@klorad/api/world

The World layer. Scenes, Scene Objects, space, time, snapshots, interaction and projections. Pure TypeScript.

import { createScene } from "@klorad/api/world";

Scene

Export	Kind	Description
`createScene(options)`	function	Creates an empty scene anchored on Earth. Throws without a `coordinateSystem`.
`Scene`	type	The scene: the only way to change world state.
`SceneOptions`	type	Options of `createScene`.
`SceneEvent`, `SceneListener`	type	The ordered events every change becomes.
`snapshotScene(scene)`, `restoreScene(snapshot, options?)`	function	To and from a JSON `SceneSnapshot`.
`projectScene(source, admits, name?)`	function	A read model holding only the objects `admits` accepts, kept in step. Returns a `Projection` (`scene`, `stop()`).

Prop

Type

Method	Returns	Description
`add(spec)`	the object, typed by its spec	Adds a Scene Object. Throws on a duplicate id or an invalid spec.
`update(id, patch)`	`SceneObject`	Patches name, position, orientation, scale, geometry, colour or properties (merged). Throws on an unknown id.
`remove(id)`	`boolean`	Removes an object and its readings.
`get(id)`	`SceneObject \| undefined`
`objects()`	`readonly SceneObject[]`	In insertion order; the same array until something changes.
`observe(input)`	`ObserveResult`	Offers a reading: `latest`, `late`, `duplicate` or `rejected`.
`latest(id, quantity)`	`Observation \| undefined`	The current reading.
`readings(id)`	`Record<string, Observation>`	The current reading of every quantity; the same object until one changes.
`history(id, quantity)`	`readonly Observation[]`	Ordered by `observedAt`, then `seq`.
`isStale(id, quantity)`	`boolean`	Against the scene's clock, now.
`boundTo(source, entity)`	`readonly SceneObject[]`	The shadows and twins bound to a source entity.
`subscribe(listener)`	`() => void`	Every event, in order. Returns an unsubscribe function.
`version()`	`number`	The `seq` of the last event.

Export	Kind	Description
`SceneObject`	type	`DigitalObject \| DigitalShadow \| DigitalTwin`, discriminated by `correspondence`.
`SceneObjectSpec`, `DigitalObjectSpec`, `DigitalShadowSpec`, `DigitalTwinSpec`	type	What `add` takes.
`SceneObjectPatch`	type	What `update` takes.
`Correspondence`	type	`"object" \| "shadow" \| "twin"`.
`SourceBinding`	type	`{ source, entity }`.
`Geometry`	type	`box`, `cylinder`, `sphere`, `marker` or `model` (a glTF `uri`).
`Orientation`	type	`heading`, `pitch`, `roll` in degrees.
`isObservable(object)`	function	Narrows to a shadow or a twin.

Export	Kind	Description
`createCoordinateSystem({ origin })`	function	An East, North, Up frame in metres at a WGS84 origin: `toLocal`, `toGeo`, `resolve`.
`Position`, `GeoPosition`, `LocalPosition`, `GeoPoint`, `LocalPoint`	type	A position on Earth (`lat`, `lon`, `height`) or in metres (`east`, `north`, `up`).
`isLocalPosition(p)`	function	True for the local form.
`geoPoint`, `geodeticToEcef`, `ecefToGeodetic`, `toRadians`, `toDegrees`	function	Geodesy helpers on WGS84.

Export	Kind	Description
`Clock`, `Instant`	type	`now()` in epoch milliseconds.
`systemClock`	value	The default clock.
`createManualClock(start)`	function	A clock you `advance(ms)` or `set(instant)`, for tests.
`Observation`, `ObservationInput`, `ObservationValue`, `ObservationQuality`, `ObserveResult`	type	A reading: `objectId`, `quantity`, `value`, `unit`, `observedAt`, `receivedAt`, `source`, `quality`, `seq`.
`compareObservations(a, b)`	function	The Time Spectrum order: `observedAt`, then `seq`.

Export	Kind	Description
`createInteraction(scene, options)`	function	Runs Action, Entitlement, Behaviour, Animation. Returns an `Interaction`.
`Interaction`	type	`available(objectId, actor, world?)` and `perform(request)`.
`ActionDefinition`, `BehaviourDefinition`, `BehaviourContext`, `AnimationRequest`	type	What you define.
`ActionRequest`, `ActionResult`, `ActionOutcome`, `ActionParams`, `ParamValue`, `Actor`	type	What you ask and what you get back.
`Entitlement`, `Decision`	type	The port Access implements.
`Actuator`, `Command`, `CommandReceipt`	type	The port toward devices, for Digital Twins.

Prop

Type