@needle-tools/engine 4.12.0-beta.2 → 4.12.0-next.58a3049

package/src/engine/xr/NeedleXRSession.ts

@@ -6,6 +6,7 @@ import { Context, FrameEvent } from "../engine_context.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
 import { isDestroyed } from "../engine_gameobject.js";
 import { Gizmos } from "../engine_gizmos.js";
+import { Telemetry } from "../engine_license.js";
 import { registerFrameEventCallback, unregisterFrameEventCallback } from "../engine_lifecycle_functions_internal.js";
 import { getBoundingBox, getTempQuaternion, getTempVector, getWorldPosition, getWorldQuaternion, getWorldScale, setWorldPosition, setWorldQuaternion, setWorldScale } from "../engine_three_utils.js";
 import type { ICamera, IComponent, INeedleXRSession } from "../engine_types.js";
@@ -98,12 +99,12 @@ async function handleSessionGranted() {
         }
         // Check if AR is supported, otherwise we can't do anything
         if (!(await navigator.xr?.isSessionSupported("immersive-ar")) && defaultMode === "immersive-ar") {
-            console.warn("[NeedleXRSession:granted] Neither VR nor AR supported, aborting session start.");
+            // console.warn("[NeedleXRSession:granted] Neither VR nor AR supported, aborting session start.");
             // showBalloonMessage("NeidleXRSession: Neither VR nor AR supported, aborting session start.");
             return;
         }
     } catch (e) {
-        console.error("[NeedleXRSession:granted] Error while checking XR support:", e);
+        console.debug("[NeedleXRSession:granted] Error while checking XR support:", e);
         // showBalloonWarning("NeedleXRSession: Error while checking XR support: " + (e as Error).message);
         return;
     }
@@ -148,6 +149,7 @@ async function handleSessionGranted() {
         navigator.xr?.addEventListener('sessiongranted', async () => {
             // enableSpatialConsole(true);
 
+
             const lastSessionMode = sessionStorage.getItem("needle_xr_session_mode") as XRSessionMode;
             const lastSessionInit = sessionStorage.getItem("needle_xr_session_init") ?? null;
             const init = lastSessionInit ? JSON.parse(lastSessionInit) : null;
@@ -459,24 +461,55 @@ export class NeedleXRSession implements INeedleXRSession {
         if (DeviceUtilities.isiOS()) {
 
             const arSupported = await this.isARSupported().catch(() => false);
-            
+
             // On VisionOS, we use QuickLook for AR experiences; no AppClip support for now.
             if (DeviceUtilities.isVisionOS() && !arSupported && (mode === "ar" || mode === "immersive-ar")) {
                 mode = "quicklook";
             }
 
             if (mode === "quicklook") {
+                Telemetry.sendEvent(Context.Current, "xr", {
+                    action: "quicklook_export",
+                    source: "NeedleXRSession.start",
+                });
                 InternalUSDZRegistry.exportAndOpen();
                 return null;
             }
-            
+
             if (!arSupported && (mode === "immersive-ar" || mode === "ar")) {
-                // Forward to the AppClip experience
-                // const url = `https://appclip.apple.com/id?p=tools.needle.launch-app.Clip&url=${encodeURIComponent(location.href)}` 
-                const url =`https://appclip.needle.tools/ar?url=${encodeURIComponent(location.href)}`;
-                console.debug("iOS device detected - opening Needle App Clip for AR experience", url, { mode, init });
-                // navigate to app clip url but keep the current url in history, open in same tab
-                window.location.href = url;
+                // const debugAppClip = getParam("debugappclip")
+                // Forward to the AppClip experience (Using the apple.com url the appclip overlay shows immediately)
+                // const url =`https://appclip.needle.tools/ar?url=${(location.href)}`;
+                const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
+                url.searchParams.set("url", location.href);
+
+                const urlStr = url.toString();
+
+                Telemetry.sendEvent(Context.Current, "xr", {
+                    action: "app_clip_launch",
+                    source: "NeedleXRSession.start",
+                    url: urlStr,
+                });
+
+                // if we are in an iframe, we need to navigate the top window
+                const topWindow = window.top || window;
+                try {
+                    console.debug("iOS device detected - opening Needle App Clip for AR experience", { mode, init, url });
+                    // navigate to app clip url but keep the current url in history, open in same tab
+                    // eslint-disable-next-line xss/no-location-href-assign
+                    topWindow.location.href = urlStr;
+                }
+                catch (e) {
+                    console.warn("Error navigating to AppClip " + urlStr + "\n", e);
+                    // if top window navigation fails and we are in an iframe, we try to navigate the top window directly
+                    const weAreInIframe = window !== window.top;
+                    if (weAreInIframe) {
+                        // we can try to open a new tab as a fallback
+                        window.open(urlStr, "_blank");
+                    }
+                    // eslint-disable-next-line xss/no-location-href-assign
+                    else window.location.href = urlStr;
+                }
 
                 return null;
             }
@@ -486,7 +519,7 @@ export class NeedleXRSession implements INeedleXRSession {
             console.warn("QuickLook mode is only supported on iOS devices");
             return null;
         }
-        
+
         // Since we now know we are not on iOS, ar mode becomes "immersive-ar"
         if (mode == "ar") {
             mode = "immersive-ar";
@@ -586,6 +619,12 @@ export class NeedleXRSession implements INeedleXRSession {
             listener({ mode, init });
         }
         if (debug) showBalloonMessage("Requesting " + mode + " session (" + Date.now() + ")");
+        Telemetry.sendEvent(Context.Current, "xr", {
+            action: "session_request",
+            mode: mode,
+            features: ((init.requiredFeatures ?? []).concat(init.optionalFeatures ?? [])).join(","),
+            source: "NeedleXRSession.start",
+        });
         this._currentSessionRequest = navigator?.xr?.requestSession(mode, init);
         this._currentSessionRequestMode = mode;
         /**@type {XRSystem} */
@@ -1162,6 +1201,12 @@ export class NeedleXRSession implements INeedleXRSession {
 
         console.debug("XR Session ended");
 
+        Telemetry.sendEvent(Context.Current, "xr", {
+            action: "session_end",
+            mode: this.mode,
+            source: "NeedleXRSession.onEnd",
+        });
+
         deleteSessionInfo();
 
         this.onAfterRender();

package/src/engine-components/Camera.ts

@@ -8,7 +8,7 @@ import { Context } from "../engine/engine_setup.js";
 import { RenderTexture } from "../engine/engine_texture.js";
 import { getTempColor, getWorldPosition } from "../engine/engine_three_utils.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 { NeedleXREventArgs } from "../engine/engine_xr.js";
 import { RGBAColor } from "../engine/js-extensions/index.js";
 import { Behaviour, GameObject } from "./Component.js";
@@ -664,6 +664,9 @@ export class Camera extends Behaviour implements ICamera {
                 else if (navigator.userAgent?.includes("Mozilla") && navigator.userAgent?.includes("Mobile WebXRViewer/v2")) {
                     transparent = true;
                 }
+                else if(DeviceUtilities.isNeedleAppClip()) {
+                    return true;
+                }
             }
         }
 

package/src/engine-components/DragControls.ts

@@ -447,7 +447,7 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         if (!this || !this._isDragging) return;
         this._isDragging = false;
         for (const rb of this._draggingRigidbodies) {
-            rb.setVelocity(rb.smoothedVelocity);
+            rb.setVelocity(rb.smoothedVelocity.multiplyScalar(this.context.time.deltaTime));
         }
         this._draggingRigidbodies.length = 0;
         this._targetObject = null;

package/src/engine-components/DropListener.ts

@@ -10,7 +10,7 @@ import { BlobStorage } from "../engine/engine_networking_blob.js";
 import { PreviewHelper } from "../engine/engine_networking_files.js";
 import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { fitObjectIntoVolume, getBoundingBox, placeOnSurface } from "../engine/engine_three_utils.js";
+import { fitObjectIntoVolume, getBoundingBox, getWorldScale, placeOnSurface } from "../engine/engine_three_utils.js";
 import { Model, Vec3 } from "../engine/engine_types.js";
 import { getParam, setParamWithoutReload } from "../engine/engine_utils.js";
 import { determineMimeTypeFromExtension } from "../engine/engine_utils_format.js";
@@ -111,6 +111,7 @@ const blobKeyName = "blob";
 
 /** The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene  
  * It can be used to allow users to drag and drop glTF files into the scene to add new objects.  
+ * Existing child objects will behave like placeholders and will be removed when new files are dropped.  
  * 
  * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
  * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
@@ -522,22 +523,42 @@ export class DropListener extends Behaviour {
 
         const obj = model.scene;
 
-        // use attach to ignore the DropListener scale (e.g. if the parent object scale is not uniform)
-        this.gameObject.attach(obj);
-        obj.position.set(0, 0, 0);
-        obj.quaternion.identity();
+        obj.position.copy(this.gameObject.worldPosition);
+        let scale = getWorldScale(this.gameObject);
 
-        this._addedObjects.push(obj);
-        this._addedModels.push(model);
+        let localPos = new Vector3(0,0,0);
+        scale.x = Math.abs(scale.x);
+        scale.y = Math.abs(scale.y);
+        scale.z = Math.abs(scale.z);
+        let localScale =obj.scale.clone();
+
+        // TODOs: handle rotation when Gizmos APIs has changed to support it
 
-        const volume = new Box3().setFromCenterAndSize(new Vector3(0, this.fitVolumeSize.y * .5, 0).add(this.gameObject.worldPosition), this.fitVolumeSize);
+        const volume = new Box3().setFromCenterAndSize(new Vector3(0, this.fitVolumeSize.y * scale.y * .5, 0).add(this.gameObject.worldPosition), this.fitVolumeSize.clone().multiply(scale));
         if (debug) Gizmos.DrawWireBox3(volume, 0x0000ff, 5);
         if (this.fitIntoVolume) {
+
             fitObjectIntoVolume(obj, volume, {
                 position: !this.placeAtHitPosition
             });
+
+            // to match parent scale later, divide by it
+            localScale = obj.scale.clone().divide(scale);
+            // just take the computed offset from fitting 
+            localPos = obj.worldPosition.clone().sub(this.gameObject.worldPosition).divide(scale);
+            if (debug) Gizmos.DrawSphere(localPos, 0.1, 0xff0000, 5);
         }
 
+        // use attach to ignore the DropListener scale (e.g. if the parent object scale is not uniform)
+        this.gameObject.attach(obj);
+        obj.position.copy(localPos);
+        obj.quaternion.identity();
+        obj.scale.copy(localScale);
+        if (debug) Gizmos.DrawArrow(this.gameObject.worldPosition, obj.getWorldPosition(new Vector3()), 0x00ff00, 5);
+
+        this._addedObjects.push(obj);
+        this._addedModels.push(model);
+
         if (this.placeAtHitPosition && ctx && ctx.screenposition) {
             obj.visible = false; // < don't raycast on the placed object
             const rc = this.context.physics.raycast({ screenPoint: this.context.input.convertScreenspaceToRaycastSpace(ctx.screenposition.clone()) });

package/src/engine-components/EventList.ts

@@ -78,7 +78,11 @@ export class CallInfo {
             // If the target is a property
             else {
                 if (this.arguments) {
-                    this.target[this.methodName] = this.arguments[0] || args[0];
+
+                    if (args !== undefined && args.length > 0)
+                        this.target[this.methodName] = args[0];
+                    else
+                        this.target[this.methodName] = this.arguments[0];
                 }
                 else {
                     this.target[this.methodName] = args[0];

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,14 +247,23 @@ 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) {
@@ -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.  
@@ -601,14 +606,13 @@ export class SceneSwitcher extends Behaviour {
                 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);
         }
     }
 
@@ -658,7 +662,6 @@ export class SceneSwitcher extends Behaviour {
                 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;
@@ -672,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);

package/src/engine-components/SpectatorCamera.ts

@@ -1,5 +1,4 @@
 import { Color, Object3D, PerspectiveCamera, Quaternion, Vector3, WebGLState } from "three";
-import { PlayerState } from "../engine-components-experimental/networking/PlayerSync.js";
 
 import { InputEvents } from "../engine/engine_input.js";
 import { RoomEvents } from "../engine/engine_networking.js";
@@ -10,6 +9,7 @@ import { serializable } from "../engine/engine_serialization.js";
 import { Context } from "../engine/engine_setup.js";
 import type { ICamera } from "../engine/engine_types.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";

package/src/engine-components/api.ts

@@ -35,8 +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/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/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";
@@ -12,7 +13,6 @@ import { Behaviour, GameObject } from "../Component.js";
 import { SyncedTransform } from "../SyncedTransform.js";
 import { AvatarMarker } from "./WebXRAvatar.js";
 import { XRFlag } from "./XRFlag.js";
-import { ViewDevice } from "../../engine/engine_playerview.js";
 
 const debug = getParam("debugwebxr");
 

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;