@needle-tools/engine 4.5.0-alpha.6 → 4.5.0

package/lib/engine-components/webxr/WebXR.d.ts

@@ -1,232 +1,232 @@
-/// <reference types="webxr" />
-import { AssetReference } from "../../engine/engine_addressables.js";
-import { type NeedleXREventArgs, NeedleXRSession } from "../../engine/engine_xr.js";
-import { WebXRButtonFactory } from "../../engine/webcomponents/WebXRButtons.js";
-import { Behaviour } from "../Component.js";
-import { XRControllerModel } from "./controllers/XRControllerModel.js";
-import { XRControllerMovement } from "./controllers/XRControllerMovement.js";
-import { WebARSessionRoot } from "./WebARSessionRoot.js";
-/**
- * WebXR component to enable VR, AR and Quicklook on iOS in your scene.
- * It provides a simple wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons or enabling default movement behaviour.
- * @category XR
- * @group Components
- */
-export declare class WebXR extends Behaviour {
-    /**
-     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter VR mode.
-     */
-    createVRButton: boolean;
-    /**
-     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter AR mode.
-     */
-    createARButton: boolean;
-    /**
-     * When enabled, a button to send the experience to an Oculus Quest will be shown if the current device does not support VR.
-     * This helps direct users to compatible devices for optimal VR experiences.
-     */
-    createSendToQuestButton: boolean;
-    /**
-     * When enabled, a QR code will be generated and displayed on desktop devices to allow easy opening of the experience on mobile devices.
-     */
-    createQRCode: boolean;
-    /**
-     * When enabled, default movement controls will be automatically added to the scene when entering VR.
-     * This includes teleportation and smooth locomotion options for VR controllers.
-     */
-    useDefaultControls: boolean;
-    /**
-     * When enabled, 3D models representing the user's VR controllers will be automatically created and rendered in the scene.
-     */
-    showControllerModels: boolean;
-    /**
-     * When enabled, 3D models representing the user's hands will be automatically created and rendered when hand tracking is available.
-     */
-    showHandModels: boolean;
-    /**
-     * When enabled, a reticle will be displayed to help place the scene in AR. The user must tap on a detected surface to position the scene.
-     */
-    usePlacementReticle: boolean;
-    /**
-     * Optional custom 3D object to use as the AR placement reticle instead of the default one.
-     */
-    customARPlacementReticle?: AssetReference;
-    /**
-     * When enabled, users can adjust the position, rotation, and scale of the AR scene with one or two fingers after initial placement.
-     */
-    usePlacementAdjustment: boolean;
-    /**
-     * Determines the scale of the user relative to the scene in AR. Larger values make the 3D content appear smaller.
-     * Only applies when `usePlacementReticle` is enabled.
-     */
-    arScale: number;
-    /**
-     * When enabled, an XRAnchor will be created for the AR scene and its position will be regularly updated to match the anchor.
-     * This can help with spatial persistence in AR experiences.
-     * @experimental
-     */
-    useXRAnchor: boolean;
-    /**
-     * When enabled, the scene will be automatically placed as soon as a suitable surface is detected in AR,
-     * without requiring the user to tap to confirm placement.
-     */
-    autoPlace: boolean;
-    /**
-     * When enabled, the AR session root center will be automatically adjusted to place the center of the scene.
-     * This helps ensure the scene is properly aligned with detected surfaces.
-     */
-    autoCenter: boolean;
-    /**
-     * When enabled, a USDZExporter component will be automatically added to the scene if none is found.
-     * This allows iOS and visionOS devices to view 3D content using Apple's AR QuickLook.
-     */
-    useQuicklookExport: boolean;
-    /**
-     * When enabled, the 'depth-sensing' WebXR feature will be requested to provide real-time depth occlusion.
-     * Currently only supported on Oculus Quest devices.
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/XRDepthInformation
-     * @experimental
-     */
-    useDepthSensing: boolean;
-    /**
-     * When enabled, a {@link SpatialGrabRaycaster} will be added or enabled in the scene,
-     * allowing users to interact with objects at a distance in VR/AR.
-     * @default true
-     */
-    useSpatialGrab: boolean;
-    /**
-     * Specifies the avatar representation that will be created when entering a WebXR session.
-     * Can be a reference to a 3D model or a boolean to use the default avatar.
-     */
-    defaultAvatar?: AssetReference | boolean;
-    private _playerSync?;
-    /** these components were created by the WebXR component on session start and will be cleaned up again in session end */
-    private readonly _createdComponentsInSession;
-    private _usdzExporter?;
-    static activeWebXRComponent: WebXR | null;
-    /**
-     * Initializes the WebXR component by obtaining the XR sync object for this context.
-     * @internal
-     */
-    awake(): void;
-    /**
-     * Sets up the WebXR component when it's enabled. Checks for HTTPS connection,
-     * sets up USDZ export if enabled, creates UI buttons, and configures avatar settings.
-     * @internal
-     */
-    onEnable(): void;
-    /**
-     * Cleans up resources when the component is disabled.
-     * Destroys the USDZ exporter if one was created and removes UI buttons.
-     * @internal
-     */
-    onDisable(): void;
-    /**
-     * Checks if WebXR is supported and offers an appropriate session.
-     * This is used to show the WebXR session joining prompt in browsers that support it.
-     * @returns A Promise that resolves to true if a session was offered, false otherwise
-     */
-    private handleOfferSession;
-    /** the currently active webxr input session */
-    get session(): NeedleXRSession | null;
-    /** immersive-vr or immersive-ar */
-    get sessionMode(): XRSessionMode | null;
-    /** While AR: this will return the currently active WebARSessionRoot component.
-     * You can also query this component in your scene with `findObjectOfType(WebARSessionRoot)`
-     */
-    get arSessionRoot(): WebARSessionRoot | null;
-    /** Call to start an WebVR session.
-     *
-     * This is a shorthand for `NeedleXRSession.start("immersive-vr", init, this.context)`
-    */
-    enterVR(init?: XRSessionInit): Promise<NeedleXRSession | null>;
-    /** Call to start an WebAR session
-     *
-     * This is a shorthand for `NeedleXRSession.start("immersive-ar", init, this.context)`
-    */
-    enterAR(init?: XRSessionInit): Promise<NeedleXRSession | null>;
-    /** Call to end a WebXR (AR or VR) session.
-     *
-     * This is a shorthand for `NeedleXRSession.stop()`
-     */
-    exitXR(): void;
-    private _exitXRMenuButton?;
-    private _previousXRState;
-    private _spatialGrabRaycaster?;
-    private _activeWebARSessionRoot;
-    private get isActiveWebXR();
-    /**
-     * Called before entering a WebXR session. Sets up optional features like depth sensing, if needed.
-     * @param _mode The XR session mode being requested (immersive-ar or immersive-vr)
-     * @param args The XRSessionInit object that will be passed to the WebXR API
-     * @internal
-     */
-    onBeforeXR(_mode: XRSessionMode, args: XRSessionInit): void;
-    /**
-     * Called when a WebXR session begins. Sets up the scene for XR by configuring controllers,
-     * AR placement, and other features based on component settings.
-     * @param args Event arguments containing information about the started XR session
-     * @internal
-     */
-    onEnterXR(args: NeedleXREventArgs): Promise<void>;
-    /**
-     * Called every frame during an active WebXR session.
-     * Updates components that depend on the current XR state.
-     * @param _args Event arguments containing information about the current XR session frame
-     * @internal
-     */
-    onUpdateXR(_args: NeedleXREventArgs): void;
-    /**
-     * Called when a WebXR session ends. Restores pre-session state,
-     * removes temporary components, and cleans up resources.
-     * @param _ Event arguments containing information about the ended XR session
-     * @internal
-     */
-    onLeaveXR(_: NeedleXREventArgs): void;
-    /** Call to enable or disable default controller behaviour */
-    setDefaultMovementEnabled(enabled: boolean): XRControllerMovement | null;
-    /** Call to enable or disable default controller rendering */
-    setDefaultControllerRenderingEnabled(enabled: boolean): XRControllerModel | null;
-    /**
-     * Creates and instantiates the user's avatar representation in the WebXR session.
-     * @param xr The active session
-     */
-    protected createLocalAvatar(xr: NeedleXRSession): Promise<void>;
-    /**
-     * Event handler called when a player avatar is spawned.
-     * Ensures the avatar has the necessary Avatar component.
-     * @param instance The spawned avatar 3D object
-     */
-    private onAvatarSpawned;
-    /** @deprecated use {@link getButtonsFactory} or directly access {@link WebXRButtonFactory.getOrCreate} */
-    getButtonsContainer(): WebXRButtonFactory;
-    /**
-     * Returns the WebXR button factory, creating one if it doesn't exist.
-     * Use this to access and modify WebXR UI buttons.
-     * @returns The WebXRButtonFactory instance
-     */
-    getButtonsFactory(): WebXRButtonFactory;
-    /**
-     * Reference to the WebXR button factory used by this component.
-     */
-    private _buttonFactory?;
-    /**
-     * Creates and sets up UI elements for WebXR interaction based on component settings
-     * and device capabilities. Handles creating AR, VR, QuickLook buttons and utility buttons like QR codes.
-     */
-    private handleCreatingHTML;
-    /**
-     * Storage for UI buttons created by this component.
-     */
-    private readonly _buttons;
-    /**
-     * Adds a button to the UI with the specified priority.
-     * @param button The HTML element to add
-     * @param priority The button's priority value (lower numbers appear first)
-     */
-    private addButton;
-    /**
-     * Removes all buttons created by this component from the UI.
-     */
-    private removeButtons;
-}
+/// <reference types="webxr" />
+import { AssetReference } from "../../engine/engine_addressables.js";
+import { type NeedleXREventArgs, NeedleXRSession } from "../../engine/engine_xr.js";
+import { WebXRButtonFactory } from "../../engine/webcomponents/WebXRButtons.js";
+import { Behaviour } from "../Component.js";
+import { XRControllerModel } from "./controllers/XRControllerModel.js";
+import { XRControllerMovement } from "./controllers/XRControllerMovement.js";
+import { WebARSessionRoot } from "./WebARSessionRoot.js";
+/**
+ * WebXR component to enable VR, AR and Quicklook on iOS in your scene.
+ * It provides a simple wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons or enabling default movement behaviour.
+ * @category XR
+ * @group Components
+ */
+export declare class WebXR extends Behaviour {
+    /**
+     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter VR mode.
+     */
+    createVRButton: boolean;
+    /**
+     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter AR mode.
+     */
+    createARButton: boolean;
+    /**
+     * When enabled, a button to send the experience to an Oculus Quest will be shown if the current device does not support VR.
+     * This helps direct users to compatible devices for optimal VR experiences.
+     */
+    createSendToQuestButton: boolean;
+    /**
+     * When enabled, a QR code will be generated and displayed on desktop devices to allow easy opening of the experience on mobile devices.
+     */
+    createQRCode: boolean;
+    /**
+     * When enabled, default movement controls will be automatically added to the scene when entering VR.
+     * This includes teleportation and smooth locomotion options for VR controllers.
+     */
+    useDefaultControls: boolean;
+    /**
+     * When enabled, 3D models representing the user's VR controllers will be automatically created and rendered in the scene.
+     */
+    showControllerModels: boolean;
+    /**
+     * When enabled, 3D models representing the user's hands will be automatically created and rendered when hand tracking is available.
+     */
+    showHandModels: boolean;
+    /**
+     * When enabled, a reticle will be displayed to help place the scene in AR. The user must tap on a detected surface to position the scene.
+     */
+    usePlacementReticle: boolean;
+    /**
+     * Optional custom 3D object to use as the AR placement reticle instead of the default one.
+     */
+    customARPlacementReticle?: AssetReference;
+    /**
+     * When enabled, users can adjust the position, rotation, and scale of the AR scene with one or two fingers after initial placement.
+     */
+    usePlacementAdjustment: boolean;
+    /**
+     * Determines the scale of the user relative to the scene in AR. Larger values make the 3D content appear smaller.
+     * Only applies when `usePlacementReticle` is enabled.
+     */
+    arScale: number;
+    /**
+     * When enabled, an XRAnchor will be created for the AR scene and its position will be regularly updated to match the anchor.
+     * This can help with spatial persistence in AR experiences.
+     * @experimental
+     */
+    useXRAnchor: boolean;
+    /**
+     * When enabled, the scene will be automatically placed as soon as a suitable surface is detected in AR,
+     * without requiring the user to tap to confirm placement.
+     */
+    autoPlace: boolean;
+    /**
+     * When enabled, the AR session root center will be automatically adjusted to place the center of the scene.
+     * This helps ensure the scene is properly aligned with detected surfaces.
+     */
+    autoCenter: boolean;
+    /**
+     * When enabled, a USDZExporter component will be automatically added to the scene if none is found.
+     * This allows iOS and visionOS devices to view 3D content using Apple's AR QuickLook.
+     */
+    useQuicklookExport: boolean;
+    /**
+     * When enabled, the 'depth-sensing' WebXR feature will be requested to provide real-time depth occlusion.
+     * Currently only supported on Oculus Quest devices.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/XRDepthInformation
+     * @experimental
+     */
+    useDepthSensing: boolean;
+    /**
+     * When enabled, a {@link SpatialGrabRaycaster} will be added or enabled in the scene,
+     * allowing users to interact with objects at a distance in VR/AR.
+     * @default true
+     */
+    useSpatialGrab: boolean;
+    /**
+     * Specifies the avatar representation that will be created when entering a WebXR session.
+     * Can be a reference to a 3D model or a boolean to use the default avatar.
+     */
+    defaultAvatar?: AssetReference | boolean;
+    private _playerSync?;
+    /** these components were created by the WebXR component on session start and will be cleaned up again in session end */
+    private readonly _createdComponentsInSession;
+    private _usdzExporter?;
+    static activeWebXRComponent: WebXR | null;
+    /**
+     * Initializes the WebXR component by obtaining the XR sync object for this context.
+     * @internal
+     */
+    awake(): void;
+    /**
+     * Sets up the WebXR component when it's enabled. Checks for HTTPS connection,
+     * sets up USDZ export if enabled, creates UI buttons, and configures avatar settings.
+     * @internal
+     */
+    onEnable(): void;
+    /**
+     * Cleans up resources when the component is disabled.
+     * Destroys the USDZ exporter if one was created and removes UI buttons.
+     * @internal
+     */
+    onDisable(): void;
+    /**
+     * Checks if WebXR is supported and offers an appropriate session.
+     * This is used to show the WebXR session joining prompt in browsers that support it.
+     * @returns A Promise that resolves to true if a session was offered, false otherwise
+     */
+    private handleOfferSession;
+    /** the currently active webxr input session */
+    get session(): NeedleXRSession | null;
+    /** immersive-vr or immersive-ar */
+    get sessionMode(): XRSessionMode | null;
+    /** While AR: this will return the currently active WebARSessionRoot component.
+     * You can also query this component in your scene with `findObjectOfType(WebARSessionRoot)`
+     */
+    get arSessionRoot(): WebARSessionRoot | null;
+    /** Call to start an WebVR session.
+     *
+     * This is a shorthand for `NeedleXRSession.start("immersive-vr", init, this.context)`
+    */
+    enterVR(init?: XRSessionInit): Promise<NeedleXRSession | null>;
+    /** Call to start an WebAR session
+     *
+     * This is a shorthand for `NeedleXRSession.start("immersive-ar", init, this.context)`
+    */
+    enterAR(init?: XRSessionInit): Promise<NeedleXRSession | null>;
+    /** Call to end a WebXR (AR or VR) session.
+     *
+     * This is a shorthand for `NeedleXRSession.stop()`
+     */
+    exitXR(): void;
+    private _exitXRMenuButton?;
+    private _previousXRState;
+    private _spatialGrabRaycaster?;
+    private _activeWebARSessionRoot;
+    private get isActiveWebXR();
+    /**
+     * Called before entering a WebXR session. Sets up optional features like depth sensing, if needed.
+     * @param _mode The XR session mode being requested (immersive-ar or immersive-vr)
+     * @param args The XRSessionInit object that will be passed to the WebXR API
+     * @internal
+     */
+    onBeforeXR(_mode: XRSessionMode, args: XRSessionInit): void;
+    /**
+     * Called when a WebXR session begins. Sets up the scene for XR by configuring controllers,
+     * AR placement, and other features based on component settings.
+     * @param args Event arguments containing information about the started XR session
+     * @internal
+     */
+    onEnterXR(args: NeedleXREventArgs): Promise<void>;
+    /**
+     * Called every frame during an active WebXR session.
+     * Updates components that depend on the current XR state.
+     * @param _args Event arguments containing information about the current XR session frame
+     * @internal
+     */
+    onUpdateXR(_args: NeedleXREventArgs): void;
+    /**
+     * Called when a WebXR session ends. Restores pre-session state,
+     * removes temporary components, and cleans up resources.
+     * @param _ Event arguments containing information about the ended XR session
+     * @internal
+     */
+    onLeaveXR(_: NeedleXREventArgs): void;
+    /** Call to enable or disable default controller behaviour */
+    setDefaultMovementEnabled(enabled: boolean): XRControllerMovement | null;
+    /** Call to enable or disable default controller rendering */
+    setDefaultControllerRenderingEnabled(enabled: boolean): XRControllerModel | null;
+    /**
+     * Creates and instantiates the user's avatar representation in the WebXR session.
+     * @param xr The active session
+     */
+    protected createLocalAvatar(xr: NeedleXRSession): Promise<void>;
+    /**
+     * Event handler called when a player avatar is spawned.
+     * Ensures the avatar has the necessary Avatar component.
+     * @param instance The spawned avatar 3D object
+     */
+    private onAvatarSpawned;
+    /** @deprecated use {@link getButtonsFactory} or directly access {@link WebXRButtonFactory.getOrCreate} */
+    getButtonsContainer(): WebXRButtonFactory;
+    /**
+     * Returns the WebXR button factory, creating one if it doesn't exist.
+     * Use this to access and modify WebXR UI buttons.
+     * @returns The WebXRButtonFactory instance
+     */
+    getButtonsFactory(): WebXRButtonFactory;
+    /**
+     * Reference to the WebXR button factory used by this component.
+     */
+    private _buttonFactory?;
+    /**
+     * Creates and sets up UI elements for WebXR interaction based on component settings
+     * and device capabilities. Handles creating AR, VR, QuickLook buttons and utility buttons like QR codes.
+     */
+    private handleCreatingHTML;
+    /**
+     * Storage for UI buttons created by this component.
+     */
+    private readonly _buttons;
+    /**
+     * Adds a button to the UI with the specified priority.
+     * @param button The HTML element to add
+     * @param priority The button's priority value (lower numbers appear first)
+     */
+    private addButton;
+    /**
+     * Removes all buttons created by this component from the UI.
+     */
+    private removeButtons;
+}