@relu-interactives/spatial-ecs 0.4.3 → 0.4.5

package/dist/index.cjs

@@ -12059,6 +12059,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     const rig = world.getComponent(rigEntityId, XRRigComponent);
     const rigTransform = world.getComponent(rigEntityId, TransformComponent);
     if (!rig || !rigTransform) return;
+    if (world.isXrPassthrough()) return;
     const inputs = this.inputSystem.getInputs();
     if (inputs.length === 0) return;
     if (rig.snapTurn) {
@@ -12305,6 +12306,8 @@ var _XRSessionSystem = class _XRSessionSystem {
     this.capabilities = NO_XR_CAPABILITIES;
     /** Y compensation applied when a floor-relative space was requested but not granted. */
     this.appliedOriginOffset = 0;
+    /** The live session, so an async floor probe can tell if it has been replaced. */
+    this.session = null;
     this.inputSystem = inputSystem ?? null;
   }
   update(world) {
@@ -12319,10 +12322,37 @@ var _XRSessionSystem = class _XRSessionSystem {
     }
     if (presenting) {
       this.dispatchInputEdges(world);
+      this.muteDepthOcclusionColor(world);
+    }
+  }
+  /**
+   * Stop three's depth-occlusion pass from writing COLOR.
+   *
+   * With depth sensing granted, three draws a full-screen, head-locked mesh
+   * every frame whose fragment shader assigns ONLY `gl_FragDepth` — that is
+   * the whole occlusion mechanism — but its material never sets
+   * `colorWrite: false`, so the colour output is UNDEFINED per GLSL. Desktop
+   * drivers happen to zero it, which is why this ships unnoticed; Quest's
+   * mobile GPU frequently leaves the last-computed temporary in the register —
+   * the sampled DEPTH value — so the pass paints the depth camera's view over
+   * the screen as faint head-locked contour bands. On device that reads as "a
+   * large wireframe dome that follows my head".
+   *
+   * The mesh is created lazily inside three's render, so this is re-checked
+   * every frame rather than hooked once; the write is idempotent and the
+   * check is two property reads. Depth-only is the mesh's entire purpose —
+   * occlusion is unaffected.
+   */
+  muteDepthOcclusionColor(world) {
+    const xr = world.getRenderer().xr;
+    const material = xr.getDepthSensingMesh?.()?.material;
+    if (material && material.colorWrite !== false) {
+      material.colorWrite = false;
     }
   }
   handleSessionStart(world) {
     const session = world.getRenderer().xr.getSession();
+    this.session = session ?? null;
     const mode = session && session.environmentBlendMode !== "opaque" ? "immersive-ar" : "immersive-vr";
     this.capabilities = readXrCapabilities(session ?? null, mode);
     if (session && this.inputSystem) {
@@ -12361,16 +12391,16 @@ var _XRSessionSystem = class _XRSessionSystem {
       renderer.xr.setReferenceSpaceType(wantsFloor ? "local-floor" : "local");
     } catch {
     }
-    const granted = session?.enabledFeatures;
-    const floorGranted = Array.isArray(granted) ? granted.includes("local-floor") : (
-      // No report at all: trust the request, since a wrong offset is worse
-      // than none on devices that did honour it.
-      true
-    );
-    this.appliedOriginOffset = wantsFloor && !floorGranted ? rig.fallbackEyeHeight : 0;
-    if (this.appliedOriginOffset !== 0) {
+    this.appliedOriginOffset = 0;
+    if (!wantsFloor || !session) return;
+    const sessionAtRequest = session;
+    session.requestReferenceSpace("local-floor").then(() => {
+    }).catch(() => {
+      if (this.session !== sessionAtRequest) return;
+      if (this.appliedOriginOffset !== 0) return;
+      this.appliedOriginOffset = rig.fallbackEyeHeight;
       transform.position.y -= this.appliedOriginOffset;
-    }
+    });
   }
   handleSessionEnd(world) {
     if (this.appliedOriginOffset !== 0) {
@@ -12381,6 +12411,7 @@ var _XRSessionSystem = class _XRSessionSystem {
       }
       this.appliedOriginOffset = 0;
     }
+    this.session = null;
     this.capabilities = NO_XR_CAPABILITIES;
     this.inputSystem?.detachSession();
     this.forEachBehaviour(world, (behaviour) => {
@@ -12470,8 +12501,12 @@ function planeColliderFromPolygon(polygon) {
 __name(planeColliderFromPolygon, "planeColliderFromPolygon");
 function writeXrMeshGeometry(vertices, indices, existing) {
   const geometry = existing ?? new THREE51__namespace.BufferGeometry();
-  geometry.setAttribute("position", new THREE51__namespace.BufferAttribute(vertices, 3));
-  geometry.setIndex(new THREE51__namespace.BufferAttribute(indices, 1));
+  geometry.setAttribute(
+    "position",
+    new THREE51__namespace.BufferAttribute(vertices.slice(), 3)
+  );
+  geometry.setIndex(new THREE51__namespace.BufferAttribute(indices.slice(), 1));
+  geometry.deleteAttribute("normal");
   geometry.computeBoundingSphere();
   geometry.computeVertexNormals();
   return geometry;
@@ -12497,6 +12532,42 @@ __name(decomposeXrPose, "decomposeXrPose");
 
 // core/systems/XREnvironmentSystem.ts
 var DEBUG_COLOR = 5088255;
+function debugColorFor(kind, semanticLabel) {
+  switch (semanticLabel) {
+    case "floor":
+      return 5100666;
+    // green — the surface everything should rest on
+    case "ceiling":
+      return 11693055;
+    // purple
+    case "wall":
+    case "wall face":
+      return DEBUG_COLOR;
+    // blue, the family's base colour
+    case "global mesh":
+      return 9079442;
+    // dim gray — raw scan, not an object
+    default:
+      return semanticLabel ? 16747594 : DEBUG_COLOR;
+  }
+}
+__name(debugColorFor, "debugColorFor");
+var GLOBAL_MESH_DEBUG_OPACITY = 0.35;
+var DEBUG_RENDER_ORDER = 900;
+var ROOM_CAPTURE_DELAY_SECONDS = 3;
+var SYNTHETIC_FLOOR_EXTENT = 50;
+var SYNTHETIC_FLOOR_PLANE = {
+  planeSpace: {},
+  polygon: [
+    { x: -SYNTHETIC_FLOOR_EXTENT / 2, y: 0, z: -SYNTHETIC_FLOOR_EXTENT / 2 },
+    { x: SYNTHETIC_FLOOR_EXTENT / 2, y: 0, z: -SYNTHETIC_FLOOR_EXTENT / 2 },
+    { x: SYNTHETIC_FLOOR_EXTENT / 2, y: 0, z: SYNTHETIC_FLOOR_EXTENT / 2 },
+    { x: -SYNTHETIC_FLOOR_EXTENT / 2, y: 0, z: SYNTHETIC_FLOOR_EXTENT / 2 }
+  ],
+  orientation: "horizontal",
+  semanticLabel: "floor",
+  lastChangedTime: 0
+};
 var _XREnvironmentSystem = class _XREnvironmentSystem {
   constructor() {
     /** Keyed by the XRPlane/XRMesh object itself — the runtime's own identity. */
@@ -12504,17 +12575,24 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     this.meshes = /* @__PURE__ */ new Map();
     this.presenting = false;
     this.debugVisible = false;
+    /** Seconds presenting, used to decide the room has genuinely nothing in it. */
+    this.elapsed = 0;
+    /** `initiateRoomCapture` may be called only ONCE per session. */
+    this.roomCaptureRequested = false;
   }
-  update(world) {
+  update(world, deltaTime = 0) {
     const presenting = world.isXrPresenting();
     if (!presenting) {
       if (this.presenting) {
         this.presenting = false;
+        this.elapsed = 0;
+        this.roomCaptureRequested = false;
         this.clearAll(world);
       }
       return;
     }
     this.presenting = true;
+    this.elapsed += deltaTime;
     const rig = this.findRig(world);
     const mode = rig?.environmentPhysics ?? "none";
     if (mode === "none") {
@@ -12530,6 +12608,11 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     const frame = xr.getFrame?.();
     const referenceSpace = xr.getReferenceSpace();
     if (!frame || !referenceSpace) return;
+    if (frame.detectedPlanes === void 0 && frame.detectedMeshes === void 0) {
+      this.ensureSyntheticFloor(world);
+      return;
+    }
+    this.removeSyntheticFloor(world);
     const meshesAvailable = Boolean(frame.detectedMeshes);
     const useMesh = (mode === "mesh" || mode === "auto") && meshesAvailable;
     const usePlanes = mode === "planes" || mode === "auto" && !useMesh;
@@ -12543,11 +12626,84 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     } else if (this.meshes.size > 0) {
       this.clearMap(world, this.meshes);
     }
+    this.maybeCaptureRoom(world, frame);
+  }
+  /**
+   * Ask the runtime to scan the room when it turns out we have no room.
+   *
+   * Plane and mesh detection do NOT scan anything — they replay a scan the user
+   * captured earlier through the system's own room setup. Most people have
+   * never run it, and those who have may have run it in a DIFFERENT room, so a
+   * mixed-reality experience opens against either nothing at all or someone
+   * else's furniture, with no prompt and no error.
+   *
+   * `XRSession.initiateRoomCapture()` (Meta's extension) launches that setup
+   * from inside the session, and exists precisely for this case. Contract, from
+   * Meta's docs: callable ONCE per session, and only worth calling once we are
+   * confident the room really is empty — the arrays populate a beat after the
+   * session starts, so a check on frame one would fire for everyone.
+   */
+  maybeCaptureRoom(world, frame) {
+    if (this.roomCaptureRequested) return;
+    if (this.elapsed < ROOM_CAPTURE_DELAY_SECONDS) return;
+    if (this.planes.size > 0 || this.meshes.size > 0) return;
+    if ((frame.detectedPlanes?.size ?? 0) > 0) return;
+    if ((frame.detectedMeshes?.size ?? 0) > 0) return;
+    const session = world.getRenderer().xr.getSession?.();
+    if (typeof session?.initiateRoomCapture !== "function") return;
+    this.roomCaptureRequested = true;
+    session.initiateRoomCapture()?.catch(() => {
+    });
   }
   /** How many pieces of real geometry are currently colliding. Script-facing. */
   getDetectedCount() {
     return { planes: this.planes.size, meshes: this.meshes.size };
   }
+  /**
+   * A census of every surface currently spawned: what it is, where it sits and
+   * roughly how big it is. Built for the template's post-session readout, so a
+   * mystery shape on the headset can be looked up by its label instead of
+   * guessed at — a small-radius entry at head height IS the mystery shape, and
+   * a clean list means whatever was seen did not come from this system.
+   */
+  getDebugSnapshot(world) {
+    const snapshot = [];
+    for (const [plane, entry] of this.planes) {
+      const transform = world.getComponent(entry.entityId, TransformComponent);
+      const collider = planeColliderFromPolygon(plane.polygon);
+      snapshot.push({
+        kind: "plane",
+        label: plane.semanticLabel ?? null,
+        position: transform ? { ...transform.position } : { x: 0, y: 0, z: 0 },
+        radius: collider ? Math.hypot(collider.size.x, collider.size.z) / 2 : 0,
+        emulated: entry.emulated
+      });
+    }
+    for (const [mesh, entry] of this.meshes) {
+      const transform = world.getComponent(entry.entityId, TransformComponent);
+      snapshot.push({
+        kind: "mesh",
+        label: mesh.semanticLabel ?? null,
+        position: transform ? { ...transform.position } : { x: 0, y: 0, z: 0 },
+        radius: entry.geometry?.boundingSphere?.radius ?? 0,
+        emulated: entry.emulated
+      });
+    }
+    return snapshot;
+  }
+  /** Create the no-scan floor once; it lives in the ordinary plane map. */
+  ensureSyntheticFloor(world) {
+    if (this.planes.has(SYNTHETIC_FLOOR_PLANE)) return;
+    const created = this.createPlaneEntity(world, SYNTHETIC_FLOOR_PLANE);
+    if (created) this.planes.set(SYNTHETIC_FLOOR_PLANE, created);
+  }
+  /** Real scene data exists (or arrived) — the stand-in must go. */
+  removeSyntheticFloor(world) {
+    const entry = this.planes.get(SYNTHETIC_FLOOR_PLANE);
+    if (!entry) return;
+    this.destroyEntry(world, entry);
+    this.planes.delete(SYNTHETIC_FLOOR_PLANE);
+  }
   findRig(world) {
     const ids = world.query(XRRigComponent);
     if (ids.length === 0) return null;
@@ -12565,9 +12721,11 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     for (const plane of detected) {
       const pose = frame.getPose(plane.planeSpace, referenceSpace);
       if (!pose) continue;
+      const emulated = pose.emulatedPosition === true;
       let entry = this.planes.get(plane);
       const changed = plane.lastChangedTime ?? 0;
       if (!entry) {
+        if (emulated) continue;
         const created = this.createPlaneEntity(world, plane);
         if (!created) continue;
         entry = created;
@@ -12580,11 +12738,17 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
           if (collider) {
             entry.geometry?.dispose();
             entry.geometry = null;
-            this.attachPlaneDebug(world, entry, collider);
+            this.attachPlaneDebug(
+              world,
+              entry,
+              collider,
+              plane.semanticLabel ?? null
+            );
           }
         }
       }
-      this.applyPose(world, entry.entityId, pose);
+      entry.emulated = emulated;
+      if (!emulated) this.applyPose(world, entry.entityId, pose);
     }
   }
   syncMeshes(world, frame, referenceSpace) {
@@ -12599,9 +12763,11 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
     for (const mesh of detected) {
       const pose = frame.getPose(mesh.meshSpace, referenceSpace);
       if (!pose) continue;
+      const emulated = pose.emulatedPosition === true;
       let entry = this.meshes.get(mesh);
       const changed = mesh.lastChangedTime ?? 0;
       if (!entry) {
+        if (emulated) continue;
         const created = this.createMeshEntity(world, mesh);
         if (!created) continue;
         entry = created;
@@ -12610,7 +12776,8 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
         entry.lastChangedTime = changed;
         writeXrMeshGeometry(mesh.vertices, mesh.indices, entry.geometry);
       }
-      this.applyPose(world, entry.entityId, pose);
+      entry.emulated = emulated;
+      if (!emulated) this.applyPose(world, entry.entityId, pose);
     }
   }
   createPlaneEntity(world, plane) {
@@ -12630,9 +12797,12 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       entityId,
       lastChangedTime: plane.lastChangedTime ?? 0,
       geometry: null,
-      material: null
+      material: null,
+      emulated: false
     };
-    if (this.debugVisible) this.attachPlaneDebug(world, entry, collider);
+    if (this.debugVisible) {
+      this.attachPlaneDebug(world, entry, collider, plane.semanticLabel ?? null);
+    }
     return entry;
   }
   applyPlaneCollider(world, entityId, plane) {
@@ -12657,15 +12827,36 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
   createMeshEntity(world, mesh) {
     if (!mesh.vertices?.length || !mesh.indices?.length) return null;
     const geometry = writeXrMeshGeometry(mesh.vertices, mesh.indices);
+    const label = mesh.semanticLabel ?? null;
+    const isGlobalMesh = label === "global mesh";
     const material = new THREE51__namespace.MeshBasicMaterial({
-      color: DEBUG_COLOR,
-      wireframe: true
+      color: debugColorFor("mesh", label),
+      wireframe: true,
+      // The global scan is a coarse triangle soup of the whole room; at full
+      // strength it reads as phantom objects rather than as context.
+      transparent: isGlobalMesh,
+      opacity: isGlobalMesh ? GLOBAL_MESH_DEBUG_OPACITY : 1,
+      // Depth-TESTED, deliberately. The overlay was X-ray for one release —
+      // introduced on the theory that depth occlusion was carving it into a
+      // head-locked dome — but that theory was falsified (the dome was the
+      // depth mesh's unset colour output, plus emulated poses; both fixed).
+      // X-ray had its own on-device failure: the global scan is DENSE, and a
+      // dense wireframe at 0.35 opacity fuses into a translucent sheet — with
+      // no depth test the walls' sheets drew through everything, stacked in
+      // front of the user's eyes ("planes covering my face"). With the depth
+      // buffer now holding CORRECT real-world depth, normal testing gives the
+      // right picture: the near wall hides the far one. depthWrite stays off
+      // so the overlay never occludes actual content.
+      depthTest: true,
+      depthWrite: false
     });
     const root = new THREE51__namespace.Group();
     const child = new THREE51__namespace.Mesh(geometry, material);
     child.visible = this.debugVisible;
+    child.renderOrder = DEBUG_RENDER_ORDER;
     root.add(child);
     const entityId = world.createEntity();
+    root.userData.entityId = entityId;
     world.addComponents(entityId, [
       new TransformComponent(),
       new Object3DRef(root),
@@ -12679,29 +12870,37 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       entityId,
       lastChangedTime: mesh.lastChangedTime ?? 0,
       geometry,
-      material
+      material,
+      emulated: false
     };
   }
   /** A thin box so a detected plane can be SEEN, not just collided with. */
-  attachPlaneDebug(world, entry, collider) {
-    const geometry = new THREE51__namespace.BoxGeometry(
+  attachPlaneDebug(world, entry, collider, semanticLabel) {
+    const box = new THREE51__namespace.BoxGeometry(
       collider.size.x,
       collider.size.y,
       collider.size.z
     );
-    const material = new THREE51__namespace.MeshBasicMaterial({
-      color: DEBUG_COLOR,
-      wireframe: true
+    const geometry = new THREE51__namespace.EdgesGeometry(box);
+    box.dispose();
+    const material = new THREE51__namespace.LineBasicMaterial({
+      color: debugColorFor("plane", semanticLabel),
+      // Same depth policy as the mesh overlay — see createMeshEntity.
+      depthTest: true,
+      depthWrite: false
     });
     const root = new THREE51__namespace.Group();
-    const child = new THREE51__namespace.Mesh(geometry, material);
+    const child = new THREE51__namespace.LineSegments(geometry, material);
+    child.renderOrder = DEBUG_RENDER_ORDER;
     child.position.set(collider.offset.x, collider.offset.y, collider.offset.z);
     child.visible = this.debugVisible;
     root.add(child);
     entry.geometry = geometry;
     entry.material = material;
+    root.userData.entityId = entry.entityId;
     const existing = world.getComponent(entry.entityId, Object3DRef);
     if (existing) {
+      existing.object.removeFromParent();
       existing.object = root;
     } else {
       world.addComponent(entry.entityId, new Object3DRef(root));
@@ -12717,19 +12916,31 @@ var _XREnvironmentSystem = class _XREnvironmentSystem {
       for (const [plane, entry] of this.planes) {
         if (entry.geometry) continue;
         const collider = planeColliderFromPolygon(plane.polygon);
-        if (collider) this.attachPlaneDebug(world, entry, collider);
+        if (collider) {
+          this.attachPlaneDebug(
+            world,
+            entry,
+            collider,
+            plane.semanticLabel ?? null
+          );
+        }
       }
     }
     for (const map of [this.planes, this.meshes]) {
       for (const entry of map.values()) {
         const ref = world.getComponent(entry.entityId, Object3DRef);
         ref?.object.traverse((child) => {
-          if (child.isMesh) child.visible = this.debugVisible;
+          const drawable = child;
+          if (drawable.isMesh || drawable.isLine) {
+            child.visible = this.debugVisible;
+          }
         });
       }
     }
   }
   destroyEntry(world, entry) {
+    const ref = world.getComponent(entry.entityId, Object3DRef);
+    ref?.object.removeFromParent();
     entry.geometry?.dispose();
     entry.material?.dispose();
     world.destroyEntity(entry.entityId);
@@ -12906,7 +13117,9 @@ var _XRAnchorSystem = class _XRAnchorSystem {
         continue;
       }
       const pose = frame.getPose(anchor.anchorSpace, referenceSpace);
-      if (pose) decomposeXrPose(pose.transform.matrix, transform);
+      if (pose && pose.emulatedPosition !== true) {
+        decomposeXrPose(pose.transform.matrix, transform);
+      }
     }
   }
   /** Whether this entity's pose is currently being driven by an anchor. */