Skip to content

Components ​

Components are pure-JSON data attached to entities. Molen ships a known component vocabulary; molen validate checks component data against it, so a typo'd name (helth → health) or a wrong field (transform.position → pos) is caught in the cheap pre-sim loop. Inventing your own components is fine — a name that doesn't resemble a known one is accepted as-is (declare it under components in the scene or project to document it). A name that is a near-typo of a known component is flagged.

Discover the live vocabulary from the tools (this page is generated from the same registry):

sh
molen components            # name, owning layer, description
molen component transform   # one component's JSON Schema + examples

(MCP: list_components, get_component.) Capability packages and content can register more with registerComponent(name, zodSchema, meta) from @bendyline/molen-schema. Strict schemas (additionalProperties: false) flag unknown fields; loose ones allow extras.

Conventions ​

  • Coordinate system: Y-up, right-handed; distances in meters.
  • Time is in ticks at the scene tickRate (dt = 1/tickRate s); rates are per second.
  • Quaternions are [x, y, z, w]; identity is [0, 0, 0, 1].
  • Colors are "#rrggbb" strings.
  • collider.halfExtents is [x, z] (2.5D kinematics act in the XZ plane).
  • moveIntent.dir is [x, z]: +x east, +z south (screen-down in top-down views).
  • layer/mask are bitmasks: a collides with b when a.mask & b.layer or b.mask & a.layer is non-zero.
  • renderable.primitive.size is [x, y, z].
  • environment.sun.direction points FROM the origin TOWARD the sun (the light sits at that offset and shines back at the origin).

Vocabulary ​

ComponentOwnerDescription
aircraftkernel/aircraftExternal airplane/helicopter instance. Y up, Z forward; landing-contact origin.
aircraftInputkernel/aircraftPilot flight controls. Power is retained when input keys are released.
aircraftStatekernel/aircraftDeterministic flight state, including rotor phase and engine spool, preserved by keyframes.
ambientAgentambientKernel-owned state of an ambient NPC (car, pedestrian, train car, aircraft or boat): its lane, position along it, speed and routing. Read it; the ambient systems write it.
ambientObserverambientMarks the entity ambient NPCs spawn around (usually the player or camera rig), with optional radius and density overrides.
ambientRoleambientOn an entity type: makes it an ambient NPC candidate (car, bus, rail car, aircraft, boat or ferry) with dimensions, speeds and spawn weight.
ambientStateambientKernel-owned ambient bookkeeping on the $ambient entity: observer, spawn sequence and policy overrides.
audioEnvironmentaudioSingleton soundscape rules: bus gains, ambience layers gated on weather/sky/listener signals, music playlist, event → sound mappings and listener footsteps.
audioSourceaudioSound emitter on an entity: a sound-bank id, loop/autoplay, gain and pitch driven by signals (vehicleState.speed, listener.distance…), and one-shot triggers. Positional when the entity has a transform. Render-side only; see guide/audio.md.
audioZoneaudioArea ambience: a looping sound that fades in as the listener enters a sphere or box around the entity (a waterfall, a machine room, a market).
boatkernel/boatsWaterline-aligned powered hull with data-driven handling and shared seats.
boatInputkernel/boatsHelm intent: signed thrust, steering and low-speed anchor. Only the driver controls it.
boatStatekernel/boatsSnapshot-safe hull motion, buoyancy and anchoring; owned by installBoats.
boostModekernelWorld-wide 4× travel assist for people and vehicles. Control response times stay normal.
characterkernel/characterKinematic character controller state (speed/jump/gravity + kernel-owned vy/grounded).
colliderkernel/kinematics2.5D kinematic collider (circle or XZ AABB) with layer/mask bitmasks.
collider3dphysics-rapier3D collider (ball/cuboid/capsule/hull/trimesh/asset/heightfield) with layer/mask, sensor, and material params. Static without a rigidbody.
coupledkernel/vehiclesA rail car in a consist: rides the leader's track trail at a fixed distance behind it, sharing its speed. Powered cars add their traction to the leader's (multiple-unit control); every car adds its mass and brakes.
environmentclientSingleton scene environment: optional Earth/custom sky, ambient/sun lighting, background, fog, tone mapping, shadow quality tier.
figurefiguresWhat a figure is: a preset plus descriptor overrides (height, build, proportions, features, palette) and how it faces its motion. Pair with renderable.kind "figure".
figureAttachmentfiguresFollow a named socket of the parent figure (with parent): the figures systems write localTransform from the evaluated pose each tick.
figureIntentfiguresOptional authored control of a figure: a forced mode, a look-at target, joint overrides, and IK goals.
figureStatefiguresKernel-owned locomotion state of a figure (mode, quantized speed, tick-anchored gait phase). Read it; the figures systems write it.
forcephysics-rapierContinuous force/torque applied every tick while present.
fsmkernel/gameplayMinimal event-driven state machine: transitions fire on world events targeting the entity.
glasskernel/glassBreakable glass surfaces with metric geometry, material fracture and independent frame/interlayer retention.
glassStatekernel/glassPersistent glass fracture, retention and release state. Missing panes are intact; remove the component to repair.
healthcontentCommon gameplay hit-points component.
impulsephysics-rapierOne-shot impulse/torque; consumed the tick it is applied.
jointphysics-rapierImpulse joint to another body (fixed/revolute/spherical/prismatic + limits/motor).
kinematicBodykernel/kinematicsVelocity-driven body for the kinematic collision layer.
lifetimekernelAuto-despawn countdown in ticks.
lightclientA light source at the entity transform (directional/point/spot).
liveryclientReusable model paint slots, bound surface markings and selectable liveries. Visual only.
localTransformkernel/gameplayParent-relative transform for entities carrying parent.
model.signalsclientBind same-entity simulation fields and named numeric expressions to GLB transforms and visibility. Supports calibration, cyclic needles and timed response. Visual only; no physics writes.
mountablekernel/vehiclesMount points in local meters, ordered safe exit candidates, and interaction reach. Seat position is the rider camera anchor.
mountedkernel/vehiclesRider-to-mount relationship. Occupied seats are exclusive; mounted characters bypass walking physics.
moveIntentkernel/characterDesired planar move direction + jump flag, consumed by the character controller.
parentkernel/gameplayAttach to a parent entity: transform becomes parent.transform × localTransform each tick.
platformBodykernelDeterministic XY platform controller: gravity, swept wall/floor/ceiling collision, jump buffering and coyote time.
platformIntentkernelInput to a platformBody. Scripts translate declared commands to this component.
platformSolidkernelStatic XY solid for physics.engine=platformer; Z is ignored.
renderableclientClient render contract: a primitive, a gltf asset (by project asset id) with optional sub-node, material override, shadows, and clip playback, or a capability-registered kind.
rigidbodyphysics-rapier3D rigid-body dynamics: dynamic, fixed, or kinematicPosition (characters).
setVelocityphysics-rapierOne-shot velocity set; consumed the tick it is applied.
tagcontentNamed tag for selecting/grouping entities (e.g. tag.name === "enemy").
timerkernel/gameplaySnapshot-safe countdown timers that emit events (one-shot or repeating). Replaces callbacks.
transformkernelWorld position + orientation. pos is required; rot defaults to identity.
tweenkernel/gameplayData-driven value animation over ticks: component + select-style path, lerp with easing.
vehiclekernel/vehiclesExternal wheeled-vehicle instance: stable id, paint, complete physics tuning, and GLB bindings.
vehicleInputkernel/vehiclesDriver intent: signed throttle (negative brakes then reverses), signed steering (positive right), service brake and optional handbrake.
vehicleStatekernel/vehiclesSnapshot-safe chassis state. Speeds in m/s, angles in radians; owned by installVehicles.
velocityphysics-rapierOpt-in per-tick body velocity mirror (presence = subscription; plugin-written).
waterkernel/boatsDeterministic swells and current for boats; heights and coverage come from the host water field.
weatherSingleton physical atmosphere and visual weather: temperature, pressure, humidity, wind, independent cloud cover, precipitation and visibility. Readable by scripts and physics; see guide/weather.md.
worldgenBuildingworldgenA building generated at runtime from an outline in the entity frame, styled by a molen/archstyle@1 in the loaded pack; rendered by the worldgen client entity layer.

Owner: ambient ​

ambientAgent ​

Kernel-owned state of an ambient NPC (car, pedestrian, train car, aircraft or boat): its lane, position along it, speed and routing. Read it; the ambient systems write it.

Required: kind, type, lane, s, speed, seed, length, width, state, since, hops, spawnedTick

json
{
  "kind": "car",
  "type": "molen.entities.vehicle.sedan",
  "color": "#4d76b8",
  "lane": "15/5245/11443#k3j9x2>f0",
  "s": 42.5,
  "speed": 11.2,
  "seed": 1964432,
  "length": 4.65,
  "width": 1.82,
  "state": "move",
  "since": 1200,
  "hops": 3,
  "spawnedTick": 1180
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "car",
        "pedestrian",
        "train",
        "aircraft",
        "boat"
      ],
      "description": "Agent class."
    },
    "type": {
      "type": "string",
      "description": "Content type id (e.g. molen.entities.vehicle.sedan), figure preset, or \"proxy\"."
    },
    "color": {
      "type": "string",
      "description": "Body colour (#rrggbb)."
    },
    "lane": {
      "type": "string",
      "description": "Lane id the agent is on (\"\" for aircraft)."
    },
    "s": {
      "type": "number",
      "description": "Metres along the lane; negative while on the connector into it."
    },
    "speed": {
      "type": "number",
      "minimum": 0,
      "description": "Speed along the lane in m/s."
    },
    "boosted": {
      "description": "Lane speed includes the 4× travel boost.",
      "type": "boolean"
    },
    "cruise": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Vessel cruise limit in m/s."
    },
    "prev": {
      "type": "string",
      "description": "Previous lane (its connector leads onto `lane`)."
    },
    "next": {
      "type": "string",
      "description": "Chosen next lane."
    },
    "seed": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Per-agent seed for every random choice it makes."
    },
    "length": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Body length in metres."
    },
    "width": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Body width in metres."
    },
    "state": {
      "type": "string",
      "enum": [
        "move",
        "wait",
        "dwell",
        "idle"
      ],
      "description": "Moving, waiting (queue, signal, crossing), dwelling at a stop, or idling."
    },
    "since": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Tick the current state began."
    },
    "hops": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Lane transitions so far (routing draw stream)."
    },
    "hidden": {
      "type": "boolean",
      "description": "Inside a tunnel: simulated but not drawn."
    },
    "consist": {
      "type": "string",
      "description": "Train cars: the lead agent of the consist."
    },
    "carIndex": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Train cars: position behind the lead (1 = first)."
    },
    "offset": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Train cars: metres behind the lead's centre (default from carIndex)."
    },
    "trail": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Train leads: the lanes behind the lead, most recent first."
    },
    "served": {
      "type": "string",
      "description": "The last stop served (not stopped at again)."
    },
    "air": {
      "type": "object",
      "properties": {
        "x": {
          "type": "number",
          "description": "Corridor start X."
        },
        "z": {
          "type": "number",
          "description": "Corridor start Z."
        },
        "dx": {
          "type": "number",
          "description": "Unit heading X."
        },
        "dz": {
          "type": "number",
          "description": "Unit heading Z."
        },
        "y0": {
          "type": "number",
          "description": "Altitude at the start."
        },
        "y1": {
          "type": "number",
          "description": "Altitude at the end."
        },
        "length": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Corridor length in metres."
        }
      },
      "required": [
        "x",
        "z",
        "dx",
        "dz",
        "y0",
        "y1",
        "length"
      ],
      "additionalProperties": false,
      "description": "Aircraft: the straight corridor flown (s runs along it)."
    },
    "spawnedTick": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Tick the agent appeared (clients fade it in)."
    }
  },
  "required": [
    "kind",
    "type",
    "lane",
    "s",
    "speed",
    "seed",
    "length",
    "width",
    "state",
    "since",
    "hops",
    "spawnedTick"
  ],
  "additionalProperties": false
}

</details>

ambientObserver ​

Marks the entity ambient NPCs spawn around (usually the player or camera rig), with optional radius and density overrides.

Required: none

json
{}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "radius": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Override the car spawn radius in metres."
    },
    "despawnRadius": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Override the car despawn radius in metres."
    },
    "density": {
      "type": "number",
      "minimum": 0,
      "description": "Scale every class density (1 = default)."
    }
  },
  "additionalProperties": false
}

</details>

ambientRole ​

On an entity type: makes it an ambient NPC candidate (car, bus, rail car, aircraft, boat or ferry) with dimensions, speeds and spawn weight.

Required: role

json
{
  "role": "car",
  "cruise": 13,
  "max": 25
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "car",
        "bus",
        "rail",
        "aircraft",
        "boat",
        "ferry"
      ],
      "description": "Which ambient pool the type joins (buses drive with cars)."
    },
    "length": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Body length in metres (default from vehicle.spec)."
    },
    "width": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Body width in metres (default from vehicle.spec)."
    },
    "height": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Body height in metres (default from vehicle.spec)."
    },
    "cruise": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Preferred cruise speed in m/s."
    },
    "max": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Top speed in m/s."
    },
    "weight": {
      "type": "number",
      "minimum": 0,
      "description": "Relative spawn weight within its pool (default 1)."
    },
    "cars": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Rail: cars per consist (default 2)."
    },
    "track": {
      "type": "string",
      "enum": [
        "light",
        "heavy"
      ],
      "description": "Rail: tram and light-rail lines (light) or the rest (heavy); default any."
    },
    "consist": {
      "type": "object",
      "properties": {
        "units": {
          "type": "array",
          "prefixItems": [
            {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991
            }
          ],
          "items": false,
          "minItems": 2,
          "maxItems": 2,
          "description": "Copies of this type at the head, inclusive range (default [1, 1])."
        },
        "length": {
          "type": "array",
          "prefixItems": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            }
          ],
          "items": false,
          "minItems": 2,
          "maxItems": 2,
          "description": "Cars after the units, inclusive range."
        },
        "block": {
          "type": "array",
          "prefixItems": [
            {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991
            }
          ],
          "items": false,
          "minItems": 2,
          "maxItems": 2,
          "description": "Cars of one type in a row, inclusive range (default [1, 1])."
        },
        "cars": {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "minLength": 1,
                "description": "Car entity type id."
              },
              "weight": {
                "type": "number",
                "minimum": 0,
                "description": "Relative draw weight (default 1)."
              },
              "colors": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Paints this car picks from (#rrggbb)."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          "description": "The car pool."
        }
      },
      "required": [
        "length",
        "cars"
      ],
      "additionalProperties": false,
      "description": "Rail: a mixed train this type leads; supersedes cars."
    },
    "colors": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Paint colours spawned agents pick from (#rrggbb)."
    },
    "visual": {
      "type": "object",
      "properties": {
        "wheelNodes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Wheel nodes (their first child spins)."
        },
        "frontWheelNodes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Wheel nodes that steer."
        },
        "paintMaterial": {
          "type": "string",
          "description": "Material name tinted with the agent colour."
        },
        "wheelRadius": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Wheel radius in metres."
        },
        "wheelbase": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Axle spacing in metres."
        },
        "rotors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Aircraft: nodes spun about Z (fans, propellers)."
        },
        "gearNodes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Aircraft: landing gear shown on approach."
        }
      },
      "additionalProperties": false,
      "description": "How the model animates when drawn in full near the camera (types without a vehicle component)."
    }
  },
  "required": [
    "role"
  ],
  "additionalProperties": false
}

</details>

ambientState ​

Kernel-owned ambient bookkeeping on the $ambient entity: observer, spawn sequence and policy overrides.

Required: nextSeq, spawned, despawned

json
{
  "nextSeq": 12,
  "spawned": 12,
  "despawned": 3,
  "observer": {
    "pos": [
      0,
      0,
      0
    ],
    "setAtTick": 0
  }
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "observer": {
      "type": "object",
      "properties": {
        "pos": {
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "Observer position."
        },
        "forward": {
          "minItems": 2,
          "maxItems": 2,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "Unit view direction [x, z]; spawns avoid the view cone near it."
        },
        "entity": {
          "type": "string",
          "description": "Entity whose transform is the observer."
        },
        "setAtTick": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Tick the observer was last set."
        }
      },
      "required": [
        "setAtTick"
      ],
      "additionalProperties": false,
      "description": "Where agents spawn around."
    },
    "nextSeq": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Sequence number of the next spawned agent."
    },
    "spawned": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Agents spawned so far."
    },
    "despawned": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Agents removed so far."
    },
    "policy": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "$ref": "#/$defs/__schema0"
      },
      "description": "Policy overrides set by the ambient.policy command."
    }
  },
  "required": [
    "nextSeq",
    "spawned",
    "despawned"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

</details>

Owner: audio ​

audioEnvironment ​

Singleton soundscape rules: bus gains, ambience layers gated on weather/sky/listener signals, music playlist, event → sound mappings and listener footsteps.

Required: none

json
{
  "buses": {
    "music": 0.5
  },
  "ambience": [
    {
      "sound": "ambience.rain.medium",
      "when": {
        "weather.precipitation.kind": "rain"
      },
      "gainFrom": {
        "signal": "weather.precipitation.intensity",
        "curve": [
          [
            0,
            0
          ],
          [
            1,
            1
          ]
        ]
      }
    },
    {
      "sound": "ambience.birds.day",
      "when": {
        "sky.daylight": {
          "min": 0.3
        }
      },
      "fadeS": 4
    }
  ],
  "music": {
    "playlist": [
      "music.ambient.dawn"
    ],
    "mode": "sequence"
  },
  "events": {
    "crash": {
      "sound": "impact.metal.heavy"
    }
  },
  "footsteps": {
    "sound": "footstep.grass",
    "strideM": 0.75
  }
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "buses": {
      "description": "Bus gains (music, ambience, sfx, ui, voice, custom), default 1 each.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]*$"
      },
      "additionalProperties": {
        "type": "number",
        "minimum": 0,
        "maximum": 2
      }
    },
    "ambience": {
      "description": "Looping ambience layers, each active while its `when` holds.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sound": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$",
            "description": "Sound id from a molen/soundbank@1 document, e.g. \"ambience.rain.medium\"."
          },
          "when": {
            "type": "object",
            "propertyNames": {
              "type": "string",
              "minLength": 1
            },
            "additionalProperties": {
              "anyOf": [
                {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                {
                  "minItems": 1,
                  "type": "array",
                  "items": {
                    "type": [
                      "string",
                      "number",
                      "boolean"
                    ]
                  }
                },
                {
                  "type": "object",
                  "properties": {
                    "min": {
                      "description": "Inclusive lower bound.",
                      "type": "number"
                    },
                    "max": {
                      "description": "Inclusive upper bound.",
                      "type": "number"
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "exists": {
                      "type": "boolean",
                      "description": "true = the signal resolves to a value."
                    }
                  },
                  "required": [
                    "exists"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "description": "Conditions that must ALL hold, keyed by signal: a value (equality), a list (any of), {min,max} (inclusive range), or {exists}."
          },
          "gain": {
            "description": "Gain multiplier; default 1.",
            "type": "number",
            "minimum": 0,
            "maximum": 4
          },
          "gainFrom": {
            "description": "Drive gain from a signal, or from several whose curves multiply.",
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "signal": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Signal path: <component>.<field> on the entity (vehicleState.speed), or self.*, listener.*, weather.*, sky.*, time.*, host.*."
                  },
                  "curve": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "minItems": 2,
                      "maxItems": 2,
                      "type": "array",
                      "items": {
                        "type": "number"
                      }
                    },
                    "description": "Piecewise-linear [input, output] points, clamped at the ends."
                  },
                  "smoothS": {
                    "description": "Smoothing time constant in seconds; default 0.15.",
                    "type": "number",
                    "minimum": 0
                  }
                },
                "required": [
                  "signal",
                  "curve"
                ],
                "additionalProperties": false
              },
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "signal": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Signal path: <component>.<field> on the entity (vehicleState.speed), or self.*, listener.*, weather.*, sky.*, time.*, host.*."
                    },
                    "curve": {
                      "minItems": 1,
                      "type": "array",
                      "items": {
                        "minItems": 2,
                        "maxItems": 2,
                        "type": "array",
                        "items": {
                          "type": "number"
                        }
                      },
                      "description": "Piecewise-linear [input, output] points, clamped at the ends."
                    },
                    "smoothS": {
                      "description": "Smoothing time constant in seconds; default 0.15.",
                      "type": "number",
                      "minimum": 0
                    }
                  },
                  "required": [
                    "signal",
                    "curve"
                  ],
                  "additionalProperties": false
                }
              }
            ]
          },
          "pitchFrom": {
            "description": "Drive pitch from a signal, or from several whose curves multiply.",
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "signal": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Signal path: <component>.<field> on the entity (vehicleState.speed), or self.*, listener.*, weather.*, sky.*, time.*, host.*."
                  },
                  "curve": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "minItems": 2,
                      "maxItems": 2,
                      "type": "array",
                      "items": {
                        "type": "number"
                      }
                    },
                    "description": "Piecewise-linear [input, output] points, clamped at the ends."
                  },
                  "smoothS": {
                    "description": "Smoothing time constant in seconds; default 0.15.",
                    "type": "number",
                    "minimum": 0
                  }
                },
                "required": [
                  "signal",
                  "curve"
                ],
                "additionalProperties": false
              },
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "signal": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Signal path: <component>.<field> on the entity (vehicleState.speed), or self.*, listener.*, weather.*, sky.*, time.*, host.*."
                    },
                    "curve": {
                      "minItems": 1,
                      "type": "array",
                      "items": {
                        "minItems": 2,
                        "maxItems": 2,
                        "type": "array",
                        "items": {
                          "type": "number"
                        }
                      },
                      "description": "Piecewise-linear [input, output] points, clamped at the ends."
                    },
                    "smoothS": {
                      "description": "Smoothing time constant in seconds; default 0.15.",
                      "type": "number",
                      "minimum": 0
                    }
                  },
                  "required": [
                    "signal",
                    "curve"
                  ],
                  "additionalProperties": false
                }
              }
            ]
          },
          "fadeS": {
            "description": "Fade in/out time in seconds; default 1.5.",
            "type": "number",
            "minimum": 0
          }
        },
        "required": [
          "sound"
        ],
        "additionalProperties": false
      }
    },
    "music": {
      "description": "Background music; scripts switch it with molen.audio.music().",
      "type": "object",
      "properties": {
        "playlist": {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$",
            "description": "Sound id from a molen/soundbank@1 document, e.g. \"ambience.rain.medium\"."
          },
          "description": "Tracks, played on the music bus."
        },
        "mode": {
          "description": "Default sequence.",
          "type": "string",
          "enum": [
            "sequence",
            "shuffle"
          ]
        },
        "crossfadeS": {
          "description": "Crossfade between tracks; default 4.",
          "type": "number",
          "minimum": 0
        },
        "gain": {
          "description": "Music gain multiplier; default 1.",
          "type": "number",
          "minimum": 0,
          "maximum": 4
        },
        "when": {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "minLength": 1
          },
          "additionalProperties": {
            "anyOf": [
              {
                "type": [
                  "string",
                  "number",
                  "boolean"
                ]
              },
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                }
              },
              {
                "type": "object",
                "properties": {
                  "min": {
                    "description": "Inclusive lower bound.",
                    "type": "number"
                  },
                  "max": {
                    "description": "Inclusive upper bound.",
                    "type": "number"
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "exists": {
                    "type": "boolean",
                    "description": "true = the signal resolves to a value."
                  }
                },
                "required": [
                  "exists"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Conditions that must ALL hold, keyed by signal: a value (equality), a list (any of), {min,max} (inclusive range), or {exists}."
        }
      },
      "required": [
        "playlist"
      ],
      "additionalProperties": false
    },
    "events": {
      "description": "Engine/script event type → one-shot sound (e.g. \"crash\", \"delivery\").",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "sound": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$",
            "description": "Sound id from a molen/soundbank@1 document, e.g. \"ambience.rain.medium\"."
          },
          "at": {
            "description": "Where it plays: \"listener\" (2D) or \"payload.<field>\" naming an entity id or [x,y,z]. Default: payload.entity, payload.position, payload.a, else listener.",
            "type": "string"
          },
          "gain": {
            "type": "number",
            "minimum": 0,
            "maximum": 4
          },
          "pitch": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "bus": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]*$",
            "description": "Mixer bus: music, ambience, sfx, ui, voice, or a custom lowercase name."
          }
        },
        "required": [
          "sound"
        ],
        "additionalProperties": false
      }
    },
    "footsteps": {
      "description": "Listener footsteps from distance travelled (walk modes, first-person games).",
      "type": "object",
      "properties": {
        "sound": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$",
          "description": "Default footstep sound."
        },
        "surfaces": {
          "description": "listener.surface value → footstep sound (grass, concrete, wood…).",
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$",
            "description": "Sound id from a molen/soundbank@1 document, e.g. \"ambience.rain.medium\"."
          }
        },
        "strideM": {
          "description": "Meters per step; default 0.75.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "gain": {
          "description": "Footstep gain multiplier; default 1.",
          "type": "number",
          "minimum": 0,
          "maximum": 4
        },
        "when": {
          "description": "Default { \"listener.grounded\": true }.",
          "type": "object",
          "propertyNames": {
            "type": "string",
            "minLength": 1
          },
          "additionalProperties": {
            "anyOf": [
              {
                "type": [
                  "string",
                  "number",
                  "boolean"
                ]
              },
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                }
              },
              {
                "type": "object",
                "properties": {
                  "min": {
                    "description": "Inclusive lower bound.",
                    "type": "number"
                  },
                  "max": {
                    "description": "Inclusive upper bound.",
                    "type": "number"
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "exists": {
                    "type": "boolean",
                    "description": "true = the signal resolves to a value."
                  }
                },
                "required": [
                  "exists"
                ],
                "additionalProperties": false
              }
            ]
          }
        }
      },
      "required": [
        "sound"
      ],
      "additionalProperties": false
    },
    "listenerEntity": {
      "description": "Entity treated as the listener's body; <component>.<field> signals in ambience/music/footsteps resolve on it.",
      "type": "string"
    },
    "maxVoices": {
      "description": "Voice budget; default 32.",
      "type": "integer",
      "minimum": 1,
      "maximum": 256
    }
  },
  "additionalProperties": false
}

</details>

audioSource ​

Sound emitter on an entity: a sound-bank id, loop/autoplay, gain and pitch driven by signals (vehicleState.speed, listener.distance…), and one-shot triggers. Positional when the entity has a transform. Render-side only; see guide/audio.md.

Required: sound

json
{
  "sound": "vehicle.engine.car",
  "loop": true,
  "spatial": {
    "refDistance": 3,
    "maxDistance": 120
  },
  "pitchFrom": {
    "signal": "vehicleState.speed",
    "curve": [
      [
        0,
        0.8
      ],
      [
        30,
        1.7
      ]
    ]
  },
  "gainFrom": {
    "signal": "vehicleInput.throttle",
    "curve": [
      [
        0,
        0.45
      ],
      [
        1,
        1
      ]
    ]
  }
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sound": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$",
      "description": "Sound id from a molen/soundbank@1 document, e.g. \"ambience.rain.medium\"."
    },
    "loop": {
      "description": "Loop while active; default the sound's own loop flag.",
      "type": "boolean"
    },
    "autoplay": {
      "description": "Play when the entity exists and `when` holds; default true. false = only triggerFrom/startTick fire it.",
      "type": "boolean"
    },
    "gain": {
      "description": "Gain multiplier; default 1.",
      "type": "number",
      "minimum": 0,
      "maximum": 4
    },
    "pitch": {
      "description": "Playback-rate multiplier; default 1.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "bus": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Mixer bus: music, ambience, sfx, ui, voice, or a custom lowercase name."
    },
    "spatial": {
      "description": "Override the sound's spatial settings. Positional sources follow the entity's transform.",
      "anyOf": [
        {
          "type": "boolean",
          "const": false
        },
        {
          "type": "object",
          "properties": {
            "refDistance": {
              "description": "Distance in meters at which the sound plays at full gain; default 1.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "maxDistance": {
              "description": "Distance in meters beyond which the sound is culled; default 60.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "rolloff": {
              "description": "How fast gain falls off past refDistance; default 1.",
              "type": "number",
              "minimum": 0
            },
            "model": {
              "description": "Distance attenuation model (Web Audio PannerNode.distanceModel); default inverse.",
              "type": "string",
              "enum": [
                "linear",
                "inverse",
                "exponential"
              ]
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "when": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": [
              "string",
              "number",
              "boolean"
            ]
          },
          {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": [
                "string",
                "number",
                "boolean"
              ]
            }
          },
          {
            "type": "object",
            "properties": {
              "min": {
                "description": "Inclusive lower bound.",
                "type": "number"
              },
              "max": {
                "description": "Inclusive upper bound.",
                "type": "number"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "exists": {
                "type": "boolean",
                "description": "true = the signal resolves to a value."
              }
            },
            "required": [
              "exists"
            ],
            "additionalProperties": false
          }
        ]
      },
      "description": "Conditions that must ALL hold, keyed by signal: a value (equality), a list (any of), {min,max} (inclusive range), or {exists}."
    },
    "gainFrom": {
      "description": "Drive gain from a signal, or from several whose curves multiply.",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "signal": {
              "type": "string",
              "minLength": 1,
              "description": "Signal path: <component>.<field> on the entity (vehicleState.speed), or self.*, listener.*, weather.*, sky.*, time.*, host.*."
            },
            "curve": {
              "minItems": 1,
              "type": "array",
              "items": {
                "minItems": 2,
                "maxItems": 2,
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              "description": "Piecewise-linear [input, output] points, clamped at the ends."
            },
            "smoothS": {
              "description": "Smoothing time constant in seconds; default 0.15.",
              "type": "number",
              "minimum": 0
            }
          },
          "required": [
            "signal",
            "curve"
          ],
          "additionalProperties": false
        },
        {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "signal": {
                "type": "string",
                "minLength": 1,
                "description": "Signal path: <component>.<field> on the entity (vehicleState.speed), or self.*, listener.*, weather.*, sky.*, time.*, host.*."
              },
              "curve": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "minItems": 2,
                  "maxItems": 2,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                "description": "Piecewise-linear [input, output] points, clamped at the ends."
              },
              "smoothS": {
                "description": "Smoothing time constant in seconds; default 0.15.",
                "type": "number",
                "minimum": 0
              }
            },
            "required": [
              "signal",
              "curve"
            ],
            "additionalProperties": false
          }
        }
      ]
    },
    "pitchFrom": {
      "description": "Drive pitch from a signal, or from several whose curves multiply.",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "signal": {
              "type": "string",
              "minLength": 1,
              "description": "Signal path: <component>.<field> on the entity (vehicleState.speed), or self.*, listener.*, weather.*, sky.*, time.*, host.*."
            },
            "curve": {
              "minItems": 1,
              "type": "array",
              "items": {
                "minItems": 2,
                "maxItems": 2,
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              "description": "Piecewise-linear [input, output] points, clamped at the ends."
            },
            "smoothS": {
              "description": "Smoothing time constant in seconds; default 0.15.",
              "type": "number",
              "minimum": 0
            }
          },
          "required": [
            "signal",
            "curve"
          ],
          "additionalProperties": false
        },
        {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "signal": {
                "type": "string",
                "minLength": 1,
                "description": "Signal path: <component>.<field> on the entity (vehicleState.speed), or self.*, listener.*, weather.*, sky.*, time.*, host.*."
              },
              "curve": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "minItems": 2,
                  "maxItems": 2,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                "description": "Piecewise-linear [input, output] points, clamped at the ends."
              },
              "smoothS": {
                "description": "Smoothing time constant in seconds; default 0.15.",
                "type": "number",
                "minimum": 0
              }
            },
            "required": [
              "signal",
              "curve"
            ],
            "additionalProperties": false
          }
        }
      ]
    },
    "triggerFrom": {
      "description": "Fire one-shots from a signal (footsteps from distance, clicks on change).",
      "type": "object",
      "properties": {
        "signal": {
          "type": "string",
          "minLength": 1,
          "description": "Signal to watch (see signal paths)."
        },
        "every": {
          "description": "Fire each time the signal advances by this much (odometer-style, e.g. meters).",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "onChange": {
          "description": "Fire whenever the signal value changes.",
          "type": "boolean"
        },
        "sound": {
          "description": "Sound to fire; default the source's own sound.",
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$"
        }
      },
      "required": [
        "signal"
      ],
      "additionalProperties": false
    },
    "startTick": {
      "description": "Play once at this tick; changing it retriggers (like renderable.animation).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "sound"
  ],
  "additionalProperties": false
}

</details>

audioZone ​

Area ambience: a looping sound that fades in as the listener enters a sphere or box around the entity (a waterfall, a machine room, a market).

Required: sound, shape

json
{
  "sound": "ambience.water.stream",
  "shape": {
    "kind": "sphere",
    "radius": 12
  },
  "fade": 8
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sound": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_-]*(\\.[a-z0-9][a-z0-9_-]*)*$",
      "description": "Looping ambience played while the listener is inside the zone."
    },
    "shape": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "sphere",
              "description": "Sphere around the entity."
            },
            "radius": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Radius in meters."
            }
          },
          "required": [
            "kind",
            "radius"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "box",
              "description": "Axis-aligned box around the entity."
            },
            "halfExtents": {
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "Half sizes [x, y, z] in meters, axis-aligned."
            }
          },
          "required": [
            "kind",
            "halfExtents"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Zone volume, centered on the entity's transform."
    },
    "fade": {
      "description": "Meters outside the shape over which gain fades to zero; default 5.",
      "type": "number",
      "minimum": 0
    },
    "gain": {
      "description": "Gain multiplier; default 1.",
      "type": "number",
      "minimum": 0,
      "maximum": 4
    },
    "bus": {
      "description": "Default ambience.",
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "when": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": [
              "string",
              "number",
              "boolean"
            ]
          },
          {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": [
                "string",
                "number",
                "boolean"
              ]
            }
          },
          {
            "type": "object",
            "properties": {
              "min": {
                "description": "Inclusive lower bound.",
                "type": "number"
              },
              "max": {
                "description": "Inclusive upper bound.",
                "type": "number"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "exists": {
                "type": "boolean",
                "description": "true = the signal resolves to a value."
              }
            },
            "required": [
              "exists"
            ],
            "additionalProperties": false
          }
        ]
      },
      "description": "Conditions that must ALL hold, keyed by signal: a value (equality), a list (any of), {min,max} (inclusive range), or {exists}."
    }
  },
  "required": [
    "sound",
    "shape"
  ],
  "additionalProperties": false
}

</details>

Owner: client ​

environment ​

Singleton scene environment: optional Earth/custom sky, ambient/sun lighting, background, fog, tone mapping, shadow quality tier.

Required: none

json
{
  "ambient": {
    "sky": "#ffffff",
    "ground": "#444455",
    "intensity": 1.1
  },
  "sun": {
    "direction": [
      5,
      10,
      7
    ],
    "intensity": 1.4,
    "castShadow": true
  },
  "shadows": "medium"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sky": {
      "description": "Clear sky with sun, moon, stars and automatic lighting. Earth mode uses an explicit UTC epoch and observer; custom mode accepts authored body directions. See guide/sky.md.",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "palette": {
              "description": "Art-directed clear-sky colors. These control the sky dome, not distance fog or weather.",
              "type": "object",
              "properties": {
                "dayZenith": {
                  "description": "Daytime overhead color, default #2374c5.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "dayHorizon": {
                  "description": "Daytime horizon and ambient light color, default #b8d7eb.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "twilight": {
                  "description": "Twilight glow and low Sun color, default #f78753.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "nightZenith": {
                  "description": "Nighttime overhead color, default #020510.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "nightHorizon": {
                  "description": "Nighttime horizon and ambient light color, default #121c32.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "ground": {
                  "description": "Below-horizon dome and ground ambient color, default #18212c.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "sun": {
                  "description": "Sun disk and high-altitude sunlight color, default #fff4dc.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "moon": {
                  "description": "Moon surface and moonlight color, default #dae5f5.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                }
              },
              "additionalProperties": false
            },
            "lighting": {
              "description": "Sky-managed lights replace environment.ambient and environment.sun when sky is enabled.",
              "type": "object",
              "properties": {
                "sunIntensity": {
                  "description": "Peak directional sunlight, default 3.",
                  "type": "number",
                  "minimum": 0
                },
                "moonIntensity": {
                  "description": "Full-moon directional light, default 0.12; scaled by phase and altitude.",
                  "type": "number",
                  "minimum": 0
                },
                "dayAmbient": {
                  "description": "Daytime hemisphere intensity, default 0.6.",
                  "type": "number",
                  "minimum": 0
                },
                "nightAmbient": {
                  "description": "Nighttime hemisphere intensity, default 0.025.",
                  "type": "number",
                  "minimum": 0
                },
                "skyLightSaturation": {
                  "description": "Saturation of the light the sky casts (fill and reflections) relative to the dome colors: 1 (default) lights with the dome palette, lower values toward its luminance. A saturated zenith otherwise tints every surface in shade blue.",
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "referenceElevation": {
                  "description": "Sun elevation in degrees whose sunlit-ground brightness is kept as the sun climbs higher: above it, sun and sky light scale down together so a level surface in sun receives the same light, as a camera adapts its exposure. Omit for constant light, which renders midday ground brighter than its authored color.",
                  "type": "number",
                  "minimum": 1,
                  "maximum": 90
                },
                "castShadow": {
                  "description": "Sun shadows; also requires environment.shadows. Default true.",
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            },
            "dome": {
              "description": "Sky dome drawing. Filmic tone mapping renders a physically bright clear sky pale; below 1 deepens it.",
              "type": "object",
              "properties": {
                "brightness": {
                  "description": "Multiplier on the drawn dome color, default 1. Lighting and reflections keep the palette.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 4
                }
              },
              "additionalProperties": false
            },
            "stars": {
              "description": "Star catalog visibility, brightness and size.",
              "type": "object",
              "properties": {
                "enabled": {
                  "description": "Show the star catalog, default true.",
                  "type": "boolean"
                },
                "magnitudeLimit": {
                  "description": "Faintest catalog magnitude rendered, default 6.",
                  "type": "number",
                  "minimum": -2,
                  "maximum": 6.5
                },
                "intensity": {
                  "description": "Star brightness multiplier, default 1; fades with daylight and moonlight.",
                  "type": "number",
                  "minimum": 0
                },
                "size": {
                  "description": "Visual angular-size multiplier, default 1.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 10
                }
              },
              "additionalProperties": false
            },
            "sun": {
              "description": "Sun disk appearance.",
              "type": "object",
              "properties": {
                "visible": {
                  "description": "Show the Sun disk; lighting is independent. Default true.",
                  "type": "boolean"
                },
                "size": {
                  "description": "Visual diameter multiplier, default 1. Does not affect astronomy or lighting.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 100
                }
              },
              "additionalProperties": false
            },
            "moon": {
              "description": "Moon disk appearance.",
              "type": "object",
              "properties": {
                "visible": {
                  "description": "Show the Moon disk; lighting is independent. Default true.",
                  "type": "boolean"
                },
                "size": {
                  "description": "Visual diameter multiplier, default 1.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 100
                },
                "earthshine": {
                  "description": "Dark-side visibility, default 0.025.",
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                }
              },
              "additionalProperties": false
            },
            "mode": {
              "type": "string",
              "const": "earth",
              "description": "Compute positions from an Earth observer and UTC clock."
            },
            "observer": {
              "type": "object",
              "properties": {
                "latitude": {
                  "type": "number",
                  "minimum": -90,
                  "maximum": 90,
                  "description": "Geodetic degrees north."
                },
                "longitude": {
                  "type": "number",
                  "minimum": -180,
                  "maximum": 180,
                  "description": "Degrees east; west is negative."
                },
                "elevation": {
                  "description": "Meters above sea level, default 0; used for lunar parallax.",
                  "type": "number",
                  "minimum": -500,
                  "maximum": 100000
                },
                "northOffsetDeg": {
                  "description": "Rotate geographic north clockwise toward +X, default 0 (-Z north).",
                  "type": "number"
                }
              },
              "required": [
                "latitude",
                "longitude"
              ],
              "additionalProperties": false,
              "description": "Geographic observing position and world orientation."
            },
            "time": {
              "type": "object",
              "properties": {
                "epochMs": {
                  "type": "number",
                  "minimum": -2208988800000,
                  "maximum": 4133980799999,
                  "description": "UTC Unix milliseconds at simulation second zero (1900–2100). Explicit: never reads the host clock."
                },
                "scale": {
                  "description": "Sky seconds per simulation second, default 1. Zero freezes, negative rewinds.",
                  "type": "number"
                }
              },
              "required": [
                "epochMs"
              ],
              "additionalProperties": false,
              "description": "UTC epoch and rate relative to simulation time."
            }
          },
          "required": [
            "mode",
            "observer",
            "time"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "palette": {
              "description": "Art-directed clear-sky colors. These control the sky dome, not distance fog or weather.",
              "type": "object",
              "properties": {
                "dayZenith": {
                  "description": "Daytime overhead color, default #2374c5.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "dayHorizon": {
                  "description": "Daytime horizon and ambient light color, default #b8d7eb.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "twilight": {
                  "description": "Twilight glow and low Sun color, default #f78753.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "nightZenith": {
                  "description": "Nighttime overhead color, default #020510.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "nightHorizon": {
                  "description": "Nighttime horizon and ambient light color, default #121c32.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "ground": {
                  "description": "Below-horizon dome and ground ambient color, default #18212c.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "sun": {
                  "description": "Sun disk and high-altitude sunlight color, default #fff4dc.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "moon": {
                  "description": "Moon surface and moonlight color, default #dae5f5.",
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                }
              },
              "additionalProperties": false
            },
            "lighting": {
              "description": "Sky-managed lights replace environment.ambient and environment.sun when sky is enabled.",
              "type": "object",
              "properties": {
                "sunIntensity": {
                  "description": "Peak directional sunlight, default 3.",
                  "type": "number",
                  "minimum": 0
                },
                "moonIntensity": {
                  "description": "Full-moon directional light, default 0.12; scaled by phase and altitude.",
                  "type": "number",
                  "minimum": 0
                },
                "dayAmbient": {
                  "description": "Daytime hemisphere intensity, default 0.6.",
                  "type": "number",
                  "minimum": 0
                },
                "nightAmbient": {
                  "description": "Nighttime hemisphere intensity, default 0.025.",
                  "type": "number",
                  "minimum": 0
                },
                "skyLightSaturation": {
                  "description": "Saturation of the light the sky casts (fill and reflections) relative to the dome colors: 1 (default) lights with the dome palette, lower values toward its luminance. A saturated zenith otherwise tints every surface in shade blue.",
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "referenceElevation": {
                  "description": "Sun elevation in degrees whose sunlit-ground brightness is kept as the sun climbs higher: above it, sun and sky light scale down together so a level surface in sun receives the same light, as a camera adapts its exposure. Omit for constant light, which renders midday ground brighter than its authored color.",
                  "type": "number",
                  "minimum": 1,
                  "maximum": 90
                },
                "castShadow": {
                  "description": "Sun shadows; also requires environment.shadows. Default true.",
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            },
            "dome": {
              "description": "Sky dome drawing. Filmic tone mapping renders a physically bright clear sky pale; below 1 deepens it.",
              "type": "object",
              "properties": {
                "brightness": {
                  "description": "Multiplier on the drawn dome color, default 1. Lighting and reflections keep the palette.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 4
                }
              },
              "additionalProperties": false
            },
            "stars": {
              "description": "Star catalog visibility, brightness and size.",
              "type": "object",
              "properties": {
                "enabled": {
                  "description": "Show the star catalog, default true.",
                  "type": "boolean"
                },
                "magnitudeLimit": {
                  "description": "Faintest catalog magnitude rendered, default 6.",
                  "type": "number",
                  "minimum": -2,
                  "maximum": 6.5
                },
                "intensity": {
                  "description": "Star brightness multiplier, default 1; fades with daylight and moonlight.",
                  "type": "number",
                  "minimum": 0
                },
                "size": {
                  "description": "Visual angular-size multiplier, default 1.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 10
                }
              },
              "additionalProperties": false
            },
            "sun": {
              "description": "Sun disk appearance.",
              "type": "object",
              "properties": {
                "visible": {
                  "description": "Show the Sun disk; lighting is independent. Default true.",
                  "type": "boolean"
                },
                "size": {
                  "description": "Visual diameter multiplier, default 1. Does not affect astronomy or lighting.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 100
                }
              },
              "additionalProperties": false
            },
            "moon": {
              "description": "Moon disk appearance.",
              "type": "object",
              "properties": {
                "visible": {
                  "description": "Show the Moon disk; lighting is independent. Default true.",
                  "type": "boolean"
                },
                "size": {
                  "description": "Visual diameter multiplier, default 1.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 100
                },
                "earthshine": {
                  "description": "Dark-side visibility, default 0.025.",
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                }
              },
              "additionalProperties": false
            },
            "mode": {
              "type": "string",
              "const": "custom",
              "description": "Use authored body positions without an Earth clock."
            },
            "sunBody": {
              "type": "object",
              "properties": {
                "direction": {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  },
                  "description": "Nonzero direction toward the body; +X east, +Y up, -Z north. Normalized by the renderer."
                },
                "angularDiameterDeg": {
                  "description": "Apparent diameter in degrees; default 0.53.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 90
                }
              },
              "required": [
                "direction"
              ],
              "additionalProperties": false,
              "description": "Authored sun position and apparent diameter."
            },
            "moonBody": {
              "description": "Moon lit from sunBody.direction; omit for a moonless world.",
              "type": "object",
              "properties": {
                "direction": {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  },
                  "description": "Nonzero direction toward the body; +X east, +Y up, -Z north. Normalized by the renderer."
                },
                "angularDiameterDeg": {
                  "description": "Apparent diameter in degrees; default 0.53.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 90
                }
              },
              "required": [
                "direction"
              ],
              "additionalProperties": false
            },
            "starRotationDeg": {
              "description": "XYZ Euler rotation in degrees of the catalog sphere; default [0,0,0].",
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              }
            }
          },
          "required": [
            "mode",
            "sunBody"
          ],
          "additionalProperties": false
        }
      ]
    },
    "ambient": {
      "type": "object",
      "properties": {
        "sky": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Sky-side (from above) ambient color '#rrggbb'."
        },
        "ground": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Ground-side (from below) ambient color '#rrggbb'."
        },
        "intensity": {
          "type": "number",
          "minimum": 0,
          "description": "Ambient intensity (unitless multiplier; default 1.1)."
        }
      },
      "additionalProperties": false,
      "description": "Hemisphere ambient light."
    },
    "sun": {
      "type": "object",
      "properties": {
        "direction": {
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "Vector [x, y, z] pointing FROM the world origin TOWARD the sun: the directional light is placed at this offset and shines back toward the origin, so y > 0 puts the sun above the horizon (Y-up). Default [5, 10, 7]."
        },
        "color": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Sun light color '#rrggbb'."
        },
        "intensity": {
          "type": "number",
          "minimum": 0,
          "description": "Sun intensity (unitless multiplier; default 1.4)."
        },
        "castShadow": {
          "type": "boolean",
          "description": "Whether the sun casts shadows (also requires shadows != 'off')."
        }
      },
      "additionalProperties": false,
      "description": "Directional sun light."
    },
    "background": {
      "type": "string",
      "pattern": "^#[0-9a-fA-F]{6}$",
      "description": "Background clear color '#rrggbb'."
    },
    "fog": {
      "type": "object",
      "properties": {
        "color": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Fog color '#rrggbb'."
        },
        "near": {
          "type": "number",
          "minimum": 0,
          "description": "Distance from the camera in meters at which fog starts."
        },
        "far": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Distance from the camera in meters at which fog is fully opaque."
        }
      },
      "required": [
        "color"
      ],
      "additionalProperties": false,
      "description": "Linear distance fog."
    },
    "toneMapping": {
      "type": "string",
      "enum": [
        "none",
        "aces",
        "agx",
        "neutral"
      ],
      "description": "Tone-mapping operator: none, aces, agx, or neutral (Khronos PBR Neutral: keeps authored base colors and saturation below the highlights)."
    },
    "exposure": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Tone-mapping exposure multiplier (1 = neutral)."
    },
    "shadows": {
      "type": "string",
      "enum": [
        "off",
        "low",
        "medium",
        "high"
      ],
      "description": "Shadow quality tier (shadow-map resolution); off disables all shadows."
    }
  },
  "additionalProperties": false
}

</details>

light ​

A light source at the entity transform (directional/point/spot).

Required: type

json
{
  "type": "point",
  "color": "#ffdca8",
  "intensity": 2,
  "range": 12
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "directional",
        "point",
        "spot"
      ],
      "description": "Light type: directional (parallel rays), point (omnidirectional), or spot (cone). Directional/spot lights aim at the world origin by default."
    },
    "color": {
      "type": "string",
      "pattern": "^#[0-9a-fA-F]{6}$",
      "description": "Light color as '#rrggbb'."
    },
    "intensity": {
      "type": "number",
      "minimum": 0,
      "description": "Light intensity (three.js units; a unitless multiplier)."
    },
    "range": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "point/spot falloff distance in meters (absent = unlimited)."
    },
    "angleDeg": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "spot cone half-angle in degrees, measured from the aim direction (default 45)."
    },
    "penumbra": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "spot soft-edge fraction 0..1 of the cone (default 0 = hard edge)."
    },
    "castShadow": {
      "type": "boolean",
      "description": "Whether this light casts shadows."
    }
  },
  "required": [
    "type"
  ],
  "additionalProperties": false
}

</details>

livery ​

Reusable model paint slots, bound surface markings and selectable liveries. Visual only.

Required: selected, slots, variants

json
{
  "selected": "red",
  "slots": {
    "body": {
      "materials": [
        "body-paint"
      ]
    }
  },
  "variants": [
    {
      "id": "red",
      "label": "Red",
      "provenance": {
        "kind": "original",
        "note": "Original paint.",
        "references": []
      },
      "paints": {
        "body": {
          "color": "#b8463d"
        }
      }
    }
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "selected": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Selected variant id; patch only this field to change the livery."
    },
    "slots": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "materials": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Exact glTF material names belonging to this paint region."
          },
          "node": {
            "description": "Optional named glTF subtree restricting this region.",
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        },
        "required": [
          "materials"
        ],
        "additionalProperties": false
      },
      "description": "Stable paint regions bound to named model materials."
    },
    "anchors": {
      "description": "Reusable marking projectors attached to model paint regions.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "slot": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Paint region receiving the projected marking."
          },
          "position": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number"
              },
              {
                "type": "number"
              },
              {
                "type": "number"
              }
            ],
            "items": false,
            "minItems": 3,
            "maxItems": 3,
            "description": "Projector center as fractions of the region bounds, measured from their minimum corner."
          },
          "size": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 4
              },
              {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 4
              },
              {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 4
              }
            ],
            "items": false,
            "minItems": 3,
            "maxItems": 3,
            "description": "Projector width, height and depth as fractions of the longest region dimension."
          },
          "rotation": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number"
              },
              {
                "type": "number"
              },
              {
                "type": "number"
              }
            ],
            "items": false,
            "minItems": 3,
            "maxItems": 3,
            "description": "XYZ Euler rotation in radians; local positive Z points out of the surface."
          }
        },
        "required": [
          "slot",
          "position",
          "size",
          "rotation"
        ],
        "additionalProperties": false
      }
    },
    "variants": {
      "minItems": 1,
      "maxItems": 64,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Stable identifier used by selected."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Display name for this livery."
          },
          "provenance": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "photo",
                  "inspired",
                  "original"
                ],
                "description": "Whether the appearance is photograph verified, reference inspired or an original design."
              },
              "note": {
                "type": "string",
                "minLength": 1,
                "description": "Attribution, verification scope and any deliberate approximations."
              },
              "references": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Human-readable reference title."
                    },
                    "url": {
                      "type": "string",
                      "pattern": "^https?:\\/\\/[^\\s]+$",
                      "description": "HTTP or HTTPS source URL."
                    }
                  },
                  "required": [
                    "title",
                    "url"
                  ],
                  "additionalProperties": false
                },
                "description": "Public references supporting the appearance; required for photo and inspired designs."
              }
            },
            "required": [
              "kind",
              "note",
              "references"
            ],
            "additionalProperties": false,
            "description": "Evidence and authorship for the appearance."
          },
          "paints": {
            "type": "object",
            "propertyNames": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "color": {
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$",
                  "description": "Base paint color as an sRGB hex triplet."
                },
                "roughness": {
                  "description": "Optional material roughness override.",
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "metalness": {
                  "description": "Optional material metalness override.",
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "camouflage": {
                  "description": "Optional camouflage projected in model space without changing authored UVs.",
                  "type": "object",
                  "properties": {
                    "colors": {
                      "minItems": 2,
                      "maxItems": 4,
                      "type": "array",
                      "items": {
                        "type": "string",
                        "pattern": "^#[0-9a-fA-F]{6}$"
                      },
                      "description": "Two to four colors for deterministic camouflage patches."
                    },
                    "scale": {
                      "type": "number",
                      "exclusiveMinimum": 0,
                      "maximum": 100,
                      "description": "Pattern repetitions across the longest paint-region dimension."
                    },
                    "seed": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 4294967295,
                      "description": "Unsigned deterministic pattern seed."
                    }
                  },
                  "required": [
                    "colors",
                    "scale",
                    "seed"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "color"
              ],
              "additionalProperties": false
            },
            "description": "Paint overrides keyed by stable paint-region name; omitted regions retain their authored appearance."
          },
          "markings": {
            "description": "Surface markings to project for this variant.",
            "maxItems": 32,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "anchor": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "description": "Reusable model marking anchor."
                },
                "graphic": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "description": "Optional descriptive label; rendered lettering belongs in the polygon artwork.",
                      "type": "string",
                      "maxLength": 256
                    },
                    "shapes": {
                      "minItems": 1,
                      "maxItems": 4096,
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "color": {
                            "type": "string",
                            "pattern": "^#[0-9a-fA-F]{6}$",
                            "description": "Flat polygon color as an sRGB hex triplet."
                          },
                          "points": {
                            "minItems": 3,
                            "maxItems": 512,
                            "type": "array",
                            "items": {
                              "type": "array",
                              "prefixItems": [
                                {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1
                                },
                                {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1
                                }
                              ],
                              "items": false,
                              "minItems": 2,
                              "maxItems": 2
                            },
                            "description": "Polygon vertices in normalized 0–1 coordinates with positive Y upward."
                          }
                        },
                        "required": [
                          "color",
                          "points"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Original flat artwork polygons, painted in order."
                    }
                  },
                  "required": [
                    "shapes"
                  ],
                  "additionalProperties": false,
                  "description": "Resolution-independent artwork rasterized for the surface projector."
                }
              },
              "required": [
                "anchor",
                "graphic"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "id",
          "label",
          "provenance",
          "paints"
        ],
        "additionalProperties": false
      },
      "description": "Available livery recipes for this model."
    }
  },
  "required": [
    "selected",
    "slots",
    "variants"
  ],
  "additionalProperties": false
}

</details>

model.signals ​

Bind same-entity simulation fields and named numeric expressions to GLB transforms and visibility. Supports calibration, cyclic needles and timed response. Visual only; no physics writes.

Required: sources, bindings

json
{
  "sources": {
    "speed": {
      "component": "vehicleState",
      "path": [
        "speed"
      ]
    }
  },
  "derived": {
    "speedKmh": {
      "op": "multiply",
      "args": [
        "speed",
        3.6
      ]
    }
  },
  "bindings": [
    {
      "node": "speed-pointer",
      "source": "speedKmh",
      "property": "rotation",
      "axis": "z",
      "keys": [
        [
          0,
          -2
        ],
        [
          60,
          0
        ],
        [
          180,
          2
        ]
      ],
      "responseSeconds": 0.2
    }
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sources": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "component": {
            "type": "string",
            "minLength": 1,
            "description": "Component on this same entity."
          },
          "path": {
            "minItems": 1,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1
                },
                {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                }
              ]
            },
            "description": "Explicit property names or array indices leading to a number or boolean."
          }
        },
        "required": [
          "component",
          "path"
        ],
        "additionalProperties": false
      },
      "description": "Named signals read from same-entity component fields."
    },
    "bindings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "node": {
            "type": "string",
            "minLength": 1,
            "description": "Exact loaded GLB node name."
          },
          "source": {
            "type": "string",
            "minLength": 1,
            "description": "Named simulation signal."
          },
          "property": {
            "type": "string",
            "enum": [
              "rotation",
              "position",
              "visible"
            ],
            "description": "Local transform or visibility channel."
          },
          "axis": {
            "description": "Required for transforms; omit for visible.",
            "type": "string",
            "enum": [
              "x",
              "y",
              "z"
            ]
          },
          "scale": {
            "description": "Multiply the signal by this value. Supply this or keys.",
            "type": "number"
          },
          "offset": {
            "description": "Offset after scaling; default zero.",
            "type": "number"
          },
          "keys": {
            "description": "Keyframed curve of [signal, displacement] pairs, signals strictly ascending; holds the end values outside them. Supply this or scale.",
            "minItems": 2,
            "type": "array",
            "items": {
              "type": "array",
              "prefixItems": [
                {
                  "type": "number"
                },
                {
                  "type": "number"
                }
              ],
              "items": false,
              "minItems": 2,
              "maxItems": 2
            }
          },
          "ease": {
            "description": "Interpolation between keys: linear (default), or smooth to ease out of and into every key.",
            "type": "string",
            "enum": [
              "linear",
              "smooth"
            ]
          },
          "min": {
            "description": "Minimum displacement from authored pose.",
            "type": "number"
          },
          "max": {
            "description": "Maximum displacement from authored pose.",
            "type": "number"
          },
          "period": {
            "description": "Rotation output wraps to [0, period); smoothing follows the shortest arc. Cannot combine with min/max.",
            "type": "number",
            "exclusiveMinimum": 0
          },
          "responseSeconds": {
            "description": "First-order response time constant in simulation seconds; default zero. Requires a timestamp from the host.",
            "type": "number",
            "minimum": 0
          },
          "missing": {
            "description": "Missing reading: hold last pose (default), restore authored pose, or hide a visible channel.",
            "type": "string",
            "enum": [
              "hold",
              "rest",
              "hide"
            ]
          }
        },
        "required": [
          "node",
          "source",
          "property"
        ],
        "additionalProperties": false
      },
      "description": "Per-model node channels and their signal calibration."
    },
    "derived": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "op": {
            "type": "string",
            "enum": [
              "add",
              "subtract",
              "multiply",
              "divide",
              "min",
              "max",
              "clamp",
              "abs",
              "sqrt",
              "floor",
              "modulo",
              "sin",
              "cos",
              "atan2",
              "less",
              "greater",
              "equal",
              "and",
              "or",
              "not",
              "if",
              "coalesce"
            ],
            "description": "Numeric operation; comparisons/logic return 0 or 1. Angles are radians."
          },
          "args": {
            "minItems": 1,
            "maxItems": 16,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "string",
                  "minLength": 1
                }
              ]
            },
            "description": "Finite numeric literals or names of signals, in operand order."
          }
        },
        "required": [
          "op",
          "args"
        ],
        "additionalProperties": false
      },
      "description": "Up to 256 named data-only formulas, evaluated in dependency order. No cycles."
    }
  },
  "required": [
    "sources",
    "bindings"
  ],
  "additionalProperties": false
}

</details>

renderable ​

Client render contract: a primitive, a gltf asset (by project asset id) with optional sub-node, material override, shadows, and clip playback, or a capability-registered kind.

Required: kind, ref

json
{
  "kind": "primitive",
  "ref": "box",
  "materialRef": "palette:#4363d8"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "primitive",
        "gltf",
        "ambient-vehicle",
        "figure"
      ],
      "description": "Render source: 'primitive' (built-in geometry named by ref), 'gltf' (an imported project asset), 'ambient-vehicle' (an ambient NPC vehicle: an instanced proxy from its `ambientAgent` dimensions, or the content model named by `ref` near the camera), 'figure' (a procedural skinned figure body from the entity `figure` component)."
    },
    "ref": {
      "type": "string",
      "minLength": 1,
      "description": "Primitive name (box, sphere, plane, cylinder) or, for gltf, the project asset id."
    },
    "materialRef": {
      "type": "string",
      "description": "Material reference, e.g. 'palette:#rrggbb' or a project material doc id; overrides the asset's own materials."
    },
    "primitive": {
      "type": "object",
      "properties": {
        "size": {
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "Primitive extents [x, y, z] in meters: box = full extents; sphere = x is the diameter; cylinder = x diameter, y height; plane = x by z. Default [1, 1, 1]."
        }
      },
      "additionalProperties": false,
      "description": "Primitive geometry parameters (kind = primitive)."
    },
    "node": {
      "type": "string",
      "minLength": 1,
      "description": "gltf: named sub-node of the asset to instance (default: the whole scene)."
    },
    "visible": {
      "type": "boolean",
      "description": "Whether the object is drawn; default true."
    },
    "shadows": {
      "type": "object",
      "properties": {
        "cast": {
          "type": "boolean",
          "description": "Whether this object casts shadows onto others."
        },
        "receive": {
          "type": "boolean",
          "description": "Whether this object receives shadows from others."
        }
      },
      "additionalProperties": false,
      "description": "Shadow participation flags."
    },
    "animation": {
      "type": "object",
      "properties": {
        "clip": {
          "type": "string",
          "minLength": 1,
          "description": "Name of the glTF animation clip to play."
        },
        "speed": {
          "type": "number",
          "description": "Playback rate multiplier (1 = authored speed)."
        },
        "loop": {
          "type": "string",
          "enum": [
            "repeat",
            "once",
            "pingpong"
          ],
          "description": "Loop mode: repeat, once (hold the last frame), or pingpong."
        },
        "paused": {
          "type": "boolean",
          "description": "Freeze playback at pausedAtTick (default startTick)."
        },
        "pausedAtTick": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Simulation tick to hold while paused; serialize this when pausing so live and captured poses agree."
        },
        "startTick": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Tick the clip started at; clip time = (tick - startTick) / tickRate * speed seconds (default 0)."
        }
      },
      "required": [
        "clip"
      ],
      "additionalProperties": false,
      "description": "gltf clip playback (client-owned); clip time derives deterministically from startTick."
    },
    "lod": {
      "anyOf": [
        {
          "type": "string",
          "const": "auto"
        },
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        }
      ],
      "description": "Figure body detail tier: 0 (full), 1 (medium), 2 (far), or \"auto\" to pick by distance."
    }
  },
  "required": [
    "kind",
    "ref"
  ],
  "additionalProperties": false
}

</details>

Owner: content ​

health ​

Common gameplay hit-points component.

Required: hp

json
{
  "hp": 100
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "hp": {
      "type": "number",
      "description": "Hit points."
    }
  },
  "required": [
    "hp"
  ],
  "additionalProperties": {}
}

</details>

tag ​

Named tag for selecting/grouping entities (e.g. tag.name === "enemy").

Required: name

json
{
  "name": "enemy"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Tag name used for selecting/grouping entities, e.g. 'enemy'."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": {}
}

</details>

Owner: figures ​

figure ​

What a figure is: a preset plus descriptor overrides (height, build, proportions, features, palette) and how it faces its motion. Pair with renderable.kind "figure".

Required: preset

json
{
  "preset": "human.adult",
  "height": 1.7,
  "palette": {
    "top": "#3b6ea5",
    "bottom": "#2f2f38"
  }
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "preset": {
      "type": "string",
      "enum": [
        "human.adult",
        "human.child",
        "human.elder",
        "dog",
        "cat",
        "horse",
        "deer",
        "cow",
        "sheep"
      ],
      "description": "Preset the descriptor starts from, e.g. 'human.adult' or 'horse'."
    },
    "height": {
      "type": "number",
      "minimum": 0.2,
      "maximum": 4,
      "description": "Standing height in meters (bipeds: head top; quadrupeds: withers)."
    },
    "build": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Body mass from -1 (slight) to 1 (heavy): limb and torso radii, shoulder width."
    },
    "age": {
      "type": "string",
      "enum": [
        "child",
        "adult",
        "elder"
      ],
      "description": "Age band (head and limb ratios)."
    },
    "proportions": {
      "type": "object",
      "properties": {
        "legRatio": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 1.6,
          "description": "Leg length multiplier (1 = preset)."
        },
        "armRatio": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 1.6,
          "description": "Arm length multiplier (1 = preset)."
        },
        "torsoRatio": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 1.6,
          "description": "Torso length multiplier (1 = preset)."
        },
        "headScale": {
          "type": "number",
          "minimum": 0.6,
          "maximum": 2,
          "description": "Head size multiplier (1 = preset)."
        },
        "neckLength": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 1.6,
          "description": "Neck length multiplier (1 = preset)."
        },
        "neckPitch": {
          "type": "number",
          "minimum": -1.2,
          "maximum": 1.6,
          "description": "Quadruped neck pitch above the spine line, radians."
        },
        "shoulderWidth": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 1.6,
          "description": "Shoulder width multiplier (1 = preset)."
        },
        "hipWidth": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 1.6,
          "description": "Hip width multiplier (1 = preset)."
        },
        "bodyLength": {
          "type": "number",
          "minimum": 0.8,
          "maximum": 2.5,
          "description": "Quadruped body length as a multiple of height (withers)."
        },
        "tailLength": {
          "type": "number",
          "minimum": 0,
          "maximum": 2,
          "description": "Tail length as a multiple of height."
        },
        "earSize": {
          "type": "number",
          "minimum": 0,
          "maximum": 2,
          "description": "Ear size multiplier (1 = preset)."
        },
        "snoutLength": {
          "type": "number",
          "minimum": 0,
          "maximum": 1.5,
          "description": "Snout length as a multiple of the head unit (0 = flat face)."
        }
      },
      "additionalProperties": false,
      "description": "Proportion multipliers over the preset."
    },
    "features": {
      "type": "object",
      "properties": {
        "form": {
          "type": "string",
          "enum": [
            "neutral",
            "masculine",
            "feminine"
          ],
          "description": "Human body form: shoulder, waist, hip and chest shape (bipeds)."
        },
        "hair": {
          "type": "string",
          "enum": [
            "none",
            "buzz",
            "balding",
            "cap",
            "crop",
            "bob",
            "long",
            "ponytail",
            "bun",
            "afro"
          ],
          "description": "Hair style: none, buzz, balding, cap (short), crop, bob, long, ponytail, bun, afro."
        },
        "facialHair": {
          "type": "string",
          "enum": [
            "none",
            "stubble",
            "mustache",
            "beard"
          ],
          "description": "Facial hair (humans), drawn in the hair color."
        },
        "hands": {
          "type": "string",
          "enum": [
            "mitten",
            "fingers"
          ],
          "description": "Hand geometry (fingers: near tier only)."
        },
        "sleeves": {
          "type": "string",
          "enum": [
            "none",
            "short",
            "long"
          ],
          "description": "Sleeve length (top color extent)."
        },
        "legs": {
          "type": "string",
          "enum": [
            "shorts",
            "long",
            "skirt"
          ],
          "description": "Legwear: shorts, long trousers, or a knee-length skirt (bottom color)."
        },
        "tail": {
          "type": "string",
          "enum": [
            "none",
            "short",
            "long",
            "bushy"
          ],
          "description": "Tail style."
        },
        "ears": {
          "type": "string",
          "enum": [
            "none",
            "round",
            "pointed",
            "floppy"
          ],
          "description": "Ear style."
        },
        "horns": {
          "type": "string",
          "enum": [
            "none",
            "short",
            "long",
            "antlers"
          ],
          "description": "Horn style."
        },
        "feet": {
          "type": "string",
          "enum": [
            "plantigrade",
            "digitigrade",
            "unguligrade"
          ],
          "description": "Foot stance: flat feet, paws, or hooves."
        },
        "mane": {
          "type": "boolean",
          "description": "Neck mane (horses)."
        }
      },
      "additionalProperties": false,
      "description": "Discrete feature choices over the preset."
    },
    "palette": {
      "type": "object",
      "properties": {
        "skin": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Skin, fur, or hide color."
        },
        "hair": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Hair or mane color."
        },
        "eyes": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Color as \"#rrggbb\"."
        },
        "top": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Torso and sleeves."
        },
        "bottom": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Legwear."
        },
        "shoes": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Shoes, paws, or hooves."
        },
        "accent": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Belt, collar, or saddle strip."
        },
        "markings": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Secondary fur markings (animals)."
        }
      },
      "additionalProperties": false,
      "description": "Color blocks over the preset (\"#rrggbb\")."
    },
    "seed": {
      "type": "string",
      "minLength": 1,
      "description": "Detail jitter seed (symmetry-safe details only; default none)."
    },
    "facing": {
      "type": "string",
      "enum": [
        "velocity",
        "manual"
      ],
      "description": "How the figure turns: 'velocity' (default) writes transform.rot toward the travel direction; 'manual' leaves rotation to whoever owns it."
    },
    "turnRate": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Max turn rate in rad/s for velocity facing (default 10)."
    },
    "speedSource": {
      "type": "string",
      "enum": [
        "auto",
        "transform",
        "none"
      ],
      "description": "Where speed comes from: 'auto' (kinematicBody, character, platformBody, rapier velocity, else transform deltas), 'transform', or 'none'."
    },
    "blendTicks": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Ticks to blend between modes (default 12)."
    }
  },
  "required": [
    "preset"
  ],
  "additionalProperties": false
}

</details>

figureAttachment ​

Follow a named socket of the parent figure (with parent): the figures systems write localTransform from the evaluated pose each tick.

Required: socket

json
{
  "socket": "head.top"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "socket": {
      "type": "string",
      "minLength": 1,
      "description": "Socket name on the parent figure: 'head.top', 'hand.r', 'back', 'saddle', ..."
    },
    "offset": {
      "type": "object",
      "properties": {
        "pos": {
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "Socket-local position offset in meters."
        },
        "rot": {
          "minItems": 4,
          "maxItems": 4,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "Socket-local rotation offset [x, y, z, w]."
        }
      },
      "additionalProperties": false,
      "description": "Extra socket-local offset."
    },
    "anchor": {
      "type": "string",
      "enum": [
        "origin",
        "pelvis",
        "eye"
      ],
      "description": "Which point of the attached entity sits on the socket (default 'origin')."
    }
  },
  "required": [
    "socket"
  ],
  "additionalProperties": false
}

</details>

figureIntent ​

Optional authored control of a figure: a forced mode, a look-at target, joint overrides, and IK goals.

Required: none

json
{
  "mode": "sit"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "idle",
        "walk",
        "run",
        "jump",
        "fall",
        "sit",
        "custom"
      ],
      "description": "Force a mode instead of deriving it from motion."
    },
    "lookAt": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "pos": {
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "World point [x, y, z] to look at."
            }
          },
          "required": [
            "pos"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "entity": {
              "type": "string",
              "minLength": 1,
              "description": "Entity id to look at."
            }
          },
          "required": [
            "entity"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Aim the head at a world point or another entity."
    },
    "overrides": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1
      },
      "additionalProperties": {
        "minItems": 4,
        "maxItems": 4,
        "type": "array",
        "items": {
          "type": "number"
        }
      },
      "description": "Joint-local rotations [x, y, z, w] by canonical joint name, replacing the gait."
    },
    "ik": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "enum": [
          "hand.l",
          "hand.r",
          "foot.l",
          "foot.r"
        ]
      },
      "additionalProperties": {
        "minItems": 3,
        "maxItems": 3,
        "type": "array",
        "items": {
          "type": "number"
        }
      },
      "description": "Figure-local effector goals solved by two-bone IK after the gait."
    },
    "footIk": {
      "type": "boolean",
      "description": "Plant feet on the ground field (opt-in)."
    }
  },
  "additionalProperties": false
}

</details>

figureState ​

Kernel-owned locomotion state of a figure (mode, quantized speed, tick-anchored gait phase). Read it; the figures systems write it.

Required: mode, speed, strideRate, phaseAt, phaseAtTick, modeAtTick

json
{
  "mode": "walk",
  "speed": 1.4,
  "strideRate": 1.09,
  "phaseAt": 0.37,
  "phaseAtTick": 1200,
  "modeAtTick": 1180,
  "prevMode": "idle"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "idle",
        "walk",
        "run",
        "jump",
        "fall",
        "sit",
        "custom"
      ],
      "description": "Current locomotion mode."
    },
    "gait": {
      "type": "string",
      "enum": [
        "walk",
        "trot",
        "gallop"
      ],
      "description": "Quadruped gait for walk/run modes."
    },
    "speed": {
      "type": "number",
      "minimum": 0,
      "description": "Planar speed in m/s (quantized)."
    },
    "travel": {
      "type": "number",
      "description": "Travel direction relative to facing, radians (absent = forward)."
    },
    "strideRate": {
      "type": "number",
      "minimum": 0,
      "description": "Gait cycles per second."
    },
    "phaseAt": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Gait phase [0, 1) at phaseAtTick."
    },
    "phaseAtTick": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Tick the phase was anchored at."
    },
    "modeAtTick": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Tick the current mode began (blend start)."
    },
    "prevMode": {
      "type": "string",
      "enum": [
        "idle",
        "walk",
        "run",
        "jump",
        "fall",
        "sit",
        "custom"
      ],
      "description": "Mode being blended out of."
    },
    "lookAtTick": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Tick the look-at target last changed."
    }
  },
  "required": [
    "mode",
    "speed",
    "strideRate",
    "phaseAt",
    "phaseAtTick",
    "modeAtTick"
  ],
  "additionalProperties": false
}

</details>

Owner: kernel ​

boostMode ​

World-wide 4× travel assist for people and vehicles. Control response times stay normal.

Required: enabled

json
{
  "enabled": true
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Enable 4× travel speed for people and vehicles."
    }
  },
  "required": [
    "enabled"
  ],
  "additionalProperties": false
}

</details>

lifetime ​

Auto-despawn countdown in ticks.

Required: ticksLeft

json
{
  "ticksLeft": 30
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ticksLeft": {
      "type": "number",
      "description": "Ticks remaining before the entity is despawned; decremented each tick."
    }
  },
  "required": [
    "ticksLeft"
  ],
  "additionalProperties": false
}

</details>

platformBody ​

Deterministic XY platform controller: gravity, swept wall/floor/ceiling collision, jump buffering and coyote time.

Required: halfExtents

json
{
  "halfExtents": [
    0.4,
    0.6
  ],
  "speed": 7,
  "jumpSpeed": 11
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "halfExtents": {
      "minItems": 2,
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "number",
        "exclusiveMinimum": 0
      },
      "description": "Moving XY box half-width/half-height, world meters. Z remains unchanged."
    },
    "vel": {
      "description": "XY velocity in meters/second; default [0,0].",
      "minItems": 2,
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "speed": {
      "description": "Maximum horizontal speed; default 7 m/s.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "acceleration": {
      "description": "Horizontal acceleration/braking; default 45 m/s squared.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "gravity": {
      "description": "Downward acceleration; default 28 m/s squared.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "jumpSpeed": {
      "description": "Jump velocity; default 11 m/s.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "grounded": {
      "description": "Output: landed in the last physics tick.",
      "type": "boolean"
    },
    "coyoteTicks": {
      "description": "Jump grace after leaving a ledge; default 3 ticks.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "bufferTicks": {
      "description": "Jump input buffer before landing; default 4 ticks.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "grace": {
      "description": "Runtime remaining coyote ticks; checkpointed.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "buffered": {
      "description": "Runtime remaining buffered jump ticks; checkpointed.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "halfExtents"
  ],
  "additionalProperties": false
}

</details>

platformIntent ​

Input to a platformBody. Scripts translate declared commands to this component.

Required: move

json
{
  "move": 1,
  "jump": true,
  "jumpHeld": true
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "move": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Horizontal intent -1..1."
    },
    "jump": {
      "description": "One-shot jump request, consumed by the controller. Send on press, not every tick.",
      "type": "boolean"
    },
    "jumpHeld": {
      "description": "Hold for full height; false cuts upward velocity for a short hop. Default true.",
      "type": "boolean"
    }
  },
  "required": [
    "move"
  ],
  "additionalProperties": false
}

</details>

platformSolid ​

Static XY solid for physics.engine=platformer; Z is ignored.

Required: halfExtents

json
{
  "halfExtents": [
    3,
    0.5
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "halfExtents": {
      "minItems": 2,
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "number",
        "exclusiveMinimum": 0
      },
      "description": "Static XY box half-width/half-height in world meters. Rotation and visual scale do not affect collision."
    },
    "oneWay": {
      "type": "boolean",
      "description": "Only stop descending bodies crossing the top; default false."
    }
  },
  "required": [
    "halfExtents"
  ],
  "additionalProperties": false
}

</details>

transform ​

World position + orientation. pos is required; rot defaults to identity.

Required: pos

json
{
  "pos": [
    0,
    1.5,
    -3
  ],
  "rot": [
    0,
    0,
    0,
    1
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pos": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "World position [x, y, z] in meters (Y-up)."
    },
    "rot": {
      "minItems": 4,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "World orientation quaternion [x, y, z, w]; defaults to identity [0, 0, 0, 1]."
    },
    "scale": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Per-axis scale factors [x, y, z]; defaults to [1, 1, 1]."
    },
    "teleport": {
      "type": "boolean",
      "description": "Client interpolation hint: when true the client snaps to this update instead of lerping from the previous tick."
    }
  },
  "required": [
    "pos"
  ],
  "additionalProperties": false
}

</details>

Owner: kernel/aircraft ​

aircraft ​

External airplane/helicopter instance. Y up, Z forward; landing-contact origin.

Required: kind, spec

json
{
  "kind": "example.airplane",
  "spec": {
    "label": "Example airplane",
    "model": "airplane",
    "mass": 1200,
    "span": 10,
    "length": 8,
    "height": 3,
    "centerOfMass": [
      0,
      1,
      0
    ],
    "pilotEye": [
      0,
      1.8,
      0
    ],
    "engine": {
      "position": [
        0,
        1,
        2.5
      ],
      "thrustAxis": [
        0,
        0,
        1
      ],
      "power": 200000,
      "idleRpm": 0.2,
      "spoolRate": 0.5,
      "rotorAngularSpeed": 200
    },
    "airplane": {
      "wingPosition": [
        0,
        1,
        0
      ],
      "wingArea": 16,
      "controlAuthoritySpeed": 45,
      "maxControlAuthority": 1.3,
      "pitchAuthority": 0.4,
      "pitchResponse": 3,
      "stallPitchRate": 0.18,
      "rollAuthority": 1,
      "rollResponse": 2,
      "rudderAuthority": 1,
      "groundSteerSpeed": 8,
      "groundLevelRate": 2,
      "maxGroundPitch": 0.2,
      "camberAngle": 0.04,
      "flapLift": 0.3,
      "postStallFlapEffect": 0.4,
      "stallAngle": 0.28,
      "stallSpeed": 22,
      "liftSlope": 4.5,
      "postStallLift": 0.2,
      "postStallDecay": 2.8,
      "profileDrag": 0.025,
      "inducedDrag": 0.065,
      "gearDrag": 0.018,
      "flapDrag": 0.035,
      "stallDrag": 0.2,
      "propellerEfficiency": 0.8,
      "maxThrust": 5000,
      "minPropellerSpeed": 40,
      "lateralDamping": 0.8,
      "brakeDeceleration": 7,
      "rollingDeceleration": 0.22,
      "groundTrackRate": 12
    },
    "hardLandingSpeed": 4.5,
    "hardLandingRoll": 0.3,
    "hardLandingPitch": 0.35,
    "maxSupportStep": 0.65,
    "collisionProbes": [
      [
        0,
        1,
        0
      ]
    ],
    "visual": {
      "rotors": [
        {
          "node": "propeller",
          "axis": "z",
          "multiplier": 1
        }
      ],
      "gearNodes": [
        "gear"
      ],
      "flaps": [
        {
          "node": "flap",
          "axis": "x",
          "multiplier": -0.45
        }
      ],
      "ailerons": [
        {
          "node": "aileron",
          "axis": "x",
          "multiplier": 0.3
        }
      ],
      "controlStick": {
        "node": "control-stick",
        "pitchAxis": "x",
        "rollAxis": "z"
      },
      "airspeedGaugeMax": 180
    }
  }
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "minLength": 1,
      "description": "Stable external entity/type id."
    },
    "spec": {
      "type": "object",
      "properties": {
        "actuators": {
          "description": "External actuators setting.",
          "type": "object",
          "propertyNames": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[a-zA-Z][a-zA-Z0-9]*$"
          },
          "additionalProperties": {
            "type": "object",
            "properties": {
              "seconds": {
                "type": "number",
                "minimum": 0,
                "description": "Seconds for full travel or a full cycle."
              },
              "initial": {
                "description": "Rest position or phase; defaults to zero.",
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "mode": {
                "description": "Position by default. Cycles park when off; latches cannot reverse.",
                "type": "string",
                "enum": [
                  "position",
                  "cycle",
                  "latch"
                ]
              }
            },
            "required": [
              "seconds"
            ],
            "additionalProperties": false
          }
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "External label setting."
        },
        "genericLabel": {
          "description": "External genericLabel setting.",
          "type": "string",
          "minLength": 1
        },
        "model": {
          "type": "string",
          "enum": [
            "airplane",
            "helicopter"
          ],
          "description": "External model setting."
        },
        "mass": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External mass setting."
        },
        "span": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External span setting."
        },
        "length": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External length setting."
        },
        "height": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External height setting."
        },
        "centerOfMass": {
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "External centerOfMass setting."
        },
        "pilotEye": {
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "External pilotEye setting."
        },
        "engine": {
          "description": "Single engine, implicitly named main. Supply exactly one of engine or engines.",
          "type": "object",
          "properties": {
            "mixtureControl": {
              "description": "Manual piston mixture; omitted leaves fuel scheduling automatic.",
              "type": "boolean"
            },
            "propellerControl": {
              "description": "Constant-speed propeller; the lever selects RPM and the governor varies pitch.",
              "type": "object",
              "properties": {
                "minRpm": {
                  "type": "number",
                  "minimum": 0.3,
                  "maximum": 0.95,
                  "description": "Minimum governed RPM as a fraction of rated propeller RPM."
                }
              },
              "required": [
                "minRpm"
              ],
              "additionalProperties": false
            },
            "propulsion": {
              "description": "Installed propulsion type; omitted preserves the legacy constant-power model.",
              "type": "string",
              "enum": [
                "propeller",
                "jet"
              ]
            },
            "dryThrust": {
              "description": "Sea-level static dry jet thrust in newtons, per engine.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "afterburnerThrust": {
              "description": "Total sea-level static augmented thrust in newtons, per engine; must exceed dry thrust.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "afterburnerDetent": {
              "description": "Throttle fraction where reheat starts; default 0.85.",
              "type": "number",
              "minimum": 0.1,
              "maximum": 0.99
            },
            "densityExponent": {
              "description": "Installed power/thrust density lapse exponent.",
              "type": "number",
              "minimum": 0,
              "maximum": 3
            },
            "highAltitudeDensityRatio": {
              "description": "Density ratio where upper-altitude engine lapse begins; continuous at this knee.",
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1
            },
            "highAltitudeExponent": {
              "description": "Density lapse exponent below highAltitudeDensityRatio; defaults to densityExponent.",
              "type": "number",
              "minimum": 0,
              "maximum": 3
            },
            "ratedDensityRatio": {
              "description": "Lowest density ratio retaining flat-rated power or thrust; default 1.",
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1
            },
            "ramRise": {
              "description": "Jet net-thrust multiplier per Mach squared, representing inlet ram recovery; default 0.",
              "type": "number",
              "minimum": 0,
              "maximum": 2
            },
            "position": {
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "Engine thrust application point in aircraft-local meters, relative to the landing-contact origin."
            },
            "thrustAxis": {
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "Local thrust direction; normalized by the solver."
            },
            "power": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Maximum shaft power in watts, per engine; retained as compatibility metadata for jets."
            },
            "idleRpm": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "External idleRpm setting."
            },
            "spoolRate": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External spoolRate setting."
            },
            "rotorAngularSpeed": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External rotorAngularSpeed setting."
            },
            "vectored": {
              "description": "Rotate +Z thrust toward +Y with the powered-lift lever.",
              "type": "boolean"
            },
            "propellerEfficiency": {
              "description": "Per-engine override of airplane.propellerEfficiency.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "maxThrust": {
              "description": "Per-engine static thrust cap in newtons; defaults to airplane.maxThrust.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "minPropellerSpeed": {
              "description": "Minimum propeller advance speed in m/s for the power/thrust calculation; defaults to airplane.minPropellerSpeed.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "propellerRotation": {
              "description": "Turning direction seen from the cockpit. Clockwise (default) swings the nose left; scaled by airplane.propellerEffects.",
              "type": "string",
              "enum": [
                "clockwise",
                "counterclockwise"
              ]
            },
            "propellerInertia": {
              "description": "Propeller polar moment of inertia in kg m², for gyroscopic precession. Default 0.",
              "type": "number",
              "minimum": 0
            },
            "fuelConsumption": {
              "description": "Specific fuel consumption when the aircraft declares fuel: kg per joule of shaft work for a propeller or rotor engine (default 7.5e-8 with a manual mixture, 9.5e-8 otherwise), kg per newton-second of thrust for a jet (default 2e-5).",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "afterburnerFuelConsumption": {
              "description": "Jet consumption in kg per newton-second of total thrust at full reheat. Default 5.4e-5.",
              "type": "number",
              "exclusiveMinimum": 0
            }
          },
          "required": [
            "position",
            "thrustAxis",
            "power",
            "idleRpm",
            "spoolRate",
            "rotorAngularSpeed"
          ],
          "additionalProperties": false
        },
        "engines": {
          "description": "Named independent airplane engines; ids must be unique. Each power/thrust limit is per engine.",
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "mixtureControl": {
                "description": "Manual piston mixture; omitted leaves fuel scheduling automatic.",
                "type": "boolean"
              },
              "propellerControl": {
                "description": "Constant-speed propeller; the lever selects RPM and the governor varies pitch.",
                "type": "object",
                "properties": {
                  "minRpm": {
                    "type": "number",
                    "minimum": 0.3,
                    "maximum": 0.95,
                    "description": "Minimum governed RPM as a fraction of rated propeller RPM."
                  }
                },
                "required": [
                  "minRpm"
                ],
                "additionalProperties": false
              },
              "propulsion": {
                "description": "Installed propulsion type; omitted preserves the legacy constant-power model.",
                "type": "string",
                "enum": [
                  "propeller",
                  "jet"
                ]
              },
              "dryThrust": {
                "description": "Sea-level static dry jet thrust in newtons, per engine.",
                "type": "number",
                "exclusiveMinimum": 0
              },
              "afterburnerThrust": {
                "description": "Total sea-level static augmented thrust in newtons, per engine; must exceed dry thrust.",
                "type": "number",
                "exclusiveMinimum": 0
              },
              "afterburnerDetent": {
                "description": "Throttle fraction where reheat starts; default 0.85.",
                "type": "number",
                "minimum": 0.1,
                "maximum": 0.99
              },
              "densityExponent": {
                "description": "Installed power/thrust density lapse exponent.",
                "type": "number",
                "minimum": 0,
                "maximum": 3
              },
              "highAltitudeDensityRatio": {
                "description": "Density ratio where upper-altitude engine lapse begins; continuous at this knee.",
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1
              },
              "highAltitudeExponent": {
                "description": "Density lapse exponent below highAltitudeDensityRatio; defaults to densityExponent.",
                "type": "number",
                "minimum": 0,
                "maximum": 3
              },
              "ratedDensityRatio": {
                "description": "Lowest density ratio retaining flat-rated power or thrust; default 1.",
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1
              },
              "ramRise": {
                "description": "Jet net-thrust multiplier per Mach squared, representing inlet ram recovery; default 0.",
                "type": "number",
                "minimum": 0,
                "maximum": 2
              },
              "position": {
                "minItems": 3,
                "maxItems": 3,
                "type": "array",
                "items": {
                  "type": "number"
                },
                "description": "Engine thrust application point in aircraft-local meters, relative to the landing-contact origin."
              },
              "thrustAxis": {
                "minItems": 3,
                "maxItems": 3,
                "type": "array",
                "items": {
                  "type": "number"
                },
                "description": "Local thrust direction; normalized by the solver."
              },
              "power": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "Maximum shaft power in watts, per engine; retained as compatibility metadata for jets."
              },
              "idleRpm": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "External idleRpm setting."
              },
              "spoolRate": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "External spoolRate setting."
              },
              "rotorAngularSpeed": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "External rotorAngularSpeed setting."
              },
              "vectored": {
                "description": "Rotate +Z thrust toward +Y with the powered-lift lever.",
                "type": "boolean"
              },
              "propellerEfficiency": {
                "description": "Per-engine override of airplane.propellerEfficiency.",
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "maxThrust": {
                "description": "Per-engine static thrust cap in newtons; defaults to airplane.maxThrust.",
                "type": "number",
                "exclusiveMinimum": 0
              },
              "minPropellerSpeed": {
                "description": "Minimum propeller advance speed in m/s for the power/thrust calculation; defaults to airplane.minPropellerSpeed.",
                "type": "number",
                "exclusiveMinimum": 0
              },
              "propellerRotation": {
                "description": "Turning direction seen from the cockpit. Clockwise (default) swings the nose left; scaled by airplane.propellerEffects.",
                "type": "string",
                "enum": [
                  "clockwise",
                  "counterclockwise"
                ]
              },
              "propellerInertia": {
                "description": "Propeller polar moment of inertia in kg m², for gyroscopic precession. Default 0.",
                "type": "number",
                "minimum": 0
              },
              "fuelConsumption": {
                "description": "Specific fuel consumption when the aircraft declares fuel: kg per joule of shaft work for a propeller or rotor engine (default 7.5e-8 with a manual mixture, 9.5e-8 otherwise), kg per newton-second of thrust for a jet (default 2e-5).",
                "type": "number",
                "exclusiveMinimum": 0
              },
              "afterburnerFuelConsumption": {
                "description": "Jet consumption in kg per newton-second of total thrust at full reheat. Default 5.4e-5.",
                "type": "number",
                "exclusiveMinimum": 0
              },
              "id": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
                "description": "Stable engine id, such as left or right; single-engine form uses main."
              }
            },
            "required": [
              "position",
              "thrustAxis",
              "power",
              "idleRpm",
              "spoolRate",
              "rotorAngularSpeed",
              "id"
            ],
            "additionalProperties": false
          }
        },
        "airplane": {
          "description": "External airplane setting.",
          "type": "object",
          "properties": {
            "wingPosition": {
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "External wingPosition setting."
            },
            "wingArea": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External wingArea setting."
            },
            "controlAuthoritySpeed": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Reference equivalent airspeed in m/s for the control, stability and damping rates."
            },
            "maxControlAuthority": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Cap on aileron, elevator and rudder power relative to the reference speed."
            },
            "pitchAuthority": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Angle of attack in radians that full elevator adds to the trim angle."
            },
            "pitchResponse": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Elevator travel per second, in full deflections."
            },
            "stallPitchRate": {
              "type": "number",
              "minimum": 0,
              "description": "Nose-down pitch rate in rad/s at full flow separation (the stall break)."
            },
            "rollAuthority": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Roll rate in rad/s at full aileron and reference speed; grows with speed up to maxControlAuthority."
            },
            "rollResponse": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Roll damping in 1/s at reference speed; grows with airspeed."
            },
            "rudderAuthority": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Yaw acceleration in rad/s² at full rudder and reference speed; propwash keeps some at low speed."
            },
            "groundSteerSpeed": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Ground speed in m/s at which tailwheel steering reaches full turn rate."
            },
            "groundLevelRate": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External groundLevelRate setting."
            },
            "maxGroundPitch": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External maxGroundPitch setting."
            },
            "camberAngle": {
              "type": "number",
              "description": "External camberAngle setting."
            },
            "flapLift": {
              "type": "number",
              "minimum": 0,
              "description": "External flapLift setting."
            },
            "postStallFlapEffect": {
              "type": "number",
              "minimum": 0,
              "description": "External postStallFlapEffect setting."
            },
            "stallAngle": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External stallAngle setting."
            },
            "criticalMach": {
              "description": "Mach at which compressibility wave drag begins; omitted disables wave drag.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "waveDrag": {
              "description": "Wave drag coefficient at criticalMach + 0.25; default 0.",
              "type": "number",
              "minimum": 0
            },
            "maxEquivalentAirspeed": {
              "description": "Airframe operating limit in m/s equivalent airspeed; alert only.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "maxMach": {
              "description": "Airframe Mach operating limit; alert only.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "gearLimitSpeed": {
              "description": "Maximum equivalent airspeed with gear extended, m/s; alert only.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "flapLimitSpeed": {
              "description": "Maximum equivalent airspeed with flaps extended, m/s; alert only.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "groundEffect": {
              "description": "Reduce wing induced drag near the ground; default false.",
              "type": "boolean"
            },
            "departure": {
              "description": "External departure setting.",
              "type": "object",
              "properties": {
                "onsetAngle": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1.5707963267948966,
                  "description": "High-alpha departure onset, radians."
                },
                "fullAngle": {
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 1.5707963267948966,
                  "description": "Fully developed departure incidence, radians; greater than onsetAngle."
                },
                "yawInstability": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Separated-flow yaw growth rate, per second."
                },
                "yawSaturationRate": {
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "description": "Autorotation saturation scale, radians per second."
                },
                "rudderBlanking": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "Fraction of rudder authority lost at full departure."
                },
                "pitchBlanking": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "Fraction of pitch stability and control lost at full departure."
                },
                "aileronReversal": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "Aileron reversal: 0 unchanged, 0.5 ineffective, 1 reversed."
                }
              },
              "required": [
                "onsetAngle",
                "fullAngle",
                "yawInstability",
                "yawSaturationRate",
                "rudderBlanking",
                "pitchBlanking",
                "aileronReversal"
              ],
              "additionalProperties": false
            },
            "stallTransitionAngle": {
              "description": "Radians beyond stallAngle over which flow separates smoothly. Default 0.12.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "pitchFrequency": {
              "description": "Short-period natural frequency in rad/s at reference speed. Default 3.5.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "pitchDamping": {
              "description": "Short-period damping ratio. Default 0.7.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "maxLoadFactor": {
              "description": "Load factor in g that full back stick pulls at high speed. Default 6.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "minLoadFactor": {
              "description": "Load factor in g that full forward stick pushes at high speed. Default -3.",
              "type": "number",
              "exclusiveMaximum": 0
            },
            "autoTrim": {
              "description": "Rate in 1/s at which trim follows the angle of attack that holds the flight path; 0 leaves trim fixed. Default 1.",
              "type": "number",
              "minimum": 0
            },
            "directionalStability": {
              "description": "Weathercock stiffness: yaw acceleration in rad/s² per radian of sideslip at reference speed. Default 4.",
              "type": "number",
              "minimum": 0
            },
            "yawDamping": {
              "description": "Yaw damping in 1/s at reference speed. Default 1.2.",
              "type": "number",
              "minimum": 0
            },
            "dihedralEffect": {
              "description": "Roll acceleration in rad/s² per radian of sideslip at reference speed, away from the slip. Default 3.",
              "type": "number"
            },
            "rollInertia": {
              "description": "Roll inertia in kg m². Default mass * (0.14 * span)².",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "pitchInertia": {
              "description": "Pitch inertia in kg m². Default mass * (0.18 * length)².",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "yawInertia": {
              "description": "Yaw inertia in kg m². Default mass * (span² + length²) / 12.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "propellerEffects": {
              "description": "Scale of propeller torque, P-factor and slipstream yaw, and gyroscopic precession; 0 disables them. Default 0.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "stallSpeed": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Legacy tuning reference in m/s; aerodynamic stall detection uses angle of attack."
            },
            "liftSlope": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External liftSlope setting."
            },
            "postStallLift": {
              "type": "number",
              "minimum": 0,
              "description": "External postStallLift setting."
            },
            "postStallDecay": {
              "type": "number",
              "minimum": 0,
              "description": "External postStallDecay setting."
            },
            "profileDrag": {
              "type": "number",
              "minimum": 0,
              "description": "External profileDrag setting."
            },
            "inducedDrag": {
              "type": "number",
              "minimum": 0,
              "description": "External inducedDrag setting."
            },
            "gearDrag": {
              "type": "number",
              "minimum": 0,
              "description": "Drag coefficient of the landing gear fully down; scales with the gear position."
            },
            "speedBrakeDrag": {
              "description": "Additional drag coefficient at full speedBrake actuator extension.",
              "type": "number",
              "minimum": 0
            },
            "flapDrag": {
              "type": "number",
              "minimum": 0,
              "description": "Drag coefficient of the flaps fully down; scales with the flap position."
            },
            "fixedGear": {
              "description": "Fixed undercarriage stays down regardless of the gear selection.",
              "type": "boolean"
            },
            "gearTransitTime": {
              "description": "Seconds for a full landing-gear cycle, doors included, either way. The gear holds still with weight on the wheels, and only a locked-down gear can land. Default 0 (instant).",
              "type": "number",
              "minimum": 0
            },
            "flapTransitTime": {
              "description": "Seconds for the flaps to travel fully up to fully down. Default 0 (instant).",
              "type": "number",
              "minimum": 0
            },
            "stallDrag": {
              "type": "number",
              "minimum": 0,
              "description": "Broadside separated-flow drag coefficient, blended by separation and sin(alpha)^2."
            },
            "propellerEfficiency": {
              "type": "number",
              "minimum": 0,
              "description": "External propellerEfficiency setting."
            },
            "maxThrust": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External maxThrust setting."
            },
            "minPropellerSpeed": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External minPropellerSpeed setting."
            },
            "lateralDamping": {
              "type": "number",
              "minimum": 0,
              "description": "External lateralDamping setting."
            },
            "brakeDeceleration": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External brakeDeceleration setting."
            },
            "rollingDeceleration": {
              "type": "number",
              "minimum": 0,
              "description": "External rollingDeceleration setting."
            },
            "groundTrackRate": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Tire side grip with full weight on the wheels: lateral deceleration in m/s² and yaw grip in 1/s."
            },
            "tailwheel": {
              "description": "Main wheels ahead of the center of mass with a tailwheel: a firm touchdown pitches the nose up and hard braking lifts the tail. Default false (nosewheel).",
              "type": "boolean"
            },
            "gearRebound": {
              "description": "Share of the sink speed beyond 0.6 m/s that struts and tires give back at touchdown. Default 0.45.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "pilotGTolerance": {
              "description": "Sustained positive g the pilot holds before vision dims. Default 4.5, or 6.5 when maxLoadFactor is 7.5 or more.",
              "type": "number",
              "exclusiveMinimum": 0
            }
          },
          "required": [
            "wingPosition",
            "wingArea",
            "controlAuthoritySpeed",
            "maxControlAuthority",
            "pitchAuthority",
            "pitchResponse",
            "stallPitchRate",
            "rollAuthority",
            "rollResponse",
            "rudderAuthority",
            "groundSteerSpeed",
            "groundLevelRate",
            "maxGroundPitch",
            "camberAngle",
            "flapLift",
            "postStallFlapEffect",
            "stallAngle",
            "stallSpeed",
            "liftSlope",
            "postStallLift",
            "postStallDecay",
            "profileDrag",
            "inducedDrag",
            "gearDrag",
            "flapDrag",
            "stallDrag",
            "propellerEfficiency",
            "maxThrust",
            "minPropellerSpeed",
            "lateralDamping",
            "brakeDeceleration",
            "rollingDeceleration",
            "groundTrackRate"
          ],
          "additionalProperties": false
        },
        "helicopter": {
          "description": "External helicopter setting.",
          "type": "object",
          "properties": {
            "fixedGear": {
              "description": "Fixed skids or wheels by default; false enables retractable gear.",
              "type": "boolean"
            },
            "gearTransitTime": {
              "description": "Seconds for full retractable gear travel.",
              "type": "number",
              "minimum": 0
            },
            "rotorPosition": {
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "External rotorPosition setting."
            },
            "rotorRadius": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External rotorRadius setting."
            },
            "powerLimitedRotor": {
              "description": "Govern rotor RPM and limit thrust using installed shaft power and actuator-disc momentum theory.",
              "type": "boolean"
            },
            "rotorEfficiency": {
              "description": "Rotor induced-power efficiency; default 0.75.",
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1
            },
            "profilePowerFraction": {
              "description": "Installed shaft-power fraction spent on rotor profile drag at governed RPM; default 0.12.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "vortexRing": {
              "description": "Enable estimated powered-descent vortex-ring loss of lift; default false.",
              "type": "boolean"
            },
            "retreatingBladeSpeed": {
              "description": "Sea-level TAS for estimated retreating-blade onset, m/s; decreases with density and rotor RPM.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "rotorDiscs": {
              "description": "Effective lifting-disc count, 2 for a tandem rotor; default 1.",
              "type": "integer",
              "minimum": 1,
              "maximum": 2
            },
            "rotorInertiaTime": {
              "description": "Seconds of hover power stored in the rotor at full speed; default 2. Sets how long an unpowered rotor carries the helicopter (autorotation); needs powerLimitedRotor.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "directionalStability": {
              "description": "Tail-fin weathervaning in forward flight; default 1, 0 disables. The nose turns into the relative wind at directionalStability × airspeed / length rad/s per radian of sideslip, so a banked helicopter turns its nose with its track.",
              "type": "number",
              "minimum": 0
            },
            "cyclicRate": {
              "description": "Direct-cyclic pitch and roll rate at full stick with the rotor carrying the weight, rad/s; default cyclicResponse / 4.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "hubStiffness": {
              "description": "Share of direct-cyclic control power independent of rotor thrust, 0..1; default 0.25. Near 0 for a teetering rotor (no control at zero g), higher for articulated and hingeless rotors.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "cyclicTilt": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External cyclicTilt setting."
            },
            "cyclicResponse": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External cyclicResponse setting."
            },
            "cyclicDamping": {
              "type": "number",
              "minimum": 0,
              "description": "External cyclicDamping setting."
            },
            "groundLevelRate": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External groundLevelRate setting."
            },
            "maxTilt": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External maxTilt setting."
            },
            "yawRate": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External yawRate setting."
            },
            "liftMultiplier": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External liftMultiplier setting."
            },
            "groundEffect": {
              "type": "number",
              "minimum": 0,
              "description": "External groundEffect setting."
            },
            "translationalLift": {
              "type": "number",
              "minimum": 0,
              "description": "External translationalLift setting."
            },
            "translationalLiftSpeed": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External translationalLiftSpeed setting."
            },
            "verticalDrag": {
              "type": "number",
              "minimum": 0,
              "description": "External verticalDrag setting."
            },
            "horizontalDrag": {
              "type": "number",
              "minimum": 0,
              "description": "External horizontalDrag setting."
            },
            "quadraticDrag": {
              "type": "number",
              "minimum": 0,
              "description": "External quadraticDrag setting."
            },
            "groundDeceleration": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "External groundDeceleration setting."
            }
          },
          "required": [
            "rotorPosition",
            "rotorRadius",
            "cyclicTilt",
            "cyclicResponse",
            "cyclicDamping",
            "groundLevelRate",
            "maxTilt",
            "yawRate",
            "liftMultiplier",
            "groundEffect",
            "translationalLift",
            "translationalLiftSpeed",
            "verticalDrag",
            "horizontalDrag",
            "quadraticDrag",
            "groundDeceleration"
          ],
          "additionalProperties": false
        },
        "poweredLift": {
          "description": "Assisted hover controls and 0–90 degree thrust-vector actuator; airplane model only.",
          "type": "object",
          "properties": {
            "transitTime": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Seconds for thrust-vector travel from forward to vertical."
            },
            "controlFadeSpeed": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Axial airspeed in m/s at which assisted hover controls fade to zero."
            },
            "pitchAuthority": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Full-stick hover pitch angular acceleration in rad/s²."
            },
            "rollAuthority": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Full-stick hover roll angular acceleration in rad/s²."
            },
            "yawAuthority": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Full-pedal hover yaw angular acceleration in rad/s²."
            },
            "damping": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Thrust-dependent hover angular-rate damping in 1/s."
            }
          },
          "required": [
            "transitTime",
            "controlFadeSpeed",
            "pitchAuthority",
            "rollAuthority",
            "yawAuthority",
            "damping"
          ],
          "additionalProperties": false
        },
        "fuel": {
          "description": "Fuel on board: mass is the aircraft with full tanks, it lightens as fuel burns and the engines stop when the tanks are dry. Omitted is unlimited fuel at constant mass.",
          "type": "object",
          "properties": {
            "capacity": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Usable fuel in kg with full tanks."
            }
          },
          "required": [
            "capacity"
          ],
          "additionalProperties": false
        },
        "hardLandingSpeed": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External hardLandingSpeed setting."
        },
        "hardLandingRoll": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External hardLandingRoll setting."
        },
        "hardLandingPitch": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External hardLandingPitch setting."
        },
        "maxSupportStep": {
          "type": "number",
          "minimum": 0,
          "description": "External maxSupportStep setting."
        },
        "collisionProbes": {
          "minItems": 1,
          "type": "array",
          "items": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "description": "External collisionProbes setting."
        },
        "collisionParts": {
          "description": "Breakable airframe sections: local probe spheres, section center, mass fraction, normal break speed (m/s), GLB nodes and attached engines. Replaces collisionProbes.",
          "minItems": 1,
          "maxItems": 64,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
                "description": "Unique section id used by damage and debris state."
              },
              "role": {
                "type": "string",
                "enum": [
                  "body",
                  "leftWing",
                  "rightWing",
                  "tail",
                  "rotor",
                  "tailRotor",
                  "gear",
                  "engine"
                ],
                "description": "Flight role; +X is the left wing. Body sections cannot detach."
              },
              "probes": {
                "maxItems": 64,
                "type": "array",
                "items": {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                "description": "Local collision sphere centers, meters."
              },
              "radius": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "Probe and detached-piece collision radius, meters."
              },
              "disc": {
                "description": "Finite rotor disc replacing sphere probes, including at rest. Blade speed contributes to strike damage.",
                "type": "object",
                "properties": {
                  "center": {
                    "minItems": 3,
                    "maxItems": 3,
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Rotor hub in model coordinates, meters."
                  },
                  "normal": {
                    "minItems": 3,
                    "maxItems": 3,
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Unit rotation axis in model coordinates."
                  },
                  "radius": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "description": "Full swept rotor radius, meters."
                  },
                  "halfThickness": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "description": "Half the swept blade thickness, meters."
                  },
                  "rotor": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Node in visual.rotors supplying engine RPM and speed multiplier."
                  },
                  "tilt": {
                    "description": "Powered-lift hinge, in model coordinates at forward thrust.",
                    "type": "object",
                    "properties": {
                      "pivot": {
                        "minItems": 3,
                        "maxItems": 3,
                        "type": "array",
                        "items": {
                          "type": "number"
                        },
                        "description": "Powered-lift hinge pivot in model coordinates, meters."
                      },
                      "axis": {
                        "minItems": 3,
                        "maxItems": 3,
                        "type": "array",
                        "items": {
                          "type": "number"
                        },
                        "description": "Unit powered-lift hinge axis in model coordinates."
                      },
                      "angle": {
                        "type": "number",
                        "description": "Hinge rotation in radians at full thrustVectorPosition."
                      }
                    },
                    "required": [
                      "pivot",
                      "axis",
                      "angle"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "center",
                  "normal",
                  "radius",
                  "halfThickness",
                  "rotor"
                ],
                "additionalProperties": false
              },
              "parent": {
                "description": "Supporting part id; separation also releases this part.",
                "type": "string",
                "minLength": 1
              },
              "center": {
                "minItems": 3,
                "maxItems": 3,
                "type": "array",
                "items": {
                  "type": "number"
                },
                "description": "Section center in model coordinates, meters."
              },
              "massFraction": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1,
                "description": "Share of the original mass removed on separation."
              },
              "breakSpeed": {
                "description": "Joint failure speed in m/s for a normal impact. Loaded sliding also causes shear damage. Omit for an unbreakable section.",
                "type": "number",
                "exclusiveMinimum": 0
              },
              "nodes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                },
                "description": "GLB node names belonging to this section, including attached controls."
              },
              "fragments": {
                "description": "Optional region for splitting shared markings and detail meshes.",
                "type": "object",
                "properties": {
                  "nodes": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "description": "Shared static meshes to partition by triangle centroid."
                  },
                  "min": {
                    "minItems": 3,
                    "maxItems": 3,
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Minimum corner of the section region in model meters."
                  },
                  "max": {
                    "minItems": 3,
                    "maxItems": 3,
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Maximum corner of the section region in model meters."
                  }
                },
                "required": [
                  "nodes",
                  "min",
                  "max"
                ],
                "additionalProperties": false
              },
              "engines": {
                "description": "Engine ids that fail when this section detaches.",
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
                  "description": "Stable engine id, such as left or right; single-engine form uses main."
                }
              }
            },
            "required": [
              "id",
              "role",
              "probes",
              "radius",
              "center",
              "massFraction",
              "nodes"
            ],
            "additionalProperties": false
          }
        },
        "visual": {
          "type": "object",
          "properties": {
            "rotors": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "node": {
                    "type": "string",
                    "minLength": 1,
                    "description": "External node setting."
                  },
                  "axis": {
                    "type": "string",
                    "enum": [
                      "x",
                      "y",
                      "z"
                    ],
                    "description": "External axis setting."
                  },
                  "multiplier": {
                    "type": "number",
                    "description": "External multiplier setting."
                  },
                  "engine": {
                    "description": "Engine id driving this propeller; omitted follows the first engine.",
                    "type": "string",
                    "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
                  }
                },
                "required": [
                  "node",
                  "axis",
                  "multiplier"
                ],
                "additionalProperties": false
              },
              "description": "External rotors setting."
            },
            "gearNodes": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Nodes hidden while the landing gear is fully up."
            },
            "flaps": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "node": {
                    "type": "string",
                    "minLength": 1,
                    "description": "External node setting."
                  },
                  "axis": {
                    "type": "string",
                    "enum": [
                      "x",
                      "y",
                      "z"
                    ],
                    "description": "External axis setting."
                  },
                  "multiplier": {
                    "type": "number",
                    "description": "External multiplier setting."
                  }
                },
                "required": [
                  "node",
                  "axis",
                  "multiplier"
                ],
                "additionalProperties": false
              },
              "description": "Flap nodes turned by multiplier radians at full travel, in proportion to the flap position."
            },
            "ailerons": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "node": {
                    "type": "string",
                    "minLength": 1,
                    "description": "External node setting."
                  },
                  "axis": {
                    "type": "string",
                    "enum": [
                      "x",
                      "y",
                      "z"
                    ],
                    "description": "External axis setting."
                  },
                  "multiplier": {
                    "type": "number",
                    "description": "External multiplier setting."
                  }
                },
                "required": [
                  "node",
                  "axis",
                  "multiplier"
                ],
                "additionalProperties": false
              },
              "description": "External ailerons setting."
            },
            "controlStick": {
              "description": "External controlStick setting.",
              "type": "object",
              "properties": {
                "node": {
                  "type": "string",
                  "minLength": 1,
                  "description": "External node setting."
                },
                "pitchAxis": {
                  "type": "string",
                  "enum": [
                    "x",
                    "y",
                    "z"
                  ],
                  "description": "External pitchAxis setting."
                },
                "rollAxis": {
                  "type": "string",
                  "enum": [
                    "x",
                    "y",
                    "z"
                  ],
                  "description": "External rollAxis setting."
                }
              },
              "required": [
                "node",
                "pitchAxis",
                "rollAxis"
              ],
              "additionalProperties": false
            },
            "collective": {
              "description": "External collective setting.",
              "type": "object",
              "properties": {
                "node": {
                  "type": "string",
                  "minLength": 1,
                  "description": "External node setting."
                },
                "axis": {
                  "type": "string",
                  "enum": [
                    "x",
                    "y",
                    "z"
                  ],
                  "description": "External axis setting."
                },
                "multiplier": {
                  "type": "number",
                  "description": "External multiplier setting."
                }
              },
              "required": [
                "node",
                "axis",
                "multiplier"
              ],
              "additionalProperties": false
            },
            "airspeedGaugeMax": {
              "description": "External airspeedGaugeMax setting.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "interior": {
              "description": "External interior setting.",
              "type": "object",
              "properties": {
                "nodes": {
                  "minItems": 1,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  },
                  "description": "Cabin nodes in the same exterior/interior GLB."
                },
                "sources": {
                  "description": "Optional component fields overriding or extending host telemetry.",
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "minLength": 1
                  },
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "component": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Component on this same entity."
                      },
                      "path": {
                        "minItems": 1,
                        "type": "array",
                        "items": {
                          "anyOf": [
                            {
                              "type": "string",
                              "minLength": 1
                            },
                            {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 9007199254740991
                            }
                          ]
                        },
                        "description": "Explicit property names or array indices leading to a number or boolean."
                      }
                    },
                    "required": [
                      "component",
                      "path"
                    ],
                    "additionalProperties": false
                  }
                },
                "bindings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "node": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Exact loaded GLB node name."
                      },
                      "source": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Named simulation signal."
                      },
                      "property": {
                        "type": "string",
                        "enum": [
                          "rotation",
                          "position",
                          "visible"
                        ],
                        "description": "Local transform or visibility channel."
                      },
                      "axis": {
                        "description": "Required for transforms; omit for visible.",
                        "type": "string",
                        "enum": [
                          "x",
                          "y",
                          "z"
                        ]
                      },
                      "scale": {
                        "description": "Multiply the signal by this value. Supply this or keys.",
                        "type": "number"
                      },
                      "offset": {
                        "description": "Offset after scaling; default zero.",
                        "type": "number"
                      },
                      "keys": {
                        "description": "Keyframed curve of [signal, displacement] pairs, signals strictly ascending; holds the end values outside them. Supply this or scale.",
                        "minItems": 2,
                        "type": "array",
                        "items": {
                          "type": "array",
                          "prefixItems": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "number"
                            }
                          ],
                          "items": false,
                          "minItems": 2,
                          "maxItems": 2
                        }
                      },
                      "ease": {
                        "description": "Interpolation between keys: linear (default), or smooth to ease out of and into every key.",
                        "type": "string",
                        "enum": [
                          "linear",
                          "smooth"
                        ]
                      },
                      "min": {
                        "description": "Minimum displacement from authored pose.",
                        "type": "number"
                      },
                      "max": {
                        "description": "Maximum displacement from authored pose.",
                        "type": "number"
                      },
                      "period": {
                        "description": "Rotation output wraps to [0, period); smoothing follows the shortest arc. Cannot combine with min/max.",
                        "type": "number",
                        "exclusiveMinimum": 0
                      },
                      "responseSeconds": {
                        "description": "First-order response time constant in simulation seconds; default zero. Requires a timestamp from the host.",
                        "type": "number",
                        "minimum": 0
                      },
                      "missing": {
                        "description": "Missing reading: hold last pose (default), restore authored pose, or hide a visible channel.",
                        "type": "string",
                        "enum": [
                          "hold",
                          "rest",
                          "hide"
                        ]
                      }
                    },
                    "required": [
                      "node",
                      "source",
                      "property"
                    ],
                    "additionalProperties": false
                  },
                  "description": "Per-model node channels and their signal calibration."
                },
                "derived": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "minLength": 1
                  },
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "op": {
                        "type": "string",
                        "enum": [
                          "add",
                          "subtract",
                          "multiply",
                          "divide",
                          "min",
                          "max",
                          "clamp",
                          "abs",
                          "sqrt",
                          "floor",
                          "modulo",
                          "sin",
                          "cos",
                          "atan2",
                          "less",
                          "greater",
                          "equal",
                          "and",
                          "or",
                          "not",
                          "if",
                          "coalesce"
                        ],
                        "description": "Numeric operation; comparisons/logic return 0 or 1. Angles are radians."
                      },
                      "args": {
                        "minItems": 1,
                        "maxItems": 16,
                        "type": "array",
                        "items": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "string",
                              "minLength": 1
                            }
                          ]
                        },
                        "description": "Finite numeric literals or names of signals, in operand order."
                      }
                    },
                    "required": [
                      "op",
                      "args"
                    ],
                    "additionalProperties": false
                  },
                  "description": "Up to 256 named data-only formulas, evaluated in dependency order. No cycles."
                }
              },
              "required": [
                "nodes",
                "bindings"
              ],
              "additionalProperties": false
            },
            "animation": {
              "description": "External animation setting.",
              "type": "object",
              "properties": {
                "sources": {
                  "description": "Optional component fields overriding or extending host telemetry.",
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "minLength": 1
                  },
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "component": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Component on this same entity."
                      },
                      "path": {
                        "minItems": 1,
                        "type": "array",
                        "items": {
                          "anyOf": [
                            {
                              "type": "string",
                              "minLength": 1
                            },
                            {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 9007199254740991
                            }
                          ]
                        },
                        "description": "Explicit property names or array indices leading to a number or boolean."
                      }
                    },
                    "required": [
                      "component",
                      "path"
                    ],
                    "additionalProperties": false
                  }
                },
                "bindings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "node": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Exact loaded GLB node name."
                      },
                      "source": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Named simulation signal."
                      },
                      "property": {
                        "type": "string",
                        "enum": [
                          "rotation",
                          "position",
                          "visible"
                        ],
                        "description": "Local transform or visibility channel."
                      },
                      "axis": {
                        "description": "Required for transforms; omit for visible.",
                        "type": "string",
                        "enum": [
                          "x",
                          "y",
                          "z"
                        ]
                      },
                      "scale": {
                        "description": "Multiply the signal by this value. Supply this or keys.",
                        "type": "number"
                      },
                      "offset": {
                        "description": "Offset after scaling; default zero.",
                        "type": "number"
                      },
                      "keys": {
                        "description": "Keyframed curve of [signal, displacement] pairs, signals strictly ascending; holds the end values outside them. Supply this or scale.",
                        "minItems": 2,
                        "type": "array",
                        "items": {
                          "type": "array",
                          "prefixItems": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "number"
                            }
                          ],
                          "items": false,
                          "minItems": 2,
                          "maxItems": 2
                        }
                      },
                      "ease": {
                        "description": "Interpolation between keys: linear (default), or smooth to ease out of and into every key.",
                        "type": "string",
                        "enum": [
                          "linear",
                          "smooth"
                        ]
                      },
                      "min": {
                        "description": "Minimum displacement from authored pose.",
                        "type": "number"
                      },
                      "max": {
                        "description": "Maximum displacement from authored pose.",
                        "type": "number"
                      },
                      "period": {
                        "description": "Rotation output wraps to [0, period); smoothing follows the shortest arc. Cannot combine with min/max.",
                        "type": "number",
                        "exclusiveMinimum": 0
                      },
                      "responseSeconds": {
                        "description": "First-order response time constant in simulation seconds; default zero. Requires a timestamp from the host.",
                        "type": "number",
                        "minimum": 0
                      },
                      "missing": {
                        "description": "Missing reading: hold last pose (default), restore authored pose, or hide a visible channel.",
                        "type": "string",
                        "enum": [
                          "hold",
                          "rest",
                          "hide"
                        ]
                      }
                    },
                    "required": [
                      "node",
                      "source",
                      "property"
                    ],
                    "additionalProperties": false
                  },
                  "description": "Per-model node channels and their signal calibration."
                },
                "derived": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "minLength": 1
                  },
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "op": {
                        "type": "string",
                        "enum": [
                          "add",
                          "subtract",
                          "multiply",
                          "divide",
                          "min",
                          "max",
                          "clamp",
                          "abs",
                          "sqrt",
                          "floor",
                          "modulo",
                          "sin",
                          "cos",
                          "atan2",
                          "less",
                          "greater",
                          "equal",
                          "and",
                          "or",
                          "not",
                          "if",
                          "coalesce"
                        ],
                        "description": "Numeric operation; comparisons/logic return 0 or 1. Angles are radians."
                      },
                      "args": {
                        "minItems": 1,
                        "maxItems": 16,
                        "type": "array",
                        "items": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "string",
                              "minLength": 1
                            }
                          ]
                        },
                        "description": "Finite numeric literals or names of signals, in operand order."
                      }
                    },
                    "required": [
                      "op",
                      "args"
                    ],
                    "additionalProperties": false
                  },
                  "description": "Up to 256 named data-only formulas, evaluated in dependency order. No cycles."
                }
              },
              "required": [
                "bindings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "rotors",
            "gearNodes",
            "flaps",
            "ailerons"
          ],
          "additionalProperties": false,
          "description": "External visual setting."
        }
      },
      "required": [
        "label",
        "model",
        "mass",
        "span",
        "length",
        "height",
        "centerOfMass",
        "pilotEye",
        "hardLandingSpeed",
        "hardLandingRoll",
        "hardLandingPitch",
        "maxSupportStep",
        "collisionProbes",
        "visual"
      ],
      "additionalProperties": false,
      "description": "Complete airplane or helicopter performance configuration."
    }
  },
  "required": [
    "kind",
    "spec"
  ],
  "additionalProperties": false
}

</details>

aircraftInput ​

Pilot flight controls. Power is retained when input keys are released.

Required: power, pitch, roll, yaw, brake, engine, gear, flaps

json
{
  "power": 0,
  "pitch": 0,
  "roll": 0,
  "yaw": 0,
  "brake": true,
  "engine": false,
  "gear": true,
  "flaps": false
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "actuators": {
      "description": "Mechanism targets from zero to one, or on/off selections.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 64,
        "pattern": "^[a-zA-Z][a-zA-Z0-9]*$"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "mixture": {
      "description": "Common mixture: 0 idle cutoff, 1 full rich (default).",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "propeller": {
      "description": "Common propeller lever: 0 minimum governed RPM, 1 maximum (default).",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "power": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Absolute throttle for a plane; collective for a helicopter."
    },
    "pitch": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Positive pulls the nose up."
    },
    "roll": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Positive banks right."
    },
    "yaw": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Positive rudder/pedals turns right."
    },
    "brake": {
      "type": "boolean",
      "description": "Ground wheel brake."
    },
    "engine": {
      "type": "boolean",
      "description": "Engine on; rotor/propeller spools over time."
    },
    "engines": {
      "description": "Per-engine pilot overrides by id. Failures live in aircraftState and cannot be cleared by pilot input.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
        "description": "Stable engine id, such as left or right; single-engine form uses main."
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "power": {
            "description": "Absolute throttle override; omitted inherits common power.",
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "mixture": {
            "description": "Individual mixture override; inherits common mixture.",
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "propeller": {
            "description": "Individual propeller RPM override; inherits common propeller.",
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "enabled": {
            "description": "Individual engine switch; common engine switch is the master cutoff.",
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    },
    "gear": {
      "type": "boolean",
      "description": "Landing gear extended; helicopter skids are fixed."
    },
    "flaps": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      ],
      "description": "Plane flap selection: boolean up/down or fraction 0..1."
    },
    "thrustVector": {
      "description": "Powered-lift lever: 0 forward to 1 vertical.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "cyclicMode": {
      "description": "Helicopter cyclic: assisted (default) commands a bounded, self-levelling tilt; direct commands pitch and roll rates with full authority (loops, rolls, straight down). Both are assisted on the ground.",
      "type": "string",
      "enum": [
        "assisted",
        "direct"
      ]
    }
  },
  "required": [
    "power",
    "pitch",
    "roll",
    "yaw",
    "brake",
    "engine",
    "gear",
    "flaps"
  ],
  "additionalProperties": false
}

</details>

aircraftState ​

Deterministic flight state, including rotor phase and engine spool, preserved by keyframes.

Required: velocity, yaw, pitch, roll, pitchRate, rollRate, rpm, rotorAngle, airspeed, altitudeAGL, verticalSpeed, angleOfAttack, stalled, grounded, crashed, waitingForTerrain

json
{
  "velocity": [
    0,
    0,
    0
  ],
  "yaw": 0,
  "pitch": 0,
  "roll": 0,
  "pitchRate": 0,
  "rollRate": 0,
  "rpm": 0,
  "rotorAngle": 0,
  "airspeed": 0,
  "altitudeAGL": 0,
  "verticalSpeed": 0,
  "angleOfAttack": 0,
  "stalled": false,
  "grounded": true,
  "crashed": false,
  "waitingForTerrain": false
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "actuators": {
      "description": "Current mechanism positions and cycle phases, from zero to one.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 64,
        "pattern": "^[a-zA-Z][a-zA-Z0-9]*$"
      },
      "additionalProperties": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "damage": {
      "description": "Persistent section integrity and separation, keyed by collision part id.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "integrity": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Remaining joint integrity, 0 broken to 1 intact."
          },
          "detached": {
            "type": "boolean",
            "description": "Section has separated and no longer supplies lift or collision probes."
          }
        },
        "required": [
          "integrity",
          "detached"
        ],
        "additionalProperties": false
      }
    },
    "debris": {
      "description": "Detached sections in world coordinates, simulated for 20 seconds. Their removal does not repair the aircraft.",
      "maxItems": 64,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "part": {
            "type": "string",
            "minLength": 1,
            "description": "Owning collision section id."
          },
          "pos": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Section center in world meters."
          },
          "rot": {
            "minItems": 4,
            "maxItems": 4,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "World-space section orientation quaternion."
          },
          "velocity": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "World velocity in m/s, inherited at separation including travel boost."
          },
          "angularVelocity": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Local angular velocity about +X, +Y and +Z, rad/s."
          },
          "age": {
            "type": "number",
            "minimum": 0,
            "description": "Simulated seconds since separation; expires at 20 seconds."
          }
        },
        "required": [
          "part",
          "pos",
          "rot",
          "velocity",
          "angularVelocity",
          "age"
        ],
        "additionalProperties": false
      }
    },
    "boosted": {
      "description": "Speeds include the 4× travel boost; kernel-owned.",
      "type": "boolean"
    },
    "mach": {
      "description": "True airspeed divided by local speed of sound.",
      "type": "number",
      "minimum": 0
    },
    "equivalentAirspeed": {
      "description": "Airspeed normalized to standard sea-level density, m/s; not calibrated IAS.",
      "type": "number",
      "minimum": 0
    },
    "overspeed": {
      "description": "An airframe, surface or rotor speed limit is exceeded; informational, not a speed clamp.",
      "type": "boolean"
    },
    "departure": {
      "description": "Developed high-alpha departure fraction.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "vortexRing": {
      "description": "Rotor vortex-ring severity in powered slow descent.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "velocity": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "World velocity in meters per second."
    },
    "yaw": {
      "type": "number",
      "description": "Heading in radians, zero +Z. Airplanes report it from transform.rot, which is authoritative."
    },
    "pitch": {
      "type": "number",
      "description": "Nose-up angle in radians (±π/2 at the vertical)."
    },
    "roll": {
      "type": "number",
      "description": "Right bank angle in radians; ±π inverted."
    },
    "pitchRate": {
      "type": "number",
      "description": "Body pitch rate, nose up, in radians per second."
    },
    "rollRate": {
      "type": "number",
      "description": "Body roll rate, right wing down, in radians per second."
    },
    "yawRate": {
      "description": "Airplane body yaw rate about local +Y (nose left), in rad/s.",
      "type": "number"
    },
    "elevator": {
      "description": "Airplane elevator position after its travel limit, -1..1.",
      "type": "number",
      "minimum": -1,
      "maximum": 1
    },
    "gearPosition": {
      "description": "Landing gear: 0 up and locked, 1 down and locked, between them in transit. Fixed undercarriages stay down.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "flapPosition": {
      "description": "Airplane flaps as a fraction of full travel, 0..1. Starts at the commanded position.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "pitchTrim": {
      "description": "Airplane trimmed angle of attack in radians, flown with the stick centered.",
      "type": "number"
    },
    "thrustVectorPosition": {
      "description": "Actual thrust-vector position after actuator travel, 0 forward to 1 vertical.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "sideslip": {
      "description": "Airplane sideslip in radians, positive with the relative wind from the left.",
      "type": "number"
    },
    "loadFactor": {
      "description": "Airplane aerodynamic and thrust load along its up axis, in g.",
      "type": "number"
    },
    "fuel": {
      "description": "Fuel remaining in kg when the aircraft declares fuel; absent is full tanks.",
      "type": "number",
      "minimum": 0
    },
    "buffet": {
      "description": "Airplane pre-stall and stalled-wing buffet, 0..1: a cue to shake the view, starting a few degrees before the stall.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "greyout": {
      "description": "Pilot strain under positive g, 0..1: vision starts to dim near 0.3 and is gone at 1.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "redout": {
      "description": "Pilot strain under negative g, 0..1.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "engines": {
      "description": "Authoritative individual spool, rotor phase, failure and thrust state; initialized by the solver.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
        "description": "Stable engine id, such as left or right; single-engine form uses main."
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "rpm": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "shaftPower": {
            "type": "number",
            "minimum": 0
          },
          "combustion": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "rotorAngle": {
            "type": "number"
          },
          "failed": {
            "type": "boolean"
          },
          "afterburner": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "thrust": {
            "type": "number",
            "minimum": 0,
            "description": "Current propeller thrust in newtons; zero for the helicopter shaft engine."
          }
        },
        "required": [
          "rpm",
          "rotorAngle",
          "failed",
          "thrust"
        ],
        "additionalProperties": false
      }
    },
    "rpm": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Maximum normalized RPM across all engines; used by common HUDs and exit checks."
    },
    "rotorAngle": {
      "type": "number",
      "description": "First engine rotor phase, wrapped in radians; bind visuals by engine id for independent phases."
    },
    "airspeed": {
      "type": "number",
      "minimum": 0,
      "description": "Speed relative to wind in meters per second."
    },
    "altitudeAGL": {
      "type": "number",
      "minimum": 0,
      "description": "Height above available terrain in meters."
    },
    "verticalSpeed": {
      "type": "number",
      "description": "Vertical velocity in meters per second."
    },
    "angleOfAttack": {
      "type": "number",
      "description": "Wing incidence relative to airflow in radians."
    },
    "stalled": {
      "type": "boolean",
      "description": "Wing beyond useful lift envelope."
    },
    "grounded": {
      "type": "boolean",
      "description": "Supported by landing surface."
    },
    "crashed": {
      "type": "boolean",
      "description": "Airframe damage requiring recovery. Motion continues under forces and collision impulses."
    },
    "waitingForTerrain": {
      "type": "boolean",
      "description": "Paused at last known position while terrain is unavailable."
    }
  },
  "required": [
    "velocity",
    "yaw",
    "pitch",
    "roll",
    "pitchRate",
    "rollRate",
    "rpm",
    "rotorAngle",
    "airspeed",
    "altitudeAGL",
    "verticalSpeed",
    "angleOfAttack",
    "stalled",
    "grounded",
    "crashed",
    "waitingForTerrain"
  ],
  "additionalProperties": false
}

</details>

Owner: kernel/boats ​

boat ​

Waterline-aligned powered hull with data-driven handling and shared seats.

Required: kind, spec, visual

json
{
  "kind": "demo.boat",
  "spec": {
    "label": "Launch",
    "length": 6,
    "width": 2.4,
    "height": 2,
    "draft": 0.5,
    "mass": 1200,
    "thrust": 3600,
    "maxSpeed": 14,
    "reverseSpeed": 3,
    "turnRate": 0.5,
    "turnResponse": 1,
    "lateralDrag": 2,
    "buoyancyFrequency": 1,
    "driverEye": [
      0.5,
      1.2,
      0
    ]
  },
  "visual": {
    "wheelNodes": [],
    "frontWheelNodes": [],
    "paintMaterial": "hull"
  }
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "minLength": 1,
      "description": "Stable external vessel entity/type id."
    },
    "spec": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable vessel name."
        },
        "length": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Hull length along Z in meters."
        },
        "width": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Hull width along X in meters."
        },
        "height": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Vessel height in meters."
        },
        "draft": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Minimum water depth in meters."
        },
        "mass": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Mass in kg."
        },
        "thrust": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Forward propeller thrust in newtons."
        },
        "maxSpeed": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Maximum forward speed through water in m/s."
        },
        "reverseSpeed": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Maximum reverse speed through water in m/s."
        },
        "turnRate": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Maximum cruise yaw rate in radians per second."
        },
        "turnResponse": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Time to build or lose yaw rate in seconds."
        },
        "lateralDrag": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Lateral water resistance per second."
        },
        "buoyancyFrequency": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 4,
          "description": "Buoyancy spring frequency in hertz."
        },
        "driverEye": {
          "type": "array",
          "prefixItems": [
            {
              "type": "number"
            },
            {
              "type": "number"
            },
            {
              "type": "number"
            }
          ],
          "items": false,
          "minItems": 3,
          "maxItems": 3,
          "description": "Helm eye position in local meters."
        }
      },
      "required": [
        "label",
        "length",
        "width",
        "height",
        "draft",
        "mass",
        "thrust",
        "maxSpeed",
        "reverseSpeed",
        "turnRate",
        "turnResponse",
        "lateralDrag",
        "buoyancyFrequency",
        "driverEye"
      ],
      "additionalProperties": false,
      "description": "Complete hull dimensions and handling configuration."
    },
    "visual": {
      "type": "object",
      "properties": {
        "wheelNodes": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Wheel nodes; empty for ordinary hulls."
        },
        "frontWheelNodes": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Steering wheel nodes; usually empty."
        },
        "steeringWheelNode": {
          "description": "External steeringWheelNode setting.",
          "type": "string",
          "minLength": 1
        },
        "paintMaterial": {
          "type": "string",
          "minLength": 1,
          "description": "External paintMaterial setting."
        },
        "interior": {
          "description": "External interior setting.",
          "type": "object",
          "properties": {
            "nodes": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Cabin nodes in the same exterior/interior GLB."
            },
            "sources": {
              "description": "Optional component fields overriding or extending host telemetry.",
              "type": "object",
              "propertyNames": {
                "type": "string",
                "minLength": 1
              },
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "component": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Component on this same entity."
                  },
                  "path": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 1
                        },
                        {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        }
                      ]
                    },
                    "description": "Explicit property names or array indices leading to a number or boolean."
                  }
                },
                "required": [
                  "component",
                  "path"
                ],
                "additionalProperties": false
              }
            },
            "bindings": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "node": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Exact loaded GLB node name."
                  },
                  "source": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Named simulation signal."
                  },
                  "property": {
                    "type": "string",
                    "enum": [
                      "rotation",
                      "position",
                      "visible"
                    ],
                    "description": "Local transform or visibility channel."
                  },
                  "axis": {
                    "description": "Required for transforms; omit for visible.",
                    "type": "string",
                    "enum": [
                      "x",
                      "y",
                      "z"
                    ]
                  },
                  "scale": {
                    "description": "Multiply the signal by this value. Supply this or keys.",
                    "type": "number"
                  },
                  "offset": {
                    "description": "Offset after scaling; default zero.",
                    "type": "number"
                  },
                  "keys": {
                    "description": "Keyframed curve of [signal, displacement] pairs, signals strictly ascending; holds the end values outside them. Supply this or scale.",
                    "minItems": 2,
                    "type": "array",
                    "items": {
                      "type": "array",
                      "prefixItems": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "number"
                        }
                      ],
                      "items": false,
                      "minItems": 2,
                      "maxItems": 2
                    }
                  },
                  "ease": {
                    "description": "Interpolation between keys: linear (default), or smooth to ease out of and into every key.",
                    "type": "string",
                    "enum": [
                      "linear",
                      "smooth"
                    ]
                  },
                  "min": {
                    "description": "Minimum displacement from authored pose.",
                    "type": "number"
                  },
                  "max": {
                    "description": "Maximum displacement from authored pose.",
                    "type": "number"
                  },
                  "period": {
                    "description": "Rotation output wraps to [0, period); smoothing follows the shortest arc. Cannot combine with min/max.",
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "responseSeconds": {
                    "description": "First-order response time constant in simulation seconds; default zero. Requires a timestamp from the host.",
                    "type": "number",
                    "minimum": 0
                  },
                  "missing": {
                    "description": "Missing reading: hold last pose (default), restore authored pose, or hide a visible channel.",
                    "type": "string",
                    "enum": [
                      "hold",
                      "rest",
                      "hide"
                    ]
                  }
                },
                "required": [
                  "node",
                  "source",
                  "property"
                ],
                "additionalProperties": false
              },
              "description": "Per-model node channels and their signal calibration."
            },
            "derived": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "minLength": 1
              },
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "op": {
                    "type": "string",
                    "enum": [
                      "add",
                      "subtract",
                      "multiply",
                      "divide",
                      "min",
                      "max",
                      "clamp",
                      "abs",
                      "sqrt",
                      "floor",
                      "modulo",
                      "sin",
                      "cos",
                      "atan2",
                      "less",
                      "greater",
                      "equal",
                      "and",
                      "or",
                      "not",
                      "if",
                      "coalesce"
                    ],
                    "description": "Numeric operation; comparisons/logic return 0 or 1. Angles are radians."
                  },
                  "args": {
                    "minItems": 1,
                    "maxItems": 16,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "string",
                          "minLength": 1
                        }
                      ]
                    },
                    "description": "Finite numeric literals or names of signals, in operand order."
                  }
                },
                "required": [
                  "op",
                  "args"
                ],
                "additionalProperties": false
              },
              "description": "Up to 256 named data-only formulas, evaluated in dependency order. No cycles."
            }
          },
          "required": [
            "nodes",
            "bindings"
          ],
          "additionalProperties": false
        },
        "animation": {
          "description": "External animation setting.",
          "type": "object",
          "properties": {
            "sources": {
              "description": "Optional component fields overriding or extending host telemetry.",
              "type": "object",
              "propertyNames": {
                "type": "string",
                "minLength": 1
              },
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "component": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Component on this same entity."
                  },
                  "path": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 1
                        },
                        {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        }
                      ]
                    },
                    "description": "Explicit property names or array indices leading to a number or boolean."
                  }
                },
                "required": [
                  "component",
                  "path"
                ],
                "additionalProperties": false
              }
            },
            "bindings": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "node": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Exact loaded GLB node name."
                  },
                  "source": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Named simulation signal."
                  },
                  "property": {
                    "type": "string",
                    "enum": [
                      "rotation",
                      "position",
                      "visible"
                    ],
                    "description": "Local transform or visibility channel."
                  },
                  "axis": {
                    "description": "Required for transforms; omit for visible.",
                    "type": "string",
                    "enum": [
                      "x",
                      "y",
                      "z"
                    ]
                  },
                  "scale": {
                    "description": "Multiply the signal by this value. Supply this or keys.",
                    "type": "number"
                  },
                  "offset": {
                    "description": "Offset after scaling; default zero.",
                    "type": "number"
                  },
                  "keys": {
                    "description": "Keyframed curve of [signal, displacement] pairs, signals strictly ascending; holds the end values outside them. Supply this or scale.",
                    "minItems": 2,
                    "type": "array",
                    "items": {
                      "type": "array",
                      "prefixItems": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "number"
                        }
                      ],
                      "items": false,
                      "minItems": 2,
                      "maxItems": 2
                    }
                  },
                  "ease": {
                    "description": "Interpolation between keys: linear (default), or smooth to ease out of and into every key.",
                    "type": "string",
                    "enum": [
                      "linear",
                      "smooth"
                    ]
                  },
                  "min": {
                    "description": "Minimum displacement from authored pose.",
                    "type": "number"
                  },
                  "max": {
                    "description": "Maximum displacement from authored pose.",
                    "type": "number"
                  },
                  "period": {
                    "description": "Rotation output wraps to [0, period); smoothing follows the shortest arc. Cannot combine with min/max.",
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "responseSeconds": {
                    "description": "First-order response time constant in simulation seconds; default zero. Requires a timestamp from the host.",
                    "type": "number",
                    "minimum": 0
                  },
                  "missing": {
                    "description": "Missing reading: hold last pose (default), restore authored pose, or hide a visible channel.",
                    "type": "string",
                    "enum": [
                      "hold",
                      "rest",
                      "hide"
                    ]
                  }
                },
                "required": [
                  "node",
                  "source",
                  "property"
                ],
                "additionalProperties": false
              },
              "description": "Per-model node channels and their signal calibration."
            },
            "derived": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "minLength": 1
              },
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "op": {
                    "type": "string",
                    "enum": [
                      "add",
                      "subtract",
                      "multiply",
                      "divide",
                      "min",
                      "max",
                      "clamp",
                      "abs",
                      "sqrt",
                      "floor",
                      "modulo",
                      "sin",
                      "cos",
                      "atan2",
                      "less",
                      "greater",
                      "equal",
                      "and",
                      "or",
                      "not",
                      "if",
                      "coalesce"
                    ],
                    "description": "Numeric operation; comparisons/logic return 0 or 1. Angles are radians."
                  },
                  "args": {
                    "minItems": 1,
                    "maxItems": 16,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "string",
                          "minLength": 1
                        }
                      ]
                    },
                    "description": "Finite numeric literals or names of signals, in operand order."
                  }
                },
                "required": [
                  "op",
                  "args"
                ],
                "additionalProperties": false
              },
              "description": "Up to 256 named data-only formulas, evaluated in dependency order. No cycles."
            }
          },
          "required": [
            "bindings"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "wheelNodes",
        "frontWheelNodes",
        "paintMaterial"
      ],
      "additionalProperties": false,
      "description": "Named GLB nodes, material and animation bindings."
    },
    "color": {
      "description": "Optional hull paint override.",
      "type": "string"
    }
  },
  "required": [
    "kind",
    "spec",
    "visual"
  ],
  "additionalProperties": false
}

</details>

boatInput ​

Helm intent: signed thrust, steering and low-speed anchor. Only the driver controls it.

Required: throttle, steering, anchor

json
{
  "throttle": 0,
  "steering": 0,
  "anchor": true
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "throttle": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Signed propeller power; negative reverses thrust."
    },
    "steering": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Signed helm input; positive turns right."
    },
    "anchor": {
      "type": "boolean",
      "description": "Request the low-speed anchor; release to apply thrust."
    }
  },
  "required": [
    "throttle",
    "steering",
    "anchor"
  ],
  "additionalProperties": false
}

</details>

boatState ​

Snapshot-safe hull motion, buoyancy and anchoring; owned by installBoats.

Required: speed, lateralSpeed, velocity, yaw, yawRate, steer, pitch, roll, vy, anchored, grounded, waitingForWater

json
{
  "speed": 0,
  "lateralSpeed": 0,
  "velocity": [
    0,
    0
  ],
  "yaw": 0,
  "yawRate": 0,
  "steer": 0,
  "pitch": 0,
  "roll": 0,
  "vy": 0,
  "anchored": true,
  "grounded": false,
  "waitingForWater": false
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "boosted": {
      "description": "Horizontal speeds include the 4× travel boost.",
      "type": "boolean"
    },
    "speed": {
      "type": "number",
      "description": "Forward speed through water in m/s."
    },
    "lateralSpeed": {
      "type": "number",
      "description": "Lateral speed through water in m/s."
    },
    "velocity": {
      "type": "array",
      "prefixItems": [
        {
          "type": "number"
        },
        {
          "type": "number"
        }
      ],
      "items": false,
      "minItems": 2,
      "maxItems": 2,
      "description": "World velocity [east, south] including current in m/s."
    },
    "yaw": {
      "type": "number",
      "description": "Heading about +Y in radians."
    },
    "yawRate": {
      "type": "number",
      "description": "Yaw rate in radians per second."
    },
    "steer": {
      "type": "number",
      "description": "Smoothed helm input in [-1, 1]."
    },
    "pitch": {
      "type": "number",
      "description": "Hull pitch in radians."
    },
    "roll": {
      "type": "number",
      "description": "Hull roll in radians."
    },
    "vy": {
      "type": "number",
      "description": "Vertical buoyancy velocity in m/s."
    },
    "anchored": {
      "type": "boolean",
      "description": "Whether the low-speed anchor is engaged."
    },
    "grounded": {
      "type": "boolean",
      "description": "Whether the hull is stopped by insufficient depth."
    },
    "waitingForWater": {
      "type": "boolean",
      "description": "Whether motion is paused for unavailable water data."
    }
  },
  "required": [
    "speed",
    "lateralSpeed",
    "velocity",
    "yaw",
    "yawRate",
    "steer",
    "pitch",
    "roll",
    "vy",
    "anchored",
    "grounded",
    "waitingForWater"
  ],
  "additionalProperties": false
}

</details>

water ​

Deterministic swells and current for boats; heights and coverage come from the host water field.

Required: none

json
{
  "waves": [],
  "current": [
    0,
    0
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "waves": {
      "description": "Up to eight travelling swells added to the water surface.",
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amplitude": {
            "type": "number",
            "minimum": 0,
            "maximum": 10,
            "description": "Swell amplitude in meters."
          },
          "wavelength": {
            "type": "number",
            "minimum": 1,
            "description": "Wavelength in meters."
          },
          "direction": {
            "type": "number",
            "description": "Travel direction in radians; zero is +Z."
          },
          "speed": {
            "type": "number",
            "minimum": 0,
            "description": "Wave propagation speed in m/s."
          }
        },
        "required": [
          "amplitude",
          "wavelength",
          "direction",
          "speed"
        ],
        "additionalProperties": false
      }
    },
    "current": {
      "description": "Current [east, south] in m/s.",
      "type": "array",
      "prefixItems": [
        {
          "type": "number"
        },
        {
          "type": "number"
        }
      ],
      "items": false,
      "minItems": 2,
      "maxItems": 2
    }
  },
  "additionalProperties": false
}

</details>

Owner: kernel/character ​

character ​

Kinematic character controller state (speed/jump/gravity + kernel-owned vy/grounded).

Required: speed, jumpSpeed, gravity, vy, grounded

json
{
  "speed": 6,
  "jumpSpeed": 8,
  "gravity": 20,
  "vy": 0,
  "grounded": true
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "speed": {
      "type": "number",
      "description": "Planar move speed in meters per second."
    },
    "jumpSpeed": {
      "type": "number",
      "description": "Initial upward velocity in meters per second applied when jumping from the ground."
    },
    "gravity": {
      "type": "number",
      "description": "Downward acceleration in meters per second squared applied to vy each tick."
    },
    "vy": {
      "type": "number",
      "description": "Current vertical velocity in meters per second (kernel-owned)."
    },
    "grounded": {
      "type": "boolean",
      "description": "True when the character stood on the ground as of the last tick (kernel-owned)."
    }
  },
  "required": [
    "speed",
    "jumpSpeed",
    "gravity",
    "vy",
    "grounded"
  ],
  "additionalProperties": false
}

</details>

moveIntent ​

Desired planar move direction + jump flag, consumed by the character controller.

Required: dir, jump

json
{
  "dir": [
    1,
    0
  ],
  "jump": false
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "dir": {
      "minItems": 2,
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Desired planar move direction [x, z]: +x east, +z south (screen-down in top-down views); magnitudes above 1 are normalized."
    },
    "jump": {
      "type": "boolean",
      "description": "Request a jump this tick (honored only while grounded)."
    }
  },
  "required": [
    "dir",
    "jump"
  ],
  "additionalProperties": false
}

</details>

Owner: kernel/gameplay ​

fsm ​

Minimal event-driven state machine: transitions fire on world events targeting the entity.

Required: state, transitions

json
{
  "state": "idle",
  "transitions": [
    {
      "from": "idle",
      "event": "player_seen",
      "to": "aggro"
    }
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "minLength": 1,
      "description": "Current state name."
    },
    "transitions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "minLength": 1,
            "description": "State the transition leaves ('*' matches any state)."
          },
          "event": {
            "type": "string",
            "minLength": 1,
            "description": "World event type that triggers the transition (events with payload.entity only match that entity)."
          },
          "to": {
            "type": "string",
            "minLength": 1,
            "description": "State entered."
          }
        },
        "required": [
          "from",
          "event",
          "to"
        ],
        "additionalProperties": false
      },
      "description": "Transition table, checked in order; the first match wins."
    }
  },
  "required": [
    "state",
    "transitions"
  ],
  "additionalProperties": false
}

</details>

localTransform ​

Parent-relative transform for entities carrying parent.

Required: pos

json
{
  "pos": [
    0,
    1,
    0
  ],
  "rot": [
    0,
    0,
    0,
    1
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pos": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Parent-relative position [x, y, z] in meters (Y-up)."
    },
    "rot": {
      "minItems": 4,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Parent-relative orientation quaternion [x, y, z, w]; defaults to identity [0, 0, 0, 1]."
    },
    "scale": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Per-axis scale factors [x, y, z]; defaults to [1, 1, 1]."
    },
    "teleport": {
      "type": "boolean",
      "description": "Client interpolation hint: when true the client snaps to this update instead of lerping from the previous tick."
    }
  },
  "required": [
    "pos"
  ],
  "additionalProperties": false
}

</details>

parent ​

Attach to a parent entity: transform becomes parent.transform × localTransform each tick.

Required: id

json
{
  "id": "turret-base"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Entity id of the parent."
    },
    "onParentDestroyed": {
      "type": "string",
      "enum": [
        "destroy",
        "detach"
      ],
      "description": "When the parent is destroyed: destroy this entity too (default, cascading) or detach it and keep it alive."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

</details>

timer ​

Snapshot-safe countdown timers that emit events (one-shot or repeating). Replaces callbacks.

Required: timers

json
{
  "timers": [
    {
      "id": "respawn",
      "ticksLeft": 90,
      "event": "respawn_ready"
    }
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "timers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "description": "Timer id, unique within this entity."
          },
          "ticksLeft": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "Ticks until the timer fires; decremented each tick."
          },
          "event": {
            "type": "string",
            "minLength": 1,
            "description": "World event type emitted when the timer fires (payload carries entity + timerId)."
          },
          "payload": {
            "description": "Optional JSON payload included in the emitted event.",
            "$ref": "#/$defs/__schema0"
          },
          "repeatEvery": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "If set, the timer re-arms with this many ticks after firing (repeating)."
          }
        },
        "required": [
          "id",
          "ticksLeft",
          "event"
        ],
        "additionalProperties": false
      },
      "description": "Active timers on this entity."
    }
  },
  "required": [
    "timers"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

</details>

tween ​

Data-driven value animation over ticks: component + select-style path, lerp with easing.

Required: tweens

json
{
  "tweens": [
    {
      "component": "transform",
      "path": "pos[1]",
      "to": 4,
      "ticks": 30,
      "easing": "quadOut"
    }
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "tweens": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "description": "Optional tween id."
          },
          "component": {
            "type": "string",
            "minLength": 1,
            "description": "Name of the component whose value is animated."
          },
          "path": {
            "type": "string",
            "minLength": 1,
            "description": "Select-style value path within the component, e.g. 'pos', 'pos[1]', or 'primitive.size'."
          },
          "from": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "array",
                "items": {
                  "type": "number"
                }
              }
            ],
            "description": "Start value (number or number array); defaults to the current value when the tween starts."
          },
          "to": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "array",
                "items": {
                  "type": "number"
                }
              }
            ],
            "description": "End value (number or number array, same arity as from)."
          },
          "ticks": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "Duration in ticks."
          },
          "elapsed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Ticks elapsed so far (kernel-owned; starts at 0)."
          },
          "easing": {
            "type": "string",
            "enum": [
              "linear",
              "quadIn",
              "quadOut",
              "quadInOut",
              "cubicIn",
              "cubicOut",
              "cubicInOut"
            ],
            "description": "Easing curve (default linear)."
          },
          "loop": {
            "type": "string",
            "enum": [
              "none",
              "loop",
              "pingpong"
            ],
            "description": "After completing: none (remove, default), loop (restart from `from`), or pingpong (swap from/to)."
          },
          "emitOnComplete": {
            "type": "string",
            "description": "World event type emitted (payload { entity }) each time the tween completes."
          }
        },
        "required": [
          "component",
          "path",
          "to",
          "ticks"
        ],
        "additionalProperties": false
      },
      "description": "Active tweens on this entity."
    }
  },
  "required": [
    "tweens"
  ],
  "additionalProperties": false
}

</details>

Owner: kernel/glass ​

glass ​

Breakable glass surfaces with metric geometry, material fracture and independent frame/interlayer retention.

Required: surfaces

json
{
  "surfaces": [
    {
      "id": "windshield",
      "material": "laminated",
      "center": [
        0,
        1.2,
        0.8
      ],
      "rotation": [
        0,
        0,
        0,
        1
      ],
      "size": [
        1.4,
        0.7
      ],
      "thickness": 0.005
    }
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "surfaces": {
      "minItems": 1,
      "maxItems": 64,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Stable pane id, unique on its owner."
          },
          "material": {
            "type": "string",
            "enum": [
              "laminated",
              "tempered",
              "annealed"
            ],
            "description": "Laminated retains cracked glass; tempered releases granules; annealed releases larger shards."
          },
          "center": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number"
              },
              {
                "type": "number"
              },
              {
                "type": "number"
              }
            ],
            "items": false,
            "minItems": 3,
            "maxItems": 3,
            "description": "Pane center in owner coordinates, meters."
          },
          "rotation": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number"
              },
              {
                "type": "number"
              },
              {
                "type": "number"
              },
              {
                "type": "number"
              }
            ],
            "items": false,
            "minItems": 4,
            "maxItems": 4,
            "description": "Pane XY orientation in owner coordinates, unit quaternion."
          },
          "size": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number",
                "exclusiveMinimum": 0
              },
              {
                "type": "number",
                "exclusiveMinimum": 0
              }
            ],
            "items": false,
            "minItems": 2,
            "maxItems": 2,
            "description": "Width and height in meters."
          },
          "thickness": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Total glass thickness, meters; interlayer thickness excluded."
          },
          "density": {
            "description": "Glass density, kg/m³; default 2500.",
            "type": "number",
            "exclusiveMinimum": 0
          },
          "strength": {
            "description": "Effective bending failure stress, Pa. Defaults: tempered 120e6, others 45e6. Simulation tuning, not certification.",
            "type": "number",
            "exclusiveMinimum": 0
          },
          "fractureEnergy": {
            "description": "Post-initiation fracture work, J/m²; default 80.",
            "type": "number",
            "exclusiveMinimum": 0
          },
          "retentionForce": {
            "description": "Frame/interlayer failure force, N; default 4000 times pane perimeter in meters.",
            "type": "number",
            "exclusiveMinimum": 0
          },
          "retentionEnergy": {
            "description": "Work to lose frame/interlayer retention, J; default 3000 times area in m².",
            "type": "number",
            "exclusiveMinimum": 0
          },
          "nodes": {
            "description": "Dedicated glass mesh/group names; omit for a generated rectangular pane. Never bind a whole vehicle or a shared body mesh.",
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "required": [
          "id",
          "material",
          "center",
          "rotation",
          "size",
          "thickness"
        ],
        "additionalProperties": false
      },
      "description": "Physical glass panes and their model bindings."
    },
    "crashPulseSeconds": {
      "description": "Duration of the vehicle crash pulse, seconds; default 0.06, independent of tick rate.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1
    }
  },
  "required": [
    "surfaces"
  ],
  "additionalProperties": false
}

</details>

glassState ​

Persistent glass fracture, retention and release state. Missing panes are intact; remove the component to repair.

Required: surfaces

json
{
  "surfaces": {}
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "surfaces": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "fracture": {
            "type": "string",
            "enum": [
              "intact",
              "cracked",
              "shattered"
            ]
          },
          "retained": {
            "type": "boolean"
          },
          "damage": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "retentionDamage": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "peakStress": {
            "type": "number",
            "minimum": 0,
            "description": "Largest resolved bending stress in Pa."
          },
          "point": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number"
              },
              {
                "type": "number"
              }
            ],
            "items": false,
            "minItems": 2,
            "maxItems": 2
          },
          "release": {
            "description": "Snapshot-safe initial world pose, velocity and simulation time for cosmetic debris.",
            "type": "object",
            "properties": {
              "time": {
                "type": "number",
                "minimum": 0
              },
              "position": {
                "type": "array",
                "prefixItems": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "number"
                  }
                ],
                "items": false,
                "minItems": 3,
                "maxItems": 3
              },
              "rotation": {
                "type": "array",
                "prefixItems": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "number"
                  }
                ],
                "items": false,
                "minItems": 4,
                "maxItems": 4
              },
              "velocity": {
                "type": "array",
                "prefixItems": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "number"
                  }
                ],
                "items": false,
                "minItems": 3,
                "maxItems": 3
              },
              "fragmentSpeed": {
                "description": "Energy-limited cosmetic fragment dispersion speed, m/s.",
                "type": "number",
                "minimum": 0
              }
            },
            "required": [
              "time",
              "position",
              "rotation",
              "velocity"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "fracture",
          "retained",
          "damage",
          "retentionDamage",
          "peakStress",
          "point"
        ],
        "additionalProperties": false
      },
      "description": "Per-pane fracture, retention and release state keyed by surface id."
    }
  },
  "required": [
    "surfaces"
  ],
  "additionalProperties": false
}

</details>

Owner: kernel/kinematics ​

collider ​

2.5D kinematic collider (circle or XZ AABB) with layer/mask bitmasks.

Required: (shape="circle": shape, layer, mask) or (shape="aabb": shape, layer, mask)

json
{
  "shape": "circle",
  "radius": 0.5,
  "layer": 1,
  "mask": 1
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "shape": {
          "type": "string",
          "const": "circle",
          "description": "Circle collider in the XZ plane."
        },
        "radius": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Circle radius in meters (default 0.5)."
        },
        "layer": {
          "type": "integer",
          "minimum": 0,
          "maximum": 4294967295,
          "description": "Bitmask of collision layers this collider belongs to; a collides with b when (a.mask & b.layer) or (b.mask & a.layer) is non-zero."
        },
        "mask": {
          "type": "integer",
          "minimum": 0,
          "maximum": 4294967295,
          "description": "Bitmask of layers this collider collides with (see layer for the rule)."
        },
        "isStatic": {
          "type": "boolean",
          "description": "Static colliders never move and are never pushed by other bodies."
        }
      },
      "required": [
        "shape",
        "layer",
        "mask"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "shape": {
          "type": "string",
          "const": "aabb",
          "description": "Axis-aligned box collider in the XZ plane."
        },
        "halfExtents": {
          "minItems": 2,
          "maxItems": 2,
          "type": "array",
          "items": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "description": "Half-extents [x, z] in meters of the box in the XZ plane (2.5D; default [0.5, 0.5])."
        },
        "layer": {
          "type": "integer",
          "minimum": 0,
          "maximum": 4294967295,
          "description": "Bitmask of collision layers this collider belongs to; a collides with b when (a.mask & b.layer) or (b.mask & a.layer) is non-zero."
        },
        "mask": {
          "type": "integer",
          "minimum": 0,
          "maximum": 4294967295,
          "description": "Bitmask of layers this collider collides with (see layer for the rule)."
        },
        "isStatic": {
          "type": "boolean",
          "description": "Static colliders never move and are never pushed by other bodies."
        }
      },
      "required": [
        "shape",
        "layer",
        "mask"
      ],
      "additionalProperties": false
    }
  ]
}

</details>

kinematicBody ​

Velocity-driven body for the kinematic collision layer.

Required: vel, slide

json
{
  "vel": [
    0,
    0,
    0
  ],
  "slide": true
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "vel": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Velocity [x, y, z] in meters per second, integrated each tick (dt = 1/tickRate)."
    },
    "slide": {
      "type": "boolean",
      "description": "When true, blocked motion slides along the contact surface instead of stopping."
    }
  },
  "required": [
    "vel",
    "slide"
  ],
  "additionalProperties": false
}

</details>

Owner: kernel/vehicles ​

coupled ​

A rail car in a consist: rides the leader's track trail at a fixed distance behind it, sharing its speed. Powered cars add their traction to the leader's (multiple-unit control); every car adds its mass and brakes.

Required: leader, offset

json
{
  "leader": "train-1-loco",
  "offset": 21.5
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "leader": {
      "type": "string",
      "minLength": 1,
      "description": "Entity ID of the track-guided vehicle at the head of the consist."
    },
    "offset": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Distance in meters along the track from the leader's centre back to this car's centre."
    }
  },
  "required": [
    "leader",
    "offset"
  ],
  "additionalProperties": false
}

</details>

mountable ​

Mount points in local meters, ordered safe exit candidates, and interaction reach. Seat position is the rider camera anchor.

Required: seats, exits, reach

json
{
  "seats": [
    {
      "id": "driver",
      "role": "driver",
      "position": [
        0.4,
        1.14,
        0.25
      ]
    }
  ],
  "exits": [
    [
      -1.56,
      0,
      0.25
    ],
    [
      1.56,
      0,
      0.25
    ]
  ],
  "reach": 3
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "seats": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "description": "Unique seat identifier within this mount."
          },
          "role": {
            "type": "string",
            "enum": [
              "driver",
              "passenger"
            ],
            "description": "Only a driver seat grants vehicle control."
          },
          "position": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Local rider/camera anchor in meters, transformed by the chassis quaternion."
          }
        },
        "required": [
          "id",
          "role",
          "position"
        ],
        "additionalProperties": false
      },
      "description": "Available seat definitions. Each seat can hold one actor."
    },
    "entries": {
      "description": "Optional boarding points in local meters, e.g. a boat gangway; seat anchors remain valid entry points.",
      "minItems": 1,
      "type": "array",
      "items": {
        "minItems": 3,
        "maxItems": 3,
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    },
    "exits": {
      "minItems": 1,
      "type": "array",
      "items": {
        "minItems": 3,
        "maxItems": 3,
        "type": "array",
        "items": {
          "type": "number"
        }
      },
      "description": "Ordered local foot positions to check when dismounting."
    },
    "reach": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Maximum distance in meters from the actor to the seat to enter."
    }
  },
  "required": [
    "seats",
    "exits",
    "reach"
  ],
  "additionalProperties": false
}

</details>

mounted ​

Rider-to-mount relationship. Occupied seats are exclusive; mounted characters bypass walking physics.

Required: vehicle, seat

json
{
  "vehicle": "car-1",
  "seat": "driver"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "vehicle": {
      "type": "string",
      "minLength": 1,
      "description": "Entity ID of the mount."
    },
    "seat": {
      "type": "string",
      "minLength": 1,
      "description": "Occupied seat ID in the mountable component."
    }
  },
  "required": [
    "vehicle",
    "seat"
  ],
  "additionalProperties": false
}

</details>

vehicle ​

External wheeled-vehicle instance: stable id, paint, complete physics tuning, and GLB bindings.

Required: kind, color, spec, visual

json
{
  "kind": "example.vehicle",
  "color": "#566d82",
  "spec": {
    "label": "Example car",
    "width": 1.8,
    "length": 4.6,
    "height": 1.5,
    "centerOfMass": [
      0,
      0.55,
      0
    ],
    "wheelbase": 2.75,
    "wheelTrack": 1.5,
    "wheelRadius": 0.31,
    "mass": 1450,
    "engineForce": 6200,
    "maxSpeed": 42,
    "reverseSpeed": 8,
    "brakeDeceleration": 9.5,
    "maxSteer": 0.56,
    "grip": 8,
    "driverEye": [
      0.4,
      1.14,
      0.25
    ],
    "steeringRate": 1.8,
    "steeringFadeSpeed": 18,
    "rollingResistance": 0.15,
    "aerodynamicResistance": 0.0025,
    "terrainAlignRate": 1.8,
    "supportTolerance": 0.08,
    "maxStepHeight": 0.4,
    "maxSlope": 0.61
  },
  "visual": {
    "wheelNodes": [
      "wheel-front-left"
    ],
    "frontWheelNodes": [
      "wheel-front-left"
    ],
    "steeringWheelNode": "steering-wheel",
    "paintMaterial": "vehicle-paint-and-trim"
  }
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "minLength": 1,
      "description": "Stable external entity/type id."
    },
    "color": {
      "type": "string",
      "pattern": "^#[0-9a-fA-F]{6}$",
      "description": "Body paint as an sRGB #rrggbb color."
    },
    "spec": {
      "type": "object",
      "properties": {
        "collisionParts": {
          "description": "Independent wheels, panels and engines: model-space sphere probes, joint strength in m/s and GLB node ownership.",
          "maxItems": 64,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
                "description": "Unique part id used by damage and debris state."
              },
              "role": {
                "type": "string",
                "enum": [
                  "frontWheel",
                  "rearWheel",
                  "panel",
                  "engine"
                ],
                "description": "Wheel axle, exterior panel or drivetrain role."
              },
              "hinge": {
                "description": "Panel hinge driven by the named vehicle actuator.",
                "type": "object",
                "properties": {
                  "pivot": {
                    "minItems": 3,
                    "maxItems": 3,
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Hinge pivot in model coordinates, meters."
                  },
                  "axis": {
                    "minItems": 3,
                    "maxItems": 3,
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Unit hinge axis in model coordinates."
                  },
                  "angle": {
                    "type": "number",
                    "description": "Hinge rotation in radians at full actuator travel."
                  },
                  "actuator": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Vehicle actuator id supplying hinge travel."
                  }
                },
                "required": [
                  "pivot",
                  "axis",
                  "angle",
                  "actuator"
                ],
                "additionalProperties": false
              },
              "center": {
                "minItems": 3,
                "maxItems": 3,
                "type": "array",
                "items": {
                  "type": "number"
                },
                "description": "Debris origin in model coordinates, meters."
              },
              "probes": {
                "minItems": 1,
                "maxItems": 64,
                "type": "array",
                "items": {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                "description": "Sphere centers in model coordinates, meters."
              },
              "radius": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "Probe and debris collision radius, meters."
              },
              "massFraction": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1,
                "description": "Share of the original mass removed on separation."
              },
              "breakSpeed": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "Normal impact speed that breaks an intact joint, m/s."
              },
              "nodes": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                },
                "description": "Exact GLB node names owned by this part."
              }
            },
            "required": [
              "id",
              "role",
              "center",
              "probes",
              "radius",
              "massFraction",
              "breakSpeed",
              "nodes"
            ],
            "additionalProperties": false
          }
        },
        "actuators": {
          "description": "External actuators setting.",
          "type": "object",
          "propertyNames": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[a-zA-Z][a-zA-Z0-9]*$"
          },
          "additionalProperties": {
            "type": "object",
            "properties": {
              "seconds": {
                "type": "number",
                "minimum": 0,
                "description": "Seconds for full travel or a full cycle."
              },
              "initial": {
                "description": "Rest position or phase; defaults to zero.",
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "mode": {
                "description": "Position by default. Cycles park when off; latches cannot reverse.",
                "type": "string",
                "enum": [
                  "position",
                  "cycle",
                  "latch"
                ]
              }
            },
            "required": [
              "seconds"
            ],
            "additionalProperties": false
          }
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "External label setting."
        },
        "bodyStyle": {
          "description": "External bodyStyle setting.",
          "type": "string",
          "enum": [
            "city",
            "hatchback",
            "sedan",
            "fastback",
            "coupe",
            "roadster",
            "wagon",
            "crossover",
            "suv",
            "offroad",
            "pickup",
            "van",
            "cargo-van",
            "box-truck",
            "motorhome",
            "bus",
            "light-rail",
            "locomotive",
            "freight-car",
            "passenger-car",
            "bicycle",
            "motorcycle",
            "scooter",
            "moped",
            "kick-scooter",
            "skateboard",
            "auto-rickshaw",
            "skis",
            "snowboard",
            "snowmobile"
          ]
        },
        "genericLabel": {
          "description": "External genericLabel setting.",
          "type": "string",
          "minLength": 1
        },
        "width": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External width setting."
        },
        "length": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External length setting."
        },
        "height": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External height setting."
        },
        "centerOfMass": {
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "External centerOfMass setting."
        },
        "wheelbase": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External wheelbase setting."
        },
        "wheelTrack": {
          "type": "number",
          "minimum": 0,
          "description": "Lateral wheel spacing in meters; zero for cycles."
        },
        "wheelRadius": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External wheelRadius setting."
        },
        "mass": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External mass setting."
        },
        "engineForce": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External engineForce setting."
        },
        "maxSpeed": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External maxSpeed setting."
        },
        "reverseSpeed": {
          "type": "number",
          "minimum": 0,
          "description": "Maximum reverse speed; zero disables powered reverse."
        },
        "brakeDeceleration": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External brakeDeceleration setting."
        },
        "maxSteer": {
          "type": "number",
          "minimum": 0,
          "description": "External maxSteer setting."
        },
        "grip": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Peak tire friction on dry pavement as an acceleration in m/s²; grip / 9.81 is the friction coefficient. Rain and snow lower it."
        },
        "driverEye": {
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "External driverEye setting."
        },
        "steeringRate": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External steeringRate setting."
        },
        "steeringFadeSpeed": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External steeringFadeSpeed setting."
        },
        "rollingResistance": {
          "type": "number",
          "minimum": 0,
          "description": "External rollingResistance setting."
        },
        "aerodynamicResistance": {
          "type": "number",
          "minimum": 0,
          "description": "External aerodynamicResistance setting."
        },
        "terrainAlignRate": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External terrainAlignRate setting."
        },
        "supportTolerance": {
          "type": "number",
          "minimum": 0,
          "description": "External supportTolerance setting."
        },
        "maxStepHeight": {
          "type": "number",
          "minimum": 0,
          "description": "External maxStepHeight setting."
        },
        "maxSlope": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "External maxSlope setting."
        },
        "drive": {
          "description": "Driven wheels. Default front.",
          "type": "string",
          "enum": [
            "front",
            "rear",
            "all"
          ]
        },
        "corneringStiffness": {
          "description": "Tire side force per unit load per radian of slip angle before it saturates at the grip limit. Default 18.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "brakeBias": {
          "description": "Share of braking force on the front wheels. Default 0.65.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "yawInertia": {
          "description": "Yaw moment of inertia in kg m². Default mass * (length² + width²) / 12.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "rollStiffness": {
          "description": "Body roll in radians per g of cornering. Default 0.05.",
          "type": "number",
          "minimum": 0
        },
        "pitchStiffness": {
          "description": "Body pitch in radians per g of braking or acceleration. Default 0.03. Weight shifts between the axles through this pitch; 0 keeps the axle loads fixed.",
          "type": "number",
          "minimum": 0
        },
        "suspensionFrequency": {
          "description": "Suspension natural frequency in Hz for body roll and pitch. Default 1.5.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "suspensionDamping": {
          "description": "Suspension damping ratio. Default 0.5.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "powertrain": {
          "description": "Engine, gears and driveline: wheel force is engine torque through the selected gear. Without one the constant engineForce drives the vehicle up to maxSpeed.",
          "type": "object",
          "properties": {
            "power": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Peak power at the engine or motor shaft, in watts."
            },
            "peakPowerRpm": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Engine speed at peak power, rev/min."
            },
            "redline": {
              "description": "Rev limit, rev/min. Default 1.1 × peakPowerRpm.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "idle": {
              "description": "Idle speed, rev/min. Default 800, or 0 for an electric motor.",
              "type": "number",
              "minimum": 0
            },
            "curve": {
              "description": "Torque curve shape. Default gasoline; turbo and diesel hold a low-speed torque plateau, electric holds its peak torque from rest up to peakPowerRpm and then constant power.",
              "type": "string",
              "enum": [
                "gasoline",
                "turbo",
                "diesel",
                "electric"
              ]
            },
            "gears": {
              "minItems": 1,
              "maxItems": 12,
              "type": "array",
              "items": {
                "type": "number",
                "exclusiveMinimum": 0
              },
              "description": "Overall ratios (gearbox × final drive: engine revs per wheel rev), lowest gear first."
            },
            "continuous": {
              "description": "Continuously variable transmission ranging between the first and last gears ratios.",
              "type": "boolean"
            },
            "reverse": {
              "description": "Overall reverse ratio. Default first gear.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "efficiency": {
              "description": "Share of engine torque that reaches the wheels. Default 0.9.",
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1
            },
            "shiftTime": {
              "description": "Seconds of reduced drive during a gear change. Default 0.3.",
              "type": "number",
              "minimum": 0
            },
            "engineBraking": {
              "description": "Engine braking off the throttle (regeneration for an electric motor), as a share of the torque at peak power. Default 0.2.",
              "type": "number",
              "minimum": 0
            },
            "response": {
              "description": "How fast delivered torque follows the pedal, 1/s. Default 8; turbo and diesel 4, electric 20.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "inertia": {
              "description": "Rotating inertia of the engine, flywheel and gearbox input in kg m², spun up with the car (most in low gears). Default 0.1 + power / 1 MW, or 0.06 for an electric motor.",
              "type": "number",
              "minimum": 0
            }
          },
          "required": [
            "power",
            "peakPowerRpm",
            "gears"
          ],
          "additionalProperties": false
        },
        "rearGrip": {
          "description": "Rear tire grip in m/s² where it differs from the front (wider rear tires). Default grip.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "tireLoadSensitivity": {
          "description": "Share of its friction a tire loses when its load doubles from a quarter of the weight. Default 0.25; the heavier and the stiffer-sprung axle slides first. 0 keeps grip proportional to load.",
          "type": "number",
          "minimum": 0,
          "maximum": 0.6
        },
        "rollBalance": {
          "description": "Front axle share of the roll stiffness. Default 0.6; the stiffer axle carries more of the cornering weight transfer and loses grip first, so more is understeer.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "aerodynamicLift": {
          "description": "Aerodynamic lift as an acceleration per (m/s)² of airspeed, in 1/m; negative is downforce. Default 0.",
          "type": "number"
        },
        "tractionControl": {
          "description": "Traction control holds wheelspin at the grip limit. Default true.",
          "type": "boolean"
        },
        "stabilityControl": {
          "description": "Stability control brakes one wheel to catch a slide. Default true.",
          "type": "boolean"
        },
        "limitedSlip": {
          "description": "How far the driven axle resists one-wheel spin: 0 open differential (the unloaded inside wheel spins first), 1 locked. Default 0.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "looseSurfaceGrip": {
          "description": "Share of the grip loose surfaces take away that the tires win back (off-road tread). Default 0.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "runners": {
          "description": "Runners in place of tires (skis, a snowboard, a snowmobile): slides on the weather snow cover with this friction, holds its full grip there and floats over any depth; scrapes to a stop off the snow. Slides downhill from rest unless braked.",
          "type": "object",
          "properties": {
            "friction": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Sliding friction coefficient on snow; resists as friction × g. About 0.05 for waxed skis, 0.12 for a snowmobile track."
            },
            "bareDrag": {
              "description": "Resistance in m/s² off the snow, where runners scrape bare ground. Default 3.",
              "type": "number",
              "minimum": 0
            },
            "pushSpeed": {
              "description": "Fastest the rider pushing (poling, skating) drives it, m/s; gravity may take it on to maxSpeed. Absent: engineForce works up to maxSpeed.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "flat": {
              "description": "A cycle whose runners stay flat on the snow in a turn (a pair of skis) instead of banking as one plank (a snowboard); the lean stays in vehicleState.bodyRoll for the rider pose. Default false.",
              "type": "boolean"
            }
          },
          "required": [
            "friction"
          ],
          "additionalProperties": false
        },
        "cycle": {
          "description": "Self-balancing cycle handling and rider contact points. Driver seat anchors the pelvis.",
          "type": "object",
          "properties": {
            "maxLean": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1.2,
              "description": "Maximum balanced inward lean in radians."
            },
            "riderLean": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Forward torso lean in radians."
            },
            "handlebarPivot": {
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "Steering pivot in model-local meters."
            },
            "grips": {
              "type": "array",
              "prefixItems": [
                {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                }
              ],
              "items": false,
              "minItems": 2,
              "maxItems": 2,
              "description": "Left and right hand targets in model-local meters; they turn with the bars. A sideways rider holds them free: unturned, moving with the hips of a shorter or taller body."
            },
            "footrests": {
              "type": "array",
              "prefixItems": [
                {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                }
              ],
              "items": false,
              "minItems": 2,
              "maxItems": 2,
              "description": "Left and right ankle targets on the footrests or deck, in model-local meters."
            },
            "stance": {
              "description": "How the rider stands: on a saddle (seated, default), upright on a deck facing the bars (standing), or across a board left foot forward (sideways). Standing and sideways seats are adult hip positions; the pose fits the hips to each body's legs.",
              "type": "string",
              "enum": [
                "seated",
                "standing",
                "sideways"
              ]
            },
            "kick": {
              "description": "Push-powered (a skateboard): under power the rider turns forward and pushes off the ground with the rear foot.",
              "type": "object",
              "properties": {
                "stride": {
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "description": "Meters travelled per push."
                }
              },
              "required": [
                "stride"
              ],
              "additionalProperties": false
            },
            "pedals": {
              "description": "Bicycle crank geometry and gearing; omitted on motor vehicles.",
              "type": "object",
              "properties": {
                "center": {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  },
                  "description": "Crank centre in model-local meters."
                },
                "radius": {
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "description": "Crank arm length in meters."
                },
                "halfWidth": {
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "description": "Distance from centreline to each pedal in meters."
                },
                "ratio": {
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "description": "Wheel revolutions per crank revolution."
                }
              },
              "required": [
                "center",
                "radius",
                "halfWidth",
                "ratio"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "maxLean",
            "riderLean",
            "handlebarPivot",
            "grips",
            "footrests"
          ],
          "additionalProperties": false
        },
        "headlamps": {
          "description": "Headlamp lens centres in model-local meters, at most two; night lighting places its beams there. Empty: no headlamps. Absent: a pair guessed from the body size.",
          "maxItems": 2,
          "type": "array",
          "items": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            }
          }
        },
        "handlebar": {
          "description": "Handlebar steering on a vehicle that does not lean (a three-wheeler): the driver contact points, the driver seat anchoring the pelvis. Ignored with cycle.",
          "type": "object",
          "properties": {
            "riderLean": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Forward torso lean in radians."
            },
            "handlebarPivot": {
              "minItems": 3,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "Steering pivot in model-local meters."
            },
            "grips": {
              "type": "array",
              "prefixItems": [
                {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                }
              ],
              "items": false,
              "minItems": 2,
              "maxItems": 2,
              "description": "Left and right hand targets in model-local meters; they turn with the bars. A sideways rider holds them free: unturned, moving with the hips of a shorter or taller body."
            },
            "footrests": {
              "type": "array",
              "prefixItems": [
                {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                }
              ],
              "items": false,
              "minItems": 2,
              "maxItems": 2,
              "description": "Left and right ankle targets on the footrests or deck, in model-local meters."
            }
          },
          "required": [
            "riderLean",
            "handlebarPivot",
            "grips",
            "footrests"
          ],
          "additionalProperties": false
        },
        "rail": {
          "description": "External rail setting.",
          "type": "object",
          "properties": {
            "truckCenters": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Distance between the two truck (bogie) pivots along the body, meters. The body rides as the chord between them on curves."
            },
            "couplerLength": {
              "description": "Length over the coupler pulling faces, meters; spacing in a consist. Default length.",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "power": {
              "description": "Power at the rail in watts. Tractive effort is engineForce up to power / speed; 0 (default) is an unpowered car that only brakes.",
              "type": "number",
              "minimum": 0
            },
            "gauge": {
              "description": "Track gauge between rail heads, meters. Default 1.435 (standard gauge).",
              "type": "number",
              "exclusiveMinimum": 0
            },
            "profile": {
              "description": "Silhouette of the low-detail stand-in drawn at a distance (parked in a yard, far traffic). Default box.",
              "type": "string",
              "enum": [
                "box",
                "hopper",
                "tank",
                "gondola",
                "flat",
                "well",
                "autorack",
                "locomotive",
                "coach",
                "railcar"
              ]
            }
          },
          "required": [
            "truckCenters"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "label",
        "width",
        "length",
        "height",
        "centerOfMass",
        "wheelbase",
        "wheelTrack",
        "wheelRadius",
        "mass",
        "engineForce",
        "maxSpeed",
        "reverseSpeed",
        "brakeDeceleration",
        "maxSteer",
        "grip",
        "driverEye",
        "steeringRate",
        "steeringFadeSpeed",
        "rollingResistance",
        "aerodynamicResistance",
        "terrainAlignRate",
        "supportTolerance",
        "maxStepHeight",
        "maxSlope"
      ],
      "additionalProperties": false,
      "description": "Complete data-driven chassis and handling configuration."
    },
    "visual": {
      "type": "object",
      "properties": {
        "wheelNodes": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Wheel nodes, spun by the wheel angle. At least one, except on a vehicle with runners (skis, a board), which has none."
        },
        "frontWheelNodes": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Wheel nodes turned by the steering angle. Empty when animation bindings pose the steering instead (a skateboard turns its trucks)."
        },
        "steeringWheelNode": {
          "description": "External steeringWheelNode setting.",
          "type": "string",
          "minLength": 1
        },
        "paintMaterial": {
          "type": "string",
          "minLength": 1,
          "description": "External paintMaterial setting."
        },
        "interior": {
          "description": "External interior setting.",
          "type": "object",
          "properties": {
            "nodes": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Cabin nodes in the same exterior/interior GLB."
            },
            "sources": {
              "description": "Optional component fields overriding or extending host telemetry.",
              "type": "object",
              "propertyNames": {
                "type": "string",
                "minLength": 1
              },
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "component": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Component on this same entity."
                  },
                  "path": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 1
                        },
                        {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        }
                      ]
                    },
                    "description": "Explicit property names or array indices leading to a number or boolean."
                  }
                },
                "required": [
                  "component",
                  "path"
                ],
                "additionalProperties": false
              }
            },
            "bindings": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "node": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Exact loaded GLB node name."
                  },
                  "source": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Named simulation signal."
                  },
                  "property": {
                    "type": "string",
                    "enum": [
                      "rotation",
                      "position",
                      "visible"
                    ],
                    "description": "Local transform or visibility channel."
                  },
                  "axis": {
                    "description": "Required for transforms; omit for visible.",
                    "type": "string",
                    "enum": [
                      "x",
                      "y",
                      "z"
                    ]
                  },
                  "scale": {
                    "description": "Multiply the signal by this value. Supply this or keys.",
                    "type": "number"
                  },
                  "offset": {
                    "description": "Offset after scaling; default zero.",
                    "type": "number"
                  },
                  "keys": {
                    "description": "Keyframed curve of [signal, displacement] pairs, signals strictly ascending; holds the end values outside them. Supply this or scale.",
                    "minItems": 2,
                    "type": "array",
                    "items": {
                      "type": "array",
                      "prefixItems": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "number"
                        }
                      ],
                      "items": false,
                      "minItems": 2,
                      "maxItems": 2
                    }
                  },
                  "ease": {
                    "description": "Interpolation between keys: linear (default), or smooth to ease out of and into every key.",
                    "type": "string",
                    "enum": [
                      "linear",
                      "smooth"
                    ]
                  },
                  "min": {
                    "description": "Minimum displacement from authored pose.",
                    "type": "number"
                  },
                  "max": {
                    "description": "Maximum displacement from authored pose.",
                    "type": "number"
                  },
                  "period": {
                    "description": "Rotation output wraps to [0, period); smoothing follows the shortest arc. Cannot combine with min/max.",
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "responseSeconds": {
                    "description": "First-order response time constant in simulation seconds; default zero. Requires a timestamp from the host.",
                    "type": "number",
                    "minimum": 0
                  },
                  "missing": {
                    "description": "Missing reading: hold last pose (default), restore authored pose, or hide a visible channel.",
                    "type": "string",
                    "enum": [
                      "hold",
                      "rest",
                      "hide"
                    ]
                  }
                },
                "required": [
                  "node",
                  "source",
                  "property"
                ],
                "additionalProperties": false
              },
              "description": "Per-model node channels and their signal calibration."
            },
            "derived": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "minLength": 1
              },
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "op": {
                    "type": "string",
                    "enum": [
                      "add",
                      "subtract",
                      "multiply",
                      "divide",
                      "min",
                      "max",
                      "clamp",
                      "abs",
                      "sqrt",
                      "floor",
                      "modulo",
                      "sin",
                      "cos",
                      "atan2",
                      "less",
                      "greater",
                      "equal",
                      "and",
                      "or",
                      "not",
                      "if",
                      "coalesce"
                    ],
                    "description": "Numeric operation; comparisons/logic return 0 or 1. Angles are radians."
                  },
                  "args": {
                    "minItems": 1,
                    "maxItems": 16,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "string",
                          "minLength": 1
                        }
                      ]
                    },
                    "description": "Finite numeric literals or names of signals, in operand order."
                  }
                },
                "required": [
                  "op",
                  "args"
                ],
                "additionalProperties": false
              },
              "description": "Up to 256 named data-only formulas, evaluated in dependency order. No cycles."
            }
          },
          "required": [
            "nodes",
            "bindings"
          ],
          "additionalProperties": false
        },
        "animation": {
          "description": "External animation setting.",
          "type": "object",
          "properties": {
            "sources": {
              "description": "Optional component fields overriding or extending host telemetry.",
              "type": "object",
              "propertyNames": {
                "type": "string",
                "minLength": 1
              },
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "component": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Component on this same entity."
                  },
                  "path": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 1
                        },
                        {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        }
                      ]
                    },
                    "description": "Explicit property names or array indices leading to a number or boolean."
                  }
                },
                "required": [
                  "component",
                  "path"
                ],
                "additionalProperties": false
              }
            },
            "bindings": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "node": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Exact loaded GLB node name."
                  },
                  "source": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Named simulation signal."
                  },
                  "property": {
                    "type": "string",
                    "enum": [
                      "rotation",
                      "position",
                      "visible"
                    ],
                    "description": "Local transform or visibility channel."
                  },
                  "axis": {
                    "description": "Required for transforms; omit for visible.",
                    "type": "string",
                    "enum": [
                      "x",
                      "y",
                      "z"
                    ]
                  },
                  "scale": {
                    "description": "Multiply the signal by this value. Supply this or keys.",
                    "type": "number"
                  },
                  "offset": {
                    "description": "Offset after scaling; default zero.",
                    "type": "number"
                  },
                  "keys": {
                    "description": "Keyframed curve of [signal, displacement] pairs, signals strictly ascending; holds the end values outside them. Supply this or scale.",
                    "minItems": 2,
                    "type": "array",
                    "items": {
                      "type": "array",
                      "prefixItems": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "number"
                        }
                      ],
                      "items": false,
                      "minItems": 2,
                      "maxItems": 2
                    }
                  },
                  "ease": {
                    "description": "Interpolation between keys: linear (default), or smooth to ease out of and into every key.",
                    "type": "string",
                    "enum": [
                      "linear",
                      "smooth"
                    ]
                  },
                  "min": {
                    "description": "Minimum displacement from authored pose.",
                    "type": "number"
                  },
                  "max": {
                    "description": "Maximum displacement from authored pose.",
                    "type": "number"
                  },
                  "period": {
                    "description": "Rotation output wraps to [0, period); smoothing follows the shortest arc. Cannot combine with min/max.",
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "responseSeconds": {
                    "description": "First-order response time constant in simulation seconds; default zero. Requires a timestamp from the host.",
                    "type": "number",
                    "minimum": 0
                  },
                  "missing": {
                    "description": "Missing reading: hold last pose (default), restore authored pose, or hide a visible channel.",
                    "type": "string",
                    "enum": [
                      "hold",
                      "rest",
                      "hide"
                    ]
                  }
                },
                "required": [
                  "node",
                  "source",
                  "property"
                ],
                "additionalProperties": false
              },
              "description": "Per-model node channels and their signal calibration."
            },
            "derived": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "minLength": 1
              },
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "op": {
                    "type": "string",
                    "enum": [
                      "add",
                      "subtract",
                      "multiply",
                      "divide",
                      "min",
                      "max",
                      "clamp",
                      "abs",
                      "sqrt",
                      "floor",
                      "modulo",
                      "sin",
                      "cos",
                      "atan2",
                      "less",
                      "greater",
                      "equal",
                      "and",
                      "or",
                      "not",
                      "if",
                      "coalesce"
                    ],
                    "description": "Numeric operation; comparisons/logic return 0 or 1. Angles are radians."
                  },
                  "args": {
                    "minItems": 1,
                    "maxItems": 16,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "string",
                          "minLength": 1
                        }
                      ]
                    },
                    "description": "Finite numeric literals or names of signals, in operand order."
                  }
                },
                "required": [
                  "op",
                  "args"
                ],
                "additionalProperties": false
              },
              "description": "Up to 256 named data-only formulas, evaluated in dependency order. No cycles."
            }
          },
          "required": [
            "bindings"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "wheelNodes",
        "frontWheelNodes",
        "paintMaterial"
      ],
      "additionalProperties": false,
      "description": "Named GLB nodes/material used by the generic client."
    }
  },
  "required": [
    "kind",
    "color",
    "spec",
    "visual"
  ],
  "additionalProperties": false
}

</details>

vehicleInput ​

Driver intent: signed throttle (negative brakes then reverses), signed steering (positive right), service brake and optional handbrake.

Required: throttle, steering, brake

json
{
  "throttle": 1,
  "steering": 0,
  "brake": false
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "actuators": {
      "description": "Mechanism targets from zero to one, or on/off selections.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 64,
        "pattern": "^[a-zA-Z][a-zA-Z0-9]*$"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "throttle": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Signed accelerator; opposite input brakes to zero before reversing."
    },
    "steering": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Steering intent -1..1; positive turns right."
    },
    "brake": {
      "type": "boolean",
      "description": "Apply the service brakes (all wheels, anti-lock) while true; holds the car at rest."
    },
    "handbrake": {
      "description": "Lock the rear wheels while true: they slide instead of rolling, for handbrake turns.",
      "type": "boolean"
    }
  },
  "required": [
    "throttle",
    "steering",
    "brake"
  ],
  "additionalProperties": false
}

</details>

vehicleState ​

Snapshot-safe chassis state. Speeds in m/s, angles in radians; owned by installVehicles.

Required: speed, steer, yaw, pitch, roll, vy, grounded, waitingForTerrain, wheelAngle

json
{
  "speed": 0,
  "steer": 0,
  "yaw": 0,
  "pitch": 0,
  "roll": 0,
  "vy": 0,
  "grounded": true,
  "waitingForTerrain": false,
  "wheelAngle": 0
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "damage": {
      "description": "Persistent joint integrity and separation, keyed by collision part id.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "integrity": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "detached": {
            "type": "boolean"
          }
        },
        "required": [
          "integrity",
          "detached"
        ],
        "additionalProperties": false
      }
    },
    "debris": {
      "description": "Detached parts in world coordinates; expire after 20 simulated seconds without repairing the vehicle.",
      "maxItems": 64,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "part": {
            "type": "string",
            "minLength": 1,
            "description": "Collision part id of the separated geometry."
          },
          "pos": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Debris origin in world coordinates, meters."
          },
          "rot": {
            "minItems": 4,
            "maxItems": 4,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Debris orientation as a quaternion."
          },
          "velocity": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "World-space linear velocity, m/s."
          },
          "angularVelocity": {
            "minItems": 3,
            "maxItems": 3,
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Local angular velocity about X, Y and Z, radians/s."
          },
          "age": {
            "type": "number",
            "minimum": 0,
            "description": "Elapsed simulation seconds since separation."
          }
        },
        "required": [
          "part",
          "pos",
          "rot",
          "velocity",
          "angularVelocity",
          "age"
        ],
        "additionalProperties": false
      }
    },
    "actuators": {
      "description": "Current mechanism positions and cycle phases, from zero to one.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 64,
        "pattern": "^[a-zA-Z][a-zA-Z0-9]*$"
      },
      "additionalProperties": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "boosted": {
      "description": "Speeds include the 4× travel boost; kernel-owned.",
      "type": "boolean"
    },
    "speed": {
      "type": "number",
      "description": "Signed forward speed in meters per second."
    },
    "steer": {
      "type": "number",
      "description": "Current front wheel steering angle in radians. Positive turns right."
    },
    "yaw": {
      "type": "number",
      "description": "Chassis rotation about Y in radians; zero faces +Z."
    },
    "pitch": {
      "type": "number",
      "description": "Chassis rotation about local X in radians from terrain support, nose down positive."
    },
    "roll": {
      "type": "number",
      "description": "Chassis rotation about local Z in radians from terrain support, right side down positive."
    },
    "vy": {
      "type": "number",
      "description": "Vertical velocity in meters per second."
    },
    "grounded": {
      "type": "boolean",
      "description": "Whether wheel support currently carries the chassis."
    },
    "waitingForTerrain": {
      "type": "boolean",
      "description": "Motion is paused because one or more wheel samples have no terrain."
    },
    "wheelAngle": {
      "type": "number",
      "description": "Accumulated wheel spin angle in radians, wrapped each revolution."
    },
    "pedalAngle": {
      "description": "Cycle crank angle in radians; advances under forward power and holds while coasting or braking. On a push-powered cycle, the phase of the current push.",
      "type": "number"
    },
    "kick": {
      "description": "Push-powered cycles: 0 riding sideways to 1 turned forward to push off; eases between them.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "lateralSpeed": {
      "description": "Sideways speed in meters per second, positive to the left: the slide.",
      "type": "number"
    },
    "yawRate": {
      "description": "Yaw rate in radians per second, positive turning left.",
      "type": "number"
    },
    "bodyPitch": {
      "description": "Suspension pitch in radians on top of the terrain, nose down positive.",
      "type": "number"
    },
    "bodyPitchRate": {
      "description": "Suspension pitch rate in radians per second.",
      "type": "number"
    },
    "bodyRoll": {
      "description": "Suspension roll in radians on top of the terrain, right side down positive.",
      "type": "number"
    },
    "bodyRollRate": {
      "description": "Suspension roll rate in radians per second.",
      "type": "number"
    },
    "skid": {
      "description": "0–1: how far the tires are past their grip (sliding, wheelspin, locked wheels).",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "gear": {
      "description": "Selected gear with a powertrain: -1 reverse, 1 upward forward gears.",
      "type": "integer",
      "minimum": -1,
      "maximum": 12
    },
    "rpm": {
      "description": "Engine speed in rev/min with a powertrain; rises and falls with the gears.",
      "type": "number",
      "minimum": 0
    },
    "engineLoad": {
      "description": "0–1 share of the engine torque being delivered, after its throttle response.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "shift": {
      "description": "Seconds until the gearbox may change gear again; drive is reduced as it starts.",
      "type": "number",
      "minimum": 0
    },
    "assist": {
      "description": "0–1: how hard traction or stability control is intervening.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "surfaceGrip": {
      "description": "Grip of the surface under the wheels relative to dry pavement; 1 on the road.",
      "type": "number",
      "minimum": 0
    },
    "snowDepth": {
      "description": "Meters of lying snow under the vehicle (the weather snow cover, less what a ploughed road clears); absent on bare ground.",
      "type": "number",
      "minimum": 0
    },
    "stuck": {
      "description": "Deep snow is holding the vehicle against its own drive: it cannot pull away from a stand.",
      "type": "boolean"
    },
    "track": {
      "description": "Track-guided vehicles (spec.rail with a host track guide): where the rails ran.",
      "type": "object",
      "properties": {
        "trail": {
          "maxItems": 3072,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "Recent track centreline under the vehicle, newest first, as flat x, y, z triples in world meters about 2 m apart; coupled cars ride on it."
        },
        "prefer": {
          "anyOf": [
            {
              "type": "number",
              "const": -1
            },
            {
              "type": "number",
              "const": 0
            },
            {
              "type": "number",
              "const": 1
            }
          ],
          "description": "Route at the next switch: -1 left, 0 straight on, 1 right."
        },
        "ended": {
          "description": "True while the vehicle stands at the end of its track.",
          "type": "boolean"
        },
        "ref": {
          "description": "The host track guide's reference for the piece of track under the head.",
          "type": "string"
        }
      },
      "required": [
        "trail",
        "prefer"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "speed",
    "steer",
    "yaw",
    "pitch",
    "roll",
    "vy",
    "grounded",
    "waitingForTerrain",
    "wheelAngle"
  ],
  "additionalProperties": false
}

</details>

Owner: other ​

weather ​

Singleton physical atmosphere and visual weather: temperature, pressure, humidity, wind, independent cloud cover, precipitation and visibility. Readable by scripts and physics; see guide/weather.md.

Required: none

json
{
  "atmosphere": {
    "temperatureK": 282.15,
    "pressurePa": 100200,
    "windVelocity": [
      7,
      0,
      3
    ]
  },
  "clouds": {
    "coverage": 0.95
  },
  "precipitation": {
    "kind": "rain",
    "intensity": 0.7
  },
  "visibility": 4500
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "atmosphere": {
      "description": "Physical atmospheric state; independent of the visual weather profile.",
      "type": "object",
      "properties": {
        "model": {
          "description": "Standard layered Earth lapse rates (default), or a uniform-temperature isothermal atmosphere.",
          "type": "string",
          "enum": [
            "standard",
            "isothermal"
          ]
        },
        "moistAir": {
          "description": "Apply water-vapor ideal-gas density correction. Default false (dry reference air).",
          "type": "boolean"
        },
        "temperatureK": {
          "description": "Temperature at referenceAltitude in kelvin; default 288.15 (15 °C).",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "pressurePa": {
          "description": "Absolute barometric pressure at referenceAltitude in pascals; default 101325. Zero permits vacuum.",
          "type": "number",
          "minimum": 0
        },
        "relativeHumidity": {
          "description": "Relative humidity 0–1, default 0.5. Stored independently; does not select precipitation.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "windVelocity": {
          "description": "Air velocity [x,y,z] in world meters/second; default [0,0,0]. This is a velocity, not a meteorological FROM bearing.",
          "minItems": 3,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "number"
          }
        },
        "referenceAltitude": {
          "description": "World Y in meters where temperature and pressure apply; default 0.",
          "type": "number"
        },
        "gasConstant": {
          "description": "Specific gas constant in J/(kg·K); default 287.05 for dry Earth air. Supports other atmospheres.",
          "type": "number",
          "exclusiveMinimum": 0
        }
      },
      "additionalProperties": false
    },
    "visibility": {
      "description": "Visual distance in meters; default 50000. Independent of clouds and precipitation. Renderer also respects a nearer authored fog limit.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "clouds": {
      "description": "World-anchored, wind-advected volumetric cloud layer of one type, plus an optional high cirrus layer. Does not imply precipitation.",
      "type": "object",
      "properties": {
        "coverage": {
          "description": "Sky coverage 0–1, default 0: the share of the sky the layer covers; 1 closes it.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "density": {
          "description": "Cloud optical density 0–1, default 0.65; independent of coverage.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "baseAltitude": {
          "description": "Cloud base at absolute world Y in meters, default 1800.",
          "type": "number"
        },
        "thickness": {
          "description": "Depth of the layer from base to top in meters, default 600.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "scale": {
          "description": "Horizontal cloud-pattern repeat size in meters, default 16000.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "type": {
          "description": "Cloud type of the layer, default cumulus: separate heaps; stratocumulus a lumpy closed layer; stratus a flat sheet; cumulonimbus towering storm cells (give them a thick layer).",
          "type": "string",
          "enum": [
            "cumulus",
            "stratocumulus",
            "stratus",
            "cumulonimbus"
          ]
        },
        "cirrus": {
          "description": "Coverage 0–1 of a thin, wispy high cirrus layer, default 0. Independent of the main layer.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "cirrusAltitude": {
          "description": "Cirrus layer at absolute world Y in meters, default 9000.",
          "type": "number"
        }
      },
      "additionalProperties": false
    },
    "precipitation": {
      "description": "Precipitation independent of cloud coverage and visibility.",
      "type": "object",
      "properties": {
        "kind": {
          "description": "Explicit precipitation phase, default none. Temperature never silently overrides it.",
          "type": "string",
          "enum": [
            "none",
            "rain",
            "snow"
          ]
        },
        "intensity": {
          "description": "Visual precipitation intensity 0–1, default 0. Not a calibrated rainfall rate.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "additionalProperties": false
    },
    "wind": {
      "description": "Spatial and temporal structure of the wind around the mean atmosphere.windVelocity. Deterministic from seed and simulation time; consumes no simulation RNG.",
      "type": "object",
      "properties": {
        "referenceHeight": {
          "description": "Height above ground in meters where atmosphere.windVelocity is measured; default 10.",
          "type": "number",
          "exclusiveMinimum": 0
        },
        "shear": {
          "description": "Power-law exponent of mean wind speed with height above ground, up to 600 m; default 0 (uniform). About 0.14 over open country, 0.3 over cities.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "turbulence": {
          "description": "Turbulence intensity 0–1, default 0: about 0.15 light chop, 0.4 moderate, 0.8 severe. Grows with wind speed and fades above the 1 km boundary layer.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "gusts": {
          "description": "Gust factor 0–1, default 0: along-wind speed swings as a fraction of the mean wind, advected with it.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "terrain": {
          "description": "Strength 0–1 of wind deflected by terrain slopes: ridge lift upwind, sink in the lee. Default 0.",
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "additionalProperties": false
    },
    "snowCover": {
      "description": "Snow lying on the ground above a snow line, independent of whether snow is falling. Absent means bare ground. Slows walkers, bogs wheeled vehicles down and lets runners glide; renderers whiten ground, roofs and foliage above the line.",
      "type": "object",
      "properties": {
        "level": {
          "type": "number",
          "description": "Snow line: the absolute world Y in meters where lying snow begins. Ground below it is bare."
        },
        "transition": {
          "description": "Height in meters above the snow line over which cover builds from none to complete; default 150. Zero is a hard line.",
          "type": "number",
          "minimum": 0
        },
        "depth": {
          "description": "Snow depth in meters where cover becomes complete, at the top of the transition; default 0.15.",
          "type": "number",
          "minimum": 0
        },
        "depthGain": {
          "description": "Extra depth in meters for each 1000 m of height above that; default 0.6.",
          "type": "number",
          "minimum": 0
        },
        "maxDepth": {
          "description": "Greatest depth in meters at any height; default 1.5.",
          "type": "number",
          "minimum": 0
        }
      },
      "required": [
        "level"
      ],
      "additionalProperties": false
    },
    "seed": {
      "description": "Stable visual pattern seed, default 1. Does not consume simulation RNG.",
      "type": "integer",
      "minimum": 0,
      "maximum": 4294967295
    }
  },
  "additionalProperties": false
}

</details>

Owner: physics-rapier ​

collider3d ​

3D collider (ball/cuboid/capsule/hull/trimesh/asset/heightfield) with layer/mask, sensor, and material params. Static without a rigidbody.

Required: shape

json
{
  "shape": {
    "type": "cuboid",
    "hx": 10,
    "hy": 0.5,
    "hz": 10
  }
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "shape": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "ball",
              "description": "Sphere."
            },
            "radius": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Sphere radius in meters."
            }
          },
          "required": [
            "type",
            "radius"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "cuboid",
              "description": "Axis-aligned box (in the collider frame)."
            },
            "hx": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Half-extent along X in meters."
            },
            "hy": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Half-extent along Y in meters."
            },
            "hz": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Half-extent along Z in meters."
            }
          },
          "required": [
            "type",
            "hx",
            "hy",
            "hz"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "capsule",
              "description": "Capsule aligned with the Y axis."
            },
            "halfHeight": {
              "type": "number",
              "minimum": 0,
              "description": "Half the length of the cylindrical section along Y in meters (caps excluded)."
            },
            "radius": {
              "type": "number",
              "exclusiveMinimum": 0,
              "description": "Capsule radius in meters."
            }
          },
          "required": [
            "type",
            "halfHeight",
            "radius"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "convexHull",
              "description": "Convex hull of a point cloud."
            },
            "points": {
              "minItems": 12,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "Flat [x, y, z, x, y, z, ...] point list in meters (at least 4 points); the shape is their convex hull."
            }
          },
          "required": [
            "type",
            "points"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "trimesh",
              "description": "Triangle mesh (static geometry)."
            },
            "vertices": {
              "minItems": 9,
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "Flat [x, y, z, ...] vertex positions in meters."
            },
            "indices": {
              "minItems": 3,
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "description": "Triangle vertex indices, three per triangle."
            }
          },
          "required": [
            "type",
            "vertices",
            "indices"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "asset",
              "description": "Collision geometry from a project asset's sidecar."
            },
            "assetId": {
              "type": "string",
              "minLength": 1,
              "description": "Project asset id whose sidecar collision geometry is used."
            },
            "collision": {
              "type": "string",
              "enum": [
                "hull",
                "trimesh"
              ],
              "description": "Which sidecar geometry to use: hull (convex, default) or trimesh."
            },
            "index": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991,
              "description": "Index of the sidecar hull to use when the asset has several (default 0)."
            }
          },
          "required": [
            "type",
            "assetId"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "heightfield",
              "description": "Terrain heightfield."
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "description": "Heightfield reference id resolved by the host (e.g. the scene terrain)."
            }
          },
          "required": [
            "type",
            "ref"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Collision shape."
    },
    "offset": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Shape offset [x, y, z] in meters relative to the entity transform."
    },
    "rotOffset": {
      "minItems": 4,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Shape rotation quaternion [x, y, z, w] relative to the entity transform."
    },
    "layer": {
      "type": "integer",
      "minimum": 0,
      "maximum": 65535,
      "description": "16-bit collision-group bitmask this collider belongs to (default 1)."
    },
    "mask": {
      "type": "integer",
      "minimum": 0,
      "maximum": 65535,
      "description": "16-bit bitmask of groups this collider collides with (default 0xffff = all)."
    },
    "sensor": {
      "type": "boolean",
      "description": "Sensor colliders detect overlaps (collision events) but produce no contact forces."
    },
    "events": {
      "type": "boolean",
      "description": "Emit 'collision' / 'collisionEnd' world events for this collider."
    },
    "restitution": {
      "type": "number",
      "minimum": 0,
      "description": "Bounciness coefficient (0 = inelastic)."
    },
    "friction": {
      "type": "number",
      "minimum": 0,
      "description": "Coulomb friction coefficient."
    },
    "density": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Mass density in kg/m^3 used to derive the body mass from the shape volume."
    }
  },
  "required": [
    "shape"
  ],
  "additionalProperties": false
}

</details>

force ​

Continuous force/torque applied every tick while present.

Required: none

json
{
  "linear": [
    0,
    20,
    0
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "linear": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Force [x, y, z] in newtons applied at the center of mass every tick while present."
    },
    "torque": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Torque [x, y, z] in N*m applied every tick while present."
    }
  },
  "additionalProperties": false
}

</details>

impulse ​

One-shot impulse/torque; consumed the tick it is applied.

Required: none

json
{
  "v": [
    10,
    0,
    0
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "v": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Linear impulse [x, y, z] in N*s (kg*m/s) applied once."
    },
    "torque": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Angular impulse [x, y, z] in N*m*s applied once."
    }
  },
  "additionalProperties": false
}

</details>

joint ​

Impulse joint to another body (fixed/revolute/spherical/prismatic + limits/motor).

Required: type, other, anchor1, anchor2

json
{
  "type": "revolute",
  "other": "chassis",
  "anchor1": [
    0,
    0,
    1
  ],
  "anchor2": [
    0,
    0,
    0
  ],
  "axis": [
    0,
    0,
    1
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "fixed",
        "revolute",
        "spherical",
        "prismatic"
      ],
      "description": "Joint type: fixed, revolute (hinge), spherical (ball), or prismatic (slider)."
    },
    "other": {
      "type": "string",
      "minLength": 1,
      "description": "Entity id of the other body."
    },
    "anchor1": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Anchor point [x, y, z] in meters in this body's local frame."
    },
    "anchor2": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Anchor point [x, y, z] in meters in the other body's local frame."
    },
    "axis": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Joint axis [x, y, z] in this body's local frame (revolute/prismatic)."
    },
    "limits": {
      "minItems": 2,
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "[min, max] joint limits: radians for revolute, meters for prismatic."
    },
    "motor": {
      "type": "object",
      "properties": {
        "targetVel": {
          "type": "number",
          "description": "Target joint velocity: rad/s for revolute, m/s for prismatic."
        },
        "maxForce": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Maximum force (N) or torque (N*m) the motor may apply."
        }
      },
      "required": [
        "targetVel",
        "maxForce"
      ],
      "additionalProperties": false,
      "description": "Velocity motor driving the joint (revolute/prismatic)."
    }
  },
  "required": [
    "type",
    "other",
    "anchor1",
    "anchor2"
  ],
  "additionalProperties": false
}

</details>

rigidbody ​

3D rigid-body dynamics: dynamic, fixed, or kinematicPosition (characters).

Required: body

json
{
  "body": "dynamic"
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "enum": [
        "dynamic",
        "fixed",
        "kinematicPosition"
      ],
      "description": "Body type: dynamic (simulated), fixed (immovable), or kinematicPosition (driven by transform writes, e.g. characters)."
    },
    "gravityScale": {
      "type": "number",
      "description": "Multiplier on scene gravity for this body (1 = normal, 0 = weightless)."
    },
    "linearDamping": {
      "type": "number",
      "minimum": 0,
      "description": "Linear velocity damping coefficient per second (0 = none)."
    },
    "angularDamping": {
      "type": "number",
      "minimum": 0,
      "description": "Angular velocity damping coefficient per second (0 = none)."
    },
    "ccd": {
      "type": "boolean",
      "description": "Enable continuous collision detection for fast-moving bodies."
    },
    "lockRot": {
      "type": "boolean",
      "description": "Lock all rotations so the body never tumbles."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false
}

</details>

setVelocity ​

One-shot velocity set; consumed the tick it is applied.

Required: none

json
{
  "linear": [
    0,
    0,
    5
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "linear": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Linear velocity [x, y, z] in m/s to set once."
    },
    "angular": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Angular velocity [x, y, z] in rad/s to set once."
    }
  },
  "additionalProperties": false
}

</details>

velocity ​

Opt-in per-tick body velocity mirror (presence = subscription; plugin-written).

Required: linear, angular

json
{
  "linear": [
    0,
    0,
    0
  ],
  "angular": [
    0,
    0,
    0
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "linear": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Current linear velocity [x, y, z] in m/s (plugin-written each tick)."
    },
    "angular": {
      "minItems": 3,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Current angular velocity [x, y, z] in rad/s (plugin-written each tick)."
    }
  },
  "required": [
    "linear",
    "angular"
  ],
  "additionalProperties": false
}

</details>

Owner: worldgen ​

worldgenBuilding ​

A building generated at runtime from an outline in the entity frame, styled by a molen/archstyle@1 in the loaded pack; rendered by the worldgen client entity layer.

Required: style, outline

json
{
  "style": "molen.worldgen.fantasy.hall",
  "outline": [
    [
      -12,
      -5
    ],
    [
      12,
      -5
    ],
    [
      12,
      5
    ],
    [
      -12,
      5
    ]
  ],
  "levels": 2,
  "labels": [
    "hall"
  ]
}

<details> <summary>JSON Schema</summary>

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "style": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$",
      "description": "Style id in the loaded pack, e.g. 'molen.worldgen.fantasy.hall'."
    },
    "appearance": {
      "type": "object",
      "properties": {
        "wall": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "trim": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        }
      },
      "additionalProperties": false
    },
    "storefronts": {
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "identity": {
            "type": "string",
            "minLength": 1
          },
          "at": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number"
              },
              {
                "type": "number"
              }
            ],
            "items": false,
            "minItems": 2,
            "maxItems": 2,
            "description": "Desired frontage anchor in local meters; projected to a non-seam exterior edge."
          },
          "signModel": {
            "type": "string",
            "pattern": "^(builtin:[a-z][a-z0-9_.]*|[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+)$"
          },
          "signSize": {
            "type": "array",
            "prefixItems": [
              {
                "type": "number",
                "exclusiveMinimum": 0
              },
              {
                "type": "number",
                "exclusiveMinimum": 0
              }
            ],
            "items": false,
            "minItems": 2,
            "maxItems": 2
          },
          "accent": {
            "type": "string",
            "pattern": "^#[0-9a-fA-F]{6}$"
          },
          "width": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100
          },
          "sign": {
            "description": "A name set from the batch glyph atlas in place of the sign model text; without an atlas holding every character the sign model shows.",
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "description": "The name as shown; it may break over two lines."
              },
              "plate": {
                "type": "string",
                "pattern": "^#[0-9a-fA-F]{6}$"
              },
              "ink": {
                "type": "string",
                "pattern": "^#[0-9a-fA-F]{6}$"
              },
              "stripe": {
                "type": "string",
                "pattern": "^#[0-9a-fA-F]{6}$"
              },
              "font": {
                "description": "Glyph atlas role or face id.",
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "letterSpacing": {
                "type": "number",
                "minimum": -0.1,
                "maximum": 0.5
              }
            },
            "required": [
              "text",
              "plate",
              "ink"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "identity",
          "at",
          "signModel",
          "accent"
        ],
        "additionalProperties": false
      }
    },
    "outline": {
      "minItems": 3,
      "type": "array",
      "items": {
        "minItems": 2,
        "maxItems": 2,
        "type": "array",
        "items": {
          "type": "number"
        },
        "description": "[x, z] in entity-local meters."
      },
      "description": "Open ring of [x, z] points."
    },
    "holes": {
      "type": "array",
      "items": {
        "minItems": 3,
        "type": "array",
        "items": {
          "minItems": 2,
          "maxItems": 2,
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "[x, z] in entity-local meters."
        },
        "description": "Open ring of [x, z] points."
      },
      "description": "Inner rings (courtyards)."
    },
    "height": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Wall height in meters (overrides levels)."
    },
    "levels": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Floor count."
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Labels the style rules and props see (default ['building'])."
    },
    "seed": {
      "type": "string",
      "minLength": 1,
      "description": "Stable identity for the seed (default: entity id)."
    },
    "tier": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Detail tier, 0 = full (default 0)."
    }
  },
  "required": [
    "style",
    "outline"
  ],
  "additionalProperties": {}
}

</details>

50 guides · 44 schema formats · 51 API entry points · 11 samples. API, CLI and schema pages are generated from the shipped build.