Appearance
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.halfExtentsis[x, z](2.5D kinematics act in the XZ plane).moveIntent.diris[x, z]: +x east, +z south (screen-down in top-down views).layer/maskare bitmasks: a collides with b whena.mask & b.layerorb.mask & a.layeris non-zero.renderable.primitive.sizeis[x, y, z].environment.sun.directionpoints FROM the origin TOWARD the sun (the light sits at that offset and shines back at the origin).
Vocabulary
| Component | Owner | Description |
|---|---|---|
aircraft | kernel/aircraft | External airplane/helicopter instance. Y up, Z forward; landing-contact origin. |
aircraftInput | kernel/aircraft | Pilot flight controls. Power is retained when input keys are released. |
aircraftState | kernel/aircraft | Deterministic flight state, including rotor phase and engine spool, preserved by keyframes. |
ambientAgent | ambient | 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. |
ambientObserver | ambient | Marks the entity ambient NPCs spawn around (usually the player or camera rig), with optional radius and density overrides. |
ambientRole | ambient | On an entity type: makes it an ambient NPC candidate (car, bus, rail car, aircraft, boat or ferry) with dimensions, speeds and spawn weight. |
ambientState | ambient | Kernel-owned ambient bookkeeping on the $ambient entity: observer, spawn sequence and policy overrides. |
audioEnvironment | audio | Singleton soundscape rules: bus gains, ambience layers gated on weather/sky/listener signals, music playlist, event → sound mappings and listener footsteps. |
audioSource | audio | 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. |
audioZone | audio | 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). |
boat | kernel/boats | Waterline-aligned powered hull with data-driven handling and shared seats. |
boatInput | kernel/boats | Helm intent: signed thrust, steering and low-speed anchor. Only the driver controls it. |
boatState | kernel/boats | Snapshot-safe hull motion, buoyancy and anchoring; owned by installBoats. |
boostMode | kernel | World-wide 4× travel assist for people and vehicles. Control response times stay normal. |
character | kernel/character | Kinematic character controller state (speed/jump/gravity + kernel-owned vy/grounded). |
collider | kernel/kinematics | 2.5D kinematic collider (circle or XZ AABB) with layer/mask bitmasks. |
collider3d | physics-rapier | 3D collider (ball/cuboid/capsule/hull/trimesh/asset/heightfield) with layer/mask, sensor, and material params. Static without a rigidbody. |
coupled | kernel/vehicles | 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. |
environment | client | Singleton scene environment: optional Earth/custom sky, ambient/sun lighting, background, fog, tone mapping, shadow quality tier. |
figure | figures | 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". |
figureAttachment | figures | Follow a named socket of the parent figure (with parent): the figures systems write localTransform from the evaluated pose each tick. |
figureIntent | figures | Optional authored control of a figure: a forced mode, a look-at target, joint overrides, and IK goals. |
figureState | figures | Kernel-owned locomotion state of a figure (mode, quantized speed, tick-anchored gait phase). Read it; the figures systems write it. |
force | physics-rapier | Continuous force/torque applied every tick while present. |
fsm | kernel/gameplay | Minimal event-driven state machine: transitions fire on world events targeting the entity. |
glass | kernel/glass | Breakable glass surfaces with metric geometry, material fracture and independent frame/interlayer retention. |
glassState | kernel/glass | Persistent glass fracture, retention and release state. Missing panes are intact; remove the component to repair. |
health | content | Common gameplay hit-points component. |
impulse | physics-rapier | One-shot impulse/torque; consumed the tick it is applied. |
joint | physics-rapier | Impulse joint to another body (fixed/revolute/spherical/prismatic + limits/motor). |
kinematicBody | kernel/kinematics | Velocity-driven body for the kinematic collision layer. |
lifetime | kernel | Auto-despawn countdown in ticks. |
light | client | A light source at the entity transform (directional/point/spot). |
livery | client | Reusable model paint slots, bound surface markings and selectable liveries. Visual only. |
localTransform | kernel/gameplay | Parent-relative transform for entities carrying parent. |
model.signals | client | 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. |
mountable | kernel/vehicles | Mount points in local meters, ordered safe exit candidates, and interaction reach. Seat position is the rider camera anchor. |
mounted | kernel/vehicles | Rider-to-mount relationship. Occupied seats are exclusive; mounted characters bypass walking physics. |
moveIntent | kernel/character | Desired planar move direction + jump flag, consumed by the character controller. |
parent | kernel/gameplay | Attach to a parent entity: transform becomes parent.transform × localTransform each tick. |
platformBody | kernel | Deterministic XY platform controller: gravity, swept wall/floor/ceiling collision, jump buffering and coyote time. |
platformIntent | kernel | Input to a platformBody. Scripts translate declared commands to this component. |
platformSolid | kernel | Static XY solid for physics.engine=platformer; Z is ignored. |
renderable | client | 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. |
rigidbody | physics-rapier | 3D rigid-body dynamics: dynamic, fixed, or kinematicPosition (characters). |
setVelocity | physics-rapier | One-shot velocity set; consumed the tick it is applied. |
tag | content | Named tag for selecting/grouping entities (e.g. tag.name === "enemy"). |
timer | kernel/gameplay | Snapshot-safe countdown timers that emit events (one-shot or repeating). Replaces callbacks. |
transform | kernel | World position + orientation. pos is required; rot defaults to identity. |
tween | kernel/gameplay | Data-driven value animation over ticks: component + select-style path, lerp with easing. |
vehicle | kernel/vehicles | External wheeled-vehicle instance: stable id, paint, complete physics tuning, and GLB bindings. |
vehicleInput | kernel/vehicles | Driver intent: signed throttle (negative brakes then reverses), signed steering (positive right), service brake and optional handbrake. |
vehicleState | kernel/vehicles | Snapshot-safe chassis state. Speeds in m/s, angles in radians; owned by installVehicles. |
velocity | physics-rapier | Opt-in per-tick body velocity mirror (presence = subscription; plugin-written). |
water | kernel/boats | Deterministic swells and current for boats; heights and coverage come from the host water field. |
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. | |
worldgenBuilding | worldgen | 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. |
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>