Get Started with NodeForge

NodeForge compiles a Python-like DSL script into a native Blender Geometry Nodes group. The script defines the group's interface and internal data flow. This page takes you from installing the add-on to compiling and updating your first generated group; see Core Concepts for the complete language model.

Install NodeForge

NodeForge requires Blender 5.2 or newer. Install it through its Blender Extensions repository to receive updates in Blender:

  1. Open Edit → Preferences → Get Extensions.
  2. Under Repositories, choose Add Remote Repository and enter https://denikryt.github.io/NodeForge/index.json.
  3. Find NodeForge, click Install, and enable it.

To install from a file instead, download the latest Extension ZIP from GitHub Releases. In Get Extensions, choose Install from Disk..., select the ZIP, and enable NodeForge. This method also works offline after downloading the ZIP.

When switching from the earlier ZIP add-on, disable the old NodeForge add-on before enabling the Extension. Your Local files and installed NodeForge packages remain in Blender's user-data directories.

The installed add-on adds a NodeForge tab to the sidebar of the Geometry Node Editor.

Update NodeForge

If you installed from the remote repository, open Get Extensions, use Refresh Remote to check for updates, then update NodeForge when a newer version is available. You can also enable Check for Updates on Startup for the repository.

If you installed from a ZIP, download a newer Extension ZIP from GitHub Releases and install it from disk again. ZIP installations do not receive repository updates.

NodeForge comes with the Math and L-System libraries. Enabling the Extension installs or updates them, but keeps a separately installed newer version.

Create your first NodeForge group

  1. Select a mesh object.
  2. Open the Geometry Node Editor and click New to create a Geometry Nodes modifier and node tree.
  3. Press N to open the sidebar, then select the NodeForge tab.
  4. Open a Text Editor in another Blender area and click New to create a Text datablock.
  5. Enter this script:
geo = cube(size=2.0)
output("Geometry", geo)
  1. In the NodeForge sidebar, select the new Text datablock in Text Script.
  2. Click Compile Script. NodeForge compiles the text and adds the generated group node to the current Geometry Nodes tree.
  3. Connect the generated node Geometry output to the Group Output node Geometry input.

The object now displays the cube produced by the script.

Text Editor completion (prototype)

NodeForge has built-in text completion for scripts in Blender's Text Editor. This prototype suggests Core DSL functions, Local and package imports, members of imported namespaces, and functions declared in the current script. It also shows function parameters and return types when available. Enable it with NodeForge in the Text Editor header.

Update the generated group

  1. Edit the source in the Text Editor. For example, change size=2.0 to size=3.0.
  2. Select the generated NodeForge group node in the Geometry Node Editor.
  3. Click Update Selected NodeGroup in the NodeForge sidebar.

NodeForge recompiles the selected text into the same node group. The group name, compatible input values, and compatible links are preserved.

The rebuilt group also stores the edited source. Use Load Script From Selected NodeGroup to recover that source into a Text datablock and continue editing it later.

Main actions

Button What it does
Compile Script Compiles the selected Text datablock into a new Geometry Nodes group and inserts it into the active Geometry Nodes editor. For a Mesh Compute script, creates a modifier on the selected Mesh instead.
Update Selected NodeGroup Recompiles the selected Text datablock into the selected generated group. Compatible input values and links are preserved.
Load Script From Selected NodeGroup Copies the source embedded in the selected generated group into the selected Text datablock.
Reload from Source Rebuilds a selected Local or package-backed group from its current catalog source.

The generated result is native Blender data; see Generated groups remain native Blender data for its lifecycle.

First script: one input, one output

Start with the smallest useful node group: one float input and one float output.

value = input_float('Value', default=1.0)
output('Value', value)

What this means:

Line Meaning
input_float('Value', default=1.0) Creates a float input socket named Value with default value 1.0.
value = ... Stores that socket value in the script variable value.
output('Value', value) Creates an output socket named Value and connects the value to it.

After compiling, the generated node group has one input socket and one output socket. This is not visually exciting, but it shows the core model: inputs create node-group inputs, outputs create node-group outputs.

First geometry script: adjustable cube

Now create geometry. This script makes a cube whose size is controlled by a group input.

size = input_float('Size', default=2.0)
geo = cube(size=size)
output('Geometry', geo)

The generated group has:

Socket Direction Type
Size Input Float
Geometry Output Geometry

The important difference from normal Python is that geo is not a mesh object in Python memory. It is a Geometry Nodes value being built by the compiler.

Use the object's input geometry

A compiled NodeForge group can process geometry supplied by the surrounding Geometry Nodes tree. Declare a Geometry input in the script, then connect the surrounding tree's geometry to that socket on the generated group node. The generated NodeForge group is a nested node group; it is not itself the modifier's root node tree.

geo = input_geometry('Geometry')
scale = vector(1, 1, 2)
result = transform(geo, scale=scale)
output('Geometry', result)

After compiling, connect the object's geometry to the generated group's Geometry input if it is not connected automatically. In a Geometry Nodes modifier, this is the socket that carries the mesh or curve from the object in the scene.

Use this when you want to modify an existing object instead of generating all geometry from scratch with functions like cube(...).

Add variables and transforms

Use variables to keep scripts readable. The following script creates a cube and scales it in Z.

size = input_float('Size', default=1.0)
height = input_float('Height', default=3.0)

base = cube(size=size)
scale = vector(1, 1, height)
geo = transform(base, scale=scale)

output('Geometry', geo)

This pattern is usually clearer than nesting calls directly inside other calls. Write each meaningful value once, name it, and pass the name to the next operation.

Build a small shape with a loop

Lists and compile-time for loops are useful for generating repeated geometry. This example creates a row of five cubes.

spacing = input_float('Spacing', default=1.25)
count = 5

parts = []
for i in range(count):
    base = cube(size=1.0)
    offset = vector(i * spacing, 0, 0)
    moved = transform(base, translation=offset)
    parts.append(moved)

geo = join(parts)
output('Geometry', geo)

What is happening:

Part Meaning
count = 5 A compile-time value. NodeForge knows it while compiling.
range(count) Unrolls the loop during compilation.
parts = [] / parts.append(...) Collects Geometry values into a compile-time list.
join(parts) Combines the generated cubes into one Geometry output.

Use range(...) when the number of loop iterations is known during compilation. Use repeat_range(...) when the iteration count must be a runtime input or when you want a Blender Repeat Zone.

Use the Library panel

The Library panel contains reusable scripts and package management tools. Install other packages through Library → Packages:

Catalog Purpose
Local NodeForge-managed .nf files and read-only external source folders.
Functions Reusable DSL functions provided by installed packages.
Examples Bundled examples and examples provided by installed packages.
Packages Install and remove NodeForge packages.

Each script catalog has Refresh and Add Node Group actions. For a script that uses Mesh Compute, Add Node Group creates a modifier on the selected Mesh instead of inserting a group node.

  1. Open a catalog section, for example Functions.
  2. Click Refresh to scan that catalog.
  3. Select an entry from the list.
  4. Click Add Node Group to insert that entry into the active Geometry Nodes editor.
  5. Select the inserted group node and click Load Script From Selected NodeGroup if you want to inspect or edit the stored source.

Save your own script to Local

Use Local when you want to keep a script as a reusable file instead of only keeping it as a node group inside the Blender file.

  1. Write or load a script in a Text datablock.
  2. Open Library → Local.
  3. Use the folder rows and arrow buttons to open the managed destination where the script should be stored.
  4. Optionally click New Folder to create a subfolder in the current managed directory.
  5. Click Save, enter the script name, and confirm. Enable Overwrite when replacing an existing file.
  6. Select the saved script and click Add Node Group to insert it into the current Geometry Nodes editor.

The Save and New Folder actions are available only in NodeForge-managed Local directories.

Add an external Local folder

Use Add Folder... to make an existing directory of .nf files available in Local without copying it.

  1. Open Library → Local and click Add Folder....
  2. Select an existing folder.
  3. Select the linked folder row and use its arrow button to browse its scripts and subfolders.
  4. Select a script and click Add Node Group, or import it from local in another script.

External folders are read-only in NodeForge. Edit their .nf files with your normal editor, then select an inserted group and click Reload from Source to rebuild it from the current file. Remove from Local removes the folder registration and leaves the external files on disk.

For managed Local content, Delete File removes a selected .nf file. Delete Folder removes a selected empty folder.

Local files can be imported directly or through their folder path. See Local imports for the supported forms.

Reuse a saved script from another script

A saved Local script can be imported and called from another NodeForge script. This is the main reuse mechanism: write a script once, save it as a .nf file, then call it from other scripts like a function.

The saved script's input_* declarations become function parameters. One output becomes the returned value; multiple outputs can be unpacked or selected with a compile-time index.

For example, save this as a Local script named cube_row:

spacing = input_float('Spacing', default=1.25)
count = 5

parts = []
for i in range(count):
    base = cube(size=1.0)
    offset = vector(i * spacing, 0, 0)
    moved = transform(base, translation=offset)
    parts.append(moved)

geo = join(parts)
output('Geometry', geo)

Then use it from another script:

from local import cube_row

spacing = input_float('Spacing', default=2.0)
geo = cube_row(spacing)
output('Geometry', geo)

Here Spacing from the saved script becomes the spacing argument of cube_row(spacing). The saved script's Geometry output becomes the returned geo value.

Existing compiled groups keep the Local dependency source snapshot used when they were built. Editing a Local file affects a group when you compile a new caller or use Reload from Source on the existing library-backed group.

For the import and call rules, see Imports and Reusable Functions. For reusable functions from the Math library, see Math Functions.

Read these in order:

  1. Core Concepts — understand how source becomes a node-group interface, nodes, links, and runtime state.
  2. DSL Syntax and Semantics — learn the supported language rules.
  3. Core DSL Built-ins Reference — learn the primitive functions available everywhere.
  4. Writing Functions — create reusable functions with the Core DSL.
  5. Package Guide — distribute source functions, examples, and extensions as a third-party library.
  6. Extension API Reference — define typed Python-backed package callables when the Core DSL is not enough.
  7. Math Methods — use the methods added by the Math library.
  8. Math Functions — use reusable DSL functions from the Math library.
  9. Math Examples — explore complete scripts included with the Math package.
  10. L-System Guide — create geometry with L-system rules; use the L-System Reference for exact contracts.

To study an installed example, add it from Library → Examples, load its source with Load Script From Selected NodeGroup, and edit the source in a Text datablock.