Skip to content

@bendyline/molen-schema ​

Molen data formats: schemas, validator, and error formatter.

ts
import { /* … */ } from '@bendyline/molen-schema';

Interfaces ​

ActuatorSpec ​

Model-owned mechanisms. Positions and cycle phases are normalized to 0..1.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

initial? ​
ts
optional initial?: number;
mode? ​
ts
optional mode?: "position" | "cycle" | "latch";

Cycles finish at the parked phase when switched off. Latches cannot be reversed.

seconds ​
ts
seconds: number;

Seconds for full travel, or one complete out-and-back cycle. Zero switches immediately.


AircraftCollisionPart ​

A rigid airframe section; +X is the aircraft's left side.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

breakSpeed? ​
ts
optional breakSpeed?: number;

Normal impact speed in m/s that exhausts an undamaged joint. Omit for an unbreakable body.

center ​
ts
center: [number, number, number];

Center of the detached section in model coordinates.

disc? ​
ts
optional disc?: object;

Finite swept rotor volume, replacing this section's sphere probes. Active even at rest.

center ​
ts
center: [number, number, number];
halfThickness ​
ts
halfThickness: number;
normal ​
ts
normal: [number, number, number];
radius ​
ts
radius: number;
rotor ​
ts
rotor: string;
tilt? ​
ts
optional tilt?: object;
tilt.angle ​
ts
angle: number;
tilt.axis ​
ts
axis: [number, number, number];
tilt.pivot ​
ts
pivot: [number, number, number];
engines? ​
ts
optional engines?: string[];

Engines disabled when this section separates.

fragments? ​
ts
optional fragments?: object;

Split shared static detail meshes by triangle centroid in model coordinates.

max ​
ts
max: [number, number, number];
min ​
ts
min: [number, number, number];
nodes ​
ts
nodes: string[];
id ​
ts
id: string;
massFraction ​
ts
massFraction: number;

Fraction of the original aircraft mass carried away on separation.

nodes ​
ts
nodes: string[];

Exact GLB node names, including attached controls, markings and gear.

parent? ​
ts
optional parent?: string;

Supporting section. Its separation also releases this part, once, with its own debris.

probes ​
ts
probes: [number, number, number][];

Collision sphere centers in model coordinates, meters.

radius ​
ts
radius: number;
role ​
ts
role: 
  | "body"
  | "leftWing"
  | "rightWing"
  | "tail"
  | "rotor"
  | "tailRotor"
  | "gear"
  | "engine";

AircraftCollisionProbe ​

World-space sphere, or a finite rotor disc when disc is present.

Properties ​

center ​
ts
center: [number, number, number];
disc? ​
ts
optional disc?: object;

Radius is radial, not a bounding sphere. Normal is unit length in world space.

angularSpeed ​
ts
angularSpeed: number;
halfThickness ​
ts
halfThickness: number;
normal ​
ts
normal: [number, number, number];
part ​
ts
part: string;
radius ​
ts
radius: number;

AircraftContact ​

Normal points out of the obstacle. Point and depth are in world meters.

Properties ​

depth ​
ts
depth: number;
normal ​
ts
normal: [number, number, number];
part ​
ts
part: string;
point ​
ts
point: [number, number, number];

AircraftData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

kind ​
ts
kind: string;

Stable external entity/type id.

spec ​
ts
spec: AircraftSpec;

AircraftDebris ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

age ​
ts
age: number;
angularVelocity ​
ts
angularVelocity: [number, number, number];

Local angular velocity about +X, +Y and +Z, rad/s.

part ​
ts
part: string;
pos ​
ts
pos: [number, number, number];

World-space section center and orientation; meters and quaternion.

rot ​
ts
rot: [number, number, number, number];
velocity ​
ts
velocity: [number, number, number];

AircraftEngineInputData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

enabled? ​
ts
optional enabled?: boolean;

Individual engine switch. The common engine switch remains a master cutoff.

mixture? ​
ts
optional mixture?: number;

Fuel mixture: 0 idle cutoff, 1 full rich; omitted inherits common mixture.

power? ​
ts
optional power?: number;

Absolute throttle override, 0–1. Omitted inherits the common throttle.

propeller? ​
ts
optional propeller?: number;

Propeller RPM lever: 0 minimum governed RPM, 1 maximum; inherits common propeller.


AircraftEngineSpec ​

Extends ​

Extended by ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

afterburnerDetent? ​
ts
optional afterburnerDetent?: number;

Common throttle detent; above it reheat increases from 0 to 1. Default 0.85.

afterburnerFuelConsumption? ​
ts
optional afterburnerFuelConsumption?: number;

A jet's consumption per newton-second of total thrust at full reheat; default 5.4e-5.

afterburnerThrust? ​
ts
optional afterburnerThrust?: number;

Sea-level static thrust at full reheat, N (total, not an increment).

densityExponent? ​
ts
optional densityExponent?: number;

Density exponent for installed power/thrust lapse. Default 1 with explicit propulsion.

dryThrust? ​
ts
optional dryThrust?: number;

Sea-level static dry jet thrust, N.

fuelConsumption? ​
ts
optional fuelConsumption?: number;

Specific fuel consumption, used 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, about 0.27 kg/kWh; 9.5e-8 otherwise), kg per newton-second of thrust for a jet (default 2e-5).

highAltitudeDensityRatio? ​
ts
optional highAltitudeDensityRatio?: number;

Density-ratio knee for the upper-altitude installed-engine lapse. Optional.

highAltitudeExponent? ​
ts
optional highAltitudeExponent?: number;

Lapse exponent below that density ratio, continuous at the knee.

idleRpm ​
ts
idleRpm: number;
maxThrust? ​
ts
optional maxThrust?: number;
minPropellerSpeed? ​
ts
optional minPropellerSpeed?: number;
mixtureControl? ​
ts
optional mixtureControl?: boolean;

Manually metered piston fuel mixture; omitted/false leaves fuel scheduling automatic.

position ​
ts
position: [number, number, number];
power ​
ts
power: number;
propellerControl? ​
ts
optional propellerControl?: object;

Constant-speed propeller governor. Lever selects normalized RPM, not blade angle directly.

minRpm ​
ts
minRpm: number;
propellerEfficiency? ​
ts
optional propellerEfficiency?: number;

Optional per-engine propeller tuning; defaults to the airplane's values.

propellerInertia? ​
ts
optional propellerInertia?: number;

Propeller polar moment of inertia in kg m², for gyroscopic precession; default 0.

propellerRotation? ​
ts
optional propellerRotation?: "clockwise" | "counterclockwise";

Turning direction seen from the cockpit; default clockwise (the nose swings left).

propulsion? ​
ts
optional propulsion?: "propeller" | "jet";

Omitted retains legacy constant-power propulsion. Jets produce thrust, not shaft power.

ramRise? ​
ts
optional ramRise?: number;

Jet net-thrust multiplier per Mach squared, representing inlet ram recovery. Default 0.

ratedDensityRatio? ​
ts
optional ratedDensityRatio?: number;

Flat-rated shaft engine holds power to this density ratio; default 1.

rotorAngularSpeed ​
ts
rotorAngularSpeed: number;
spoolRate ​
ts
spoolRate: number;
thrustAxis ​
ts
thrustAxis: [number, number, number];
vectored? ​
ts
optional vectored?: boolean;

Rotate this engine's thrust from +Z toward +Y with the common vector lever.


AircraftEngineStateData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

afterburner? ​
ts
optional afterburner?: number;

Actual reheat fraction, 0..1, after spool/ignition delay.

combustion? ​
ts
optional combustion?: number;

Mixture-dependent combustion effectiveness, 0..1; zero when switched off or failed.

failed ​
ts
failed: boolean;

Latched failure; pilot throttle/switch changes cannot clear it.

rotorAngle ​
ts
rotorAngle: number;
rpm ​
ts
rpm: number;
shaftPower? ​
ts
optional shaftPower?: number;

Available delivered shaft power in watts; zero for jet engines.

thrust ​
ts
thrust: number;

Current engine thrust in newtons (zero for the helicopter's shaft engine).


AircraftInputData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

actuators? ​
ts
optional actuators?: ActuatorInputs;
brake ​
ts
brake: boolean;
cyclicMode? ​
ts
optional cyclicMode?: "assisted" | "direct";

Helicopter cyclic. assisted (the default) commands a bounded tilt that levels itself when the stick is released. direct commands pitch and roll rates with full authority, so the helicopter can loop, roll or point straight down, and holds its attitude when released. On the ground both behave as assisted.

engine ​
ts
engine: boolean;
engines? ​
ts
optional engines?: Record<string, AircraftEngineInputData>;

Optional per-engine switch/throttle overrides, keyed by engine id.

flaps ​
ts
flaps: number | boolean;
gear ​
ts
gear: boolean;
mixture? ​
ts
optional mixture?: number;

Common fuel mixture: 0 idle cutoff, 1 full rich (default). Only manually metered pistons.

pitch ​
ts
pitch: number;
power ​
ts
power: number;

Absolute engine throttle (airplane) or collective (helicopter), retained when keys release.

propeller? ​
ts
optional propeller?: number;

Common propeller governor lever: 0 minimum RPM, 1 maximum (default).

roll ​
ts
roll: number;
thrustVector? ​
ts
optional thrustVector?: number;

Powered-lift lever: 0 forward, 1 vertical. Omitted selects forward thrust.

yaw ​
ts
yaw: number;

AircraftNamedEngineSpec ​

A named installation in an airplane's engine bank. Positions use aircraft-local meters.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

afterburnerDetent? ​
ts
optional afterburnerDetent?: number;

Common throttle detent; above it reheat increases from 0 to 1. Default 0.85.

Inherited from ​

AircraftEngineSpec.afterburnerDetent

afterburnerFuelConsumption? ​
ts
optional afterburnerFuelConsumption?: number;

A jet's consumption per newton-second of total thrust at full reheat; default 5.4e-5.

Inherited from ​

AircraftEngineSpec.afterburnerFuelConsumption

afterburnerThrust? ​
ts
optional afterburnerThrust?: number;

Sea-level static thrust at full reheat, N (total, not an increment).

Inherited from ​

AircraftEngineSpec.afterburnerThrust

densityExponent? ​
ts
optional densityExponent?: number;

Density exponent for installed power/thrust lapse. Default 1 with explicit propulsion.

Inherited from ​

AircraftEngineSpec.densityExponent

dryThrust? ​
ts
optional dryThrust?: number;

Sea-level static dry jet thrust, N.

Inherited from ​

AircraftEngineSpec.dryThrust

fuelConsumption? ​
ts
optional fuelConsumption?: number;

Specific fuel consumption, used 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, about 0.27 kg/kWh; 9.5e-8 otherwise), kg per newton-second of thrust for a jet (default 2e-5).

Inherited from ​

AircraftEngineSpec.fuelConsumption

highAltitudeDensityRatio? ​
ts
optional highAltitudeDensityRatio?: number;

Density-ratio knee for the upper-altitude installed-engine lapse. Optional.

Inherited from ​

AircraftEngineSpec.highAltitudeDensityRatio

highAltitudeExponent? ​
ts
optional highAltitudeExponent?: number;

Lapse exponent below that density ratio, continuous at the knee.

Inherited from ​

AircraftEngineSpec.highAltitudeExponent

id ​
ts
id: string;
idleRpm ​
ts
idleRpm: number;
Inherited from ​

AircraftEngineSpec.idleRpm

maxThrust? ​
ts
optional maxThrust?: number;
Inherited from ​

AircraftEngineSpec.maxThrust

minPropellerSpeed? ​
ts
optional minPropellerSpeed?: number;
Inherited from ​

AircraftEngineSpec.minPropellerSpeed

mixtureControl? ​
ts
optional mixtureControl?: boolean;

Manually metered piston fuel mixture; omitted/false leaves fuel scheduling automatic.

Inherited from ​

AircraftEngineSpec.mixtureControl

position ​
ts
position: [number, number, number];
Inherited from ​

AircraftEngineSpec.position

power ​
ts
power: number;
Inherited from ​

AircraftEngineSpec.power

propellerControl? ​
ts
optional propellerControl?: object;

Constant-speed propeller governor. Lever selects normalized RPM, not blade angle directly.

minRpm ​
ts
minRpm: number;
Inherited from ​

AircraftEngineSpec.propellerControl

propellerEfficiency? ​
ts
optional propellerEfficiency?: number;

Optional per-engine propeller tuning; defaults to the airplane's values.

Inherited from ​

AircraftEngineSpec.propellerEfficiency

propellerInertia? ​
ts
optional propellerInertia?: number;

Propeller polar moment of inertia in kg m², for gyroscopic precession; default 0.

Inherited from ​

AircraftEngineSpec.propellerInertia

propellerRotation? ​
ts
optional propellerRotation?: "clockwise" | "counterclockwise";

Turning direction seen from the cockpit; default clockwise (the nose swings left).

Inherited from ​

AircraftEngineSpec.propellerRotation

propulsion? ​
ts
optional propulsion?: "propeller" | "jet";

Omitted retains legacy constant-power propulsion. Jets produce thrust, not shaft power.

Inherited from ​

AircraftEngineSpec.propulsion

ramRise? ​
ts
optional ramRise?: number;

Jet net-thrust multiplier per Mach squared, representing inlet ram recovery. Default 0.

Inherited from ​

AircraftEngineSpec.ramRise

ratedDensityRatio? ​
ts
optional ratedDensityRatio?: number;

Flat-rated shaft engine holds power to this density ratio; default 1.

Inherited from ​

AircraftEngineSpec.ratedDensityRatio

rotorAngularSpeed ​
ts
rotorAngularSpeed: number;
Inherited from ​

AircraftEngineSpec.rotorAngularSpeed

spoolRate ​
ts
spoolRate: number;
Inherited from ​

AircraftEngineSpec.spoolRate

thrustAxis ​
ts
thrustAxis: [number, number, number];
Inherited from ​

AircraftEngineSpec.thrustAxis

vectored? ​
ts
optional vectored?: boolean;

Rotate this engine's thrust from +Z toward +Y with the common vector lever.

Inherited from ​

AircraftEngineSpec.vectored


AircraftPartDamage ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

detached ​
ts
detached: boolean;
integrity ​
ts
integrity: number;

AircraftRotorBinding ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

axis ​
ts
axis: "x" | "y" | "z";
Inherited from ​

AircraftVisualBinding.axis

engine? ​
ts
optional engine?: string;

Engine id for an independent propeller. Omitted follows the first engine.

multiplier ​
ts
multiplier: number;
Inherited from ​

AircraftVisualBinding.multiplier

node ​
ts
node: string;
Inherited from ​

AircraftVisualBinding.node


AircraftSpec ​

Complete data-driven tuning consumed by the generic aircraft solver and client.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

actuators? ​
ts
optional actuators?: ActuatorSpecs;
airplane? ​
ts
optional airplane?: AirplanePhysicsSpec;
centerOfMass ​
ts
centerOfMass: [number, number, number];
collisionParts? ​
ts
optional collisionParts?: AircraftCollisionPart[];

Optional authored breakable sections. Replaces collisionProbes when present.

collisionProbes ​
ts
collisionProbes: [number, number, number][];
engine? ​
ts
optional engine?: AircraftEngineSpec;

Single-engine form, identified as "main". Supply this or engines, never both.

engines? ​
ts
optional engines?: AircraftNamedEngineSpec[];

Named independent propeller engines. Currently supported by the airplane model.

fuel? ​
ts
optional fuel?: object;

Fuel on board. mass is the aircraft with full tanks: it lightens as fuel burns, and the engines stop when the tanks are dry. Without it fuel is unlimited and the mass constant.

capacity ​
ts
capacity: number;

Usable fuel in kg with full tanks.

genericLabel? ​
ts
optional genericLabel?: string;

Name-free display label such as 'Light helicopter', for hosts that must not show the type name.

hardLandingPitch ​
ts
hardLandingPitch: number;
hardLandingRoll ​
ts
hardLandingRoll: number;
hardLandingSpeed ​
ts
hardLandingSpeed: number;
height ​
ts
height: number;
helicopter? ​
ts
optional helicopter?: HelicopterPhysicsSpec;
label ​
ts
label: string;
length ​
ts
length: number;
mass ​
ts
mass: number;
maxSupportStep ​
ts
maxSupportStep: number;
model ​
ts
model: FlightModel;
pilotEye ​
ts
pilotEye: [number, number, number];
poweredLift? ​
ts
optional poweredLift?: object;

Assisted powered-lift controls for tiltrotors and vectored jets, blended into wing flight.

controlFadeSpeed ​
ts
controlFadeSpeed: number;
damping ​
ts
damping: number;
pitchAuthority ​
ts
pitchAuthority: number;
rollAuthority ​
ts
rollAuthority: number;
transitTime ​
ts
transitTime: number;

Seconds to travel from forward thrust to vertical thrust (90 degrees).

yawAuthority ​
ts
yawAuthority: number;
span ​
ts
span: number;
visual ​
ts
visual: AircraftVisualSpec;

AircraftStateData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

actuators? ​
ts
optional actuators?: ActuatorPositions;
airspeed ​
ts
airspeed: number;
altitudeAGL ​
ts
altitudeAGL: number;
angleOfAttack ​
ts
angleOfAttack: number;
boosted? ​
ts
optional boosted?: boolean;

Kernel-owned: velocity and speed telemetry include the 4× travel boost.

buffet? ​
ts
optional buffet?: number;

Pre-stall and stalled-wing buffet, 0..1: a cue for hosts to shake the view and sound a warning. It starts a few degrees before the stall. Airplanes only.

crashed ​
ts
crashed: boolean;
damage? ​
ts
optional damage?: Record<string, AircraftPartDamage>;

Persistent joint damage. Recovery starts with a fresh aircraft state.

debris? ​
ts
optional debris?: AircraftDebris[];

Detached sections, simulated for 20 seconds; damage remains after debris expires.

departure? ​
ts
optional departure?: number;

Nonlinear departure intensity, 0..1; diagnostic, not a scripted spin switch.

elevator? ​
ts
optional elevator?: number;

Elevator position -1..1 after its travel limit. Airplanes only.

engines? ​
ts
optional engines?: Record<string, AircraftEngineStateData>;

Per-engine state, initialized by the solver and authoritative once present.

equivalentAirspeed? ​
ts
optional equivalentAirspeed?: number;

Equivalent airspeed (density-corrected TAS), m/s; not compressible calibrated IAS.

flapPosition? ​
ts
optional flapPosition?: number;

Flap position as a fraction of full travel, 0..1. Airplanes only; starts as commanded.

fuel? ​
ts
optional fuel?: number;

Fuel remaining in kg when the aircraft declares fuel; absent is full tanks.

gearPosition? ​
ts
optional gearPosition?: number;

Landing-gear position: 0 up and locked, 1 down and locked, between them in transit. The solver starts it at the commanded position; fixed undercarriages stay down.

greyout? ​
ts
optional greyout?: number;

The pilot's accumulated strain under positive g, 0..1: vision starts to dim near 0.3 and is gone at 1. It builds above the tolerance and recovers below it. Airplanes only.

grounded ​
ts
grounded: boolean;
loadFactor? ​
ts
optional loadFactor?: number;

Aerodynamic and thrust load along the airframe's up axis, in g.

mach? ​
ts
optional mach?: number;

Air-relative speed divided by local speed of sound.

overspeed? ​
ts
optional overspeed?: boolean;

Exceeding an authored airframe or deployed-surface limit.

pitch ​
ts
pitch: number;
pitchRate ​
ts
pitchRate: number;

Body pitch rate, nose up, rad/s.

pitchTrim? ​
ts
optional pitchTrim?: number;

Trimmed angle of attack in radians that the airframe flies with the stick centered.

redout? ​
ts
optional redout?: number;

The same for negative g (blood to the head), 0..1. Airplanes only.

roll ​
ts
roll: number;
rollRate ​
ts
rollRate: number;

Body roll rate, right wing down, rad/s.

rotorAngle ​
ts
rotorAngle: number;

First engine's rotor phase; independent visuals bind to engines by id.

rpm ​
ts
rpm: number;

Maximum engine RPM, retained for HUDs and safe boarding/exit checks.

sideslip? ​
ts
optional sideslip?: number;

Sideslip angle in radians, positive with the relative wind from the left.

stalled ​
ts
stalled: boolean;
thrustVectorPosition? ​
ts
optional thrustVectorPosition?: number;

Actual powered-lift lever position, 0 forward to 1 vertical, after actuator travel.

velocity ​
ts
velocity: [number, number, number];
verticalSpeed ​
ts
verticalSpeed: number;
vortexRing? ​
ts
optional vortexRing?: number;

Rotor vortex-ring lift-loss fraction, 0..1.

waitingForTerrain ​
ts
waitingForTerrain: boolean;
yaw ​
ts
yaw: number;
yawRate? ​
ts
optional yawRate?: number;

Body yaw rate about local +Y (nose left), rad/s. Airplanes only.


AircraftVisualBinding ​

Extends ​

Extended by ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

axis ​
ts
axis: "x" | "y" | "z";
multiplier ​
ts
multiplier: number;
node ​
ts
node: string;

AircraftVisualSpec ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

ailerons ​
ts
ailerons: AircraftVisualBinding[];
airspeedGaugeMax? ​
ts
optional airspeedGaugeMax?: number;

Legacy metadata; gauge calibration is owned by interior.bindings.

animation? ​
ts
optional animation?: ModelSignalSpec;

Exterior moving parts posed from the same signals as the interior: landing-gear legs and doors sequenced by keyframes over the gear position, flaps, control surfaces.

collective? ​
ts
optional collective?: AircraftVisualBinding;
controlStick? ​
ts
optional controlStick?: object;

Legacy explicit control binding. Prefer interior.bindings for new models.

node ​
ts
node: string;
pitchAxis ​
ts
pitchAxis: "x" | "y" | "z";
rollAxis ​
ts
rollAxis: "x" | "y" | "z";
flaps ​
ts
flaps: AircraftVisualBinding[];

Turn by multiplier radians at full flap travel, in proportion to the flap position.

gearNodes ​
ts
gearNodes: string[];

Legacy unrigged gear hides when fully up; position/rotation-bound nodes keep their pose.

interior? ​
ts
optional interior?: VehicleInteriorSpec;
rotors ​
ts
rotors: AircraftRotorBinding[];

AirplanePhysicsSpec ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

autoTrim? ​
ts
optional autoTrim?: number;

Rate in 1/s at which trim follows the angle of attack that holds the flight path; default 1.

brakeDeceleration ​
ts
brakeDeceleration: number;
camberAngle ​
ts
camberAngle: number;
controlAuthoritySpeed ​
ts
controlAuthoritySpeed: number;

Reference equivalent airspeed in m/s for the control and stability rates below.

criticalMach? ​
ts
optional criticalMach?: number;

Mach at which wave drag starts rising. Omitted disables compressibility drag.

departure? ​
ts
optional departure?: object;

Optional nonlinear high-alpha departure model; coefficients are empirical estimates.

aileronReversal ​
ts
aileronReversal: number;
fullAngle ​
ts
fullAngle: number;
onsetAngle ​
ts
onsetAngle: number;
pitchBlanking ​
ts
pitchBlanking: number;
rudderBlanking ​
ts
rudderBlanking: number;
yawInstability ​
ts
yawInstability: number;
yawSaturationRate ​
ts
yawSaturationRate: number;
dihedralEffect? ​
ts
optional dihedralEffect?: number;

Roll acceleration in rad/s² per radian of sideslip at reference speed; default 3.

directionalStability? ​
ts
optional directionalStability?: number;

Weathercock stiffness: yaw acceleration in rad/s² per radian of sideslip at reference speed; default 4.

fixedGear? ​
ts
optional fixedGear?: boolean;

Fixed undercarriage stays down even if the pilot selects gear up. Default false.

flapDrag ​
ts
flapDrag: number;

Drag coefficient of the flaps fully down; scales with the flap position.

flapLift ​
ts
flapLift: number;
flapLimitSpeed? ​
ts
optional flapLimitSpeed?: number;
flapTransitTime? ​
ts
optional flapTransitTime?: number;

Seconds for the flaps to travel fully up to fully down; default 0 (instant).

gearDrag ​
ts
gearDrag: number;

Drag coefficient of the landing gear fully down; scales with the gear position.

gearLimitSpeed? ​
ts
optional gearLimitSpeed?: number;
gearRebound? ​
ts
optional gearRebound?: number;

Share of the sink speed beyond a gentle 0.6 m/s that the struts and tires give back at touchdown; default 0.45. A firm landing skips, a greased one stays down.

gearTransitTime? ​
ts
optional gearTransitTime?: number;

Seconds for a full landing-gear cycle, doors included, either way; default 0 (instant). The gear holds still while the wheels carry weight, and only a locked-down gear can land.

groundEffect? ​
ts
optional groundEffect?: boolean;

Wing ground effect: reduction of induced drag close to the surface. Default false.

groundLevelRate ​
ts
groundLevelRate: number;
groundSteerSpeed ​
ts
groundSteerSpeed: number;
groundTrackRate ​
ts
groundTrackRate: number;

Tire side grip: lateral deceleration in m/s² and yaw grip in 1/s with full weight on the wheels.

inducedDrag ​
ts
inducedDrag: number;
lateralDamping ​
ts
lateralDamping: number;
liftSlope ​
ts
liftSlope: number;
maxControlAuthority ​
ts
maxControlAuthority: number;

Cap on control-surface power relative to the reference speed.

maxEquivalentAirspeed? ​
ts
optional maxEquivalentAirspeed?: number;

Operating limits flag overspeed; they do not clamp velocity. Speeds in m/s EAS.

maxGroundPitch ​
ts
maxGroundPitch: number;
maxLoadFactor? ​
ts
optional maxLoadFactor?: number;

Positive load-factor limit in g that full back stick will pull; default 6.

maxMach? ​
ts
optional maxMach?: number;
maxThrust ​
ts
maxThrust: number;
minLoadFactor? ​
ts
optional minLoadFactor?: number;

Negative load-factor limit in g that full forward stick will push; default -3.

minPropellerSpeed ​
ts
minPropellerSpeed: number;
pilotGTolerance? ​
ts
optional pilotGTolerance?: number;

Sustained positive g the pilot holds before vision starts to dim; default 4.5, or 6.5 (a g-suit) when maxLoadFactor is 7.5 or more.

pitchAuthority ​
ts
pitchAuthority: number;

Angle of attack in radians that full elevator adds to the trim angle.

pitchDamping? ​
ts
optional pitchDamping?: number;

Short-period damping ratio; default 0.7.

pitchFrequency? ​
ts
optional pitchFrequency?: number;

Short-period natural frequency in rad/s at reference speed; default 3.5.

pitchInertia? ​
ts
optional pitchInertia?: number;

Pitch moment of inertia in kg m²; defaults to mass * (0.18 length)².

pitchResponse ​
ts
pitchResponse: number;

Elevator travel per second, in full deflections.

postStallDecay ​
ts
postStallDecay: number;
postStallFlapEffect ​
ts
postStallFlapEffect: number;
postStallLift ​
ts
postStallLift: number;
profileDrag ​
ts
profileDrag: number;
propellerEffects? ​
ts
optional propellerEffects?: number;

Scale 0–1 of propeller torque, P-factor, slipstream and gyroscopic effects; default 0.

propellerEfficiency ​
ts
propellerEfficiency: number;
rollAuthority ​
ts
rollAuthority: number;

Roll rate in rad/s at full aileron and reference speed; grows with speed to the cap.

rollInertia? ​
ts
optional rollInertia?: number;

Roll moment of inertia in kg m²; defaults to mass * (0.14 span)².

rollingDeceleration ​
ts
rollingDeceleration: number;
rollResponse ​
ts
rollResponse: number;

Roll damping in 1/s at reference speed; grows with speed.

rudderAuthority ​
ts
rudderAuthority: number;

Yaw acceleration in rad/s² at full rudder and reference speed; propwash keeps some at rest.

speedBrakeDrag? ​
ts
optional speedBrakeDrag?: number;

Additional drag coefficient at full speed-brake actuator extension.

stallAngle ​
ts
stallAngle: number;
stallDrag ​
ts
stallDrag: number;

Broadside separated-flow drag coefficient, blended by separation and sin(alpha)^2.

stallPitchRate ​
ts
stallPitchRate: number;

Nose-down pitch rate in rad/s at full flow separation (the stall break).

stallSpeed ​
ts
stallSpeed: number;

Legacy tuning reference in m/s; stall detection uses angle of attack.

stallTransitionAngle? ​
ts
optional stallTransitionAngle?: number;

Radians beyond stallAngle over which flow separates smoothly; default 0.12.

tailwheel? ​
ts
optional tailwheel?: boolean;

Main wheels ahead of the center of mass with a tailwheel behind: a firm touchdown on the mains pitches the nose up (and the airplane back into the air), and hard braking lifts the tail. Default false: a nosewheel, which a touchdown pitches down onto.

waveDrag? ​
ts
optional waveDrag?: number;

Added wave-drag coefficient at criticalMach + 0.25. Default 0.

wingArea ​
ts
wingArea: number;
wingPosition ​
ts
wingPosition: [number, number, number];
yawDamping? ​
ts
optional yawDamping?: number;

Yaw damping in 1/s at reference speed; default 1.2.

yawInertia? ​
ts
optional yawInertia?: number;

Yaw moment of inertia in kg m²; defaults to mass * (span² + length²) / 12.


AssertionDoc ​

Properties ​

assertions ​
ts
assertions: Assertion[];
format ​
ts
format: "molen/assert@1";

AssetBounds ​

Properties ​

aabb ​
ts
aabb: object;
max ​
ts
max: [number, number, number];
min ​
ts
min: [number, number, number];
sphere ​
ts
sphere: object;
center ​
ts
center: [number, number, number];
radius ​
ts
radius: number;

AssetCollision ​

Properties ​

hulls ​
ts
hulls: AssetHull[];
trimesh? ​
ts
optional trimesh?: AssetTrimeshHeader;

AssetHull ​

Properties ​

node ​
ts
node: string;

Mesh-bearing node the hull was computed from.

points ​
ts
points: number[];

Flat xyz triples, ≤ 64 vertices, rounded to 1e-4.


AssetRuntimeLod ​

Independently fetched, source-derived representations, ordered coarse to fine.

Properties ​

bytes ​
ts
bytes: number;
cpuBytes ​
ts
cpuBytes: number;
drawCalls ​
ts
drawCalls: number;
errorMeters ​
ts
errorMeters: number;
file ​
ts
file: string;
gpuBytes ​
ts
gpuBytes: number;
gzipBytes ​
ts
gzipBytes: number;
hash ​
ts
hash: string;
name ​
ts
name: "skyline" | "district" | "street" | "closeup";
triangles ​
ts
triangles: number;

AssetRuntimeLods ​

Properties ​

levels ​
ts
levels: AssetRuntimeLod[];
masterHash ​
ts
masterHash: string;
recipe ​
ts
recipe: number;
recipeHash? ​
ts
optional recipeHash?: string;

AssetSidecar ​

Properties ​

animations ​
ts
animations: object[];
channels ​
ts
channels: number;
durationSec ​
ts
durationSec: number;
name ​
ts
name: string;
bounds ​
ts
bounds: AssetBounds;
collision ​
ts
collision: AssetCollision;
extensionsUsed ​
ts
extensionsUsed: string[];
files ​
ts
files: object;
collision? ​
ts
optional collision?: string;
main ​
ts
main: string;
variants ​
ts
variants: Record<string, string>;
format ​
ts
format: "molen/asset@1";
hash ​
ts
hash: string;

sha256 of files.main.

id ​
ts
id: string;
kind ​
ts
kind: "model" | "audio";
materials ​
ts
materials: object[];
alphaMode ​
ts
alphaMode: "OPAQUE" | "MASK" | "BLEND";
doubleSided ​
ts
doubleSided: boolean;
name ​
ts
name: string;
slots ​
ts
slots: ("baseColor" | "roughness" | "metalness" | "normal" | "emissive" | "ao")[];
nodes ​
ts
nodes: object[];

Named mesh-bearing nodes (capped; see nodesTruncated).

name ​
ts
name: string;
triangles ​
ts
triangles: number;
nodesTruncated ​
ts
nodesTruncated: boolean;
runtimeLods? ​
ts
optional runtimeLods?: AssetRuntimeLods;

Runtime representations; files.main remains the unchanged detailed master.

sourceHash? ​
ts
optional sourceHash?: string;

sha256 of the pre-import source file.

stats ​
ts
stats: AssetStats;

AssetStats ​

Properties ​

animations ​
ts
animations: number;
materials ​
ts
materials: number;
meshes ​
ts
meshes: number;
primitives ​
ts
primitives: number;
sizeBytes ​
ts
sizeBytes: number;
textures ​
ts
textures: number;
triangles ​
ts
triangles: number;
vertices ​
ts
vertices: number;

AssetTrimeshHeader ​

Properties ​

bin ​
ts
bin: string;

Sidecar-relative filename of the collision binary.

hash ​
ts
hash: string;

sha256 of the binary file.

indices ​
ts
indices: object;

u32le triangle indices.

byteOffset ​
ts
byteOffset: number;
count ​
ts
count: number;
positions ​
ts
positions: object;

f32le xyz triples.

byteOffset ​
ts
byteOffset: number;
count ​
ts
count: number;

BoatData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

color? ​
ts
optional color?: string;
kind ​
ts
kind: string;
spec ​
ts
spec: BoatSpec;
visual ​
ts
visual: VehicleVisualSpec;

BoatInputData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

anchor ​
ts
anchor: boolean;

Drops anchor only at low speed; release before applying thrust.

steering ​
ts
steering: number;
throttle ​
ts
throttle: number;

BoatSpec ​

Hull tuning; the model origin is the waterline.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

buoyancyFrequency ​
ts
buoyancyFrequency: number;

Buoyancy spring frequency in Hz.

draft ​
ts
draft: number;
driverEye ​
ts
driverEye: [number, number, number];
height ​
ts
height: number;
label ​
ts
label: string;
lateralDrag ​
ts
lateralDrag: number;

Lateral resistance per second.

length ​
ts
length: number;
mass ​
ts
mass: number;
maxSpeed ​
ts
maxSpeed: number;
reverseSpeed ​
ts
reverseSpeed: number;
thrust ​
ts
thrust: number;
turnRate ​
ts
turnRate: number;

Maximum turn rate at cruise, rad/s.

turnResponse ​
ts
turnResponse: number;

Time to build or lose yaw rate, seconds.

width ​
ts
width: number;

BoatStateData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

anchored ​
ts
anchored: boolean;
boosted? ​
ts
optional boosted?: boolean;

Kernel-owned: horizontal velocities include the 4× travel boost.

grounded ​
ts
grounded: boolean;
lateralSpeed ​
ts
lateralSpeed: number;
pitch ​
ts
pitch: number;
roll ​
ts
roll: number;
speed ​
ts
speed: number;
steer ​
ts
steer: number;
velocity ​
ts
velocity: [number, number];

World velocity [east, south], including current.

vy ​
ts
vy: number;
waitingForWater ​
ts
waitingForWater: boolean;
yaw ​
ts
yaw: number;
yawRate ​
ts
yawRate: number;

Command ​

Properties ​

kind ​
ts
kind: "command";
payload ​
ts
payload: JsonValue;
seq ​
ts
seq: number;

Per-source monotonic sequence number: dedupe + deterministic total order.

source ​
ts
source: string;

Peer/agent identity: "local" in single-player, "agent:..." from tooling.

tick ​
ts
tick: number;

Requested execution tick (client-stamped).

tickExecuted? ​
ts
optional tickExecuted?: number;

Set by the kernel when a late command is re-stamped; replay logs store it.

type ​
ts
type: string;

CommandMessage ​

Properties ​

command ​
ts
command: Command;
type ​
ts
type: "command";

CommandQueueState ​

Accepted future commands and live-source deduplication cursors.

Properties ​

highestSeq ​
ts
highestSeq: Record<string, number>;
latePolicy ​
ts
latePolicy: "rewrite" | "reject";
pending ​
ts
pending: Command[];

ComponentEntry ​

Properties ​

meta ​
ts
meta: ComponentMeta;
name ​
ts
name: string;
zod ​
ts
zod: ZodType;

ComponentMeta ​

Properties ​

description ​
ts
description: string;

One-line human/agent description.

docsRef? ​
ts
optional docsRef?: string;
examples ​
ts
examples: JsonValue[];

At least one valid example of the component's data; feeds hints and docs.

owner? ​
ts
optional owner?: string;

Owning layer, for docs grouping.


ComponentSummary ​

Properties ​

description ​
ts
description: string;
name ​
ts
name: string;
owner? ​
ts
optional owner?: string;

ComponentValidateOptions ​

Extended by ​

Properties ​

allowUnknownComponents? ​
ts
optional allowUnknownComponents?: boolean;

When true, unknown component names are never flagged (not even near-typos).

partial? ​
ts
optional partial?: boolean;

The data is a partial layer (entity overrides, or components stacked on a prefab/type base): keep the unknown-name did-you-mean but skip shape validation — only the RESOLVED component map can be checked for completeness.

registry? ​
ts
optional registry?: ComponentRegistry;

ContentIdentityEntry ​

One content domain a world was built from (e.g. "types", "places").

Properties ​

hash ​
ts
hash: string;

Hash of the domain's content, from the library that loaded it.

packs? ​
ts
optional packs?: string[];

The packs it came from, as "id@version".


ControlMessage ​

Properties ​

control ​
ts
control: ControlAction;
type ​
ts
type: "control";

CustomComponentDecl ​

A declared custom component: docs + examples, optionally a JSON Schema for its data.

Properties ​

description ​
ts
description: string;
examples ​
ts
examples: JsonValue[];
schema? ​
ts
optional schema?: JsonObject;

CustomSkyData ​

Extends ​

Properties ​

dome? ​
ts
optional dome?: object;
brightness? ​
ts
optional brightness?: number;
Inherited from ​

SkyAppearance.dome

lighting? ​
ts
optional lighting?: object;
castShadow? ​
ts
optional castShadow?: boolean;
dayAmbient? ​
ts
optional dayAmbient?: number;
moonIntensity? ​
ts
optional moonIntensity?: number;
nightAmbient? ​
ts
optional nightAmbient?: number;
referenceElevation? ​
ts
optional referenceElevation?: number;
skyLightSaturation? ​
ts
optional skyLightSaturation?: number;
sunIntensity? ​
ts
optional sunIntensity?: number;
Inherited from ​

SkyAppearance.lighting

mode ​
ts
mode: "custom";
moon? ​
ts
optional moon?: object;
earthshine? ​
ts
optional earthshine?: number;
size? ​
ts
optional size?: number;
visible? ​
ts
optional visible?: boolean;
Inherited from ​

SkyAppearance.moon

moonBody? ​
ts
optional moonBody?: SkyBodyData;
palette? ​
ts
optional palette?: SkyPalette;
Inherited from ​

SkyAppearance.palette

starRotationDeg? ​
ts
optional starRotationDeg?: [number, number, number];
stars? ​
ts
optional stars?: object;
enabled? ​
ts
optional enabled?: boolean;
intensity? ​
ts
optional intensity?: number;
magnitudeLimit? ​
ts
optional magnitudeLimit?: number;
size? ​
ts
optional size?: number;
Inherited from ​

SkyAppearance.stars

sun? ​
ts
optional sun?: object;
size? ​
ts
optional size?: number;
visible? ​
ts
optional visible?: boolean;
Inherited from ​

SkyAppearance.sun

sunBody ​
ts
sunBody: SkyBodyData;

CycleSpec ​

Self-balancing two-wheel handling and metric rider contact points, in model space.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

footrests ​
ts
footrests: [[number, number, number], [number, number, number]];

Left, then right ankle targets on the footrests or deck (used without pedals).

Inherited from ​

HandlebarSpec.footrests

grips ​
ts
grips: [[number, number, number], [number, number, number]];

Left, then right hand grips; they turn with the bars about handlebarPivot. A sideways rider has no bars: these are free hand positions for an adult, which do not turn and move with the hips of a shorter or taller body.

Inherited from ​

HandlebarSpec.grips

handlebarPivot ​
ts
handlebarPivot: [number, number, number];
Inherited from ​

HandlebarSpec.handlebarPivot

kick? ​
ts
optional kick?: object;

Push-powered (a skateboard): under power the rider turns forward and pushes off the ground with the rear foot, one push per stride meters travelled, then rides sideways again.

stride ​
ts
stride: number;

Meters travelled per push.

maxLean ​
ts
maxLean: number;
pedals? ​
ts
optional pedals?: object;
center ​
ts
center: [number, number, number];
halfWidth ​
ts
halfWidth: number;
radius ​
ts
radius: number;
ratio ​
ts
ratio: number;
riderLean ​
ts
riderLean: number;

Forward torso lean in radians.

Inherited from ​

HandlebarSpec.riderLean

stance? ​
ts
optional stance?: CycleStance;

DeclaredComponent ​

The shape of a project/scene-declared custom component (molen/project@1, molen/scene@3).

Properties ​

description ​
ts
description: string;
examples ​
ts
examples: JsonValue[];
schema? ​
ts
optional schema?: JsonObject;

JSON Schema for the data; omitted = any object.


Delta ​

Properties ​

baseTick ​
ts
baseTick: number;
changed ​
ts
changed: Record<EntityId, ComponentMap>;

Whole-component replacement granularity.

destroyed ​
ts
destroyed: string[];
events ​
ts
events: EngineEvent[];
kind ​
ts
kind: "delta";
removedComponents ​
ts
removedComponents: Record<EntityId, string[]>;
spawned ​
ts
spawned: Record<EntityId, ComponentMap>;
tick ​
ts
tick: number;
v ​
ts
v: 1;

DeltaMessage ​

Properties ​

delta ​
ts
delta: Delta;
type ​
ts
type: "delta";

DiagMessage ​

Properties ​

code ​
ts
code: 
  | "tick-overrun"
  | "command-rejected"
  | "protocol-error"
  | "control-rejected"
  | "tick-failed"
  | "link-error"
  | "frame-error";
detail ​
ts
detail: string;
type ​
ts
type: "diag";

EarthObserver ​

Properties ​

elevation? ​
ts
optional elevation?: number;
latitude ​
ts
latitude: number;
longitude ​
ts
longitude: number;
northOffsetDeg? ​
ts
optional northOffsetDeg?: number;

EarthSkyData ​

Extends ​

Properties ​

dome? ​
ts
optional dome?: object;
brightness? ​
ts
optional brightness?: number;
Inherited from ​

SkyAppearance.dome

lighting? ​
ts
optional lighting?: object;
castShadow? ​
ts
optional castShadow?: boolean;
dayAmbient? ​
ts
optional dayAmbient?: number;
moonIntensity? ​
ts
optional moonIntensity?: number;
nightAmbient? ​
ts
optional nightAmbient?: number;
referenceElevation? ​
ts
optional referenceElevation?: number;
skyLightSaturation? ​
ts
optional skyLightSaturation?: number;
sunIntensity? ​
ts
optional sunIntensity?: number;
Inherited from ​

SkyAppearance.lighting

mode ​
ts
mode: "earth";
moon? ​
ts
optional moon?: object;
earthshine? ​
ts
optional earthshine?: number;
size? ​
ts
optional size?: number;
visible? ​
ts
optional visible?: boolean;
Inherited from ​

SkyAppearance.moon

observer ​
ts
observer: EarthObserver;
palette? ​
ts
optional palette?: SkyPalette;
Inherited from ​

SkyAppearance.palette

stars? ​
ts
optional stars?: object;
enabled? ​
ts
optional enabled?: boolean;
intensity? ​
ts
optional intensity?: number;
magnitudeLimit? ​
ts
optional magnitudeLimit?: number;
size? ​
ts
optional size?: number;
Inherited from ​

SkyAppearance.stars

sun? ​
ts
optional sun?: object;
size? ​
ts
optional size?: number;
visible? ​
ts
optional visible?: boolean;
Inherited from ​

SkyAppearance.sun

time ​
ts
time: SkyTime;

EngineEvent ​

Properties ​

payload ​
ts
payload: JsonValue;
type ​
ts
type: string;

EntityTypeDef ​

Properties ​

assets ​
ts
assets: string[];

Project asset ids this type depends on.

components ​
ts
components: ComponentMap;

Default components applied below prefab/entity data.

doc? ​
ts
optional doc?: string;
extends? ​
ts
optional extends?: string;

Full id of another registry type to inherit from (deep-merged, ancestor-first).

scripts ​
ts
scripts: ScriptRef[];

Deterministic behavior installed once per world for this external entity type.


EventAssertion ​

Properties ​

event ​
ts
event: string;
op ​
ts
op: "occurred" | "never" | "count" | "at_tick";
value? ​
ts
optional value?: number;

GamepadAxisBinding ​

Any raw axis index, including non-standard flight sticks, pedals and throttles.

Properties ​

action ​
ts
action: string;
axis ​
ts
axis: number;
center? ​
ts
optional center?: number;
curve? ​
ts
optional curve?: number;

Response exponent > 0 (default 1).

deadZone? ​
ts
optional deadZone?: number;

Rescaled dead zone in [0, 1). Defaults to 0.12, or 0 for unit axes.

device? ​
ts
optional device?: InputDevice;
invert? ​
ts
optional invert?: boolean;
max? ​
ts
optional max?: number;
min? ​
ts
optional min?: number;

Raw endpoints and center (defaults -1, 0, 1); min < center < max.

mode? ​
ts
optional mode?: "signed" | "positive" | "negative" | "unit";

signed: -1..1; positive/negative: one half of a stick; unit: full travel mapped to 0..1.


GamepadButtonBinding ​

Properties ​

action ​
ts
action: string;
button ​
ts
button: number;
device? ​
ts
optional device?: InputDevice;
threshold? ​
ts
optional threshold?: number;

Press threshold for analog buttons (default 0.5).


GlassData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

crashPulseSeconds? ​
ts
optional crashPulseSeconds?: number;

Physical crash pulse, independent of simulation substeps; default 0.06 s.

surfaces ​
ts
surfaces: GlassSurfaceSpec[];

GlassImpact ​

A resolved contact load, not vehicle speed. Impulse is in the owner's frame, in N s.

Extends ​

Extended by ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

distributed? ​
ts
optional distributed?: boolean;

Uniform inertial loading instead of a point contact.

duration ​
ts
duration: number;
energy ​
ts
energy: number;
impulse ​
ts
impulse: [number, number, number];
point ​
ts
point: [number, number];

Contact in pane XY coordinates, meters from its center.


GlassImpactEvent ​

A resolved contact load, not vehicle speed. Impulse is in the owner's frame, in N s.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

distributed? ​
ts
optional distributed?: boolean;

Uniform inertial loading instead of a point contact.

Inherited from ​

GlassImpact.distributed

duration ​
ts
duration: number;
Inherited from ​

GlassImpact.duration

energy ​
ts
energy: number;
Inherited from ​

GlassImpact.energy

entity ​
ts
entity: string;
impulse ​
ts
impulse: [number, number, number];
Inherited from ​

GlassImpact.impulse

point ​
ts
point: [number, number];

Contact in pane XY coordinates, meters from its center.

Inherited from ​

GlassImpact.point

surface ​
ts
surface: string;
velocity? ​
ts
optional velocity?: [number, number, number];

Owner's world velocity at this pane, for released visual fragments.


GlassRelease ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

fragmentSpeed? ​
ts
optional fragmentSpeed?: number;
position ​
ts
position: [number, number, number];
rotation ​
ts
rotation: [number, number, number, number];
time ​
ts
time: number;
velocity ​
ts
velocity: [number, number, number];

GlassStateData ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

surfaces ​
ts
surfaces: Record<string, GlassSurfaceState>;

GlassSurfaceSpec ​

A rectangular pane in its owner's metric frame. Local XY is the pane, +Z its normal.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

center ​
ts
center: [number, number, number];
density? ​
ts
optional density?: number;
fractureEnergy? ​
ts
optional fractureEnergy?: number;
id ​
ts
id: string;
material ​
ts
material: GlassMaterial;
nodes? ​
ts
optional nodes?: string[];

Dedicated pane meshes/groups. Omit to draw a procedural pane.

retentionEnergy? ​
ts
optional retentionEnergy?: number;
retentionForce? ​
ts
optional retentionForce?: number;
rotation ​
ts
rotation: [number, number, number, number];
size ​
ts
size: [number, number];
strength? ​
ts
optional strength?: number;
thickness ​
ts
thickness: number;

GlassSurfaceState ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

damage ​
ts
damage: number;
fracture ​
ts
fracture: "intact" | "cracked" | "shattered";
peakStress ​
ts
peakStress: number;
point ​
ts
point: [number, number];
release? ​
ts
optional release?: GlassRelease;
retained ​
ts
retained: boolean;
retentionDamage ​
ts
retentionDamage: number;

HandlebarSpec ​

Where a rider's hands and feet go, in model space, for a vehicle steered by handlebars rather than a wheel. The driver seat is the pelvis anchor.

Extends ​

Extended by ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

footrests ​
ts
footrests: [[number, number, number], [number, number, number]];

Left, then right ankle targets on the footrests or deck (used without pedals).

grips ​
ts
grips: [[number, number, number], [number, number, number]];

Left, then right hand grips; they turn with the bars about handlebarPivot. A sideways rider has no bars: these are free hand positions for an adult, which do not turn and move with the hips of a shorter or taller body.

handlebarPivot ​
ts
handlebarPivot: [number, number, number];
riderLean ​
ts
riderLean: number;

Forward torso lean in radians.


HelicopterPhysicsSpec ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

cyclicDamping ​
ts
cyclicDamping: number;
cyclicRate? ​
ts
optional cyclicRate?: number;

Direct-cyclic pitch and roll rate at full stick with the rotor carrying the weight, rad/s. Default cyclicResponse / 4.

cyclicResponse ​
ts
cyclicResponse: number;
cyclicTilt ​
ts
cyclicTilt: number;
directionalStability? ​
ts
optional directionalStability?: number;

Tail-fin weathervaning in forward flight, default 1; 0 disables it. The nose turns into the relative wind at directionalStability × airspeed / length rad/s per radian of sideslip, fading out below about a fifth of translationalLiftSpeed, so a banked helicopter's nose follows its turning track.

fixedGear? ​
ts
optional fixedGear?: boolean;

Fixed skids/wheels by default; false enables retractable gear.

gearTransitTime? ​
ts
optional gearTransitTime?: number;
groundDeceleration ​
ts
groundDeceleration: number;
groundEffect ​
ts
groundEffect: number;
groundLevelRate ​
ts
groundLevelRate: number;
horizontalDrag ​
ts
horizontalDrag: number;
hubStiffness? ​
ts
optional hubStiffness?: number;

Share of direct-cyclic control power that does not depend on rotor thrust, 0..1, default 0.25. The rest fades as the rotor unloads: near 0 for a teetering rotor, which has no control at zero g, higher for articulated and most for hingeless rotors.

liftMultiplier ​
ts
liftMultiplier: number;
maxTilt ​
ts
maxTilt: number;
powerLimitedRotor? ​
ts
optional powerLimitedRotor?: boolean;

Govern rotor RPM independently of collective and limit lift to available shaft power.

profilePowerFraction? ​
ts
optional profilePowerFraction?: number;

Shaft-power fraction used by rotor profile drag at governed RPM; default 0.12.

quadraticDrag ​
ts
quadraticDrag: number;
retreatingBladeSpeed? ​
ts
optional retreatingBladeSpeed?: number;

Sea-level TAS for retreating-blade stall onset, m/s; decreases with density and rotor RPM.

rotorDiscs? ​
ts
optional rotorDiscs?: number;

Effective lifting disc count (e.g. 2 for tandem rotors), default 1.

rotorEfficiency? ​
ts
optional rotorEfficiency?: number;

Induced-power efficiency, 0..1; default 0.75.

rotorInertiaTime? ​
ts
optional rotorInertiaTime?: number;

Seconds of hover power stored in the turning rotor at full speed; default 2. With the engine out in flight the rotor lives on this and on the air it descends through (autorotation): a heavy rotor forgives a late flare, a light one does not. Needs powerLimitedRotor.

rotorPosition ​
ts
rotorPosition: [number, number, number];
rotorRadius ​
ts
rotorRadius: number;
translationalLift ​
ts
translationalLift: number;
translationalLiftSpeed ​
ts
translationalLiftSpeed: number;
verticalDrag ​
ts
verticalDrag: number;
vortexRing? ​
ts
optional vortexRing?: boolean;

Optional rotor aerodynamic penalties; assisted rotor model, not blade-element dynamics.

yawRate ​
ts
yawRate: number;

InputDevice ​

Browser controller selector. Omit to accept any detected device; combine to disambiguate twins.

Properties ​

id? ​
ts
optional id?: string;
index? ​
ts
optional index?: number;

InputProfile ​

Serializable, complete set of physical bindings for one use case.

Extended by ​

Properties ​

axes? ​
ts
optional axes?: GamepadAxisBinding[];
bindings ​
ts
bindings: Record<string, string>;

KeyboardEvent.code or Mouse<button> -> named action.

buttons? ​
ts
optional buttons?: GamepadButtonBinding[];

JsonObject ​

Extended by ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Keyframe ​

Properties ​

commands? ​
ts
optional commands?: CommandQueueState;

Absent in older saves, which restore with an empty queue.

engine ​
ts
engine: string;
entities ​
ts
entities: Record<EntityId, ComponentMap>;
entityOrder? ​
ts
optional entityOrder?: string[];

Explicit creation order (including integer-like ids); absent in older saves.

kind ​
ts
kind: "keyframe";
nextEntitySeq ​
ts
nextEntitySeq: number;
plugins ​
ts
plugins: Record<string, JsonValue>;

Opaque per-plugin snapshot blobs (e.g. Rapier).

rng ​
ts
rng: RngState;
seed ​
ts
seed: string | number;
tick ​
ts
tick: number;
tickRate ​
ts
tickRate: number;
v ​
ts
v: 1;

KeyframeMessage ​

A full snapshot plus the events of the tick it was taken on (a keyframe replaces that tick's delta, so its events ride along; deltas carry theirs in delta.events). One ordering rule for the client: apply the state, then dispatch the message's events at its tick.

Properties ​

events ​
ts
events: EngineEvent[];
keyframe ​
ts
keyframe: Keyframe;
type ​
ts
type: "keyframe";

LegacySchemaVersion ​

Properties ​

examples ​
ts
examples: JsonValue[];

At least one valid legacy example (feeds cross-validation tests and migrate docs).

id ​
ts
id: string;

The legacy format envelope id, e.g. "molen/scene@1".

upgrade ​
ts
upgrade: (legacyParsed) => unknown;

Pure upgrade from this version's parsed shape to the CURRENT version's shape.

Parameters ​
legacyParsed ​

unknown

Returns ​

unknown

zod ​
ts
zod: ZodType;

LiveryAnchor ​

A projector in the rest-pose bounds of a paint slot (or its named subtree).

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

position ​
ts
position: [number, number, number];

Fractions of the bound's extent, from its minimum corner.

rotation ​
ts
rotation: [number, number, number];

XYZ Euler radians; the projector's +Z points out of the painted surface.

size ​
ts
size: [number, number, number];

Projector width, height and depth as fractions of the longest bound dimension.

slot ​
ts
slot: string;

LiveryData ​

Shared by vehicles, aircraft, boats and ordinary glTF props. No simulation behavior.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

anchors? ​
ts
optional anchors?: Record<string, LiveryAnchor>;
selected ​
ts
selected: string;
slots ​
ts
slots: Record<string, LiverySlot>;
variants ​
ts
variants: LiveryVariant[];

LiveryGraphic ​

Original flat artwork, including font outlines; coordinates are 0..1, Y up.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

label? ​
ts
optional label?: string;
shapes ​
ts
shapes: object[];
color ​
ts
color: string;
points ​
ts
points: [number, number][];

LiveryPaint ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

camouflage? ​
ts
optional camouflage?: object;

Deterministic, model-space camouflage, independent of authored UVs.

colors ​
ts
colors: string[];
scale ​
ts
scale: number;
seed ​
ts
seed: number;
color ​
ts
color: string;
metalness? ​
ts
optional metalness?: number;
roughness? ​
ts
optional roughness?: number;

LiverySlot ​

Model-owned binding. Names, never mesh indices or texture UV coordinates.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

materials ​
ts
materials: string[];
node? ​
ts
optional node?: string;

Optional named subtree restriction.


LiveryVariant ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

id ​
ts
id: string;
label ​
ts
label: string;
markings? ​
ts
optional markings?: object[];
anchor ​
ts
anchor: string;
graphic ​
ts
graphic: LiveryGraphic;
paints ​
ts
paints: Record<string, LiveryPaint>;
provenance ​
ts
provenance: object;

Be explicit about approximation; a reference URL alone is not verification.

kind ​
ts
kind: "photo" | "inspired" | "original";
note ​
ts
note: string;
references ​
ts
references: object[];

Properties ​

onmessage? ​
ts
optional onmessage?: MessageEventLike | null;

Methods ​

addEventListener()? ​
ts
optional addEventListener(type, listener): void;
Parameters ​
type ​

"message"

listener ​

MessageEventLike

Returns ​

void

postMessage() ​
ts
postMessage(message): void;
Parameters ​
message ​

unknown

Returns ​

void

removeEventListener()? ​
ts
optional removeEventListener(type, listener): void;
Parameters ​
type ​

"message"

listener ​

MessageEventLike

Returns ​

void


ModelSignalBinding ​

Numeric simulation state mapped to an existing model's local transform channels. A binding is calibrated either linearly (scale, offset) or by a keyframed curve (keys), which can hold a part still over part of the signal's range: a landing-gear door opens, waits while the leg swings, then closes, all driven by one gear position.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

axis? ​
ts
optional axis?: "x" | "y" | "z";

Required for transforms; omit for visibility (calibrated value > 0 means visible).

ease? ​
ts
optional ease?: "linear" | "smooth";

Between keys: linear (default), or smooth to ease out of and into every key.

keys? ​
ts
optional keys?: [number, number][];

Keyframed calibration: [signal, displacement] pairs with strictly ascending signals. The displacement holds the first or last key's value outside their range.

max? ​
ts
optional max?: number;
min? ​
ts
optional min?: number;
missing? ​
ts
optional missing?: "hold" | "rest" | "hide";

Missing/nonfinite readings hold the last pose (default) or restore the authored pose.

node ​
ts
node: string;
offset? ​
ts
optional offset?: number;
period? ​
ts
optional period?: number;

Positive output period; rotation only. Filtering follows the shortest arc.

property ​
ts
property: "position" | "rotation" | "visible";
responseSeconds? ​
ts
optional responseSeconds?: number;

First-order response time constant in simulation seconds; zero/default is immediate.

scale? ​
ts
optional scale?: number;

Linear calibration: the displacement is signal * scale + offset. Omit with keys.

source ​
ts
source: string;

ModelSignalExpression ​

Data-only expressions; name intermediate results instead of nesting executable strings.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

args ​
ts
args: ModelSignalOperand[];
op ​
ts
op: ModelSignalOperator;

ModelSignalSource ​

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

component ​
ts
component: string;
path ​
ts
path: (string | number)[];

Explicit segments; component and property names may contain dots.


ModelSignalSpec ​

Extends ​

Extended by ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

bindings ​
ts
bindings: ModelSignalBinding[];
derived? ​
ts
optional derived?: Record<string, ModelSignalExpression>;
sources? ​
ts
optional sources?: Record<string, ModelSignalSource>;

Same-entity component reads. Scripts can publish custom components here.


NamespaceReservation ​

Properties ​

namespace ​
ts
namespace: string;
note? ​
ts
optional note?: string;
owner ​
ts
owner: string;

PackBlock ​

Properties ​

entry ​
ts
entry: string;

Zip member holding the block.

size ​
ts
size: number;

Uncompressed block size in bytes.


PackEntry ​

Properties ​

block? ​
ts
optional block?: string;

Solid block holding this file; absent when the file is its own zip member.

mediaType ​
ts
mediaType: string;
offset? ​
ts
optional offset?: number;

Byte offset inside the block (required with block).

sha256 ​
ts
sha256: string;
size ​
ts
size: number;

Uncompressed size in bytes.

variants? ​
ts
optional variants?: Record<string, string>;

Alternative encodings of the same content, e.g. { "ktx2": "<path>" }.


PackIndex ​

A directory listing of built packs, for hosts that publish several.

Properties ​

format ​
ts
format: "molen/pack-index@1";
packs ​
ts
packs: Record<string, PackIndexEntry>;

PackIndexEntry ​

Properties ​

contentHash ​
ts
contentHash: string;
file ​
ts
file: string;

Pack file, relative to the index.

size ​
ts
size: number;

File size in bytes.

version ​
ts
version: string;

PackManifest ​

The manifest inside a built pack.

Properties ​

blocks ​
ts
blocks: Record<string, PackBlock>;
contentHash ​
ts
contentHash: string;

sha256 over every logical file (path and content), independent of the zip layout.

entries ​
ts
entries: Record<string, PackEntry>;
format ​
ts
format: "molen/pack@1";
id ​
ts
id: string;
ids ​
ts
ids: Record<string, string>;

Asset id to the entry path of its runtime file.

license? ​
ts
optional license?: string;

SPDX expression for the pack's content.

notice? ​
ts
optional notice?: string;

Path of the entry that carries the pack's attribution notice.

provides ​
ts
provides: Record<string, string[]>;

Role (e.g. types, stylepack, stars) to the entry paths that provide it.

title? ​
ts
optional title?: string;
version ​
ts
version: string;

PackSourceConfig ​

Build configuration read from molen-pack.source.json in a pack's source directory.

Properties ​

exclude ​
ts
exclude: string[];
format ​
ts
format: "molen/pack-source@1";
id ​
ts
id: string;
ids ​
ts
ids: Record<string, string>;
include ​
ts
include: string[];

Globs (*, **, ?) of files to include, relative to the source directory.

independent? ​
ts
optional independent?: string[];

Files or directory prefixes (ending /) excluded from solid blocks.

license? ​
ts
optional license?: string;
notice? ​
ts
optional notice?: string;
provides ​
ts
provides: Record<string, string | string[]>;
solid ​
ts
solid: boolean;

Group small text files into compressed solid blocks (default true).

title? ​
ts
optional title?: string;
version ​
ts
version: string;

Prefab ​

Properties ​

components ​
ts
components: ComponentMap;
extends? ​
ts
optional extends?: string;

Name of a prefab in the same manifest to inherit components from (deep-merged).

format? ​
ts
optional format?: "molen/prefab@1";
type? ​
ts
optional type?: string;

Project-registry type this prefab specializes (its defaults merge in below extends).


ProjectManifest ​

Properties ​

assets ​
ts
assets: Record<string, string>;

Asset id -> project-relative path to its molen asset sidecar.

codegen ​
ts
codegen: object;
out ​
ts
out: string;
components ​
ts
components: Record<string, CustomComponentDecl>;

Custom component vocabulary shared by every scene in the project.

defaultScene? ​
ts
optional defaultScene?: string;
engine? ​
ts
optional engine?: string;

Engine version this project targets (informational).

format ​
ts
format: "molen/project@1";
name ​
ts
name: string;
packs ​
ts
packs: ProjectPackRef[];

Content packs to load, in order; a later pack wins on duplicate ids.

reservations ​
ts
reservations: NamespaceReservation[];

Namespace ownership for type + asset ids (multi-agent vocabulary partitioning).

scenes ​
ts
scenes: Record<string, string>;

Scene name -> project-relative scene file path.

setup? ​
ts
optional setup?: string;

Default setup/Experience module for sim/shot (project-relative).

types ​
ts
types: string[];

Project-relative paths to molen/types@1 documents.


ProjectPackRef ​

A content pack a project loads (see molen/pack@1).

Properties ​

contentHash? ​
ts
optional contentHash?: string;

Expected pack contentHash; loading fails when the pack's differs.

id ​
ts
id: string;
source ​
ts
source: string;

Project-relative pack file or source directory, or an http(s) URL.


RailVehicleSpec ​

Running gear of a track-guided vehicle. engineForce is its starting tractive effort, held up to power / speed; brakeDeceleration its full-service brake; rollingResistance and aerodynamicResistance the Davis terms (N per kg, and per kg per (m/s)²).

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

couplerLength? ​
ts
optional couplerLength?: number;

Length over the coupler pulling faces, meters (spacing in a consist); default length.

gauge? ​
ts
optional gauge?: number;

Track gauge between rail heads, meters; default 1.435.

power? ​
ts
optional power?: number;

Power at the rail in watts; 0 or absent is an unpowered car that only brakes.

profile? ​
ts
optional profile?: RailVehicleProfile;

Silhouette of the low-detail stand-in drawn at a distance; default box.

truckCenters ​
ts
truckCenters: number;

Distance between the two truck (bogie) pivots, meters.


ReadyMessage ​

Properties ​

tick ​
ts
tick: number;
tickRate ​
ts
tickRate: number;
type ​
ts
type: "ready";

RegisterComponentOptions ​

Properties ​

override? ​
ts
optional override?: boolean;

Replace an existing registration instead of throwing on a duplicate name.


RenderableKindMeta ​

Properties ​

description ​
ts
description: string;

What the kind renders (e.g. "an imported project asset"); shown in the kind field docs.

fields? ​
ts
optional fields?: Record<string, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>;

Extra renderable fields this kind reads, e.g. figures' lod. renderable is strict, so a capability that reads a field nobody declared would have its own documents rejected as typos. Declare it here and it joins the schema, the emitted JSON Schema and the docs. Each field is made optional (one flat renderable shape serves every kind) and may not shadow a core field.

owner? ​
ts
optional owner?: string;

Owning layer (the capability's client half), for docs grouping.


ReplayFixture ​

Properties ​

commands ​
ts
commands: Command[];
content? ​
ts
optional content?: ContentIdentity;

The content the replay was recorded with; replaying against different content fails.

engine ​
ts
engine: string;
expected? ​
ts
optional expected?: object;
eventCount? ​
ts
optional eventCount?: number;
stateHash ​
ts
stateHash: string;
tickHashes? ​
ts
optional tickHashes?: string[];
format ​
ts
format: "molen/replay@1";
initialKeyframe? ​
ts
optional initialKeyframe?: Keyframe;
scene? ​
ts
optional scene?: string;
seed? ​
ts
optional seed?: string | number;
ticks ​
ts
ticks: number;

ResolvedEntityType ​

Properties ​

components ​
ts
components: ComponentMap;
scripts ​
ts
scripts: ScriptRef[];

Ancestor-first behavior scripts, already source-inlined by the host loader.


RngState ​

Properties ​

algo ​
ts
algo: "sfc32";
state ​
ts
state: [number, number, number, number];

RunnerSpec ​

Runners in place of tires: skis, a snowboard, a sled, or a snowmobile's skis and track. On the weather's lying snow the vehicle slides with little friction, its edges or paddles hold the full grip, and it floats over any depth; off the snow it scrapes to a stop. Gravity along a slope moves it, and at rest only a brake or a slope too gentle to beat the friction holds it.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

bareDrag? ​
ts
optional bareDrag?: number;

Resistance in m/s² off the snow, where runners scrape bare ground; default 3.

flat? ​
ts
optional flat?: boolean;

A cycle whose runners stay flat on the snow in a turn (a pair of skis side by side) rather than banking as one plank (a snowboard). The lean into the turn stays in vehicleState.bodyRoll, where the rider's pose reads it. Default false.

friction ​
ts
friction: number;

Sliding friction coefficient on snow: it resists as friction × g. About 0.05 for waxed skis, 0.12 for a snowmobile's track.

pushSpeed? ​
ts
optional pushSpeed?: number;

Fastest the rider's own pushing (poling, skating) drives it, in m/s; gravity may take it on to maxSpeed. Absent, engineForce works up to maxSpeed, as an engine does.


SceneAmbient ​

Ambient life (NPC traffic) settings; consumed by @bendyline/molen-ambient.

Properties ​

classes? ​
ts
optional classes?: SceneAmbientKind[];

Which NPC classes run (default ['car']).

density? ​
ts
optional density?: Partial<Record<SceneAmbientKind, number>>;

Target agents per kilometre of lane near the observer, per class.

despawnRadius? ​
ts
optional despawnRadius?: number;

Distance in metres beyond which cars are removed.

drivingSide? ​
ts
optional drivingSide?: "right" | "left";
network? ​
ts
optional network?: string | JsonObject;

Scene-relative path to a molen/transport-network@1 document, or the document inline.

observer? ​
ts
optional observer?: string;

Entity whose position drives the spawn ring.

radius? ​
ts
optional radius?: number;

Outer spawn radius in metres for cars.

seedSalt? ​
ts
optional seedSalt?: string;
templates? ​
ts
optional templates?: Partial<Record<SceneAmbientKind, string>>;

Prefab name per class whose components every spawned agent receives.


SceneCommandDef ​

A command type the scene accepts; scripts attach handlers with molen.onCommand.

Properties ​

doc? ​
ts
optional doc?: string;
payload? ​
ts
optional payload?: JsonObject;

JSON Schema for the payload (see schema/src/commands.ts for the subset); omitted = any.


SceneEntity ​

Properties ​

components? ​
ts
optional components?: ComponentMap;

Components layered over the type/prefab base (a partial when a base is present).

id? ​
ts
optional id?: string;

Authored id; must not match /^e\d+$/, be all digits, or start with "$" (reserved).

prefab? ​
ts
optional prefab?: string;
type? ​
ts
optional type?: string;

Project-registry type to instantiate (lowest layer of the component stack).


SceneInput ​

Serializable, complete set of physical bindings for one use case.

Extends ​

Properties ​

axes? ​
ts
optional axes?: GamepadAxisBinding[];
Inherited from ​

InputProfile.axes

bindings ​
ts
bindings: Record<string, string>;

Device code (KeyW, Mouse0, …) -> action name; the client InputMap's exact shape.

Overrides ​

InputProfile.bindings

buttons? ​
ts
optional buttons?: GamepadButtonBinding[];
Inherited from ​

InputProfile.buttons

emit ​
ts
emit: InputEmitRule[];

Declarative action -> command emission rules the client runs; the kernel adjudicates.

profile? ​
ts
optional profile?: string;

Initial profile name; hosts switch at runtime with InputMap.setProfile().

profiles? ​
ts
optional profiles?: Record<string, InputProfile>;

Named complete binding sets. The root bindings are used when profile is absent.


SceneManifest ​

Properties ​

ambient? ​
ts
optional ambient?: SceneAmbient;
camera? ​
ts
optional camera?: SceneCamera;
commands ​
ts
commands: Record<string, SceneCommandDef>;

Command types this scene accepts, with optional payload schemas.

components ​
ts
components: Record<string, CustomComponentDecl>;

Custom component vocabulary this scene introduces.

entities ​
ts
entities: SceneEntity[];
format ​
ts
format: "molen/scene@3";
input? ​
ts
optional input?: SceneInput;
keyframeInterval ​
ts
keyframeInterval: number;
lateCommands ​
ts
lateCommands: "rewrite" | "reject";
name ​
ts
name: string;
physics? ​
ts
optional physics?: ScenePhysics;
prefabs ​
ts
prefabs: Record<string, Prefab>;
scripts ​
ts
scripts: ScriptRef[];
seed ​
ts
seed: string | number;
terrain? ​
ts
optional terrain?: SceneTerrainRef;
tickRate ​
ts
tickRate: number;

Fixed timestep rate in Hz; immutable for the world's lifetime.


ScenePhysics ​

Properties ​

character? ​
ts
optional character?: boolean;

Install the kernel character controller (character + moveIntent). Not with rapier.

engine ​
ts
engine: "none" | "kinematics" | "platformer" | "rapier";

kinematics and platformer are cross-platform deterministic; rapier is same-platform.

gravity? ​
ts
optional gravity?: Vec3;
ground? ​
ts
optional ground?: "flat" | "terrain";

Ground for kinematic bodies: flat y=0 (default) or the scene's terrain heightfield.


SceneResolveOptions ​

Properties ​

types? ​
ts
optional types?: ResolvedTypes;

Flattened registry types; required when the scene references type ids.


SceneTerrainRef ​

Properties ​

descriptor ​
ts
descriptor: string;

Scene-file-relative path to a molen/terrain@2 descriptor (v1 auto-upgrades).

heightmap? ​
ts
optional heightmap?: string;

Scene-file-relative path to a 16-bit grayscale heightmap PNG.


SchemaEntry ​

Properties ​

kind ​
ts
kind: string;
legacy ​
ts
legacy: LegacySchemaVersion[];

Older accepted versions, newest first; validate() auto-upgrades them with a notice.

meta ​
ts
meta: SchemaMeta;
zod ​
ts
zod: ZodType;

SchemaKindMap ​

Properties ​

assert ​
ts
assert: AssertionDoc;
asset ​
ts
asset: AssetSidecar;
command ​
ts
command: Command;
delta ​
ts
delta: Delta;
keyframe ​
ts
keyframe: Keyframe;
pack ​
ts
pack: PackManifest;
pack-index ​
ts
pack-index: PackIndex;
pack-source ​
ts
pack-source: PackSourceConfig;
prefab ​
ts
prefab: Prefab;
project ​
ts
project: ProjectManifest;
replay ​
ts
replay: ReplayFixture;
scene ​
ts
scene: SceneManifest;
soundbank ​
ts
soundbank: SoundbankDoc;
source-bundle ​
ts
source-bundle: SourceBundle;
types ​
ts
types: TypesDoc;

SchemaMeta ​

Properties ​

description ​
ts
description: string;
docsRef? ​
ts
optional docsRef?: string;
examples ​
ts
examples: JsonValue[];

At least one valid example document; feeds error hints, docs, and tests.

id ​
ts
id: string;

Format envelope id, e.g. "molen/scene@1".

title ​
ts
title: string;
validate? ​
ts
optional validate?: (data) => ValidationIssue[];

Optional post-parse, cross-field validation that Zod (and thus the emitted JSON Schema) can't express — e.g. material-graph cycles, dangling node refs, pixel-grid row lengths. Receives the parsed (defaults-applied) value; returns pinpoint issues (empty = valid). Runs only on Zod-valid documents, so it never double-reports structural errors.

Parameters ​
data ​

unknown

Returns ​

ValidationIssue[]


SchemaSummary ​

Properties ​

description ​
ts
description: string;
id ​
ts
id: string;
kind ​
ts
kind: string;
title ​
ts
title: string;

ScriptRef ​

Properties ​

checkpoint? ​
ts
optional checkpoint?: "state";

All durable state is in molen.state/components/plugins, never mutable closures.

code? ​
ts
optional code?: string;

Inline JavaScript text (exactly one of code | path).

config ​
ts
config: JsonObject;
id ​
ts
id: string;
path? ​
ts
optional path?: string;

Scene-file-relative path to a JS text file; tooling resolves it into code pre-build.


SelectAssertion ​

Properties ​

op ​
ts
op: SelectOp;
select ​
ts
select: string;

Selector DSL: "#id", "tag:x", "has:comp", value paths like ".health.hp".

tol? ​
ts
optional tol?: number;
value? ​
ts
optional value?: JsonValue;

SkyAppearance ​

Extended by ​

Properties ​

dome? ​
ts
optional dome?: object;
brightness? ​
ts
optional brightness?: number;
lighting? ​
ts
optional lighting?: object;
castShadow? ​
ts
optional castShadow?: boolean;
dayAmbient? ​
ts
optional dayAmbient?: number;
moonIntensity? ​
ts
optional moonIntensity?: number;
nightAmbient? ​
ts
optional nightAmbient?: number;
referenceElevation? ​
ts
optional referenceElevation?: number;
skyLightSaturation? ​
ts
optional skyLightSaturation?: number;
sunIntensity? ​
ts
optional sunIntensity?: number;
moon? ​
ts
optional moon?: object;
earthshine? ​
ts
optional earthshine?: number;
size? ​
ts
optional size?: number;
visible? ​
ts
optional visible?: boolean;
palette? ​
ts
optional palette?: SkyPalette;
stars? ​
ts
optional stars?: object;
enabled? ​
ts
optional enabled?: boolean;
intensity? ​
ts
optional intensity?: number;
magnitudeLimit? ​
ts
optional magnitudeLimit?: number;
size? ​
ts
optional size?: number;
sun? ​
ts
optional sun?: object;
size? ​
ts
optional size?: number;
visible? ​
ts
optional visible?: boolean;

SkyBodyData ​

Properties ​

angularDiameterDeg? ​
ts
optional angularDiameterDeg?: number;
direction ​
ts
direction: [number, number, number];

SkyPalette ​

Properties ​

dayHorizon? ​
ts
optional dayHorizon?: string;
dayZenith? ​
ts
optional dayZenith?: string;
ground? ​
ts
optional ground?: string;
moon? ​
ts
optional moon?: string;
nightHorizon? ​
ts
optional nightHorizon?: string;
nightZenith? ​
ts
optional nightZenith?: string;
sun? ​
ts
optional sun?: string;
twilight? ​
ts
optional twilight?: string;

SkyTime ​

Properties ​

epochMs ​
ts
epochMs: number;

UTC Unix milliseconds at simulation second zero.

scale? ​
ts
optional scale?: number;

Sky seconds per simulation second, default 1.


SnowCoverSample ​

How much of the ground snow covers at a height, and how deep it lies there.

Properties ​

coverage ​
ts
coverage: number;

Share of the ground covered, 0 (bare) to 1.

depth ​
ts
depth: number;

Depth in meters; 0 where the ground is bare.


SourceBundle ​

Portable authoring-time contents for one logical thing. Runtime outputs live elsewhere.

Properties ​

files ​
ts
files: object;
definitions ​
ts
definitions: string[];
documents ​
ts
documents: string[];
generators ​
ts
generators: SourceBundleNamedFile[];
models ​
ts
models: SourceBundleModel[];
scripts ​
ts
scripts: SourceBundleNamedFile[];
sounds ​
ts
sounds: SourceBundleNamedFile[];
textures ​
ts
textures: SourceBundleNamedFile[];
format ​
ts
format: "molen/source-bundle@1";
id ​
ts
id: string;
kind ​
ts
kind: string;
order? ​
ts
optional order?: number;
title ​
ts
title: string;

SourceBundleModel ​

Properties ​

assetId? ​
ts
optional assetId?: string;
output? ​
ts
optional output?: string;
path ​
ts
path: string;
pipeline? ​
ts
optional pipeline?: "copy" | "import";
sha256? ​
ts
optional sha256?: string;

SourceBundleNamedFile ​

Properties ​

id ​
ts
id: string;
path ​
ts
path: string;

TypeIndex ​

Properties ​

index ​
ts
index: Map<string, TypeIndexEntry>;
issues ​
ts
issues: ValidationIssue[];

TypeIndexEntry ​

Properties ​

def ​
ts
def: EntityTypeDef;
id ​
ts
id: string;
source? ​
ts
optional source?: string;

Which types document declared it (for error messages).


TypesDoc ​

Properties ​

doc? ​
ts
optional doc?: string;
format ​
ts
format: "molen/types@1";
namespace ​
ts
namespace: string;

Dotted namespace every type id in this file must live under.

owner? ​
ts
optional owner?: string;

Matched against project reservations by molen types check.

types ​
ts
types: Record<string, EntityTypeDef>;

ValidateOptions ​

Extends ​

Properties ​

allowUnknownComponents? ​
ts
optional allowUnknownComponents?: boolean;

When true, unknown component names are never flagged (not even near-typos).

Inherited from ​

ComponentValidateOptions.allowUnknownComponents

label? ​
ts
optional label?: string;

Label used in the formatted error header, e.g. 'scene "arena"'.

partial? ​
ts
optional partial?: boolean;

The data is a partial layer (entity overrides, or components stacked on a prefab/type base): keep the unknown-name did-you-mean but skip shape validation — only the RESOLVED component map can be checked for completeness.

Inherited from ​

ComponentValidateOptions.partial

registry? ​
ts
optional registry?: ComponentRegistry;
Inherited from ​

ComponentValidateOptions.registry

types? ​
ts
optional types?: ResolvedTypes;

Supply project types to validate final scene entity and prefab merges.


ValidationFailure ​

Properties ​

formatted ​
ts
formatted: string;
issues ​
ts
issues: ValidationIssue[];
ok ​
ts
ok: false;

ValidationIssue ​

Properties ​

code ​
ts
code: string;

Stable machine code, e.g. "invalid_type", "unrecognized_keys".

docsRef? ​
ts
optional docsRef?: string;
expected? ​
ts
optional expected?: string;

What valid looks like.

hint? ​
ts
optional hint?: string;

Did-you-mean, example value, or fix suggestion.

message ​
ts
message: string;

What is wrong.

path ​
ts
path: string;

JSON Pointer to the offending location, e.g. "/components/transform/pos".

received? ​
ts
optional received?: string;

What was found (truncated repr).

severity? ​
ts
optional severity?: "error" | "notice";

Absent = error (blocks). notice = advisory only; the document is still accepted.


ValidationSuccess ​

Type Parameters ​

T ​

T

Properties ​

notices? ​
ts
optional notices?: ValidationIssue[];

Non-fatal advisories (e.g. code "deprecated_format" after a legacy auto-upgrade).

ok ​
ts
ok: true;
value ​
ts
value: T;

VehicleCollisionPart ​

Authored rigid sections for road-vehicle impacts. The chassis remains the support body.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

breakSpeed ​
ts
breakSpeed: number;
center ​
ts
center: [number, number, number];
hinge? ​
ts
optional hinge?: object;

Optional articulated panel hinge, driven by a named actuator.

actuator ​
ts
actuator: string;
angle ​
ts
angle: number;
axis ​
ts
axis: [number, number, number];
pivot ​
ts
pivot: [number, number, number];
id ​
ts
id: string;
massFraction ​
ts
massFraction: number;
nodes ​
ts
nodes: string[];
probes ​
ts
probes: [number, number, number][];
radius ​
ts
radius: number;
role ​
ts
role: "engine" | "frontWheel" | "rearWheel" | "panel";

VehicleDamageState ​

Persistent section integrity and independently moving debris, shared with aircraft.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

damage? ​
ts
optional damage?: Record<string, AircraftPartDamage>;
debris? ​
ts
optional debris?: AircraftDebris[];

VehicleData ​

Complete external configuration consumed by the generic vehicle solver and client.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

color ​
ts
color: string;
kind ​
ts
kind: string;
spec ​
ts
spec: VehicleSpec;
visual ​
ts
visual: VehicleVisualSpec;

VehicleInteriorSpec ​

Cabin geometry in the main GLB, shared by every camera view.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

bindings ​
ts
bindings: ModelSignalBinding[];
Inherited from ​

ModelSignalSpec.bindings

derived? ​
ts
optional derived?: Record<string, ModelSignalExpression>;
Inherited from ​

ModelSignalSpec.derived

nodes ​
ts
nodes: string[];

Informational: never hidden on boarding or in chase view.

sources? ​
ts
optional sources?: Record<string, ModelSignalSource>;

Same-entity component reads. Scripts can publish custom components here.

Inherited from ​

ModelSignalSpec.sources


VehiclePlacement ​

Serializable spawn record, independent of terrain tile identity and render resources.

Properties ​

color ​
ts
color: string;
id ​
ts
id: string;
kind ​
ts
kind: string;

External entity/type id, for example molen.entities.vehicle.sedan.

pitch? ​
ts
optional pitch?: number;
position ​
ts
position: [number, number, number];
roll? ​
ts
optional roll?: number;
spec ​
ts
spec: VehicleSpec;

Resolved external physics/dimension data used by terrain-owned low-detail rendering.

yaw ​
ts
yaw: number;

VehiclePowertrainSpec ​

Engine, gearbox and driveline. Wheel force is engine torque through the selected gear, so a car pulls hardest in first and runs out of power, not into a wall, at speed. Without a powertrain a vehicle keeps the constant engineForce up to maxSpeed.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

continuous? ​
ts
optional continuous?: boolean;

A continuously variable transmission ranging between the first and last gears ratios.

curve? ​
ts
optional curve?: "gasoline" | "turbo" | "diesel" | "electric";

Shape of the torque curve; default gasoline (torque peaks at half the peak-power speed). turbo and diesel hold a torque plateau low down; electric holds its peak torque from rest up to peakPowerRpm, then constant power.

efficiency? ​
ts
optional efficiency?: number;

Share of engine torque that reaches the wheels; default 0.9.

engineBraking? ​
ts
optional engineBraking?: number;

Engine braking off the throttle (regeneration for an electric motor), as a share of the torque at peak power; default 0.2.

gears ​
ts
gears: number[];

Overall ratios (gearbox × final drive: engine revs per wheel rev), lowest gear first.

idle? ​
ts
optional idle?: number;

Idle speed, rev/min; default 800, or 0 for an electric motor.

inertia? ​
ts
optional inertia?: number;

Rotating inertia of the engine, flywheel and gearbox input in kg m², which the car has to spin up as it accelerates (most in the low gears); default 0.1 + power / 1 MW, or 0.06 for an electric motor.

peakPowerRpm ​
ts
peakPowerRpm: number;

Engine speed at peak power, rev/min.

power ​
ts
power: number;

Peak power at the engine or motor shaft, in watts.

redline? ​
ts
optional redline?: number;

Rev limit, rev/min; default 1.1 × peakPowerRpm.

response? ​
ts
optional response?: number;

How fast delivered torque follows the pedal, 1/s; default 8 (turbo and diesel 4, electric 20).

reverse? ​
ts
optional reverse?: number;

Overall reverse ratio; default the first gear.

shiftTime? ​
ts
optional shiftTime?: number;

Seconds of reduced drive during a gear change; default 0.3.


VehicleSpec ​

Data-driven tuning consumed by the generic wheeled-vehicle solver.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

actuators? ​
ts
optional actuators?: ActuatorSpecs;
aerodynamicLift? ​
ts
optional aerodynamicLift?: number;

Aerodynamic lift as an acceleration per (m/s)² of airspeed, in 1/m; negative is downforce. Default 0.

aerodynamicResistance ​
ts
aerodynamicResistance: number;
bodyStyle? ​
ts
optional bodyStyle?: VehicleBodyStyle;

Generic body style, so a host can classify or relabel the vehicle without its real name.

brakeBias? ​
ts
optional brakeBias?: number;

Share of braking on the front wheels; default 0.65.

brakeDeceleration ​
ts
brakeDeceleration: number;
centerOfMass ​
ts
centerOfMass: [number, number, number];
collisionParts? ​
ts
optional collisionParts?: VehicleCollisionPart[];
corneringStiffness? ​
ts
optional corneringStiffness?: number;

Tire cornering stiffness: side force per unit load per radian of slip before it saturates; default 18.

cycle? ​
ts
optional cycle?: CycleSpec;

Two contact patches on the centreline; balances upright at rest and leans into turns.

drive? ​
ts
optional drive?: "front" | "rear" | "all";

Driven wheels; default front.

driverEye ​
ts
driverEye: [number, number, number];
engineForce ​
ts
engineForce: number;
genericLabel? ​
ts
optional genericLabel?: string;

Name-free display label such as 'Full-size pickup', for hosts that must not show the real name.

grip ​
ts
grip: number;

Peak tire friction on dry pavement as an acceleration in m/s² (grip / 9.81 is the friction coefficient).

handlebar? ​
ts
optional handlebar?: HandlebarSpec;

Handlebar steering on a vehicle that does not lean (a three-wheeler): the driver's hands and feet, with the seat as the pelvis anchor. Ignored when cycle is present.

headlamps? ​
ts
optional headlamps?: [number, number, number][];

Headlamp lens centres in model space, at most two. Hosts that light vehicles at night place their beams and lit lenses here; empty means no headlamps (a skateboard). Absent, they guess a pair from the body's width, height and length.

height ​
ts
height: number;
label ​
ts
label: string;
length ​
ts
length: number;
limitedSlip? ​
ts
optional limitedSlip?: number;

How far the driven axle's differential resists one-wheel spin, 0 (open, the unloaded inside wheel spins first) to 1 (locked); default 0.

looseSurfaceGrip? ​
ts
optional looseSurfaceGrip?: number;

Share 0–1 of the grip loose surfaces take away that the tires win back (off-road tread); default 0.

mass ​
ts
mass: number;
maxSlope ​
ts
maxSlope: number;
maxSpeed ​
ts
maxSpeed: number;
maxSteer ​
ts
maxSteer: number;

Maximum steering angle in radians; zero locks the wheels for straight-track vehicles.

maxStepHeight ​
ts
maxStepHeight: number;
pitchStiffness? ​
ts
optional pitchStiffness?: number;

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.

powertrain? ​
ts
optional powertrain?: VehiclePowertrainSpec;

Engine, gears and driveline; without one the constant engineForce drives the car.

rail? ​
ts
optional rail?: RailVehicleSpec;

Track-guided running gear: follows a host track guide instead of steering.

rearGrip? ​
ts
optional rearGrip?: number;

Rear tire grip in m/s² where it differs from the front's grip (wider rear tires); default grip.

reverseSpeed ​
ts
reverseSpeed: number;
rollBalance? ​
ts
optional rollBalance?: number;

Front axle's share of the roll stiffness, 0–1; default 0.6. The stiffer axle carries more of the cornering weight transfer and gives up grip first: more is understeer.

rollingResistance ​
ts
rollingResistance: number;
rollStiffness? ​
ts
optional rollStiffness?: number;

Body roll in radians per g of cornering; default 0.05.

runners? ​
ts
optional runners?: RunnerSpec;

Slides on snow instead of rolling on tires (skis, a board, a snowmobile).

stabilityControl? ​
ts
optional stabilityControl?: boolean;

Stability control: brakes one wheel to catch a slide; default true.

steeringFadeSpeed ​
ts
steeringFadeSpeed: number;
steeringRate ​
ts
steeringRate: number;
supportTolerance ​
ts
supportTolerance: number;
suspensionDamping? ​
ts
optional suspensionDamping?: number;

Suspension damping ratio; default 0.5.

suspensionFrequency? ​
ts
optional suspensionFrequency?: number;

Suspension natural frequency in Hz; default 1.5.

terrainAlignRate ​
ts
terrainAlignRate: number;
tireLoadSensitivity? ​
ts
optional tireLoadSensitivity?: number;

How much friction a tire loses as it is loaded: the share lost when its load doubles from a quarter of the weight; default 0.25. Makes the heavier and the stiffer-sprung axle slide first. 0 keeps grip proportional to load.

tractionControl? ​
ts
optional tractionControl?: boolean;

Traction control: holds wheelspin at the grip limit; default true.

wheelbase ​
ts
wheelbase: number;
wheelRadius ​
ts
wheelRadius: number;
wheelTrack ​
ts
wheelTrack: number;
width ​
ts
width: number;
yawInertia? ​
ts
optional yawInertia?: number;

Yaw moment of inertia in kg m²; defaults to mass * (length² + width²) / 12.


VehicleVisualSpec ​

Named-node bindings for a GLB-backed wheeled vehicle.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

animation? ​
ts
optional animation?: ModelSignalSpec;

Exterior moving parts posed from the same signals as the interior.

frontWheelNodes ​
ts
frontWheelNodes: string[];

Wheel nodes turned by the steering; empty when animation bindings pose the steering.

interior? ​
ts
optional interior?: VehicleInteriorSpec;
paintMaterial ​
ts
paintMaterial: string;
steeringWheelNode? ​
ts
optional steeringWheelNode?: string;

Legacy explicit steering binding. Prefer interior.bindings for new models.

wheelNodes ​
ts
wheelNodes: string[];

WaterSettings ​

Authored water conditions, in metric world coordinates and simulation seconds.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

current? ​
ts
optional current?: [number, number];

Current velocity [east, south] in m/s.

waves? ​
ts
optional waves?: WaterWave[];

WaterWave ​

One travelling swell. Direction is radians about +Y, zero towards +Z.

Extends ​

Indexable ​

ts
[key: string]: JsonValue | undefined

Properties ​

amplitude ​
ts
amplitude: number;
direction ​
ts
direction: number;
speed ​
ts
speed: number;
wavelength ​
ts
wavelength: number;

Type Aliases ​

ActuatorInputs ​

ts
type ActuatorInputs = Record<string, number | boolean>;

ActuatorPositions ​

ts
type ActuatorPositions = Record<string, number>;

ActuatorSpecs ​

ts
type ActuatorSpecs = Record<string, ActuatorSpec>;

AircraftKind ​

ts
type AircraftKind = string;

Stable external entity/type id for an aircraft.


Assertion ​

ts
type Assertion = 
  | SelectAssertion
  | EventAssertion;

AudioAmbienceLayer ​

ts
type AudioAmbienceLayer = object;

Properties ​

fadeS? ​
ts
optional fadeS?: number;
gain? ​
ts
optional gain?: number;
gainFrom? ​
ts
optional gainFrom?: AudioSignalDrive;
pitchFrom? ​
ts
optional pitchFrom?: AudioSignalDrive;
sound ​
ts
sound: string;
when? ​
ts
optional when?: AudioWhen;

AudioCondition ​

ts
type AudioCondition = 
  | AudioScalar
  | AudioScalar[]
  | {
  max?: number;
  min?: number;
}
  | {
  exists: boolean;
};

AudioEnvironmentData ​

ts
type AudioEnvironmentData = object;

Properties ​

ambience? ​
ts
optional ambience?: AudioAmbienceLayer[];
buses? ​
ts
optional buses?: Record<string, number>;
events? ​
ts
optional events?: Record<string, AudioEventRule>;
footsteps? ​
ts
optional footsteps?: AudioFootsteps;
listenerEntity? ​
ts
optional listenerEntity?: string;
maxVoices? ​
ts
optional maxVoices?: number;
music? ​
ts
optional music?: AudioMusicSpec;

AudioEventRule ​

ts
type AudioEventRule = object;

Properties ​

at? ​
ts
optional at?: string;
bus? ​
ts
optional bus?: string;
gain? ​
ts
optional gain?: number;
pitch? ​
ts
optional pitch?: number;
sound ​
ts
sound: string;

AudioFootsteps ​

ts
type AudioFootsteps = object;

Properties ​

gain? ​
ts
optional gain?: number;
sound ​
ts
sound: string;
strideM? ​
ts
optional strideM?: number;
surfaces? ​
ts
optional surfaces?: Record<string, string>;
when? ​
ts
optional when?: AudioWhen;

AudioMusicSpec ​

ts
type AudioMusicSpec = object;

Properties ​

crossfadeS? ​
ts
optional crossfadeS?: number;
gain? ​
ts
optional gain?: number;
mode? ​
ts
optional mode?: "sequence" | "shuffle";
playlist ​
ts
playlist: string[];
when? ​
ts
optional when?: AudioWhen;

AudioScalar ​

ts
type AudioScalar = string | number | boolean;

AudioSignalBinding ​

ts
type AudioSignalBinding = object;

Properties ​

curve ​
ts
curve: [number, number][];
signal ​
ts
signal: string;
smoothS? ​
ts
optional smoothS?: number;

AudioSignalDrive ​

ts
type AudioSignalDrive = 
  | AudioSignalBinding
  | AudioSignalBinding[];

One signal binding, or several whose outputs multiply (fade with height AND distance).


AudioSourceData ​

ts
type AudioSourceData = object;

Properties ​

autoplay? ​
ts
optional autoplay?: boolean;
bus? ​
ts
optional bus?: string;
gain? ​
ts
optional gain?: number;
gainFrom? ​
ts
optional gainFrom?: AudioSignalDrive;
loop? ​
ts
optional loop?: boolean;
pitch? ​
ts
optional pitch?: number;
pitchFrom? ​
ts
optional pitchFrom?: AudioSignalDrive;
sound ​
ts
sound: string;
spatial? ​
ts
optional spatial?: SoundSpatial | false;
startTick? ​
ts
optional startTick?: number;
triggerFrom? ​
ts
optional triggerFrom?: AudioTrigger;
when? ​
ts
optional when?: AudioWhen;

AudioTrigger ​

ts
type AudioTrigger = object;

Properties ​

every? ​
ts
optional every?: number;
onChange? ​
ts
optional onChange?: boolean;
signal ​
ts
signal: string;
sound? ​
ts
optional sound?: string;

AudioWhen ​

ts
type AudioWhen = Record<string, AudioCondition>;

AudioZoneData ​

ts
type AudioZoneData = object;

Properties ​

bus? ​
ts
optional bus?: string;
fade? ​
ts
optional fade?: number;
gain? ​
ts
optional gain?: number;
shape ​
ts
shape: 
  | {
  kind: "sphere";
  radius: number;
}
  | {
  halfExtents: [number, number, number];
  kind: "box";
};
sound ​
ts
sound: string;
when? ​
ts
optional when?: AudioWhen;

CloudType ​

ts
type CloudType = "cumulus" | "stratocumulus" | "stratus" | "cumulonimbus";

Cloud genera the renderer draws: separate fair-weather heaps, a lumpy closed layer, a flat grey sheet, and towering storm cells with anvil tops.


ComponentMap ​

ts
type ComponentMap = Record<string, JsonObject>;

Component name -> pure-JSON component data.


ComponentRegistry ​

ts
type ComponentRegistry = ReadonlyMap<string, ComponentEntry>;

ContentIdentity ​

ts
type ContentIdentity = Record<string, ContentIdentityEntry>;

Which content a world was built from, by domain. Recorded next to the state hash (never in it), so a keyframe or replay can refuse to run against different content with a named error.


ControlAction ​

ts
type ControlAction = 
  | {
  action: "pause";
}
  | {
  action: "resume";
}
  | {
  action: "set-active";
  active: boolean;
}
  | {
  action: "step";
  ticks?: number;
}
  | {
  action: "request-keyframe";
}
  | {
  action: "set-rate";
  hz: number;
};

CycleStance ​

ts
type CycleStance = "seated" | "standing" | "sideways";

How a cycle's rider stands: on a saddle (seated, the default), upright on a deck facing the bars (standing), or across a board with the left foot forward (sideways). A standing or sideways rider's seat is where an adult's hips go; the pose lowers or raises the hips to the body's own leg length, keeping the hands and feet on their targets.


EntityId ​

ts
type EntityId = string;

Runtime ids are "e" + sequence; authored ids are any other non-empty string.


FlightModel ​

ts
type FlightModel = "airplane" | "helicopter";

GlassMaterial ​

ts
type GlassMaterial = "laminated" | "tempered" | "annealed";

Fracture and retention are independent: laminated fragments can remain in the opening.


InputEmitRule ​

ts
type InputEmitRule = 
  | {
  action: string;
  command: string;
  kind: "press";
  payload: JsonObject;
}
  | {
  action: string;
  command: string;
  kind: "release";
  payload: JsonObject;
}
  | {
  action: string;
  command: string;
  field: string;
  kind: "axis";
  negative?: string;
}
  | {
  command: string;
  field: string;
  kind: "axis2d";
  xNeg: string;
  xPos: string;
  yNeg: string;
  yPos: string;
};

JsonPrimitive ​

ts
type JsonPrimitive = string | number | boolean | null;

JsonValue ​

ts
type JsonValue = 
  | JsonPrimitive
  | JsonValue[]
  | JsonObject;

KernelInbound ​

ts
type KernelInbound = CommandMessage | ControlMessage;

Messages the client sends to the kernel.


KernelOutbound ​

ts
type KernelOutbound = 
  | ReadyMessage
  | KeyframeMessage
  | DeltaMessage
  | DiagMessage;

Messages the kernel sends to the client.


ModelSignalOperand ​

ts
type ModelSignalOperand = number | string;

A number is a literal; a string names a source or another derived signal.


ModelSignalOperator ​

ts
type ModelSignalOperator = 
  | "add"
  | "subtract"
  | "multiply"
  | "divide"
  | "min"
  | "max"
  | "clamp"
  | "abs"
  | "sqrt"
  | "floor"
  | "modulo"
  | "sin"
  | "cos"
  | "atan2"
  | "less"
  | "greater"
  | "equal"
  | "and"
  | "or"
  | "not"
  | "if"
  | "coalesce";

PayloadCheck ​

ts
type PayloadCheck = 
  | {
  ok: true;
}
  | {
  message: string;
  ok: false;
};

Result of a payload validator: ok, or a formatted, agent-facing reason.


Quat ​

ts
type Quat = [number, number, number, number];

RailVehicleProfile ​

ts
type RailVehicleProfile = 
  | "box"
  | "hopper"
  | "tank"
  | "gondola"
  | "flat"
  | "well"
  | "autorack"
  | "locomotive"
  | "coach"
  | "railcar";

Distant silhouettes of rail vehicles, by kind of car.


ResolvedSnowCover ​

ts
type ResolvedSnowCover = Required<SnowCoverData>;

ResolvedTypes ​

ts
type ResolvedTypes = ReadonlyMap<string, ResolvedEntityType>;

Pre-flattened project type registry.


ResolvedWeather ​

ts
type ResolvedWeather = object;

Properties ​

atmosphere ​
ts
atmosphere: Required<NonNullable<WeatherData["atmosphere"]>>;
clouds ​
ts
clouds: Required<NonNullable<WeatherData["clouds"]>>;
precipitation ​
ts
precipitation: Required<NonNullable<WeatherData["precipitation"]>>;
seed ​
ts
seed: number;
snowCover? ​
ts
optional snowCover?: ResolvedSnowCover;
visibility ​
ts
visibility: number;
wind ​
ts
wind: Required<NonNullable<WeatherData["wind"]>>;

SceneAmbientKind ​

ts
type SceneAmbientKind = "car" | "pedestrian" | "train" | "aircraft" | "boat";

An NPC class the ambient-life capability simulates.


SceneCamera ​

ts
type SceneCamera = 
  | {
  entity: EntityId;
  fov?: number;
  lookOffset: Vec3;
  mode: "follow";
  offset: Vec3;
  space?: "world" | "local";
}
  | {
  fov?: number;
  lookAt?: Vec3;
  mode: "fixed";
  position: Vec3;
}
  | {
  boost: number;
  fov?: number;
  lookAt?: Vec3;
  mode: "free-fly";
  moveSpeed: number;
  position: Vec3;
}
  | {
  cameraHeight?: number;
  center: [number, number];
  mode: "top-down-ortho";
  viewHeight: number;
};

SchemaKind ​

ts
type SchemaKind = keyof SchemaKindMap;

SelectOp ​

ts
type SelectOp = 
  | "eq"
  | "approx"
  | "gt"
  | "gte"
  | "lt"
  | "lte"
  | "count"
  | "exists"
  | "all_eq"
  | "all_approx"
  | "all_gt"
  | "all_gte"
  | "all_lt"
  | "all_lte"
  | "any_eq"
  | "any_approx"
  | "any_gt"
  | "any_gte"
  | "any_lt"
  | "any_lte";

SkyData ​

ts
type SkyData = EarthSkyData | CustomSkyData;

SnowCoverData ​

ts
type SnowCoverData = NonNullable<WeatherData["snowCover"]>;

Snow lying on the ground above a snow line; see snowCoverAt.


SoundbankDoc ​

ts
type SoundbankDoc = object;

Properties ​

format ​
ts
format: "molen/soundbank@1";
id ​
ts
id: string;
license? ​
ts
optional license?: string;
sounds ​
ts
sounds: Record<string, SoundEntry>;
title? ​
ts
optional title?: string;

SoundEntry ​

ts
type SoundEntry = object;

Properties ​

bus? ​
ts
optional bus?: string;
clips ​
ts
clips: string[];
description? ​
ts
optional description?: string;
durationS? ​
ts
optional durationS?: number;
gain? ​
ts
optional gain?: number;
hash? ​
ts
optional hash?: string;
loop? ​
ts
optional loop?: boolean;
loopEnd? ​
ts
optional loopEnd?: number;
loopStart? ​
ts
optional loopStart?: number;
pitch? ​
ts
optional pitch?: [number, number];
source ​
ts
source: SoundSource;
spatial? ​
ts
optional spatial?: SoundSpatial | false;
tags? ​
ts
optional tags?: string[];

SoundSource ​

ts
type SoundSource = object;

Properties ​

author? ​
ts
optional author?: string;
generator? ​
ts
optional generator?: string;
license ​
ts
license: string;
notes? ​
ts
optional notes?: string;
prompt? ​
ts
optional prompt?: string;
site? ​
ts
optional site?: string;
title? ​
ts
optional title?: string;
url? ​
ts
optional url?: string;

SoundSpatial ​

ts
type SoundSpatial = object;

Properties ​

maxDistance? ​
ts
optional maxDistance?: number;
model? ​
ts
optional model?: "linear" | "inverse" | "exponential";
refDistance? ​
ts
optional refDistance?: number;
rolloff? ​
ts
optional rolloff?: number;

ValidationResult ​

ts
type ValidationResult<T> = 
  | ValidationSuccess<T>
  | ValidationFailure;

Type Parameters ​

T ​

T


Vec3 ​

ts
type Vec3 = [number, number, number];

VehicleBodyStyle ​

ts
type VehicleBodyStyle = 
  | "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";

Generic body styles, independent of any make or model name.


VehicleInteriorBinding ​

ts
type VehicleInteriorBinding = ModelSignalBinding;

VehicleKind ​

ts
type VehicleKind = string;

Stable external entity/type id for a wheeled vehicle.


WeatherData ​

ts
type WeatherData = object;

Independent atmospheric, cloud and precipitation parameters, in SI units.

Properties ​

atmosphere? ​
ts
optional atmosphere?: object;
gasConstant? ​
ts
optional gasConstant?: number;
model? ​
ts
optional model?: "standard" | "isothermal";
moistAir? ​
ts
optional moistAir?: boolean;
pressurePa? ​
ts
optional pressurePa?: number;
referenceAltitude? ​
ts
optional referenceAltitude?: number;
relativeHumidity? ​
ts
optional relativeHumidity?: number;
temperatureK? ​
ts
optional temperatureK?: number;
windVelocity? ​
ts
optional windVelocity?: [number, number, number];
clouds? ​
ts
optional clouds?: object;
baseAltitude? ​
ts
optional baseAltitude?: number;
cirrus? ​
ts
optional cirrus?: number;
cirrusAltitude? ​
ts
optional cirrusAltitude?: number;
coverage? ​
ts
optional coverage?: number;
density? ​
ts
optional density?: number;
scale? ​
ts
optional scale?: number;
thickness? ​
ts
optional thickness?: number;
type? ​
ts
optional type?: CloudType;
precipitation? ​
ts
optional precipitation?: object;
intensity? ​
ts
optional intensity?: number;
kind? ​
ts
optional kind?: "none" | "rain" | "snow";
seed? ​
ts
optional seed?: number;
snowCover? ​
ts
optional snowCover?: object;
depth? ​
ts
optional depth?: number;
depthGain? ​
ts
optional depthGain?: number;
level ​
ts
level: number;
maxDepth? ​
ts
optional maxDepth?: number;
transition? ​
ts
optional transition?: number;
visibility? ​
ts
optional visibility?: number;
wind? ​
ts
optional wind?: object;
gusts? ​
ts
optional gusts?: number;
referenceHeight? ​
ts
optional referenceHeight?: number;
shear? ​
ts
optional shear?: number;
terrain? ​
ts
optional terrain?: number;
turbulence? ​
ts
optional turbulence?: number;

WeatherProfile ​

ts
type WeatherProfile = "sunny" | "partly-cloudy" | "overcast" | "rain" | "storm" | "snow" | "fog";

Variables ​

actuatorInputsSchema ​

ts
const actuatorInputsSchema: z.ZodType<ActuatorInputs>;

actuatorPositionsSchema ​

ts
const actuatorPositionsSchema: z.ZodType<ActuatorPositions>;

actuatorSpecsSchema ​

ts
const actuatorSpecsSchema: z.ZodType<ActuatorSpecs>;

AUDIO_BUS_PATTERN ​

ts
const AUDIO_BUS_PATTERN: RegExp;

Bus names: lowercase, e.g. music, ambience, sfx, ui, voice.


AUDIO_BUSES ​

ts
const AUDIO_BUSES: readonly string[];

The buses every audio backend creates; others are created on first use.


AUDIO_SIGNALS ​

ts
const AUDIO_SIGNALS: Readonly<Record<string, string>>;

Built-in signal names (besides <component>.<field> on an entity and host-supplied host.*).


audioEnvironmentSchema ​

ts
const audioEnvironmentSchema: z.ZodType<AudioEnvironmentData>;

audioSignalBindingSchema ​

ts
const audioSignalBindingSchema: z.ZodType<AudioSignalBinding>;

audioSignalDriveSchema ​

ts
const audioSignalDriveSchema: z.ZodType<AudioSignalDrive>;

audioSourceSchema ​

ts
const audioSourceSchema: z.ZodType<AudioSourceData>;

audioWhenSchema ​

ts
const audioWhenSchema: z.ZodType<AudioWhen>;

audioZoneSchema ​

ts
const audioZoneSchema: z.ZodType<AudioZoneData>;

BOOST_SPEED_MULTIPLIER ​

ts
const BOOST_SPEED_MULTIPLIER: 4 = 4;

Travel assist: four times the distance with ordinary control response times.


glassImpactSchema ​

ts
const glassImpactSchema: z.ZodType<GlassImpactEvent>;

glassSchema ​

ts
const glassSchema: z.ZodType<GlassData>;

glassStateSchema ​

ts
const glassStateSchema: z.ZodType<GlassStateData>;

glassSurfaceSchema ​

ts
const glassSurfaceSchema: z.ZodType<GlassSurfaceSpec>;

inputProfileSchema ​

ts
const inputProfileSchema: z.ZodType<InputProfile>;

liverySchema ​

ts
const liverySchema: z.ZodType<LiveryData>;

modelSignalDerivedSchema ​

ts
const modelSignalDerivedSchema: z.ZodType<Record<string, ModelSignalExpression>>;

Validated once, before compiling a visual. Bounds also keep dependency traversal small.


modelSignalExpressionSchema ​

ts
const modelSignalExpressionSchema: z.ZodType<ModelSignalExpression>;

modelSignalSpecSchema ​

ts
const modelSignalSpecSchema: z.ZodType<ModelSignalSpec>;

Bindings plus optional same-entity sources, as a vehicle visual's animation block.


modelSignalsSchema ​

ts
const modelSignalsSchema: z.ZodType<ModelSignalSpec>;

Automatic ECS bridge requires all sources; the direct API can supply values itself.


PACK_MANIFEST_ENTRY ​

ts
const PACK_MANIFEST_ENTRY: "molen-pack.json" = "molen-pack.json";

Zip member name of the manifest; it is written last, just before the central directory.


PACK_RESERVED_PREFIX ​

ts
const PACK_RESERVED_PREFIX: "molen-pack/" = "molen-pack/";

Reserved prefix for zip members that are not logical files (solid blocks).


SCHEMA_ID_BASE ​

ts
const SCHEMA_ID_BASE: string;

Absolute base URI for the $id of every emitted JSON Schema (scripts/emit-schemas.mjs). The docs site (molen.dev) serves them, so an authored document can carry a resolvable "$schema" line and one emitted schema can $ref another. A bare relative $id like molen/scene@3 resolves against nothing, which is why the format envelope id (meta.id) and the schema $id are deliberately different strings.


skySchema ​

ts
const skySchema: z.ZodType<SkyData>;

Data-only configuration for an Earth ephemeris or an authored fantasy sky.


SOUND_ID_PATTERN ​

ts
const SOUND_ID_PATTERN: RegExp;

Sound ids: lowercase dotted segments, e.g. ambience.rain.medium, footstep.grass.


SOUNDBANK_EXAMPLE ​

ts
const SOUNDBANK_EXAMPLE: SoundbankDoc;

soundbankSchema ​

ts
const soundbankSchema: z.ZodType<SoundbankDoc>;

vehicleInteriorSchema ​

ts
const vehicleInteriorSchema: z.ZodType<VehicleInteriorSpec>;

waterSettingsSchema ​

ts
const waterSettingsSchema: z.ZodType<WaterSettings>;

weatherSchema ​

ts
const weatherSchema: z.ZodType<WeatherData>;

Data-only weather shared by headless simulation, scripts and rendering.

Functions ​

audioSignalBindings() ​

ts
function audioSignalBindings(drive): AudioSignalBinding[];

The bindings of a drive as a list.

Parameters ​

drive ​

AudioSignalDrive | undefined

Returns ​

AudioSignalBinding[]


audioSignalIssues() ​

ts
function audioSignalIssues(signal, path?): ValidationIssue[];

Issues for a signal path (unknown built-ins get did-you-mean); component paths pass.

Parameters ​

signal ​

string

path? ​

string

Returns ​

ValidationIssue[]


audioSignalRefs() ​

ts
function audioSignalRefs(component, data): object[];

Every signal path an audio component or environment references, with its JSON Pointer.

Parameters ​

component ​

"audioSource" | "audioZone" | "audioEnvironment"

data ​

| AudioEnvironmentData | AudioSourceData | AudioZoneData

Returns ​

object[]


audioSoundRefs() ​

ts
function audioSoundRefs(component, data): object[];

Every sound id an audio component or environment references, with its JSON Pointer.

Parameters ​

component ​

"audioSource" | "audioZone" | "audioEnvironment"

data ​

| AudioEnvironmentData | AudioSourceData | AudioZoneData

Returns ​

object[]


blockingIssues() ​

ts
function blockingIssues(issues): ValidationIssue[];

The issues that make a document invalid (everything except notices).

Parameters ​

issues ​

ValidationIssue[]

Returns ​

ValidationIssue[]


boostSpeedMultiplier() ​

ts
function boostSpeedMultiplier(enabled): number;

Parameters ​

enabled ​

boolean | undefined

Returns ​

number


buildTypeIndex() ​

ts
function buildTypeIndex(docs): TypeIndex;

Index type defs across documents; duplicate ids across files are issues.

Parameters ​

docs ​

object[]

Returns ​

TypeIndex


checkTypes() ​

ts
function checkTypes(project, docs): ValidationIssue[];

Project-level cross-checks over all types documents: cross-file duplicates, dangling/cyclic extends, namespace ownership vs reservations, and asset refs missing from project.assets. (Per-file namespace containment and per-type component shapes are covered by validate.)

Parameters ​

project ​

ProjectManifest

docs ​

object[]

Returns ​

ValidationIssue[]


commandPayloadValidator() ​

ts
function commandPayloadValidator(type, schema): (payload) => PayloadCheck;

Build a command payload validator from a declared JSON Schema. The message on failure is the standard formatted issue block, labelled command "<type>" payload.

Parameters ​

type ​

string

schema ​

JsonObject

Returns ​

(payload) => PayloadCheck


compileCommandPayload() ​

ts
function compileCommandPayload(schema): ZodType;

Compile a JSON Schema payload shape to a Zod schema. Throws (with the converter's message) when the document uses keywords the converter does not support, and refuses a pattern that can backtrack catastrophically — molen validate reports the same patterns as issues, but a host that builds a world straight from a scene file never gets to run one.

Parameters ​

schema ​

JsonObject

Returns ​

ZodType


componentIssues() ​

ts
function componentIssues(
   name, 
   data, 
   basePointer, 
   opts?
): ValidationIssue[];

Validate one component's data, returning prefixed ValidationIssues. basePointer is the JSON Pointer to the component itself (e.g. "/entities/0/components/transform").

Parameters ​

name ​

string

data ​

unknown

basePointer ​

string

opts? ​

ComponentValidateOptions

Returns ​

ValidationIssue[]


componentMapIssues() ​

ts
function componentMapIssues(
   componentMap, 
   basePointer, 
   opts?
): ValidationIssue[];

Walk a component map and collect issues for each entry.

Parameters ​

componentMap ​

Record&lt;string, unknown&gt; | undefined

basePointer ​

string

opts? ​

ComponentValidateOptions

Returns ​

ValidationIssue[]


componentNames() ​

ts
function componentNames(registry?): string[];

Parameters ​

registry? ​

ComponentRegistry

Returns ​

string[]


createComponentRegistry() ​

ts
function createComponentRegistry(decls?, opts?): object;

Create an isolated vocabulary. Validation never installs declarations in another context.

Parameters ​

decls? ​

Record&lt;string, DeclaredComponent&gt;

opts? ​
base? ​

ComponentRegistry

owner? ​

string

Returns ​

object

issues ​
ts
issues: ValidationIssue[];
registry ​
ts
registry: ComponentRegistry;

decodeCollisionTrimesh() ​

ts
function decodeCollisionTrimesh(header, bin): object;

Decode a collision trimesh from its sidecar header + binary bytes. Pure (no fs/WASM) so the kernel/physics side can consume asset collision headlessly.

Parameters ​

AssetTrimeshHeader

bin ​

Uint8Array

Returns ​

object

indices ​
ts
indices: Uint32Array;
positions ​
ts
positions: Float32Array;

deepMergeJson() ​

ts
function deepMergeJson(base, override): JsonObject;

Deep-merge JSON objects (later sources win); arrays and primitives are replaced wholesale. The one merge semantics used everywhere data layers stack: prefab extends chains, type defaults under scene data, entity components under overrides. Inputs are never mutated.

Parameters ​

base ​

JsonObject

override ​

JsonObject

Returns ​

JsonObject


detectKind() ​

ts
function detectKind(data): string | undefined;

Infer the schema kind from a document's format/kind envelope fields (any registered kind).

Parameters ​

data ​

unknown

Returns ​

string | undefined


encodeCollisionTrimesh() ​

ts
function encodeCollisionTrimesh(positions, indices): object;

Encode a collision trimesh to binary + header fields (the writer used by asset import).

Parameters ​

positions ​

Float32Array

indices ​

Uint32Array

Returns ​

object

bin ​
ts
bin: Uint8Array;
indices ​
ts
indices: object;
indices.byteOffset ​
ts
byteOffset: number;
indices.count ​
ts
count: number;
positions ​
ts
positions: object;
positions.byteOffset ​
ts
byteOffset: number;
positions.count ​
ts
count: number;

findReservation() ​

ts
function findReservation(reservations, id): NamespaceReservation | undefined;

The longest (most specific) reservation covering an id, if any.

Parameters ​

reservations ​

readonly NamespaceReservation[]

id ​

string

Returns ​

NamespaceReservation | undefined


formatIssues() ​

ts
function formatIssues(label, issues): string;

Renders the agent-facing error block. Its exact shape is a tested product surface.

Parameters ​

label ​

string

issues ​

ValidationIssue[]

Returns ​

string


getComponent() ​

ts
function getComponent(name, registry?): ComponentEntry | undefined;

Parameters ​

name ​

string

registry? ​

ComponentRegistry

Returns ​

ComponentEntry | undefined


getLegacySchema() ​

ts
function getLegacySchema(kind, formatId): LegacySchemaVersion | undefined;

Find the legacy version entry (if any) whose id matches a document's format.

Parameters ​

kind ​

string

formatId ​

string

Returns ​

LegacySchemaVersion | undefined


getSchema() ​

ts
function getSchema(kind): SchemaEntry | undefined;

Parameters ​

kind ​

string

Returns ​

SchemaEntry | undefined


inputProfileIssues() ​

ts
function inputProfileIssues(profile): object[];

Semantic constraints shared by scene validation and runtime remapping.

Parameters ​

profile ​

InputProfile

Returns ​

object[]


jsonSchemaId() ​

ts
function jsonSchemaId(formatId): string;

The absolute $id an emitted JSON Schema carries, derived from a format envelope id: molen/scene@3 → https://molen.dev/schemas/scene@3.json, and molen/component/transform@1 → https://molen.dev/schemas/component/transform@1.json.

Parameters ​

formatId ​

string

Returns ​

string


listComponents() ​

ts
function listComponents(registry?): ComponentSummary[];

Parameters ​

registry? ​

ComponentRegistry

Returns ​

ComponentSummary[]


listRenderableKinds() ​

ts
function listRenderableKinds(): object[];

Every registered renderable kind, in registration order (core kinds first).

Returns ​

object[]


listSchemas() ​

ts
function listSchemas(): SchemaSummary[];

Returns ​

SchemaSummary[]


namespaceCovers() ​

ts
function namespaceCovers(ns, id): boolean;

Does a reserved namespace cover an id? Dot-boundary prefix: "train" covers "train.car", not "trainer.x".

Parameters ​

ns ​

string

id ​

string

Returns ​

boolean


nearest() ​

ts
function nearest(input, candidates): string | undefined;

Nearest candidate by Levenshtein distance, if close enough to be a likely typo.

Parameters ​

input ​

string

candidates ​

string[]

Returns ​

string | undefined


nearestWithDistance() ​

ts
function nearestWithDistance(input, candidates): 
  | {
  candidate: string;
  distance: number;
}
  | undefined;

Like nearest, but also reports the (case-insensitive) edit distance.

Parameters ​

input ​

string

candidates ​

string[]

Returns ​

| { candidate: string; distance: number; } | undefined


noticeIssues() ​

ts
function noticeIssues(issues): ValidationIssue[];

The advisory issues only.

Parameters ​

issues ​

ValidationIssue[]

Returns ​

ValidationIssue[]


registerComponent() ​

ts
function registerComponent(
   name, 
   zod, 
   meta, 
   opts?
): void;

Register a component schema. Capability packages and content may register their own component names so validation knows about them; core components are registered below. Duplicate names throw (two packages silently fighting over one name is a determinism hazard) unless { override: true } is passed.

Parameters ​

name ​

string

zod ​

ZodType

meta ​

ComponentMeta

opts? ​

RegisterComponentOptions

Returns ​

void


registerDeclaredComponents() ​

ts
function registerDeclaredComponents(decls, opts): ValidationIssue[];

Register a declared custom-component vocabulary so every consumer (validation, spawn checks, molen components, docs) knows the names. A declaration WITH a schema is shape-checked like a core component; without one it accepts any object. Re-declaring overrides (a project reload is the normal case). Returns blocking issues for reserved names or unsupported schemas.

registry is REQUIRED and is never the process-global vocabulary: one document's declarations must not leak into every later validation in a long-lived process (an MCP server validates documents from unrelated projects back to back). createComponentRegistry is the normal entry point; call this directly only to add declarations to a registry you already own.

Parameters ​

decls ​

Record&lt;string, DeclaredComponent&gt;

opts ​
owner? ​

string

pointer? ​

string

registry ​

Map&lt;string, ComponentEntry&gt;

Returns ​

ValidationIssue[]


registerLegacySchema() ​

ts
function registerLegacySchema(kind, legacy): void;

Register a previous version of a kind. Documents carrying the legacy format id still validate — against the legacy Zod, then upgraded to the current shape via upgrade() — and the result carries a deprecation notice (see validateByKind). There is no migration command: a legacy document is upgraded in memory on read, and a breaking change bumps the version.

Parameters ​

kind ​

string

legacy ​

LegacySchemaVersion

Returns ​

void


registerRenderableKind() ​

ts
function registerRenderableKind(kind, meta): void;

Register a renderable kind rendered by a capability client half (e.g. 'figure'). Idempotent (re-registering updates the description) and additive: renderable is re-registered with the widened kind enum — and with any fields the kind declares — so molen validate, the emitted JSON Schema, and the docs all list it.

Parameters ​

kind ​

string

meta ​

RenderableKindMeta

Returns ​

void


registerSchema() ​

ts
function registerSchema(
   kind, 
   zod, 
   meta
): void;

Capability packages register their formats here; tooling sees one unified registry.

Parameters ​

kind ​

string

zod ​

ZodType

meta ​

SchemaMeta

Returns ​

void


resolveAllTypes() ​

ts
function resolveAllTypes(index): Map<string, ResolvedEntityType>;

Parameters ​

index ​

Map&lt;string, TypeIndexEntry&gt;

Returns ​

Map&lt;string, ResolvedEntityType&gt;


resolveEntityComponents() ​

ts
function resolveEntityComponents(
   manifest, 
   entity, 
   opts?
): ComponentMap;

Resolve a scene entity's final components (type <- prefab <- components).

Parameters ​

manifest ​

SceneManifest

entity ​
components? ​

ComponentMap

prefab? ​

string

type? ​

string

opts? ​

SceneResolveOptions

Returns ​

ComponentMap


resolvePrefab() ​

ts
function resolvePrefab(
   manifest, 
   name, 
   opts?, 
   seen?
): ComponentMap;

Resolve a prefab's components: registry type <- extends chain <- own components.

Parameters ​

manifest ​

SceneManifest

name ​

string

opts? ​

SceneResolveOptions

seen? ​

string[]

Returns ​

ComponentMap


resolveSnowCover() ​

ts
function resolveSnowCover(data): ResolvedSnowCover;

A snow cover with its defaults filled in.

Parameters ​

data ​
depth? ​

number

depthGain? ​

number

level ​

number

maxDepth? ​

number

transition? ​

number

Returns ​

ResolvedSnowCover


resolveType() ​

ts
function resolveType(
   index, 
   id, 
   seen?
): ComponentMap;

Resolve a type's component map, following the extends chain ancestor-first (parent under child). Throws on unknown ids and cycles — callers validate first via checkTypes.

Parameters ​

index ​

Map&lt;string, TypeIndexEntry&gt;

id ​

string

seen? ​

string[]

Returns ​

ComponentMap


resolveWeather() ​

ts
function resolveWeather(data?): ResolvedWeather;

Expand validated weather data without changing or retaining its mutable nested values.

Parameters ​

data? ​

WeatherData

Returns ​

ResolvedWeather


sceneTypeRefIssues() ​

ts
function sceneTypeRefIssues(manifest, knownTypeIds): ValidationIssue[];

Scene entities/prefabs that reference registry type ids the project does not define. Pure: pass the ids the project resolved (e.g. resolvedTypes.keys()); the issues carry a did-you-mean over them, so molen validate and the scene loader report a typo'd type with a pointer instead of the kernel throwing "unknown type".

Parameters ​

manifest ​

SceneManifest

knownTypeIds ​

Iterable&lt;string&gt;

Returns ​

ValidationIssue[]


schemaKinds() ​

ts
function schemaKinds(): string[];

Returns ​

string[]


snowCoverAt() ​

ts
function snowCoverAt(cover, altitude): SnowCoverSample;

Snow on the ground at an absolute world height. Cover builds smoothly from the snow line to complete at the top of the transition, where it is depth deep, and deepens by depthGain for each 1000 m above that, up to maxDepth. Uses only arithmetic, so simulation and rendering agree bit for bit on every platform.

Parameters ​

cover ​

| { depth?: number; depthGain?: number; level: number; maxDepth?: number; transition?: number; } | undefined

altitude ​

number

Returns ​

SnowCoverSample


snowWalkingPace() ​

ts
function snowWalkingPace(depth): number;

Share of a person's pace left when wading through lying snow depth meters deep: all of it up to boot-sole depth, about 70% at 30 cm, 40% from 60 cm on.

Parameters ​

depth ​

number

Returns ​

number


unregisterComponent() ​

ts
function unregisterComponent(name): boolean;

Remove a registration (tests, and re-loading a project with a changed vocabulary). Core components are not removable: unregisterComponent('transform') would leave every later validation in a long-lived process (an MCP server, the dev server) unable to check the one component every entity has, and nothing would report it.

Parameters ​

name ​

string

Returns ​

boolean


validate() ​

ts
function validate<K>(
   kind, 
   data, 
   opts?
): ValidationResult<SchemaKindMap[K]>;

Type Parameters ​

K ​

K extends keyof SchemaKindMap

Parameters ​

kind ​

K

data ​

unknown

opts? ​

ValidateOptions

Returns ​

ValidationResult&lt;SchemaKindMap[K]&gt;


validateByKind() ​

ts
function validateByKind(
   kind, 
   data, 
   opts?
): ValidationResult<unknown>;

Validate against any registered schema kind (core or capability-package). Returns an untyped result; prefer the typed validate<K> for the core kinds in SchemaKindMap.

Parameters ​

kind ​

string

data ​

unknown

opts? ​

ValidateOptions

Returns ​

ValidationResult&lt;unknown&gt;


validateSoundbank() ​

ts
function validateSoundbank(data): ValidationIssue[];

Cross-field checks Zod cannot express (loop ranges, pitch order, license policy, paths).

Parameters ​

data ​

unknown

Returns ​

ValidationIssue[]


weatherProfile() ​

ts
function weatherProfile(profile): WeatherData;

Presets are starting points, not a mutually exclusive weather model. Returns fresh data.

Parameters ​

profile ​

WeatherProfile

Returns ​

WeatherData

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