Skill for building Blender node trees with Geometry Script.

GitHub stars
389

Install

/plugin install geometry-script@geometry-script

Run it inside Claude Code after adding the marketplace with /plugin marketplace add carson-katri/geometry-script.

Contents

Discovered from source

Skills 1

Geometry Script

Geometry Script turns a decorated Python function into a Geometry Nodes group. Every Blender node is a generated, typed function. The add-on checks your input names, output names, enum values and link types, and its errors say what to change. Guess, run and fix from the error. That is cheaper than reading up front.

The repo root is two directories above this file. tools/ and api/ paths below are relative to it.

The loop

  1. Write the script to a .py file, not an inline string, so later edits are small diffs.
  2. Run it and read the short report. Always go through agent.run: raw exec of the same script returns a traceback about 10x longer.
    • Blender MCP, running Blender: execute_blender_code with from geometry_script import agent; agent.run("/abs/path/script.py", object="Name"). The report comes back as stdout.
    • Blender MCP, no window: execute_blender_code_for_cli with a blend_file and from geometry_script import agent; result = agent.run("/abs/path/script.py", object="Name", echo=False). This tool returns only result, not printed output.
    • No MCP: python3 tools/run.py script.py --object Name (add --blend file.blend to start from a file).
  3. Fix the single error it prints, then run again.
  4. Check the result with the report's geometry stats (vertex/face/point/instance counts, bounds) and node warnings. Take a viewport screenshot only when what it looks like matters.

Live edit: if the user has the script open in Blender's Text Editor with Live Edit and the add-on's auto-resolve on, saving the file reruns it. Then just edit the file and call agent.status(), which prints the latest run's report.

agent.run prints a few lines and returns them as {"ok": bool, "report": str}: each tree built (nodes, inputs, outputs), then the evaluated geometry and node warnings for every object using those trees. object= attaches the last tree built, or tree= if given, to that object, creating the object if needed. Errors print as ERROR Type: message plus the failing line of your script. Pass traceback=True only when that isn't enough.

Saving context

NeedCheap wayAvoid
Find a nodepython3 tools/describe.py --search "points on faces" or agent.search(...)grepping api/nodes.py (9k+ lines)
A node's socketspython3 tools/describe.py set_position mesh_to_points or agent.describe(...)reading the generated function source
Shader / compositor nodestools/describe.py --tree shader ..., agent.describe(..., tree="compositor")grepping api/shader_nodes.py / api/compositor_nodes.py
Check a buildagent.run(...) / tools/run.py report, or agent.status() after a live-edit saveraw exec with full tracebacks; screenshots
Understand an existing treeagent.describe_tree("Name") (node group, material or world): prints it as Geometry Script calls, without default valuesdumping node_tree.nodes / links
Know the APIthis filethe book in book/ (longer)
See the resultreport stats first; then MCP get_screenshot_of_area_as_image(area_ui_type="VIEW_3D", size_limit_in_bytes=200000)get_screenshot_of_window_as_image (the whole window)
A bpy (not node) questionMCP search_api_docs / get_python_api_docsguessing, or long dir() dumps

Describe only the nodes you're unsure of, and several in one call. Most names are the node's UI name in snake_case, and the error will tell you if you're wrong.

Writing trees

from geometry_script import *

@tree("Scatter Cubes")                       # group name; rebuilt in place if it exists
def scatter_cubes(geometry: Geometry, count: int = 4, size: float = 0.3):
    mesh = grid(size_x=4.0, size_y=4.0, vertices_x=count, vertices_y=count).mesh
    points = mesh_to_points(mesh=mesh).points
    cube_mesh = cube(size=(size, size, size)).mesh     # socket tuples -> Combine XYZ
    lifted = set_position(geometry=points, offset=(0.0, 0.0, size * 2)).geometry
    return instance_on_points(points=lifted, instance=cube_mesh).instances
  • Inputs: parameter annotations and defaults become group inputs: Geometry, float, int, bool, str, Vector, Color, Rotation, Matrix, Menu, Object, Material, Collection, Image, plus Field[T], Grid[T], Vector2. Return one value, a tuple, or a dict {"Output Name": value} for named outputs.
  • Node functions take keyword arguments only and return a namedtuple of outputs: mesh_to_points(mesh=m).points. Enum settings are strings: mode="FACES". Type settings (data_type, input_type) are inferred from what you link, so set them only to override.
  • Arithmetic (+ - * / % **, unary -) on float, int and vector sockets adds Math / Vector Math nodes. Comparisons (< <= > >= == !=) add a Compare node and give a boolean socket: z > 0.5, index().index % 2 == 0. Combine them with boolean_math, not and/or/not or 0 < x < 1. Fields such as position().position and index().index are plain sockets.
  • Calling a @tree function inside another @tree adds a group node. Those take positional arguments: repeat_grid(geometry).
  • Builds are all-or-nothing: if a build raises, the previous tree (and its modifier input values) is left untouched. Modifiers keep their input values across rebuilds.
  • Names that would shadow Python builtins get a trailing underscore: math_ (math(...) also works, and math.pi is still the math module), id_, object_, string_.

Zones

@repeat_zone
def climb(geometry: Geometry, step: float, iteration: int):   # `iteration` is the index
    return set_position(geometry=geometry, offset=(0.0, 0.0, step)).geometry, step * 2.0

@simulation_zone
def fall(geometry: Geometry, delta_time: float):
    return set_position(geometry=geometry, offset=(0.0, 0.0, -1.0)).geometry

@for_each_element(domain="POINT")
def per_point(index: int, radius: float):
    return ForEachResult(main={"scale": radius * 2.0},
                         generated=[{"geometry": uv_sphere(radius=radius).mesh}])

@closure_zone
def scale(x: float, factor: float = 2.0):
    return x * factor

@tree("Zones")
def zones(geometry: Geometry):
    climbed = climb(geometry, 1.0, iterations=4).geometry
    out = per_point(mesh_to_points(mesh=climbed).points, radius=0.25)
    value = scale.evaluate(scale(), 1.0, 3.0)
    return {"Geometry": fall(out.generated.geometry), "Value": value}

Shaders, materials, worlds and the compositor

Each tree type has its own module of node functions; names like normal, mix or object_info mean different nodes in each. A node used in the wrong tree raises an error naming the module it belongs to.

from geometry_script import *            # geometry nodes, @tree / @geometry
from geometry_script import shader as sh # @sh.shader, @sh.material, @sh.world
from geometry_script import compositor as comp

@sh.shader("Stripes")                    # shader node group: works like @tree
def stripes(color: Color = (0.9, 0.3, 0.1, 1.0), scale: float = 6.0):
    wave = sh.wave_texture(scale=scale)
    return sh.mix(data_type="RGBA", factor=wave.factor, a=color, b=(0, 0, 0, 1)).result

@sh.material("Striped")                  # no parameters; return the surface shader,
def striped():                           # or {"surface": ..., "displacement": ...}
    return sh.principled_bsdf(base_color=stripes(scale=10.0)).bsdf

@sh.world("Studio", scene=True)          # scene=True makes it the scene's world
def studio():
    return sh.background(color=(0.05, 0.06, 0.08, 1.0)).background

@comp.compositor("Glow", scene=True)     # scene=True makes it the scene's compositor
def glow(strength: float = 0.3):
    image = comp.render_layers().image
    blurred = comp.blur(image=image, size=(20, 20)).image
    return comp.mix(data_type="RGBA", blend_type="SCREEN", factor=strength, a=image, b=blurred).result

@tree("Striped Cube")                    # calling a @material returns the Material
def striped_cube():
    return set_material(geometry=cube().mesh, material=striped()).geometry

@repeat_zone and @closure_zone also work in shader trees. agent.run reports shader groups, materials and worlds, but object= only attaches geometry trees.

Item nodes

Capture Attribute, Index/Menu Switch, Bundles and Format String take their items as keyword arguments, items=[...] or items={...}, and expose them by name: capture_attribute(geometry=g, height=position().position).height.

Errors and what they mean

ErrorFix
unexpected keyword argument 'offest'. Did you mean 'offset'?Rename it.
...Outputs has no output 'geometry'; available: ['points']Use a listed name.
has no 'vector' output with its current settings {'operation': 'DOT_PRODUCT'}; available: ['value']That mode outputs something else; use a listed output or change the setting.
Cannot set ...mode to 'VERTEX'. Expected one of [...]. Did you mean 'VERTICES'?Use a listed value.
has no 'x' input with its current settings {...}That input only exists in another mode or type.
Invalid links ... cannot take ... Set the node's type, one of: ...Wrong socket type, or set data_type=/input_type=.
takes 0 positional argumentsNode functions are keyword-only.
NameError: name 'foo' is not definedWrong node name: run tools/describe.py --search foo.

Watch out: Blender silently converts some types (float → vector, bool → float), so a link of the wrong kind can still build. Check the result stats.

Blender 5.x scene snippets

  • Attach by hand: mod = obj.modifiers.new("GS", "NODES"); mod.node_group = bpy.data.node_groups["Name"] (agent.run(..., object=...) does this for you).
  • Modifier input values: getattr(mod.properties.inputs, socket.identifier).value = 5.0, where socket = mod.node_group.interface.items_tree["Height"]. The old mod["Socket_1"] form no longer works in Blender 5.

Sponsors

Details

Marketplace
carson-katri/geometry-script
Source
.
Category
Community