TreeBuilder

TreeBuilder(
    tree='Geometry Nodes',
    *,
    tree_type='GeometryNodeTree',
    collapse=False,
    arrange='sugiyama',
    fake_user=False,
    ignore_visibility=False,
    split_inputs=False,
)

Builder for creating Blender node trees with a clean Python API.

Supports geometry, shader, and compositor node trees.

Attributes

Name Description
collapse
fake_user
group_input_splits The extra Group Input instances beyond the primary one, each as
ignore_visibility
inputs
layout_snapshot A structural layout snapshot: for every node its type, (x, y)
node_positions A {node name: (x, y)} snapshot of every node’s location.
nodes
outputs
tree

Methods

Name Description
activate_tree Make this tree the active tree for all new node creation.
add
arrange
compositor Create a compositor node tree.
deactivate_tree Whatever tree was previously active is set to be the active one (or None if no previously active tree).
disable_arrange Disable the auto-layout that otherwise runs when this tree’s context
geometry Create a geometry node tree.
link
panel A panel that can group input and output sockets together
shader Create a shader node tree.
split_group_inputs Split the Group Input node into one instance per consumer node,
to_mermaid Generate a Mermaid diagram that represents this tree.
to_python Generate Python source that recreates this tree using nodebpy.

activate_tree

activate_tree()

Make this tree the active tree for all new node creation.

add

add(name)

arrange

arrange()

compositor

compositor(
    name='Compositor Nodes',
    *,
    collapse=False,
    arrange='sugiyama',
    fake_user=False,
    split_inputs=False,
)

Create a compositor node tree.

deactivate_tree

deactivate_tree()

Whatever tree was previously active is set to be the active one (or None if no previously active tree).

disable_arrange

disable_arrange()

Disable the auto-layout that otherwise runs when this tree’s context exits, so explicitly assigned node locations are preserved.

geometry

geometry(
    name='Geometry Nodes',
    *,
    collapse=False,
    arrange='sugiyama',
    fake_user=False,
    split_inputs=False,
)

Create a geometry node tree.

panel

panel(name, *, description='', default_closed=False, reuse=True)

A panel that can group input and output sockets together (tree.inputs.panel / tree.outputs.panel group one direction). Reuses an existing same-named panel under the same parent, so a mixed panel can be declared in separate input and output passes; pass reuse=False to always create a fresh panel — Blender allows several same-named sibling panels, and rebuilding such an interface must not fold them into one. Passing an existing panel (or a previous tree.panel(...) context) instead of a name reopens exactly that panel — the unambiguous spelling generated code uses for the second direction pass over a same-named sibling.

shader

shader(
    name='Shader Nodes',
    *,
    collapse=False,
    arrange='sugiyama',
    fake_user=False,
    split_inputs=False,
)

Create a shader node tree.

split_group_inputs

split_group_inputs()

Split the Group Input node into one instance per consumer node, with unused sockets hidden — regenerating the editor style that avoids a single input node trailing long noodles. Runs automatically on context exit (before auto-layout, so the instances are arranged next to their consumers) when the builder was created with split_inputs=True.

to_mermaid

to_mermaid(fenced=True)

Generate a Mermaid diagram that represents this tree.

This can be used for documentation or visualization purposes. The Mermaid syntax is supported by many tools, including GitHub and Jupyter notebooks.

Arguments

fenced:
    Whether to wrap the output in a fenced code block with mermaid syntax highlighting.

Returns

Name Type Description
A string containing the Mermaid diagram syntax representing this node tree.

to_python

to_python(
    min_chain_length=3,
    strict=True,
    max_inline_width=88,
    snapshot_positions=False,
    keep_reroutes=False,
    top_level='with',
    format=True,
    nodebpy_pkg='nodebpy',
)

Generate Python source that recreates this tree using nodebpy.

See :func:nodebpy.codegen.to_python for parameter details.