@needle-tools/engine 4.12.0-beta.1 → 4.12.0-beta.3

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

@@ -10,6 +10,7 @@ import type { IComponent, IGameObject } from "../../engine/engine_types.js";
 import { DeviceUtilities, getParam } from "../../engine/engine_utils.js";
 import { NeedleXRController, type NeedleXREventArgs, type NeedleXRHitTestResult, NeedleXRSession } from "../../engine/engine_xr.js";
 import { Behaviour, GameObject } from "../Component.js";
+import type { WebXR } from "./WebXR.js";
 
 // https://github.com/takahirox/takahirox.github.io/blob/master/js.mmdeditor/examples/js/controls/DeviceOrientationControls.js
 
@@ -20,14 +21,17 @@ const invertForwardMatrix = new Matrix4().makeRotationY(Math.PI);
 
 /**
  * The WebARSessionRoot is the root object for a WebAR session and used to place the scene in AR.  
- * It is also responsible for scaling the user in AR and to define the center of the AR scene. If not present in the scene it will be created automatically by the WebXR component when entering an AR session.
+ * It is also responsible for scaling the user in AR and to define the center of the AR scene.  
+ * If not present in the scene it will be created automatically by the WebXR component when entering an AR session.
  * 
- * @example 
+ * **Note**: If the WebXR component {@link WebXR.autoCenter} option is enabled the scene will be automatically centered based on the content in the scene.  
+ * 
+ * @example Callback when the scene has been placed in AR:
  * ```ts
  * WebARSessionRoot.onPlaced((args) => {
  *    console.log("Scene has been placed in AR");
  * });
- * ```
+ * ```  
  * 
  * @summary Root object for WebAR sessions, managing scene placement and user scaling in AR.
  * @category XR

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

@@ -23,7 +23,7 @@ const debug = getParam("debugwebxr");
 const debugQuicklook = getParam("debugusdz");
 
 /**
- * Use the WebXR component to enable VR, AR and Quicklook on iOS in your scene.  
+ * Use the WebXR component to enable VR and AR on iOS and Android in your scene. VisionOS support is also provided via QuickLook USDZ export.  
  * 
  * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.
  * 
@@ -146,7 +146,9 @@ export class WebXR extends Behaviour {
 
     /**
      * 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.
+     * This helps ensure the scene is properly aligned with detected surfaces.  
+     * 
+     * **Note**: This option overrides the placement of the {@link WebARSessionRoot} component if both are used.
      */
     @serializable()
     autoCenter: boolean = false;
@@ -210,17 +212,25 @@ export class WebXR extends Behaviour {
             showBalloonWarning("<a href=\"https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API\" target=\"_blank\">WebXR</a> only works on secure connections (https).");
         }
 
-        if (this.useQuicklookExport) {
-            const existingUSDZExporter = GameObject.findObjectOfType(USDZExporter);
-            if (!existingUSDZExporter) {
-                // if no USDZ Exporter is found we add one and assign the scene to be exported
-                if (debug) console.log("WebXR: Adding USDZExporter");
-                this._usdzExporter = GameObject.addComponent(this.gameObject, USDZExporter);
-                this._usdzExporter.objectToExport = this.context.scene;
-                this._usdzExporter.autoExportAnimations = true;
-                this._usdzExporter.autoExportAudioSources = true;
+        // Showing the QuickLook button depends on whether we're on iOS or visionOS –
+        // on iOS we have AppClip support, so we don't need QuickLook button there,
+        // while on visionOS we use QuickLook for AR experiences for now (unless it happens to have WebXR support by then).
+        navigator.xr?.isSessionSupported("immersive-ar").catch(() => false).then((arSupported) => {
+
+            const isVisionOSFallback = DeviceUtilities.isVisionOS() && !arSupported;
+            
+            if (this.useQuicklookExport || isVisionOSFallback) {
+                const existingUSDZExporter = GameObject.findObjectOfType(USDZExporter);
+                if (!existingUSDZExporter) {
+                    // if no USDZ Exporter is found we add one and assign the scene to be exported
+                    if (debug) console.log("WebXR: Adding USDZExporter");
+                    this._usdzExporter = GameObject.addComponent(this.gameObject, USDZExporter);
+                    this._usdzExporter.objectToExport = this.context.scene;
+                    this._usdzExporter.autoExportAnimations = true;
+                    this._usdzExporter.autoExportAudioSources = true;
+                }
             }
-        }
+        });
 
         this.handleCreatingHTML();
         this.handleOfferSession();
@@ -360,7 +370,7 @@ export class WebXR extends Behaviour {
 
         // Handle AR session root
         if (args.xr.isAR) {
-            let sessionroot = GameObject.findObjectOfType(WebARSessionRoot);
+            let sessionroot = GameObject.findObjectOfType(WebARSessionRoot, this.context, false);
             // Only create a WebARSessionRoot if none is in the scene already
             if (!sessionroot) {
                 if (this.usePlacementReticle) {