Asset Node Groups

Blender ships node-group assets (the bundled “essentials” libraries), and many add-ons distribute their own. nodebpy can generate typed Python classes for these assets so they read, link and type-check exactly like any built-in node — the only difference is that instantiating one appends the asset’s node group from its .blend at runtime (and points a Group node at it) instead of building the tree from scratch.

This is the asset counterpart to Custom Node Groups: a custom group builds its tree in _build_group; an asset group appends a pre-authored one.

Using the bundled essentials

The classes for Blender’s bundled essentials libraries are generated into nodebpy.nodes.{geometry,shader,compositor} and exported alongside the built-in nodes, so you reach them straight off the editor module:

from nodebpy import geometry as g

with g.tree("Assets") as tree:
    mesh = g.SmoothByAngle(mesh=g.Cube(), angle=0.6).o.mesh
    _ = g.Array(geometry=mesh, count=4) >> tree.outputs.geometry()

tree

graph LR
    N0("Cube"):::geometry-node
    N1("Smooth by Angle"):::geometry-node
    N2("Array<br/><small>(1,0,0) +(1,0,0)</small>"):::geometry-node
    N3("Group Output"):::default-node
    N0 -->|"Mesh->Mesh"| N1
    N1 -->|"Mesh->Geometry"| N2
    N2 -->|"Geometry->Geometry"| N3

Each asset is a normal node: typed inputs/outputs (g.SmoothByAngle().o.mesh is a GeometrySocket), >> chaining, IDE autocomplete, and the usual operators. The underlying node group is appended once and reused on subsequent uses.

Generating an API for your own assets

generate_asset_api introspects a .blend asset library and writes a module of typed classes. Point it at your library and a destination .py file:

from nodebpy.assets import generate_asset_api, PackageLibrary

generate_asset_api(
    PackageLibrary(__file__, "data/my_assets.blend"),
    "my_addon/nodes/assets.py",
)

PackageLibrary(anchor, relative) locates a .blend shipped inside your own package (resolved relative to anchor, usually __file__); use BundledLibrary("…") for a library that ships with Blender. You can pass a list of libraries to merge several into one module, and names={...} to restrict generation to specific node groups.

The generated module imports from nodebpy and looks like any other node module, so import and use it directly:

from my_addon.nodes import assets as a

with a.tree("Demo") as tree:
    _ = a.MyAsset(value=2.0) >> tree.outputs.geometry()

Re-run generate_asset_api whenever the .blend changes — the classes are regenerated from the assets’ current interfaces.

How resolution works

Generated classes carry the library reference, not a hard-coded path, and the group is located on demand:

Library	Resolves to
BundledLibrary("geometry_nodes_essentials.blend")	Blender’s system datafiles (…/datafiles/assets/nodes/…)
PackageLibrary(__file__, "data/my_assets.blend")	a path relative to the generated module’s file

Because asset names can collide across editors (a geometry and a compositor “Combine Spherical” both exist), an appended group is reused only when its tree type matches; otherwise the correct one is appended fresh.

Notes

• The generator is a normal runtime tool — call generate_asset_api in a build step, a test, or once by hand; commit the generated module like the rest of your source.
• Inputs with non-scalar defaults (vectors, colours) take None in the generated signature; the appended group keeps its own socket defaults.
• nodebpy’s own bundled-essentials modules are regenerated by python -m nodebpy.assets (wired into make generate).