@relu-interactives/spatial-ecs 0.2.25 → 0.3.1

package/dist/systems/index.cjs

@@ -1719,6 +1719,22 @@ function getMaterialType(material) {
   return "standard";
 }
 __name(getMaterialType, "getMaterialType");
+function textureImageSrc(texture) {
+  const src = texture?.image?.src;
+  return typeof src === "string" ? src : void 0;
+}
+__name(textureImageSrc, "textureImageSrc");
+function textureSourceUrl(texture) {
+  if (!texture?.image) {
+    return void 0;
+  }
+  const currentSrc = texture.source?.data?.currentSrc;
+  if (typeof currentSrc === "string" && currentSrc) {
+    return currentSrc;
+  }
+  return textureImageSrc(texture);
+}
+__name(textureSourceUrl, "textureSourceUrl");
 function createMaterialValue(material) {
   const materialRecord = material;
   const normalScale = materialRecord.normalScale;
@@ -1738,17 +1754,33 @@ function createMaterialValue(material) {
     depthWrite: materialRecord.depthWrite !== false,
     wireframe: Boolean(materialRecord.wireframe),
     transparent: Boolean(materialRecord.transparent),
-    textureMap: map?.image ? map.source?.data?.currentSrc || map.image?.src : void 0,
-    alphaTextureMap: materialRecord.alphaMap?.image?.src,
-    normalMap: materialRecord.normalMap?.image?.src,
-    roughnessMap: materialRecord.roughnessMap?.image?.src,
-    metalnessMap: materialRecord.metalnessMap?.image?.src,
-    aoMap: materialRecord.aoMap?.image?.src,
-    emissiveMap: materialRecord.emissiveMap?.image?.src,
-    bumpMap: materialRecord.bumpMap?.image?.src,
-    displacementMap: materialRecord.displacementMap?.image?.src,
-    lightMap: materialRecord.lightMap?.image?.src,
-    envMap: materialRecord.envMap?.image?.src,
+    textureMap: textureSourceUrl(map),
+    alphaTextureMap: textureImageSrc(
+      materialRecord.alphaMap
+    ),
+    normalMap: textureImageSrc(
+      materialRecord.normalMap
+    ),
+    roughnessMap: textureImageSrc(
+      materialRecord.roughnessMap
+    ),
+    metalnessMap: textureImageSrc(
+      materialRecord.metalnessMap
+    ),
+    aoMap: textureImageSrc(materialRecord.aoMap),
+    emissiveMap: textureImageSrc(
+      materialRecord.emissiveMap
+    ),
+    bumpMap: textureImageSrc(
+      materialRecord.bumpMap
+    ),
+    displacementMap: textureImageSrc(
+      materialRecord.displacementMap
+    ),
+    lightMap: textureImageSrc(
+      materialRecord.lightMap
+    ),
+    envMap: textureImageSrc(materialRecord.envMap),
     textureFiltering: map?.magFilter === THREE14__namespace.NearestFilter ? "sharp" : "smooth",
     useMipmaps: map?.generateMipmaps !== false
   };
@@ -2043,6 +2075,47 @@ var _VideoComponent = class _VideoComponent extends Component {
 __name(_VideoComponent, "VideoComponent");
 var VideoComponent = _VideoComponent;
 
+// core/components/VRTeleportArea.ts
+var _VRTeleportAreaComponent = class _VRTeleportAreaComponent extends Component {
+  constructor(options) {
+    super();
+    this.enabled = options?.enabled ?? true;
+    this.shape = options?.shape ?? "plane";
+    this.width = options?.width ?? 10;
+    this.depth = options?.depth ?? 10;
+  }
+};
+__name(_VRTeleportAreaComponent, "VRTeleportAreaComponent");
+var VRTeleportAreaComponent = _VRTeleportAreaComponent;
+
+// core/components/XRInteractable.ts
+var _XRInteractableComponent = class _XRInteractableComponent extends Component {
+  constructor(options) {
+    super();
+    this.enabled = options?.enabled ?? true;
+    this.grabbable = options?.grabbable ?? true;
+    this.pointable = options?.pointable ?? true;
+    this.grabMode = options?.grabMode ?? "kinematic";
+    this.highlightOnHover = options?.highlightOnHover ?? true;
+  }
+};
+__name(_XRInteractableComponent, "XRInteractableComponent");
+var XRInteractableComponent = _XRInteractableComponent;
+
+// core/components/XRRig.ts
+var _XRRigComponent = class _XRRigComponent extends Component {
+  constructor(options) {
+    super();
+    this.locomotion = options?.locomotion ?? "teleport";
+    this.moveSpeed = options?.moveSpeed ?? 2;
+    this.snapTurn = options?.snapTurn ?? true;
+    this.snapTurnDegrees = options?.snapTurnDegrees ?? 30;
+    this.fallbackEyeHeight = options?.fallbackEyeHeight ?? 1.6;
+  }
+};
+__name(_XRRigComponent, "XRRigComponent");
+var XRRigComponent = _XRRigComponent;
+
 // core/utils/dracoDecoderPath.ts
 var LOCAL_DRACO_DECODER_RELATIVE_PATH = "./assets/draco/";
 var DRACO_DECODER_CDN_PATH = "https://www.gstatic.com/draco/versioned/decoders/1.5.7/";
@@ -2549,6 +2622,7 @@ var _CameraSyncSystem = class _CameraSyncSystem {
   update(world) {
     const entityIds = world.query(CameraComponent, Object3DRef);
     const windowAspect = readWindowAspect();
+    const xrCamera = world.isXrPresenting() ? world.getCamera() : null;
     const alive = new Set(entityIds);
     for (const trackedId of this.signatures.keys()) {
       if (!alive.has(trackedId)) {
@@ -2565,6 +2639,9 @@ var _CameraSyncSystem = class _CameraSyncSystem {
       if (!(camera instanceof THREE14__namespace.Camera)) {
         continue;
       }
+      if (xrCamera !== null && camera === xrCamera) {
+        continue;
+      }
       const nextSignature = buildSignature(component, camera, windowAspect);
       if (this.signatures.get(entityId) === nextSignature) {
         continue;
@@ -4067,6 +4144,7 @@ function applyMaterialState(material, value, textureCache) {
   }
   target.side = value.side;
   target.blending = value.blending;
+  target.premultipliedAlpha = value.blending === THREE14__namespace.MultiplyBlending || value.blending === THREE14__namespace.SubtractiveBlending;
   target.depthTest = value.depthTest;
   target.depthWrite = value.depthWrite;
   target.wireframe = value.wireframe;
@@ -5535,7 +5613,9 @@ var HYDRATABLE_ENTITY_KINDS = /* @__PURE__ */ new Set([
   "areaLight",
   "instancedMesh",
   "instanceSlot",
-  "scriptObject"
+  "scriptObject",
+  "xrRig",
+  "teleportArea"
 ]);
 
 // core/hydration/hydrateWorld.ts
@@ -6239,6 +6319,49 @@ var _Behaviour = class _Behaviour {
    */
   onTargetLost(target) {
   }
+  // ─── WebXR (VR / MR) hooks ────────────────────────────────────────────────
+  // Dispatched by XRSessionSystem / XRInteractionSystem, following the same
+  // pattern as the AR hooks above: public no-op methods that subclasses opt
+  // into by overriding. They never fire outside an immersive session.
+  /**
+   * Called once when an immersive session starts. Optional XR hook.
+   *
+   * Use it to set up XR-only state. Inspect `capabilities` rather than guessing
+   * by device: feature support differs sharply per headset (for example Vision
+   * Pro grants no passthrough on the web today).
+   *
+   * @param capabilities - What the session actually granted, read from
+   *   `XRSession.enabledFeatures`.
+   */
+  onXRSessionStart(capabilities) {
+  }
+  /** Called once when the immersive session ends. Optional XR hook. */
+  onXRSessionEnd() {
+  }
+  /**
+   * Called when a primary action begins — controller trigger, hand pinch, or
+   * Vision Pro gaze-pinch. Optional XR hook.
+   *
+   * @param input - Normalized state for the source that acted.
+   */
+  onSelectStart(input) {
+  }
+  /** Called when the primary action ends. Optional XR hook. */
+  onSelectEnd(input) {
+  }
+  /**
+   * Called when this entity is grabbed. Optional XR hook.
+   *
+   * Only fires for entities carrying an enabled, grabbable
+   * `XRInteractableComponent`.
+   *
+   * @param input - The source doing the grabbing.
+   */
+  onGrab(input) {
+  }
+  /** Called when this entity is released. Optional XR hook. */
+  onRelease(input) {
+  }
 };
 __name(_Behaviour, "Behaviour");
 /**
@@ -7086,12 +7209,16 @@ var ScriptObjectSystem = _ScriptObjectSystem;
 var _TransformSyncSystem = class _TransformSyncSystem {
   update(world) {
     const entities = world.query(TransformComponent, Object3DRef);
+    const xrCamera = world.isXrPresenting() ? world.getCamera() : null;
     for (const entityId of entities) {
       const transform = world.getComponent(entityId, TransformComponent);
       const object = world.getComponent(entityId, Object3DRef)?.object;
       if (!transform || !object) {
         continue;
       }
+      if (xrCamera !== null && object === xrCamera) {
+        continue;
+      }
       applyTransform(object, transform);
       object.updateMatrixWorld(true);
     }
@@ -7342,6 +7469,580 @@ var _VideoSystem = class _VideoSystem {
 };
 __name(_VideoSystem, "VideoSystem");
 var VideoSystem = _VideoSystem;
+function handednessOf(source) {
+  const value = source.handedness;
+  return value === "left" || value === "right" ? value : "none";
+}
+__name(handednessOf, "handednessOf");
+function kindOf(source) {
+  const mode = source.targetRayMode;
+  if (mode === "transient-pointer") return "transient-pointer";
+  if (mode === "gaze") return "gaze";
+  if (source.hand) return "hand";
+  return "controller";
+}
+__name(kindOf, "kindOf");
+function blankState(source) {
+  return {
+    handedness: handednessOf(source),
+    kind: kindOf(source),
+    connected: true,
+    rayOrigin: new THREE14__namespace.Vector3(),
+    rayDirection: new THREE14__namespace.Vector3(0, 0, -1),
+    gripPosition: null,
+    gripQuaternion: null,
+    select: false,
+    selectStart: false,
+    selectEnd: false,
+    squeeze: false,
+    squeezeStart: false,
+    squeezeEnd: false,
+    axes: [],
+    hasAxes: false,
+    buttons: []
+  };
+}
+__name(blankState, "blankState");
+var _XRInputSystem = class _XRInputSystem {
+  constructor() {
+    this.records = /* @__PURE__ */ new Map();
+    this.session = null;
+    this.onSelectStart = /* @__PURE__ */ __name((event) => this.mark(event, "pendingSelectStart"), "onSelectStart");
+    this.onSelectEnd = /* @__PURE__ */ __name((event) => this.mark(event, "pendingSelectEnd"), "onSelectEnd");
+    this.onSqueezeStart = /* @__PURE__ */ __name((event) => this.mark(event, "pendingSqueezeStart"), "onSqueezeStart");
+    this.onSqueezeEnd = /* @__PURE__ */ __name((event) => this.mark(event, "pendingSqueezeEnd"), "onSqueezeEnd");
+  }
+  mark(event, flag) {
+    const record = this.ensureRecord(event.inputSource);
+    record[flag] = true;
+  }
+  ensureRecord(source) {
+    let record = this.records.get(source);
+    if (!record) {
+      record = {
+        source,
+        state: blankState(source),
+        pendingSelectStart: false,
+        pendingSelectEnd: false,
+        pendingSqueezeStart: false,
+        pendingSqueezeEnd: false,
+        removed: false
+      };
+      this.records.set(source, record);
+    }
+    return record;
+  }
+  /** Bind to a session. Called by {@link XRSessionSystem} on session start. */
+  attachSession(session) {
+    this.detachSession();
+    this.session = session;
+    session.addEventListener("selectstart", this.onSelectStart);
+    session.addEventListener("selectend", this.onSelectEnd);
+    session.addEventListener(
+      "squeezestart",
+      this.onSqueezeStart
+    );
+    session.addEventListener("squeezeend", this.onSqueezeEnd);
+  }
+  /** Unbind and drop all per-source state. */
+  detachSession() {
+    const session = this.session;
+    if (session) {
+      session.removeEventListener(
+        "selectstart",
+        this.onSelectStart
+      );
+      session.removeEventListener(
+        "selectend",
+        this.onSelectEnd
+      );
+      session.removeEventListener(
+        "squeezestart",
+        this.onSqueezeStart
+      );
+      session.removeEventListener(
+        "squeezeend",
+        this.onSqueezeEnd
+      );
+    }
+    this.session = null;
+    this.records.clear();
+  }
+  update(world) {
+    for (const [source, record] of this.records) {
+      if (record.removed) {
+        this.records.delete(source);
+        continue;
+      }
+      record.state.selectStart = false;
+      record.state.selectEnd = false;
+      record.state.squeezeStart = false;
+      record.state.squeezeEnd = false;
+    }
+    const session = this.session;
+    if (!session || !world.isXrPresenting()) return;
+    const renderer = world.getRenderer();
+    const referenceSpace = renderer.xr.getReferenceSpace();
+    const frame = renderer.xr.getFrame?.();
+    const live = /* @__PURE__ */ new Set();
+    for (const source of session.inputSources) {
+      live.add(source);
+      const record = this.ensureRecord(source);
+      const state = record.state;
+      state.connected = true;
+      state.handedness = handednessOf(source);
+      state.kind = kindOf(source);
+      if (frame && referenceSpace && source.targetRaySpace) {
+        const pose = frame.getPose(source.targetRaySpace, referenceSpace);
+        if (pose) {
+          const m = new THREE14__namespace.Matrix4().fromArray(pose.transform.matrix);
+          state.rayOrigin.setFromMatrixPosition(m);
+          state.rayDirection.set(0, 0, -1).applyQuaternion(
+            new THREE14__namespace.Quaternion().setFromRotationMatrix(m)
+          ).normalize();
+        }
+      }
+      if (frame && referenceSpace && source.gripSpace) {
+        const gripPose = frame.getPose(source.gripSpace, referenceSpace);
+        if (gripPose) {
+          const m = new THREE14__namespace.Matrix4().fromArray(gripPose.transform.matrix);
+          state.gripPosition ?? (state.gripPosition = new THREE14__namespace.Vector3());
+          state.gripQuaternion ?? (state.gripQuaternion = new THREE14__namespace.Quaternion());
+          state.gripPosition.setFromMatrixPosition(m);
+          state.gripQuaternion.setFromRotationMatrix(m);
+        }
+      } else {
+        state.gripPosition = null;
+        state.gripQuaternion = null;
+      }
+      const gamepad = source.gamepad;
+      if (gamepad) {
+        state.axes = Array.from(gamepad.axes);
+        state.hasAxes = gamepad.axes.some((axis) => Number.isFinite(axis));
+        state.buttons = gamepad.buttons.map((button) => button.pressed);
+      } else {
+        state.axes = [];
+        state.hasAxes = false;
+        state.buttons = [];
+      }
+      if (record.pendingSelectStart) {
+        state.select = true;
+        state.selectStart = true;
+        record.pendingSelectStart = false;
+      }
+      if (record.pendingSelectEnd) {
+        state.select = false;
+        state.selectEnd = true;
+        record.pendingSelectEnd = false;
+      }
+      if (record.pendingSqueezeStart) {
+        state.squeeze = true;
+        state.squeezeStart = true;
+        record.pendingSqueezeStart = false;
+      }
+      if (record.pendingSqueezeEnd) {
+        state.squeeze = false;
+        state.squeezeEnd = true;
+        record.pendingSqueezeEnd = false;
+      }
+    }
+    for (const [source, record] of this.records) {
+      if (live.has(source)) continue;
+      record.state.connected = false;
+      record.removed = true;
+    }
+  }
+  /** Every input source active this frame. */
+  getInputs() {
+    return Array.from(this.records.values(), (record) => record.state);
+  }
+  /** The first source for a hand, or null. Prefer this for hand-specific logic. */
+  getInput(handedness) {
+    for (const record of this.records.values()) {
+      if (record.state.handedness === handedness) return record.state;
+    }
+    return null;
+  }
+  /** True while ANY source is selecting — the portable "is the user acting" check. */
+  isSelecting() {
+    for (const record of this.records.values()) {
+      if (record.state.select) return true;
+    }
+    return false;
+  }
+  dispose() {
+    this.detachSession();
+  }
+};
+__name(_XRInputSystem, "XRInputSystem");
+var XRInputSystem = _XRInputSystem;
+var RAYLESS_HOLD_DISTANCE = 0.5;
+var _XRInteractionSystem = class _XRInteractionSystem {
+  constructor(inputSystem) {
+    this.raycaster = new THREE14__namespace.Raycaster();
+    /** Which entity each source is holding. Keyed by source state identity. */
+    this.grabs = /* @__PURE__ */ new Map();
+    this.hoveredEntityId = null;
+    this.inputSystem = inputSystem;
+  }
+  update(world) {
+    if (!world.isXrPresenting()) {
+      this.releaseAll(world);
+      return;
+    }
+    const inputs = this.inputSystem.getInputs();
+    const interactables = this.collectInteractables(world);
+    this.hoveredEntityId = null;
+    for (const input of inputs) {
+      if (!input.connected) {
+        this.release(world, input);
+        continue;
+      }
+      const held = this.grabs.get(input);
+      if (held) {
+        this.moveHeld(world, input, held);
+        if (input.selectEnd) this.release(world, input);
+        continue;
+      }
+      const hitEntityId = this.raycast(input, interactables);
+      if (hitEntityId === null) continue;
+      if (this.hoveredEntityId === null) {
+        this.hoveredEntityId = hitEntityId;
+      }
+      const interactable = world.getComponent(
+        hitEntityId,
+        XRInteractableComponent
+      );
+      if (input.selectStart && interactable?.grabbable) {
+        this.grab(world, input, hitEntityId);
+      }
+    }
+  }
+  collectInteractables(world) {
+    const out = [];
+    for (const entityId of world.query(XRInteractableComponent, Object3DRef)) {
+      const interactable = world.getComponent(entityId, XRInteractableComponent);
+      if (!interactable?.enabled || !interactable.pointable) continue;
+      if (!world.isEntityVisible(entityId)) continue;
+      const object = world.getComponent(entityId, Object3DRef)?.object;
+      if (object) out.push({ entityId, object });
+    }
+    return out;
+  }
+  /** Entity id of the nearest pointable hit along this source's ray, or null. */
+  raycast(input, interactables) {
+    if (interactables.length === 0) return null;
+    this.raycaster.set(input.rayOrigin, input.rayDirection);
+    let nearestId = null;
+    let nearestDistance = Number.POSITIVE_INFINITY;
+    for (const entry of interactables) {
+      const hit = this.raycaster.intersectObject(entry.object, true)[0];
+      if (!hit) continue;
+      if (hit.distance < nearestDistance) {
+        nearestDistance = hit.distance;
+        nearestId = entry.entityId;
+      }
+    }
+    return nearestId;
+  }
+  grab(world, input, entityId) {
+    const transform = world.getComponent(entityId, TransformComponent);
+    if (!transform) return;
+    const hand = this.handPosition(input);
+    const offset = new THREE14__namespace.Vector3(
+      transform.position.x - hand.x,
+      transform.position.y - hand.y,
+      transform.position.z - hand.z
+    );
+    const physics = world.getComponent(entityId, PhysicsComponent);
+    let restoreBodyType = null;
+    const interactable = world.getComponent(entityId, XRInteractableComponent);
+    if (physics && interactable?.grabMode === "kinematic") {
+      restoreBodyType = physics.values.rigidbody.type;
+      physics.values.rigidbody.type = "kinematicPosition";
+    }
+    this.grabs.set(input, { entityId, offset, restoreBodyType });
+    this.dispatch(world, entityId, (b) => b.onGrab(input));
+  }
+  moveHeld(world, input, held) {
+    const transform = world.getComponent(held.entityId, TransformComponent);
+    if (!transform) return;
+    const hand = this.handPosition(input);
+    transform.position.x = hand.x + held.offset.x;
+    transform.position.y = hand.y + held.offset.y;
+    transform.position.z = hand.z + held.offset.z;
+  }
+  release(world, input) {
+    const held = this.grabs.get(input);
+    if (!held) return;
+    this.grabs.delete(input);
+    if (held.restoreBodyType !== null) {
+      const physics = world.getComponent(held.entityId, PhysicsComponent);
+      if (physics) {
+        physics.values.rigidbody.type = held.restoreBodyType;
+      }
+    }
+    this.dispatch(world, held.entityId, (b) => b.onRelease(input));
+  }
+  releaseAll(world) {
+    for (const input of Array.from(this.grabs.keys())) {
+      this.release(world, input);
+    }
+  }
+  /**
+   * Where the "hand" is for this source. Controllers and tracked hands report a
+   * grip pose; gaze and transient-pointer sources have none, so we hold the
+   * object a fixed distance along the ray instead.
+   */
+  handPosition(input) {
+    if (input.gripPosition) return input.gripPosition;
+    return new THREE14__namespace.Vector3().copy(input.rayDirection).multiplyScalar(RAYLESS_HOLD_DISTANCE).add(input.rayOrigin);
+  }
+  dispatch(world, entityId, visit) {
+    const script = world.getComponent(entityId, ScriptComponent);
+    const instances = script?.scriptInstances;
+    if (!instances) return;
+    for (const instance of instances.values()) {
+      if (!(instance instanceof Behaviour)) continue;
+      try {
+        visit(instance);
+      } catch (error) {
+        console.error("[XRInteractionSystem] Behaviour hook failed:", error);
+      }
+    }
+  }
+  /** Entity currently under a pointer this frame, or null. */
+  getHoveredEntityId() {
+    return this.hoveredEntityId;
+  }
+  /** True when any source is holding something. */
+  isGrabbing() {
+    return this.grabs.size > 0;
+  }
+};
+__name(_XRInteractionSystem, "XRInteractionSystem");
+var XRInteractionSystem = _XRInteractionSystem;
+var UP = new THREE14__namespace.Vector3(0, 1, 0);
+var AXIS_DEADZONE = 0.5;
+var _XRLocomotionSystem = class _XRLocomotionSystem {
+  constructor(inputSystem) {
+    this.raycaster = new THREE14__namespace.Raycaster();
+    /** Per-source latch so one stick push yields exactly one snap turn. */
+    this.turnLatched = /* @__PURE__ */ new WeakSet();
+    /** Where the pointer currently lands, for the consumer to draw a marker. */
+    this.teleportPoint = null;
+    this.inputSystem = inputSystem;
+  }
+  update(world, deltaTime) {
+    this.teleportPoint = null;
+    if (!world.isXrPresenting()) return;
+    const rigEntityId = world.query(XRRigComponent, TransformComponent)[0];
+    if (typeof rigEntityId !== "number") return;
+    const rig = world.getComponent(rigEntityId, XRRigComponent);
+    const rigTransform = world.getComponent(rigEntityId, TransformComponent);
+    if (!rig || !rigTransform) return;
+    const inputs = this.inputSystem.getInputs();
+    if (inputs.length === 0) return;
+    if (rig.snapTurn) {
+      this.applySnapTurn(rig, rigTransform, inputs);
+    }
+    if (rig.locomotion === "teleport") {
+      this.applyTeleport(world, rigTransform, inputs);
+    } else if (rig.locomotion === "smooth") {
+      this.applySmoothMove(world, rig, rigTransform, inputs, deltaTime);
+    }
+  }
+  /**
+   * Snap turning, not smooth turning — rotating the view continuously is the
+   * single biggest cause of VR nausea, so the comfort-safe option is the one
+   * wired to the stick.
+   */
+  applySnapTurn(rig, transform, inputs) {
+    for (const input of inputs) {
+      if (!input.hasAxes || input.axes.length < 3) continue;
+      const x = input.axes[2] ?? 0;
+      const source = input;
+      if (Math.abs(x) < AXIS_DEADZONE) {
+        this.turnLatched.delete(source);
+        continue;
+      }
+      if (this.turnLatched.has(source)) continue;
+      this.turnLatched.add(source);
+      const step = THREE14__namespace.MathUtils.degToRad(rig.snapTurnDegrees);
+      transform.rotation.y -= Math.sign(x) * step;
+    }
+  }
+  applySmoothMove(world, rig, transform, inputs, deltaTime) {
+    for (const input of inputs) {
+      if (!input.hasAxes || input.axes.length < 2) continue;
+      const x = input.axes[0] ?? 0;
+      const y = input.axes[1] ?? 0;
+      if (Math.abs(x) < 0.15 && Math.abs(y) < 0.15) continue;
+      const camera = world.getCamera();
+      const forward = new THREE14__namespace.Vector3();
+      camera.getWorldDirection(forward);
+      forward.y = 0;
+      if (forward.lengthSq() < 1e-6) continue;
+      forward.normalize();
+      const right = new THREE14__namespace.Vector3().crossVectors(forward, UP).normalize();
+      const step = rig.moveSpeed * Math.max(0, deltaTime);
+      transform.position.x += (forward.x * -y + right.x * x) * step;
+      transform.position.z += (forward.z * -y + right.z * x) * step;
+    }
+  }
+  applyTeleport(world, transform, inputs) {
+    const targets = this.collectTeleportTargets(world);
+    if (targets.length === 0) return;
+    for (const input of inputs) {
+      this.raycaster.set(input.rayOrigin, input.rayDirection);
+      const hit = this.raycaster.intersectObjects(targets, true)[0];
+      if (!hit) continue;
+      this.teleportPoint = hit.point.clone();
+      if (input.selectEnd) {
+        transform.position.x = hit.point.x;
+        transform.position.y = hit.point.y;
+        transform.position.z = hit.point.z;
+      }
+    }
+  }
+  collectTeleportTargets(world) {
+    const objects = [];
+    for (const entityId of world.query(VRTeleportAreaComponent, Object3DRef)) {
+      const area = world.getComponent(entityId, VRTeleportAreaComponent);
+      if (!area?.enabled) continue;
+      if (!world.isEntityVisible(entityId)) continue;
+      const object = world.getComponent(entityId, Object3DRef)?.object;
+      if (object) objects.push(object);
+    }
+    return objects;
+  }
+  /**
+   * Where the teleport pointer currently lands this frame, or null.
+   * Consumers use this to render an aim marker.
+   */
+  getTeleportPoint() {
+    return this.teleportPoint;
+  }
+};
+__name(_XRLocomotionSystem, "XRLocomotionSystem");
+var XRLocomotionSystem = _XRLocomotionSystem;
+
+// core/xr/types.ts
+var NO_XR_CAPABILITIES = {
+  mode: "inline",
+  handTracking: false,
+  planeDetection: false,
+  meshDetection: false,
+  depthSensing: false,
+  anchors: false,
+  hitTest: false,
+  enabledFeatures: []
+};
+function readXrCapabilities(session, mode = "immersive-vr") {
+  if (!session) return NO_XR_CAPABILITIES;
+  const raw = session.enabledFeatures;
+  const features = Array.isArray(raw) ? Array.from(raw) : [];
+  const has = /* @__PURE__ */ __name((name) => features.includes(name), "has");
+  return {
+    mode,
+    handTracking: has("hand-tracking"),
+    planeDetection: has("plane-detection"),
+    meshDetection: has("mesh-detection"),
+    depthSensing: has("depth-sensing"),
+    anchors: has("anchors"),
+    hitTest: has("hit-test"),
+    enabledFeatures: features
+  };
+}
+__name(readXrCapabilities, "readXrCapabilities");
+
+// core/systems/XRSessionSystem.ts
+var _XRSessionSystem = class _XRSessionSystem {
+  constructor(inputSystem) {
+    this.presenting = false;
+    this.capabilities = NO_XR_CAPABILITIES;
+    this.inputSystem = inputSystem ?? null;
+  }
+  update(world) {
+    const presenting = world.isXrPresenting();
+    if (presenting !== this.presenting) {
+      this.presenting = presenting;
+      if (presenting) {
+        this.handleSessionStart(world);
+      } else {
+        this.handleSessionEnd(world);
+      }
+    }
+    if (presenting) {
+      this.dispatchInputEdges(world);
+    }
+  }
+  handleSessionStart(world) {
+    const session = world.getRenderer().xr.getSession();
+    const mode = session && session.environmentBlendMode !== "opaque" ? "immersive-ar" : "immersive-vr";
+    this.capabilities = readXrCapabilities(session ?? null, mode);
+    if (session && this.inputSystem) {
+      this.inputSystem.attachSession(session);
+    }
+    this.forEachBehaviour(world, (behaviour) => {
+      behaviour.onXRSessionStart(this.capabilities);
+    });
+  }
+  handleSessionEnd(world) {
+    this.capabilities = NO_XR_CAPABILITIES;
+    this.inputSystem?.detachSession();
+    this.forEachBehaviour(world, (behaviour) => {
+      behaviour.onXRSessionEnd();
+    });
+  }
+  /**
+   * Relay this frame's one-frame select edges. Polling the latched state (rather
+   * than dispatching from the DOM event) keeps hook delivery on the ECS tick, so
+   * a Behaviour's `onSelectStart` always observes the same world state its
+   * `onUpdate` would.
+   */
+  dispatchInputEdges(world) {
+    const inputs = this.inputSystem?.getInputs();
+    if (!inputs || inputs.length === 0) return;
+    for (const input of inputs) {
+      if (input.selectStart) {
+        this.forEachBehaviour(world, (b) => b.onSelectStart(input));
+      }
+      if (input.selectEnd) {
+        this.forEachBehaviour(world, (b) => b.onSelectEnd(input));
+      }
+    }
+  }
+  forEachBehaviour(world, visit) {
+    for (const entityId of world.query(ScriptComponent)) {
+      const script = world.getComponent(entityId, ScriptComponent);
+      const instances = script?.scriptInstances;
+      if (!instances) continue;
+      for (const instance of instances.values()) {
+        if (!(instance instanceof Behaviour)) continue;
+        try {
+          visit(instance);
+        } catch (error) {
+          console.error("[XRSessionSystem] Behaviour hook failed:", error);
+        }
+      }
+    }
+  }
+  /** What the active session granted. `NO_XR_CAPABILITIES` when not presenting. */
+  getCapabilities() {
+    return this.capabilities;
+  }
+  /** True while an immersive session is presenting. */
+  isPresenting() {
+    return this.presenting;
+  }
+  /** Convenience passthrough so consumers need only hold this system. */
+  getInputs() {
+    return this.inputSystem?.getInputs() ?? [];
+  }
+};
+__name(_XRSessionSystem, "XRSessionSystem");
+var XRSessionSystem = _XRSessionSystem;
 
 exports.AnimationSystem = AnimationSystem;
 exports.AudioSystem = AudioSystem;
@@ -7363,5 +8064,9 @@ exports.ScriptBehaviourSystem = ScriptBehaviourSystem;
 exports.ScriptObjectSystem = ScriptObjectSystem;
 exports.TransformSyncSystem = TransformSyncSystem;
 exports.VideoSystem = VideoSystem;
+exports.XRInputSystem = XRInputSystem;
+exports.XRInteractionSystem = XRInteractionSystem;
+exports.XRLocomotionSystem = XRLocomotionSystem;
+exports.XRSessionSystem = XRSessionSystem;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map