Cycles and self links are refused before Blender is asked; the snapshot's instance scan stops at 100k depsgraph items and says instancesComplete=false (2000x2000 instanced grid: 22 s -> 1.4 s); the daemon advertisement lists the scene-action and node-graph capabilities. Live: 156 checks pass on Blender 5.2.3. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
4.5 KiB
Geometry node graph actions
Command intents (brokkr.blender.command_intent.v0) that build and drive a Geometry Nodes graph.
Owner: brokkr_bridge/node_actions.py; the target only dispatches. Every field is validated before
bpy is touched; a refused intent is a failed receipt naming the rule and leaves the tree as it was.
Design and the parts not built yet: docs/blender-node-graphs.md (on libby/blender-node-graphs-design).
| action | fields | rule |
|---|---|---|
createNodeGroup |
treeKey, interface [{inOut, name, type, default?}] |
New geometry node group with gin and gout nodes. Types: Geometry, Float, Int, Bool, Vector. Refuses an existing group. The receipt lists the interface identifiers (Socket_N). |
addNode |
treeKey, id, blIdname, location?, label?, properties?, inputs? |
id is Brokkr's key (stored as the node's brokkr_id). Type must be a GeometryNode*, FunctionNode* or ShaderNode* name that is not an importer, exporter, script, bake, group, zone, viewer or image-texture node. Properties are enum/bool/int/float node settings (set first, they decide which sockets exist); inputs are unlinked defaults (float, int, bool, vector, colour). At most 500 nodes per group. |
removeNode |
treeKey, id |
Removes the node and its links. Absent id: accepted. gin and gout stay. |
linkSockets |
treeKey, fromNode, fromSocket, toNode, toSocket |
Sockets by identifier, or by display name when exactly one available socket has it (Group Input/Output sockets are addressed by interface name). A link Blender calls invalid (field into a single value, type mismatch) is removed and refused, and the single link it displaced is put back. A valid link into a single-link input replaces the old one (Blender's behaviour); a link that would close a cycle, or link a node to itself, is refused before Blender is asked. |
unlinkSockets |
treeKey, toNode, toSocket, fromNode?, fromSocket? |
Removes the links into an input, or only the one from the given source. None to remove: accepted. |
addModifier |
objectName, treeKey, modifierName? (default Brokkr GeoNodes) |
NODES only. Reuses a modifier of that name; at most 8 per object. |
removeModifier |
objectName, modifierName? |
Geometry Nodes modifiers only (a Subdivision or other modifier is refused). Absent: accepted. |
setModifierInput |
objectName, modifierName?, socket (identifier or unique interface name), value |
Float, Int, Bool, Vector inputs. Written as getattr(modifier.properties.inputs, id).value = v (indexing inputs[id] yields a raw ID property group without .value on 5.2.3), then object.update_tag(). |
setObjectCustomProperty refuses a property whose name is the identifier (Socket_N) of an input of a Geometry
Nodes modifier on that object; a custom property never drives a modifier input. A name that only equals an
input's display name is an ordinary custom property.
The host snapshot's object entries carry evaluated for mesh objects with modifiers: vertex, edge and
polygon counts, instanceCount, and up to 256 vertex and instance locations (truncated when cut). Vertex
positions and vertexBounds* are in the object's local space; instance locations and instanceBounds* are
world space. Above 1,000,000 vertices only counts are read (positionsSkipped); a non-finite coordinate sets
nonFinite and drops the positions and bounds. The instances come from one depsgraph scan per capture.
instancesComplete is false when the depsgraph scan stopped at 100,000 items (instanceCount and the instance bounds are then lower bounds); the scan is what costs time (about 5 microseconds per instance in Python), so a 2000 x 2000 grid instanced on points captures in 1.4 s on the test machine where an unbounded scan took 22 s. instanceCount counts evaluated instances whose parent is the object, so a curve, point or volume result
also reads as one instance. mesh stays the base mesh.
Not built: zones, item sockets, multi-input ordering, library groups, group-in-group nodes, batches/rollback across
intents, an expectedRevision check, per-node cost estimates. Int values are capped at +-4096 and floats at +-1e9,
which bounds a request but not the cost of a graph: Blender evaluates what it is given, and the snapshot evaluates
every mesh with modifiers on each capture (mesh grids measured: 16.7M vertices evaluate and read in 0.4 s).
addModifier refuses object types that take no modifiers.
Live proof: tests/live/gn_actions.py (Blender 5.2.3, headless). Unit tests: tests/test_node_actions.py.