Geometry Nodes

The execution model is in blender-core. Build trees with scripts/gn_builder.py, a compact JSON spec that's far cheaper than raw bpy. Look up exact socket names first, because they change between versions:

scripts/gn_builder.py -- --describe GeometryNodeDistributePointsOnFaces GeometryNodeInstanceOnPoints
scripts/gn_builder.py -- --spec scatter.json --apply Ground --set Density=20 Seed=3 Mask=@paint_mask

--set Name=@attr feeds a modifier input from a named attribute. The result reports evaluated vert/face counts and node warnings. The spec format is in the script docstring; full examples are in references/recipes.md.

Core concepts (get these right or nothing works)

• Geometry flows left→right through sockets with circle shapes. Fields (diamond sockets) are functions evaluated per element on the node that consumes them, in that node's domain/context.
• Domains: Point, Edge, Face, Face Corner, Spline, Instance, Layer. Capture Attribute freezes a field at a point in the graph (before topology changes), and Evaluate on Domain converts between domains.
• Attributes: built-ins (position, normal, sharp_face, material_index, UVMap...) plus named ones via Store Named Attribute. Named attributes persist after the modifier. That's how GN data reaches shaders (Attribute node) and exporters (glTF export_attributes, which exports names starting with _).
• Instances are cheap (one mesh, many transforms). Realize Instances only when you must edit per-instance geometry or export a single mesh. Realize as late as possible.
• Inputs exposed on the group interface become modifier inputs (5.2: mod.properties.inputs.<identifier>.value). Panels group them, menu sockets give enums.