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

package/src/engine-components/SceneSwitcher.ts

@@ -261,7 +261,7 @@ export class SceneSwitcher extends Behaviour {
             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 +477,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") {
@@ -595,7 +595,7 @@ 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();
@@ -620,6 +620,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 +633,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,15 +647,15 @@ 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;
 
 
@@ -683,7 +684,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 +714,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 +772,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 +913,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 +923,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 +950,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 +1019,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/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/WebXR.ts

@@ -210,17 +210,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 +368,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) {