@relu-interactives/spatial-ecs 0.3.20 → 0.4.0

package/dist/systems/index.cjs

@@ -2154,11 +2154,39 @@ var _XRRigComponent = class _XRRigComponent extends Component {
     this.teleportArcColor = options?.teleportArcColor ?? "#4da3ff";
     this.teleportArcInvalidColor = options?.teleportArcInvalidColor ?? "#ff5a5a";
     this.teleportArcThickness = options?.teleportArcThickness ?? 0.012;
+    this.passthrough = options?.passthrough ?? false;
+    this.depthOcclusion = options?.depthOcclusion ?? false;
+    this.environmentPhysics = options?.environmentPhysics ?? "none";
+    this.environmentDebug = options?.environmentDebug ?? false;
+    this.hitTest = options?.hitTest ?? false;
+    this.anchors = options?.anchors ?? false;
   }
 };
 __name(_XRRigComponent, "XRRigComponent");
 var XRRigComponent = _XRRigComponent;
 
+// core/components/XREnvironment.ts
+var _XREnvironmentComponent = class _XREnvironmentComponent extends Component {
+  constructor(kind, semanticLabel = null, orientation = null) {
+    super();
+    this.kind = kind;
+    this.semanticLabel = semanticLabel;
+    this.orientation = orientation;
+  }
+};
+__name(_XREnvironmentComponent, "XREnvironmentComponent");
+var XREnvironmentComponent = _XREnvironmentComponent;
+
+// core/components/XRAnchor.ts
+var _XRAnchorComponent = class _XRAnchorComponent extends Component {
+  constructor(options) {
+    super();
+    this.enabled = options?.enabled ?? true;
+  }
+};
+__name(_XRAnchorComponent, "XRAnchorComponent");
+var XRAnchorComponent = _XRAnchorComponent;
+
 // core/components/XRInteractor.ts
 var _XRInteractorComponent = class _XRInteractorComponent extends Component {
   constructor(options) {
@@ -3045,6 +3073,8 @@ var _EnvironmentSyncSystem = class _EnvironmentSyncSystem {
     this.signature = null;
     this.activeTexture = null;
     this.pendingImageUrl = null;
+    /** Whether the skybox is currently withheld because passthrough is on. */
+    this.passthroughSuppressed = false;
     this.scene = scene;
   }
   disposeActiveTexture() {
@@ -3129,6 +3159,18 @@ var _EnvironmentSyncSystem = class _EnvironmentSyncSystem {
     this.scene.fog = new THREE26__namespace.FogExp2(fogColor, density);
   }
   update(world) {
+    const passthrough = world.isXrPassthrough();
+    if (passthrough !== this.passthroughSuppressed) {
+      this.passthroughSuppressed = passthrough;
+      if (passthrough) {
+        this.scene.background = null;
+      } else {
+        this.signature = null;
+      }
+    }
+    if (passthrough) {
+      return;
+    }
     const entityIds = world.query(Environment);
     if (entityIds.length === 0) {
       if (this.signature !== null) {
@@ -5398,6 +5440,24 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       if (typeof sourceXrRig.fallbackEyeHeight === "number") {
         rig.fallbackEyeHeight = sourceXrRig.fallbackEyeHeight;
       }
+      if (typeof sourceXrRig.passthrough === "boolean") {
+        rig.passthrough = sourceXrRig.passthrough;
+      }
+      if (typeof sourceXrRig.depthOcclusion === "boolean") {
+        rig.depthOcclusion = sourceXrRig.depthOcclusion;
+      }
+      if (typeof sourceXrRig.environmentPhysics === "string") {
+        rig.environmentPhysics = sourceXrRig.environmentPhysics;
+      }
+      if (typeof sourceXrRig.environmentDebug === "boolean") {
+        rig.environmentDebug = sourceXrRig.environmentDebug;
+      }
+      if (typeof sourceXrRig.hitTest === "boolean") {
+        rig.hitTest = sourceXrRig.hitTest;
+      }
+      if (typeof sourceXrRig.anchors === "boolean") {
+        rig.anchors = sourceXrRig.anchors;
+      }
     }
   }
   {
@@ -9650,6 +9710,509 @@ var _XRSessionSystem = class _XRSessionSystem {
 };
 __name(_XRSessionSystem, "XRSessionSystem");
 var XRSessionSystem = _XRSessionSystem;
+var PLANE_COLLIDER_THICKNESS = 0.02;
+var MIN_PLANE_EXTENT = 0.01;
+function planeColliderFromPolygon(polygon) {
+  if (!polygon || polygon.length < 3) return null;
+  let minX = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let minZ = Number.POSITIVE_INFINITY;
+  let maxZ = Number.NEGATIVE_INFINITY;
+  for (const point of polygon) {
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.z)) return null;
+    minX = Math.min(minX, point.x);
+    maxX = Math.max(maxX, point.x);
+    minZ = Math.min(minZ, point.z);
+    maxZ = Math.max(maxZ, point.z);
+  }
+  const width = maxX - minX;
+  const depth = maxZ - minZ;
+  if (width < MIN_PLANE_EXTENT || depth < MIN_PLANE_EXTENT) return null;
+  return {
+    // Thin on Y: that is the plane's normal in plane space.
+    size: { x: width, y: PLANE_COLLIDER_THICKNESS, z: depth },
+    // The polygon is not necessarily centred on its own origin, so the box has
+    // to be offset to sit over it. Pushed DOWN half its thickness so the
+    // collider's top face lines up with the real surface — otherwise objects
+    // rest a centimetre above the floor, or sink a centimetre into it.
+    offset: {
+      x: (minX + maxX) / 2,
+      y: -PLANE_COLLIDER_THICKNESS / 2,
+      z: (minZ + maxZ) / 2
+    }
+  };
+}
+__name(planeColliderFromPolygon, "planeColliderFromPolygon");
+function writeXrMeshGeometry(vertices, indices, existing) {
+  const geometry = existing ?? new THREE26__namespace.BufferGeometry();
+  geometry.setAttribute("position", new THREE26__namespace.BufferAttribute(vertices, 3));
+  geometry.setIndex(new THREE26__namespace.BufferAttribute(indices, 1));
+  geometry.computeBoundingSphere();
+  geometry.computeVertexNormals();
+  return geometry;
+}
+__name(writeXrMeshGeometry, "writeXrMeshGeometry");
+function decomposeXrPose(matrixElements, target) {
+  const matrix = new THREE26__namespace.Matrix4().fromArray(
+    matrixElements
+  );
+  const position = new THREE26__namespace.Vector3();
+  const quaternion = new THREE26__namespace.Quaternion();
+  const scale = new THREE26__namespace.Vector3();
+  matrix.decompose(position, quaternion, scale);
+  const euler = new THREE26__namespace.Euler().setFromQuaternion(quaternion, "XYZ");
+  target.position.x = position.x;
+  target.position.y = position.y;
+  target.position.z = position.z;
+  target.rotation.x = euler.x;
+  target.rotation.y = euler.y;
+  target.rotation.z = euler.z;
+}
+__name(decomposeXrPose, "decomposeXrPose");
+
+// core/systems/XREnvironmentSystem.ts
+var DEBUG_COLOR = 5088255;
+var _XREnvironmentSystem = class _XREnvironmentSystem {
+  constructor() {
+    /** Keyed by the XRPlane/XRMesh object itself — the runtime's own identity. */
+    this.planes = /* @__PURE__ */ new Map();
+    this.meshes = /* @__PURE__ */ new Map();
+    this.presenting = false;
+    this.debugVisible = false;
+  }
+  update(world) {
+    const presenting = world.isXrPresenting();
+    if (!presenting) {
+      if (this.presenting) {
+        this.presenting = false;
+        this.clearAll(world);
+      }
+      return;
+    }
+    this.presenting = true;
+    const rig = this.findRig(world);
+    const mode = rig?.environmentPhysics ?? "none";
+    if (mode === "none") {
+      if (this.planes.size > 0 || this.meshes.size > 0) this.clearAll(world);
+      return;
+    }
+    const debug = rig?.environmentDebug === true;
+    if (debug !== this.debugVisible) {
+      this.debugVisible = debug;
+      this.applyDebugVisibility(world);
+    }
+    const xr = world.getRenderer().xr;
+    const frame = xr.getFrame?.();
+    const referenceSpace = xr.getReferenceSpace();
+    if (!frame || !referenceSpace) return;
+    const meshesAvailable = Boolean(frame.detectedMeshes);
+    const useMesh = (mode === "mesh" || mode === "auto") && meshesAvailable;
+    const usePlanes = mode === "planes" || mode === "auto" && !useMesh;
+    if (usePlanes) {
+      this.syncPlanes(world, frame, referenceSpace);
+    } else if (this.planes.size > 0) {
+      this.clearMap(world, this.planes);
+    }
+    if (useMesh) {
+      this.syncMeshes(world, frame, referenceSpace);
+    } else if (this.meshes.size > 0) {
+      this.clearMap(world, this.meshes);
+    }
+  }
+  /** How many pieces of real geometry are currently colliding. Script-facing. */
+  getDetectedCount() {
+    return { planes: this.planes.size, meshes: this.meshes.size };
+  }
+  findRig(world) {
+    const ids = world.query(XRRigComponent);
+    if (ids.length === 0) return null;
+    return world.getComponent(ids[0], XRRigComponent) ?? null;
+  }
+  syncPlanes(world, frame, referenceSpace) {
+    const detected = frame.detectedPlanes;
+    if (!detected) return;
+    for (const [plane, entry] of this.planes) {
+      if (!detected.has(plane)) {
+        this.destroyEntry(world, entry);
+        this.planes.delete(plane);
+      }
+    }
+    for (const plane of detected) {
+      const pose = frame.getPose(plane.planeSpace, referenceSpace);
+      if (!pose) continue;
+      let entry = this.planes.get(plane);
+      const changed = plane.lastChangedTime ?? 0;
+      if (!entry) {
+        const created = this.createPlaneEntity(world, plane);
+        if (!created) continue;
+        entry = created;
+        this.planes.set(plane, entry);
+      } else if (changed !== entry.lastChangedTime) {
+        entry.lastChangedTime = changed;
+        this.applyPlaneCollider(world, entry.entityId, plane);
+      }
+      this.applyPose(world, entry.entityId, pose);
+    }
+  }
+  syncMeshes(world, frame, referenceSpace) {
+    const detected = frame.detectedMeshes;
+    if (!detected) return;
+    for (const [mesh, entry] of this.meshes) {
+      if (!detected.has(mesh)) {
+        this.destroyEntry(world, entry);
+        this.meshes.delete(mesh);
+      }
+    }
+    for (const mesh of detected) {
+      const pose = frame.getPose(mesh.meshSpace, referenceSpace);
+      if (!pose) continue;
+      let entry = this.meshes.get(mesh);
+      const changed = mesh.lastChangedTime ?? 0;
+      if (!entry) {
+        const created = this.createMeshEntity(world, mesh);
+        if (!created) continue;
+        entry = created;
+        this.meshes.set(mesh, entry);
+      } else if (changed !== entry.lastChangedTime) {
+        entry.lastChangedTime = changed;
+        writeXrMeshGeometry(mesh.vertices, mesh.indices, entry.geometry);
+      }
+      this.applyPose(world, entry.entityId, pose);
+    }
+  }
+  createPlaneEntity(world, plane) {
+    const collider = planeColliderFromPolygon(plane.polygon);
+    if (!collider) return null;
+    const entityId = world.createEntity();
+    world.addComponents(entityId, [
+      new TransformComponent(),
+      new XREnvironmentComponent(
+        "plane",
+        plane.semanticLabel ?? null,
+        normalizeOrientation(plane.orientation)
+      )
+    ]);
+    this.applyPlaneCollider(world, entityId, plane);
+    const entry = {
+      entityId,
+      lastChangedTime: plane.lastChangedTime ?? 0,
+      geometry: null,
+      material: null
+    };
+    if (this.debugVisible) this.attachPlaneDebug(world, entry, collider);
+    return entry;
+  }
+  applyPlaneCollider(world, entityId, plane) {
+    const collider = planeColliderFromPolygon(plane.polygon);
+    if (!collider) return;
+    const existing = world.getComponent(entityId, PhysicsComponent);
+    const values = {
+      // Fixed: the real room does not move because something hit it.
+      rigidbody: { type: "fixed" },
+      collider: {
+        shape: "cuboid",
+        size: collider.size,
+        offsetPosition: collider.offset
+      }
+    };
+    if (existing) {
+      existing.setValues(values);
+    } else {
+      world.addComponent(entityId, new PhysicsComponent(values));
+    }
+  }
+  createMeshEntity(world, mesh) {
+    if (!mesh.vertices?.length || !mesh.indices?.length) return null;
+    const geometry = writeXrMeshGeometry(mesh.vertices, mesh.indices);
+    const material = new THREE26__namespace.MeshBasicMaterial({
+      color: DEBUG_COLOR,
+      wireframe: true
+    });
+    const root = new THREE26__namespace.Group();
+    const child = new THREE26__namespace.Mesh(geometry, material);
+    child.visible = this.debugVisible;
+    root.add(child);
+    const entityId = world.createEntity();
+    world.addComponents(entityId, [
+      new TransformComponent(),
+      new Object3DRef(root),
+      new XREnvironmentComponent("mesh", mesh.semanticLabel ?? null, null),
+      new PhysicsComponent({
+        rigidbody: { type: "fixed" },
+        collider: { shape: "trimesh" }
+      })
+    ]);
+    return {
+      entityId,
+      lastChangedTime: mesh.lastChangedTime ?? 0,
+      geometry,
+      material
+    };
+  }
+  /** A thin box so a detected plane can be SEEN, not just collided with. */
+  attachPlaneDebug(world, entry, collider) {
+    const geometry = new THREE26__namespace.BoxGeometry(
+      collider.size.x,
+      collider.size.y,
+      collider.size.z
+    );
+    const material = new THREE26__namespace.MeshBasicMaterial({
+      color: DEBUG_COLOR,
+      wireframe: true
+    });
+    const root = new THREE26__namespace.Group();
+    root.add(new THREE26__namespace.Mesh(geometry, material));
+    entry.geometry = geometry;
+    entry.material = material;
+    world.addComponent(entry.entityId, new Object3DRef(root));
+  }
+  applyPose(world, entityId, pose) {
+    const transform = world.getComponent(entityId, TransformComponent);
+    if (!transform) return;
+    decomposeXrPose(pose.transform.matrix, transform);
+  }
+  applyDebugVisibility(world) {
+    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;
+        });
+      }
+    }
+  }
+  destroyEntry(world, entry) {
+    entry.geometry?.dispose();
+    entry.material?.dispose();
+    world.destroyEntity(entry.entityId);
+  }
+  clearMap(world, map) {
+    for (const entry of map.values()) this.destroyEntry(world, entry);
+    map.clear();
+  }
+  clearAll(world) {
+    this.clearMap(world, this.planes);
+    this.clearMap(world, this.meshes);
+  }
+  dispose(world) {
+    this.clearAll(world);
+  }
+};
+__name(_XREnvironmentSystem, "XREnvironmentSystem");
+var XREnvironmentSystem = _XREnvironmentSystem;
+function normalizeOrientation(value) {
+  return value === "horizontal" || value === "vertical" ? value : null;
+}
+__name(normalizeOrientation, "normalizeOrientation");
+var _XRHitTestSystem = class _XRHitTestSystem {
+  constructor() {
+    this.sources = /* @__PURE__ */ new Map();
+    /** Targets whose async request is in flight, so it is not fired twice. */
+    this.pending = /* @__PURE__ */ new Set();
+    this.results = /* @__PURE__ */ new Map();
+    this.presenting = false;
+    this.enabled = false;
+  }
+  update(world) {
+    const presenting = world.isXrPresenting();
+    if (!presenting) {
+      if (this.presenting) {
+        this.presenting = false;
+        this.teardown();
+      }
+      return;
+    }
+    if (!this.presenting) {
+      this.presenting = true;
+      this.enabled = this.rigWantsHitTest(world);
+    }
+    if (!this.enabled) return;
+    const xr = world.getRenderer().xr;
+    const session = xr.getSession();
+    const referenceSpace = xr.getReferenceSpace();
+    const frame = xr.getFrame?.();
+    if (!session || !referenceSpace || !frame) return;
+    this.ensureViewerSource(session);
+    this.ensureInputSources(session);
+    this.results.clear();
+    for (const [key, source] of this.sources) {
+      const hits = frame.getHitTestResults(source);
+      if (!hits || hits.length === 0) continue;
+      const pose = hits[0].getPose(referenceSpace);
+      if (!pose) continue;
+      const matrix = new THREE26__namespace.Matrix4().fromArray(
+        pose.transform.matrix
+      );
+      const position = new THREE26__namespace.Vector3();
+      const quaternion = new THREE26__namespace.Quaternion();
+      matrix.decompose(position, quaternion, new THREE26__namespace.Vector3());
+      this.results.set(key, { position, quaternion });
+    }
+  }
+  /**
+   * Where the given ray meets the real world this frame, or null.
+   *
+   * Null is the normal case, not an error: the source may still be being
+   * requested, the ray may point at nothing recognised, or the runtime may not
+   * have granted `hit-test` at all.
+   */
+  getHitResult(target = "viewer") {
+    return this.results.get(target) ?? null;
+  }
+  rigWantsHitTest(world) {
+    const ids = world.query(XRRigComponent);
+    if (ids.length === 0) return false;
+    return world.getComponent(ids[0], XRRigComponent)?.hitTest === true;
+  }
+  ensureViewerSource(session) {
+    if (this.sources.has("viewer") || this.pending.has("viewer")) return;
+    if (typeof session.requestHitTestSource !== "function") return;
+    this.pending.add("viewer");
+    void session.requestReferenceSpace("viewer").then((space) => session.requestHitTestSource?.({ space })).then((source) => {
+      if (source && this.presenting) this.sources.set("viewer", source);
+      else source?.cancel?.();
+    }).catch(() => {
+    }).finally(() => this.pending.delete("viewer"));
+  }
+  ensureInputSources(session) {
+    if (typeof session.requestHitTestSource !== "function") return;
+    if (!session.inputSources) return;
+    for (const input of session.inputSources) {
+      const handedness = input.handedness;
+      if (!handedness || handedness === "none") continue;
+      if (!input.targetRaySpace) continue;
+      if (this.sources.has(handedness) || this.pending.has(handedness)) continue;
+      this.pending.add(handedness);
+      const request = session.requestHitTestSource({
+        space: input.targetRaySpace
+      });
+      if (!request) {
+        this.pending.delete(handedness);
+        continue;
+      }
+      void request.then((source) => {
+        if (source && this.presenting) this.sources.set(handedness, source);
+        else source?.cancel?.();
+      }).catch(() => {
+      }).finally(() => this.pending.delete(handedness));
+    }
+  }
+  teardown() {
+    for (const source of this.sources.values()) source.cancel?.();
+    this.sources.clear();
+    this.results.clear();
+    this.pending.clear();
+    this.enabled = false;
+  }
+  dispose() {
+    this.presenting = false;
+    this.teardown();
+  }
+};
+__name(_XRHitTestSystem, "XRHitTestSystem");
+var XRHitTestSystem = _XRHitTestSystem;
+var _XRAnchorSystem = class _XRAnchorSystem {
+  constructor() {
+    this.anchors = /* @__PURE__ */ new Map();
+    /** In-flight creations, so one entity is not anchored twice. */
+    this.pending = /* @__PURE__ */ new Set();
+    this.presenting = false;
+  }
+  update(world) {
+    const presenting = world.isXrPresenting();
+    if (!presenting) {
+      if (this.presenting) {
+        this.presenting = false;
+        this.releaseAll();
+      }
+      return;
+    }
+    this.presenting = true;
+    const xr = world.getRenderer().xr;
+    const referenceSpace = xr.getReferenceSpace();
+    const frame = xr.getFrame?.();
+    if (!frame || !referenceSpace) return;
+    const entityIds = world.query(XRAnchorComponent, TransformComponent);
+    const live = new Set(entityIds);
+    for (const [entityId, anchor] of this.anchors) {
+      if (!live.has(entityId)) {
+        anchor.delete?.();
+        this.anchors.delete(entityId);
+      }
+    }
+    for (const entityId of entityIds) {
+      const component = world.getComponent(entityId, XRAnchorComponent);
+      const transform = world.getComponent(entityId, TransformComponent);
+      if (!component || !transform) continue;
+      if (!component.enabled) {
+        const existing = this.anchors.get(entityId);
+        if (existing) {
+          existing.delete?.();
+          this.anchors.delete(entityId);
+        }
+        continue;
+      }
+      const anchor = this.anchors.get(entityId);
+      if (!anchor) {
+        this.requestAnchor(entityId, transform, frame, referenceSpace);
+        continue;
+      }
+      const pose = frame.getPose(anchor.anchorSpace, referenceSpace);
+      if (pose) decomposeXrPose(pose.transform.matrix, transform);
+    }
+  }
+  /** Whether this entity's pose is currently being driven by an anchor. */
+  isAnchored(entityId) {
+    return this.anchors.has(entityId);
+  }
+  requestAnchor(entityId, transform, frame, referenceSpace) {
+    if (this.pending.has(entityId)) return;
+    if (typeof frame.createAnchor !== "function") return;
+    const RigidTransform = globalThis.XRRigidTransform;
+    if (!RigidTransform) return;
+    const quaternion = new THREE26__namespace.Quaternion().setFromEuler(
+      new THREE26__namespace.Euler(
+        transform.rotation.x,
+        transform.rotation.y,
+        transform.rotation.z,
+        "XYZ"
+      )
+    );
+    const pose = new RigidTransform(
+      {
+        x: transform.position.x,
+        y: transform.position.y,
+        z: transform.position.z,
+        w: 1
+      },
+      {
+        x: quaternion.x,
+        y: quaternion.y,
+        z: quaternion.z,
+        w: quaternion.w
+      }
+    );
+    const request = frame.createAnchor(pose, referenceSpace);
+    if (!request) return;
+    this.pending.add(entityId);
+    void request.then((anchor) => {
+      if (anchor && this.presenting) this.anchors.set(entityId, anchor);
+      else anchor?.delete?.();
+    }).catch(() => {
+    }).finally(() => this.pending.delete(entityId));
+  }
+  releaseAll() {
+    for (const anchor of this.anchors.values()) anchor.delete?.();
+    this.anchors.clear();
+    this.pending.clear();
+  }
+  dispose() {
+    this.presenting = false;
+    this.releaseAll();
+  }
+};
+__name(_XRAnchorSystem, "XRAnchorSystem");
+var XRAnchorSystem = _XRAnchorSystem;
 function buildGeometry2(area) {
   if (area.shape === "circle") {
     const radius = Math.max(5e-3, area.width / 2);
@@ -10905,8 +11468,11 @@ exports.ScriptObjectSystem = ScriptObjectSystem;
 exports.TransformSyncSystem = TransformSyncSystem;
 exports.VRTeleportAreaSystem = VRTeleportAreaSystem;
 exports.VideoSystem = VideoSystem;
+exports.XRAnchorSystem = XRAnchorSystem;
 exports.XRControllerVisualSystem = XRControllerVisualSystem;
+exports.XREnvironmentSystem = XREnvironmentSystem;
 exports.XRHandPoseSystem = XRHandPoseSystem;
+exports.XRHitTestSystem = XRHitTestSystem;
 exports.XRHoverVisualSystem = XRHoverVisualSystem;
 exports.XRInputSystem = XRInputSystem;
 exports.XRInteractionSystem = XRInteractionSystem;