@needle-tools/engine 4.12.0-next.ca2cebd → 4.12.0-next.dcaf2b0

package/src/engine-components/RendererInstancing.ts

@@ -669,14 +669,17 @@ class InstancedMeshRenderer {
     private grow(geometry: BufferGeometry) {
         const id = ++this._growId;
         const growFactor = 2;
-        const newSize = Math.ceil(this._maxInstanceCount * growFactor);
+
+        const growInstances = this.count >= this._maxInstanceCount;
+        const newSize = growInstances ? Math.ceil(this._maxInstanceCount * growFactor) : this._maxInstanceCount;
 
         // create a new BatchedMesh instance
         // TODO: we should keep track of how many instances for each geometry we have and consider that when estimating new space
         const estimatedSpace = this.tryEstimateVertexCountSize(newSize, [geometry]);// geometry.attributes.position.count;
         // const indices = geometry.index ? geometry.index.count : 0;
-        const newMaxVertexCount = Math.max(this._maxVertexCount, estimatedSpace.vertexCount);
-        const newMaxIndexCount = Math.max(this._maxIndexCount, estimatedSpace.indexCount);//, Math.ceil(this._maxVertexCount * growFactor));
+        const vertexGrowFactor = 1.25;
+        const newMaxVertexCount = Math.max(this._maxVertexCount, Math.ceil(estimatedSpace.vertexCount * vertexGrowFactor));
+        const newMaxIndexCount = Math.max(this._maxIndexCount, Math.ceil(estimatedSpace.indexCount * vertexGrowFactor));
 
         if (debugInstancing) {
             const geometryInfo = getMeshInformation(geometry);

package/src/engine-components/SceneSwitcher.ts

@@ -1,7 +1,7 @@
 import { EquirectangularReflectionMapping, Object3D, Scene, Texture } from "three";
 
 import { AssetReference } from "../engine/engine_addressables.js";
-import { destroy } from "../engine/engine_gameobject.js";
+import { destroy, instantiate } from "../engine/engine_gameobject.js";
 import { InputEvents } from "../engine/engine_input.js";
 import { isLocalNetwork } from "../engine/engine_networking_utils.js";
 import { serializable } from "../engine/engine_serialization.js";
@@ -247,21 +247,30 @@ export class SceneSwitcher extends Behaviour {
 
     private _currentIndex: number = -1;
     private _currentScene: AssetReference | undefined = undefined;
+    private _currentSceneAsset: Object3D | undefined = undefined;
     private _engineElementOverserver: MutationObserver | undefined = undefined;
 
     private _preloadScheduler?: PreLoadScheduler;
 
     private _menuButtons?: HTMLElement[];
 
+    // this is the scene that was requested last
+    private __lastSwitchScene?: AssetReference;
+    private __lastSwitchScenePromise?: Promise<boolean>;
+
     /** @internal */
     awake(): void {
+        this._currentScene = undefined;
+        this._lastLoadingScene = undefined;
+        this.__lastSwitchScenePromise = undefined;
+
         if (this.scenes === undefined) this.scenes = [];
         // remove all scenes from the url that are in the scenes array at startup
         for (const scene of this.scenes) {
             if (scene && !scene.hasUrl && scene.asset instanceof Object3D) {
                 GameObject.remove(scene.asset);
             }
-            else if(scene instanceof Object3D) {
+            else if (scene instanceof Object3D) {
                 GameObject.remove(scene);
             }
         }
@@ -477,13 +486,13 @@ export class SceneSwitcher extends Behaviour {
      * @returns a promise that resolves to true if the scene was loaded successfully
      */
     select(index: number | string): Promise<boolean> {
-        if (debug) console.log("select", index);
+        if (debug) console.log("[SceneSwitcher] select", index);
 
         if (typeof index === "object") {
             // If a user tries to reference a scene object in a UnityEvent and invoke select(obj) 
             // Then the object will be serialized as a object { guid : ... } or with the index json pointer
             // This case is not supported right now. Object references in the editor must not be scene references
-            console.warn("Switching to \"" + index + "\" might not work. Please either use an index or a AssetReference (not a scene reference)");
+            console.warn("[SceneSwitcher] Switching to \"" + index + "\" might not work. Please either use an index or a AssetReference (not a scene reference)");
         }
 
         if (typeof index === "string") {
@@ -538,10 +547,6 @@ export class SceneSwitcher extends Behaviour {
         return false;
     }
 
-    // this is the scene that was requested last
-    private __lastSwitchScene?: AssetReference;
-    private __lastSwitchScenePromise?: Promise<boolean>;
-
     /**
      * Switch to a scene by its AssetReference.  
      * If the scene is already loaded it will be unloaded and the new scene will be loaded.  
@@ -595,20 +600,19 @@ export class SceneSwitcher extends Behaviour {
         const current = this._currentScene;
         this._currentScene = undefined;
         if (current) {
-            if (debug) console.log("UNLOAD", current.url, "HasURL?: " + current.hasUrl)
+            if (debug) console.log("[SceneSwitcher] UNLOAD", current.url, "HasURL?: " + current.hasUrl)
             const sceneListener = this.tryGetSceneEventListener(current.asset as any as Object3D);
             if (sceneListener?.sceneClosing) {
                 const res = sceneListener.sceneClosing();
                 if (res instanceof Promise) await res;
             }
-            // if the current scene has a URL (so it can be reloaded)
-            // then we unload it
+
+            // // if the current scene has a URL (so it can be reloaded)
+            // // then we unload it
             if (current.hasUrl)
                 current.unload();
-            // otherwise if it's a regular Object3D we just remove it from the scene
-            else if (current.asset instanceof Object3D) {
-                GameObject.remove(current.asset as any as Object3D);
-            }
+
+            if (this._currentSceneAsset) destroy(this._currentSceneAsset, true, false);
         }
     }
 
@@ -620,6 +624,7 @@ export class SceneSwitcher extends Behaviour {
         const index = this._currentIndex = this.scenes?.indexOf(scene) ?? -1;
 
         try {
+            if (debug) console.debug(`${Date.now()} [SceneSwitcher] Loading scene start: ${scene.url} (index: ${index})`);
             this._currentlyLoadingScene = scene;
             this._currentLoadingProgress = new ProgressEvent("progress", { loaded: 0, total: 1 });
 
@@ -632,7 +637,7 @@ export class SceneSwitcher extends Behaviour {
                 if (debug) {
                     const t01 = prog.loaded / prog.total;
                     const progressBarString = "[" + "=".repeat(Math.floor(t01 * 20)) + "-".repeat(20 - Math.floor(t01 * 20)) + "]";
-                    console.debug(`[SceneSwitcher] Download ${(t01 * 100).toFixed(1)} % ${progressBarString}`, scene.url);
+                    console.debug(`${Date.now()} [SceneSwitcher] Loading scene progress: ${(t01 * 100).toFixed(1)} % ${progressBarString}`, scene.url);
                 }
                 this._currentLoadingProgress = prog;
                 this.dispatchEvent(prog);
@@ -646,18 +651,17 @@ export class SceneSwitcher extends Behaviour {
             this._currentlyLoadingScene = undefined;
 
             if (finishedEvt.defaultPrevented) {
-                if (debug) console.warn("Adding loaded scene prevented:", scene, finishedEvt);
+                if (debug) console.warn("[SceneSwitcher] Adding loaded scene prevented:", scene, finishedEvt);
                 return false;
             }
             if (!scene.asset) {
-                if (debug) console.warn("Failed loading scene:", scene);
+                if (debug) console.warn("[SceneSwitcher] Failed loading scene:", scene);
                 return false;
             }
             if (this._currentIndex === index) {
-                if (debug) console.log("ADD", scene.url);
+                if (debug) console.log("[SceneSwitcher] ADD", scene.url);
                 this._currentScene = scene;
 
-
                 // Experimental: replace the whole content of the scene
                 if (experimental_clearSceneOnLoad) {
                     const camera = this.context.mainCameraComponent?.gameObject || this.context.mainCamera;
@@ -671,7 +675,14 @@ export class SceneSwitcher extends Behaviour {
                     }
                 }
 
-                GameObject.add(scene.asset, this.gameObject);
+                // @TODO: if multiple scene switcher or scenes use this asset already it will be moved
+                if (!scene.asset.parent) {
+                    this._currentSceneAsset = scene.asset;
+                    GameObject.add(scene.asset, this.gameObject);
+                }
+                else {
+                    this._currentSceneAsset = instantiate(scene.asset, { parent: this.gameObject });
+                }
 
                 if (this.useSceneLighting)
                     this.context.sceneLighting.enable(scene);
@@ -683,7 +694,7 @@ export class SceneSwitcher extends Behaviour {
                         this.context.scene.background = skybox;
                     }
                     else if (debug) {
-                        console.warn("SceneSwitcher: Can't find skybox for scene " + scene.url);
+                        console.warn("[SceneSwitcher] Can't find skybox for scene " + scene.url);
                     }
                 }
 
@@ -713,10 +724,9 @@ export class SceneSwitcher extends Behaviour {
                     const res = sceneListener.sceneOpened(this);
                     if (res instanceof Promise) await res;
                 }
-
+                if (debug) console.debug(`${Date.now()} [SceneSwitcher] Loading scene finished: ${scene.url} (index: ${index})`);
                 const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
                 this.dispatchEvent(openedEvt);
-
                 this.sceneLoaded?.invoke(this);
                 return true;
             }
@@ -772,7 +782,7 @@ export class SceneSwitcher extends Behaviour {
             }
         }
 
-        if (isLocalNetwork()) console.warn("Can not find scene: \"" + value + "\"", this)
+        if (isLocalNetwork()) console.warn("[SceneSwitcher] Can not find scene: \"" + value + "\"", this)
 
         return couldNotLoadScenePromise;
     }
@@ -913,7 +923,7 @@ class PreLoadScheduler {
      */
     begin(delay: number) {
         if (this._isRunning) return;
-        if (debug) console.log("Preload begin", { delay })
+        if (debug) console.log("[SceneSwitcher] Preload scheduled", { delay });
         this._isRunning = true;
         let lastRoom: number = -10;
         let searchDistance: number;
@@ -923,7 +933,7 @@ class PreLoadScheduler {
         const interval = setInterval(() => {
             if (this.allLoaded()) {
                 if (debug)
-                    console.log("All scenes (pre-)loaded");
+                    console.log("[SceneSwitcher] All scenes (pre-)loaded");
                 this.stop();
             }
             if (!this._isRunning) {
@@ -950,7 +960,7 @@ class PreLoadScheduler {
             if (roomIndex < 0 || roomIndex >= array.length) return;
             if (!this._loadTasks.some(t => t.index === roomIndex)) {
                 const scene = array[roomIndex];
-                if (debug) console.log("Preload scene", { roomIndex, searchForward, lastRoom, currentIndex: this._switcher.currentIndex, tasks: this._loadTasks.length }, scene?.url);
+                if (debug) console.log("[SceneSwitcher] Schedule preload scene", { roomIndex, searchForward, lastRoom, currentIndex: this._switcher.currentIndex, tasks: this._loadTasks.length }, scene?.url);
                 new LoadTask(roomIndex, scene, this._loadTasks);
             }
         }, 200);
@@ -1019,10 +1029,10 @@ class LoadTask {
     private async awaitLoading() {
         if (this.asset && !this.asset.isLoaded()) {
             if (debug)
-                console.log("Preload start: " + this.asset.url, this.index);
+                console.log("[SceneSwitcher] Preload start: " + this.asset.url, this.index);
             await this.asset.preload();
             if (debug)
-                console.log("Preload finished: " + this.asset.url, this.index);
+                console.log("[SceneSwitcher] Preload finished: " + this.asset.url, this.index);
         }
 
         const i = this.tasks.indexOf(this);

package/src/engine-components/SpectatorCamera.ts

@@ -8,7 +8,8 @@ import { PlayerView, ViewDevice } from "../engine/engine_playerview.js";
 import { serializable } from "../engine/engine_serialization.js";
 import { Context } from "../engine/engine_setup.js";
 import type { ICamera } from "../engine/engine_types.js";
-import { getParam } from "../engine/engine_utils.js";
+import { DeviceUtilities, getParam } from "../engine/engine_utils.js";
+import { PlayerState } from "../engine-components-experimental/networking/PlayerSync.js";
 import { Camera } from "./Camera.js";
 import { Behaviour, Component, GameObject } from "./Component.js";
 import { OrbitControls } from "./OrbitControls.js";
@@ -98,7 +99,7 @@ export class SpectatorCamera extends Behaviour {
     }
 
     /** Gets the local player's connection ID */
-    private get localId() : string {
+    private get localId(): string {
         return this.context.connection.connectionId ?? "local";
     }
 
@@ -196,9 +197,8 @@ export class SpectatorCamera extends Behaviour {
      */
     private isSupportedPlatform() {
         const ua = window.navigator.userAgent;
-        const standalone = /Windows|MacOS/.test(ua);
         const isHololens = /Windows NT/.test(ua) && /Edg/.test(ua) && !/Win64/.test(ua);
-        return standalone && !isHololens;
+        return DeviceUtilities.isDesktop() && !DeviceUtilities.isMobileDevice() && !isHololens;
     }
 
     /**
@@ -268,11 +268,16 @@ export class SpectatorCamera extends Behaviour {
         const previousRenderTarget = renderer.getRenderTarget();
         let oldFramebuffer: WebGLFramebuffer | null = null;
 
+
         const webglState = renderer.state as WebGLState & { bindXRFramebuffer?: Function };
 
+
         // seems that in some cases, renderer.getRenderTarget returns null
         // even when we're rendering to a headset.
-        if (!previousRenderTarget) {
+        if (!previousRenderTarget || 
+            // Prevent rendering if in XR - @TODO: check if we need to allow this for VR?
+            previousRenderTarget["isXRRenderTarget"] === true) 
+        {
             if (!renderer.state.bindFramebuffer || !webglState.bindXRFramebuffer)
                 return;
 
@@ -557,12 +562,18 @@ class SpectatorSelectionController {
             for (const hit of hits) {
                 if (hit.distance < .2) continue;
                 const obj = hit.object;
-                const avatar = GameObject.getComponentInParent(obj, AvatarMarker);
-                const id = avatar?.connectionId;
+                // For WebXR
+                const state = PlayerState.getFor(obj);
+                let id = state?.owner;
+                // for SpectatorCamera
+                if (!id) {
+                    const avatar = GameObject.getComponentInParent(obj, AvatarMarker);
+                    id = avatar?.connectionId;
+                }
                 if (id) {
                     const view = this.context.players.getPlayerView(id);
                     this.spectator.target = view;
-                    if (debug) console.log("spectate", id, avatar);
+                    if (debug) console.log("spectate", id, state);
                     break;
                 }
             }
@@ -633,7 +644,7 @@ class SpectatorCamNetworking {
         this.context.connection.beginListen("spectator-request-follow", this._requestFollowMethod);
         this.context.connection.beginListen(RoomEvents.JoinedRoom, this._joinedRoomMethod);
         this.context.domElement.addEventListener("keydown", evt => {
-            if(!this.spectator.useKeys) return;
+            if (!this.spectator.useKeys) return;
             if (evt.key === "f") {
                 this.onRequestFollowMe();
             }
@@ -767,7 +778,7 @@ class SpectatorCamNetworking {
     }
 
     private _enforceFollowInterval: any;
-    
+
     /**
      * Periodically retries following a user if the initial attempt failed
      */

package/src/engine-components/SpriteRenderer.ts

@@ -262,7 +262,8 @@ export class SpriteData {
  * 
  * - Example: https://engine.needle.tools/samples/spritesheet-animation
  * 
- * @category Sprites
+ * @summary Renders 2D images from a sprite sheet
+ * @category Rendering
  * @group Components
  */
 export class SpriteRenderer extends Behaviour {

package/src/engine-components/api.ts

@@ -35,7 +35,8 @@
  */
 
 export * from "./codegen/components.js";
-export { Behaviour, Component, GameObject } from "./Component.js"
+export { Collider } from "./Collider.js"; // export abstract type
+export { Behaviour, Component, GameObject } from "./Component.js";
 
 // We dont want to export everything in the extensions
 export { ClearFlags } from "./Camera.js"

package/src/engine-components/codegen/components.ts

@@ -23,7 +23,6 @@ export { BoxHelperComponent } from "../BoxHelperComponent.js";
 export { Camera } from "../Camera.js";
 export { CharacterController } from "../CharacterController.js";
 export { CharacterControllerInput } from "../CharacterController.js";
-export { Collider } from "../Collider.js";
 export { SphereCollider } from "../Collider.js";
 export { BoxCollider } from "../Collider.js";
 export { MeshCollider } from "../Collider.js";

package/src/engine-components/export/usdz/extensions/behavior/BehaviourComponents.ts

@@ -11,6 +11,7 @@ import { Animation } from "../../../../Animation.js";
 import { Animator } from "../../../../Animator.js";
 import { AudioSource } from "../../../../AudioSource.js";
 import { Behaviour, GameObject } from "../../../../Component.js";
+import { Rigidbody } from "../../../../RigidBody.js";
 import type { IPointerClickHandler, PointerEventData } from "../../../../ui/PointerEvents.js";
 import { ObjectRaycaster,Raycaster } from "../../../../ui/Raycaster.js";
 import { makeNameSafeForUSD,USDDocument, USDObject, USDZExporterContext } from "../../ThreeUSDZExporter.js";
@@ -68,6 +69,16 @@ export class ChangeTransformOnClick extends Behaviour implements IPointerClickHa
     }
 
     onPointerClick(args: PointerEventData) {
+
+        const rbs = this.object?.getComponentsInChildren(Rigidbody);
+
+        if (rbs){
+            for (const rb of rbs) {	
+                rb.resetVelocities();
+                rb.resetForcesAndTorques();
+            }
+        }
+
         args.use();
         if (this.coroutine) this.stopCoroutine(this.coroutine);
         if (!this.relativeMotion)

package/src/engine-components/timeline/SignalAsset.ts

@@ -30,7 +30,7 @@ export class SignalReceiverEvent {
  * Signals can be added to a signal track on a {@link PlayableDirector}
  * 
  * @summary Receives signals and invokes reactions
- * @category Sequencing and Timelines
+ * @category Animation and Sequencing
  * @group Components
  */
 export class SignalReceiver extends Behaviour {

package/src/engine-components/ui/Raycaster.ts

@@ -31,7 +31,7 @@ export abstract class Raycaster extends Behaviour {
 /**
  * A Raycaster that performs raycasting against its own GameObject.  
  * 
- * @category Interaction
+ * @category Interactivity
  * @group Components
  */
 export class ObjectRaycaster extends Raycaster {
@@ -75,7 +75,8 @@ export class ObjectRaycaster extends Raycaster {
 /**
  * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
  * 
- * @category UI
+ * @summary Raycaster for UI elements
+ * @category User Interface
  * @group Components
  */
 export class GraphicRaycaster extends ObjectRaycaster {

package/src/engine-components/ui/RectTransform.ts

@@ -29,6 +29,12 @@ const tempVec = new Vector3();
 const tempMatrix = new Matrix4();
 const tempQuaternion = new Quaternion();
 
+/** 
+* RectTransform is a component that defines a rectangle for UI layout. 
+* @summary UI Rectangle Transform
+* @category User Interface
+* @group Components
+*/
 export class RectTransform extends BaseUIComponent implements IRectTransform, IRectTransformChangedReceiver {
 
     get parent() {

package/src/engine-components/utils/LookAt.ts

@@ -13,7 +13,8 @@ import { Behaviour } from "../Component.js";
  * It can also invert the forward direction and keep the up direction.
  * 
  * @summary Makes the object look at a target object or the camera
- * @category Interactivity, Everywhere Actions
+ * @category Everywhere Actions
+ * @category Interactivity
  * @group Components
  */
 export class LookAt extends Behaviour implements UsdzBehaviour {

package/src/engine-components/web/CursorFollow.ts

@@ -15,7 +15,7 @@ const debug = getParam("debugcursor");
  * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
  * 
  * @summary Makes the object follow the cursor position on screen
- * @category Web
+ * @category Interactivity
  * @group Components
  * @component
  */

package/src/engine-components/web/HoverAnimation.ts

@@ -14,7 +14,7 @@ import { Behaviour } from "../Component.js";
  * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
  * 
  * @summary Hover Animation on Pointer Enter/Exit
- * @category Web
+ * @category Interactivity
  * @group Components
  */
 @registerType

package/src/engine-components/web/ViewBox.ts

@@ -32,7 +32,7 @@ export type ViewBoxMode = "continuous" | "once";
  * ```
   
  * @summary Automatically fits a box area into the camera view
- * @category Camera
+ * @category Camera and Controls
  * @group Components
  * @component
  */

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

@@ -2,6 +2,7 @@ import { Mesh, Object3D, Quaternion, Vector3 } from "three";
 
 import { AssetReference } from "../../engine/engine_addressables.js";
 import { ObjectUtils, PrimitiveType } from "../../engine/engine_create_objects.js";
+import { ViewDevice } from "../../engine/engine_playerview.js";
 import { serializable } from "../../engine/engine_serialization_decorator.js";
 import type { IGameObject } from "../../engine/engine_types.js";
 import { getParam, PromiseAllWithErrors } from "../../engine/engine_utils.js";
@@ -55,10 +56,13 @@ export class Avatar extends Behaviour {
             const marker = this.gameObject.addComponent(AvatarMarker)!;
             marker.avatar = this.gameObject;
             marker.connectionId = playerstate.owner;
+
+            this.context.players.setPlayerView(playerstate.owner, this.head?.asset, ViewDevice.Headset);
         }
         else if (this.context.connection.isConnected) console.error("No player state found for avatar", this);
         // don't destroy the avatar when entering XR and not connected to a networking backend
         else if (playerstate && !this.context.connection.isConnected) playerstate.dontDestroy = true;
+
     }
 
     onLeaveXR(_args: NeedleXREventArgs): void {

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