@needle-tools/engine 5.1.0 → 5.1.2

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

@@ -42,6 +42,10 @@ export class Avatar extends Behaviour {
     private _leftHandMeshes?: Mesh[];
     private _rightHandMeshes?: Mesh[];
 
+    // meshes of remote avatar hands - hidden render-only so the hand root stays active and keeps syncing
+    private _remoteLeftHandMeshes?: Mesh[];
+    private _remoteRightHandMeshes?: Mesh[];
+
     private _syncTransforms?: SyncedTransform[];
 
     async onEnterXR(_args: NeedleXREventArgs) {
@@ -120,46 +124,54 @@ export class Avatar extends Behaviour {
         }
 
         // synchronize hands
+        // IMPORTANT: never toggle `.visible` on the hand object itself - it carries the SyncedTransform,
+        // and setting it invisible deactivates the component (onDisable -> freeOwnership), which means the
+        // owner loses ownership and stops sending (the remote hand then stays frozen). The head syncs fine
+        // precisely because its synced root is never deactivated (only a child mesh is hidden). So we keep
+        // the hand object active and hide only the rendered meshes (render-only, via setCustomVisibility).
         const leftCtrl = args.xr.leftController;
         const leftObj = this.leftHand?.asset as Object3D;
-        if (leftCtrl && leftObj) {
-            leftObj.position.copy(leftCtrl.gripPosition);
-            leftObj.quaternion.copy(leftCtrl.gripQuaternion);
-            leftObj.quaternion.multiply(flipForwardQuaternion);
-            leftObj.visible = leftCtrl.isTracking;
+        if (leftObj) {
+            if (leftCtrl) {
+                leftObj.position.copy(leftCtrl.gripPosition);
+                leftObj.quaternion.copy(leftCtrl.gripQuaternion);
+                leftObj.quaternion.multiply(flipForwardQuaternion);
+            }
+            leftObj.visible = true;
             this.updateHandVisibility(leftCtrl, leftObj, this._leftHandMeshes);
         }
-        else if (leftObj && leftObj.visible) {
-            leftObj.visible = false;
-        }
 
         const right = args.xr.rightController;
         const rightObj = this.rightHand?.asset as Object3D;
-        if (right && rightObj) {
-            rightObj.position.copy(right.gripPosition);
-            rightObj.quaternion.copy(right.gripQuaternion);
-            rightObj.quaternion.multiply(flipForwardQuaternion);
-            rightObj.visible = right.isTracking;
+        if (rightObj) {
+            if (right) {
+                rightObj.position.copy(right.gripPosition);
+                rightObj.quaternion.copy(right.gripQuaternion);
+                rightObj.quaternion.multiply(flipForwardQuaternion);
+            }
+            rightObj.visible = true;
             this.updateHandVisibility(right, rightObj, this._rightHandMeshes);
         }
-        else if (rightObj && rightObj.visible) {
-            rightObj.visible = false;
-        }
     }
 
     onBeforeRender(): void {
-        if (this.context.xr) {
-            if (this.context.time.frame % 10 === 0)
-                this.updateRemoteAvatarVisibility();
-        }
+        // Remote avatar visibility depends on the *owner's* tracking state, not on whether THIS client is
+        // in XR: other users' avatars are syncInstantiated onto non-XR clients too (spectators / lobby),
+        // and must hide/show their hands correctly there as well. So this runs regardless of the local XR
+        // state. updateRemoteAvatarVisibility() early-outs for the local player and when not connected.
+        if (this.context.time.frame % 10 === 0)
+            this.updateRemoteAvatarVisibility();
     }
 
-    private updateHandVisibility(controller: NeedleXRController, avatarHand: Object3D, meshes: Mesh[] | undefined) {
+    private updateHandVisibility(controller: NeedleXRController | null | undefined, avatarHand: Object3D, meshes: Mesh[] | undefined) {
         if (meshes) {
-            // Hide the hand meshes for the local user if another model (e.g. the controller model) is being rendered
-            // We don't set the visible flag here because it would also disable SyncedTransforms networking
-            const hasOtherRenderingModel = controller.model && controller.model.visible && controller.model !== avatarHand;
-            meshes.forEach(mesh => { setCustomVisibility(mesh, !hasOtherRenderingModel); });
+            // Hide the hand meshes (render-only) when the hand is not tracked, or when another model
+            // (e.g. the controller/hand model) is being rendered in its place. We hide the meshes rather
+            // than the object's `visible` flag because that would disable SyncedTransform networking.
+            const isTracking = controller?.isTracking === true;
+            const hasOtherRenderingModel = !!controller?.model && controller.model.visible && controller.model !== avatarHand;
+            const render = isTracking && !hasOtherRenderingModel;
+            meshes.forEach(mesh => { setCustomVisibility(mesh, render); });
         }
     }
 
@@ -173,14 +185,13 @@ export class Avatar extends Behaviour {
                     if (sync.hasState(state.owner)) {
                         this.tryFindAvatarObjectsIfMissing();
 
-                        const leftObj = this.leftHand?.asset as Object3D;
-                        if (leftObj) {
-                            leftObj.visible = sync?.isTracking(state.owner, "left") ?? false;
-                        }
-                        const rightObj = this.rightHand?.asset as Object3D;
-                        if (rightObj) {
-                            rightObj.visible = sync?.isTracking(state.owner, "right") ?? false;
-                        }
+                        // Keep the hand object active (don't toggle `.visible`) so its SyncedTransform keeps
+                        // applying updates and a non-owner freeOwnership can't strip the owner's ownership.
+                        // Hide/show the rendered meshes based on the owner's tracking state instead.
+                        const leftRendered = sync.isTracking(state.owner, "left") ?? false;
+                        this._remoteLeftHandMeshes = this.setRemoteHandRendered(this.leftHand?.asset as Object3D, this._remoteLeftHandMeshes, leftRendered);
+                        const rightRendered = sync.isTracking(state.owner, "right") ?? false;
+                        this._remoteRightHandMeshes = this.setRemoteHandRendered(this.rightHand?.asset as Object3D, this._remoteRightHandMeshes, rightRendered);
                     }
                 }
 
@@ -198,6 +209,22 @@ export class Avatar extends Behaviour {
 
 
 
+    /**
+     * Show/hide a remote avatar hand render-only. The hand object stays active so its SyncedTransform keeps
+     * applying networked updates (toggling `.visible` would deactivate it and could free the owner's ownership).
+     * The mesh list is gathered lazily and cached, and returned so the caller can keep it.
+     */
+    private setRemoteHandRendered(obj: Object3D | undefined, meshes: Mesh[] | undefined, rendered: boolean): Mesh[] | undefined {
+        if (!obj) return meshes;
+        obj.visible = true;
+        if (!meshes || meshes.length === 0) {
+            meshes = [];
+            obj.traverse(o => { if ((o as Mesh).isMesh) meshes!.push(o as Mesh); });
+        }
+        for (const mesh of meshes) setCustomVisibility(mesh, rendered);
+        return meshes;
+    }
+
     private tryFindAvatarObjectsIfMissing() {
         // if no avatar objects are set, try to find them
         if (!this.head || !this.leftHand || !this.rightHand) {

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

@@ -237,22 +237,30 @@ export class WebXR extends Behaviour {
         // 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;
-                }
+        const addUsdzExporterIfMissing = () => {
+            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;
             }
-        });
+        };
+        // QuickLook is added when explicitly requested, or as the visionOS fallback when
+        // WebXR AR isn't available. Only probe XR support on visionOS (the only case that
+        // consumes the result) and go through the cached NeedleXRSession.isARSupported() so
+        // we don't eagerly hit navigator.xr on every enable — that probe trips the
+        // `xr-spatial-tracking` Permissions-Policy in embeds that weren't granted it.
+        if (this.useQuicklookExport) {
+            addUsdzExporterIfMissing();
+        }
+        else if (DeviceUtilities.isVisionOS()) {
+            NeedleXRSession.isARSupported().then((arSupported) => {
+                if (!arSupported) addUsdzExporterIfMissing();
+            });
+        }
 
         this.handleCreatingHTML();
         this.handleOfferSession();

package/src/engine-schemes/synced-transform-model.ts

@@ -54,8 +54,13 @@ dontSave():boolean {
   return offset ? !!this.bb!.readInt8(this.bb_pos + offset) : false;
 }
 
+version():number {
+  const offset = this.bb!.__offset(this.bb_pos, 12);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
 static startSyncedTransformModel(builder:flatbuffers.Builder) {
-  builder.startObject(4);
+  builder.startObject(5);
 }
 
 static addGuid(builder:flatbuffers.Builder, guidOffset:flatbuffers.Offset) {
@@ -74,6 +79,10 @@ static addDontSave(builder:flatbuffers.Builder, dontSave:boolean) {
   builder.addFieldInt8(3, +dontSave, +false);
 }
 
+static addVersion(builder:flatbuffers.Builder, version:number) {
+  builder.addFieldInt32(4, version, 0);
+}
+
 static endSyncedTransformModel(builder:flatbuffers.Builder):flatbuffers.Offset {
   const offset = builder.endObject();
   return offset;

package/src/engine-schemes/transforms.fbs

@@ -20,6 +20,7 @@ table SyncedTransformModel {
     transform: Transform;
     /// if the server should not save this info
     dont_save:bool;
+    version : int;
 }
 
 // file_identifier "STRS";