Nodebox (asset type)

A nodebox is a namespace folder that groups related .procNode/ children, the way a toolbox groups .tool/ children. A node's name is its folder name inside its box: points.nodebox/disc.procNode is called points.disc, and nothing inside the node states that name. Moving or renaming a node is a VFS move that keeps its guid.

Where it lives

• Source: <anywhere>/<family>.nodebox/, usually inside a .package, an effect or a world's content.
• Identity: the folders above it and <family> (fx.points for fx/points.nodebox; the .nodebox suffix strips). A graph calls its nodes by <family>.<node> alone.
• Folder shape (open child set):
  • README.md: what the family is for. Required.
  • .metadata: description and tags. Required. It also states where the box's nodes work: context (one of proc.registry.contexts(): geometry, field, value, sim, raster, material, prefab) and, when every node of the box reads the scene or assets beside its inputs or writes them beside its outputs, pulls / pushes (scene or asset). A node that works elsewhere states its own in its .metadata. procgen describeNode and the context, pulls and pushes filters of searchNodes read them.
  • <node>.procNode/: any number of nodes.

How a graph reaches a node

g.<family>.<node>(args) resolves the node by its asset identity: the box and the folder name together (g.points.disc), a path (g["/zero/source/fx/ring.procNode"]), ~ (the nearest enclosing package, effect or world root: g["~/ring"]) or a short name the asset system resolves (g.disc). A name that matches two nodes is an error naming both; a name that matches none is an error naming the closest nodes. Each call is recorded in the graph's reference table by the node's guid.

How to create one

asset.create("nodebox", "points", { folder = "fx" })
local box = asset.resolve("points.nodebox")
asset.create("procNode", "disc", { into = box })

Discovery

• asset.list("nodebox"): every box.
• asset.inspect("points"): the nodes in it and what each does.
• asset.list("procNode"): every node, in or out of a box.

In the Inspector

Nodes: how many nodes the box holds, each node's full name and what it does, and a link to each.