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): ObjectDescriptor

Create a box primitive descriptor

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

Returns: ObjectDescriptor

createSphere()

createSphere(radius?: number): ObjectDescriptor

Create a sphere primitive

Parameters:

• radius (number) (optional)

Returns: ObjectDescriptor

createPlane()

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

Create a plane primitive

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): ObjectDescriptor

Create a 3D model object descriptor

Parameters:

• urlOrId (string) - HTTPS URL to .usdz/.reality file or asset ID from project

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

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

Parameters:

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

Returns: ObjectDescriptor

createPanel()

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