Model JSON
The persisted schema is the set of Rust serde structs in crates/model/src/document, with ModelJson as the root. The TypeScript types are generated from them by ts-rs into packages/model/src/generated; nothing is declared by hand. Every shape rejects unknown keys, so a misspelled field fails validation instead of being ignored.
Document shape
ModelJson = { version?, title, description?, settings?, materials?, layers?, patterns?,
parameters?, behaviors?, objects?, views?, components?, onClick? }| Field | Meaning |
|---|---|
title | Plain text, verbatim. |
description | Verbatim allowlisted HTML or plain text; never a parameter. |
version | The platform's publish counter. 0 means never published; a save never changes it. |
settings | { units?, environment? }. Absent units means millimetres; the unit only changes how a host displays lengths. |
parameters | Root parameters: the values a user can change. See Parameters and expressions. |
objects | The objects of the model. See Objects and components. |
behaviors | Standing acts on the siblings of the document's objects (an opening that cuts a wall). |
materials, layers, patterns | Record lanes referenced by key. |
views | Camera records. The views lane is in the schema, but no surface lists or edits views and the viewport uses the free camera. |
components | Documents this document places, as functions of their parameters. |
onClick | An expression evaluating to click actions for the root parameters. |
The document type is derived and never stored: a document that has only materials or only patterns is a library, anything else is a component. Internal units are millimetres, Z is up, rotations are in degrees.
One shape for every node
Every node in every lane has the same shape:
{ method, args?, steps?, properties?, behaviors?, objects? } // plus chrome: key?, label?| Field | Holds |
|---|---|
method | A method of the catalog. |
args | Arguments, matched by key, each an expression string. |
steps | A chain: steps run in order and the data kind may change mid-chain. Steps have no keys. |
objects | Keyed nodes: the body of a nest, of the root, of a component. |
properties | Paint, identity, placement and onClick of one object. Each method appears once; copies repeats the placement. |
behaviors | Acts on siblings. Blocks only; each method once, except opening, which may repeat (one cut per entry). |
There is no enabled, locked, flag, cache or fifth body. A node with a key is addressable across the whole model, and there is one key namespace per document across all lanes; renaming a key rewrites every reference.
Arguments
An argument is { key, input }. input is an expression string: a literal ('20', '[0,0,0]'), a parameter name, or any expression over parameters and the stream. Arguments are matched by key, not by position. Text literals use single quotes. An argument that is JSON array or object text, or exactly one quoted string literal, is data and is exempt from the expression length and step budgets.
Steps: the chain
An object's steps form one chain over one data kind at a time. Producers create geometry or records (a rectangle, a circle, a mesh literal, a placed component). Transforms take the stream and return it changed; they carry their input type as a prefix: curve*, face*, solid*, vertex*, mesh*. Curve booleans are 2D and per plane; solid* booleans are 3D and need closed, outward-oriented operands. The evaluated shapes are Curve (N unshared chains) and Mesh (vertices, edges, faces), and every mesh is a closed solid or empty.
Two shapes are final: Curve { vertices, edges } and Mesh { vertices, edges, faces }. A face has loops: loops[0] is the outer loop, the rest are holes, even-odd, planar within tolerance and simple at load.
Properties: placement and appearance
An object has two tiers: the definition (steps or objects, in the object's local frame) and the instance (properties). The twelve placement scalars are translateX/Y/Z (mm), rotateX/Y/Z (degrees), scaleX/Y/Z and pivotX/Y/Z, composed as M = T(t) T(p) Rz Ry Rx S T(-p). Defaults: translate 0, rotate 0, scale 1; an absent pivot axis is the content's bounding-box minimum on that axis (0 for a chain-produced block). There is no vector translation, rotation, scale or pivot property.
Every instance property accepts a per-copy arrow (i) => ... where i is the copy index. copies is the number of copies added. visible is true, false, a list of view keys, or the arrow (i) => boolean, or (i, camera) => boolean when a model chooses to read the camera. Other instance properties: name, material, layer, attributes (engine-blind third-party data) and onClick.
Behaviors
behaviors act on the siblings of their block after the set evaluates. opening cuts every mesh of its siblings, including meshes inside a placed component or nest at any depth, through the composed placements: one extruded profile and direction per entry, each cutting on its own. faceCamera may appear at most once. A behavior never leaves its set. A cut travels as a behavior (the document root's behaviors), never as a placement argument.
Click actions
An object's onClick (or the root onClick) evaluates to one action or an array of actions: Property.animate(name, seconds, [v1...vn]) tweens a numeric property and Property.set(name, [v1...vn]) switches a value. The engine never plays them: it returns plain data and the host executes it. Click state and pose overrides are session state, never document fields. Time is not a document fact: there are no keyframes, timeline or clock.
Validation
engine_load rejects a document with error diagnostics and returns warnings as Changes.diagnostics. Publishing additionally runs the audit (engine_audit): four ordered stages (static, evaluated, settled, shells), the first stage with findings stops the pipeline, and every finding blocks. The closed code list is in the Engine API.
- A
createBlocknest with nopropertiesand nobehaviorsis the static findingbare_nest: a nest exists to carry a placement, copies, paint, visibility, a click action or behaviors for its children. - A declared
sizeX/Y/Zmust equal the visible box's extent on its axis, and a settable size must drive the box (size_mismatch,size_not_driven). - A consumer model's visible bounding box must contain the origin, the attachment point (
origin_outside_box). - One closed shell must not cross itself (
self_intersect). Parts may pass through each other.