Skip to content

@bendyline/molen-dioramas/client ​

Bounded scripted set pieces: deterministic local scenes and lazy proximity playback.

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

Classes ​

DioramaDirector ​

Proximity/schedule selection and cancellation. No network or kernel is loaded until selected.

Constructors ​

Constructor ​
ts
new DioramaDirector(options): DioramaDirector;
Parameters ​
options ​

DioramaDirectorOptions

Returns ​

DioramaDirector

Methods ​

add() ​
ts
add(placement): void;
Parameters ​
placement ​

DioramaPlacement

Returns ​

void

dispose() ​
ts
dispose(): void;
Returns ​

void

list() ​
ts
list(): readonly string[];
Returns ​

readonly string[]

remove() ​
ts
remove(id): void;
Parameters ​
id ​

string

Returns ​

void

retry() ​
ts
retry(id): void;

A failed load/script stays failed until explicitly retried, preventing fetch loops.

Parameters ​
id ​

string

Returns ​

void

setPosition() ​
ts
setPosition(id, position): void;
Parameters ​
id ​

string

position ​

Vec3

Returns ​

void

status() ​
ts
status(id): DioramaStatus | undefined;
Parameters ​
id ​

string

Returns ​

DioramaStatus | undefined

update() ​
ts
update(
   observer, 
   seconds, 
   timeMs
): void;

timeMs is a host clock for eligibility only; scripts advance on their own fixed ticks.

Parameters ​
observer ​

Vec3

seconds ​

number

timeMs ​

number

Returns ​

void

whenIdle() ​
ts
whenIdle(): Promise<void>;
Returns ​

Promise&lt;void&gt;

Interfaces ​

DioramaDirectorOptions ​

Properties ​

create ​
ts
create: DioramaFactory;
maxActive? ​
ts
optional maxActive?: number;

Includes loading instances; default 2.

onError? ​
ts
optional onError?: (error, id) => void;
Parameters ​
error ​

unknown

id ​

string

Returns ​

void


DioramaInstance ​

Methods ​

dispose() ​
ts
dispose(): void;
Returns ​

void

setPosition()? ​
ts
optional setPosition(position): void;

Re-anchor scenery without restarting local simulation (e.g. terrain LOD refinement).

Parameters ​
position ​

Vec3

Returns ​

void

update() ​
ts
update(seconds): void;
Parameters ​
seconds ​

number

Returns ​

void


DioramaPlacement ​

Properties ​

active? ​
ts
optional active?: (timeMs) => boolean;

Host clock policy; omitted means always eligible. Never passed into script state.

Parameters ​
timeMs ​

number

Returns ​

boolean

enterDistance? ​
ts
optional enterDistance?: number;

Meters from the placement origin, including altitude (default 350).

exitDistance? ​
ts
optional exitDistance?: number;

Hysteresis: retain a loaded/loading scene until this distance (default enter * 1.2).

id ​
ts
id: string;
load ​
ts
load: DioramaLoader;
position ​
ts
position: Vec3;
yaw? ​
ts
optional yaw?: number;

Rotation about Y, radians. The authored local +Z turns toward +X.


DioramaVisualOptions ​

Properties ​

assets? ​
ts
optional assets?: AssetCache;
camera? ​
ts
optional camera?: Camera;
localLights? ​
ts
optional localLights?: boolean;

Light the host scene with the diorama's own point and spot lights (default true). A host that streams a large world turns them off: three builds every lit shader for the lights in the scene, so a light arriving or leaving with a diorama rebuilt every object in view in one frame.

prepare? ​
ts
optional prepare?: (object, parent) => Promise<void>;

Build the diorama's shaders before it joins root (a host passes its renderer's prepareObject). Its figures, models and static batches otherwise built them in the first frame that drew them: a flight school beside a runway stalled a takeoff for a quarter second.

Parameters ​
object ​

Object3D

parent ​

Object3D

Returns ​

Promise&lt;void&gt;

root ​
ts
root: Object3D;

Attach below the host's floating-origin root.

Type Aliases ​

DioramaFactory ​

ts
type DioramaFactory = (definition, placement) => 
  | DioramaInstance
| Promise<DioramaInstance>;

Injectable lifecycle boundary; the standard client creates a local world and a Three visual.

Parameters ​

definition ​

DioramaDefinition

placement ​

DioramaPlacement

Returns ​

| DioramaInstance | Promise&lt;DioramaInstance&gt;


DioramaLoader ​

ts
type DioramaLoader = (signal) => Promise<DioramaDefinition>;

A loader is invoked only when a placement is selected for playback.

Parameters ​

signal ​

AbortSignal

Returns ​

Promise&lt;DioramaDefinition&gt;


DioramaStatus ​

ts
type DioramaStatus = "idle" | "loading" | "playing" | "failed";

Functions ​

createDioramaVisual() ​

ts
function createDioramaVisual(
   definition, 
   placement, 
   options
): Promise<DioramaInstance>;

Lazy-load the scripting runtime only when a placement is admitted by the director.

Parameters ​

definition ​

DioramaDefinition

placement ​

DioramaPlacement

options ​

DioramaVisualOptions

Returns ​

Promise&lt;DioramaInstance&gt;


loadDioramaScene() ​

ts
function loadDioramaScene(
   url, 
   bounds, 
   signal?
): Promise<DioramaDefinition>;

Fetch a trusted scene and its relative JavaScript sources on demand. TypeScript sources must be erased by the publisher, or bundled with molenScripts() and supplied through a custom loader. No requests happen until the host calls this function. The host owns URL/pack selection.

Parameters ​

url ​

URL

bounds ​

DioramaBounds

signal? ​

AbortSignal

Returns ​

Promise&lt;DioramaDefinition&gt;

References ​

DioramaBounds ​

Re-exports DioramaBounds


DioramaDefinition ​

Re-exports DioramaDefinition


DioramaPlayback ​

Re-exports DioramaPlayback

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