`@bendyline/molen-schema`

ComponentValidateOptions.allowUnknownComponents

SchemaSummary

Properties

description

description: string;

id

id: string;

kind

kind: string;

title

title: string;

ScriptRef

Properties

checkpoint?

optional checkpoint?: "state";

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

code?

optional code?: string;

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

config

config: JsonObject;

id

id: string;

path?

optional path?: string;

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

SelectAssertion

Properties

op

op: SelectOp;

select

select: string;

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

tol?

optional tol?: number;

value?

optional value?: JsonValue;

SkyAppearance

Properties

lighting?

optional lighting?: object;

castShadow?

optional castShadow?: boolean;

dayAmbient?

optional dayAmbient?: number;

moonIntensity?

optional moonIntensity?: number;

nightAmbient?

optional nightAmbient?: number;

sunIntensity?

optional sunIntensity?: number;

moon?

optional moon?: object;

earthshine?

optional earthshine?: number;

size?

optional size?: number;

visible?

optional visible?: boolean;

palette?

optional palette?: SkyPalette;

stars?

optional stars?: object;

enabled?

optional enabled?: boolean;

intensity?

optional intensity?: number;

magnitudeLimit?

optional magnitudeLimit?: number;

size?

optional size?: number;

sun?

optional sun?: object;

size?

optional size?: number;

visible?

optional visible?: boolean;

SkyBodyData

Properties

angularDiameterDeg?

optional angularDiameterDeg?: number;

direction

direction: [number, number, number];

SkyPalette

Properties

dayHorizon?

optional dayHorizon?: string;

dayZenith?

optional dayZenith?: string;

ground?

optional ground?: string;

moon?

optional moon?: string;

nightHorizon?

optional nightHorizon?: string;

nightZenith?

optional nightZenith?: string;

sun?

optional sun?: string;

twilight?

optional twilight?: string;

SkyTime

Properties

epochMs

epochMs: number;

UTC Unix milliseconds at simulation second zero.

scale?

optional scale?: number;

Sky seconds per simulation second, default 1.

SourceBundle

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

Properties

files

files: object;

definitions

definitions: string[];

documents

documents: string[];

generators

generators: SourceBundleNamedFile[];

models

models: SourceBundleModel[];

scripts

scripts: SourceBundleNamedFile[];

sounds

sounds: SourceBundleNamedFile[];

textures

textures: SourceBundleNamedFile[];

format

format: "molen/source-bundle@1";

id

id: string;

kind

kind: string;

order?

optional order?: number;

title

title: string;

SourceBundleModel

Properties

assetId?

optional assetId?: string;

output?

optional output?: string;

path

path: string;

pipeline?

optional pipeline?: "copy" | "import";

sha256?

optional sha256?: string;

SourceBundleNamedFile

Properties

id

id: string;

path

path: string;

TypeIndex

Properties

index

index: Map<string, TypeIndexEntry>;

issues

issues: ValidationIssue[];

TypeIndexEntry

Properties

def

def: EntityTypeDef;

id

id: string;

source?

optional source?: string;

Which types document declared it (for error messages).

TypesDoc

Properties

doc?

optional doc?: string;

format

format: "molen/types@1";

namespace

namespace: string;

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

owner?

optional owner?: string;

Matched against project reservations by molen types check.

types

types: Record<string, EntityTypeDef>;

ValidateOptions

Extends

ComponentValidateOptions

Properties

allowUnknownComponents?

optional allowUnknownComponents?: boolean;

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

Inherited from

label?

optional label?: string;

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

partial?

optional partial?: boolean;

Inherited from

ComponentValidateOptions.partial

registry?

optional registry?: ComponentRegistry;

Inherited from

ComponentValidateOptions.registry

types?

optional types?: ResolvedTypes;

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

ValidationFailure

Properties

formatted

formatted: string;

issues

issues: ValidationIssue[];

ok

ok: false;

ValidationIssue

Properties

code

code: string;

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

docsRef?

optional docsRef?: string;

expected?

optional expected?: string;

What valid looks like.

hint?

optional hint?: string;

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

message

message: string;

What is wrong.

path

path: string;

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

received?

optional received?: string;

What was found (truncated repr).

severity?

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

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

ValidationSuccess

Type Parameters

T

T

Properties

notices?

optional notices?: ValidationIssue[];

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

ok

ok: true;

value

value: T;

VehicleData

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

Extends

JsonObject

Indexable

[key: string]: JsonValue | undefined

Properties

color

color: string;

kind

kind: string;

spec

spec: VehicleSpec;

visual

visual: VehicleVisualSpec;

VehicleInteriorSpec

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

Extends

ModelSignalSpec

Indexable

[key: string]: JsonValue | undefined

Properties

bindings

bindings: ModelSignalBinding[];

Inherited from

ModelSignalSpec.bindings

nodes

nodes: string[];

Informational: never hidden on boarding or in chase view.

sources?

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

color: string;

id

id: string;

kind

kind: string;

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

pitch?

optional pitch?: number;

position

position: [number, number, number];

roll?

optional roll?: number;

spec

spec: VehicleSpec;

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

yaw

yaw: number;

VehicleSpec

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

Extends

JsonObject

Indexable

[key: string]: JsonValue | undefined

Properties

aerodynamicResistance

aerodynamicResistance: number;

brakeDeceleration

brakeDeceleration: number;

centerOfMass

centerOfMass: [number, number, number];

driverEye

driverEye: [number, number, number];

engineForce

engineForce: number;

grip

grip: number;

height

height: number;

label

label: string;

length

length: number;

mass

mass: number;

maxSlope

maxSlope: number;

maxSpeed

maxSpeed: number;

maxSteer

maxSteer: number;

maxStepHeight

maxStepHeight: number;

reverseSpeed

reverseSpeed: number;

rollingResistance

rollingResistance: number;

steeringFadeSpeed

steeringFadeSpeed: number;

steeringRate

steeringRate: number;

supportTolerance

supportTolerance: number;

terrainAlignRate

terrainAlignRate: number;

wheelbase

wheelbase: number;

wheelRadius

wheelRadius: number;

wheelTrack

wheelTrack: number;

width

width: number;

VehicleVisualSpec

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

Extends

JsonObject

Indexable

[key: string]: JsonValue | undefined

Properties

frontWheelNodes

frontWheelNodes: string[];

interior?

optional interior?: VehicleInteriorSpec;

paintMaterial

paintMaterial: string;

steeringWheelNode?

optional steeringWheelNode?: string;

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

wheelNodes

wheelNodes: string[];

Type Aliases

AircraftKind

type AircraftKind = string;

Stable external entity/type id for an aircraft.

Assertion

type Assertion = 
  | SelectAssertion
  | EventAssertion;

AudioAmbienceLayer

type AudioAmbienceLayer = object;

Properties

fadeS?

optional fadeS?: number;

gain?

optional gain?: number;

gainFrom?

optional gainFrom?: AudioSignalDrive;

pitchFrom?

optional pitchFrom?: AudioSignalDrive;

sound

sound: string;

when?

optional when?: AudioWhen;

AudioCondition

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

AudioEnvironmentData

type AudioEnvironmentData = object;

Properties

ambience?

optional ambience?: AudioAmbienceLayer[];

buses?

optional buses?: Record<string, number>;

events?

optional events?: Record<string, AudioEventRule>;

footsteps?

optional footsteps?: AudioFootsteps;

listenerEntity?

optional listenerEntity?: string;

maxVoices?

optional maxVoices?: number;

music?

optional music?: AudioMusicSpec;

AudioEventRule

type AudioEventRule = object;

Properties

at?

optional at?: string;

bus?

optional bus?: string;

gain?

optional gain?: number;

pitch?

optional pitch?: number;

sound

sound: string;

AudioFootsteps

type AudioFootsteps = object;

Properties

gain?

optional gain?: number;

sound

sound: string;

strideM?

optional strideM?: number;

surfaces?

optional surfaces?: Record<string, string>;

when?

optional when?: AudioWhen;

AudioMusicSpec

type AudioMusicSpec = object;

Properties

crossfadeS?

optional crossfadeS?: number;

gain?

optional gain?: number;

mode?

optional mode?: "sequence" | "shuffle";

playlist

playlist: string[];

when?

optional when?: AudioWhen;

AudioScalar

type AudioScalar = string | number | boolean;

AudioSignalBinding

type AudioSignalBinding = object;

Properties

curve

curve: [number, number][];

signal

signal: string;

smoothS?

optional smoothS?: number;

AudioSignalDrive

type AudioSignalDrive = 
  | AudioSignalBinding
  | AudioSignalBinding[];

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

AudioSourceData

type AudioSourceData = object;

Properties

autoplay?

optional autoplay?: boolean;

bus?

optional bus?: string;

gain?

optional gain?: number;

gainFrom?

optional gainFrom?: AudioSignalDrive;

loop?

optional loop?: boolean;

pitch?

optional pitch?: number;

pitchFrom?

optional pitchFrom?: AudioSignalDrive;

sound

sound: string;

spatial?

optional spatial?: SoundSpatial | false;

startTick?

optional startTick?: number;

triggerFrom?

optional triggerFrom?: AudioTrigger;

when?

optional when?: AudioWhen;

AudioTrigger

type AudioTrigger = object;

Properties

every?

optional every?: number;

onChange?

optional onChange?: boolean;

signal

signal: string;

sound?

optional sound?: string;

AudioWhen

type AudioWhen = Record<string, AudioCondition>;

AudioZoneData

type AudioZoneData = object;

Properties

bus?

optional bus?: string;

fade?

optional fade?: number;

gain?

optional gain?: number;

shape

shape: 
  | {
  kind: "sphere";
  radius: number;
}
  | {
  halfExtents: [number, number, number];
  kind: "box";
};

sound

sound: string;

when?

optional when?: AudioWhen;

ComponentMap

type ComponentMap = Record<string, JsonObject>;

Component name -> pure-JSON component data.

ComponentRegistry

type ComponentRegistry = ReadonlyMap<string, ComponentEntry>;

ContentIdentity

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

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

EntityId

type EntityId = string;

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

FlightModel

type FlightModel = "airplane" | "helicopter";

InputEmitRule

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

type JsonPrimitive = string | number | boolean | null;

JsonValue

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

KernelInbound

type KernelInbound = CommandMessage | ControlMessage;

Messages the client sends to the kernel.

KernelOutbound

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

Messages the kernel sends to the client.

PayloadCheck

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

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

Quat

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

ResolvedTypes

type ResolvedTypes = ReadonlyMap<string, ResolvedEntityType>;

Pre-flattened project type registry.

ResolvedWeather

type ResolvedWeather = object;

Properties

atmosphere

atmosphere: Required<NonNullable<WeatherData["atmosphere"]>>;

clouds

clouds: Required<NonNullable<WeatherData["clouds"]>>;

precipitation

precipitation: Required<NonNullable<WeatherData["precipitation"]>>;

seed

seed: number;

visibility

visibility: number;

SceneAmbientKind

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

An NPC class the ambient-life capability simulates.

SceneCamera

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

type SchemaKind = keyof SchemaKindMap;

SelectOp

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

type SkyData = EarthSkyData | CustomSkyData;

SoundbankDoc

type SoundbankDoc = object;

Properties

format

format: "molen/soundbank@1";

id

id: string;

license?

optional license?: string;

sounds

sounds: Record<string, SoundEntry>;

title?

optional title?: string;

SoundEntry

type SoundEntry = object;

Properties

bus?

optional bus?: string;

clips

clips: string[];

description?

optional description?: string;

durationS?

optional durationS?: number;

gain?

optional gain?: number;

hash?

optional hash?: string;

loop?

optional loop?: boolean;

loopEnd?

optional loopEnd?: number;

loopStart?

optional loopStart?: number;

pitch?

optional pitch?: [number, number];

source

source: SoundSource;

spatial?

optional spatial?: SoundSpatial | false;

tags?

optional tags?: string[];

SoundSource

type SoundSource = object;

Properties

author?

optional author?: string;

generator?

optional generator?: string;

license

license: string;

notes?

optional notes?: string;

prompt?

optional prompt?: string;

site?

optional site?: string;

title?

optional title?: string;

url?

optional url?: string;

SoundSpatial

type SoundSpatial = object;

Properties

maxDistance?

optional maxDistance?: number;

model?

optional model?: "linear" | "inverse" | "exponential";

refDistance?

optional refDistance?: number;

rolloff?

optional rolloff?: number;

ValidationResult

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

Type Parameters

T

T

Vec3

type Vec3 = [number, number, number];

VehicleInteriorBinding

type VehicleInteriorBinding = ModelSignalBinding;

VehicleKind

type VehicleKind = string;

Stable external entity/type id for a wheeled vehicle.

WeatherData

type WeatherData = object;

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

Properties

atmosphere?

optional atmosphere?: object;

gasConstant?

optional gasConstant?: number;

pressurePa?

optional pressurePa?: number;

referenceAltitude?

optional referenceAltitude?: number;

relativeHumidity?

optional relativeHumidity?: number;

temperatureK?

optional temperatureK?: number;

windVelocity?

optional windVelocity?: [number, number, number];

clouds?

optional clouds?: object;

baseAltitude?

optional baseAltitude?: number;

coverage?

optional coverage?: number;

density?

optional density?: number;

scale?

optional scale?: number;

thickness?

optional thickness?: number;

precipitation?

optional precipitation?: object;

intensity?

optional intensity?: number;

kind?

optional kind?: "none" | "rain" | "snow";

seed?

optional seed?: number;

visibility?

optional visibility?: number;

WeatherProfile

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

Variables

AUDIO_BUS_PATTERN

const AUDIO_BUS_PATTERN: RegExp;

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

AUDIO_BUSES

const AUDIO_BUSES: readonly string[];

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

AUDIO_SIGNALS

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

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

audioEnvironmentSchema

const audioEnvironmentSchema: z.ZodType<AudioEnvironmentData>;

audioSignalBindingSchema

const audioSignalBindingSchema: z.ZodType<AudioSignalBinding>;

audioSignalDriveSchema

const audioSignalDriveSchema: z.ZodType<AudioSignalDrive>;

audioSourceSchema

const audioSourceSchema: z.ZodType<AudioSourceData>;

audioWhenSchema

const audioWhenSchema: z.ZodType<AudioWhen>;

audioZoneSchema

const audioZoneSchema: z.ZodType<AudioZoneData>;

inputProfileSchema

const inputProfileSchema: z.ZodType<InputProfile>;

modelSignalsSchema

const modelSignalsSchema: z.ZodType<ModelSignalSpec>;

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

PACK_MANIFEST_ENTRY

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

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

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

SCHEMA_ID_BASE

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

const skySchema: z.ZodType<SkyData>;

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

SOUND_ID_PATTERN

const SOUND_ID_PATTERN: RegExp;

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

SOUNDBANK_EXAMPLE

const SOUNDBANK_EXAMPLE: SoundbankDoc;

soundbankSchema

const soundbankSchema: z.ZodType<SoundbankDoc>;

vehicleInteriorSchema

const vehicleInteriorSchema: z.ZodType<VehicleInteriorSpec>;

weatherSchema

const weatherSchema: z.ZodType<WeatherData>;

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

Functions

audioSignalBindings()

function audioSignalBindings(drive): AudioSignalBinding[];

The bindings of a drive as a list.

Parameters

drive

AudioSignalDrive | undefined

Returns

AudioSignalBinding[]

audioSignalIssues()

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

audioSignalRefs()

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()

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()

function blockingIssues(issues): ValidationIssue[];

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

Parameters

issues

Returns

buildTypeIndex()

function buildTypeIndex(docs): TypeIndex;

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

Parameters

docs

object[]

Returns

TypeIndex

checkTypes()

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

ComponentValidateOptions

commandPayloadValidator()

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()

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()

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?

Returns

ComponentValidateOptions

componentMapIssues()

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

Walk a component map and collect issues for each entry.

Parameters

componentMap

Record<string, unknown> | undefined

basePointer

string

opts?

Returns

componentNames()

function componentNames(registry?): string[];

Parameters

registry?

Returns

string[]

createComponentRegistry()

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

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

Parameters

decls?

Record<string, DeclaredComponent>

opts?

base?

owner?

string

Returns

object

issues

issues: ValidationIssue[];

registry

registry: ComponentRegistry;

decodeCollisionTrimesh()

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

indices: Uint32Array;

positions

positions: Float32Array;

deepMergeJson()

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

detectKind()

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()

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

bin: Uint8Array;

indices

indices: object;

indices.byteOffset

byteOffset: number;

indices.count

count: number;

positions

positions: object;

positions.byteOffset

byteOffset: number;

positions.count

count: number;

findReservation()

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()

function formatIssues(label, issues): string;

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

Parameters

label

string

issues

Returns

string

getComponent()

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

Parameters

name

string

registry?

Returns

ComponentEntry | undefined

getLegacySchema()

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()

function getSchema(kind): SchemaEntry | undefined;

Parameters

kind

string

Returns

SchemaEntry | undefined

inputProfileIssues()

function inputProfileIssues(profile): object[];

Semantic constraints shared by scene validation and runtime remapping.

Parameters

profile

InputProfile

Returns

object[]

jsonSchemaId()

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()

function listComponents(registry?): ComponentSummary[];

Parameters

registry?

Returns

ComponentSummary[]

listRenderableKinds()

function listRenderableKinds(): object[];

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

Returns

object[]

listSchemas()

function listSchemas(): SchemaSummary[];

Returns

SchemaSummary[]

namespaceCovers()

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()

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()

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()

function noticeIssues(issues): ValidationIssue[];

The advisory issues only.

Parameters

issues

Returns

RegisterComponentOptions

registerComponent()

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?

Returns

void

registerDeclaredComponents()

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<string, DeclaredComponent>

opts

owner?

string

pointer?

string

registry

Map<string, ComponentEntry>

Returns

registerLegacySchema()

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()

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()

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()

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

Parameters

index

Map<string, TypeIndexEntry>

Returns

Map<string, ResolvedEntityType>

resolveEntityComponents()

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

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

Parameters

manifest

SceneManifest

entity

components?

prefab?

string

type?

string

opts?

SceneResolveOptions

Returns

resolvePrefab()

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

resolveType()

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<string, TypeIndexEntry>

id

string

seen?

string[]

Returns

resolveWeather()

function resolveWeather(data?): ResolvedWeather;

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

Parameters

data?

WeatherData

Returns

ResolvedWeather

sceneTypeRefIssues()

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<string>

Returns

schemaKinds()

function schemaKinds(): string[];

Returns

string[]

unregisterComponent()

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()

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<SchemaKindMap[K]>

validateByKind()

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<unknown>

validateSoundbank()

function validateSoundbank(data): ValidationIssue[];

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

Parameters

data

unknown

Returns