@bendyline/molen-client

Molen rendering client: three.js wrapper, snapshot sync, interpolation.

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

Classes

AdaptiveQualityController

Rendering-only feedback controller; does not change simulation state or depend on a browser. Lower quickly, recover slowly, and probe with backoff instead of oscillating between tiers. Hosts should apply a change atomically to resolution, screen-space error, and residency.

Constructors

Constructor

new AdaptiveQualityController(options?): AdaptiveQualityController;

Parameters

options?

AdaptiveQualityOptions

Returns

AdaptiveQualityController

Methods

getStats()

getStats(): AdaptiveQualityStats;

Returns

AdaptiveQualityStats

sample()

sample(frameMs, sample?): AdaptiveQualityChange | undefined;

No allocation in the usual per-frame path. A change object is returned only on a step.

Parameters

frameMs

number

sample?

AdaptiveQualitySample

Returns

AdaptiveQualityChange | undefined

setBounds()

setBounds(minLevel, maxLevel): AdaptiveQualityChange | undefined;

Change a user/device ceiling and floor; an out-of-bounds current level is clamped.

Parameters

minLevel

number

maxLevel

number

Returns

AdaptiveQualityChange | undefined

setLevel()

setLevel(level): AdaptiveQualityChange | undefined;

Set a manual tier or restart automatic adaptation without carrying stale timing samples.

Parameters

level

number

Returns

AdaptiveQualityChange | undefined

---

AssetCache

Parse each glTF ref once; hand out per-entity instances (SkeletonUtils.clone so skinned meshes work while geometry/textures stay shared). whenIdle() resolves when no loads are pending — the capture path awaits it before its single deterministic frame.

Constructors

Constructor

new AssetCache(provider, loader): AssetCache;

Parameters

provider

AssetProvider

loader

GLTFLoader

Returns

AssetCache

Methods

clear()

clear(): void;

Returns

void

dispose()

dispose(): void;

Returns

void

instance()

instance(ref, node?): Promise<LoadedGltf>;

A fresh instance of the (sub-)scene for one entity.

Parameters

ref

string

node?

string

Returns

Promise<LoadedGltf>

track()

track<T>(p): Promise<T>;

Register an external async task (e.g. a material bake) so whenIdle() waits for it.

Type Parameters

T

T

Parameters

p

Promise<T>

Returns

Promise<T>

whenIdle()

whenIdle(): Promise<void>;

Resolves once every load kicked off so far has settled.

Returns

Promise<void>

---

FrameAdmissionQueue

Implements

• SceneAdmission

Constructors

Constructor

new FrameAdmissionQueue(options?): FrameAdmissionQueue;

Parameters

options?

FrameAdmissionOptions

Returns

FrameAdmissionQueue

Accessors

pending

Get Signature

get pending(): number;

Returns

number

Methods

dispose()

dispose(): void;

Returns

void

flush()

flush(): void;

One frame's budget. Exposed for hosts with a manual frame loop and deterministic tests.

Returns

void

promote()

promote(promise): void;

Move a still-queued background job to the normal lane, behind the jobs already there.

Parameters

promise

Promise<unknown>

Returns

void

run()

run<T>(task, options?): Promise<T>;

Type Parameters

T

T

Parameters

task

() => T

options?

AdmissionOptions

Returns

Promise<T>

Implementation of

SceneAdmission.run

---

InputMap

Keyboard/mouse + browser controllers mapped to numeric named actions. Call update() each frame (applyInputRules does this on its poller). Profiles are complete replacements.

Constructors

Constructor

new InputMap(opts): InputMap;

Parameters

opts

InputMapOptions

Returns

InputMap

Accessors

activeProfile

Get Signature

get activeProfile(): string | undefined;

Returns

string | undefined

gamepadStatus

Get Signature

get gamepadStatus(): "available" | "unavailable" | "blocked";

Returns

"available" | "unavailable" | "blocked"

Methods

activeActions()

activeActions(): Set<string>;

Returns

Set<string>

clearVirtual()

clearVirtual(source?): void;

Release every action a software control drives (all controls when source is omitted).

Parameters

source?

string

Returns

void

defineProfile()

defineProfile(name, profile): void;

Atomically validate and replace bindings; no held button becomes a new action.

Parameters

name

string | undefined

profile

InputProfile

Returns

void

devices()

devices(): InputGamepad[];

Snapshot of all detected devices and raw values, suitable for an axis/button inspector.

Returns

InputGamepad[]

dispose()

dispose(): void;

Returns

void

getProfile()

getProfile(...selection): InputProfile;

Detached, serializable copy for custom editors and host-managed persistence.

Parameters

selection

...[string]

Returns

InputProfile

isActive()

isActive(action): boolean;

Parameters

action

string

Returns

boolean

onChange()

onChange(handler): Unsubscribe;

Action values changed (including neutralization on reset/profile switch).

Parameters

handler

() => void

Returns

Unsubscribe

onPress()

onPress(action, handler): Unsubscribe;

Parameters

action

string

handler

(action) => void

Returns

Unsubscribe

onProfilesChanged()

onProfilesChanged(handler): Unsubscribe;

Profile selection or definitions changed.

Parameters

handler

() => void

Returns

Unsubscribe

onRelease()

onRelease(action, handler): Unsubscribe;

Parameters

action

string

handler

(action) => void

Returns

Unsubscribe

onReset()

onReset(handler): Unsubscribe;

Explicit neutralization on reset, focus loss, suspension or profile replacement.

Parameters

handler

() => void

Returns

Unsubscribe

press()

press(code): void;

Parameters

code

string

Returns

void

profileNames()

profileNames(): string[];

Returns

string[]

release()

release(code): void;

Parameters

code

string

Returns

void

reset()

reset(): void;

Release actions immediately; suppress held physical buttons until released.

Returns

void

setEnabled()

setEnabled(enabled): void;

Suspend while editing a form/menu; device discovery continues during update().

Parameters

enabled

boolean

Returns

void

setProfile()

setProfile(name): void;

Undefined selects the root bindings. Held keys/buttons must be released before reuse.

Parameters

name

string | undefined

Returns

void

setVirtual()

setVirtual(
   source, 
   action, 
   value
): void;

Drive an action from a software control such as a touch joystick or an on-screen button. source names the control so several can feed one action; like every device, the strongest contribution wins. A value persists until changed, clearVirtual, or a reset (focus loss, suspension, profile switch), and is ignored while input is not accepted.

Parameters

source

string

action

string

value

number

Returns

void

suspend()

suspend(): Unsubscribe;

Temporarily suppress gameplay while a remapping UI is open; returned release is idempotent.

Returns

Unsubscribe

update()

update(): void;

Poll fresh browser objects; unplugging or losing permission releases affected controls.

Returns

void

value()

value(action): number;

Numeric action value; strongest absolute contribution wins, keyboard wins ties.

Parameters

action

string

Returns

number

---

InterpolationBuffer

Holds a small ring of recent per-tick transform snapshots and samples interpolated transforms ~delayTicks behind the latest tick. Never extrapolates: clamps to the latest known transform when ahead of the buffer.

Constructors

Constructor

new InterpolationBuffer(tickRate, opts?): InterpolationBuffer;

Parameters

tickRate

number

opts?

capacity?

number

delayTicks?

number

Returns

InterpolationBuffer

Properties

delayTicks

readonly delayTicks: number;

tickRate

readonly tickRate: number;

Accessors

lastSampleVisited

Get Signature

get lastSampleVisited(): number;

Returns

number

latestTick

Get Signature

get latestTick(): number | undefined;

Returns

number | undefined

size

Get Signature

get size(): number;

Number of snapshots currently held (≤ capacity).

Returns

number

Methods

activate()

activate(id): void;

Reapply a static pose after a render/light binding changes without a transform delta.

Parameters

id

string

Returns

void

clear()

clear(): void;

Returns

void

estimateRenderTick()

estimateRenderTick(nowMs): number | undefined;

Estimate the render tick for a wall-clock time from the smoothed clock, minus the delay. Never runs ahead of the newest tick held (sampling clamps there anyway) and never steps backwards between calls, so a late delta cannot reverse motion mid-flight.

Parameters

nowMs

number

Returns

number | undefined

latestIds()

latestIds(): string[];

Ids present in the most recent snapshot.

Returns

string[]

push()

push(
   tick, 
   transforms, 
   recvMs
): void;

Record the transforms present at a kernel tick. recvMs is the local receive time.

Parameters

tick

number

transforms

Map<string, InterpTransform>

recvMs

number

Returns

void

pushDelta()

pushDelta(
   tick, 
   changes, 
   recvMs
): void;

Record a contiguous sparse update. Unmentioned entities keep their previous transform.

Parameters

tick

number

changes

Map<string, InterpTransform | undefined>

recvMs

number

Returns

void

sample()

sample(nowMs, id): InterpTransform | undefined;

Sample for a wall-clock time using the estimated render tick.

Parameters

nowMs

number

id

string

Returns

InterpTransform | undefined

sampleActive()

sampleActive(nowMs, apply): void;

Visit only changed/interpolating entities; send the final pose once before retiring it.

Parameters

nowMs

number

apply

(id, transform) => void

Returns

void

sampleAt()

sampleAt(renderTick, id): InterpTransform | undefined;

Sample an entity's interpolated transform at an explicit render tick (the tested core).

Parameters

renderTick

number

id

string

Returns

InterpTransform | undefined

---

MaterialResolver

Resolves materialRef strings to three.js materials. Sync for palette:; doc-backed refs (matgraph:/pixelgrid:) load + bake asynchronously. Every ref string maps to ONE cached material shared by all entities using it; acquire*/release refcount those so a material (and its textures) is disposed exactly when its last user lets go.

Constructors

Constructor

new MaterialResolver(provider?, baker?): MaterialResolver;

An optional caller-owned worker baker keeps procedural rasterization off the UI thread.

Parameters

provider?

AssetProvider

baker?

MaterialBaker

Returns

MaterialResolver

Methods

acquire()

acquire(materialRef): Promise<Material<MaterialEventMap>>;

resolve plus one reference; pair with release.

Parameters

materialRef

string

Returns

Promise<Material<MaterialEventMap>>

acquireSync()

acquireSync(materialRef): Material;

resolveSync plus one reference; pair with release.

Parameters

materialRef

string | undefined

Returns

Material

dispose()

dispose(): void;

Returns

void

isAsync()

isAsync(materialRef): boolean;

Is this a doc-backed ref that resolves asynchronously?

Parameters

materialRef

string | undefined

Returns

boolean

release()

release(material): void;

Drop one reference; at zero the material (and its textures) is disposed and evicted from the cache. Materials not handed out by acquire* are ignored.

Parameters

material

Material

Returns

void

resolve()

resolve(materialRef): Promise<Material<MaterialEventMap>>;

Async resolution for doc-backed refs; falls back to grey (with one warning) when the doc is missing/invalid so a bad ref never blanks the scene.

Parameters

materialRef

string

Returns

Promise<Material<MaterialEventMap>>

resolveSync()

resolveSync(materialRef): Material;

Sync resolution: palette refs (and the shared grey fallback for unknown/absent refs).

Parameters

materialRef

string | undefined

Returns

Material

---

Renderer

Thin wrapper over the three.js renderer + scene + camera. The engine owns the single construction path so capture settings (pixel ratio, AA, tone mapping) are deterministic. The backend option selects WebGPU or WebGL — see docs-src/guide/rendering-backends.md.

Constructors

Constructor

new Renderer(opts?, initialized?): Renderer;

Parameters

opts?

RendererOptions

initialized?

InitializedRenderer

Returns

Renderer

Properties

admission

readonly admission: FrameAdmissionQueue;

backend

readonly backend: RendererBackend;

camera

camera: PerspectiveCamera | OrthographicCamera;

defaultClearColor

readonly defaultClearColor: Color;

scene

readonly scene: Scene;

three

readonly three: ThreeRenderer;

worldRoot

readonly worldRoot: Group;

World-space objects live here so the renderer can rebase them near the camera.

Accessors

deviceLost

Get Signature

get deviceLost(): string | undefined;

The WebGPU device-loss reason once the device is gone (undefined while it is live). Every later render() throws, so a frame loop stops here instead of failing once per frame.

Returns

string | undefined

fallbackReason

Get Signature

get fallbackReason(): string | undefined;

Returns

string | undefined

sky

Get Signature

get sky(): SkyVisual | undefined;

Active clear-sky visual and sampled ephemeris, when environment.sky is configured.

Returns

SkyVisual | undefined

weather

Get Signature

get weather(): WeatherVisual | undefined;

Active weather effects; physical weather data is also available in the simulation component.

Returns

WeatherVisual | undefined

Methods

createGpuTimer()

createGpuTimer(options?): GpuFrameTimer | undefined;

Optional backend-specific GPU timing with the same nonblocking polling interface.

Parameters

options?

GpuFrameTimerOptions

Returns

GpuFrameTimer | undefined

createRenderGroup()

createRenderGroup(): Group;

Use for independent terrain/content chunks. WebGPU caches eligible opaque draw commands.

Returns

Group

dispose()

dispose(): void;

Returns

void

getViewportSize()

getViewportSize(): [number, number];

Drawing size in CSS pixels as last passed to setSize (before the pixel ratio).

Returns

[number, number]

getWorldOrigin()

getWorldOrigin(): Vec3;

Returns

Vec3

prepareObject()

prepareObject(
   root, 
   signal?, 
   parent?
): Promise<void>;

Prepare shared resources once; all dependants await the same admission jobs.

With parent (the object this root will be added to), LODs are evaluated for the current camera as if attached: the levels they select are prepared before this resolves, and the other levels afterwards in the background, so publication waits only for what can be seen. Queued work is cancelled once every caller waiting for it has aborted, and background work once its mesh or geometry is disposed.

Parameters

root

Object3D

signal?

AbortSignal

parent?

Object3D<Object3DEventMap>

Returns

Promise<void>

render()

render(): void;

Returns

void

setCamera()

setCamera(pose): void;

Pose the perspective camera (leaving top-down ortho mode if it was active).

Parameters

pose

CameraPose

Returns

void

setCameraClip()

setCameraClip(near, far): void;

Parameters

near

number

far

number

Returns

void

setEnvironmentTime()

setEnvironmentTime(seconds): void;

Absolute simulation seconds, shared by live playback, paused snapshots and captures.

Parameters

seconds

number

Returns

void

setEnvironmentTimeOverride()

setEnvironmentTimeOverride(seconds): void;

Preview a sky at absolute simulation seconds without seeking the world; undefined resumes its clock.

Parameters

seconds

number | undefined

Returns

void

setFov()

setFov(fovDeg): void;

Vertical field of view in degrees (perspective camera only; a no-op for ortho).

Parameters

fovDeg

number

Returns

void

setPixelRatio()

setPixelRatio(ratio): void;

Update the device pixel ratio after a display change. Three applies the ratio on the next setSize, so callers pair the two (the mount's resize handler does).

Parameters

ratio

number

Returns

void

setShadowFocus()

setShadowFocus(focus): void;

Aim the sun's shadow at a focus (absolute world coordinates) covering ±radius meters, or undefined for the environment's own fixed box. Call whenever what the camera frames moves: an orbit target, a walker, a car. Shadows must be on (setShadowQuality).

Parameters

focus

ShadowFocus | undefined

Returns

void

setShadowQuality()

setShadowQuality(quality): void;

Turn sun shadows on at a map resolution, or off, without rebuilding the environment.

Parameters

quality

ShadowQuality

Returns

void

setSize()

setSize(width, height): void;

Parameters

width

number

height

number

Returns

void

setStarCatalog()

setStarCatalog(stars): void;

Stars for every sky this renderer shows, e.g. decodeStarCatalog of a content pack's molen/stars@1 file. Applies to the current sky at once and survives sky changes; undefined removes the stars.

Parameters

stars

readonly SkyStar[] | undefined

Returns

void

setTopDownOrtho()

setTopDownOrtho(opts): void;

Switch to a top-down orthographic camera looking straight down at a world point.

Parameters

opts

TopDownOrtho

Returns

void

setWeather()

setWeather(data): void;

Apply the singleton weather component without rebuilding the sky or moving the camera.

Parameters

data

WeatherData | undefined

Returns

void

setWeatherTimeOverride()

setWeatherTimeOverride(seconds): void;

Standalone weather preview clock. Undefined follows simulation time, independently of sky seeks.

Parameters

seconds

number | undefined

Returns

void

setWorldOrigin()

setWorldOrigin(origin): void;

Shift all engine-owned world objects near the local origin without changing world poses.

Parameters

origin

Vec3

Returns

void

stats()

stats(): object;

Last completed visible frame, excluding offscreen resource preparation.

Returns

object

drawCalls

drawCalls: number;

triangles

triangles: number;

create()

static create(opts?): Promise<Renderer>;

Prefer WebGPU when available; explicit webgpu is strict and never silently falls back.

Parameters

opts?

RendererOptions

Returns

Promise<Renderer>

---

SceneMirror

Maintains a client-side mirror of kernel entities and reconciles renderable bindings against a SceneBackend (create / updateRenderable / destroy). Pure aside from the backend calls, so it is unit-testable with a mock backend.

Reconciliation is incremental: a delta marks the ids it touched dirty and reconcile visits only those (a keyframe forces a full pass), so a 1000-entity scene with one moving entity serializes one renderable per message, not a thousand.

Constructors

Constructor

new SceneMirror(): SceneMirror;

Returns

SceneMirror

Accessors

lastReconcileVisited

Get Signature

get lastReconcileVisited(): number;

How many entity ids the last reconcile examined (all of them after a keyframe).

Returns

number

tick

Get Signature

get tick(): number | undefined;

Returns

number | undefined

Methods

applyDelta()

applyDelta(delta): boolean;

Apply only a contiguous delta; false means the caller must request a fresh keyframe.

Parameters

delta

Delta

Returns

boolean

applyKeyframe()

applyKeyframe(keyframe): void;

Parameters

keyframe

Keyframe

Returns

void

boundIds()

boundIds(): string[];

Returns

string[]

components()

components(id): string[];

The component names an entity currently carries.

Parameters

id

string

Returns

string[]

entities()

entities(): string[];

Every mirrored entity id, in creation order.

Returns

string[]

get()

get(id, component): JsonObject | undefined;

A detached copy of one component of a mirrored entity (undefined when absent).

Parameters

id

string

component

string

Returns

JsonObject | undefined

has()

has(id): boolean;

Parameters

id

string

Returns

boolean

peek()

peek(id, component): JsonObject | undefined;

The stored component object (no copy) for renderers that sample every frame: treat it as frozen. Its identity changes exactly when a delta or keyframe replaced it.

Parameters

id

string

component

string

Returns

JsonObject | undefined

reconcile()

reconcile(backend): void;

Create/update/destroy backend objects so they match the mirror's renderables.

Parameters

backend

SceneBackend

Returns

void

transformChanges()

transformChanges(delta): Map<string, InterpTransform | undefined>;

Extract only transform changes (including removals), before reconciliation clears dirty ids.

Parameters

delta

Delta

Returns

Map<string, InterpTransform | undefined>

transforms()

transforms(): Map<string, InterpTransform>;

Extract the transforms present in the mirror (for the interpolation buffer).

Returns

Map<string, InterpTransform>

---

SkyReflections

One small half-float panorama and filtered target per viewer; no model-specific textures or network fetches. Quantization suppresses imperceptible ephemeris changes and camera motion never invalidates the map. Explicit host-assigned scene.environment textures take priority.

Constructors

Constructor

new SkyReflections(scene, filter): SkyReflections;

Parameters

scene

Scene

filter

SkyReflectionFilter

Returns

SkyReflections

Properties

texture

readonly texture: DataTexture;

Accessors

active

Get Signature

get active(): boolean;

False when a host has replaced the scene environment with its own texture.

Returns

boolean

Methods

dispose()

dispose(): void;

Returns

void

update()

update(state): boolean;

Parameters

state

SkyReflectionState

Returns

boolean

---

SkyVisual

Generic clear-sky dome, celestial spheres, batched stars and lighting, using standard materials on WebGL and WebGPU. A separate background scene avoids far-plane, reverse-depth, logarithmic-depth and floating-origin coupling. No textures, shaders or network requests.

Constructors

Constructor

new SkyVisual(data, options?): SkyVisual;

Parameters

data

SkyData

options?

SkyVisualOptions

Returns

SkyVisual

Properties

ambientLight

readonly ambientLight: HemisphereLight;

camera

readonly camera: PerspectiveCamera;

data

readonly data: SkyData;

lights

readonly lights: Group;

moonLight

readonly moonLight: DirectionalLight;

scene

readonly scene: Scene;

sunLight

readonly sunLight: DirectionalLight;

Accessors

frame

Get Signature

get frame(): SkyFrame;

Returns

SkyFrame

reflectionState

Get Signature

get reflectionState(): SkyReflectionState;

Sky radiance for the viewer's shared PBR environment, sampled with the celestial frame.

Returns

SkyReflectionState

Methods

dispose()

dispose(): void;

Returns

void

prepareCamera()

prepareCamera(camera): void;

Copy view orientation/projection only; celestial bodies never translate with the camera.

Parameters

camera

Camera

Returns

void

setCloudAttenuation()

setCloudAttenuation(value): void;

Diffuse cloud lighting; actual celestial occlusion comes from the cloud layer geometry.

Parameters

value

number

Returns

void

setObserver()

setObserver(observer): void;

Move an Earth observer without rebuilding the dome, bodies or star catalog.

Parameters

observer

EarthObserver

Returns

void

setStars()

setStars(stars): void;

Replace the star catalog, e.g. once a catalog loaded from a content pack arrives. undefined removes the stars. Takes effect on the next update.

Parameters

stars

readonly SkyStar[] | undefined

Returns

void

update()

update(simulationSeconds): SkyFrame;

Seek in simulation seconds. Earth render samples use a stable one-second UTC grid.

Parameters

simulationSeconds

number

Returns

SkyFrame

---

ThreeSceneBackend

three.js implementation of the SceneBackend: primitives + async glTF instances + lights.

Implements

• SceneBackend

Constructors

Constructor

new ThreeSceneBackend(
   scene, 
   assets?, 
   renderer?, 
   materials?, 
   optimization?
): ThreeSceneBackend;

Parameters

scene

Object3D

assets?

AssetCache

renderer?

Renderer

materials?

MaterialResolver

optimization?

SceneOptimizationOptions

Returns

ThreeSceneBackend

Accessors

threeScene

Get Signature

get threeScene(): Object3D;

The three.js world root this backend writes into (escape hatch for custom objects/lights).

Returns

Object3D

Methods

bindMirror()

bindMirror(reader): void;

Give custom kinds read access to the mirrored components (no per-frame cloning).

Parameters

reader

MirrorReader

Returns

void

count()

count(): number;

Returns

number

create()

create(id, renderable): void;

Parameters

id

string

renderable

Renderable

Returns

void

Implementation of

SceneBackend.create

createLight()

createLight(id, data): void;

Per-entity light components (directional/spot aim at the origin by default).

Parameters

id

string

data

LightData

Returns

void

Implementation of

SceneBackend.createLight

destroy()

destroy(id): void;

Parameters

id

string

Returns

void

Implementation of

SceneBackend.destroy

destroyLight()

destroyLight(id): void;

Parameters

id

string

Returns

void

Implementation of

SceneBackend.destroyLight

dispose()

dispose(): void;

Returns

void

entityForIntersection()

entityForIntersection(hit): string | undefined;

Parameters

hit

Intersection

Returns

string | undefined

getObject()

getObject(id): Object3D<Object3DEventMap> | undefined;

Escape hatch: the raw three.js object for an entity (undefined if not created), for advanced effects the wrapper doesn't cover. Unstable — you own whatever you mutate, and the backend may recreate the object when the renderable changes.

Parameters

id

string

Returns

Object3D<Object3DEventMap> | undefined

prepareFrame()

prepareFrame(): void;

Flush static membership only when bindings change; world-origin shifts move the common root.

Returns

void

registerKind()

registerKind(kind): void;

Register a custom renderable kind (capability client halves). Core kinds cannot be replaced.

Parameters

kind

RenderableKind

Returns

void

setAnimationTick()

setAnimationTick(tick, tickRate): void;

Live and capture poses use the same simulation tick and no wall-clock accumulation.

Parameters

tick

number

tickRate

number

Returns

void

setEnvironment()

setEnvironment(env): void;

The singleton environment component; undefined restores the default rig.

Parameters

env

Record<string, unknown> | undefined

Returns

void

Implementation of

SceneBackend.setEnvironment

setModelSignals()

setModelSignals(
   id, 
   spec, 
   signals
): void;

Latest mirrored values are retained while the model loads. No simulation state is changed.

Parameters

id

string

spec

ModelSignalSpec | undefined

signals

ModelSignals

Returns

void

Implementation of

SceneBackend.setModelSignals

setTransform()

setTransform(id, t): void;

Parameters

id

string

t

InterpTransform

Returns

void

Implementation of

SceneBackend.setTransform

setWeather()

setWeather(weather): void;

Physical and visual weather singleton; independent of environment/sky configuration.

Parameters

weather

Record<string, unknown> | undefined

Returns

void

Implementation of

SceneBackend.setWeather

tickAnimations()

tickAnimations(dtSec): void;

Standalone preview clock; connected clients use setAnimationTick with the kernel clock.

Parameters

dtSec

number

Returns

void

updateLight()

updateLight(id, data): void;

Parameters

id

string

data

LightData

Returns

void

Implementation of

SceneBackend.updateLight

updateLiveAnimations()

updateLiveAnimations(
   tick, 
   tickRate, 
   camera
): void;

Exact tick-derived poses on return to view; invisible shadow casters are never skipped.

Parameters

tick

number

tickRate

number

camera

Camera

Returns

void

updateRenderable()

updateRenderable(id, renderable): void;

Parameters

id

string

renderable

Renderable

Returns

void

Implementation of

SceneBackend.updateRenderable

whenReady()

whenReady(): Promise<void>;

Returns

Promise<void>

---

WeatherVisual

Lightweight layered clouds and local precipitation with standard materials on both graphics backends. Patterns are seeded and sampled at absolute simulation time, not integrated frames. Cloud layers use absolute world altitudes; particles are visual and do not accumulate or collide.

Constructors

Constructor

new WeatherVisual(data): WeatherVisual;

Parameters

data

WeatherData

Returns

WeatherVisual

Properties

fog

readonly fog: Fog;

object

readonly object: Group;

Accessors

cloudAttenuation

Get Signature

get cloudAttenuation(): number;

Returns

number

data

Get Signature

get data(): ResolvedWeather;

Resolved copy; editing it does not change the visual.

Returns

ResolvedWeather

stats

Get Signature

get stats(): object;

Returns

object

cloudLayers

cloudLayers: number;

particles

particles: number;

Methods

dispose()

dispose(): void;

Returns

void

fogFor()

fogFor(base, sky?): Fog | FogExp2;

Combine weather visibility with an authored/streaming fog limit without mutating it.

Parameters

base

Fog | FogExp2 | null

sky?

SkyFrame

Returns

Fog | FogExp2

setData()

setData(data): void;

Replace weather while retaining geometry, particles and cached noise.

Parameters

data

WeatherData

Returns

void

update()

update(
   seconds, 
   camera, 
   origin, 
   sky?
): void;

Update camera-relative geometry using the renderer's absolute floating origin.

Parameters

seconds

number

camera

Camera

origin

Vec3

sky?

SkyFrame

Returns

void

Interfaces

AdaptiveQualityChange

Properties

level

level: number;

previousLevel

previousLevel: number;

reason

reason: AdaptiveQualityReason;

---

AdaptiveQualityOptions

Properties

cooldownMs?

optional cooldownMs?: number;

decreaseDelayMs?

optional decreaseDelayMs?: number;

Sustained overload before stepping down; memory pressure bypasses this delay.

evaluationIntervalMs?

optional evaluationIntervalMs?: number;

Measurements are evaluated in windows; frame samples alone never change quality.

increaseDelayMs?

optional increaseDelayMs?: number;

Stable headroom before probing one higher level. Failed probes increase this delay.

initialLevel?

optional initialLevel?: number;

maxLevel?

optional maxLevel?: number;

minLevel?

optional minLevel?: number;

Integer detail levels increase with quality. The host maps them to its own budgets.

pauseFrameMs?

optional pauseFrameMs?: number;

An isolated longer interval is treated as a pause; repeated ones remain overload.

targetFrameMs?

optional targetFrameMs?: number;

warmupMs?

optional warmupMs?: number;

---

AdaptiveQualitySample

Properties

active?

optional active?: boolean;

False while hidden, suspended, or deliberately not rendering. Resets measurement history.

cpuFrameMs?

optional cpuFrameMs?: number;

Optional measured work, excluding waiting for the next animation frame.

gpuFrameMs?

optional gpuFrameMs?: number;

Supply only a completed, valid asynchronous GPU timing query.

loading?

optional loading?: boolean;

Loading never authorizes an upgrade. With CPU/GPU work measurements it lowers detail only when that work itself is heavy; otherwise sustained overload while loading still lowers it.

memoryPressure?

optional memoryPressure?: number;

Estimated resident working set / memory budget. Values above one lower detail.

---

AdaptiveQualityStats

Properties

changes

changes: number;

level

level: number;

p90FrameMs

p90FrameMs: number | undefined;

reason

reason: AdaptiveQualityReason | undefined;

recoveryDelayMs

recoveryDelayMs: number;

samples

samples: number;

Valid samples in the most recently completed measurement window.

slowFrameRatio

slowFrameRatio: number;

smoothedFrameMs

smoothedFrameMs: number | undefined;

Exponentially smoothed, trimmed frame time; undefined before the first complete window.

targetFrameMs

targetFrameMs: number;

---

AdmissionOptions

Shared main-thread work queue. A job is indivisible; oversize jobs run alone and are reported.

Properties

bytes?

optional bytes?: number;

label?

optional label?: string;

priority?

optional priority?: "normal" | "background";

Background jobs run only in frame budget that no normal job is waiting for.

signal?

optional signal?: AbortSignal;

---

AdmissionSample

Properties

background

background: boolean;

Ran from the background lane, so its queue time was deliberately deferred.

bytes

bytes: number;

label

label: string;

overBudget

overBudget: boolean;

queueMs

queueMs: number;

workMs

workMs: number;

---

AssetOptions

Properties

baseUrl?

optional baseUrl?: string;

Base URL asset refs resolve against (default: the page origin).

index?

optional index?: Record<string, string>;

Asset id -> served URL index (from the project manifest); ids without an entry use the assets/<id>/model.glb convention.

provider?

optional provider?: AssetProvider;

Bring-your-own provider (overrides baseUrl/index).

variant?

optional variant?: string;

Packed runtime variant to prefer for convention-resolved ids (e.g. "ktx2"); pair it with decoders.ktx2TranscoderPath. Falls back to model.glb per asset when the variant is missing.

---

AssetProvider

Resolves asset refs to bytes. Refs are project asset ids ("crate"); refs containing "/" or starting with "./" / "http(s):" pass through as URLs, so manifest-less demos stay trivial.

Methods

load()

load(ref): Promise<ArrayBuffer>;

Parameters

ref

string

Returns

Promise&lt;ArrayBuffer&gt;

loadText()

loadText(ref): Promise<string>;

Parameters

ref

string

Returns

Promise&lt;string&gt;

---

AutoWorldOriginOptions

Properties

gridSize?

optional gridSize?: number;

Snap the new origin to this grid size; omitted means use the exact camera position.

includeY?

optional includeY?: boolean;

Include vertical movement in the threshold and new origin. Defaults to horizontal XZ only.

threshold

threshold: number;

Rebase after the camera moves farther than this world-space distance from the current origin.

---

CameraPose

Properties

lookAt?

optional lookAt?: Vec3;

Either a look-at target or an explicit rotation quaternion.

position

position: Vec3;

rotation?

optional rotation?: Quat;

---

CameraTarget

The renderer surface applySceneCamera needs (satisfied by Renderer).

Methods

setCamera()

setCamera(pose): void;

Parameters

pose

CameraPose

Returns

void

setFov()

setFov(fovDeg): void;

Parameters

fovDeg

number

Returns

void

setTopDownOrtho()

setTopDownOrtho(opts): void;

Parameters

opts

TopDownOrtho

Returns

void

---

CelestialPosition

Properties

altitudeDeg

altitudeDeg: number;

Geometric topocentric altitude; no atmospheric refraction.

angularDiameterDeg

angularDiameterDeg: number;

azimuthDeg

azimuthDeg: number;

Clockwise from geographic north, before northOffsetDeg.

direction

direction: Vec3;

Unit vector toward the body; Y-up, default +X east / -Z north.

distanceKm

distanceKm: number;

---

ClientCore

Properties

buffer

readonly buffer: InterpolationBuffer | undefined;

The interpolation buffer, once the first keyframe/ready message fixed the tick rate.

mirror

readonly mirror: SceneMirror;

tick

readonly tick: number | undefined;

The latest kernel tick applied to the mirror.

Methods

command()

command(type, payload?): void;

Send a command by type + payload; the envelope is filled (seq, source: 'local').

Parameters

type

string

payload?

JsonValue

Returns

void

control()

control(action): void;

Drive the kernel's scheduler: pause, resume, step a fixed number of ticks, set-rate, or request-keyframe. Pairs with the host's startPaused option — a page that boots paused resumes once its assets are in, so nothing simulates behind a loading screen.

Parameters

action

ControlAction

Returns

void

dispose()

dispose(): void;

Unhook the link and clear the buffer.

Returns

void

entities()

entities(): string[];

Every mirrored entity id (creation order).

Returns

string[]

get()

get(id, component): JsonObject | undefined;

Read a component of a mirrored entity (a detached copy).

Parameters

id

string

component

string

Returns

JsonObject | undefined

onDiag()

onDiag(cb): Unsubscribe;

Subscribe to kernel diagnostics (tick overruns, rejected commands, protocol errors). Codes the client does not know are delivered as they arrive rather than dropped, so a newer kernel's diagnostics reach an older page.

Parameters

cb

(diag) => void

Returns

Unsubscribe

onError()

onError(cb): Unsubscribe;

Subscribe to client-side failures: a dead or throwing kernel link, and frame-loop exceptions. Without this a crashed Worker is invisible — the page keeps rendering its last pose while every command() posts into nothing.

Parameters

cb

(error) => void

Returns

Unsubscribe

onEvent()

onEvent(type, cb): Unsubscribe;

Subscribe to kernel events by type, or '*' for all. Exact-type handlers run first.

Parameters

type

string

cb

(event, tick) => void

Returns

Unsubscribe

reportError()

reportError(error): void;

Push a failure through the error + diag channels (the frame loop and custom backends use it).

Parameters

error

ClientError

Returns

void

sampleTransforms()

sampleTransforms(nowMs, apply): void;

Sample every interpolated transform for nowMs into the backend (or any consumer).

Parameters

nowMs

number

apply

(id, t) => void

Returns

void

sendCommand()

sendCommand(command): void;

Parameters

command

Command

Returns

void

---

ClientCoreOptions

Properties

backend

backend: SceneBackend;

interpolationDelayTicks?

optional interpolationDelayTicks?: number;

link

link: MessageLink;

now?

optional now?: () => number;

Wall clock in ms (default performance.now / Date.now); injectable for tests.

Returns

number

---

ClientError

A failure the page has to see. link is the kernel side going away or misbehaving (an uncaught throw in the Worker, a script that fails to load, an undeserializable message); frame is an exception out of the client's own render frame. Both also reach onDiag as a ClientDiagCode diagnostic, so a page that only wired diagnostics still learns its kernel is dead.

Properties

cause?

optional cause?: unknown;

The ErrorEvent/MessageEvent or thrown value behind it, when there was one.

message

message: string;

Human-readable summary, already including the underlying message where one was available.

source

source: "link" | "frame";

---

ClientOptions

Extends

• RendererOptions

Extended by

• MountExperienceOptions

Properties

admission?

optional admission?: FrameAdmissionOptions;

Inherited from

RendererOptions.admission

antialias?

optional antialias?: boolean;

Inherited from

RendererOptions.antialias

assets?

optional assets?: AssetOptions;

Enable gltf renderables: where asset refs load from.

autoWorldOrigin?

optional autoWorldOrigin?: AutoWorldOriginOptions;

Optional automatic large-world origin rebasing driven by camera movement.

Inherited from

RendererOptions.autoWorldOrigin

backend?

optional backend?: RendererBackendPreference;

Which graphics backend to use. Defaults to 'auto': probe WebGPU, fall back to WebGL. 'webgl' skips the probe entirely — pin it when the pixels must be reproducible. 'webgpu' is strict and never silently falls back.

Inherited from

RendererOptions.backend

backendProbeTimeoutMs?

optional backendProbeTimeoutMs?: number;

How long the WebGPU probe may take before 'auto' gives up and uses WebGL (default 5000ms; 0 or Infinity waits forever). A context can advertise navigator.gpu and then never settle its initialization — headless software rendering does exactly this — and without a bound the page hangs with no error rather than falling back. 'webgpu' rejects on timeout instead.

Inherited from

RendererOptions.backendProbeTimeoutMs

cameraFar?

optional cameraFar?: number;

Inherited from

RendererOptions.cameraFar

cameraNear?

optional cameraNear?: number;

Inherited from

RendererOptions.cameraNear

canvas?

optional canvas?: HTMLCanvasElement | OffscreenCanvas;

Inherited from

RendererOptions.canvas

clearColor?

optional clearColor?: string;

Background clear color, default a mid grey.

Inherited from

RendererOptions.clearColor

decoders?

optional decoders?: DecoderConfig;

Optional Draco/KTX2 decoder hosting (canonical imported assets need neither).

frameLoop?

optional frameLoop?: "manual" | "auto";

height?

optional height?: number;

Inherited from

RendererOptions.height

interpolationDelayTicks?

optional interpolationDelayTicks?: number;

kinds?

optional kinds?: RenderableKind[];

Custom renderable kinds from capability client halves (e.g. figures).

logarithmicDepthBuffer?

optional logarithmicDepthBuffer?: boolean;

Compatibility fallback for large view ranges; costs early-fragment performance.

Inherited from

RendererOptions.logarithmicDepthBuffer

materialBaker?

optional materialBaker?: MaterialBaker;

Optional caller-owned worker pool for procedural textures.

onDeviceLost?

optional onDeviceLost?: (reason) => void;

Device loss requires a new viewer/canvas. Auto fallback applies during initialization.

Parameters

reason

string

Returns

void

Inherited from

RendererOptions.onDeviceLost

optimizeWebGpu?

optional optimizeWebGpu?: boolean;

Persistent instance buffers and managed tile command caches. Defaults to true on WebGPU.

Inherited from

RendererOptions.optimizeWebGpu

pixelRatio?

optional pixelRatio?: number;

Inherited from

RendererOptions.pixelRatio

powerPreference?

optional powerPreference?: "default" | "high-performance" | "low-power";

Inherited from

RendererOptions.powerPreference

preserveDrawingBuffer?

optional preserveDrawingBuffer?: boolean;

WebGL only. WebGPU presentation does not preserve the drawing buffer between frames.

Inherited from

RendererOptions.preserveDrawingBuffer

reflections?

optional reflections?: boolean;

Shared procedural sky/ground reflections for PBR materials. Default false; Earth viewers enable it.

Inherited from

RendererOptions.reflections

releaseContextOnDispose?

optional releaseContextOnDispose?: boolean;

WebGL only: dispose() also releases the GL context (forceContextLoss). Browsers cap live contexts per page (Chromium keeps 16), so a single-page host that mounts and unmounts viewers should enable this; each mount then needs a fresh canvas, because a lost context stays attached to its canvas. Default false keeps a canvas reusable after dispose.

Inherited from

RendererOptions.releaseContextOnDispose

reverseDepthBuffer?

optional reverseDepthBuffer?: boolean;

Better depth precision for large view ranges; WebGL uses logarithmic depth if EXT_clip_control is unavailable.

Inherited from

RendererOptions.reverseDepthBuffer

sceneCamera?

optional sceneCamera?: SceneCamera;

Declarative camera; follow targets use the same interpolation as rendered entities.

sceneOptimization?

optional sceneOptimization?: SceneOptimizationOptions;

signal?

optional signal?: AbortSignal;

Cancels a mount in flight (createClient, createSnapshotViewer, createViewer, mountExperience): if it aborts while the GPU is initializing the factory rejects with an AbortError and nothing is left running. A host that unmounts mid-mount (React StrictMode's double-invoked effect) otherwise leaks a live client on the same canvas. Every factory is asynchronous, so every mount can be cancelled.

stars?

optional stars?: readonly SkyStar[];

Stars for every sky, e.g. decodeStarCatalog of the molen.sky content pack's stars.bin. Without a catalog, skies show no stars; setStarCatalog supplies one later.

Inherited from

RendererOptions.stars

width?

optional width?: number;

Inherited from

RendererOptions.width

---

CustomSkyData

Extends

• 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;

Inherited from

SkyAppearance.lighting

mode

mode: "custom";

moon?

optional moon?: object;

earthshine?

optional earthshine?: number;

size?

optional size?: number;

visible?

optional visible?: boolean;

Inherited from

SkyAppearance.moon

moonBody?

optional moonBody?: SkyBodyData;

palette?

optional palette?: SkyPalette;

Inherited from

SkyAppearance.palette

starRotationDeg?

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

stars?

optional stars?: object;

enabled?

optional enabled?: boolean;

intensity?

optional intensity?: number;

magnitudeLimit?

optional magnitudeLimit?: number;

size?

optional size?: number;

Inherited from

SkyAppearance.stars

sun?

optional sun?: object;

size?

optional size?: number;

visible?

optional visible?: boolean;

Inherited from

SkyAppearance.sun

sunBody

sunBody: SkyBodyData;

---

DecoderConfig

Properties

dracoDecoderPath?

optional dracoDecoderPath?: string;

Hosted Draco decoder dir (e.g. "/decoders/draco/"); omit if assets are meshopt-canonical.

ktx2TranscoderPath?

optional ktx2TranscoderPath?: string;

Hosted Basis transcoder dir for KTX2 textures; omit when not using KTX2.

---

EarthObserver

Properties

elevation?

optional elevation?: number;

latitude

latitude: number;

longitude

longitude: number;

northOffsetDeg?

optional northOffsetDeg?: number;

---

EarthSkyData

Extends

• 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;

Inherited from

SkyAppearance.lighting

mode

mode: "earth";

moon?

optional moon?: object;

earthshine?

optional earthshine?: number;

size?

optional size?: number;

visible?

optional visible?: boolean;

Inherited from

SkyAppearance.moon

observer

observer: EarthObserver;

palette?

optional palette?: SkyPalette;

Inherited from

SkyAppearance.palette

stars?

optional stars?: object;

enabled?

optional enabled?: boolean;

intensity?

optional intensity?: number;

magnitudeLimit?

optional magnitudeLimit?: number;

size?

optional size?: number;

Inherited from

SkyAppearance.stars

sun?

optional sun?: object;

size?

optional size?: number;

visible?

optional visible?: boolean;

Inherited from

SkyAppearance.sun

time

time: SkyTime;

---

EarthSkyState

Properties

julianDate

julianDate: number;

moon

moon: CelestialPosition & object;

Type Declaration

illuminatedFraction

illuminatedFraction: number;

phase

phase: number;

starBasis

starBasis: [Vec3, Vec3, Vec3];

Columns transforming J2000 equatorial Cartesian coordinates into the local world.

sun

sun: CelestialPosition;

utcMs

utcMs: number;

---

EnvironmentData

Mirrors the schema environment component (loose; all fields optional).

Properties

ambient?

optional ambient?: object;

ground?

optional ground?: string;

intensity?

optional intensity?: number;

sky?

optional sky?: string;

background?

optional background?: string;

exposure?

optional exposure?: number;

fog?

optional fog?: object;

color

color: string;

far?

optional far?: number;

near?

optional near?: number;

shadows?

optional shadows?: "off" | "low" | "medium" | "high";

sky?

optional sky?: SkyData;

Earth or authored clear sky. Owns ambient/sun/moon lights when present.

sun?

optional sun?: object;

castShadow?

optional castShadow?: boolean;

color?

optional color?: string;

direction?

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

intensity?

optional intensity?: number;

toneMapping?

optional toneMapping?: "none" | "aces" | "agx";

---

FrameAdmissionOptions

Properties

maxBytes?

optional maxBytes?: number;

maxJobs?

optional maxJobs?: number;

maxMilliseconds?

optional maxMilliseconds?: number;

now?

optional now?: () => number;

Returns

number

onSample?

optional onSample?: (sample) => void;

Parameters

sample

AdmissionSample

Returns

void

schedule?

optional schedule?: (callback) => void;

Parameters

callback

() => void

Returns

void

---

GpuFrameTimer

Methods

begin()

begin(): boolean;

Returns false when unsupported, busy, suspended, or this frame is not sampled.

Returns

boolean

dispose()

dispose(): void;

Returns

void

end()

end(): void;

Finish the measurement started by begin(); safe when begin() returned false.

Returns

void

poll()

poll(): number | undefined;

Poll once per animation frame. Returns the latest completed valid duration in milliseconds.

Returns

number | undefined

---

GpuFrameTimerOptions

Properties

maxPendingQueries?

optional maxPendingQueries?: number;

Maximum outstanding queries, including an active measurement. Default 4.

sampleEveryFrames?

optional sampleEveryFrames?: number;

Sample one frame out of this many to limit instrumentation overhead. Default 4.

---

InputBindings

Properties

bindings

bindings: Record<string, string>;

---

InputGamepad

Structural Gamepad API snapshot; also usable by custom device adapters and tests.

Properties

axes

axes: readonly number[];

buttons

buttons: readonly object[];

connected

connected: boolean;

id

id: string;

index

index: number;

mapping

mapping: string;

---

InputMapOptions

Extends

• InputProfile

Properties

axes?

optional axes?: GamepadAxisBinding[];

Inherited from

InputProfile.axes

bindings

bindings: Record<string, string>;

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

Inherited from

InputProfile.bindings

buttons?

optional buttons?: GamepadButtonBinding[];

Inherited from

InputProfile.buttons

getGamepads?

optional getGamepads?: () => readonly (InputGamepad | null)[];

Defaults to navigator.getGamepads. Inject an adapter for other browser facilities.

Returns

readonly (InputGamepad | null)[]

profile?

optional profile?: string;

profiles?

optional profiles?: Record<string, InputProfile>;

target?

optional target?: EventTargetLike;

Event source (usually window); injectable for tests.

---

InputRuleOptions

Properties

pollMs?

optional pollMs?: number;

How often controllers and numeric rules are polled (ms). Default 50.

timer?

optional timer?: object;

Injectable timer (setInterval/clearInterval shape) for tests.

clear()

clear(handle): void;

Parameters

handle

unknown

Returns

void

set()

set(fn, ms): unknown;

Parameters

fn

() => void

ms

number

Returns

unknown

---

InterpTransform

Properties

pos

pos: Vec3;

rot

rot: Quat;

scale?

optional scale?: Vec3;

teleport?

optional teleport?: boolean;

When true, the renderer snaps to this transform instead of interpolating into it.

---

KindContext

Properties

assets

readonly assets: AssetCache | undefined;

materials

readonly materials: MaterialResolver;

mirror

readonly mirror: MirrorReader | undefined;

Mirrored components (bound once the client connects; undefined in bare viewers).

renderer

readonly renderer: Renderer | undefined;

scene

readonly scene: Object3D;

The world root the entity object lives under (floating origin included).

Methods

track()

track<T>(promise): Promise<T>;

Register async work the capture barrier (client.ready()) must wait for.

Type Parameters

T

T

Parameters

promise

Promise&lt;T&gt;

Returns

Promise&lt;T&gt;

warn()

warn(message): void;

Parameters

message

string

Returns

void

---

KindHandle

Properties

object

readonly object: Object3D;

The entity's root object; the backend names it, adds it to the scene and drives its transform.

Methods

dispose()

dispose(): void;

Returns

void

setTick()?

optional setTick(
   tick, 
   tickRate, 
   view
): void;

Sample the entity's pose at a simulation tick (fractional on the live path). view is undefined on the capture path: exact tick, full detail, no throttling.

Parameters

tick

number

tickRate

number

view

KindView | undefined

Returns

void

update()

update(renderable): void;

The renderable changed without changing identity.

Parameters

renderable

Renderable

Returns

void

---

KindView

What the live frame loop knows about an entity when it samples its pose.

Properties

distance

distance: number;

Distance from the camera to the entity origin, meters.

distantDistance

distantDistance: number;

The configured near/far animation distance.

inView

inView: boolean;

shadows

shadows: boolean;

Whether any mesh of the entity casts shadows (never throttled).

---

LightData

A light source component at the entity transform (mirrors the schema light component).

Properties

angleDeg?

optional angleDeg?: number;

castShadow?

optional castShadow?: boolean;

color?

optional color?: string;

intensity?

optional intensity?: number;

penumbra?

optional penumbra?: number;

range?

optional range?: number;

type

type: "directional" | "point" | "spot";

---

LoadedGltf

Properties

clips

clips: AnimationClip[];

scene

scene: Group;

---

MirrorReader

Read-only view of the client's mirrored components, without per-frame cloning.

Properties

tick

readonly tick: number | undefined;

Methods

peek()

peek(id, component): JsonObject | undefined;

The stored component object, not a copy: treat it as frozen. Its identity changes exactly when a delta or keyframe replaced it, so peek(...) !== last is a free change test.

Parameters

id

string

component

string

Returns

JsonObject | undefined

---

ModelSignalVisual

Properties

missingNodes

readonly missingNodes: readonly string[];

Methods

reset()

reset(): void;

Restore authored transforms before removing or replacing bindings.

Returns

void

update()

update(signals): void;

Parameters

signals

ModelSignals

Returns

void

---

MolenClient

Properties

backend

readonly backend: ThreeSceneBackend;

The three.js scene backend driving this client (escape hatch: getObject, threeScene, registerKind). Unstable, like everything else you reach through it.

renderer

readonly renderer: Renderer;

tick

readonly tick: number | undefined;

The latest kernel tick applied (undefined before the first keyframe).

Methods

command()

command(type, payload?): void;

Send a command by type + payload; the client fills the envelope (seq auto-increments, source: 'local', tick: 0 — the kernel rewrites late ticks to the next tick).

Parameters

type

string

payload?

JsonValue

Returns

void

control()

control(action): void;

Drive the kernel's scheduler: {action: 'resume'} after a startPaused host, 'pause', 'step' a fixed number of ticks, 'set-rate', or 'request-keyframe'. A page that boots its worker paused and resumes on ready() never simulates behind its own loading screen, and a test that steps instead of waiting is independent of wall-clock speed. No-op on a snapshot viewer, which has no kernel.

Parameters

action

ControlAction

Returns

void

dispose()

dispose(): void;

Returns

void

entities()

entities(): string[];

Every mirrored entity id.

Returns

string[]

entityForIntersection()

entityForIntersection(hit): string | undefined;

Resolve a Three ray hit to its entity, including static instanced meshes.

Parameters

hit

Intersection

Returns

string | undefined

get()

get(id, component): JsonObject | undefined;

Read a component of a mirrored entity — a HUD's data source (a detached copy).

Parameters

id

string

component

string

Returns

JsonObject | undefined

getObject()

getObject(id): Object3D<Object3DEventMap> | undefined;

Escape hatch: the raw three.js object for an entity (undefined when it has none yet). Taking it un-batches the entity from any static batch and marks it escaped, so edits you make stay visible — renderer.worldRoot.getObjectByName(id) skips that and hands back a hidden original.

Parameters

id

string

Returns

Object3D&lt;Object3DEventMap&gt; | undefined

objectCount()

objectCount(): number;

Number of bound scene objects (for stats/tests).

Returns

number

onDiag()

onDiag(cb): Unsubscribe;

Subscribe to kernel diagnostics (tick overruns, rejected commands, protocol errors).

Parameters

cb

(diag) => void

Returns

Unsubscribe

onError()

onError(cb): Unsubscribe;

Subscribe to client-side failures the kernel cannot report: the link died (source: 'link' — the Worker threw, failed to load, or sent an undeserializable message) or a render frame threw (source: 'frame'). Each also arrives on onDiag as link-error / frame-error.

Parameters

cb

(error) => void

Returns

Unsubscribe

onEvent()

onEvent(type, cb): Unsubscribe;

Subscribe to kernel events by type, or '*' for all (gameplay feedback: hits, pickups, win/lose, command-rejected). Handlers get the event and the tick it happened on.

Parameters

type

string

cb

(event, tick) => void

Returns

Unsubscribe

ready()

ready(): Promise<void>;

Resolves when all pending asset loads have settled (capture/testing barrier).

Returns

Promise&lt;void&gt;

renderFrame()

renderFrame(nowMs?): void;

Parameters

nowMs?

number

Returns

void

sendCommand()

sendCommand(command): void;

Parameters

command

Command

Returns

void

setCamera()

setCamera(pose): void;

Override the declarative camera, disabling automatic follow tracking.

Parameters

pose

CameraPose

Returns

void

---

MountedExperience

Properties

client

client: MolenClient;

input

input: InputMap | undefined;

The InputMap driving the scene's emit rules (undefined when the scene has no input block).

Methods

dispose()

dispose(): void;

Returns

void

---

MountExperienceOptions

Extends

• ClientOptions

Properties

admission?

optional admission?: FrameAdmissionOptions;

Inherited from

ClientOptions.admission

antialias?

optional antialias?: boolean;

Inherited from

ClientOptions.antialias

assets?

optional assets?: AssetOptions;

Enable gltf renderables: where asset refs load from.

Inherited from

ClientOptions.assets

autoResize?

optional autoResize?: boolean;

Follow the canvas's client size on window resize (default true when window exists).

autoWorldOrigin?

optional autoWorldOrigin?: AutoWorldOriginOptions;

Optional automatic large-world origin rebasing driven by camera movement.

Inherited from

ClientOptions.autoWorldOrigin

backend?

optional backend?: RendererBackendPreference;

Which graphics backend to use. Defaults to 'auto': probe WebGPU, fall back to WebGL. 'webgl' skips the probe entirely — pin it when the pixels must be reproducible. 'webgpu' is strict and never silently falls back.

Inherited from

ClientOptions.backend

backendProbeTimeoutMs?

optional backendProbeTimeoutMs?: number;

How long the WebGPU probe may take before 'auto' gives up and uses WebGL (default 5000ms; 0 or Infinity waits forever). A context can advertise navigator.gpu and then never settle its initialization — headless software rendering does exactly this — and without a bound the page hangs with no error rather than falling back. 'webgpu' rejects on timeout instead.

Inherited from

ClientOptions.backendProbeTimeoutMs

cameraFar?

optional cameraFar?: number;

Inherited from

ClientOptions.cameraFar

cameraNear?

optional cameraNear?: number;

Inherited from

ClientOptions.cameraNear

canvas

canvas: HTMLCanvasElement;

Overrides

ClientOptions.canvas

clearColor?

optional clearColor?: string;

Background clear color, default a mid grey.

Inherited from

ClientOptions.clearColor

decoders?

optional decoders?: DecoderConfig;

Optional Draco/KTX2 decoder hosting (canonical imported assets need neither).

Inherited from

ClientOptions.decoders

frameLoop?

optional frameLoop?: "manual" | "auto";

Inherited from

ClientOptions.frameLoop

height?

optional height?: number;

Inherited from

ClientOptions.height

inputTarget?

optional inputTarget?: EventTargetLike;

Where key/mouse events come from (default: window).

interpolationDelayTicks?

optional interpolationDelayTicks?: number;

Inherited from

ClientOptions.interpolationDelayTicks

kinds?

optional kinds?: RenderableKind[];

Custom renderable kinds from capability client halves (e.g. figures).

Inherited from

ClientOptions.kinds

link

link: MessageLink;

The kernel link (a Worker running KernelHost, or a MessagePort). Built by the host.

logarithmicDepthBuffer?

optional logarithmicDepthBuffer?: boolean;

Compatibility fallback for large view ranges; costs early-fragment performance.

Inherited from

ClientOptions.logarithmicDepthBuffer

materialBaker?

optional materialBaker?: MaterialBaker;

Optional caller-owned worker pool for procedural textures.

Inherited from

ClientOptions.materialBaker

onDeviceLost?

optional onDeviceLost?: (reason) => void;

Device loss requires a new viewer/canvas. Auto fallback applies during initialization.

Parameters

reason

string

Returns

void

Inherited from

ClientOptions.onDeviceLost

optimizeWebGpu?

optional optimizeWebGpu?: boolean;

Persistent instance buffers and managed tile command caches. Defaults to true on WebGPU.

Inherited from

ClientOptions.optimizeWebGpu

pixelRatio?

optional pixelRatio?: number;

Inherited from

ClientOptions.pixelRatio

pollMs?

optional pollMs?: number;

Controller/numeric input poll interval in ms (default 50).

powerPreference?

optional powerPreference?: "default" | "high-performance" | "low-power";

Inherited from

ClientOptions.powerPreference

preserveDrawingBuffer?

optional preserveDrawingBuffer?: boolean;

WebGL only. WebGPU presentation does not preserve the drawing buffer between frames.

Inherited from

ClientOptions.preserveDrawingBuffer

reflections?

optional reflections?: boolean;

Shared procedural sky/ground reflections for PBR materials. Default false; Earth viewers enable it.

Inherited from

ClientOptions.reflections

releaseContextOnDispose?

optional releaseContextOnDispose?: boolean;

WebGL only: dispose() also releases the GL context (forceContextLoss). Browsers cap live contexts per page (Chromium keeps 16), so a single-page host that mounts and unmounts viewers should enable this; each mount then needs a fresh canvas, because a lost context stays attached to its canvas. Default false keeps a canvas reusable after dispose.

Inherited from

ClientOptions.releaseContextOnDispose

reverseDepthBuffer?

optional reverseDepthBuffer?: boolean;

Better depth precision for large view ranges; WebGL uses logarithmic depth if EXT_clip_control is unavailable.

Inherited from

ClientOptions.reverseDepthBuffer

scene

scene: SceneManifest;

The validated scene manifest; its camera and input blocks are applied.

sceneCamera?

optional sceneCamera?: SceneCamera;

Declarative camera; follow targets use the same interpolation as rendered entities.

Inherited from

ClientOptions.sceneCamera

sceneOptimization?

optional sceneOptimization?: SceneOptimizationOptions;

Inherited from

ClientOptions.sceneOptimization

signal?

optional signal?: AbortSignal;

Cancels a mount in flight (createClient, createSnapshotViewer, createViewer, mountExperience): if it aborts while the GPU is initializing the factory rejects with an AbortError and nothing is left running. A host that unmounts mid-mount (React StrictMode's double-invoked effect) otherwise leaks a live client on the same canvas. Every factory is asynchronous, so every mount can be cancelled.

Inherited from

ClientOptions.signal

stars?

optional stars?: readonly SkyStar[];

Stars for every sky, e.g. decodeStarCatalog of the molen.sky content pack's stars.bin. Without a catalog, skies show no stars; setStarCatalog supplies one later.

Inherited from

ClientOptions.stars

width?

optional width?: number;

Inherited from

ClientOptions.width

---

Renderable

The render contract component (docs-src/schemas/components.md, renderable).

Properties

animation?

optional animation?: object;

gltf clip playback; clip time derives deterministically from startTick in captures.

clip

clip: string;

loop?

optional loop?: "repeat" | "once" | "pingpong";

paused?

optional paused?: boolean;

pausedAtTick?

optional pausedAtTick?: number;

speed?

optional speed?: number;

startTick?

optional startTick?: number;

kind

kind: "primitive" | "gltf" | string & object;

materialRef?

optional materialRef?: string;

node?

optional node?: string;

gltf: named sub-node to instance (default: the whole scene).

primitive?

optional primitive?: object;

size?

optional size?: Vec3;

ref

ref: string;

shadows?

optional shadows?: object;

cast?

optional cast?: boolean;

receive?

optional receive?: boolean;

visible?

optional visible?: boolean;

---

RenderableKind

Properties

kind

readonly kind: string;

Methods

create()

create(
   id, 
   renderable, 
   ctx
): KindHandle;

Parameters

id

string

renderable

Renderable

ctx

KindContext

Returns

KindHandle

dispose()?

optional dispose(): void;

Release kind-level shared resources (geometry caches, materials).

Returns

void

identity()

identity(renderable): string;

The identity part of a renderable: a change rebuilds the object, otherwise update runs.

Parameters

renderable

Renderable

Returns

string

---

RendererOptions

Extended by

• ClientOptions

Properties

admission?

optional admission?: FrameAdmissionOptions;

antialias?

optional antialias?: boolean;

autoWorldOrigin?

optional autoWorldOrigin?: AutoWorldOriginOptions;

Optional automatic large-world origin rebasing driven by camera movement.

backend?

optional backend?: RendererBackendPreference;

Which graphics backend to use. Defaults to 'auto': probe WebGPU, fall back to WebGL. 'webgl' skips the probe entirely — pin it when the pixels must be reproducible. 'webgpu' is strict and never silently falls back.

backendProbeTimeoutMs?

optional backendProbeTimeoutMs?: number;

How long the WebGPU probe may take before 'auto' gives up and uses WebGL (default 5000ms; 0 or Infinity waits forever). A context can advertise navigator.gpu and then never settle its initialization — headless software rendering does exactly this — and without a bound the page hangs with no error rather than falling back. 'webgpu' rejects on timeout instead.

cameraFar?

optional cameraFar?: number;

cameraNear?

optional cameraNear?: number;

canvas?

optional canvas?: HTMLCanvasElement | OffscreenCanvas;

clearColor?

optional clearColor?: string;

Background clear color, default a mid grey.

height?

optional height?: number;

logarithmicDepthBuffer?

optional logarithmicDepthBuffer?: boolean;

Compatibility fallback for large view ranges; costs early-fragment performance.

onDeviceLost?

optional onDeviceLost?: (reason) => void;

Device loss requires a new viewer/canvas. Auto fallback applies during initialization.

Parameters

reason

string

Returns

void

optimizeWebGpu?

optional optimizeWebGpu?: boolean;

Persistent instance buffers and managed tile command caches. Defaults to true on WebGPU.

pixelRatio?

optional pixelRatio?: number;

powerPreference?

optional powerPreference?: "default" | "high-performance" | "low-power";

preserveDrawingBuffer?

optional preserveDrawingBuffer?: boolean;

WebGL only. WebGPU presentation does not preserve the drawing buffer between frames.

reflections?

optional reflections?: boolean;

Shared procedural sky/ground reflections for PBR materials. Default false; Earth viewers enable it.

releaseContextOnDispose?

optional releaseContextOnDispose?: boolean;

WebGL only: dispose() also releases the GL context (forceContextLoss). Browsers cap live contexts per page (Chromium keeps 16), so a single-page host that mounts and unmounts viewers should enable this; each mount then needs a fresh canvas, because a lost context stays attached to its canvas. Default false keeps a canvas reusable after dispose.

reverseDepthBuffer?

optional reverseDepthBuffer?: boolean;

Better depth precision for large view ranges; WebGL uses logarithmic depth if EXT_clip_control is unavailable.

stars?

optional stars?: readonly SkyStar[];

Stars for every sky, e.g. decodeStarCatalog of the molen.sky content pack's stars.bin. Without a catalog, skies show no stars; setStarCatalog supplies one later.

width?

optional width?: number;

---

SceneAdmission

Methods

run()

run<T>(task, options?): Promise<T>;

Type Parameters

T

T

Parameters

task

() => T

options?

AdmissionOptions

Returns

Promise&lt;T&gt;

---

SceneBackend

A backend that owns actual scene-graph objects (three.js, or a mock in tests).

Methods

create()

create(id, renderable): void;

Parameters

id

string

renderable

Renderable

Returns

void

createLight()?

optional createLight(id, light): void;

Optional light surface (per-entity light components).

Parameters

id

string

light

LightData

Returns

void

destroy()

destroy(id): void;

Parameters

id

string

Returns

void

destroyLight()?

optional destroyLight(id): void;

Parameters

id

string

Returns

void

setEnvironment()?

optional setEnvironment(env): void;

Optional environment surface (the singleton environment component, or undefined).

Parameters

env

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

Returns

void

setModelSignals()?

optional setModelSignals(
   id, 
   spec, 
   signals
): void;

Parameters

id

string

spec

ModelSignalSpec | undefined

signals

ModelSignals

Returns

void

setTransform()

setTransform(id, transform): void;

Parameters

id

string

transform

InterpTransform

Returns

void

setWeather()?

optional setWeather(weather): void;

Physical and visual weather singleton; independent of environment/sky configuration.

Parameters

weather

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

Returns

void

updateLight()?

optional updateLight(id, light): void;

Parameters

id

string

light

LightData

Returns

void

updateRenderable()

updateRenderable(id, renderable): void;

Parameters

id

string

renderable

Renderable

Returns

void

---

SceneOptimizationOptions

Properties

animation?

optional animation?: 
  | false
  | {
  distantDistance?: number;
  distantHz?: number;
  hiddenHz?: number;
};

Live-only pose throttling. Captures continue to sample exact simulation ticks.

maxLocalLights?

optional maxLocalLights?: number;

Local lights beyond this count are ranked by influence; unlimited by default.

shaderWarmup?

optional shaderWarmup?: boolean;

staticInstancing?

optional staticInstancing?: boolean | StaticBatchOptions;

---

ShadowFocus

Properties

center

center: readonly [number, number, number];

Focus point in absolute world coordinates (before any floating-origin rebase).

radius

radius: number;

Half-width of the shadowed square around the focus, meters.

---

SkyAppearance

Extended by

• CustomSkyData
• EarthSkyData

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];

---

SkyFrame

Properties

daylight

daylight: number;

earth?

optional earth?: EarthSkyState;

moonDiameterDeg

moonDiameterDeg: number;

moonDirection?

optional moonDirection?: Vec3;

moonIllumination

moonIllumination: number;

starVisibility

starVisibility: number;

sunDiameterDeg

sunDiameterDeg: number;

sunDirection

sunDirection: Vec3;

---

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;

---

SkyReflectionFilter

A backend owns one PMREM generator and reuses its render target across lighting changes.

Methods

dispose()

dispose(): void;

Returns

void

update()

update(texture): Texture;

Parameters

texture

DataTexture

Returns

Texture

---

SkyReflectionState

Scene-linear radiance, independent of camera position and floating world origin.

Properties

clouds

clouds: number;

ground

ground: RGB;

horizon

horizon: RGB;

sunColor

sunColor: RGB;

sunDirection

sunDirection: RGB;

sunGlow

sunGlow: number;

twilight

twilight: RGB;

twilightStrength

twilightStrength: number;

zenith

zenith: RGB;

---

SkyStar

Properties

color?

optional color?: string;

direction

direction: Vec3;

Unit direction in the unrotated star sphere. Earth skies use J2000 equatorial XYZ.

magnitude

magnitude: number;

---

SkyTime

Properties

epochMs

epochMs: number;

UTC Unix milliseconds at simulation second zero.

scale?

optional scale?: number;

Sky seconds per simulation second, default 1.

---

SkyVisualOptions

Properties

shadows?

optional shadows?: "off" | "low" | "medium" | "high";

stars?

optional stars?: readonly SkyStar[];

The star catalog: decodeStarCatalog of the molen.sky pack for Earth, or an authored world's own. Without one the sky has no stars.

---

StaticBatchOptions

Properties

cellSize?

optional cellSize?: number;

minInstances?

optional minInstances?: number;

---

TopDownOrtho

The framing for the orthographic top-down camera: where it looks and how much it covers.

Properties

cameraHeight?

optional cameraHeight?: number;

Camera height above the ground (for depth ordering).

center

center: [number, number];

World XZ the camera centers on.

rotationDeg?

optional rotationDeg?: number;

viewHeight

viewHeight: number;

Vertical world extent the viewport covers.

---

UrlAssetProviderOptions

Properties

variant?

optional variant?: string;

Packed runtime variant to prefer for convention-resolved ids (e.g. "ktx2" from molen asset pack): assets/<id>/model.<variant>.glb is tried first and model.glb is the fallback when the variant is not served. Index-mapped and URL-ish refs are used as given.

Type Aliases

AdaptiveQualityReason

type AdaptiveQualityReason = "frame-time" | "memory-pressure" | "headroom" | "manual";

---

ClientDiagCode

type ClientDiagCode = "link-error" | "frame-error";

Diag codes the client synthesizes for failures the kernel cannot report (it is the casualty).

---

ModelSignals

type ModelSignals = Readonly<Record<string, number | undefined>>;

---

RendererBackend

type RendererBackend = "webgl" | "webgpu";

---

RendererBackendPreference

type RendererBackendPreference = "auto" | RendererBackend;

---

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;

---

ShadowQuality

type ShadowQuality = "off" | "low" | "medium" | "high";

---

SkyData

type SkyData = EarthSkyData | CustomSkyData;

---

StarCatalogRow

type StarCatalogRow = readonly [number, number, number, number];

One catalog row: J2000 right ascension and declination in degrees, magnitude, B-V.

---

ThreeRenderer

type ThreeRenderer = THREE.WebGLRenderer | WebGPURenderer;

---

Unsubscribe

type Unsubscribe = () => void;

Returns

void

---

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

defaultEnvironment

const defaultEnvironment: EnvironmentData;

Exactly the rig the renderer always shipped — existing scenes render byte-identical.

---

defaultSkyPalette

const defaultSkyPalette: Required<SkyPalette>;

Functions

applyEnvironment()

function applyEnvironment(renderer, env): void;

Apply an environment onto the renderer + scene: replaces the ambient/sun rig, background, fog, tone mapping, exposure, and the shadow quality tier. Passing defaultEnvironment restores the stock rig; omitted fields fall back to it.

Parameters

renderer

Renderer

env

EnvironmentData

Returns

void

---

applyInputRules()

function applyInputRules(
   input, 
   inputMap, 
   emit, 
   opts?
): Unsubscribe$1;

Run a scene's input.emit rules against an InputMap: press/release rules emit on action edges; numeric rules share one controller poller that emits a scalar or [x, y] vector only when its value changes. Returns a disposer.

Parameters

input

SceneInput

inputMap

InputMap

emit

(type, payload) => void

opts?

InputRuleOptions

Returns

Unsubscribe$1

---

applySceneCamera()

function applySceneCamera(
   camera, 
   renderer, 
   target?
): void;

Apply a scene's camera block. fixed and free-fly pose the perspective camera (free-fly applies its initial pose only; movement controls are the host's); top-down-ortho switches to the orthographic framing. Re-run after a resize to keep ortho framing (the Renderer already refits on setSize; callers with their own renderer may call this again).

Parameters

camera

SceneCamera

renderer

CameraTarget

target?

InterpTransform

Returns

void

---

computeClipTime()

function computeClipTime(
   anim, 
   tick, 
   tickRate, 
   durationSec
): number;

Deterministic clip time from kernel tick (the capture path's animation contract).

Parameters

anim

clip

string

loop?

"repeat" | "once" | "pingpong"

paused?

boolean

pausedAtTick?

number

speed?

number

startTick?

number

tick

number

tickRate

number

durationSec

number

Returns

number

---

createClient()

function createClient(link, opts?): Promise<MolenClient>;

Create a client bound to a kernel message link (Worker/MessagePort). The renderer-free core (createClientCore) applies keyframes/deltas into a scene mirror + interpolation buffer and dispatches events; this wraps it with the three.js backend and a frame loop.

Asynchronous because selecting a graphics backend is: backend defaults to 'auto', which probes WebGPU and falls back to WebGL. Pass backend: 'webgl' to skip the probe — capture and golden paths do, because a pinned backend is what makes a frame byte-stable.

Parameters

link

MessageLink

opts?

ClientOptions

Returns

Promise&lt;MolenClient&gt;

---

createClientCore()

function createClientCore(opts): ClientCore;

Parameters

opts

ClientCoreOptions

Returns

ClientCore

---

createGltfLoader()

function createGltfLoader(renderer?, config?): GLTFLoader;

A GLTFLoader with the meshopt decoder always attached (its WASM is inlined — zero hosting), plus optional Draco/KTX2 support when decoder paths are configured. Canonical GLBs from molen asset import are quantize+meshopt only, so most apps never configure paths.

Parameters

renderer?

WebGLRenderer | WebGPURenderer

config?

DecoderConfig

Returns

GLTFLoader

---

createGpuFrameTimer()

function createGpuFrameTimer(context, options?): GpuFrameTimer | undefined;

Optional WebGL2 timing. Reads a result only after QUERY_RESULT_AVAILABLE; never waits, flushes, finishes, or schedules polling. Unavailable extensions return undefined. Context restoration reacquires the extension and starts with fresh query objects.

Parameters

context

WebGLRenderingContext | WebGL2RenderingContext

options?

GpuFrameTimerOptions

Returns

GpuFrameTimer | undefined

---

createIndexedDbMaterialStore()

function createIndexedDbMaterialStore(name?): BakedMaterialStore | undefined;

Baked materials kept in IndexedDB across visits; pair with withBakedMaterialStore from @bendyline/molen-materials. Undefined where IndexedDB is unavailable. Every failure (quota, private browsing, a blocked upgrade) resolves as a miss, so baking simply runs as before.

Parameters

name?

string

Returns

BakedMaterialStore | undefined

---

createModelSignalVisual()

function createModelSignalVisual(model, spec): ModelSignalVisual;

Model-agnostic; moves existing geometry without creating a cockpit or changing physics.

Parameters

model

Object3D

spec

ModelSignalSpec

Returns

ModelSignalVisual

---

createSnapshotViewer()

function createSnapshotViewer(keyframe, opts?): Promise<MolenClient>;

Boot a client directly from a serialized keyframe with no live kernel — the capture page and replay viewer use this (docs-src/guide/three-surface.md). With gltf renderables, await ready() before the deterministic frame; clip poses derive from the keyframe tick.

Like createClient, backend defaults to 'auto'; pin 'webgl' for a byte-stable frame.

Parameters

keyframe

Keyframe

opts?

ClientOptions

Returns

Promise&lt;MolenClient&gt;

---

createUrlAssetProvider()

function createUrlAssetProvider(
   baseUrl, 
   index?, 
   options?
): AssetProvider;

URL-backed provider: asset ids resolve through an id -> URL index (from the project manifest's assets record, mapped to served model URLs); URL-ish refs resolve against baseUrl.

Parameters

baseUrl

string

index?

Record&lt;string, string&gt;

options?

UrlAssetProviderOptions

Returns

AssetProvider

---

createViewer()

function createViewer(opts?): Promise<MolenClient>;

Create a viewer with no kernel and no snapshot — just a renderer + camera over an empty scene. For client-side capabilities (terrain, custom three.js objects via renderer.scene).

Parameters

opts?

ClientOptions

Returns

Promise&lt;MolenClient&gt;

---

createWebGlSkyReflectionFilter()

function createWebGlSkyReflectionFilter(renderer): SkyReflectionFilter;

Parameters

renderer

WebGLRenderer

Returns

SkyReflectionFilter

---

decodeStarCatalog()

function decodeStarCatalog(input): SkyStar[];

Decode a molen/stars@1 catalog into sky stars (J2000 equatorial directions, the same frame the bundled catalog uses) for SkyVisual.setStars or Renderer.setStarCatalog.

Parameters

input

ArrayBuffer | Uint8Array&lt;ArrayBufferLike&gt;

Returns

SkyStar[]

---

decodeStarCatalogRows()

function decodeStarCatalogRows(input): StarCatalogRow[];

Decode molen/stars@1 bytes to catalog rows.

Parameters

input

ArrayBuffer | Uint8Array&lt;ArrayBufferLike&gt;

Returns

StarCatalogRow[]

---

encodeStarCatalog()

function encodeStarCatalog(rows): Uint8Array;

Encode catalog rows as molen/stars@1 bytes.

Parameters

rows

readonly StarCatalogRow[]

Returns

Uint8Array

---

evaluateEarthSky()

function evaluateEarthSky(utcMs, observer): EarthSkyState;

Compact Earth ephemeris: Keplerian Sun + Moon with the major lunar perturbations, ellipsoidal observer parallax, sidereal rotation and stellar precession. Formula reference: https://www.stjarnhimlen.se/comp/ppcomp.html (Paul Schlyter). Intended for visual skies, not navigation: no refraction, nutation, eclipses, or light time.

Parameters

utcMs

number

observer

EarthObserver

Returns

EarthSkyState

---

followCameraPose()

function followCameraPose(camera, target): CameraPose;

Pure camera composition shared by live interpolation and deterministic snapshot viewers.

Parameters

camera

entity

string

fov?

number

lookOffset

Vec3

mode

"follow"

offset

Vec3

space?

"world" | "local"

target

InterpTransform

Returns

CameraPose

---

lerp3()

function lerp3(
   a, 
   b, 
   t
): Vec3;

Parameters

a

Vec3

b

Vec3

t

number

Returns

Vec3

---

localCommand()

function localCommand(
   seq, 
   type, 
   payload
): Command;

The envelope command() fills: local source, kernel re-stamps tick 0 to next tick.

Parameters

seq

number

type

string

payload

JsonValue

Returns

Command

---

materialFromBaked()

function materialFromBaked(baked): MeshStandardMaterial;

Upload a BakedMaterial's slots onto a MeshStandardMaterial.

Parameters

baked

BakedMaterial

Returns

MeshStandardMaterial

---

mountExperience()

function mountExperience(opts): Promise<MountedExperience>;

The one-call browser mount: create the client on the link, apply the scene's camera, wire its input bindings + emit rules to client.command, and keep the renderer sized to the canvas. The kernel side is the host's KernelHost in a Worker built with buildWorld (which installs the same scene's scripts). Returns the client plus a disposer.

This is the one entry point a page needs. It is asynchronous because backend defaults to 'auto', which probes WebGPU and falls back to WebGL; pass backend: 'webgl' to skip the probe.

Parameters

opts

MountExperienceOptions

Returns

Promise&lt;MountedExperience&gt;

---

nextWorldOrigin()

function nextWorldOrigin(
   current, 
   cameraPosition, 
   options
): Vec3 | undefined;

Pure automatic-origin policy, exported so hosts can predict and test rebases without WebGL.

Parameters

current

Vec3

cameraPosition

Vec3

options

AutoWorldOriginOptions

Returns

Vec3 | undefined

---

nlerp4()

function nlerp4(
   a, 
   b, 
   t
): Quat;

Normalized linear quaternion interpolation along the shorter arc. Not a slerp: the angular rate is not constant across t, which is the right trade for interpolating between two consecutive simulation ticks (cheap, always returns a unit quaternion, no trig). A rotation large enough for the difference to read would have to turn most of the way around inside one tick.

Parameters

a

Quat

b

Quat

t

number

Returns

Quat

---

normalizeInputAxis()

function normalizeInputAxis(raw, binding): number;

Calibrate and shape a raw axis. Invalid/non-finite hardware readings are neutral.

Parameters

raw

number

binding

GamepadAxisBinding

Returns

number

---

orthoFrustum()

function orthoFrustum(viewHeight, aspect): object;

Orthographic half-extents for a vertical view extent at an aspect ratio (pure; testable).

Parameters

viewHeight

number

aspect

number

Returns

object

halfH

halfH: number;

halfW

halfW: number;

---

readModelSignals()

function readModelSignals(sources, readComponent): ModelSignals;

Read data only: no expressions, evaluation, prototype traversal, or simulation writes.

Parameters

sources

Readonly&lt;Record&lt;string, ModelSignalSource&gt;&gt; | undefined

readComponent

(name) => unknown

Returns

ModelSignals

---

reflectionStateFromLights()

function reflectionStateFromLights(
   ambient, 
   sun, 
   background, 
   clouds
): SkyReflectionState;

Fallback for authored/static light rigs without a celestial SkyVisual.

Parameters

ambient

HemisphereLight | undefined

sun

DirectionalLight | undefined

background

Color

clouds

number

Returns

SkyReflectionState

---

resolveAction()

function resolveAction(bindings, code): string | undefined;

Resolve a key or Mouse<button> code to its bound action.

Parameters

bindings

Record&lt;string, string&gt;

code

string

Returns

string | undefined

---

resolveWeather()

function resolveWeather(data?): ResolvedWeather;

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

Parameters

data?

WeatherData

Returns

ResolvedWeather

---

skyTimeMs()

function skyTimeMs(time, simulationSeconds?): number;

Explicit, seekable simulation clock; no implicit Date.now or browser timezone.

Parameters

time

SkyTime

simulationSeconds?

number

Returns

number

---

starDirection()

function starDirection(
   rightAscensionDeg, 
   declinationDeg, 
   state
): Vec3;

Map a catalog J2000 position (degrees) through a sampled Earth's star basis.

Parameters

rightAscensionDeg

number

declinationDeg

number

state

EarthSkyState

Returns

Vec3

---

weatherProfile()

function weatherProfile(profile): WeatherData;

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

Parameters

profile

WeatherProfile

Returns

WeatherData