@relu-interactives/spatial-ecs 0.4.3 → 0.4.4

package/dist/docs/guide/mixed-reality.md

@@ -41,6 +41,29 @@ Each detected surface becomes an ordinary entity, so it goes through the same
 physics as everything else: a dynamic rigidbody dropped in a mixed-reality scene
 lands on the real floor with no extra code.
 
+### The room has to have been scanned first
+
+This is the single most common reason a mixed-reality scene comes up empty, and
+it is not a bug in the experience.
+
+**Plane and mesh detection do not scan anything.** They replay a scan the user
+captured earlier through the headset's own room setup — on Quest, *Settings >
+Guardian > Mixed Reality* (Space Setup). If the user has never run it,
+`detectedPlanes` and `detectedMeshes` simply stay empty, with no prompt and no
+error. If they ran it in a **different room**, you get that room's furniture
+overlaid on this one, which looks like the tracking is broken.
+
+`XREnvironmentSystem` handles this: when `environmentPhysics` is on and nothing
+at all has been detected three seconds into the session, it calls
+`XRSession.initiateRoomCapture()`, which launches room setup from inside the
+session. It is a Meta extension, so it is feature-detected and silently skipped
+elsewhere, and — per Meta's contract — it is only ever called **once per
+session**.
+
+If a user reports "it never asked to scan my room" and the geometry does not
+match, they are almost certainly running against a stale scan from another
+space; re-running Space Setup for the current room fixes it.
+
 ## Finding the real room from a script
 
 Detected surfaces carry `XREnvironmentComponent`, so they are queryable like any

package/dist/{index-CBdnIyI8.d.cts → index-7YCk4cmQ.d.cts}

@@ -647,6 +647,8 @@ declare class XRSessionSystem implements EcsSystem {
     private readonly inputSystem;
     /** Y compensation applied when a floor-relative space was requested but not granted. */
     private appliedOriginOffset;
+    /** The live session, so an async floor probe can tell if it has been replaced. */
+    private session;
     constructor(inputSystem?: XRInputSystem);
     update(world: World): void;
     private handleSessionStart;
@@ -690,7 +692,27 @@ declare class XREnvironmentSystem implements EcsSystem {
     private readonly meshes;
     private presenting;
     private debugVisible;
-    update(world: World): void;
+    /** Seconds presenting, used to decide the room has genuinely nothing in it. */
+    private elapsed;
+    /** `initiateRoomCapture` may be called only ONCE per session. */
+    private roomCaptureRequested;
+    update(world: World, deltaTime?: number): void;
+    /**
+     * 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.
+     */
+    private maybeCaptureRoom;
     /** How many pieces of real geometry are currently colliding. Script-facing. */
     getDetectedCount(): {
         planes: number;

package/dist/{index-n7SeH119.d.ts → index-B2oHfqkj.d.ts}

@@ -647,6 +647,8 @@ declare class XRSessionSystem implements EcsSystem {
     private readonly inputSystem;
     /** Y compensation applied when a floor-relative space was requested but not granted. */
     private appliedOriginOffset;
+    /** The live session, so an async floor probe can tell if it has been replaced. */
+    private session;
     constructor(inputSystem?: XRInputSystem);
     update(world: World): void;
     private handleSessionStart;
@@ -690,7 +692,27 @@ declare class XREnvironmentSystem implements EcsSystem {
     private readonly meshes;
     private presenting;
     private debugVisible;
-    update(world: World): void;
+    /** Seconds presenting, used to decide the room has genuinely nothing in it. */
+    private elapsed;
+    /** `initiateRoomCapture` may be called only ONCE per session. */
+    private roomCaptureRequested;
+    update(world: World, deltaTime?: number): void;
+    /**
+     * 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.
+     */
+    private maybeCaptureRoom;
     /** How many pieces of real geometry are currently colliding. Script-facing. */
     getDetectedCount(): {
         planes: number;

package/dist/index.cjs

@@ -12305,6 +12305,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) {
@@ -12323,6 +12325,7 @@ var _XRSessionSystem = class _XRSessionSystem {
   }
   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 +12364,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 +12384,7 @@ var _XRSessionSystem = class _XRSessionSystem {
       }
       this.appliedOriginOffset = 0;
     }
+    this.session = null;
     this.capabilities = NO_XR_CAPABILITIES;
     this.inputSystem?.detachSession();
     this.forEachBehaviour(world, (behaviour) => {
@@ -12497,6 +12501,7 @@ __name(decomposeXrPose, "decomposeXrPose");
 
 // core/systems/XREnvironmentSystem.ts
 var DEBUG_COLOR = 5088255;
+var ROOM_CAPTURE_DELAY_SECONDS = 3;
 var _XREnvironmentSystem = class _XREnvironmentSystem {
   constructor() {
     /** Keyed by the XRPlane/XRMesh object itself — the runtime's own identity. */
@@ -12504,17 +12509,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") {
@@ -12543,6 +12555,34 @@ 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() {