Appearance
@pawnjs/json-render
Not on npm yet
This package comes with a later release of Pawn.
Lets a language model build scenes from your prefabs with json-render: the model answers with a spec, one element per entity, streamed as JSON Patch lines. The package needs @pawnjs/core, koota, three and zod 4.3.6 or later; it does not need React and does not call any model API itself, so the API key stays in your app or on your server.
Scene catalog
createCatalog(engine, options) offers the engine's registered prefabs to a model: what each element takes as props, and the system prompt that teaches the spec.
ts
import { createCatalog } from "@pawnjs/json-render";
const Tank = definePrefab({
name: "tank",
description: "Liquid tank, 3.2 m tall.",
traits: [Position, [Shape, { kind: "cylinder" }]],
params: { color: ["shape.color"] },
});
engine.prefabs.register(Tank);
const catalog = createCatalog(engine, {
grid: new Grid({ columns: 24, rows: 16 }),
footprints: { tank: [2, 2] },
scene: "an industrial hall",
});
const system = catalog.prompt({ rules: ["Tanks go along the west wall."] });The model then answers with lines such as:
json
{"op":"add","path":"/elements/tank-1","value":{"type":"tank","props":{"at":[2,3],"color":"#ef4444"}}}| Option | Default | Meaning |
|---|---|---|
prefabs | every registered prefab | Names of the prefabs to offer. |
grid | none | Floor grid: elements place with at: [column, row] and turn of 0, 90, 180 or 270 degrees. Without it they place with position in meters and any turn in degrees. |
footprints | [1, 1] | Cells each prefab covers on the grid, columns × rows. |
scene | "a 3D scene" | What the scene is, for the prompt's first line. |
- An element's props are its placement, the prefab's params and its own traits and behaviors, every one optional. Core traits such as
shapeare set only through params, so give the prefab acolorparam to let a model color it. - The prompt lists each prefab with its
description, footprint and props. Keep descriptions to a sentence; ten prefabs make a prompt of under 6 KB. - A
groupelement (typeGROUP,"group") lists other elements inchildren, to edit or remove them together. catalog.validate(spec)returns{ ok, problems }with every problem it finds: unknown types, props that do not fit, children on anything but a group, missing children and groups that contain themselves. It does not check placement on the grid (a footprint past the edge, overlaps); the renderer does.- A prefab param or behavior named like a placement prop (
at,turn,position) is rejected bycreateCatalog. catalog.catalogis the json-render catalog itself, for json-render's own tools.
Rendering a spec
createRenderer(catalog) spawns a spec's elements from the catalog's prefabs and keeps them in step as the spec changes. Feed it the model's answer as it streams:
ts
import { createRenderer } from "@pawnjs/json-render";
const catalog = createCatalog(engine);
const scene = createRenderer(catalog);
for await (const chunk of answer) scene.push(chunk);
scene.flush();
scene.entity("tank-1"); // also engine.findEntity("tank-1")
for (const { key, text } of scene.problems) console.warn(key, text);push(chunk)takes text split anywhere and renders every whole line;flush()renders a last line without a newline. A line that is not JSON Patch is listed inproblemsand skipped.Each call returns what it did, for a log of the stream: the keys it
spawned,updatedanddestroyed, and its ownproblems: its lines that did not apply, problems it brought (a group that lost a child), and the problems of the elements its lines touched.tsconst {spawned,problems} =scene.push(`${line}\n`); if (problems.length=== 0)console.log("spawned",spawned);render(spec)renders a whole spec, from a file or an editor; a laterpushpatches it. Either way only what differs is changed: a new element is spawned, a changed prop is set on the same entity (a removed one goes back to the prefab's value), a removed element is destroyed, and an element whose type changes is spawned again.Each element's key is its
EntityId, so snapshots andengine.findEntityknow it. Afterengine.restore(), rendering the spec again takes over the restored entities of each element's prefab instead of spawning them twice, sets them as the spec says and lists them inupdated; an entity from another prefab, or one another renderer or scope holds, with a key's id is listed inproblems. An element whose entity was destroyed elsewhere frees its cells and is spawned again by a later call.An element that does not fit (wrong props, off the floor, overlapping another footprint) is left as it was last rendered, or not spawned, and listed in
problemsuntil the spec fixes it.A
groupelement becomes an entity with its children under it (ChildOf). Without a grid, children's positions are relative to the group. Removing a group keeps the children the spec still has.scene.specis the spec as compiled so far,scene.keysthe rendered elements, andscene.clear()destroys every entity the renderer spawned or took over (it spawns into its own scope).
A recorded answer
The scene below plays back a model's answer line by line: elements are added on a 10 × 6 grid, then one tank turns red with replace and a rack goes away with remove. The AI scene showcase streams the same kind of answer live from Claude, on your own API key.
ts
import {
definePrefab,
Engine,
Grid,
Position,
Rotation,
Scale,
Shape,
} from "@pawnjs/core";
import { createCatalog, createRenderer } from "@pawnjs/json-render";
/** A model's answer, recorded: one JSON Patch line per element or edit. */
const ANSWER = [
'{"op":"add","path":"/elements/tank-1","value":{"type":"tank","props":{"at":[1,1]}}}',
'{"op":"add","path":"/elements/tank-2","value":{"type":"tank","props":{"at":[4,1]}}}',
'{"op":"add","path":"/elements/pump-1","value":{"type":"pump","props":{"at":[3,2]}}}',
'{"op":"add","path":"/elements/pump-2","value":{"type":"pump","props":{"at":[6,2]}}}',
'{"op":"add","path":"/elements/rack-1","value":{"type":"rack","props":{"at":[8,0]}}}',
'{"op":"add","path":"/elements/rack-2","value":{"type":"rack","props":{"at":[9,0]}}}',
'{"op":"add","path":"/elements/rack-3","value":{"type":"rack","props":{"at":[1,4],"turn":90}}}',
'{"op":"replace","path":"/elements/tank-2/props/color","value":"#ef4444"}',
'{"op":"remove","path":"/elements/rack-3"}',
];
export default function aiScene(canvas: HTMLCanvasElement): Engine {
canvas.style.cssText = "display:block;width:100%;height:100%";
const engine = new Engine({
canvas,
camera: { position: { x: 0, y: 9, z: 9 } },
background: "#09090b",
lights: "studio",
});
const standing = (name: string, kind: "box" | "cylinder", size: number[]) =>
definePrefab({
name,
traits: [
[Position, { y: size[1] / 2 }],
Rotation,
[Scale, { x: size[0], y: size[1], z: size[2] }],
[Shape, { kind, color: "#cbd5e1" }],
],
params: { color: ["shape.color"] },
});
engine.prefabs.register(
standing("tank", "cylinder", [1.8, 2.4, 1.8]),
standing("pump", "cylinder", [0.6, 0.8, 0.6]),
standing("rack", "box", [0.9, 1.8, 2.9]),
);
const grid = new Grid({ columns: 10, rows: 6 });
engine.spawn(
Shape({ kind: "plane", color: "#27272a" }),
Scale({ x: grid.columns, y: 1, z: grid.rows }),
);
const catalog = createCatalog(engine, {
grid,
footprints: { tank: [2, 2], rack: [1, 3] },
});
// A model reads catalog.prompt(); here its answer plays back line by line.
const scene = createRenderer(catalog);
// One line every half second, then the finished scene for 2 s.
const PAUSE = 4;
let line = 0;
engine.every(0.5, () => {
if (line === ANSWER.length + PAUSE) {
scene.clear();
line = 0;
}
if (line < ANSWER.length) scene.push(`${ANSWER[line]}\n`);
line++;
});
engine.start();
return engine;
}