Skip to content

@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"}}}
OptionDefaultMeaning
prefabsevery registered prefabNames of the prefabs to offer.
gridnoneFloor 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 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, 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 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, 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).

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
;
}