@needle-tools/engine 4.3.0-alpha.1 → 4.3.0-alpha.4

package/src/engine-components/webxr/WebXR.ts

@@ -58,7 +58,7 @@ export class WebXR extends Behaviour {
 
     // VR Settings
     /**
-     * When enabled, default movement controls will be automatically added to the scene when entering VR.
+     * 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.
      */
     @serializable()
@@ -96,14 +96,14 @@ export class WebXR extends Behaviour {
     usePlacementAdjustment: boolean = true;
 
     /**
-     * Determines the scale of the user relative to the scene in AR. Larger values make the 3D content appear smaller.
+     * 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.
      */
     @serializable()
     arScale: number = 1;
 
     /**
-     * When enabled, an XRAnchor will be created for the AR scene and its position will be regularly updated to match the anchor.
+     * 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
      */
@@ -118,21 +118,21 @@ export class WebXR extends Behaviour {
     autoPlace: boolean = false;
 
     /**
-     * When enabled, the AR session root center will be automatically adjusted to place the center of the scene.
+     * 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.
      */
     @serializable()
     autoCenter: boolean = false;
 
     /**
-     * When enabled, a USDZExporter component will be automatically added to the scene if none is found.
+     * 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.
      */
     @serializable()
     useQuicklookExport: boolean = false;
 
     /**
-     * When enabled, the 'depth-sensing' WebXR feature will be requested to provide real-time depth occlusion.
+     * 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
@@ -141,7 +141,7 @@ export class WebXR extends Behaviour {
     useDepthSensing: boolean = false;
 
     /**
-     * When enabled, a {@link SpatialGrabRaycaster} will be added or enabled in the scene,
+     * 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
      */
@@ -149,7 +149,7 @@ export class WebXR extends Behaviour {
     useSpatialGrab: boolean = true;
 
     /**
-     * Specifies the avatar representation that will be created when entering a WebXR session.
+     * 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.
      */
     @serializable(AssetReference)
@@ -166,6 +166,7 @@ export class WebXR extends Behaviour {
 
     /**
      * Initializes the WebXR component by obtaining the XR sync object for this context.
+     * @internal
      */
     awake() {
         NeedleXRSession.getXRSync(this.context);
@@ -174,6 +175,7 @@ export class WebXR extends Behaviour {
     /**
      * 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 {
         // check if we're on a secure connection:
@@ -216,6 +218,7 @@ export class WebXR extends Behaviour {
     /**
      * Cleans up resources when the component is disabled.
      * Destroys the USDZ exporter if one was created and removes UI buttons.
+     * @internal
      */
     onDisable(): void {
         this._usdzExporter?.destroy();
@@ -251,23 +254,40 @@ export class WebXR extends Behaviour {
     get sessionMode(): XRSessionMode | null {
         return NeedleXRSession.activeMode ?? 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() {
+        return this._activeWebARSessionRoot;
+    }
 
-    /** Call to start an WebVR session */
+    /** Call to start an WebVR session.     
+     * 
+     * This is a shorthand for `NeedleXRSession.start("immersive-vr", init, this.context)`
+    */
     async enterVR(init?: XRSessionInit): Promise<NeedleXRSession | null> {
         return NeedleXRSession.start("immersive-vr", init, this.context);
     }
-    /** Call to start an WebAR session */
+    /** Call to start an WebAR session   
+     * 
+     * This is a shorthand for `NeedleXRSession.start("immersive-ar", init, this.context)`
+    */
     async enterAR(init?: XRSessionInit): Promise<NeedleXRSession | null> {
         return NeedleXRSession.start("immersive-ar", init, this.context);
     }
-    /** Call to end a WebXR (AR or VR) session */
+
+    /** Call to end a WebXR (AR or VR) session.   
+     * 
+     * This is a shorthand for `NeedleXRSession.stop()`
+     */
     exitXR() {
         NeedleXRSession.stop();
     }
 
-        private _exitXRMenuButton?: HTMLElement;
+    private _exitXRMenuButton?: HTMLElement;
     private _previousXRState: number = 0;
     private _spatialGrabRaycaster?: SpatialGrabRaycaster;
+    private _activeWebARSessionRoot: WebARSessionRoot | null = null;
 
     private get isActiveWebXR() {
         return !WebXR.activeWebXRComponent || WebXR.activeWebXRComponent === this;
@@ -277,6 +297,7 @@ export class WebXR extends Behaviour {
      * 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 {
         if (!this.isActiveWebXR) {
@@ -295,6 +316,7 @@ export class WebXR extends Behaviour {
      * 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
      */
     async onEnterXR(args: NeedleXREventArgs) {
         if (!this.isActiveWebXR) return;
@@ -323,6 +345,7 @@ export class WebXR extends Behaviour {
                 }
             }
 
+            this._activeWebARSessionRoot = sessionroot;
             if (sessionroot) {
                 // sessionroot.enabled = this.usePlacementReticle; // < not sure if we want to disable the session root when placement reticle if OFF...
                 sessionroot.customReticle = this.customARPlacementReticle;
@@ -371,6 +394,7 @@ export class WebXR extends Behaviour {
      * 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 {
         if (!this.isActiveWebXR) return;
@@ -383,6 +407,7 @@ export class WebXR extends Behaviour {
      * 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 {
         this._exitXRMenuButton?.remove();
@@ -399,6 +424,8 @@ export class WebXR extends Behaviour {
         }
         this._createdComponentsInSession.length = 0;
 
+        this._activeWebARSessionRoot = null;
+
         this.handleOfferSession();
 
         delayForFrames(1).then(() => WebXR.activeWebXRComponent = null);