---
url: /pawn/docs/packages/json-render.md
description: Scenes a model writes as json-render specs, from your registered prefabs.
---

# @pawnjs/json-render

::: info 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](https://github.com/vercel-labs/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](/guide/prefabs#prefab-params) and its own traits and
  behaviors, every one optional. Core traits such as `shape` are set
  only through params, so give the prefab a `color` param to let a model
  color it.
* The prompt lists each prefab with its
  [`description`](/guide/prefabs), footprint and props. Keep descriptions
  to a sentence; ten prefabs make a prompt of under 6 KB.
* A `group` element (type `GROUP`, `"group"`) lists other elements in
  `children`, 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](#rendering-a-spec) does.
* A prefab param or behavior named like a placement prop (`at`, `turn`,
  `position`) is rejected by `createCatalog`.
* `catalog.catalog` is 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 in `problems` and skipped.
* Each call returns what it did, for a log of the stream: the keys it
  `spawned`, `updated` and `destroyed`, and its own `problems`: its lines
  that did not apply, problems it brought (a group that lost a child),
  and the problems of the elements its lines touched.

  ```ts
  const { 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 later
  `push` patches 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`](/guide/snapshots#entity-ids),
  so snapshots and `engine.findEntity` know it. After `engine.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 in `updated`; an entity from another prefab, or one
  another renderer or scope holds, with a key's id is listed in
  `problems`. 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 `problems` until the spec fixes it.
* A `group` element 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.spec` is the spec as compiled so far, `scene.keys` the rendered
  elements, and `scene.clear()` destroys every entity the renderer
  spawned or took over (it spawns into its own [scope](/guide/engine#scopes)).

## 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](https://jakubprill.github.io/pawn/ai-scene.html)
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;
}

```
