pcg-ts

What it is

A node-graph PCG library, deterministic by construction

Build worlds out of rules instead of files. You write the recipe — scatter points over this ground, thin them out with noise, turn each survivor a random amount, put a tree on every one — and pcg-ts runs it. The recipe is a small graph of nodes; running it is called a cook. Feed it the same seed and you get the same world back, byte for byte, on any machine, forever.

pcg-ts is built for real-time use — cooking is budgeted and cancellable so it can run inside a frame, and the field grammar compiles to WGSL to run on a GPU device when one is there.

Any parameter can vary across space instead of being a constant: a value can be a function of where it lands, resolved per point.

Every random decision flows from a seed through one hash chain, so the same graph and seed produce byte-identical output across runs, platforms, cook orders, and streaming paths. Cooking on a GPU device is the one documented exception, and architecture states its tolerances.

The heavy work moves to the GPU: field expressions compile to WGSL, and instance matrices are composed there and handed straight to three.js — without ever touching the CPU.

It is built to be driven by AI agents as much as by humans: nodes carry machine-readable schemas, graphs serialize to stable JSON, and every error names the node, pin, or param at fault and states the fix.

Foundations

Four concepts the rest is built on

Architecture

Layered core, optional adapters

A core that imports nothing outside itself, and adapters that depend on it one way only: three.js interop, the WebGPU compiler and device runtime, the worker pool, the CLI. Above that, a streaming runtime that cooks a world around a moving camera in budgeted, cancellable slices — and returns the same result whatever order it cooked in.

The module layers and the cook path, in two figures →

Built for agents

Runtime introspection and stable serialization

• Self-describing registry — every node type exposes pins, param schemas, defaults, and prose descriptions at runtime; the node reference is generated from it, never hand-written.
• A command line that closes the loop — pcg nodes, fields, validate, cook, inspect, render. --json picks a rendering of the same result rather than a separate code path, exit codes are 0 / 1 (failure) / 2 (misuse), and render writes a deterministic top-down SVG that diffs in git.
• A vocabulary to reference, not rebuild — 37 named primitives ship as pcg-ts/primitives, cited from JSON as ref: { name, hash? }. A name-only ref upgrades freely; a pinned one hard-errors on mismatch. No mode warns, and no mode cooks a near-miss.
• Stable JSON everywhere — graphs, subgraphs, and field expressions serialize to a versioned format that round-trips to byte-identical cooks; serialized form is stable across cooks.
• Errors that state the fix — validation names the offending node, pin, or param and lists the valid alternatives. Error messages are part of the API surface.
• Introspectable execution — cook stats report what cooked, what was cached, and how long it took; determinism makes every run reproducible.
• Agent entry points — llms.txt capability map, generated docs/nodes.md / primitives.md / graphs.md with their .json twins, three skills that cite every enumerable thing by path rather than inlining it, an authoring guide with recipes, and the user manual, whose second half is written for an agent driving the library programmatically.
• Independently audited — each phase was reviewed by a separate agent before it landed, and the defects it found were fixed with regression tests before release.

Examples

Six demos and an editor, live in your browser

Each one needs a host to exist: streaming worlds, a device-resident renderer, a closed loop that measures its own output and corrects, and the editor the single-cook recipes moved into. Click to run.

Behind them sits a corpus of 95 graphs that are data rather than pages: pcg cook graphs/<name>.json. None of them uses dataInput, because its items do not survive serialization and an example an agent cannot run teaches nothing. Most are single-concept; eight are one settlement pipeline — ground and wall, district centres, lots, buildings, roads, plus three edit variants — where each stage is the previous file plus nodes and nothing removed, and the earlier stages cook bit-identically inside the later ones. Every one of them is in the corpus gallery, cooked in the editor and shot from the frame it draws into.

editoropen any corpus graph and edit it live — palette, inspector, a curated knobs panel, JSON round-trip, shareable links, and a cook path you can switch between the CPU and two GPU paths infinite worldhierarchical streaming around a moving camera — with a GPU toggle showing combinator-authored fields reaching the device galaxyan infinite deterministic spiral galaxy — streamed star cells, click any star to visit its planets gpu worlda streamed world whose instance matrices are composed in WGSL and drawn straight from that buffer — toggle to the CPU path and watch the readbacks appear racetrackroadside art placed along a spline the page was handed — six legibility rules run as a bounded fixed point, with every repair reporting how much it had to do roadthe same page with none of the placement rules in it — one spline, one sweep, one evenly spaced row per side, shot at the same station so the difference between the two pictures is exactly what the rules add caveone node with no inputs makes the whole world: meshFromField contours a noise into triangles, and the level cuts space into CUBE cells rather than the flat ones every other world here uses — each cube is contoured knowing nothing of its neighbours, and the seam you cannot find between any two of them is the claim being demonstrated lanternsone u32 per instance is the whole interface between a graph and a shader — the graph settles where each lantern hangs and the seed it carries, the page derives colour, pulse and bob from that integer and a clock the graph never sees; switch the id source to the f32 copy and watch the colour wheel collapse

How the racetrack decides what stands beside the road, and where →

How one integer per lantern becomes a colour, a flicker and a bob →

Roadmap

What shipped in each release

Fifteen releases from the first foundation to the current one: the attribute data model and PCG32, then fields, the streaming runtime, the WebGPU compiler and device runtime, subgraphs, the worker pool, and the editor that drives all of it through the same public API this page documents.

What shipped in each release →