@relu-interactives/spatial-ecs 0.3.14 → 0.3.17

package/dist/docs/guide/vr-and-hand-poses.md

@@ -114,6 +114,17 @@ export default class Rifle extends Behaviour {
 
 Every grab setting is a plain field on the component, so a script can change it mid-session — switch on resizing, retune throw strength, or move an attach point in response to what the player is doing.
 
+## Vision Pro
+
+Vision Pro drives WebXR entirely through **gaze and pinch**. There are no controllers, and the input source for a pinch is created when the pinch starts and destroyed when it ends. That has a few consequences worth designing around:
+
+- **Look at a thing and pinch** to select or grab it. The pick ray starts between the user's eyes and is then carried by the hand, so aiming is "pinch, then move your hand", not "point, then press".
+- **There is no hover before a pinch** — the input source does not exist until then. Pointer rays and hover feedback therefore only appear *during* a pinch, not while the user looks around.
+- **Grip/squeeze is never reported.** Set an interactable's **Gesture** to `Pinch` or `Any`; `Full grip` can never trigger on Vision Pro.
+- Grabbing does not teleport the user, the same as on hand tracking elsewhere.
+- Hand tracking (and therefore hand poses) is available on visionOS 2 and later, but asks the user for a second permission. The OS draws the user's real hands.
+- `immersive-ar` is not supported by Safari on visionOS, so VR projects are the only kind that run there.
+
 ## Hand poses
 
 Add an **XR Hand Pose** component and list the poses to watch for. Each is either a built-in preset or a custom set of finger curls.

package/dist/{index-CbrjAm_8.d.cts → index-ekS4iypo.d.cts}

@@ -501,15 +501,20 @@ declare class XRInteractionSystem implements EcsSystem {
     /** True when any source is holding something. */
     isGrabbing(): boolean;
     /**
-     * Whether this hand's primary action is committed to interaction.
+     * Whether this input's primary action is committed to interaction.
      *
-     * True while the hand holds something, and also while it merely HOVERS a
+     * True while the source holds something, and also while it merely HOVERS a
      * grabbable — because the pinch that is about to grab must not be read as a
      * teleport by the locomotion system. Without the hover half, the first pinch
      * of a grab teleports the player, and so does the pinch that takes an object
      * from the other hand.
+     *
+     * Keyed on the INPUT SOURCE rather than handedness. Vision Pro reports
+     * `handedness: "none"` for every gaze-pinch (it is hard-coded in WebKit), so a
+     * handedness-keyed check silently never matched there and each pinch both
+     * grabbed and teleported.
      */
-    isHandBusy(world: World, handedness: XrInputState["handedness"]): boolean;
+    isSourceBusy(world: World, input: XrInputState): boolean;
     /** True when THIS hand is holding something. */
     isGrabbingWith(handedness: XrInputState["handedness"]): boolean;
     /**
@@ -545,6 +550,8 @@ declare class XRLocomotionSystem implements EcsSystem {
     private aimValid;
     /** Sources currently aiming via thumbstick (hysteresis, so it doesn't chatter). */
     private readonly stickAiming;
+    /** One-time warning when a committed teleport found nowhere to land. */
+    private warnedNoLanding;
     /** Gates teleport commits on a prior aim. See {@link TeleportAimGate}. */
     private readonly teleportAim;
     /** True once we've tried to self-heal camera parenting for this session. */

package/dist/{index-CvIXdHzx.d.ts → index-uKFxVCmr.d.ts}

@@ -501,15 +501,20 @@ declare class XRInteractionSystem implements EcsSystem {
     /** True when any source is holding something. */
     isGrabbing(): boolean;
     /**
-     * Whether this hand's primary action is committed to interaction.
+     * Whether this input's primary action is committed to interaction.
      *
-     * True while the hand holds something, and also while it merely HOVERS a
+     * True while the source holds something, and also while it merely HOVERS a
      * grabbable — because the pinch that is about to grab must not be read as a
      * teleport by the locomotion system. Without the hover half, the first pinch
      * of a grab teleports the player, and so does the pinch that takes an object
      * from the other hand.
+     *
+     * Keyed on the INPUT SOURCE rather than handedness. Vision Pro reports
+     * `handedness: "none"` for every gaze-pinch (it is hard-coded in WebKit), so a
+     * handedness-keyed check silently never matched there and each pinch both
+     * grabbed and teleported.
      */
-    isHandBusy(world: World, handedness: XrInputState["handedness"]): boolean;
+    isSourceBusy(world: World, input: XrInputState): boolean;
     /** True when THIS hand is holding something. */
     isGrabbingWith(handedness: XrInputState["handedness"]): boolean;
     /**
@@ -545,6 +550,8 @@ declare class XRLocomotionSystem implements EcsSystem {
     private aimValid;
     /** Sources currently aiming via thumbstick (hysteresis, so it doesn't chatter). */
     private readonly stickAiming;
+    /** One-time warning when a committed teleport found nowhere to land. */
+    private warnedNoLanding;
     /** Gates teleport commits on a prior aim. See {@link TeleportAimGate}. */
     private readonly teleportAim;
     /** True once we've tried to self-heal camera parenting for this session. */

package/dist/index.cjs

@@ -11728,17 +11728,22 @@ var _XRInteractionSystem = class _XRInteractionSystem {
     return this.grabs.size > 0;
   }
   /**
-   * Whether this hand's primary action is committed to interaction.
+   * Whether this input's primary action is committed to interaction.
    *
-   * True while the hand holds something, and also while it merely HOVERS a
+   * True while the source holds something, and also while it merely HOVERS a
    * grabbable — because the pinch that is about to grab must not be read as a
    * teleport by the locomotion system. Without the hover half, the first pinch
    * of a grab teleports the player, and so does the pinch that takes an object
    * from the other hand.
+   *
+   * Keyed on the INPUT SOURCE rather than handedness. Vision Pro reports
+   * `handedness: "none"` for every gaze-pinch (it is hard-coded in WebKit), so a
+   * handedness-keyed check silently never matched there and each pinch both
+   * grabbed and teleported.
    */
-  isHandBusy(world, handedness) {
-    if (this.isGrabbingWith(handedness)) return true;
-    const hover = this.getHoverFor(handedness);
+  isSourceBusy(world, input) {
+    if (this.grabs.has(input)) return true;
+    const hover = this.hovers.get(input);
     if (!hover) return false;
     const interactable = world.getComponent(
       hover.entityId,
@@ -11832,7 +11837,7 @@ var _TeleportAimGate = class _TeleportAimGate {
     if (aiming) this.aiming.add(source);
     if (!releasing) return false;
     this.aiming.delete(source);
-    return hadAim;
+    return hadAim || aiming;
   }
   /** True if this source currently has an aim engaged. */
   isAiming(source) {
@@ -11870,6 +11875,8 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     this.aimValid = false;
     /** Sources currently aiming via thumbstick (hysteresis, so it doesn't chatter). */
     this.stickAiming = /* @__PURE__ */ new WeakSet();
+    /** One-time warning when a committed teleport found nowhere to land. */
+    this.warnedNoLanding = false;
     /** Gates teleport commits on a prior aim. See {@link TeleportAimGate}. */
     this.teleportAim = new TeleportAimGate();
     /** True once we've tried to self-heal camera parenting for this session. */
@@ -12006,7 +12013,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     const targets = this.collectTeleportTargets(world);
     for (const input of inputs) {
       const source = input;
-      if (input.handedness !== "none" && this.interactionSystem?.isHandBusy(world, input.handedness)) {
+      if (this.interactionSystem?.isSourceBusy(world, input)) {
         if (this.teleportAim.cancel(source)) {
           this.aimCurve = [];
           this.landingPoint = null;
@@ -12015,8 +12022,9 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
         continue;
       }
       const stick = this.readStickAim(input, source);
-      const aiming = input.select || stick.aiming;
-      const releasing = input.selectEnd || stick.released;
+      const aiming = input.select || input.selectStart || stick.aiming;
+      const vanished = !input.connected && this.teleportAim.isAiming(source);
+      const releasing = input.selectEnd || stick.released || vanished;
       const commit = this.teleportAim.update(source, aiming, releasing);
       if (!aiming && !commit) continue;
       const points = sampleTeleportArc(
@@ -12036,6 +12044,12 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
         this.landingPoint = null;
         this.aimValid = false;
       } else if (commit) {
+        if (!this.warnedNoLanding) {
+          this.warnedNoLanding = true;
+          console.warn(
+            "[XRLocomotionSystem] Teleport released but the arc did not land on a Teleport Area. Add a teleportArea entity where the player should be able to go."
+          );
+        }
         this.aimCurve = [];
         this.aimValid = false;
       }