blender-geometry-nodes

blender-geometry-nodes

Typed tools for creating Geometry Nodes groups, assigning them to mesh modifiers, setting exposed modifier inputs, and inspecting procedural graph state. Use blender-shader-nodes for low-level shared node graph operations such as list_nodes, connect_nodes, and set_node_input.

Group templates

create_geometry_node_group and add_geometry_nodes_modifier take a template argument:

• pass_through (default, also selectable as default): the group gets a Geometry input socket, a Geometry output socket, and a linked Group Input -> Group Output pair, so NodeGroupInput really emits Geometry and the group can be extended and assigned as a modifier immediately.
• empty: a bare group with no sockets and no nodes. Use create_geometry_node_socket to add sockets yourself.

A template is only applied when the group is created, or when an existing group still has no nodes; an authored graph is never rewritten by a get-or-create call.

Return contract

The two tools return different context payloads. Read the fields listed for the tool you actually called; the group-creation fields are not also present on the modifier tool.

create_geometry_node_group reports the node group itself:

• group_name - name of the created or loaded node group
• template - resolved template, pass_through or empty
• created - True when this call created the group
• template_applied - True when the template was applied on this call
• node_count - node count in the group after the call
• link_count - link count in the group after the call
• interface_sockets - list of interface socket records
• input_count - number of INPUT interface sockets
• output_count - number of OUTPUT interface sockets

add_geometry_nodes_modifier reports the modifier assignment. It repeats three group facts under a group_ prefix and reports no graph detail:

• object_name - object the modifier was added to
• modifier_name - name of the Geometry Nodes modifier
• group_name - node group assigned to the modifier
• group_template - template of the created or reused group
• group_created - True when this call created the group
• group_template_applied - True when the template was applied on this call

add_geometry_nodes_modifier returns no node_count, link_count or interface_sockets. A missing value on that tool is not an empty interface: read the group with inspect_geometry_node_interface for socket identifiers and directions, or evaluate_geometry_nodes_info for modifier inputs and their values.

Interface socket workflow

Use inspect_geometry_node_interface to read socket identifiers, directions, basic defaults, the group-user count and an interface revision. The query rejects interfaces over 256 items or text fields over 1024 UTF-8 bytes; it does not return a partial revision. Node groups saved before the interface API existed report interface_api_unavailable for these tools.

Pass the exact revision to create_geometry_node_socket, update_geometry_node_socket, or remove_geometry_node_socket. Updates and removal require the returned identifier, not a potentially ambiguous label. Read back after each edit and use the new revision. Stale revisions fail before editing; never drop the guard or retry with guessed identifiers.

Creation supports Geometry, Float, Int, Bool, Vector, Color, and String socket types in either direction. Updates preserve identity and can change the name, description, or a supported basic default. Numeric defaults are finite within +/-1000000; vectors have three components and colors have four. Names are limited to 63 UTF-8 bytes; descriptions and string defaults to 1024 bytes. Use set_geometry_node_modifier_input for an individual modifier's input value; changing a group interface default is not a per-object override.

Interface edits affect all users of the group. Linked/library-override groups are refused by these mutating tools. Removing a socket can disconnect links and discard per-instance inputs. After a native edit starts, a failure reports possible mutation and no rollback; inspect before retrying.

The process-local revision covers the queried interface layout, labels, directions, types, descriptions and supported basic defaults, not evaluated geometry, links or per-modifier values. Panel CRUD, socket-type replacement, object/material/collection references, menus, field-domain controls and zones remain outside this first interface slice. The graph-info tool does not prove that evaluated geometry matches the intended result.

The implementation uses Blender's NodeTreeInterface API.