Class USDZExporter

Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.
The USDZ file is generated using the Needle Engine ThreeUSDZExporter.
The exporter supports various extensions to add custom behaviors and interactions to the USDZ file.
The exporter can automatically collect Animations and AudioSources and export them as playing at the start.
The exporter can also add a custom QuickLook overlay with a call to action button and custom branding.

Example

const usdz = new USDZExporter();
usdz.objectToExport = myObject;
usdz.autoExportAnimations = true;
usdz.autoExportAudioSources = true;
usdz.exportAsync();

Hierarchy (View Summary)

Behaviour
- USDZExporter

Index

Properties

autoExportAnimations autoExportAudioSources extensions gameObject guid interactive objectToExport physics sourceId?

Accessors

activeAndEnabled context destroyed enabled forward layer name right scene static tag up worldEuler worldPosition worldQuaternion worldRotation

Properties

autoExportAnimations

autoExportAnimations: boolean = true

Collect all Animations/Animators automatically on export and emit them as playing at the start. Animator state chains and loops will automatically be collected and exported in order as well. If this setting is off, Animators need to be registered by components – for example from PlayAnimationOnClick.

autoExportAudioSources

autoExportAudioSources: boolean = true

Collect all AudioSources automatically on export and emit them as playing at the start. They will loop according to their settings. If this setting is off, Audio Sources need to be registered by components – for example from PlayAudioOnClick.

extensions

extensions: IUSDExporterExtension[] = []

Extensions to add custom behaviors and interactions to the USDZ file.
You can add your own extensions here by extending IUSDExporterExtension.

gameObject

gameObject: GameObject

Reference to the GameObject this component is attached to This is a three.js Object3D with additional GameObject functionality

guid

guid: string = "invalid"

Unique identifier for this component instance, used for finding and tracking components

interactive

interactive: boolean = true

Enabling this option will export QuickLook-specific preliminary behaviours along with the USDZ files. These extensions are only supported on QuickLook on iOS/visionOS/MacOS. Keep this option off for general USDZ usage.

objectToExport

objectToExport: undefined | null | Object3D<Object3DEventMap> = undefined

Assign the object to export as USDZ file. If undefined or null, the whole scene will be exported.

physics

physics: boolean = true

Enabling this option will export the USDZ file with RealityKit physics components. Rigidbody and Collider components will be converted to their RealityKit counterparts. Physics are supported on QuickLook in iOS 18+ and VisionOS 1+. Physics export is automatically turned off when there are no Rigidbody components anywhere on the exported object.

`Optional`sourceId

sourceId?: string

Identifier for the source asset that created this component. For example, URL to the glTF file this component was loaded from

Accessors

activeAndEnabled

get activeAndEnabled(): boolean
Checks if this component is currently active (enabled and part of an active GameObject hierarchy) Components that are inactive won't receive lifecycle method calls

Returns boolean
True if the component is enabled and all parent GameObjects are active

Inherited from Behaviour.activeAndEnabled

context

get context(): Context
The context this component belongs to, providing access to the runtime environment including physics, timing utilities, camera, and scene

Returns Context
Inherited from Behaviour.context
set context(context: Context): void
Parameters
- context: Context
Returns void
Inherited from Behaviour.context

destroyed

get destroyed(): boolean
Checks if this component has been destroyed

Returns boolean
True if the component or its GameObject has been destroyed

Inherited from Behaviour.destroyed

enabled

get enabled(): boolean
Controls whether this component is enabled Disabled components don't receive lifecycle callbacks

Returns boolean
Inherited from Behaviour.enabled
set enabled(val: boolean): void
Parameters
- val: boolean
Returns void
Inherited from Behaviour.enabled

forward

get forward(): Vector3
Gets the forward direction vector (0,0,-1) of this component's GameObject in world space

Returns Vector3
Inherited from Behaviour.forward

layer

get layer(): number
The layer value of the GameObject this component is attached to Used for visibility and physics filtering

Returns number
Inherited from Behaviour.layer

name

get name(): string
The name of the GameObject this component is attached to Used for debugging and finding objects

Returns string
Inherited from Behaviour.name
set name(str: string): void
Parameters
- str: string
Returns void
Inherited from Behaviour.name

right

get right(): Vector3
Gets the right direction vector (1,0,0) of this component's GameObject in world space

Returns Vector3
Inherited from Behaviour.right

scene

get scene(): Scene
Shorthand accessor for the current scene from the context

Returns Scene
The scene this component belongs to

Inherited from Behaviour.scene

static

get static(): boolean
Indicates whether the GameObject is marked as static Static objects typically don't move and can be optimized by the engine

Returns boolean
Inherited from Behaviour.static
set static(value: boolean): void
Parameters
- value: boolean
Returns void
Inherited from Behaviour.static

up

get up(): Vector3
Gets the up direction vector (0,1,0) of this component's GameObject in world space

Returns Vector3
Inherited from Behaviour.up

worldEuler

get worldEuler(): Euler
Gets the rotation of this component's GameObject in world space as Euler angles (in radians)

Returns Euler
Inherited from Behaviour.worldEuler
set worldEuler(val: Euler): void
Sets the rotation of this component's GameObject in world space using Euler angles (in radians)
Parameters
- val: Euler
  The world rotation Euler angles to set
Returns void
Inherited from Behaviour.worldEuler

worldPosition

get worldPosition(): Vector3
Gets the position of this component's GameObject in world space

Returns Vector3
Inherited from Behaviour.worldPosition
set worldPosition(val: Vector3): void
Sets the position of this component's GameObject in world space
Parameters
- val: Vector3
  The world position vector to set
Returns void
Inherited from Behaviour.worldPosition

worldQuaternion

get worldQuaternion(): Quaternion
Gets the rotation of this component's GameObject in world space as a quaternion

Returns Quaternion
Inherited from Behaviour.worldQuaternion
set worldQuaternion(val: Quaternion): void
Sets the rotation of this component's GameObject in world space using a quaternion
Parameters
- val: Quaternion
  The world rotation quaternion to set
Returns void
Inherited from Behaviour.worldQuaternion

worldRotation

get worldRotation(): Vector3
Gets the rotation of this component's GameObject in world space as Euler angles (in degrees)

Returns Vector3
Inherited from Behaviour.worldRotation
set worldRotation(val: Vector3): void
Sets the rotation of this component's GameObject in world space using Euler angles (in degrees)
Parameters
- val: Vector3
  The world rotation vector to set (in degrees)
Returns void
Inherited from Behaviour.worldRotation

Methods

addEventListener

addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void
Registers an event listener for the specified event type
Type Parameters
- T extends Event
Parameters
- type: string
  The event type to listen for
- listener: (evt: T) => any
  The callback function to execute when the event occurs
Returns void
Inherited from Behaviour.addEventListener

awake

awake(): void
Called once when the component becomes active for the first time. This is the first lifecycle callback to be invoked

Returns void
Inherited from Behaviour.awake

destroy

destroy(): void
Destroys this component and removes it from its GameObject After destruction, the component will no longer receive lifecycle callbacks

Returns void
Inherited from Behaviour.destroy

dispatchEvent

dispatchEvent(evt: Event): boolean
Dispatches an event to all registered listeners
Parameters
- evt: Event
  The event object to dispatch
Returns boolean
Always returns false (standard implementation of EventTarget)

Inherited from Behaviour.dispatchEvent

download

download(blob: Blob, name: string): void
Downloads the given blob as a file.
Parameters
- blob: Blob
- name: string
Returns void

`Optional`earlyUpdate

earlyUpdate(): void
Called at the beginning of each frame before regular updates. Use for logic that needs to run before standard update callbacks.

Returns void
Inherited from Behaviour.earlyUpdate

export

export(
objectToExport: undefined | Object3D<Object3DEventMap>,
): Promise<null | Blob>
Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
Parameters
- objectToExport: undefined | Object3D<Object3DEventMap>
Returns Promise<null | Blob>
a Promise containing the USDZ file

exportAndOpen

exportAndOpen(): Promise<null | Blob>
Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.

Returns Promise<null | Blob>
a Promise containing the USDZ file

exportAsync

exportAsync(): Promise<null | Blob>
Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook. Use the various public properties of USDZExporter to customize export behaviour.

Returns Promise<null | Blob>
Deprecated
use exportAndOpen instead

getARScaleAndTarget

getARScaleAndTarget(): {
    _invertForward: boolean;
    scale: number;
    sessionRoot: null
    | Object3D<Object3DEventMap>;
    target: Object3D;
}
Returns {
    _invertForward: boolean;
    scale: number;
    sessionRoot: null | Object3D<Object3DEventMap>;
    target: Object3D;
}

`Optional`lateUpdate

lateUpdate(): void
Called after all update functions have been called. Use for calculations that depend on other components being updated first.

Returns void
Inherited from Behaviour.lateUpdate

`Optional`onAfterRender

onAfterRender(): void
Called after the scene has been rendered. Use for post-processing or UI updates that should happen after rendering

Returns void
Inherited from Behaviour.onAfterRender

`Optional`onBeforeRender

onBeforeRender(frame: null | XRFrame): void
Called immediately before the scene is rendered.
Parameters
- frame: null | XRFrame
  Current XRFrame if in an XR session, null otherwise
Returns void
Inherited from Behaviour.onBeforeRender

`Optional`onBeforeXR

onBeforeXR(mode: XRSessionMode, args: XRSessionInit): void
Called before an XR session is requested Use to modify session initialization parameters
Parameters
- mode: XRSessionMode
  The XR session mode being requested
- args: XRSessionInit
  The session initialization parameters that can be modified
Returns void
Inherited from Behaviour.onBeforeXR

`Optional`onCollisionEnter

onCollisionEnter(col: Collision): any
Called when this component's collider begins colliding with another collider.
Parameters
- col: Collision
  Information about the collision that occurred
Returns any
Inherited from Behaviour.onCollisionEnter

`Optional`onCollisionExit

onCollisionExit(col: Collision): any
Called when this component's collider stops colliding with another collider.
Parameters
- col: Collision
  Information about the collision that ended
Returns any
Inherited from Behaviour.onCollisionExit

`Optional`onCollisionStay

onCollisionStay(col: Collision): any
Called each frame while this component's collider is colliding with another collider
Parameters
- col: Collision
  Information about the ongoing collision
Returns any
Inherited from Behaviour.onCollisionStay

onDestroy

onDestroy(): void
Called when the component is destroyed. Use for cleanup operations like removing event listeners

Returns void
Inherited from Behaviour.onDestroy

`Optional`onEnterXR

onEnterXR(args: NeedleXREventArgs): void
Called when this component joins an XR session or becomes active in a running session
Parameters
- args: NeedleXREventArgs
  Event data for the XR session
Returns void
Inherited from Behaviour.onEnterXR

`Optional`onLeaveXR

onLeaveXR(args: NeedleXREventArgs): void
Called when this component exits an XR session or becomes inactive during a session
Parameters
- args: NeedleXREventArgs
  Event data for the XR session
Returns void
Inherited from Behaviour.onLeaveXR

`Optional`onPausedChanged

onPausedChanged(isPaused: boolean, wasPaused: boolean): void
Called when the context's pause state changes.
Parameters
- isPaused: boolean
  Whether the context is currently paused
- wasPaused: boolean
  The previous pause state
Returns void
Inherited from Behaviour.onPausedChanged

`Optional`onPointerClick

onPointerClick(args: PointerEventData): any
Called when a pointer completes a click interaction with this component's GameObject
Parameters
- args: PointerEventData
  Data about the pointer event
Returns any
Inherited from Behaviour.onPointerClick

`Optional`onPointerDown

onPointerDown(args: PointerEventData): any
Called when a pointer button is pressed while over this component's GameObject
Parameters
- args: PointerEventData
  Data about the pointer event
Returns any
Inherited from Behaviour.onPointerDown

`Optional`onPointerEnter

onPointerEnter(args: PointerEventData): any
Called when a pointer enters this component's GameObject
Parameters
- args: PointerEventData
  Data about the pointer event
Returns any
Inherited from Behaviour.onPointerEnter

`Optional`onPointerExit

onPointerExit(args: PointerEventData): any
Called when a pointer exits this component's GameObject
Parameters
- args: PointerEventData
  Data about the pointer event
Returns any
Inherited from Behaviour.onPointerExit

`Optional`onPointerMove

onPointerMove(args: PointerEventData): any
Called when a pointer moves while over this component's GameObject
Parameters
- args: PointerEventData
  Data about the pointer event
Returns any
Inherited from Behaviour.onPointerMove

`Optional`onPointerUp

onPointerUp(args: PointerEventData): any
Called when a pointer button is released while over this component's GameObject
Parameters
- args: PointerEventData
  Data about the pointer event
Returns any
Inherited from Behaviour.onPointerUp

`Optional`onTriggerEnter

onTriggerEnter(col: ICollider): any
Called when this component's trigger collider is entered by another collider
Parameters
- col: ICollider
  The collider that entered this trigger
Returns any
Inherited from Behaviour.onTriggerEnter

`Optional`onTriggerExit

onTriggerExit(col: ICollider): any
Called when another collider exits this component's trigger collider
Parameters
- col: ICollider
  The collider that exited this trigger
Returns any
Inherited from Behaviour.onTriggerExit

`Optional`onTriggerStay

onTriggerStay(col: ICollider): any
Called each frame while another collider is inside this component's trigger collider
Parameters
- col: ICollider
  The collider that is inside this trigger
Returns any
Inherited from Behaviour.onTriggerStay

`Optional`onUpdateXR

onUpdateXR(args: NeedleXREventArgs): void
Called each frame while this component is active in an XR session
Parameters
- args: NeedleXREventArgs
  Event data for the current XR frame
Returns void
Inherited from Behaviour.onUpdateXR

`Optional`onValidate

onValidate(prop?: string): void
Called when a field decorated with @validate() is modified.
Parameters
- Optionalprop: string
  The name of the field that was changed
Returns void
Inherited from Behaviour.onValidate

`Optional`onXRControllerAdded

onXRControllerAdded(args: NeedleXRControllerEventArgs): void
Called when an XR controller is connected or when this component becomes active in a session with existing controllers
Parameters
- args: NeedleXRControllerEventArgs
  Event data for the controller that was added
Returns void
Inherited from Behaviour.onXRControllerAdded

`Optional`onXRControllerRemoved

onXRControllerRemoved(args: NeedleXRControllerEventArgs): void
Called when an XR controller is disconnected or when this component becomes inactive during a session with controllers
Parameters
- args: NeedleXRControllerEventArgs
  Event data for the controller that was removed
Returns void
Inherited from Behaviour.onXRControllerRemoved

openInQuickLook

openInQuickLook(content: string | Blob, name: string): void
Opens QuickLook on iOS/iPadOS/visionOS with the given content in AR mode.
Parameters
- content: string | Blob
  The URL to the .usdz or .reality file or a blob containing an USDZ file.
- name: string
  Download filename
Returns void

removeEventListener

removeEventListener<T extends Event>(
type: string,
listener: (arg: T) => any,
): void
Removes a previously registered event listener
Type Parameters
- T extends Event
Parameters
- type: string
  The event type the listener was registered for
- listener: (arg: T) => any
  The callback function to remove
Returns void
Inherited from Behaviour.removeEventListener

`Optional`resolveGuids

resolveGuids(guidsMap: GuidsMap): void
Called when this component needs to remap guids after an instantiate operation.
Parameters
- guidsMap: GuidsMap
  Mapping from old guids to newly generated guids
Returns void
Inherited from Behaviour.resolveGuids

setWorldPosition

setWorldPosition(x: number, y: number, z: number): void
Sets the position of this component's GameObject in world space using individual coordinates
Parameters
- x: number
  X-coordinate in world space
- y: number
  Y-coordinate in world space
- z: number
  Z-coordinate in world space
Returns void
Inherited from Behaviour.setWorldPosition

setWorldQuaternion

setWorldQuaternion(x: number, y: number, z: number, w: number): void
Sets the rotation of this component's GameObject in world space using quaternion components
Parameters
- x: number
  X component of the quaternion
- y: number
  Y component of the quaternion
- z: number
  Z component of the quaternion
- w: number
  W component of the quaternion
Returns void
Inherited from Behaviour.setWorldQuaternion

setWorldRotation

setWorldRotation(x: number, y: number, z: number, degrees?: boolean): void
Sets the rotation of this component's GameObject in world space using individual Euler angles
Parameters
- x: number
  X-axis rotation
- y: number
  Y-axis rotation
- z: number
  Z-axis rotation
- degrees: boolean = true
  Whether the values are in degrees (true) or radians (false)
Returns void
Inherited from Behaviour.setWorldRotation

startCoroutine

startCoroutine(routine: Generator, evt?: FrameEvent): Generator
Starts a coroutine that can yield to wait for events. Coroutines allow for time-based sequencing of operations without blocking. Coroutines are based on generator functions, a JavaScript language feature.
Parameters
- routine: Generator
  Generator function to start
- evt: FrameEvent = FrameEvent.Update
  Event to register the coroutine for (default: FrameEvent.Update)
Returns Generator
The generator function that can be used to stop the coroutine
Example
Time-based sequencing of operations
```
*myCoroutine() {
  yield WaitForSeconds(1); // wait for 1 second
  yield WaitForFrames(10); // wait for 10 frames
  yield new Promise(resolve => setTimeout(resolve, 1000)); // wait for a promise to resolve
}
```
Example
Coroutine that logs a message every 5 frames
```
onEnable() {
  this.startCoroutine(this.myCoroutine());
}
private *myCoroutine() {
  while(this.activeAndEnabled) {
    console.log("Hello World", this.context.time.frame);
    // wait for 5 frames
    for(let i = 0; i < 5; i++) yield;
  }
}
```
Inherited from Behaviour.startCoroutine

stopCoroutine

stopCoroutine(routine: Generator, evt?: FrameEvent): void
Stops a coroutine that was previously started with startCoroutine
Parameters
- routine: Generator
  The routine to be stopped
- evt: FrameEvent = FrameEvent.Update
  The frame event the routine was registered with
Returns void
Inherited from Behaviour.stopCoroutine

`Optional`supportsXR

supportsXR(mode: XRSessionMode): boolean
Determines if this component supports a specific XR mode
Parameters
- mode: XRSessionMode
  The XR session mode to check support for
Returns boolean
True if the component supports the specified mode

Inherited from Behaviour.supportsXR

`Optional`update

update(): void
Called once per frame during the main update loop. The primary location for frame-based game logic.

Returns void
Inherited from Behaviour.update

Class USDZExporter

Example

Hierarchy (View Summary)

Index

Properties

Accessors

Methods

Properties

autoExportAnimations

autoExportAudioSources

extensions

gameObject

guid

interactive

objectToExport

physics

OptionalsourceId

Accessors

activeAndEnabled

Returns boolean

context

Returns Context

Parameters

Returns void

destroyed

Returns boolean

enabled

Returns boolean

Parameters

Returns void

forward

Returns Vector3

layer

Returns number

name

Returns string

Parameters

Returns void

right

Returns Vector3

scene

Returns Scene

static

Returns boolean

Parameters

Returns void

tag

Returns string

Parameters

Returns void

up

Returns Vector3

worldEuler

Returns Euler

Parameters

Returns void

worldPosition

Returns Vector3

Parameters

Returns void

worldQuaternion

Returns Quaternion

Parameters

Returns void

worldRotation

Returns Vector3

Parameters

Returns void

Methods

addEventListener

Type Parameters

Parameters

Returns void

awake

Returns void

destroy

Returns void

dispatchEvent

Parameters

Returns boolean

`Optional`sourceId

`Optional`earlyUpdate

Returns {
_invertForward: boolean;
scale: number;
sessionRoot: null | Object3D<Object3DEventMap>;
target: Object3D;
}

`Optional`lateUpdate

`Optional`onAfterRender

`Optional`onBeforeRender

`Optional`onBeforeXR

`Optional`onCollisionEnter

`Optional`onCollisionExit

`Optional`onCollisionStay

`Optional`onEnterXR

`Optional`onLeaveXR

`Optional`onPausedChanged

`Optional`onPointerClick

`Optional`onPointerDown

`Optional`onPointerEnter

`Optional`onPointerExit

`Optional`onPointerMove

`Optional`onPointerUp

`Optional`onTriggerEnter

`Optional`onTriggerExit

`Optional`onTriggerStay