Appearance

Scene ​

Properties ​

cameraTransform ​

  • Type: Transform
  • Current camera transform in world space

id ​

  • Type: string
  • Scene identifier

microphone ​

time ​

  • Type: number
  • Time elapsed since scene started (seconds)

viewportSize ​

  • Type: Vector2
  • Viewport size in points (iOS only)

Methods ​

animateBy() ​

javascript
animateBy(objectOrId: string | ObjectEntity, properties: Object, duration: number, options?: Object): Promise<void>

Animate object by relative values

Parameters:

  • objectOrId (string | ObjectEntity) - ObjectEntity or entity ID
  • properties (Object) - Relative change values
  • duration (number) - Animation duration in seconds
  • options (Object) (optional) - Animation options

Returns: Promise<void>

animateFromTo() ​

javascript
animateFromTo(objectOrId: string | ObjectEntity, fromProperties: Object, toProperties: Object, duration: number, options?: Object): Promise<void>

Animate object from starting to target properties

Parameters:

  • objectOrId (string | ObjectEntity) - ObjectEntity or entity ID
  • fromProperties (Object) - Starting properties
  • toProperties (Object) - Target properties
  • duration (number) - Animation duration in seconds
  • options (Object) (optional) - Animation options

Returns: Promise<void>

animateTo() ​

javascript
animateTo(objectOrId: string | ObjectEntity, properties: Object, duration: number, options?: Object): Promise<void>

Animate object to target properties

Parameters:

  • objectOrId (string | ObjectEntity) - ObjectEntity or entity ID
  • properties (Object) - Target properties (position, rotation, scale, opacity)
  • duration (number) - Animation duration in seconds
  • options (Object) (optional) - Animation options (timingFunction, delay, repeatCount, etc.)

Returns: Promise<void>

createAudioStream() ​

javascript
createAudioStream(options: Array<any>): AudioStream

Create a streaming audio player

Parameters:

  • options (Array<any>) - Stream configuration (sampleRate, channels, format, elementId, representationId)

Returns: AudioStream

createEntity() ​

javascript
createEntity(descriptor: ObjectDescriptor): Promise<ObjectEntity>

Create an object in the scene.

Example:

javascript
const box = createBox(0.3, 0.3, 0.3)
    .anchor(Anchor.position(0, 0, -1))
    .name('hero-box');
const entity = await scene.createEntity(box);

Parameters:

  • descriptor (ObjectDescriptor) - Object descriptor from createBox, createSphere, createModel, createPlane, createMesh, etc. Configure the object via the descriptor's chainable builder methods (.anchor(...), .name(...), .physics(...), .material(...), .shadow(...), .gestures(...), …), not as a second argument.

Returns: Promise<ObjectEntity>

createPath() beta ​

javascript
createPath(options: { points: [[x,y,z] | {x,y,z} | Vector3, …], closed?: boolean }): Path

Create a catmull-rom path from control points.

Returns a runtime path handle (not persisted): query it with point(t), pointAtDistance(d), tangent(t), length, or drive an entity along it with entity.followPath(path, { duration, constantSpeed, alignsToTangent, timing, repeat }).

Parameters:

  • options ({ points: [[x,y,z] | {x,y,z} | Vector3, …], closed?: boolean }) - (≥ 2 points).

Returns: Path

createSurfaceInput() beta ​

javascript
createSurfaceInput(options: Object): any

Platform-adaptive surface interaction. Returns a live input source that yields interaction points on a surface, in that surface's LOCAL frame, using whatever input the platform offers – fingertips on Apple Vision Pro (hand tracking), screen taps / drags on iPhone / iPad / Mac. Your logic reads the same points either way and never branches on platform.

Read input.points once per frame inside scene.on('render', ...), and call input.stop() when done (it tears down the gesture subscriptions).

Example:

javascript
const input = scene.createSurfaceInput({ target: water.representation, plane: { axis: 'y', offset: 1.25 } });
scene.on('render', function () {
    for (const p of input.points) {
        // p.x / p.y / p.z are in the surface's local frame – feed straight into your sim
    }
});
// later: input.stop();

Parameters:

  • options (Object)
  • options.target (RepresentationEntity) - The surface: the representation whose local frame the points are returned in – typically entity.representation. Passing an ObjectEntity uses its primary representation (fine for a simple object; for a composed object with nested representations, pass the specific representation holding the surface).
  • options.project (string) (optional) - How a screen ray maps to the surface: 'plane' (fast closed-form intersection with a flat plane – no collision needed, ideal for water / tables / deforming compute meshes) or 'collision' (scene.raycast against the target's collision geometry – for solid models; a deforming mesh without live collision falls back to its base shape). The hand path is proximity-based and works on any shape regardless.
  • options.plane (Object) (optional) - Plane definition for project: 'plane'.
  • options.plane.axis (string) (optional) - Plane normal axis in local space: 'x' | 'y' | 'z'.
  • options.plane.offset (number) (optional) - Plane position along that axis, in local metres.
  • options.maxDistance (number) (optional) - Hand path only: a fingertip is an active touch when within this distance (metres) of the plane. Crossing in = began, leaving = ended.

Returns: any

emitHaptic() ​

javascript
emitHaptic(feedback?: string | Object): Promise<void>

Play haptic feedback on the viewer's device.

Haptics are device-level rather than positional – they play on the device no matter which object triggered them – so this lives on the scene rather than on an entity. Devices without a haptic engine ignore it.

Example:

javascript
// Thud when the ball knocks a can over.
can.on('collision', function() {
    scene.emitHaptic('impactHeavy');
});

Parameters:

  • feedback (string | Object) (optional) - "impactLight", "impactMedium", "impactHeavy", "impactSoft", "impactRigid", "selection", or { asset: urlOrId } for a custom haptic pattern file.

Returns: Promise<void>

findEntity() ​

javascript
findEntity(query: any): ObjectEntity

Find an entity by ID or name

Example:

javascript
// By ID
var entity = scene.findEntity("ABC123");

// By ID (explicit)
var entity = scene.findEntity({ id: "ABC123" });

// By name
var entity = scene.findEntity({ name: "My Cool Box" });

Parameters:

  • query (any) - Entity ID string, or object with { id: "..." } or { name: "..." }

Returns: ObjectEntity

getAnchors() ​

javascript
getAnchors(kind?: string): Array<any>

Get detected AR anchors

Parameters:

  • kind (string) (optional) - Filter by anchor type ("plane", "image", "face", etc.), or nil for all

Returns: Array<any>

getCustomEvents() ​

javascript
getCustomEvents(): Array<any>

List custom-trigger scene events on the current segment. Useful for debug panels that enumerate triggerable events at runtime. Each entry has the event's id, optional name (omitted when unset), and isEnabled flag. System events (tap, render, screenTap, schedule, etc.) are not included – those are handled by the engine, not scripted.

Example:

javascript
scene.getCustomEvents().forEach(function(evt) {
    console.log(evt.id, evt.name, evt.isEnabled);
});

Returns: Array<any>

getMaterial() ​

javascript
getMaterial(id: string): Material

Fetch a material from the experience's material library by id, hydrated into a live Material you can inspect, .clone(), and edit. Use the get → .clone() → tweak → apply pattern to override a library material on a single object without mutating the library entry.

Parameters:

  • id (string) - The library material's id.

Returns: Material

getObjectDescriptor() ​

javascript
getObjectDescriptor(nameOrId: string | Object): ObjectDescriptor | any

Read an authored object's descriptor so a script can adjust it before it is displayed. Returns an editable {@link ObjectDescriptor} (the recipe) – distinct from findEntity, which returns the live entity once it's in the scene. Edit it with the usual chainable methods (.material, .gestures, .asset, .representation, …), then either scene.setObjectDescriptor(...) to update it in place, or .clone() + scene.createEntity(...) to spawn a variant.

Ordering: run the edit + set BEFORE the object's Display Element action, in the same event (top level or a Sequence – not inside a Group, which runs concurrently), and keep the set synchronous (no await before it).

Parameters:

  • nameOrId (string | Object) - An id string, or { id } / { name }.

Returns: ObjectDescriptor | any

getVariable() ​

javascript
getVariable(id: string): any

Get a scene-scoped variable

Parameters:

  • id (string) - Variable identifier

Returns: any

off() ​

javascript
off(eventId: string): void

Remove a scene event listener

Example:

javascript
var eventId = scene.on('render', function() {});
// Later...
scene.off(eventId);

Parameters:

  • eventId (string) - Event ID returned from on()

Returns: void

on() ​

javascript
on(type: string, options?: Object | function, listener?: function): string

Register a scene event listener

Example:

javascript
scene.on('start', function() {
    console.log('Scene started!');
});

Parameters:

  • type (string) - Event type: "start", "render", "screenTap", "pan", "pinch", "rotate", "variableChange", "schedule"
  • options (Object | function) (optional) - Event options or callback
  • listener (function) (optional) - Callback if options provided

Returns: string

once() ​

javascript
once(type: string, options?: Object | function, listener?: function): string

Register a one-time scene event listener

Example:

javascript
scene.once('start', function() {
    console.log('Scene started (once)!');
});

Parameters:

  • type (string) - Event type
  • options (Object | function) (optional) - Event options or callback
  • listener (function) (optional) - Callback if options provided

Returns: string

playAnimation() ​

javascript
playAnimation(objectOrId: string | ObjectEntity, animation: Object, representationId?: string): Promise<void>

Play animation on object

Parameters:

  • objectOrId (string | ObjectEntity) - ObjectEntity or entity ID
  • animation (Object) - Animation data
  • representationId (string) (optional) - Optional representation ID

Returns: Promise<void>

playAudioBuffer() ​

javascript
playAudioBuffer(base64: string, options?: Object): Promise<void>

Play audio from PCM buffer data

Example:

javascript
// Play at user's position (non-spatial)
await scene.playAudioBuffer(base64Data, { sampleRate: 24000 });

// Play spatially on an entity
await scene.playAudioBuffer(base64Data, { 
    sampleRate: 24000, 
    elementId: box.id 
});

Parameters:

  • base64 (string) - Base64-encoded PCM audio data
  • options (Object) (optional) - Buffer and playback options
  • options.sampleRate (number) (optional) - Sample rate in Hz
  • options.channels (number) (optional) - Number of channels (1 = mono, 2 = stereo)
  • options.format (string) (optional) - Sample format: "pcm16" or "float32"
  • options.gain (number) (optional) - Volume gain (0.0 to 4.0, default 1.0)
  • options.elementId (string) (optional) - Target element ID (optional, uses POV if omitted)
  • options.representationId (string) (optional) - Target representation ID (optional)

Returns: Promise<void>

preload() ​

javascript
preload(sources: string | Array<string>, options?: Object): Promise<void>

Warm one or more assets so their first use doesn't hitch – the decode / GPU upload happens now (e.g. during scene setup) instead of on the frame you first play or show them.

Example:

javascript
// Warm the impact sounds during setup so the first hit doesn't drop a frame.
await scene.preload(['48D3…','12F9…'], { type: 'audio' });

Parameters:

  • sources (string | Array<string>) - Asset id(s) or https:// URL(s). For type: 'entity' or 'material', pass the element / material id instead of an asset reference.
  • options (Object) (optional)
  • options.type (string) (optional) - How to warm it: 'audio' (decode + buffer), 'model' (parse + GPU upload), 'entity' (an element and everything it pulls in), 'material', 'shader', or 'file' (just download the bytes).

Returns: Promise<void>

projectToScreen() ​

javascript
projectToScreen(worldPosition: Vector3): Vector2

Convert world position to normalized screen coordinates (iOS only)

Parameters:

  • worldPosition (Vector3) - Position in world space

Returns: Vector2

raycast() ​

javascript
raycast(origin: Vector3, direction: Vector3): Array<any>

Cast ray through scene entities and scene mesh

Parameters:

Returns: Array<any>

raycastAR() ​

javascript
raycastAR(origin: Vector3, direction: Vector3, target: string, alignment: string): Array<any>

Cast ray against AR planes (iOS only)

Parameters:

  • origin (Vector3) - Ray origin in world space
  • direction (Vector3) - Ray direction (will be normalized)
  • target (string) - Target type - "plane", "planeExtended", "surface"
  • alignment (string) - Surface alignment - "horizontal", "vertical", "any"

Returns: Array<any>

runAction() ​

javascript
runAction(action: Action): Promise<void>

Run an action and wait for completion.

Parameters:

  • action (Action) - Action to run.

Returns: Promise<void>

screenToRay() ​

javascript
screenToRay(normalizedPosition: Vector2): Ray

Convert normalized screen coordinates to a ray for raycasting (iOS only)

Parameters:

  • normalizedPosition (Vector2) - Screen position in normalized coordinates (0-1)

Returns: Ray

setObjectDescriptor() ​

javascript
setObjectDescriptor(descriptor: ObjectDescriptor): boolean

Write an edited descriptor back into the current scene, keyed by its id. Takes effect the next time the object is displayed (edit before its first Display Element for the clean path). If the object is already displayed, the change lands but displayElement won't re-apply it – remove and re-display to see it.

Parameters:

Returns: boolean

setVariable() ​

javascript
setVariable(id: string, value: any, options: any): void

Set a scene-scoped variable (cleared on scene transition)

Parameters:

  • id (string) - Variable identifier
  • value (any) - Value to store (number, string, boolean, Vector3, Color, etc.)
  • options (any) - Optional type hint { type: "vector3" | "color" | ... }

Returns: void

toggle() ​

javascript
toggle(entities: Array<ObjectEntity>, isEnabled: boolean): Promise<void>

Reveal or hide a batch of objects in a single frame.

Calling entity.toggle(true) in a loop enables each object on its own frame – so physics bodies start at different times and a stack settles against its half-built self. This runs one grouped action instead, so every object reveals and every physics body starts together.

Pairs with cloning a disabled template: clone the batch (each copy stays hidden, physics off), then scene.toggle(copies, true) to bring them all up at once.

Example:

javascript
const cans = [];
for (const slot of layout) {
    cans.push(await template.clone({ position: slot }));  // hidden, deferred
}
await scene.toggle(cans, true);                           // all appear together

Parameters:

  • entities (Array<ObjectEntity>) - Objects to toggle.
  • isEnabled (boolean) - Reveal (true) or hide (false).

Returns: Promise<void>

triggerCustomEvent() ​

javascript
triggerCustomEvent(query: any): void

Trigger one or more custom-trigger events.

or { name: "..." }. Multiple events can share a name – passing { name: ... } fires all matches.

Example:

javascript
scene.triggerCustomEvent("evt-abc");                 // by ID
scene.triggerCustomEvent({ id: "evt-abc" });         // by ID, explicit
scene.triggerCustomEvent({ name: "spawn-box" });     // by name (fires all matches)

Parameters:

  • query (any) - Lookup form. Pass a string ID, { id: "..." },

Returns: void