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

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

@@ -49,18 +49,25 @@ export class WebARSessionRoot extends Behaviour {
         }
     }
 
+    private static _hasPlaced: boolean = false;
+    /**
+     * @returns true if the scene has been placed in AR by the user or automatic placement
+     */
+    static get hasPlaced(): boolean {
+        return this._hasPlaced;
+    }
+
 
-    /** The scale of a user in AR:  
-     * Note: a large value makes the scene appear smaller  
+    /** The scale of the user in AR.  
+     * **NOTE**: a large value makes the scene appear smaller  
      * @default 1
      */
     get arScale(): number {
         return this._arScale;
     }
     set arScale(val: number) {
-        if (val === this._arScale) return;
-        this._arScale = val;
-        this.onScaleChanged();
+        this._arScale = Math.max(0.000001, val);
+        this.onSetScale();
     }
     private _arScale: number = 1;
 
@@ -134,6 +141,7 @@ export class WebARSessionRoot extends Behaviour {
         if (debug) console.log("ENTER WEBXR: SessionRoot start...");
 
         this._anchor = null;
+        WebARSessionRoot._hasPlaced = false;
 
         // if (_args.xr.session.enabledFeatures?.includes("image-tracking")) {
         //     console.warn("Image tracking is enabled - will not place scene");
@@ -193,6 +201,7 @@ export class WebARSessionRoot extends Behaviour {
         this.onRevertSceneChanges();
         // this._anchor?.delete();
         this._anchor = null;
+        WebARSessionRoot._hasPlaced = false;
         this._rigPlacementMatrix = undefined;
     }
     onUpdateXR(args: NeedleXREventArgs): void {
@@ -405,6 +414,7 @@ export class WebARSessionRoot extends Behaviour {
         reticle.quaternion.copy(reticle["lastQuat"]);
 
         this.onApplyPose(reticle);
+        WebARSessionRoot._hasPlaced = true;
 
         if (this.useXRAnchor) {
             this.onCreateAnchor(NeedleXRSession.active!, hit);
@@ -417,8 +427,16 @@ export class WebARSessionRoot extends Behaviour {
         }
     }
 
-    private onScaleChanged() {
-        // TODO: implement
+    private onSetScale() {
+        if (!WebARSessionRoot._hasPlaced) return;
+        const rig = NeedleXRSession.active?.rig?.gameObject;
+        if (rig) {
+            const currentScale = NeedleXRSession.active?.rigScale || 1;
+            const newScale = (1 / this._arScale) * currentScale;
+            const scaleMatrix = new Matrix4().makeScale(newScale, newScale, newScale).invert();
+            rig.matrix.premultiply(scaleMatrix);
+            rig.matrix.decompose(rig.position, rig.quaternion, rig.scale);
+        }
     }
 
     private onRevertSceneChanges() {
@@ -516,7 +534,7 @@ export class WebARSessionRoot extends Behaviour {
             console.warn("No rig object to place");
             return;
         }
-        const rigScale = NeedleXRSession.active?.rigScale || 1;
+        // const rigScale = NeedleXRSession.active?.rigScale || 1;
 
         // save the previous rig parent
         const previousParent = rigObject.parent || this.context.scene;
@@ -578,6 +596,10 @@ class WebXRSessionRootUserInput {
     private _scale: number = 1;
     private _hasChanged: boolean = false;
 
+    get scale() {
+        return this._scale;
+    }
+
     // readonly translate: Vector3 = new Vector3();
     // readonly rotation: Quaternion = new Quaternion();
     // readonly scale: Vector3 = new Vector3(1, 1, 1);
@@ -594,6 +616,7 @@ class WebXRSessionRootUserInput {
     reset() {
         this._scale = 1;
         this.offset.identity();
+        this._hasChanged = true;
     }
     get hasChanged() { return this._hasChanged; }
 

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);