Global Functions

wait()

wait(seconds: number): Promise<void>

Wait for specified seconds

Parameters:

• seconds (number) - Seconds to wait

Returns: Promise<void>

animateValue()

animateValue(options: Object): ValueAnimation

Create and start a value animation

Automatically interpolates between from/to values based on their type. Supports numbers, Vector2, Vector3, Vector4, Color, and Rotation. Rotations use spherical interpolation (slerp) automatically.

Animations clean up automatically when complete. For infinite animations, call destroy() to stop, or they clean up when the scene ends.

Example:

// Fade in
animateValue({
    from: 0,
    to: 1,
    duration: 0.3,
    onUpdate: function(opacity) {
        entity.opacity = opacity;
    }
});

Parameters:

• options (Object) - Animation configuration
• options.from (number | Vector2 | Vector3 | Vector4 | Color | Rotation) - Start value
• options.to (number | Vector2 | Vector3 | Vector4 | Color | Rotation) - End value (must match from type)
• options.duration (number) (optional) - Duration in seconds (for curve timing)
• options.curve (string) (optional) - Easing curve: "linear", "easeIn", "easeOut", "easeInOut"
• options.spring (Object) (optional) - Spring timing (overrides duration/curve)
• options.spring.duration (number) (optional) - Spring settle duration
• options.spring.bounce (number) (optional) - Bounce amount (0 = no bounce, 1 = full bounce)
• options.bezier (Array<number>) (optional) - Custom bezier curve [p1x, p1y, p2x, p2y]
• options.delay (number) (optional) - Delay before starting (seconds)
• options.repeatCount (number) (optional) - Number of repeats (0 = play once, -1 = infinite)
• options.reverseOnRepeat (boolean) (optional) - Reverse direction on each repeat (yoyo)
• options.autoStart (boolean) (optional) - Start immediately
• options.onUpdate (function) - Called each frame with the interpolated value
• options.onComplete (function) (optional) - Called when animation finishes (not called for infinite)

Returns: ValueAnimation

createBox()

createBox(width?: number, height?: number, depth?: number, cornerRadius?: number, options?: Object): ObjectDescriptor

Create a box primitive descriptor

Example:

// Declarative: reads like data, serializes cleanly.
createBox(0.3, 0.3, 0.3, 0, { name: 'crate', physics: { mode: 'dynamic' } });

Parameters:

• width (number) (optional) - Width in meters
• height (number) (optional) - Height in meters
• depth (number) (optional) - Depth in meters
• cornerRadius (number) (optional) - Corner radius for rounded edges
• options (Object) (optional) - Declarative object config, the same keys as the builder methods: { name, anchor, physics, gestures, material, shadow, transform, opacity, fittingBox, pivot, revealAnimation, removalAnimation, hideByDefault, flatten }. createBox(w, h, d, r, { physics, material }) equals createBox(w, h, d, r).physics(…).material(…).

Returns: ObjectDescriptor

createSphere()

createSphere(radius?: number, options?: Object): ObjectDescriptor

Create a sphere primitive

Parameters:

• radius (number) (optional)
• options (Object) (optional) - Declarative object config (same keys as the builder methods) – see createBox.

Returns: ObjectDescriptor

createPlane()

createPlane(orientation: string | number, width?: number, height?: number, cornerRadius?: number): ObjectDescriptor

Create a plane primitive

Example:

// A 2m x 2m horizontal floor plane ('xz'); use 'xy' for a vertical wall.
var floor = await scene.createEntity(
    createPlane('xz', 2, 2).anchor(Anchor.position(0, 0, -2))
);

Parameters:

• orientation (string | number) - "xz" (horizontal) or "xy" (vertical), or width if orientation omitted
• width (number) (optional)
• height (number) (optional)
• cornerRadius (number) (optional)

Returns: ObjectDescriptor

createModel()

createModel(urlOrId: string, options?: Object): ObjectDescriptor

Create a 3D model object descriptor

Example:

var model = await scene.createEntity(
    createModel('https://example.com/chair.usdz').anchor(Anchor.horizontalPlane('floor'))
);

Parameters:

• urlOrId (string) - HTTPS URL to .usdz/.reality file or asset ID from project
• options (Object) (optional) - Declarative object config (same keys as the builder methods) – see createBox.

Returns: ObjectDescriptor

createSplat() beta

createSplat(urlOrId: string, options?: Object): ObjectDescriptor

Create a Gaussian splat capture object descriptor

Example:

var capture = await scene.createEntity(
    createSplat(assetId, { opacityThreshold: 0.02 }).anchor(Anchor.position(0, 0.4, -0.8))
);
var splat = capture.representation.splat;

Parameters:

• urlOrId (string) - HTTPS URL to an .spz file, or asset ID from project
• options (Object) (optional) - Declarative object config. Beyond the shared keys (see createBox): projection ("perspective" | "tangential"), sorting ("depth" | "distance"), and opacityThreshold (0–1, drops the faintest splats at load).

Returns: ObjectDescriptor

createMedia()

createMedia(kind: string, urlOrId: string, width?: number, aspectRatio?: number, options?: Object): ObjectDescriptor

Create a visual media object (image, video, or animated GIF)

Parameters:

• kind (string) - "image", "video", or "animatedGif"
• urlOrId (string) - HTTPS URL or asset ID
• width (number) (optional) - Width in meters
• aspectRatio (number) (optional) - Aspect ratio (width/height)
• options (Object) (optional) - Additional options
• options.cornerRadius (number) (optional) - Relative corner radius (0-1)
• options.doubleSided (boolean) (optional) - Render both sides
• options.showLoading (boolean) (optional) - Show loading placeholder
• options.immersive (boolean) (optional) - Enable immersive rendering
• options.video (Object) (optional) - Video playback options
• options.video.volume (number) (optional) - Volume (0-1)
• options.video.loops (boolean) (optional) - Loop playback
• options.video.stream (boolean) (optional) - Stream content

Returns: ObjectDescriptor

createImage()

createImage(urlOrId: string, width?: number, aspectRatio?: number, options?: Object): ObjectDescriptor

Create an image

Example:

// 0.5m wide, 3:2 aspect ratio (width / height).
var photo = await scene.createEntity(
    createImage('https://picsum.photos/900/600', 0.5, 1.5).anchor(Anchor.currentPOV(0, 0, -1.5))
);

Parameters:

• urlOrId (string) - HTTPS URL or asset ID
• width (number) (optional) - Width in meters
• aspectRatio (number) (optional) - Aspect ratio (width/height)
• options (Object) (optional) - Additional options (cornerRadius, doubleSided, showLoading, immersive)

Returns: ObjectDescriptor

createVideo()

createVideo(urlOrId: string, width?: number, aspectRatio?: number, options?: Object): ObjectDescriptor

Create a video

Parameters:

• urlOrId (string) - HTTPS URL or asset ID
• width (number) (optional) - Width in meters
• aspectRatio (number) (optional) - Aspect ratio (width/height)
• options (Object) (optional) - Additional options (cornerRadius, doubleSided, showLoading, immersive, video)

Returns: ObjectDescriptor

createAnimatedGif()

createAnimatedGif(urlOrId: string, width?: number, aspectRatio?: number, options?: Object): ObjectDescriptor

Create an animated GIF

Parameters:

• urlOrId (string) - HTTPS URL or asset ID
• width (number) (optional) - Width in meters
• aspectRatio (number) (optional) - Aspect ratio (width/height)
• options (Object) (optional) - Additional options (cornerRadius, doubleSided, showLoading, immersive)

Returns: ObjectDescriptor

createContainer()

createContainer(children: Array<ObjectDescriptor>): ObjectDescriptor

Create a container/composition

Example:

// Group objects so the container anchors and moves them as one.
var group = await scene.createEntity(
    createContainer([ createBox(0.1, 0.1, 0.1), createSphere(0.05) ]).anchor(Anchor.position(0, 0, -1.5))
);

Parameters:

• children (Array<ObjectDescriptor>) - Child object descriptors

Returns: ObjectDescriptor

createPanel() beta

createPanel(content: Object, options?: Object): void

Build a UI panel descriptor wrapping the given root view. Pass to scene.createEntity(panel) to instantiate.

Parameters:

• content (Object) - Root View descriptor (typically a UI.vStack/hStack/zStack).
• options (Object) (optional)
• options.panelSize (any | any | Array<number> | any) (optional) - Panel dimensions. Use 'auto' (default – sized to content), 'fill' (fill parent), or an explicit size in points (≈ 1360 pt/m): either [width, height] or { width, height }. E.g. [400, 240] ≈ 0.29m × 0.18m.

Returns: void

createMesh() beta

createMesh(opts: Object): ObjectDescriptor

Create a scriptable dynamic mesh with CPU-driven vertex/index updates.

Returns an ObjectDescriptor – pass to scene.createEntity(...). After the entity loads, reach the mesh via entity.representation.mesh and write buffer data with mesh.writeVertices(...) / mesh.writeIndices(...). Bytes flow straight from Float32Array / Uint32Array into the GPU-side buffer – single memcpy per call, no per-element overhead.

Example:

// Triangle, single static buffer, no material override (using shorthand).
const entity = await scene.createEntity(createMesh({
    vertexCapacity: 3,
    indexCapacity: 3,
    attributes: {
        position: "float3"
    },
    parts: [{
        indexCount: 3,
        bounds: { min: [-0.5, -0.1, -0.1], max: [0.5, 0.5, 0.1] }
    }]
}));

const mesh = entity.representation.mesh;
mesh.writeVertices("position", 0, new Float32Array([
    -0.25, 0.0, 0.0,
     0.25, 0.0, 0.0,
     0.0,  0.4, 0.0
]));
mesh.writeIndices(0, new Uint32Array([0, 1, 2]));

Parameters:

• opts (Object)
• opts.vertexCapacity (number) - Max vertices the mesh allocates space for. Required.
• opts.indexCapacity (number) - Max indices the mesh allocates space for. Required (must be > 0). For draw orders that would otherwise be non-indexed, set this to vertexCapacity and write sequential indices [0, 1, 2, …] once.
• opts.indexType (string) (optional) - "uint32" or "uint16".
• opts.attributes (Object<string, string | Object>) - Named attributes. Either a string shorthand or an explicit object. - Shorthand (static, semantic auto-derived from name): position: "float3", color: "uchar4Normalized". - Explicit form: { semantic, format, storage }. semantic ∈ "position" | "normal" | "tangent" | "bitangent" | "color" | "uv0" … "uv7" | "unspecified" (defaults to the attribute name when omitted). format ∈ "float" | "float2" | "float3" | "float4" | "uchar4Normalized". storage ∈ "static" (default – write once at setup) | "dynamic" (CPU-writable via writeVertices, per-frame) | "compute" (reserved for a future runtime version; rejected today).
• opts.parts (Array<Object>) - Draw ranges. Each part: { indexOffset?, indexCount, topology?, materialIndex?, bounds }. topology ∈ "triangle" (default) | "triangleStrip" | "line" | "lineStrip" | "point". bounds: { min: [x,y,z], max: [x,y,z] }. Must contain every vertex the part draws.
• opts.materials (Array<string>) (optional) - Material reference ids from the experience's material library. Each part's materialIndex indexes into this array. If empty, a default material is used.
• opts.interleavedGroups (Array<Array<string>>) (optional) - Opt-in attribute grouping. Each inner array is a set of attribute names that share one underlying buffer (interleaved layout). Default is one buffer per attribute. Use case: spatial-drawing-style stroke extension where every vertex carries position+normal+color together — interleaved gives better GPU cache locality. All attributes in a group must share storage state (all "static", all "dynamic", etc.). Per-attribute write API (mesh.writeVertices(name, ...)) stays the same; the bridge uses a strided memcpy under the hood.

Returns: ObjectDescriptor

createSpotLight()

createSpotLight(options?: Object): ObjectDescriptor

Create a spot light – a cone of light aimed along the object's forward axis.

Rotation aims it; position places it. Intensity is in lumens.

Example:

// A warm spot pointing straight down at the floor, with a soft-edged shadow.
var lamp = await scene.createEntity(
    createSpotLight({
        color: '#FFD9A0',
        intensity: 4000,
        outerAngle: 45,
        attenuationRadius: 3,
        shadow: { edges: 'soft', lightSize: 0.2 },
        anchor: Anchor.position(0, 2, -1),
        transform: { rotation: Rotation(-Math.PI / 2, 0, 0) }
    })
);

Parameters:

• options (Object) (optional) - Light configuration: color ('#RRGGBB' or { r, g, b }), intensity (lumens, default 6740.94), innerAngle / outerAngle in degrees (full cone aperture, defaults 45 / 60), attenuationRadius in metres (default 10), falloffExponent (2 is physically correct), shadow (see below), projectedTexture (asset id, HTTPS URL, or a handle from Texture.image/video/cameraFeed/compute(...)), projectedTextureOffset / projectedTextureScale ({ x, y }, a pair, or one number for both axes) and projectedTextureRotation in radians, which lay the projected texture out within the cone, lightsSurroundings (spill onto real surfaces). Plus every shared descriptor key – name, anchor, transform, …

  shadow is true for defaults, or { edges, lightSize, depthBias }: edges is 'hard' (default, cheapest), 'soft' or 'softer'; lightSize is the emitter's size in metres, which widens the blurred edge and does nothing at 'hard'; depthBias offsets the shadow off its own surface.

Returns: ObjectDescriptor

createPointLight()

createPointLight(options?: Object): ObjectDescriptor

Create a point light – light radiating equally in every direction.

Only its position matters; rotation does nothing. Intensity is in lumens, and a point light cannot cast shadows.

Example:

// A candle flame that breathes.
var flame = await scene.createEntity(
    createPointLight({ color: '#FF9A3C', intensity: 800, attenuationRadius: 1.5 })
);
animateValue({
    from: 650, to: 900, duration: 1.4, curve: 'easeInOut',
    repeatCount: -1, reverseOnRepeat: true,
    onUpdate: function(value) { flame.representation.light.intensity = value; }
});

Parameters:

• options (Object) (optional) - color, intensity (lumens, default 26963.76), attenuationRadius (metres, default 10), falloffExponent, lightsSurroundings, plus the shared descriptor keys.

Returns: ObjectDescriptor

createDirectionalLight()

createDirectionalLight(options?: Object): ObjectDescriptor

Create a directional light – a sun, shining from infinitely far away.

Only its rotation matters; position moves nothing but the editor's marker. Intensity is in lux rather than lumens, so the numbers are not comparable with the other two types.

Example:

// A low afternoon sun that casts shadows across a wide scene.
await scene.createEntity(
    createDirectionalLight({
        intensity: 2500,
        shadow: { maximumDistance: 20, cascades: 3 },
        transform: { rotation: Rotation(-0.6, 0.7, 0) }
    })
);

Parameters:

• options (Object) (optional) - color, intensity (lux, default 2145.71), shadow, plus the shared descriptor keys. shadow is true for defaults or { maximumDistance, depthBias, cascades }: maximumDistance is how far from the camera shadows are computed at all, and cascades is 'automatic' or a count of 1...4, where more sharpens distant shadows and costs the same factor in memory.

Returns: ObjectDescriptor