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 ​

_removeEntity() ​

javascript
_removeEntity(): void

Remove an entity from the scene

Returns: void

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

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>

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:

  • origin (Vector3) - Ray origin in world space
  • direction (Vector3) - Ray direction (will be normalized)

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

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