Scene API

This page describes the scene runtime API exposed as detail.api in the ready event.

How to Get It

iframe.addEventListener('ready', (event) => {
  const api = event.detail.api;
});

Scope

This API is currently intended for scene pages.

On collection pages, ready.detail.api is not the scene API.

Shared Conventions

Treat Every Method as Asynchronous

const obj = await api.getObject('rabbit');
await api.setPosition(obj, 1, 0, 0);

Objects Are Handles, Not Native 3D Objects

interface SceneObjectHandle {
  id: number;
}

You cannot read or mutate internal properties directly. You can only pass the handle back into API methods.

Start Now Button

getStartButtonRect(): Promise<DOMRect | undefined>
setStartButtonRect(rect: Partial<CSSStyleDeclaration>): Promise<void>

Used to read or adjust the style and layout of the scene landing page's Start Now Button.

Constants

api.constants = {
  no: 0,
  linear: 1,
  reinhard: 2,
  cineon: 4,
  aces_filmic: 5,
}

Mainly used with setToneMapping().

Object Query and Basic Properties

getObject(name: string): Promise<SceneObjectHandle | null>
getAllObjects(): Promise<SceneObjectHandle[]>

getObjectName(target: SceneObjectHandle): Promise<string | null>
setObjectName(target: SceneObjectHandle, name: string): Promise<void>

getObjectVisible(target: SceneObjectHandle): Promise<boolean | null>
setObjectVisible(target: SceneObjectHandle, visible: boolean): Promise<void>

getRenderOrder(target: SceneObjectHandle): Promise<number | null>
setRenderOrder(target: SceneObjectHandle, renderOrder: number): Promise<void>

getDisableClick(target: SceneObjectHandle): Promise<boolean | null>
setDisableClick(target: SceneObjectHandle, disableClick: boolean): Promise<void>

getSize(target: SceneObjectHandle): Promise<[number, number, number]>
lookAt(target: SceneObjectHandle, x: number, y: number, z: number): Promise<void>

Object Hierarchy and Lifecycle

addChild(target: SceneObjectHandle, child: SceneObjectHandle): Promise<void>
removeChild(target: SceneObjectHandle, child: SceneObjectHandle): Promise<void>

getChildren(target: SceneObjectHandle): Promise<SceneObjectHandle[]>
getChildByProperty(
  target: SceneObjectHandle,
  property: string,
  value: any,
): Promise<SceneObjectHandle | null>

add(target: SceneObjectHandle): Promise<void>
remove(target: SceneObjectHandle): Promise<void>
destroyObject(target: SceneObjectHandle): Promise<void>
clear(): Promise<void>

Transform Properties

getPosition(target: SceneObjectHandle): Promise<[number, number, number]>
setPosition(target: SceneObjectHandle, x?: number, y?: number, z?: number): Promise<void>

getRotation(target: SceneObjectHandle): Promise<[number, number, number, string]>
setRotation(
  target: SceneObjectHandle,
  x?: number,
  y?: number,
  z?: number,
  order?: string,
): Promise<void>

getQuaternion(target: SceneObjectHandle): Promise<[number, number, number, number]>
setQuaternion(
  target: SceneObjectHandle,
  x?: number,
  y?: number,
  z?: number,
  w?: number,
): Promise<void>

getScale(target: SceneObjectHandle): Promise<[number, number, number]>
setScale(target: SceneObjectHandle, x?: number, y?: number, z?: number): Promise<void>

Dynamic Content Creation

createImage(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>
createAnimatedImage(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>
createGltfModel(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>

createVideo(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>
createAlphaVideo(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>
interface KeyingVideoConfig {
  color?: string | number;
  similarity?: number;
  smoothness?: number;
  spill?: number;
}
createKeyingVideo(input: string | ArrayBuffer | Blob | File, config?: KeyingVideoConfig): Promise<SceneObjectHandle>

createPanorama(input: string | ArrayBuffer | Blob | File, segments?: number): Promise<SceneObjectHandle>
createEnvMapByHDR(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>

createGroup(): Promise<SceneObjectHandle>
createAmbientLight(color?: string | number, intensity?: number): Promise<SceneObjectHandle>
createDirectionalLight(color?: string | number, intensity?: number): Promise<SceneObjectHandle>

Rendering and Materials

setEnableMask(target: SceneObjectHandle): Promise<void>
setDisableMask(target: SceneObjectHandle): Promise<void>

setGLState(
  target: SceneObjectHandle,
  prop:
    | 'side'
    | 'shadowSide'
    | 'blending'
    | 'transparent'
    | 'opacity'
    | 'alphaTest'
    | 'depthTest'
    | 'depthWrite'
    | 'colorWrite',
  value: any,
  recursive?: boolean,
): Promise<void>

setAnisotropy(
  target: SceneObjectHandle,
  num: number,
  mapType?: string,
  recursive?: boolean,
): Promise<void>

setObjectAlpha(target: SceneObjectHandle, type: string, cutOff: number): Promise<void>
useEnvMapForObj(
  target: SceneObjectHandle,
  envMap: SceneObjectHandle,
  intensity?: number,
): Promise<void>

setToneMapping(toneMapping: number, toneMappingExposure?: number): Promise<void>

Lighting

getDefaultAmbientLight(): Promise<SceneObjectHandle | null>
getDefaultDirectionalLightLeft(): Promise<SceneObjectHandle | null>
getDefaultDirectionalLightRight(): Promise<SceneObjectHandle | null>
getDirectionalLightTarget(light: SceneObjectHandle): Promise<SceneObjectHandle | null>

getLightColor(light: SceneObjectHandle): Promise<[number, number, number]>
setLightColor(light: SceneObjectHandle, color: string | number): Promise<void>
getLightIntensity(light: SceneObjectHandle): Promise<number>
setLightIntensity(light: SceneObjectHandle, intensity: number): Promise<void>

Camera and Photo Capture

getDefaultCamera(): Promise<SceneObjectHandle>

getCameraFov(camera: SceneObjectHandle): Promise<number | null>
setCameraFov(camera: SceneObjectHandle, fov: number): Promise<void>

getCameraAspect(camera: SceneObjectHandle): Promise<number | null>
setCameraAspect(camera: SceneObjectHandle, aspect: number): Promise<void>

getCameraNear(camera: SceneObjectHandle): Promise<number | null>
setCameraNear(camera: SceneObjectHandle, near: number): Promise<void>

getCameraFar(camera: SceneObjectHandle): Promise<number | null>
setCameraFar(camera: SceneObjectHandle, far: number): Promise<void>

updateCameraProjectionMatrix(): Promise<void>
getCameraWorldDirection(): Promise<[number, number, number]>

switchCamera(position?: 'front' | 'back'): Promise<'front' | 'back'>
takePhoto(): Promise<string>
dispatchTouchEvent(x: number, y: number): Promise<void>
skipCloudar(): Promise<void>

Notes

switchCamera() is not available in web3d mode
takePhoto() returns a data:image/png;base64,... string
skipCloudar() is meaningful only for Basic AR/Gyroscope scenes

Animated Images

getAnimatedImagePaused(target: SceneObjectHandle): Promise<boolean | null>
playAnimatedImage(target: SceneObjectHandle, loopCount?: number): Promise<void>
pauseAnimatedImage(target: SceneObjectHandle): Promise<void>
stopAnimatedImage(target: SceneObjectHandle): Promise<void>

Video

getVideoDuration(target: SceneObjectHandle): Promise<number | null>
getVideoPaused(target: SceneObjectHandle): Promise<boolean | null>
getVideoCurrentTime(target: SceneObjectHandle): Promise<number | null>
setVideoCurrentTime(target: SceneObjectHandle, currentTime: number): Promise<void>

getVideoLoop(target: SceneObjectHandle): Promise<boolean | null>
setVideoLoop(target: SceneObjectHandle, loop: boolean): Promise<void>

playVideo(target: SceneObjectHandle, options?: Record<string, any>): Promise<void>
pauseVideo(target: SceneObjectHandle): Promise<void>
stopVideo(target: SceneObjectHandle): Promise<void>
playbackVideo(target: SceneObjectHandle, options?: Record<string, any>): Promise<void>

Audio

getAudioDuration(target: SceneObjectHandle): Promise<number | null>
getAudioPaused(target: SceneObjectHandle): Promise<boolean | null>
getAudioCurrentTime(target: SceneObjectHandle): Promise<number | null>
setAudioCurrentTime(target: SceneObjectHandle, currentTime: number): Promise<void>

getAudioLoop(target: SceneObjectHandle): Promise<boolean | null>
setAudioLoop(target: SceneObjectHandle, loop: boolean): Promise<void>

playAudio(target: SceneObjectHandle, options?: Record<string, any>): Promise<void>
pauseAudio(target: SceneObjectHandle): Promise<void>
stopAudio(target: SceneObjectHandle): Promise<void>
playbackAudio(target: SceneObjectHandle, options?: Record<string, any>): Promise<void>

Animation

getAnimationNames(target: SceneObjectHandle): Promise<string[] | null>
animationIsRunning(target: SceneObjectHandle, animationName?: string): Promise<boolean | null>
isAnimationLoop(target: SceneObjectHandle, animationName: string): Promise<boolean | null>
getAnimationIsRunningNames(target: SceneObjectHandle): Promise<string[] | null>

playAnimation(
  target: SceneObjectHandle,
  options?: {
    name?: string;
    loop?: boolean;
    repeat?: number;
    repeatMode?: number;
    timeScale?: number;
    weight?: number;
    clampWhenFinished?: boolean;
    resetLoopCount?: boolean;
  },
  triggerEvent?: boolean,
): Promise<void>

pauseAnimation(
  target: SceneObjectHandle,
  name?: string,
  triggerEvent?: boolean,
): Promise<void>

stopAnimation(
  target: SceneObjectHandle,
  name?: string,
  triggerEvent?: boolean,
): Promise<void>

playbackAnimation(
  target: SceneObjectHandle,
  options?: {
    name?: string;
    loop?: boolean;
    repeat?: number;
    repeatMode?: number;
    timeScale?: number;
    weight?: number;
    clampWhenFinished?: boolean;
    resetLoopCount?: boolean;
  },
  triggerEvent?: boolean,
): Promise<void>

Event Listeners

on(
  eventName:
    | 'objectClick'
    | 'click'
    | 'loop'
    | 'play'
    | 'pause'
    | 'ended'
    | 'replay',
  callback: (...args: any[]) => any,
  target?: SceneObjectHandle,
): Promise<void>

off(
  eventName:
    | 'objectClick'
    | 'click'
    | 'loop'
    | 'play'
    | 'pause'
    | 'ended'
    | 'replay',
  callback: (...args: any[]) => any,
  target?: SceneObjectHandle,
): Promise<void>

Event Name Rules

without target, only objectClick is supported
with target, click, play, pause, ended, replay, and similar object events are supported

Callback Parameters

Supported callback payloads differ by object type and event type.

Scene API ​

How to Get It ​

Scope ​

Shared Conventions ​

Treat Every Method as Asynchronous ​

Objects Are Handles, Not Native 3D Objects ​

Start Now Button ​

Constants ​

Object Query and Basic Properties ​

Object Hierarchy and Lifecycle ​

Transform Properties ​

Dynamic Content Creation ​

Rendering and Materials ​

Lighting ​

Camera and Photo Capture ​

Notes ​

Animated Images ​

Video ​

Audio ​

Animation ​

Event Listeners ​

Event Name Rules ​

Callback Parameters ​

Related Guide Pages ​