procGraph (asset type)

A .procGraph asset is a procedural graph: a description of how to make something, written as code, that can be evaluated over and over with different numbers. Its init.luau returns proc.define(...) — that source IS the asset, the way a .procNode's init.luau is.

Shape

A <name>.procGraph/ folder containing:

• init.luau: the graph's definition. Returns proc.define(function(g) … end), the graph named by its asset folder.
• graph.json — the compiled form (proc.graph.v1), written by this type from init.luau. Generated, never hand-edited.
• README.md, .metadata — the universal asset files. The type writes the graph's description and kind into .metadata on every compile.
• layout.json (optional) — where the Inspector's node editor draws each node.
• preview.png (optional) — the graph's rendered still, which search shows.

asset.create("procGraph", name) scaffolds init.luau (a box with a size input, shown through g.io.output and returned as mesh), README.md and .metadata, and the first compile writes graph.json.

Authoring

Edit init.luau. The type recompiles on the write, rewrites graph.json, and every live Generator bound to the asset re-cooks from it — there is no build step between saving and seeing the result.

A graph is built from more than its init.luau: a module the source requires while it builds (onDependencyChange), a file it reads with vfs.read, and a file a module it calls reads with proc.read are part of it, and so is every node it calls. When one of them changes, every Generator standing on the graph builds it again and cooks it on its next frame; nothing is written to the world for it.

A recompile is cheap however large the graph: node results are keyed by content, so recompiling an unchanged node reuses its cooked output, and an edit invalidates only that node and the ones downstream of it. Changing the last step of a landscape does not re-run the erosion above it.

Two words worth keeping apart, because both happen here:

• compile — init.luau → graph.json. Produces the graph.
• cook — each node performing its operation to produce a value. Runs the graph. Driven by a Generator, reported by procgen.cooks.

Using one

Through the ref rather than a path string: ref:eval("mesh") evaluates an output ("output:mesh" and "node:<id>" are targets too, and ref:eval("mesh", { inputs = { size = 3 } }) overrides inputs for the call), ref:inputs() lists the knobs a Generator can override by name ({ [name] = { type, default, min?, max?, ... } }), ref:outputs() the sorted output names, ref:validate() type-checks it (an empty list when it is well-typed), and ref:asOp() wraps it so another graph can composite it as a node. ref:graph() builds the graph from init.luau; ref:compile() compiles it now and answers { id?, nodes, out }; ref:instantiate(target?, { params?, output?, ... }) puts it in the scene on a Generator; ref:promote(opts?) makes it a .procNode; ref:preview(opts?) renders its still and ref:stillTime() names the moment that still shows.

Generated outputs (meshes, materials, textures, bundles) are persisted through their own asset types.

Related

• @builtin::systems.procgen.proc — the authoring + evaluation model.
• procgen.toolbox — preview, spawn, bake, validate, searchNodes, describeNode and the wider tool family.

In the Inspector

The Inspector shows the graph as nodes and wires, and edits it there. Every graph input, op, graph used as a node and output is a node; each input port that nothing is wired into carries the value that drives it, and a click on a value edits it where it stands (typing, dragging a number, flipping a switch, choosing from a list). Drag a node to move it, drag from a port to another port to connect, drag a connected input away to take its wire off, Delete removes the selection. A node is added from the op search under the graph, or from the procGraph assets, which stand as nodes that open their own asset on a double click. The graph's inputs and outputs are nodes too: their name, type, default and range, and an output's domain, are values on them, and the Inputs and outputs section declares new ones. Describes is the sentence search finds the graph by. The Graph section also carries Compile, which compiles the graph now, and a link that opens init.luau.

Every edit is written into init.luau with proc.saveSource and compiled by the type, so a live Generator re-cooks on it; the node positions are kept beside the graph in layout.json. The Result section scrubs the timeline of a graph that has one and shows what the selected node makes (procgen.preview with the target node:<id>), and the Preview section above it shows what the graph makes, live. The Node section describes the selected node.