Changelog

520.31.0 - 2026-09-29

Enhancements

  • Generic custom groups — a CustomGeometryGroup (or shader/compositor group) can now build a different inner tree per instance, e.g. one per data type. Override _group_name() to name each variant’s tree from state set before super().__init__(); each variant is built once and reused. Combined with a generic class (class MyGroup[T](CustomGeometryGroup)) and typed factories returning MyGroup[FloatSocket], node.i.value narrows like the built-in GetBundleItem.float().

Breaking Changes

  • Building a group node now goes through the instance method _create_group() instead of the create_group() classmethod. Calling create_group() works as before, but subclasses that overrode it to customise how the tree is made should override _create_group() instead.

Fixes

  • >> into a group node whose matching input is inactive at its current values (a group input only used behind an internal switch, such as a fade at 0) now links to it, like the UI allows, instead of raising SocketError. Active inputs are still preferred, so >> into a Switch keeps linking to the branch in use.

520.30.2 - 2026-09-29

Fixes

  • When several factory methods fit a node, to_python now prefers one setting the data type (data_type, socket_type, input_type), so g.GetBundleItem.float(..., structure_type="SINGLE") is no longer emitted as g.GetBundleItem.single(...).

520.30.1 - 2026-09-29

Fixes

  • Codegen for g.DeleteGeometry.edge(selection=g.EdgeLength() > 0.5) was emitting as g.DeleteGeometry.all(selection=g.EdgeLength() > 0.5, domain="EDGE"). Tweaked that when there is a tie between property classmethod usage, the option which includes less arguments wins. Potential in the future to have only classmethods for single properties on each node though, but that’s a broader design questions.

520.30.0 - 2026-09-28

Enhancements

  • Default spells an input’s fallback — Blender lets an input read an implicit field or a context value when nothing is connected (a group interface’s Default Input, or a built-in such as Set Position’s Position), hiding the stored value. nodebpy.Default mirrors the default-input identifiers (Default.POSITION, Default.ID_OR_INDEX, Default.SELF_OBJECT, …). Generated asset classes use them as parameter defaults (id: InputInteger = Default.ID_OR_INDEX) and say in the docstring what the input reads when unconnected; inputs with a Default Attribute keep their stored value and the docstring notes the attribute a modifier input reads. Passing a member to any node constructor leaves the socket untouched, like None, and to_python treats such a default as “nothing to export”. The tree.inputs.* factories accept the members for default_input= alongside the identifier strings. Built-in node inputs whose value Blender hides (hide_value: Set Position’s Position, every Selection, …) now default to None instead of advertising a value Blender never shows.
  • Factory methods take node properties — generated factory methods accept the node’s other properties as keyword-only arguments (g.NoiseTexture.fbm(normalize=True, noise_dimensions="4D"), g.Math.add(a, b, use_clamp=True)). Properties Blender only shows for some variants are only offered on those variants, and to_python passes non-default properties through the factory (g.Math.multiply(use_clamp=True)).
  • Rebuild materials in place — s.material(name, clear=True) rebuilds an existing material and keeps the datablock. TreeBuilder(..., clear=True) now also keeps Geometry Nodes modifier input values, matched by socket name.
  • Typed package — nodebpy ships py.typed, and the wheel is checked with mypy (strict), pyright, basedpyright, pyrefly and ty.
  • A float or integer socket combined with a 3-tuple now uses Vector Math (Scale for multiply) instead of raising.
  • g.tree / s.tree / c.tree are now TreeBuilder.geometry / .shader / .compositor themselves, so they take every option those do (split_inputs, fake_user, …).
  • ColorRamp accepts flat (position, r, g, b, a) items, so an (N, 5) numpy array works like FloatCurve’s (N, 2).

Breaking Changes

  • Shader Mix variants take (factor, a, b), so positional s.Mix.color(f, x) now sets A instead of B. The geometry Mix is now generated.
  • Factory and parameter renames: input_4x4_matrix factories are now matrix, GaborTexture.type_2d / type_3d, and variant parameters drop type suffixes and _001 counters (MapRange.vector(from_min, …), TrimCurve.length(start, end)). The leaked face_corner / input_4x4_matrix factories on field nodes are removed.
  • ColorRamp’s color_interpolation defaults to LINEAR to match Blender, and items defaults to Blender’s black-to-white stops; empty items raises ValueError.
  • FloatCurve’s items defaults to Blender’s ((0.0, 0.0), (1.0, 1.0)); fewer than two items raises ValueError.
  • g.tree()’s default name is now "Geometry Nodes" (was "Geometry Node Group"), matching Blender.
  • New materials start empty instead of with a Principled BSDF and Material Output.
  • The broken nodebpy console script is removed.

Fixes

  • Deterministic arrangement — the Sugiyama arranger iterated sets ordered by memory address (layout nodes hashed by id(), bpy sockets by pointer), so the same tree could get different node locations, link order and multi-input sort ids from one run to the next. Arrangement is now reproducible, and an asset library built twice from the same sources differs only in the fields Blender itself randomises per session.
  • Color Ramp stops — ColorRamp(items=...) with more than two stops left them out of position order, and to_python dropped a ramp’s stops and interpolation settings. Both now round-trip.
  • Float Curve points — FloatCurve(items=...) left unsorted points out of x order and kept added points selected, so a later mapping update clamped only those to the clip range. Points are now sorted and deselected, and to_python exports them as items= like ColorRamp, with the mapping’s other settings and any point selection written after the constructor.
  • Generated variants keep sockets Blender marks inactive only because of current values (Mix’s A at Factor 1.0).
  • The .default_value error on an output socket now says an input socket is needed.

520.29.0 - 2026-09-20

Fixes

  • Generated defaults are Blender’s exact socket defaults — the node-class generator rounded every float default to four decimals and vector defaults came out as None, so g.Arc() built a node whose sweep angle was 5.4978 instead of Blender’s 7π/4, and to_python then exported every untouched Arc (and any node with a rounded default such as MeshToPoints(radius=0.05)) as if it had been edited. Constructor defaults now use the same float formatting as to_python (nodebpy.export._floats, shared by the generator without importing the package it generates): the shortest literal that rebuilds exactly the float32 Blender stores, or a math.pi / math.tau / math.e expression for its rational multiples (sweep_angle: InputFloat = 7 * math.pi / 4). Vector, colour and rotation sockets now show their real default tuples instead of None, and the export’s default comparison works at float32 precision, so a fresh node exports without spurious keyword arguments.
  • InputVector accepts 2- and 4-component tuples for the 2D / 4D vector sockets Blender exposes (Blank Image’s size, motion-blur velocity), and InputIntegerVector accepts tuples; Blank Image’s size is typed as an integer vector instead of an integer.

520.28.0 - 2026-09-19

Enhancements

  • Rebuild a tree in place — TreeBuilder(tree, clear=True) (also on TreeBuilder.geometry/shader/compositor and g.tree / s.tree / c.tree) empties the tree’s nodes, links and interface before the body runs and keeps the datablock, so modifiers, group nodes and pinned editors that reference it stay attached. Given a name, an existing group of that name and tree type is reused instead of creating a Name.001 duplicate; a group of another tree type is left alone. to_python(in_place=True) emits the clear=True header so an exported tree’s source rebuilds the same datablock when re-run.
  • nodebpy.live — run_source(code, filename=...) executes nodebpy source for a live editor that re-runs on every change: node groups the code’s classes claim by _name are stashed as <name>.stale so create_group() builds fresh, then their users are remapped onto the rebuilt trees and the old ones removed (or, on failure, the old names restored and the original exception re-raised); Geometry Nodes modifier input values (including attribute-driven inputs) are preserved across the interface rebuild, matched by socket name, also when the run fails; and the produced tree is returned in a RunResult. The pieces — stash_groups / GroupStash, preserve_modifier_inputs, group_names_in_source — are public for callers that need only one of them.

520.27.0 - 2026-09-16

Enhancements

  • Dump a subset of assets — python -m nodebpy.assets dump --names (and dump_library(names=...)) takes fnmatch wildcards like plot does (--names "Style *"), for quick iteration on a few assets without regenerating the whole library. A filtered dump now writes exactly what the full dump would for those assets: the whole library is still read to decide what is shared, so a helper also used by an unselected asset stays in _shared/ (previously it was embedded into the selected asset’s module) and an unselected nested asset stays imported from its own module (previously its class was duplicated into the importer). The _shared/ and materials/ modules the selection depends on are rewritten alongside; other assets’ files are left untouched, so check remains the authority on the full sources.

520.26.0 - 2026-09-14

Enhancements

  • Layouts read left to right with less dead space — three additions to the Sugiyama arrangement, all on by default and each a SugiyamaOptions field / build flag / [tool.nodebpy.assets] key:
    • sequential_frames ranks frames as stages of the flow: every node of a frame comes after every node of the frame (or intermediate node) feeding it, so successive frames — closure bodies, processing stages — line up left to right instead of sharing columns and stacking into a staircase (MolecularNodes’ Style Surface halves in height). Frames with no links between them still stack vertically as parallel branches.
    • balance_heights counters the tall sliver a node with many inputs produces: after ranking, nodes of the tallest columns are promoted, together with everything upstream of them, into emptier columns while the drawing gets closer to a screen-shaped box (balance_aspect, default 1.6 wide per unit of height). The longer links are routed through reroutes / dummy nodes, which now pack at reroute_margin_y_fac (0.35) of the vertical margin instead of a full node gap.
    • The default direction is now BALANCED (the average of the four Brandes–Köpf extremes), which is shorter than RIGHT_UP on every MolecularNodes style tree and centres the flow vertically.
  • Links into a collapsed panel’s sockets (is_hidden in Blender’s terms) now count for the layout, so a producer feeding a panel socket is placed before its consumer instead of drifting off as a disconnected node.

Fixes

  • Zones in plots are drawn as Blender draws them: a rounded convex hull around the zone’s input and output nodes and every node fed from the zone input; a node that only feeds into the zone from outside stays outside.

520.25.0 - 2026-09-14

Enhancements

  • Blender-styled node plots — nodebpy.export.to_plot now reproduces what the node editor would show instead of bare labelled rectangles: header colours per node class and title (a Math node reads “Multiply”), socket markers coloured and shaped by type (circles, field diamonds, geometry bars), value widgets for unlinked inputs (sliders, vector rows, checkboxes, text fields, colour swatches), property dropdowns, frames with their labels, simulation / repeat / for-each zones, and socket-coloured links (dashed for fields, red for muted or invalid), all on the editor’s dotted background. Colours come from Blender’s active theme. One UI unit is drawn as one point, so text and widgets keep their real proportions at any dpi.
  • Group-node renders — to_plot(tree, path, node=True) draws a node group as the single group node a user sees when adding it: its interface inputs with default values and its outputs (width= sets the node width). python -m nodebpy.assets plot now writes both images per group (<name>.png and <name>_node.png; --tree-only / --node-only keep one), and TreeBuilder gained to_plot(). axes=True frames a render with axes ticked in Blender UI units, as the old plots were, for reading off node distances.
  • Layout rows follow Blender’s declared socket order — the row model behind calculate_node_dimensions / calculate_socket_offset_y (and so the arranger and the plots) is now one function, nodebpy.builder.layout.node_rows. Blender draws some 180 node types from their declaration rather than outputs-then-inputs: inputs and outputs interleaved, an output aligned with the input before it on one row (Set Position’s Geometry in/out, a Menu Switch item’s value input and its “chosen” output, every zone item), buttons where the declaration places them, and collapsible panels. RNA exposes none of that, so the order is recorded in the generated nodebpy.builder._socket_order table (python -m gen.socket_order, parsed from the Blender sources matching the installed bpy). Group nodes draw their interface panels the same way. Panels honour each node’s panel_states and the declared default_closed: a header row per panel, sockets beneath it while open, and only linked sockets folded onto the header while closed (links anchor there); panel-toggle inputs draw in the header. The model also stops counting RNA bookkeeping as drawn property rows (a zone’s paired_output, item collections, is_active_output, inspection_index, active item indices, …), draws vector-valued properties as one row per component, and no longer expands hide_value vector inputs such as Set Position’s Position. to_plot(node=True, open_panels=True) / plot --open-panels expand every panel for review.

520.24.0 - 2026-09-13

Fixes

  • Deterministic emission order with split Group Inputs — dumped sources oscillated forever across build → dump round trips (the same node groups re-shuffling on every rebuild): links from Group Input nodes gated their consumers’ readiness in codegen’s lexicographic topological sort, so a tree holding several instances (split_inputs) emitted consumers in an order depending on the instances’ socket-derived names — and which instance feeds a consumer follows link creation order, i.e. the previous emission. Group Input links now impose no emission order (they render as interface references, bound before any node emits), making dump → build → dump a fixpoint; expect a one-time re-normalization diff on the next dump of an affected library.

520.23.0 - 2026-09-13

Enhancements

  • Group nodes read as their group in generated code — codegen names a group node’s variable after its node group (inverse_mass = InverseMass()) instead of the generic group / group_1 a group node’s “Group” label used to produce.

v520.22.0 - 2026-09-13

Enhancements

  • Split Group Inputs on build — build_library(split_inputs=True) / python -m nodebpy.assets build --split-inputs gives each consumer node its own Group Input instance instead of one node trailing long noodles: instances are named and labelled after the interface sockets they carry (so they read as their content when scanning a tree), unused sockets are hidden, and each instance is parented into its consumer’s frame and arranged next to it. Backed by the new default_split_inputs() scope (mirroring default_sugiyama_options), which TreeBuilders left at their default split_inputs resolve on exit; snapshot-positions sources keep their authored splits untouched. group_input_splits entries now round-trip instance labels too. The config key split-inputs works in [tool.nodebpy.assets], and the option is covered by the ensure stamp fingerprint and forwarded by check.

v520.21.0 - 2026-09-12

Enhancements

  • Assets CLI reads pyproject.toml — python -m nodebpy.assets positionals and flags can come from a [tool.nodebpy.assets] table in the nearest pyproject.toml (walking up from the working directory), with keys spelled like the flags (source and blend supply the positionals, paths relative to the pyproject); explicit CLI arguments always win, and a positional neither given nor configured errors naming both the argument and the config key.
  • ensure and check subcommands — build and full dump now record a fingerprint stamp (<blend>.stamp) covering nodebpy’s version, the resolved options, the source files and the resources .blend bytes. ensure rebuilds only when the .blend or stamp is missing or stale, comparing hashes alone; check verifies the roundtrip fixed point, building the sources and dumping the result back out (as fresh-session subprocesses) and failing unless the sources are reproduced byte-for-byte. The CLI entry also strips argv up to Blender’s -- separator, so every subcommand works as blender -b --factory-startup -P .../__main__.py -- ....

Fixes

  • check reported offending source paths with the platform separator, so the listing and its ordering differed on Windows; paths are now reported and sorted as POSIX, matching the fingerprint.

v520.20.0 - 2026-09-12

Enhancements

  • Material assets are dump roots — dump_library now dumps materials marked as assets alongside node-group assets, not only materials referenced by the dumped trees. Each gets its own materials/ module carrying a MATERIAL_ASSET_METADATA footer, so build_library re-marks it as an asset with its metadata and tags; referenced-only materials still build unmarked. names / --names matches material asset names too, and a full re-dump clears modules of materials that are no longer asset-marked.

v520.19.0 - 2026-09-12

Breaking Changes

  • nodebpy.builder.arrange module renamed to nodebpy.builder.layout — the name arrange is now the arrange() function at both nodebpy.arrange and nodebpy.builder.arrange, so import nodebpy.builder.arrange (and the pre-v520.1.0 import nodebpy.arrange) raise ModuleNotFoundError. Every helper keeps its name and signature under nodebpy.builder.layout (arrange_tree, build_dependency_graph, topological_sort, organize_into_columns, calculate_node_dimensions, position_nodes_in_columns, position_reroutes); arrange_tree is also exported from nodebpy.builder. A shim module cannot be provided because importing it would rebind the package attribute and shadow the function.

Enhancements

  • Unified arrange() API — nodebpy.arrange(tree, method) lays out any node tree, in or outside a TreeBuilder context. method is "sugiyama" (layered layout, the default), "simple", None, or a SugiyamaOptions / SimpleOptions instance for tuned settings; every arrange= parameter accepts the same values. default_sugiyama_options(options) scopes what the plain "sugiyama" default resolves to, so batch builds can tune trees whose recipes don’t set an arrangement themselves.
  • Vendored node-arrange synced and made truly headless — the layout engine is synced with upstream 8ca5e29 (cycle-edge fix, Blender 5.0–5.2 socket bindings, optimize_sizes), its module-global state replaced with per-run state, and — critically — it now always arranges the whole tree: the addon-derived code arranged the selection, so a tree loaded from a .blend (no selection) was silently left untouched, and links to unselected nodes were dropped from the layout graph.
  • Calibrated layout geometry — headless size estimation now skips sockets Blender doesn’t draw (hidden-unlinked), and the row metrics were calibrated against real addon-arranged output (socket-aligned reroutes measure the true socket offsets), fixing nodes estimated ~45% too tall. SugiyamaOptions defaults now match the addon settings validated against MolecularNodes’ hand-arranged trees: 30/30 spacing, top-right alignment, no socket alignment. add_reroutes=True routes long links with reroute nodes (off by default — added reroutes change authored structure).
  • Structural layout snapshots — to_python(snapshot_positions=True) emits a tree.layout_snapshot block recording each node’s type, location, frame parent and links; on rebuild, nodes are matched to entries by structure (names only break ties), renamed to their authored names, re-parented into frames and placed. Duplicate-type nodes a rebuild names in a different order previously landed on each other’s authored spots; real libraries (including the 617-node “Curve to Tube”) now round-trip with identical names, positions and link topology. Sockets are recorded by rebuild-stable keys (name + repeat index) instead of history-dependent identifiers, and group_input_splits entries carry each instance’s location and frame parent.
  • Headless layout plots — nodebpy.export.to_plot(tree, path) draws a tree’s layout to an image with matplotlib (pip install nodebpy[plot]): real node rectangles, estimated socket-anchored links, frames and reroutes. nodebpy.assets.plot_library(blend, dir, names) / python -m nodebpy.assets plot render node groups selected by exact name or wildcard ("Style *") to PNGs — for reviewing layouts or posting graphs in pull requests — optionally re-arranged first.
  • Arrangement on the build CLI — build_library (and python -m nodebpy.assets build) accepts arrange=SugiyamaOptions(...) plus add_reroutes=True; the CLI exposes every option (--spacing, --iterations, --direction, --socket-alignment, --add-reroutes, …), shared with the plot subcommand. Snapshot-positions sources keep their authored layout regardless.

Fixes

  • TreeBuilder.link read socket endpoints after links.new(handle_dynamic_sockets=True) had freed and recreated them (a reroute retypes its sockets to match the link), an intermittent use-after-free segfault; endpoints are now re-read from the created link. The group_input_splits setter had the same stale-socket hazard after links.remove.
  • Arranged node locations are quantized to the 2-decimal dump precision, so arranged trees round-trip losslessly through dump → build.

v520.18.0 - 2026-09-10

Enhancements

  • Typed _build_group signatures — generated classes annotate the builder parameter per tree type (def _build_group(self, tree: TreeBuilder[GeometryNodeTree]) -> None:), importing the bpy.types tree class, so the whole method body type-checks and autocompletes in editors; NodeGroupBuilder._build_group itself is now typed TreeBuilder[T], so hand-written Custom*Group subclasses inherit the narrowed hint too.
  • Lint-clean generated output — formatted output now runs ruff check --fix and ruff format as it is written (sorted imports, double-quoted strings, **{...} collapsed to plain kwargs where socket names allow), so dumped sources need no lint pass afterwards; the dump’s metadata footers and library references emit double-quoted strings directly.

Fixes

  • Codegen’s value formatter rendered a one-element tuple without its trailing comma (("X") — a plain string), so any single-entry sequence value degenerated on rebuild; it now keeps the comma.

v520.17.0 - 2026-09-10

Enhancements

  • Dump and build asset libraries — nodebpy.assets.dump_library(blend, dir) writes every node-group asset in a .blend to its own .py module: assets, shared helper groups (under _shared/), code-generated materials (under materials/), with ASSET_METADATA / MATERIAL_PROPERTIES / DATABLOCK_DEPENDENCIES footers and the asset catalog file travelling alongside. nodebpy.assets.build_library(dir, blend) rebuilds the .blend from those sources, so the Python files can be the version-controlled source of truth. python -m nodebpy.assets dump <blend> <dir> / build <dir> <blend> run both in a fresh session; --typed-api merges the typed asset API (docstrings, _Inputs/_Outputs accessors, PackageLibrary anchor) into the dumped classes. A full re-dump clears modules of assets since renamed or deleted, appending refuses sessions whose same-named datablocks would corrupt the dumped names, and build_library resolves non-serialisable datablocks from the session, a resources= .blend, or on_missing="drop" placeholders — and fails upfront (with a per-tree-directory hint) when two sources build same-named assets.
  • Library parity auditing — nodebpy.export.serialize_library / compare_libraries (and the python -m nodebpy.export.parity a.blend b.blend CLI) deep-compare two asset libraries via tree_clipper serialization, with selectable cosmetic surfaces (positions, reroutes, …) to exclude. Used throughout the test suite to verify dump → build round-trips.
  • Round-trip fidelity against real libraries — Blender’s bundled geometry / shading / compositing essentials and the MolecularNodes asset library (456 assets together) now round-trip through dump → build to zero functional-parity findings, enforced by tests.
  • Curve mappings round-trip — Float Curve, RGB / Vector Curves and Hue Correct nodes with edited curves now emit their full mapping state (point locations, handle types, selection, clip ranges, tone, black/white levels); previously an edited curve silently rebuilt as the default ramp.
  • Multiple separate Group Input nodes — trees using the editor convention of one input node per consumer cluster round-trip via tree.group_input_splits (recorded with snapshot_positions=True), and tree.split_group_inputs() / TreeBuilder(split_inputs=True) regenerate the style on authored trees. Each split entry moves exactly one link, so parallel links from several instances into one multi-input socket survive.
  • Same-named sibling panels — Blender allows several same-named panels under one parent; tree.panel(...) gained reuse=False (create a fresh panel instead of reusing) and accepts an existing panel (or a previous tree.panel(...) context) to reopen exactly that panel. Codegen uses both spellings so such interfaces rebuild without folding panels together, and empty organizational panels are now emitted too. A mixed tree.panel inside tree.outputs.panel(...) now nests under it correctly and restores each direction’s own active panel on exit.
  • Interface menu defaults assigned after the with TreeBuilder(...) block exits now apply immediately instead of queueing forever, and reading menu.default_value reports the pending or applied interface value instead of the stale node socket.
  • Interface Font / Sound socket defaults are now dumped and rebuilt like the other datablock defaults, and is_strip_modifier joined the round-tripped tree-level properties.
  • Exposed the TrimString node via StringSocket.trim(), with codegen round-tripping trees back to the method call
  • Exposed the StringToValue node via StringSocket.to_float() / .to_integer(base), and IntegerSocket.to_string() now exposes the node’s base and padding options
  • to_python now round-trips split(), to_float() / to_integer() and float/integer to_string() as socket method calls instead of g.SplitString(...) / g.StringToValue.*(...) / g.ValueToString.*(...) factory calls

Fixes

  • to_python rendered datablock values as bpy.data.<collection>["Name"], so a generated script raised KeyError in any session lacking the datablock — they now render as guarded .get("Name") lookups, letting standalone scripts run with the default left empty (the dump/build pipeline still resolves them upfront via DATABLOCK_DEPENDENCIES).
  • Zone items (simulation / repeat / for-each) were re-created in socket-identifier order, silently un-reordering items that had been reordered in the editor; they now rebuild in collection order. The zone output’s inspection_index round-trips too.
  • Referencing one of several same-named outputs on a group node used an identifier-derived accessor name (group.o.socket_0) that broke on rebuild — such outputs are now referenced by position (group.o[2]), which the interface order preserves.
  • value.map_range(...) with a non-default steps value emitted five positional arguments where steps is keyword-only, making the generated script fail to run.
  • An IntegerMath operation with a float operand was lifted to a Python operator that rebuilt as a float ShaderNodeMath node; the lift now checks operand types like the other math lifts.

v520.16.0 - 2026-08-28

Enhancements

  • Font and Sound sockets everywhere Blender allows them — tree.inputs.font() / .sound() (and the outputs equivalents) create interface sockets; typed font / sound factories were added to IndexSwitch, MenuSwitch, the repeat zone’s items, closure zone inputs / outputs, EvaluateClosure inputs / outputs and Combine / Separate Bundle items. to_python emits the new spellings, and FONT joined the socket-compatibility table so font links are accepted by the builder. Simulation, For-Each, Bake and Capture Attribute items are unchanged: Blender 5.2 rejects these datablock types there.

v520.15.0 - 2026-08-27

Enhancements

  • Menu Switch item descriptions — enum items can now carry the tooltip Blender shows in the menu. A dict item value may be a (value, description) pair (g.MenuSwitch.geometry(menu, {"Object": (obj, "Use the source object")})), and the new switch.item(name, value, description=...) helper declares a single item and returns a MenuItem handle exposing the item’s input socket, its is_selected boolean output and its (settable) description. Declaring the first item via item() defaults the menu selection to it, matching the constructor, and a selection named before any items exist (g.MenuSwitch.geometry("Mesh")) is deferred until the tree is built. to_python export emits the pair form for described items, so descriptions now round-trip instead of being silently dropped.

v520.14.0 - 2026-08-23

Enhancements

  • Datablock comparisons — the Compare node now covers the datablock types Blender 5.2 can compare in geometry trees: g.Compare.object, .image, .collection, .material, .font and .sound factories each offer equal / not_equal (the only operations Blender permits for datablocks) and return a typed Compare[...] whose i.a / i.b carry the matching socket class. to_python export emits the factory spellings automatically.
  • ty 0.0.74 / ruff 0.16 migration — the whole repository now passes ty check under the current ty release. The socket class hierarchy was made Liskov-compliant without suppressions, types-networkx types the arrange library’s graphs, and code touching the newer bpy stubs (which mark most collections and pointers as optional) narrows explicitly at each call site. Test files relax only the bpy-stub noise rules via [[tool.ty.overrides]] in pyproject.toml.
  • The full ruff check rule set now passes: remaining findings were fixed individually (collapsed conditionals, contextlib.suppress, iterator idioms, a mutable Euler/list argument default, sorted __all__), with the deliberate catch-all exception handlers in probing/repr-fallback code marked noqa explicitly.
  • PEP 695 generics — every generic class and function now uses native type-parameter syntax (class SampleGrid[T](BaseNode) instead of Generic[_T]), including the generator’s emitted node classes; the shared module-level TypeVars are gone, with the socket result-type constraints carried onto each class’s own parameters. The generator also now computes stub-narrowing ignores from the actual enum subsets instead of a hard-coded property-name list, and drops the blanket node: annotation ignore the current stubs no longer need.

Fixes

  • MenuSwitch export in shader and compositor trees — to_python emitted the private g._MenuSwitchBase constructor for a MenuSwitch outside a geometry tree (and for the shader-only SHADER data type), producing code that failed to import. The emitter now uses the tree-appropriate MenuSwitch class (s.MenuSwitch.shader(...)), and the codegen registry prefers a public class over a private base sharing its bl_idname.
  • Comparison operators on vector and integer sockets were annotated as returning a Compare[...] node builder; at runtime they have returned the result socket since v520.x — the annotations now say BooleanSocket, so (a < b).x-style code type-checks against what actually happens.
  • vector.__rmatmul__ gained its missing MatrixSocket overload, and matrix __rmatmul__ accepts raw sockets and numpy arrays in its signature (the runtime always did).

v520.13.0 - 2026-08-20

Enhancements

  • Typed item factories for item-driven nodes — the typed per-datatype factories introduced for zones now cover the other items-driven nodes. CaptureAttribute(...).items.vector("Pos", field) and Bake().items.geometry("Geo", source) declare items and return statically typed two-role Item handles; FieldToGrid.float(topology).items.float("Density", field) returns a dual-typed GridItem whose field input and grid output each carry their own socket class.
  • CombineBundle().items.float("a", 0.5) / SeparateBundle(bundle).items.float("a") and EvaluateClosure(closure).inputs.geometry("Geo", source) / .outputs.vector("Force") declare bundle and closure-call items with static types, returning the relevant typed socket directly. All bundle/closure item factories accept structure_type=; menu items gained factories throughout (including the closure zone’s zone.inputs.menu()).
  • The factory surface is shared infrastructure in nodebpy.builder.items (_FieldItemFactory, _SocketItemFactory, _SocketValueItemFactory), so new items-driven nodes can adopt it declaratively; the Combine/Separate Bundle constructors moved from generator-inlined source into real mixins in nodes/_mixins.py.
  • to_python export emits the typed factories for these nodes (statement form with handle variables for consumed items) instead of the items={...} dicts. This makes generated code typed and self-documenting, and fixes real losses in the dict form: unlinked bundle/closure item defaults were silently dropped, non-"AUTO" structure_type was never emitted, and an unlinked capture/bake item whose default couldn’t round-trip type inference (e.g. a color item, or a string default spelling a socket-type name) was re-declared with the wrong type. The dict constructors remain supported as the string-typed fallback, and emission falls back to them for item types without a typed factory.

Fixes

  • EvaluateClosure’s define_signature, active_input_index and active_output_index constructor parameters now actually reach the Blender node — previously they only set attributes on the Python wrapper, so EvaluateClosure(define_signature=True) silently did nothing. All three are also exposed as node-backed properties.

v520.12.0 - 2026-08-20

Enhancements

  • Typed zone item factories — simulation and repeat zones gain a zone.items namespace with one factory method per data type (zone.items.geometry(), zone.items.float(), …). Each declares a state item and returns a ZoneItem handle whose initial / current / next / result role sockets are statically typed to the matching socket class, so editors autocomplete and type-check the zone body. An optional second argument links a linkable as the item’s starting value or sets a plain default. The repeat factory additionally offers the datablock and closure types only the repeat zone supports (object, image, collection, material, closure), so invalid simulation item types are caught statically.
  • The for-each zone gains the same typed factories for its three item collections: zone.inputs (per-element fields), zone.main (per-element results) and zone.generated (values stored on the generated geometry, with domain=), plus a typed zone.element shortcut for the current element geometry.
  • The closure zone gains zone.inputs / zone.outputs typed factories that declare signature items (with optional structure_type=) and return the body-side socket directly. Item sockets are now resolved by identifier prefix and collection position instead of fragile positional indexing, and Item.input/Item.output and zone.iteration / zone.index are properly typed.
  • to_python export now emits the typed factories (repeat_zone.items.float("value", 1.0) instead of repeat_zone.item("value", 1.0, type=...)), making generated zone code self-documenting and removing the type-inference drift checks. This also fixes a latent round-trip hazard where a string item whose default spelled a socket-type name (e.g. "GEOMETRY") would be re-declared as an item of that type instead of a string default.

Breaking

  • The raw bpy item collection is no longer exposed as .items on zone input/output builder nodes (it collided with the new typed factory namespace); the string-typed zone.item(...), zone.main_item(...), zone.generated_item(...) and zone.input_item(...) / zone.output_item(...) fallbacks are unchanged.

v520.11.0 - 2026-08-03

Fixes

  • Breaking change that fixes the geneartion of class names like BrighnessContrast which previously were being generated as Brightnesscontrast without capitalization.

v520.10.0 - 2026-08-03

Fixes

  • Asset generation exposes every interface input — introspecting an asset node group skipped inputs that Blender’s socket-usage inference marks inactive under the group’s current node options (e.g. a Menu Switch selection deactivating the inputs of the branches not taken), so those parameters were silently missing from the generated __init__. All interface inputs are now generated; the bundled essentials APIs were regenerated and pick up the previously hidden menu-gated inputs (e.g. the compositor ChromaticAberration gains axis, center, samples and fit).

v520.9.0 - 2026-07-22

Enhancements

  • Generated asset classes now carry numpy-style docstrings (description, Parameters, Inputs, Outputs) built from the asset’s own socket tooltips, so editors show documentation alongside the type hints. Pass docstrings=False to generate_asset_api (or --no-docstrings to python -m nodebpy.assets) for the terser output.
  • Menu sockets on generated asset classes are typed with the items they actually offer — shape: InputMenu | Literal["Line", "Circle", "Curve", "Transform"] — matching how menu sockets are already typed on the built-in nodes.

v520.8.0 - 2026-07-17

Enhancements

  • Group nodes are named after their tree — adding a custom node group (CustomGeometryGroup / CustomShaderGroup / CustomCompositorGroup, including asset-backed groups) now names the group node after its node tree (e.g. Smooth by Angle, Smooth by Angle.001) instead of Blender’s default Group / Group.001, matching how group assets are named when added from the Add menu.

v520.7.0 - 2026-07-16

Enhancements

  • Per-tree-type asset modules — nodebpy.assets.generate_asset_modules(libraries, output_dir) splits the generated asset classes into one module per tree type (geometry.py / shader.py / compositor.py), writing only the tree types that have assets. Asset names repeat across editors (a geometry and a compositor “Combine Spherical” both exist), so splitting keeps the generated class names collision-free where a single generate_asset_api module would silently shadow one with the other. The CLI splits the same way when the output is a directory:
python -m nodebpy.assets -b my_assets.blend -o my_addon/nodes/

v520.6.0 - 2026-07-15

Enhancements

  • Blender 5.2 stable — bpy now tracks the final 5.2 release (CI no longer installs daily builds); the node classes and bundled-essentials asset APIs were regenerated against it. The SetAttachmentSurface asset was removed upstream and is no longer generated.

Fixes

  • to_python export now preserves a Value node’s number. The editable value lives on the node’s output socket, which the generic constructor path never examined, so non-default values were silently dropped from the generated code.

v520.5.2 - 2026-07-07

Internal

  • Documentation cleanup.

v520.5.1 - 2026-07-07

Enhancements

  • Interactive graphs in docs / notebooks — a TreeBuilder now displays as an interactive, Blender-styled, pan-and-zoomable node graph in Jupyter and Quarto (via _repr_html_, backed by the new nodebpy.web_render module using tree_clipper and the geonodes-web-render web component). Falls back to the existing Mermaid diagram when rendering isn’t available.

Fixes

  • to_python export: a single link into a multi-input socket is now emitted as a one-element tuple, since the manual classes (JoinGeometry, MeshBoolean, …) expect an iterable — previously such trees didn’t round-trip. Unary float/integer math socket methods also emit Blender’s zero-padded socket identifiers (Value_001).
  • Regenerated the bundled asset APIs with upstream label fixes — e.g. cip_start → clip_start, animated_ → animated, and the “Super 8 mm” film-grain preset spelling.

v520.5.0 - 2026-06-19

Enhancements

  • Changed the linking of asset node groups for the _AssetGroupMixin to be ‘linked & packed’ by default

v520.4.0 - 2026-06-19

Enhancements

  • Chaining nodes with >> node supports None in a chain. Allows for optional insertion of a node given a condition.
from nodebpy import geometry as g

transform = False

with g.tree():
    (
        g.Cube()
        >> g.Array(count=4)
        >> (g.TransformGeometry(translation=(1, 1, 1)) if transform else None)
        >> g.SetPosition()
    )

v520.3.0 - 2026-06-18

Enhancements

  • Additional socket methods on FloatSocket and IntegerSocket.

Fixes

  • Changed nodebpy absolute imports to relative inside the package, and potentially relative / dynamic import for asset generation. Absolute imports would fail when the package is vendored. Does change the behaviour of the node class generation for the imports.
  • FloatGridSocket.to_mesh() method didn’t link any of the input arguments, this now properly links and is tested against

v520.2.0 - 2026-06-16

Enhancements

  • Asset node-group APIs — generate typed nodebpy classes for node-group assets, so an asset reads, links and type-checks like any other node. Unlike a Custom*Group (which builds its tree), an asset class appends the asset’s node group from a .blend at runtime and points a Group node at it.
    • Blender’s bundled essentials are generated into nodebpy.nodes.{geometry,shader,compositor} and exported alongside the built-in nodes, so they’re used exactly like any other node:
    from nodebpy import geometry as g

mesh = g.SmoothByAngle(mesh=g.Cube(), angle=0.6).o.mesh  # an asset, fully typed
g.Array(geometry=mesh, count=4)
    • nodebpy.assets.generate_asset_api(library, output_path) generates the same typed classes for your own assets — point it at a .blend shipped in your package via PackageLibrary(__file__, "…/assets.blend") (or BundledLibrary("…") for a Blender-bundled library) and import the result like any other node module.
    • New runtime bases AssetGeometryGroup / AssetShaderGroup / AssetCompositorGroup (parallel to the Custom*Group builders) back these classes; library resolution is handled by BundledLibrary / PackageLibrary.

Fixes

  • Fixed a bug where AxesToRotation silently did not set the primary and secondary when instantiating a new node

v520.1.1 - 2026-06-15

Internal

  • Code generator refactor — the generator gained a register_customization registry (mirroring codegen.register_emitter), so node classes that previously had to be hand-written in full inside manual.py are now auto-generated, with small reusable mixins or bespoke __init__/factory bodies layered on at generation time. The Bézier handle nodes, Switch, the bundle pack/unpack nodes, the items nodes (Bake, FieldToList, FormatString), and the field-evaluation nodes (AccumulateField, EvaluateAtIndex, FieldAverage, FieldMinAndMax, EvaluateOnDomain, FieldVariance) were moved off the hand-written path. No public API changes.
  • Generator reorganised into a gen/ package — the monolithic generate.py was split into focused modules (config, customizations, model, introspect, emit, writers), kept outside src/ so it never ships in the wheel. Run with python -m gen (or python -m gen --only geometry to regenerate a single tree). The skip / hand-written / generate decision is now a single Disposition derived from the same class-name logic used for generation, introspection is cached so each node is only inspected once, and the generator loads the dependency-free types leaf standalone so it can run even when the generated tree is mid-refactor.
  • The code generator now infers generic typing more completely — generic input sockets that track a node’s data type, and nodes whose output type is fixed while the inputs vary — tightening the type hints on HashValue, ListLength, ValueToString, FilterList, StoreBundleItem, SetSelection, and StoreNamedGrid.

Fixes

  • CombineBundle / SeparateBundle item construction is now part of the generated output, fixing a latent issue where their custom constructors were silently overwritten whenever the node classes were regenerated.

v520.1.0 - 2026-06-15

Enhancements

  • Nodes to code (to_python) — TreeBuilder.to_python() (and the standalone nodebpy.export.to_python()) converts any node tree back into idiomatic nodebpy Python — interface sockets, properties, links, zones, frames and nested groups included. It recognises lifted operators (Math → *, SeparateXYZ → .x), socket methods, factory methods and zone item APIs, so generated code reads like hand-written nodebpy. Validated end-to-end against Blender’s full bundled geometry, shader and compositor essentials asset libraries, so it round-trips real-world trees, not only ones built with nodebpy. See Nodes to Code. Options:
    • snapshot_positions=True — capture and restore each node’s authored location (top-level and inside nested groups) instead of auto-laying-out the rebuilt tree.
    • keep_reroutes=True — preserve reroute nodes as g.Reroute(...) pass-throughs instead of collapsing each reroute chain into a direct link; pairs with snapshot_positions to reproduce the original wire routing.
    • top_level="class" — emit every node group, including the working tree, as a Custom*Group subclass, for archiving a set of groups as plain reusable Python. Defaults to the with TreeBuilder(...) as tree: form.
    • Nested frames are reconstructed as nested with g.Frame(): blocks (including container frames that hold only sub-frames).
    • format=True (default) runs the output through ruff format when the optional ruff package is installed (pip install nodebpy[format]), for tidier source; a no-op when ruff is unavailable.
    • strict=False emits a # TODO placeholder for unsupported nodes; register_emitter(bl_idname) plugs in a custom generator for any node type.
  • NodeGroupBuilder.create_group() — classmethod that builds and returns a custom group’s node tree without an active TreeBuilder context (it opens its own), reusing an existing tree of the same name. Lets a group be pre-built and assigned directly to a node’s node_tree.
  • TreeBuilder.node_positions — a read/write {node name: (x, y)} mapping for snapshotting and restoring node locations, plus TreeBuilder.disable_arrange() to skip the auto-layout that otherwise runs on context exit.
  • Bundle and closure item APIs — CombineBundle(items={name: source}) / SeparateBundle(bundle, items={name: "TYPE"}), EvaluateClosure(closure, input_items=..., output_items=...), and a ClosureZone wrapper (cz.input_item(...), cz.output_item(...), cz.closure) for defining a closure’s body inline.
  • Colour field evaluation — ColorSocket gained the domain field-evaluation methods (.point.at(i), .point.evaluate(), …) via EvaluateAtIndex / EvaluateOnDomain, matching the other socket types.
  • Socket methods for AlignRotationToVector for VectorSocket and RotationSocket (align_rotation() and align_to_vector()
  • Grid socket operator methods — chainable methods on the *SocketGrid types that build and wire up the matching grid node, so grid pipelines can be expressed fluently:
    • All grids — sample(position, interpolation), sample_index(x, y, z), field_to_grid(), clip(...), dilate_erode(steps, connectivity, tiles), prune(threshold, mode), voxelize(), to_points()
    • Float, vector and integer grids — mean(width, iterations), median(width, iterations)
    • Float grids — gradient(), laplacian(), sdf_fillet(), sdf_laplacian(), sdf_mean(), sdf_mean_curvature(), sdf_median(), sdf_offset(), to_mesh()
    • Vector grids — curl(), divergence()
grid = g.CubeGridTopology() >> g.FieldToGrid.boolean()
density = grid.capture_float(g.NoiseTexture().o.fac)
flow = density.dilate_erode(1).laplacian().gradient().divergence()

Fixes

  • Grid mean() and median() now pass the correct data_type (Blender’s VALUE float type is mapped to FLOAT), fixing a crash when calling them on float grids
  • INT_VECTOR sockets (e.g. compositor Image Info “Dimensions”) are now link-compatible with regular VECTOR sockets, matching Blender’s implicit conversion.
  • Multi-input sockets (JoinBundle, …) accept an iterable of sources via their constructor, linking each in turn (as JoinGeometry already did).
  • Linking a node into a Reroute (or any other adaptive __extend__ socket, such as Viewer) now works from any source type — the reroute adapts instead of rejecting the connection.

Breaking Changes

  • g.SetHandleType() now defaults to left=True, right=True (mode = {'LEFT', 'RIGHT'}), matching Blender’s native default for a freshly added node. Previously it defaulted to an empty mode, which set no handle types. The shared left/right/mode logic for SetHandleType and HandleTypeSelection was factored into a mixin; SetHandleType also gained a mode property for parity.

v520.0.1 - 2026-06-05

Fixes

  • Import and usage of the arrange() function properly handles the optional netowrkx dependency

v520.0.0 - 2026-06-04

Enhancements

  • Added leading(), trailling() and total() methods from AccumulateField node onto relevant sockets. Added to Float, Vector, Integer and Matrix sockets.
  • Blender 5.2 support — generated nodes updated to include the nodes for Blender 5.2.
  • List socket subtypes — new *SocketList socket types matching Blender 5.2’s list sockets, added for every base socket type (FloatSocketList, IntegerSocketList, VectorSocketList, ColorSocketList, BooleanSocketList, RotationSocketList, MatrixSocketList, StringSocketList, MenuSocketList, GeometrySocketList, ObjectSocketList, MaterialSocketList, CollectionSocketList, ImageSocketList, and more). List sockets carry methods for working with the list:
    • list_length() — number of elements, also available via len()
    • get(index) — retrieve an element (or a sub-list when indexed with an IntegerSocketList) via GetListItem
    • filter(selection) — keep elements where selection is true
    • sort(sort_weight, group_id=None, selection=None) — sort via SortList
    • reverse() — reverse the list
    • list_slice(start, stop, step) — Python-style slicing, also driven through [] indexing and slicing (e.g. list[::2], list[-3:-1])
indices = g.Index().o.index.to_list(10) # an IntegerSocketList of equal to `range(10)`
evens = indices[::2]          # IntegerSocketList via GetListItem
count = len(indices)          # IntegerSocket via ListLength
first = indices.get(0)        # IntegerSocket
  • Grid socket subtypes — new *SocketGrid socket types for volume grids (FloatSocketGrid, IntegerSocketGrid, VectorSocketGrid, BooleanSocketGrid), with transform(), background_value(), and component indexing.
  • to_list(count) — convert a field socket into a list socket via FieldToList. Available on FloatSocket, IntegerSocket, VectorSocket, ColorSocket, BooleanSocket, RotationSocket, MatrixSocket, StringSocket, and MenuSocket.
  • New StringSocket methods — uppercase() and lowercase() (via SetStringCase) and reverse() (via ReverseString).
string = g.String("Example").o.string
string.uppercase()   # StringSocket via SetStringCase
string.lowercase()   # StringSocket via SetStringCase
string.reverse()     # StringSocket via ReverseString

v0.18.0 - 2026-05-20

Added

  • Pre-commit hooks for ruff and ty checks and auto-formatting.
  • ty type checking for the full src/ directory for type safety
  • Convenience methods for ObjectSocket and CollectionSocket:
    • CollectionSocket
      • instances(transform_space="ORIGINAL", separate_children=False, reset_children=False) — import objects from the collection as instances, returns GeometrySocket
    • ObjectSocket:
      • transform(transform_space="ORIGINAL") — get the transform matrix, returns MatrixSocket
      • location(transform_space="ORIGINAL") — get the location, returns VectorSocket
      • rotation(transform_space="ORIGINAL") — get the rotation, returns RotationSocket
      • scale(transform_space="ORIGINAL") — get the scale, returns VectorSocket
      • geometry(as_instance=False, transform_space="ORIGINAL") — get the geometry, returns GeometrySocket
  • Added is_selected() method to MenuSwitch - returns the BooleanSocket for the named menu item that is true when the item is selected

v0.17.0 - 2026-05-13

Enhancements

  • New methods on VectorSocket for applying transforms:
    • rotate(rotation) — apply a RotationSocket via RotateVector, returns VectorSocket
    • transform(matrix) — apply a MatrixSocket via TransformPoint, returns VectorSocket
  • New methods on RotationSocket:
    • rotate(rotation, rotation_space="GLOBAL") — compose rotations via RotateRotation, returns RotationSocket
    • to_euler() — convert to XYZ euler angles, returns VectorSocket (renamed from euler())
    • to_quaternion() — decompose via RotationToQuaternion, returns a Quaternion named tuple with .w, .x, .y, .z
    • to_axis_angle() — decompose via RotationToAxisAngle, returns an AxisAngle with .axis and .angle
  • FloatSocket.mix — factory property for creating typed Mix nodes driven by this socket as the factor. Supports .float(), .vector(), .color(), .rotation().
  • FloatSocket.map_range() and VectorSocket.map_range() — remap a socket’s values using MapRange. Supports from_min, from_max, to_min, to_max, clamp, interpolation_type, and steps.
normalized = value.map_range(0.0, 100.0, 0.0, 1.0)
remapped_vec = vec.map_range((0,0,0), (1,1,1), (-1,-1,-1), (1,1,1))
  • New methods on FloatSocket:
    • clamp(min=0.0, max=1.0) — clamp to range via Clamp
    • sqrt() — square root
    • power(exponent) — raise to a power
    • floor() / ceil() / round() — rounding variants
    • modulo(divisor) — floored modulo (always non-negative, consistent with Python %)
    • wrap(min, max) — repeat cyclically within a range
    • to_radians() / to_degrees() — angle unit conversion
  • New methods on VectorSocket:
    • cross(other) — cross product, returns VectorSocket
    • distance(other) — Euclidean distance, returns FloatSocket
    • project(other) — project onto another vector
    • reflect(normal) — reflect around a normal (normal does not need to be normalised)
  • New methods on IntegerSocket:
    • clamp(min=0, max=1) — clamp to integer range
    • modulo(divisor) — integer remainder (always non-negative)
  • New method on MatrixSocket:
    • transform_direction(direction) — apply the matrix to a direction vector, ignoring translation. Use this instead of transform() for normals and tangents.
  • Domain factories on FloatSocket, VectorSocket, IntegerSocket, BooleanSocket, RotationSocket, and MatrixSocket — select a domain property, then call the operation. Each call returns a single typed socket.
    • Domain properties: .point, .edge, .face, .corner, .spline, .instance, .layer
    • All socket types: .evaluate() — re-evaluate on the domain via EvaluateOnDomain; .at(i) — retrieve at an index via EvaluateAtIndex
    • Float/Vector additionally: .min(), .max(), .mean(), .median(), .std_dev(), .variance() (with optional group_index)
    • Integer additionally: .min(), .max() (with optional group_index)
# Field evaluation — works on all socket types
position.face.evaluate()       # VectorSocket — position re-evaluated on face domain
flag.point.at(3)         # BooleanSocket — flag value at point index 3
rot.edge.evaluate()            # RotationSocket

# Statistics — Float / Vector
lo = position.point.min()
mean = curvature.face.mean()
std_dev = weight.point.std_dev(group_index)
fac = g.Value(0.5).o.value
fac.mix.float(0.0, 1.0)          # FloatSocket
fac.mix.vector((0,0,0), (1,1,1)) # VectorSocket
fac.mix.color(color_a, color_b)  # ColorSocket

Breaking Changes

  • RotationSocket.euler() renamed to RotationSocket.to_euler() for consistency with the new to_quaternion() and to_axis_angle() methods.
  • RotationSocket.w, .x, .y, .z component properties removed. Use to_quaternion() instead.
  • Multi-output socket methods (to_quaternion(), to_axis_angle(), find(), svd()) now return typed NamedTuple results. Both named access and positional unpacking are fully typed.
# Named access
rot.to_quaternion().w      # FloatSocket
rot.to_axis_angle().angle  # FloatSocket
string.find("/").first_found  # IntegerSocket
mat.svd().u                # MatrixSocket

# Positional unpacking — all variables are specifically typed
w, x, y, z = rot.to_quaternion()
axis, angle = rot.to_axis_angle()
first, count = string.find("/")
u, s, v = mat.svd()
  • FloatSocket.to_integer(rounding_mode="ROUND") — convert to integer via FloatToInteger. Accepts "ROUND", "FLOOR", "CEILING", or "TRUNCATE".

v0.16.0 - 2026-05-05

Enhancements

  • Input VectorSocket now properly has the x, y, z attributes through CombineXYZ node.
  • Socket methods added for strings. Methods added are: length(), starts_with(), ends_with(), contains(), slice(), format(), replace(), find(), join()

string = g.String("Example String").o.string

string.length()      # return g.StringLength().o.length, same as len(string)
string.starts_with() # return g.MatchString().o.result
string.ends_with()   # return g.MatchString().o.result
string.contains()    # return g.MatchString().o.result
string.slice()       # return g.SliceString().o.string
string.format()      # return g.FormatString().o.string
string.replace()     # return g.ReplaceString().o.string
string.find()        # return FindResult(first_found, count)
string.join(x)       # return g.JoinStrings(x, delimeter=string)

String sockets can also be joined with + operator like python strings.

These two are equivalent.


string + "example"

JoinStrings((string, g.String("example")), separator="").o.string

Float and integer sockets have to_string() methods:

g.Float().o.value.to_string(3) # specify decimal places

g.Integer().o.integer.to_string()
  • Math, comparison, and unary operations on sockets now return the output socket of the created node rather than the node itself. This allows method chaining directly on the result.
# Before: result was a Math / VectorMath / Compare node
# After:  result is a FloatSocket / VectorSocket / BooleanSocket
pos = g.Position().o.position
scaled = pos * 2.0            # VectorSocket
clamped = (scaled > 0.5)      # BooleanSocket
mat = g.CombineTransform() @ g.CombineTransform()  # MatrixSocket
vec = g.CombineTransform() @ g.Position()           # VectorSocket

To access the underlying builder node from any socket returned by a math operation, use the .builder_node property:

result = g.Value(2.0) ** 3.0   # FloatSocket
result.builder_node             # the Math node
result.builder_node.i.value_001 # input socket on that node
  • Accessing .o or .i on any BaseNode now sets .builder_node on the returned socket, pointing back to that node.
pos = g.Position().o.position
pos.builder_node   # the Position node
  • Added svd() method onto MatrixSocket which returns an SVDResult with .u, .s, .v properties.
  • Add sign() and negate() methods onto the FloatSocket for method chaining. Both return FloatSocket.
  • Remove socket_name property from BaseSocket, already accessible via .socket.name.
  • Added .dot(), .length() and .normalize() methods to VectorSocket which create the corresponding DotProduct, VectorLength and Normalize nodes.
  • Properties on sockets that aren’t just accessing components of the socket are node methods. They still return sockets and not nodes.
    • RotationSocket.invert -> RotationSocket.invert()
    • RotationSocket.euler -> RotationSocket.to_euler()
    • MatrixSocket.invert -> MatrixSocket.invert()
    • MatrixSocket.transpose -> MatrixSocket.transpose()
    • MatrixSocket.determinant -> MatrixSocket.determinant()

Breaking Changes

  • Compare.switch(false, true) with automatic type inference has been removed. Use the explicit typed factory methods on BooleanSocket.switch instead.
# Before
(val == 5).switch(g.Cube(), g.IcoSphere())

# After
(val == 5).switch.geometry(g.Cube(), g.IcoSphere())
(val == 5).switch.float(0.0, 1.0)
(val == 5).switch.integer(0, 1)
  • Math operations no longer return nodes — code that accessed node properties directly on the result (e.g. result.operation, result.data_type, result.i) must now go through result.node or result.builder_node:
result = g.Value(2.0) * 3.0

# Before
result.operation              # "MULTIPLY"
result.i.value.default_value  # 2.0

# After
result.node.operation              # "MULTIPLY"
result.builder_node.i.value.default_value  # 2.0

Bug Fixes

  • The ColorSocket properly only indexes to length 3 inside of the shader as SeparateXYZ and CombineXYZ don’t have alpha inputs or outputs.
  • Fixed bug in mixins that was resulting in node comparison creation when checking if a node / socket was None instead of using is None comparison.
  • tree() helper functions in geometry, shader, and compositor modules now return a typed TreeBuilder[NodeTreeType] for improved type-checker support.
  • Fixed BaseNode._from_node() to correctly wrap an existing node without creating and immediately discarding a temporary node.

v0.15.0 - 2026-04-30

Enhancements

  • Boolean sockets have a switch method which creates a Switch node with the socket as the input. Allows for quick chaining.
b = tree.inputs.boolean()
b.switch.float(0.1, 0.2)
b.switch.geometry(g.Cube(), g.IcoSphere())
  • Changes to some node methods to better align with naming inside of Geometry Nodes:
    • EvaluateAtIndex & EvaluateOnDomain:
      • rotation -> quaternion
      • transform -> matrix
    • SampleIndex & SampelCurve:
      • rotation -> quaternion
  • Handle adding items for the ColorRamp and FloatCurve nodes to create mappins of 0..1 floats to values and colors.

Bug Fixes

  • The *Socket classes have been added to the types for checking.
  • Inputs and outputs properly listed on the ForEachGeometryElement nodes.
  • JoinString links in the intended order (by first reversing the iterator before linking which is required for multi-input sockets).
  • StoreNamedAttribute has the domain and data_type factor methods properly exposed for StoreNamedAttribute.face.vector().

v0.14.0 - 2026-04-29

Enhancements

  • Nodes which previously took *args and **kwargs have been updated to use keyword-only arguments instead. This is a hard breaking change but makes the code more readable and less error-prone. (#69)
    • Affected nodes: FieldToGrid, JoinGeometry, MenuSwitch, IndexSwitch, CaptureAttribute, JoinStrings, FormatString, SDFGridBoolean, MeshBoolean, RepeatZone, SimulationZone
  • Tree interfaces are defined with tree.inputs.geometry() methods rather than using the old context-based s.SocketGeometry(). Both systems have been living side-by-side but this completely removed old system so is a hard breaking change. (#67)
# old system
with tree.inputs:
    s.SocketGeometry()

# new system
tree.inputs.geometry()
  • Drop the .inputs and .outputs accessors for the nodes, in favor of just using .i and .o properties directly. This will reduce confusion as .inputs and .outputs are available on the base bpy nodes themselves. (#65)
  • Better type hinting and stubs for the MenuSwitch and IndexSwitch nodes. (#62)

Bug Fixes

v0.13.0 - 2026-04-28

Enhancements

  • Support adding of closure nodes (EvaluateClosure and the ClosureInput / ClosureOutput nodes). Convenience ClosureZone class is added similar to the repeat, simulation and for-each-element zones. (#60)
  • Iteration output for the RepeatZone has change .i -> .iteration to not confuse with input / output socket access (#60)
  • Add a Float() class which just wraps the Value() class / node but is better for hinting towards it’s type and more discoverage ([#58](https://github.com/BradyAJohnston/nodebpy/pull/58))

Bug Fixes

  • Properly expose mode, domain and data_type as methods and method factories for SampleIndex and SampleCurve. (#61)
  • Math on a ColorSocket now uses the VectorMath instead of Math preserving the RGB channels as XYZ. (#56)

v0.12.0 - 2026-04-25

Enhancements

  • Support custom node groups for each node tree via CustomGeometryGroup, CustomShaderGroup, CustomCompositorGroup (#53)

v0.11.1 - 2026-04-24

Bug Fixes

  • Fix type inference for the >> operator in chains, properly propagating the correct node’s return type.

v0.11.0 — 2026-04-24

Enhancements

  • Refactor the mermaid diagram generation. Change screenshot.py -> diagram.py and added test coverage.
  • Socket iteration and indexing — VectorSocket, ColorSocket, and MatrixSocket now support __getitem__, __iter__, and __len__ on both output and input sockets. (#48) Output sockets decompose via SeparateXYZ/SeparateColor/SeparateMatrix (node reuse on repeated access); input sockets auto-wire a CombineXYZ/CombineColor/CombineMatrix and return the component input socket.
for i, axis in enumerate(g.Position().o.position):
    math = axis * float(i)

# Pipe a value into the Y component of a position input
g.Value(5.0) >> g.SetPosition().i.position[1]

mat = g.InstanceTransform().o.transform
vec = g.CombineXYZ(*mat[:3])
  • RotationSocket/MatrixSocket helpers — Added .invert and .transpose properties on MatrixSocket, .invert on RotationSocket, following the same node-reuse pattern as .x/.y/.z.
  • SocketAccessor overloads — __getitem__ and _get are overloaded so slices return list[Socket] and str/int keys return Socket, eliminating the Socket | list[Socket] union that was blocking enumerate and unpacking.
  • Blender 5.1 compatibility — Generator updated for Blender 5.1: FontSocket type, Frame node moved to manually_defined, SVD class name normalisation, and classmethod param deduplication fix (min_x/min_y/min_z no longer collapsed to min). (#50)
  • Precise operator return types — Arithmetic operators on FloatSocket → Math, VectorSocket → VectorMath, IntegerSocket → IntegerMath. Comparison operators (<, >, <=, >=, ==, !=) → Compare. The >> operator is typed via TypeVar so the right-hand operand’s exact type is preserved through chains.
  • Generic factory nodes — AccumulateField, EvaluateAtIndex, FieldAverage, FieldMinAndMax, EvaluateOnDomain, FieldVariance, and Compare are now Generic[_T]. Their _Inputs/_Outputs inner classes carry the type parameter so e.g. .point.vector(...) returns FieldAverage[VectorSocket] and .o.mean resolves to VectorSocket.

Bug Fixes

  • Fix doc building and will only deploy on tagged releases. (#49)
  • Domain factory pattern — All _domain_factory / local-class patterns replaced with proper _DomainFactory inner classes (including CaptureAttribute) so the type checker can resolve their return types.
  • SocketAccessor identifier lookup fix — Added a normalised-identifier pass (normalize_name(id)) so attribute access like .i.value_001 correctly resolves Blender identifiers such as Value_001 that cannot be round-tripped through denormalize_name.

v0.10.2 - 2026-04-21

Enhancements

  • Added changelog to the documentation to better track and explain changes in the project.
  • Support len(tree.inputs) and len(tree.outputs) to get the number of inputs and outputs in the tree. (#43)
  • Added the GPLv3 license to the project.

v0.10.1 — 2026-04-20

Bug fixes

  • Fixed CaptureAttribute.capture() not correctly linking the captured input socket. (#41)

v0.10.0 — 2026-04-19

The biggest release yet. The headline change is a new typed socket accessor API — node.i.x / node.o.x — that replaces the old node.o_position-style properties and brings full IDE auto-complete and type narrowing to socket access.

Enhancements

node.i / node.o socket accessors (#39)

Sockets are now accessed through .i (inputs) and .o (outputs) accessor objects. Attribute names are the normalised socket identifier, so spaces become underscores and the first letter is lowercased.

node.o.position >> node.i.offset   # pipe position into offset
node.o.position.y * 0.2            # operate on the y component

In node definitions, _Inputs / _Outputs inner classes declare the available sockets and their types so IDEs can provide auto-complete:

class SetPosition(BaseNode):
    class _Inputs(SocketAccessor):
        geometry: GeometrySocket
        position: VectorSocket
        offset:   VectorSocket

    class _Outputs(SocketAccessor):
        geometry: GeometrySocket

NodeGroupBuilder — custom node groups as Python classes (#31)

Define reusable node groups as plain Python classes. The group tree is built once and cached; subsequent uses insert a Group node pointing at that tree.

class Jitter(NodeGroupBuilder):
    _name = "Jitter"
    _color_tag = "geometry"

    def __init__(self, geometry=None, amount=0.2, seed=0):
        super().__init__(Geometry=geometry, Amount=amount, Seed=seed)

    @classmethod
    def _build_group(cls, tree):
        geom   = tree.inputs.geometry("Geometry")
        amount = tree.inputs.float("Amount", 0.2)
        seed   = tree.inputs.integer("Seed", 0)

        offset = g.RandomValue.vector(min=-1, seed=seed) * amount
        _ = g.SetPosition(geom, offset=offset) >> tree.outputs.geometry()

# Composes identically with built-in nodes
g.IcoSphere(subdivisions=4) >> Jitter(amount=0.15) >> out

g.tree() module-level helper (#36)

Eliminates the need to import TreeBuilder directly when working with a single editor type.

# Before
from nodebpy import TreeBuilder
with TreeBuilder.geometry("My Group") as tree: ...

# After
from nodebpy import geometry as g
with g.tree("My Group") as tree: ...

Simplified interface socket definition (#37)

Interface sockets can now be defined directly on the tree object without a context manager:

with g.tree() as tree:
    geo = tree.inputs.geometry("Points")
    g.SetPosition(geo)

The previous context-manager form still works.

Other changes

  • Auto-detection of nodes requiring data-type class methods (e.g. .float(), .vector()) is now more robust. (#38)
  • builder.py was split into a builder/ package for maintainability; VectorSocketLinker was renamed to VectorSocket. (#35)
  • Internal type aliases cleaned up — InputFloat replaces TYPE_INPUT_VALUE etc. (#34)

v0.9.1 — 2026-03-27

Enhancements

== / != comparison operators (#28)

BaseNode objects now support Python equality operators, returning a Compare node. Chain .switch() to immediately branch on the result:

# Creates a Compare node then routes into a Switch
(g.Value(5.0) > 2.0).switch(false=g.Cube(), true=g.IcoSphere())

Data-type-specific socket linkers (#29)

VectorSocket, ColorSocket, FloatSocket, and IntegerSocket carry type-specific operations (e.g. .x, .y, .z on vectors) so arithmetic stays typed all the way through a chain.

Other changes

  • Documentation styling improvements. (#27)

v0.8.0 — 2026-03-16

Enhancements

networkx is now an optional dependency (#24)

nodebpy now has no hard dependencies outside of bpy, making it easier to vendor into add-ons. A built-in simple arranger is used when networkx is absent; the Sugiyama layout remains the default when it is installed.

v0.7.2 — 2026-03-15

Enhancements

matrix @ vector creates a TransformPoint node (#22)

matrix @ g.Position()  # → TransformPoint node

Bug fixes

  • Fixed ... (ellipsis) handling in >> chains — type-aware output selection now works correctly when skipping intermediate nodes. (#23)

v0.7.1 — 2026-03-14

Enhancements

Color >> Shader linking (#21)

Piping a color socket into a shader input is now handled automatically, matching the way Blender promotes color connections in the node editor.

v0.7.0 — 2026-03-13

Enhancements

Panels for tree interfaces (#20)

Group interface sockets can be organised into named panels:

with tree.inputs.panel("Settings"):
    s.SocketFloat("Amount", 0.2)
    s.SocketInt("Seed", 0)

Integer math is now handled correctly in Shader and Compositor editors (mapped to float math, as Blender does not expose integer math there).

v0.6.0 — 2026-03-13

Bug fixes

  • Fixed MenuSwitch node creation and socket wiring. (#18)

Other changes

  • Mermaid diagram generation improvements: math node operators are now shown, and socket connections use -> instead of >>. (#19)

v0.5.0 — 2026-03-13

Enhancements

Compositor and Material (Shader) node editors (#12)

nodebpy now supports building Compositor and Shader/Material node trees in addition to Geometry Nodes.

Remaining Python math operators (#15, #16)

** (power), % (modulo), // (floor divide), abs(), and unary - are all wired up. Operator order for vector math was also corrected.

Literal type hints for menu sockets (#17)

Enum choices on menu sockets are exposed as Literal type hints, giving IDE auto-complete on string arguments like data_type="FLOAT".