Docs
Download

Architecture

How a node graph becomes a running add-on.

All paths are relative to addon/scripting_nodes/src/.

The pipeline

edit in the node editor
  → scheduler.request_*()        nothing else happens inside update callbacks
  → flush (timer, ~0.1 s later)
      integrity    init new trees, unique ids, references of copied nodes,
                   versioning (file load / undo / copies only)
      sockets      every node's sockets match its declaration
      compile      graph → {path: source}            core/compiler.py
      apply        write changed files, reload       core/runtime.py

Nodes store no generated code. Every rebuild walks the graph and asks the nodes for their code again, so there is nothing that can go stale after undo, file loads or renames: what is in the graph is what compiles. A rebuild is one linear pass per tree (a 300 node chain compiles in about 40 ms).

What gets generated

The add-on is written to <user scripts>/addons/<module name>/:

__init__.py             imports the modules, registers their classes
blender_manifest.toml
<tree>.py               one module per node tree
<folder>/<file>.py      trees and scripts in folders: a package per folder (core/folders.py)
properties.py           the add-on's properties (only if there are some)
utils.py                shared helper functions (only if used)
scripts/<name>.py       the add-on's scripts (Files list, folder "Scripts" by default), unchanged
assets/<name>           the add-on's assets (Addon Data › Assets), copied (core/assets.py)
icons/<image>           images of Custom Icon nodes

The layout is the one of a hand-written add-on: __init__.py (core/package.py) imports the modules and registers an explicit classes tuple, read from the generated modules (every top-level class deriving from a registrable bpy.types type, moved after the classes its properties or bl_parent_id need). Modules defining register() / unregister() have them called after the classes are registered (before they're unregistered). The live add-on also gets bl_info, since it's loaded as a legacy add-on; the export is an extension.

A tree's or script's folder (tree.folder / script.folder, a path like UI/Panels) is its package: folder names claim module names like trees do (core/naming.py, still unique add-on wide, so __init__.py can import every module by name). Nodes write imports relative to the add-on's folder (from .properties import ...); the compiler makes them relative to the module's package (naming.relative_import), and in a folder __package__ becomes base_package (from .. import __package__ as base_package), Blender's idiom for sub-modules. Scripts default to the folder Scripts (a property default, so scripts saved before folders keep scripts/<name>.py). The Files list shows scene.sna.ui.files, one row per folder, tree and script, synced by a scheduler watcher (node_tree/file_list.py). Moving files can turn a module name into a package and back; lib/reloading.py reloads such modules (reload finds the spec again) and clears packages' stale submodule names first.

Exports are formatted like ruff format (lib/python_format.py, no dependencies), and tree modules lose the parentheses nodes put around the values they combine (remove_redundant_parens, kept only if the syntax tree stays the same). tests/test_example_addon.py compares the export of an example add-on against tests/snapshots/object_toolkit/, which CI checks with ruff (tests/snapshots/ruff.toml).

Inside a tree module, root nodes (operators, panels, events, properties, …) are emitted first, sorted by sn_order. Every other node is emitted when a flow reaches it, or, for value nodes, when one of its outputs is used. Nodes with an emit_module(ctx) method are emitted at module level too, wherever they are in a flow. A tree with a group interface also defines a function (see core/functions.py): Group Input values are its parameters, Group Output is return, and its flow sockets decide whether a Group node calls it as a value, a statement or UI. Group Input / Output are Blender's own nodes, so the compiler handles them itself.

Scripts are the user's code and stay as written. Their classes are registered like any other, unless the script defines register(): then it registers itself, before everything else.

Loading

core/runtime.py owns the generated folder:

  • Changed modules are syntax-checked before anything is written. On an error the previous version keeps running.
  • The add-on is fully disabled and enabled again. If the new version fails to import or register, the previous files are restored and loaded.
  • Only folders containing the .scripting_nodes marker file are ever written to or deleted.

Errors

Errors always end up on the node that caused them:

WhenHow it is mapped
emit() raises (NodeError or a bug)caught per node by the compiler
syntax / import / register error of the add-onfailing line → node via the compiler's line map
exception while the add-on runs (e.g. clicking a button)the add-on's functions and methods, wrapped by the runtime before it registers → traceback line → node (core/tracebacks.py)

The generated code contains nothing for this; the line map lives in Scripting Nodes.

Dev and export builds

The live add-on and an exported zip come from the same compiler (compile_addon(dev=True/False)). The only differences are in core/helpers.py: for example utils.log also writes to the node editor overlay in dev builds and is plain print in exports. Nodes never check the build mode.

Saved data

Trees store a data version (core/versioning.py). When saved data changes shape (renamed properties, idnames, socket keys, enum items), add a step there and bump DATA_VERSION. Changes to a node's sockets need no step: they are re-synced from the declaration on load.