Appearance
@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
Returns
Methods
add()
ts
add(placement): void;Parameters
placement
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<void>
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<void>
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
placement
Returns
| DioramaInstance | Promise<DioramaInstance>
DioramaLoader
ts
type DioramaLoader = (signal) => Promise<DioramaDefinition>;A loader is invoked only when a placement is selected for playback.
Parameters
signal
AbortSignal
Returns
Promise<DioramaDefinition>
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
placement
options
Returns
Promise<DioramaInstance>
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
signal?
AbortSignal
Returns
Promise<DioramaDefinition>
References
DioramaBounds
Re-exports DioramaBounds
DioramaDefinition
Re-exports DioramaDefinition
DioramaPlayback
Re-exports DioramaPlayback