NodeGenius — Documentation

v1.1.0 · Blender 4.2 LTS and later · Windows / macOS / Linux

---

1. Install

1. Keep the downloaded archive zipped.
2. Edit → Preferences → Add-ons, press the arrow button in the top right corner and choose Install from Disk...
3. Pick the archive and tick NodeGenius in the list.
4. Press N in the 3D Viewport: a tab named NodeGenius appears in the sidebar.

Updating from 1.0.0: install 1.1.0 the same way, then restart Blender. On first start 1.1.0 deletes what 1.0.0 left behind: the key for the online service that 1.0.0 kept in the add-on preferences, and three program files of 1.0.0 in the add-on's own folder. If Auto-Save Preferences is off, press Save Preferences once so the preferences file is rewritten without the key. If the add-on folder is read-only, the three files cannot be deleted: 1.1.0 names them in its preferences and in the system console so you can delete them by hand (1.1.0 never uses them).

Going back to 1.0.0: install the 1.0.0 archive the same way and restart Blender before you use it. Until the restart, some 1.1.0 commands stay registered next to the 1.0.0 ones.

To remove it: untick NodeGenius in the Add-ons list, expand its entry and press Uninstall. Modifiers and node groups you created stay in your files.

2. Quick start

1. Select a mesh object.
2. Open the Node Library panel of the NodeGenius tab.
3. Press Apply under Scatter on Surface. A new Geometry Nodes modifier is added and small cubes appear on the surface.
4. In the Geometry Nodes editor, replace the cube labelled Instance Source (replace me) with your own asset through an Object Info node.

3. Node Library

Ten presets. Each one is added as a new Geometry Nodes modifier on the active mesh; your existing modifiers are not touched, and one Undo removes it. Filter by Category or type words into the search field.

• Scatter on Surface — instances over the faces of the mesh.
• Slope-Based Scatter — only on faces that point upwards (normal Z above 0.7).
• Random Scale & Rotation — scatter with a random size between 0.5 and 1.5 and a random turn around Z.
• Proximity-Based Density — dense near a target object, thinning out to nothing at about a third of your object's size from it. Pick the target in the node labelled Target (pick an object); until you do, the scatter is even.
• Voronoi Scatter — scatter in organic clumps: points are scattered evenly, then only those near Voronoi cell centres are kept. Works on a single-face plane as well as on a dense mesh.
• Noise Displacement — pushes every vertex along its normal by a noise texture. It moves existing vertices, so subdivide a flat plane first.
• Array Grid — repeats the mesh on a 5 x 5 grid as real geometry, spaced one and a half times the object's width.
• Boolean Cutter — cuts the mesh with a second object. Pick the cutter in the node labelled Cutter (pick an object); until you do, nothing is cut.
• Height Gradient Color — stores a colour attribute named Col, blue at the bottom of the object to orange at its top. Read it with an Attribute node in a material to see it.
• Edge Wireframe — turns every edge into a thin tube on top of the mesh.

Presets are sized to the object they are added to: scatter density (about 150 instances whatever the size), the placeholder cube, texture scale, tube radius and displacement strength are set from the object's own surface area and bounding box at the moment you press Apply, measured after the modifiers already on the object (a Mirror or an Array counts). A 10 cm prop and a 50 m terrain both get a result you can see; adjust the values in the nodes afterwards.

The scatter presets keep the original mesh and add instances to it. If a preset cannot be built completely on your Blender version, nothing is added and the status bar says why.

4. Explain Tree and Explain Node

Open the Explain & Check panel. Explain Tree reads the Geometry Nodes modifier that is active on the object (the highlighted one in the modifier stack) and writes, in the order the data flows, what each node does, which values are set on it and what feeds it. Nodes that never reach the Group Output are listed separately as having no effect on the result.

Explain Node does the same for the node you last clicked in the Geometry Nodes editor.

The explainer has built-in notes for about ninety common nodes. Any other node is still listed with its name, values and inputs, and marked as having no built-in note. Nothing is sent anywhere.

5. Check Tree

Check Tree looks for nodes with no connected outputs, a Realize Instances node followed by instance operations (they do nothing after realizing), subdivision levels above 4, and very large trees. The first 30 issues are listed and the rest are counted by kind. It only reports; the tree is not changed.

6. Optional: local AI

This module is off by default. With it off, its buttons and its panel do not exist and nothing in the add-on can make a network request.

1. Run a language model server on your own computer: Ollama or LM Studio.
2. In Edit → Preferences → Add-ons → NodeGenius tick Enable local AI (optional).
3. Set Local URL (Ollama: http://localhost:11434/v1, the default; LM Studio: http://localhost:1234/v1) and Model (a model you have loaded).
4. A Local AI (optional) panel appears in the NodeGenius tab. Press Check Local Server to see that the server answers.
5. Type a description and press Generate.

This computer only. The Local URL must be localhost, 127.0.0.1 (any 127.x.x.x) or ::1. Any other address is refused with an error before anything is sent. The name is checked again after it is resolved and the connection goes to the verified local address itself. Proxy settings are ignored and redirects are never followed. No account and no key is needed or accepted.

What each button sends to the local server, as text:

• Generate — the prompt you typed.
• Generate from Selection — the prompt, plus for each selected object its name, type, vertex count and face count.
• Explain with Local AI and Suggestions from Local AI — the active node tree as text: node names, types and labels, input values (including the names of objects, collections, materials and images picked in the nodes) and links. A very large tree is cut after its first 200 nodes.
• Check Local Server — asks which models are loaded; sends no scene data.

No files, meshes, image contents or material settings are sent. Before a request, until you tick Don't ask again, a dialog lists this and the address; nothing is sent until you press Send. Repeat Last asks again as well. A Python script that calls the operator directly is taken as the request itself and sends without the dialog. Don't ask again covers that address and that kind of data only: agreeing to send prompts does not cover sending the node tree. Ask Again Before Sending in the preferences resets it.

While the model is thinking, the request runs in a worker thread, so Blender stays usable. Press Esc to stop waiting; nothing is changed. Reading the answer and building the tree take well under a second; computing the tree takes a few seconds at most (see below), plus one to three seconds to start a second copy of Blender when the tree is timed there.

What Generate does with the answer. An answer longer than about a million characters, or nested deeper than 64 levels, is refused before it is read. The tree is built on a new modifier that stays switched off until it has been checked. Nodes and links that do not exist in your Blender are skipped and counted in the report. Then:

• only nodes whose size can be told in advance are built: an answer that uses volumes, file import, repeat or simulation zones, grids, UV Unwrap or Pack UV Islands (they can take minutes on a dense mesh), or text nodes that can grow a text without end is refused, and the refusal names those nodes;
• numbers that multiply geometry — subdivision levels, grid resolutions, counts, curve resolutions, scatter densities — are kept to a safe limit whether the answer types them into the node or computes them with other nodes: a typed value is lowered, a computed one passes a Minimum node set to the limit. Both are listed in the report;
• every scatter makes about 5,000 points at most, whatever happened to the surface before it: its density is divided by the area of the faces it receives, measured in the tree itself;
• NodeGenius works out from the node settings how much geometry the tree can add to your object and, from measured costs per node, roughly how long Blender will take to compute it (Subdivision Surface is counted from what it receives: in Blender 4.3 and later its cost follows the triangles, the UV seams, the vertices with many edges and the n-gons with many corners, not the vertex count; a single n-gon with 256 corners takes seconds). Above two million vertices or points, or when the size cannot be worked out, the tree is refused and nothing is added. The time is measured on your computer: unless the estimate shows the tree is clearly light (under 4 seconds even on a computer six times slower than the one it was measured on), NodeGenius computes it once in a second copy of Blender running in the background (no add-ons, no startup file) and stops it after 3 seconds; the tree is added only if that test run finished in time. The aim is to keep out trees that take more than about 4 seconds in your Blender, but the test run is one measurement in another copy of Blender: in our tests the same tree took from about 0.6 to about 1.5 times as long in Blender itself as in the test run, and Blender's own time for one tree varied by up to about a third from run to run. So now and then a tree that would take 2.5 to 4 seconds in your Blender is refused, and one that takes a little over 4 seconds may be added; a tree that takes much longer does not get through the test run. Only a tree estimated at more than about 40 seconds is refused without that test run. Blender does not respond while the test runs. If no second copy of Blender can be started at all, a tree that the estimate puts under 4 seconds is added with a warning that it was not timed (the estimate was measured on a fast computer, so the tree may take longer on yours), and any other tree is refused. Numbers in the answer are kept within ±1,000,000, and a computed move or scale passes the same limit.

If the answer cannot be built into a tree that reaches the Group Output, nothing is added.

7. Troubleshooting

"Could not reach the local AI server" — the server is not running, or the Local URL or port is wrong. Start Ollama or LM Studio and press Check Local Server.

"... is not on this computer" — the Local URL names another machine. NodeGenius only talks to localhost.

"The model's answer was not a node tree definition" — the model answered with prose. Try again or use a larger model.

"The model's node tree could not be built" — the model named nodes that do not exist, or left the Group Output unconnected. Nothing was added.

"The model's node tree would take at least about ... seconds to compute" — the tree uses nodes that are slow on this mesh (often Subdivision Surface on many triangles or on n-gons with many corners). Nothing was added; ask for a simpler setup.

"... a test run in a separate Blender took longer than 3 seconds and was stopped" — the tree was timed in a second copy of Blender and did not finish in time on this computer. Nothing was added.

"The model's node tree would create about ... more vertices" — the tree would have been too heavy for the object it was asked for. Nothing was added; ask for less, or start from a preset.

"It uses nodes that NodeGenius does not build from a model's answer" — the answer used a node whose size cannot be told in advance (a volume, a file import, a repeat zone and the like). Nothing was added. You can still add such nodes by hand.

"Applied preset ..., but note: ... million vertices, which needs roughly ... GB of memory" — Edge Wireframe or Array Grid on a dense object makes a very large result. The preset is added; if Blender slows down, hide the modifier in the viewport or use a lighter object.

A scatter preset shows nothing — the status bar says so: "Applied preset ..., but it placed nothing" and why — the mesh has no faces to scatter on, or the Slope-Based Scatter found no faces that point upwards.

8. Limitations

• The quality of text-to-nodes depends entirely on the local model. Small models often invent node or socket names; skipped nodes and links are reported, and an unbuildable answer adds nothing.
• Presets are added to mesh objects that are local to the file; a linked object must be made local first.
• Explain and Check read the active Geometry Nodes modifier of the active object, one tree at a time. Nested node groups are named, not opened. A long tree is listed up to its first 60 nodes; the rest are counted.
• The size estimate for a generated tree is a rough estimate made from the node settings before anything is evaluated, not a measurement. It can be too low or too high: for most nodes it errs on the high side, so a heavy but legitimate tree can be refused; for Mesh Boolean it can be too low. The time is measured by one test run in a second copy of Blender (section 6), and the two Blenders do not take exactly the same time: a tree close to the limit can be refused, and now and then one a little over it can be added.

9. Changelog

v1.1.0

• The cloud AI backends are removed. The add-on no longer asks for, stores or sends any key, and never contacts an online service.
• On first start after an update, the key that 1.0.0 saved in the add-on preferences is deleted, together with the old backend, address and model values and three program files of 1.0.0. Restart Blender after updating.
• Text-to-nodes is now an optional module, off by default, that talks only to a language model on this computer (Ollama, LM Studio on localhost). Any other address is refused before anything is sent, and a dialog shows what is sent before a request (until you tick Don't ask again for that address and that kind of data).
• A generated tree is built on a switched-off modifier and checked before it is switched on: only nodes whose size can be told in advance are built, values that multiply geometry are kept to a safe limit whether typed or computed by other nodes, every scatter is limited to about 5,000 points, nodes that can take minutes (UV Unwrap, Pack UV Islands) are not built, and a tree that could add more than two million vertices is refused. Unless the tree is clearly light, it is timed once on your computer in a second, background Blender and refused if that test run takes more than 3 seconds. Blender's own time for the same tree varies by up to about a third between runs, and the test run can be faster or slower than your Blender, so a tree that would take 2.5 to 4 seconds in your Blender is sometimes refused, and now and then one that takes a little over 4 seconds may be added. A very long or very deeply nested answer is refused before it is read.
• Explain Tree and Explain Node now work offline, from built-in notes. Long trees are explained without limits on their length (the first 60 nodes are listed, the rest counted), and a nested node group is named.
• Presets are now sized to the object they are added to (density, placeholder cube, texture scale, displacement strength), measured after the modifiers already on it.
• Fixed presets: Slope-Based Scatter and Height Gradient Color were missing a node; Proximity-Based Density and Voronoi Scatter removed the original mesh; Voronoi Scatter was empty on a plane or a cube; Noise Displacement lost a link on Blender 5.x.
• A preset is added whole or not at all. A generated tree is built from the nodes and links that exist; what was skipped is reported, and a tree that cannot reach the Group Output is not added.
• Explain and Check now read the active Geometry Nodes modifier, not the first one in the stack. Both stay fast on trees of thousands of nodes; Check lists the first 30 issues and counts the rest.
• A scatter preset that places nothing on the object says so and why, instead of "Applied preset".
• Esc cancels a pending request. The Refresh button, which did nothing, is gone.
• Minimum Blender is 4.2 LTS.

10. Support & License

Through marketplace messaging. GPL-3.0-or-later; the full licence text ships inside the add-on.