@relu-interactives/spatial-ecs 0.3.19 → 0.3.20

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

@@ -125,6 +125,66 @@ Vision Pro drives WebXR entirely through **gaze and pinch**. There are no contro
 - 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.
 
+### Scripting VR interactions
+
+A few patterns that cover most scenes.
+
+**Score when a thrown object passes through something.** Give the ball a dynamic rigidbody and an XR Interactable; the throw itself is handled for you.
+
+```ts
+import { Behaviour, type XrInputState } from "@relu-interactives/spatial-ecs";
+
+export default class Ball extends Behaviour {
+  onRelease(input: XrInputState) {
+    // Fires the moment it leaves the hand — the engine has already applied the
+    // velocity, so this is where scoring or audio goes.
+    console.log("released by", input.handedness);
+  }
+}
+```
+
+**A panel you point at but cannot pick up.** Set `pointable: true` and `grabbable: false`, then act on the pointer.
+
+```ts
+export default class Button extends Behaviour {
+  onSelectStart() {
+    this.world.emit?.("door:open");
+  }
+}
+```
+
+**React to a two-handed hold.** Useful for steadying a weapon, showing a bipod, or gating an action on both hands being committed.
+
+```ts
+export default class Rifle extends Behaviour {
+  private braced = false;
+
+  onSecondaryGrab() {
+    this.braced = true;
+  }
+
+  onSecondaryRelease() {
+    this.braced = false;
+  }
+
+  onUpdate() {
+    if (this.braced) { /* tighter aim, less sway… */ }
+  }
+}
+```
+
+**Adapt to the device.** Branch on what the session granted, never on a device name.
+
+```ts
+onXRSessionStart(capabilities: XrCapabilities) {
+  if (!capabilities.handTracking) {
+    // Controllers only — hide anything that depends on finger poses.
+  }
+}
+```
+
+Two rules worth internalising: **move the rig, never the camera** (the headset owns the camera while presenting and overwrites it every frame), and give any destructive gesture a longer **Hold Time** so it cannot fire in passing.
+
 ## 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.
@@ -154,6 +214,46 @@ export default class Portal extends Behaviour {
 
 `XrHandPoseEventDetail` is `{ poseId, poseName, handedness, confidence }`. Match on `poseId` — it is the id set in the inspector, not the preset name.
 
+**Changing another object's colour from a pose.** `MaterialComponent.updateValue` takes an index and a PATCH OBJECT — `updateValue(0, { color })`, not `updateValue(0, "color", value)`.
+
+```ts
+import {
+  Behaviour,
+  MaterialComponent,
+  type EntityInput,
+  type WorldEntityView,
+  type XrHandPoseEventDetail,
+} from "@relu-interactives/spatial-ecs";
+
+export default class PoseColor extends Behaviour {
+  data = { target: { type: "entity", value: null } as unknown as EntityInput };
+  private original = "#ffffff";
+
+  init() {
+    const material = this.material();
+    const current = material?.values?.[0]?.color;
+    if (typeof current === "string") this.original = current;
+  }
+
+  onHandPoseStart(event: XrHandPoseEventDetail) {
+    if (event.poseId === "approve") this.material()?.updateValue(0, { color: "#0066ff" });
+  }
+
+  onHandPoseEnd() {
+    this.material()?.updateValue(0, { color: this.original });
+  }
+
+  private material() {
+    const target = this.data.target.value as WorldEntityView | null;
+    return target
+      ? this.world.getComponent(target.entityId, MaterialComponent)
+      : null;
+  }
+}
+```
+
+**Hand poses require HAND TRACKING.** They are read from the 25 tracked finger joints, so nothing fires while the user is holding controllers — put them down and enable hand tracking on the headset. If a scene has poses configured and no tracked hand is seen for a few seconds, the runtime says so in the console.
+
 ### Presets
 
 `fist`, `open-palm`, `point`, `thumbs-up`, `thumbs-down`, `peace`, `pinch`, `ok`, `gun`, `rock`, `shaka`, `palm-up`.

package/dist/{index-C_589fc4.d.ts → index-6l4hn2Sh.d.ts}

@@ -401,6 +401,18 @@ declare class XRInputSystem implements EcsSystem {
     getInputs(): XrInputState[];
     /** The first source for a hand, or null. Prefer this for hand-specific logic. */
     getInput(handedness: XrHandedness): XrInputState | null;
+    /**
+     * The ARTICULATED source for a hand — the one carrying joint poses.
+     *
+     * Distinct from {@link getInput} because a hand can be backed by several
+     * sources at once: a Quest reports a controller AND a tracked hand for the
+     * same handedness, and Vision Pro adds a transient pinch alongside its two
+     * persistent hands. `getInput` returns whichever was seen first, so anything
+     * needing JOINTS has to ask for them specifically — taking the first match
+     * silently handed pose detection a controller with no joints, and no pose
+     * ever fired.
+     */
+    getHandInput(handedness: XrHandedness): XrInputState | null;
     /** True while ANY source is selecting — the portable "is the user acting" check. */
     isSelecting(): boolean;
     dispose(): void;
@@ -800,6 +812,8 @@ declare class XRHandPoseSystem implements EcsSystem {
     /** Reused so head-relative orientation checks allocate nothing per frame. */
     private readonly headPosition;
     private elapsed;
+    private warnedNoHands;
+    private noHandSeconds;
     constructor(inputSystem: XRInputSystem);
     update(world: World, deltaTime: number): void;
     /** Derive each hand's shape once for the whole frame. */

package/dist/{index-3pNbH0iP.d.cts → index-C2I5PxCI.d.cts}

@@ -401,6 +401,18 @@ declare class XRInputSystem implements EcsSystem {
     getInputs(): XrInputState[];
     /** The first source for a hand, or null. Prefer this for hand-specific logic. */
     getInput(handedness: XrHandedness): XrInputState | null;
+    /**
+     * The ARTICULATED source for a hand — the one carrying joint poses.
+     *
+     * Distinct from {@link getInput} because a hand can be backed by several
+     * sources at once: a Quest reports a controller AND a tracked hand for the
+     * same handedness, and Vision Pro adds a transient pinch alongside its two
+     * persistent hands. `getInput` returns whichever was seen first, so anything
+     * needing JOINTS has to ask for them specifically — taking the first match
+     * silently handed pose detection a controller with no joints, and no pose
+     * ever fired.
+     */
+    getHandInput(handedness: XrHandedness): XrInputState | null;
     /** True while ANY source is selecting — the portable "is the user acting" check. */
     isSelecting(): boolean;
     dispose(): void;
@@ -800,6 +812,8 @@ declare class XRHandPoseSystem implements EcsSystem {
     /** Reused so head-relative orientation checks allocate nothing per frame. */
     private readonly headPosition;
     private elapsed;
+    private warnedNoHands;
+    private noHandSeconds;
     constructor(inputSystem: XRInputSystem);
     update(world: World, deltaTime: number): void;
     /** Derive each hand's shape once for the whole frame. */

package/dist/index.cjs

@@ -11019,6 +11019,25 @@ var _XRInputSystem = class _XRInputSystem {
     }
     return null;
   }
+  /**
+   * The ARTICULATED source for a hand — the one carrying joint poses.
+   *
+   * Distinct from {@link getInput} because a hand can be backed by several
+   * sources at once: a Quest reports a controller AND a tracked hand for the
+   * same handedness, and Vision Pro adds a transient pinch alongside its two
+   * persistent hands. `getInput` returns whichever was seen first, so anything
+   * needing JOINTS has to ask for them specifically — taking the first match
+   * silently handed pose detection a controller with no joints, and no pose
+   * ever fired.
+   */
+  getHandInput(handedness) {
+    for (const record of this.records.values()) {
+      const state = record.state;
+      if (state.handedness !== handedness) continue;
+      if (state.joints) return state;
+    }
+    return null;
+  }
   /** True while ANY source is selecting — the portable "is the user acting" check. */
   isSelecting() {
     for (const record of this.records.values()) {
@@ -13283,6 +13302,8 @@ var _XRHandPoseSystem = class _XRHandPoseSystem {
     /** Reused so head-relative orientation checks allocate nothing per frame. */
     this.headPosition = new THREE51__namespace.Vector3();
     this.elapsed = 0;
+    this.warnedNoHands = false;
+    this.noHandSeconds = 0;
     this.inputSystem = inputSystem;
   }
   update(world, deltaTime) {
@@ -13294,6 +13315,20 @@ var _XRHandPoseSystem = class _XRHandPoseSystem {
     this.refreshShapes();
     const entries = this.collectEntries(world);
     if (entries.length === 0) return;
+    if (!this.warnedNoHands) {
+      const tracked = this.shapes.get("left") !== null || this.shapes.get("right") !== null;
+      if (tracked) {
+        this.warnedNoHands = true;
+      } else {
+        this.noHandSeconds += deltaTime;
+        if (this.noHandSeconds > 5) {
+          this.warnedNoHands = true;
+          console.warn(
+            "[XRHandPoseSystem] Hand poses are configured but no tracked hands have been seen. Hand poses need HAND TRACKING \u2014 put the controllers down and enable hand tracking on the headset."
+          );
+        }
+      }
+    }
     world.getCamera().getWorldPosition(this.headPosition);
     const context = { headPosition: this.headPosition };
     for (const { entityId, entry } of entries) {
@@ -13338,7 +13373,7 @@ var _XRHandPoseSystem = class _XRHandPoseSystem {
   /** Derive each hand's shape once for the whole frame. */
   refreshShapes() {
     for (const handedness of ["left", "right"]) {
-      const input = this.inputSystem.getInput(handedness);
+      const input = this.inputSystem.getHandInput(handedness);
       const joints = input?.joints ?? null;
       this.shapes.set(
         handedness,