@needle-tools/engine 4.3.0-alpha → 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

@@ -31,74 +31,127 @@ const debugQuicklook = getParam("debugusdz");
 export class WebXR extends Behaviour {
 
     // UI
-    /** When enabled a button will be added to the UI to enter VR */
+    /**
+     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter VR mode.
+     */
     @serializable()
     createVRButton: boolean = true;
-    /** When enabled a button will be added to the UI to enter AR */
+
+    /**
+     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter AR mode.
+     */
     @serializable()
     createARButton: boolean = true;
-    /** When enabled a send to quest button will be shown if the device does not support VR */
+
+    /**
+     * 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.
+     */
     @serializable()
     createSendToQuestButton: boolean = true;
-    /** When enabled a QRCode will be created to open the website on a mobile device */
+
+    /**
+     * When enabled, a QR code will be generated and displayed on desktop devices to allow easy opening of the experience on mobile devices.
+     */
     @serializable()
     createQRCode: boolean = true;
 
     // VR Settings
-    /** When enabled default movement behaviour will be added */
+    /**
+     * 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()
     useDefaultControls: boolean = true;
-    /** When enabled controller models will automatically be created and updated when you are using controllers in WebXR */
+
+    /**
+     * When enabled, 3D models representing the user's VR controllers will be automatically created and rendered in the scene.
+     */
     @serializable()
     showControllerModels: boolean = true;
-    /** When enabled hand models will automatically be created and updated when you are using hands in WebXR */
+
+    /**
+     * When enabled, 3D models representing the user's hands will be automatically created and rendered when hand tracking is available.
+     */
     @serializable()
     showHandModels: boolean = true;
 
     // AR Settings
-    /** When enabled the scene must be placed in AR */
+    /**
+     * 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.
+     */
     @serializable()
     usePlacementReticle: boolean = true;
-    /** When assigned this object will be used as the AR placement reticle */
+
+    /**
+     * Optional custom 3D object to use as the AR placement reticle instead of the default one.
+     */
     @serializable(AssetReference)
     customARPlacementReticle?: AssetReference;
-    /** When enabled you can position, rotate or scale your AR scene with one or two fingers */
+
+    /**
+     * When enabled, users can adjust the position, rotation, and scale of the AR scene with one or two fingers after initial placement.
+     */
     @serializable()
     usePlacementAdjustment: boolean = true;
-    /** Used when `usePlacementReticle` is enabled. This is the scale of the user in 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;
-    /** Experimental: When enabled an XRAnchor will be created for the AR scene and the position will be updated to the anchor position every few frames */
+
+    /**
+     * 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
+     */
     @serializable()
     useXRAnchor: boolean = false;
+
     /**
-     * When enabled the scene will be placed automatically when a point in the real world is found
+     * 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.
      */
     @serializable()
-    autoPlace: boolean = true;
-    /** When enabled the AR session root center will be automatically adjusted to place the center of the scene */
+    autoPlace: boolean = false;
+
+    /**
+     * 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 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;
 
-
-    /** Preview feature enabling occlusion (when available: https://github.com/cabanier/three.js/commit/b6ee92bcd8f20718c186120b7f19a3b68a1d4e47)
-     * Enables the 'depth-sensing' WebXR feature to provide realtime depth occlusion. Only supported on Oculus Quest right now.
+    /**
+     * 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
      */
     @serializable()
     useDepthSensing: boolean = false;
 
     /**
-     * When enabled the spatial grab raycaster 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
      */
     @serializable()
     useSpatialGrab: boolean = true;
 
-    /** This avatar representation will be spawned when you enter 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)
     defaultAvatar?: AssetReference | boolean;
 
@@ -111,10 +164,19 @@ export class WebXR extends Behaviour {
 
     static activeWebXRComponent: WebXR | null = null;
 
+    /**
+     * Initializes the WebXR component by obtaining the XR sync object for this context.
+     * @internal
+     */
     awake() {
         NeedleXRSession.getXRSync(this.context);
     }
 
+    /**
+     * 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:
         if (window.location.protocol !== "https:") {
@@ -153,11 +215,21 @@ 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();
         this.removeButtons();
     }
 
+    /**
+     * 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 async handleOfferSession() {
         if (this.createVRButton) {
             const hasVRSupport = await NeedleXRSession.isVRSupported();
@@ -182,16 +254,32 @@ 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();
     }
@@ -199,11 +287,18 @@ export class WebXR extends Behaviour {
     private _exitXRMenuButton?: HTMLElement;
     private _previousXRState: number = 0;
     private _spatialGrabRaycaster?: SpatialGrabRaycaster;
+    private _activeWebARSessionRoot: WebARSessionRoot | null = null;
 
     private get isActiveWebXR() {
         return !WebXR.activeWebXRComponent || WebXR.activeWebXRComponent === this;
     }
 
+    /**
+     * 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) {
             console.warn(`WebXR: another WebXR component is already active (${WebXR.activeWebXRComponent?.name}). This is ignored: ${this.name}`);
@@ -217,6 +312,12 @@ 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;
 
@@ -244,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;
@@ -288,6 +390,12 @@ 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;
         if (this._spatialGrabRaycaster) {
@@ -295,6 +403,12 @@ 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();
 
@@ -310,6 +424,8 @@ export class WebXR extends Behaviour {
         }
         this._createdComponentsInSession.length = 0;
 
+        this._activeWebARSessionRoot = null;
+
         this.handleOfferSession();
 
         delayForFrames(1).then(() => WebXR.activeWebXRComponent = null);
@@ -339,8 +455,10 @@ export class WebXR extends Behaviour {
         return models;
     }
 
-
-
+    /**
+     * Creates and instantiates the user's avatar representation in the WebXR session.
+     * @param xr The active session
+     */
     protected async createLocalAvatar(xr: NeedleXRSession) {
         if (this._playerSync && xr.running && typeof this.defaultAvatar != "boolean") {
             this._playerSync.asset = this.defaultAvatar;
@@ -348,6 +466,11 @@ export class WebXR extends Behaviour {
         }
     }
 
+    /**
+     * 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 = (instance: Object3D) => {
         // spawned webxr avatars must have a avatar component
         if (debug) console.log("WebXR.onAvatarSpawned", instance);
@@ -360,13 +483,16 @@ export class WebXR extends Behaviour {
 
     // HTML UI
 
-    /** @deprecated use `getButtonsFactory()` or access `WebXRButtonFactory.getOrCreate()` directory */
+    /** @deprecated use {@link getButtonsFactory} or directly access {@link WebXRButtonFactory.getOrCreate} */
     getButtonsContainer(): WebXRButtonFactory {
         return this.getButtonsFactory();
     }
 
-    /** Calling this function will get the Needle WebXR button factory (it will be created if it doesnt exist yet)  
-     * @returns the Needle WebXR button factory */
+    /**
+     * 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 {
         if (!this._buttonFactory) {
             this._buttonFactory = WebXRButtonFactory.getOrCreate();
@@ -374,8 +500,15 @@ export class WebXR extends Behaviour {
         return this._buttonFactory;
     }
 
+    /**
+     * Reference to the WebXR button factory used by this component.
+     */
     private _buttonFactory?: WebXRButtonFactory;
 
+    /**
+     * 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() {
         const xrButtonsPriority = 50;
 
@@ -423,14 +556,25 @@ export class WebXR extends Behaviour {
         }
     }
 
+    /**
+     * Storage for UI buttons created by this component.
+     */
     private readonly _buttons: HTMLElement[] = [];
 
+    /**
+     * 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(button: HTMLElement, priority: number) {
         this._buttons.push(button);
         button.setAttribute("priority", priority.toString());
         this.context.menu.appendChild(button);
     }
 
+    /**
+     * Removes all buttons created by this component from the UI.
+     */
     private removeButtons() {
         for (const button of this._buttons) {
             button.remove();