@relu-interactives/spatial-ecs 0.3.18 → 0.3.19

package/dist/components/index.d.cts

@@ -1,6 +1,6 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, o as EntityType, I as ImageComponent, p as ImageTarget, q as ImageTargetAnchor, r as ImageTargetAnchorOptions, s as ImageTargetReference, t as InstanceSlotComponent, u as InstanceTransform, v as InstancedMeshComponent, w as InstancedMeshKind, L as LightComponent, x as LightValueState, M as MaterialComponent, y as MaterialTypeValue, z as MaterialValueState, B as MeshComponent, F as MeshGeometryComponent, G as MeshGeometryParameters, H as MeshGeometryParametersByKind, J as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, K as PhysicsState, Q as PlaneMeshParameters, R as RadiusHeightMeshParameters, S as RadiusMeshParameters, T as RigidbodyState, U as RigidbodyType, V as ScriptComponent, W as ScriptEntry, X as ScriptObjectComponent, Y as ScriptObjectComponentInput, Z as ScriptObjectRuntimeState, _ as Selectable, $ as SelectionTransformState, a0 as SpriteComponent, a1 as TextureFilteringValue, a2 as TransformModeValue, a3 as TransformSpaceValue, a4 as VRTeleportAreaComponent, a5 as VRTeleportAreaOptions, a6 as VideoComponent, a7 as VrTeleportShape, a8 as XRHandPoseComponent, a9 as XRHandPoseOptions, aa as XRInteractableComponent, ab as XRInteractableOptions, ac as XRInteractorComponent, ad as XRInteractorOptions, ae as XRInteractorSideComponent, af as XRRigComponent, ag as XRRigOptions, ah as XrAttachPoint, ai as XrDistanceGrabBehavior, aj as XrGrabGesture, ak as XrGrabHands, al as XrGrabReach, am as XrHandPoseEntry, an as XrHandPreset, ao as XrInteractorSide, ap as XrInteractorType, aq as XrLocomotionMode, ar as XrTrackingOrigin, as as XrTwoHandRotation, at as createAttachPoint, au as createHandPoseEntry, av as defaultMaterialValue, aw as handPoseDefinitionFor, ax as normalizePhysicsState, ay as setPhysicsLiveRef } from '../XRHandPose-B8xxFb9A.cjs';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as VRTeleportAreaComponent, a6 as VRTeleportAreaOptions, a7 as VideoComponent, a8 as VrTeleportShape, a9 as XRHandPoseComponent, aa as XRHandPoseOptions, ab as XRInteractableComponent, ac as XRInteractableOptions, ad as XRInteractorComponent, ae as XRInteractorOptions, af as XRInteractorSideComponent, ag as XRRigComponent, ah as XRRigOptions, ai as XrAttachPoint, aj as XrDistanceGrabBehavior, ak as XrGrabGesture, al as XrGrabHands, am as XrGrabReach, an as XrHandPoseEntry, ao as XrHandPreset, ap as XrInteractorSide, aq as XrInteractorType, ar as XrLocomotionMode, as as XrTrackingOrigin, at as XrTwoHandRotation, au as createAttachPoint, av as createHandPoseEntry, aw as defaultMaterialValue, ax as handPoseDefinitionFor, ay as normalizePhysicsState, az as setPhysicsLiveRef } from '../XRHandPose-CLl4MiHx.cjs';
 export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BhnLw0fZ.cjs';
-export { P as PrefabInstance, a as PrefabNode } from '../index-CA9fqh4Z.cjs';
+export { P as PrefabInstance, a as PrefabNode } from '../index-g777AmFv.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';
-import '../handPose-dFxqbFFY.cjs';
+import '../handPose-DlcTtqgx.cjs';

package/dist/components/index.d.ts

@@ -1,6 +1,6 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, o as EntityType, I as ImageComponent, p as ImageTarget, q as ImageTargetAnchor, r as ImageTargetAnchorOptions, s as ImageTargetReference, t as InstanceSlotComponent, u as InstanceTransform, v as InstancedMeshComponent, w as InstancedMeshKind, L as LightComponent, x as LightValueState, M as MaterialComponent, y as MaterialTypeValue, z as MaterialValueState, B as MeshComponent, F as MeshGeometryComponent, G as MeshGeometryParameters, H as MeshGeometryParametersByKind, J as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, K as PhysicsState, Q as PlaneMeshParameters, R as RadiusHeightMeshParameters, S as RadiusMeshParameters, T as RigidbodyState, U as RigidbodyType, V as ScriptComponent, W as ScriptEntry, X as ScriptObjectComponent, Y as ScriptObjectComponentInput, Z as ScriptObjectRuntimeState, _ as Selectable, $ as SelectionTransformState, a0 as SpriteComponent, a1 as TextureFilteringValue, a2 as TransformModeValue, a3 as TransformSpaceValue, a4 as VRTeleportAreaComponent, a5 as VRTeleportAreaOptions, a6 as VideoComponent, a7 as VrTeleportShape, a8 as XRHandPoseComponent, a9 as XRHandPoseOptions, aa as XRInteractableComponent, ab as XRInteractableOptions, ac as XRInteractorComponent, ad as XRInteractorOptions, ae as XRInteractorSideComponent, af as XRRigComponent, ag as XRRigOptions, ah as XrAttachPoint, ai as XrDistanceGrabBehavior, aj as XrGrabGesture, ak as XrGrabHands, al as XrGrabReach, am as XrHandPoseEntry, an as XrHandPreset, ao as XrInteractorSide, ap as XrInteractorType, aq as XrLocomotionMode, ar as XrTrackingOrigin, as as XrTwoHandRotation, at as createAttachPoint, au as createHandPoseEntry, av as defaultMaterialValue, aw as handPoseDefinitionFor, ax as normalizePhysicsState, ay as setPhysicsLiveRef } from '../XRHandPose-ubMe5Igc.js';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as VRTeleportAreaComponent, a6 as VRTeleportAreaOptions, a7 as VideoComponent, a8 as VrTeleportShape, a9 as XRHandPoseComponent, aa as XRHandPoseOptions, ab as XRInteractableComponent, ac as XRInteractableOptions, ad as XRInteractorComponent, ae as XRInteractorOptions, af as XRInteractorSideComponent, ag as XRRigComponent, ah as XRRigOptions, ai as XrAttachPoint, aj as XrDistanceGrabBehavior, ak as XrGrabGesture, al as XrGrabHands, am as XrGrabReach, an as XrHandPoseEntry, ao as XrHandPreset, ap as XrInteractorSide, aq as XrInteractorType, ar as XrLocomotionMode, as as XrTrackingOrigin, at as XrTwoHandRotation, au as createAttachPoint, av as createHandPoseEntry, aw as defaultMaterialValue, ax as handPoseDefinitionFor, ay as normalizePhysicsState, az as setPhysicsLiveRef } from '../XRHandPose-CrzI57JA.js';
 export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BhnLw0fZ.js';
-export { P as PrefabInstance, a as PrefabNode } from '../index-DhWfxUgL.js';
+export { P as PrefabInstance, a as PrefabNode } from '../index-JRcoel9F.js';
 import 'three';
 import '@dimforge/rapier3d-compat';
-import '../handPose-dFxqbFFY.js';
+import '../handPose-DlcTtqgx.js';

package/dist/components/index.js

@@ -1,4 +1,4 @@
-export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSE_CURLS, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, ScriptObjectComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VRTeleportAreaComponent, VideoComponent, XRHandPoseComponent, XRInteractableComponent, XRInteractorComponent, XRInteractorSideComponent, XRRigComponent, createAttachPoint, createHandPoseEntry, defaultMaterialValue, handPoseDefinitionFor, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-J3EUNW57.js';
+export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSE_CURLS, DEFAULT_POSE_DIRECTIONS, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, ScriptObjectComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VRTeleportAreaComponent, VideoComponent, XRHandPoseComponent, XRInteractableComponent, XRInteractorComponent, XRInteractorSideComponent, XRRigComponent, createAttachPoint, createHandPoseEntry, defaultMaterialValue, handPoseDefinitionFor, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-H6DQ7JRE.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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

@@ -164,6 +164,14 @@ A custom pose is five curl values, `0` (finger straight) to `1` (fully closed),
 
 Optionally add a **direction** requirement: which way the palm, fingers, or thumb must point (`up`, `down`, `forward`, `back`, `left`, `right`, `toward-head`, `away-from-head`) within an angle tolerance. This is what separates thumbs-up from thumbs-down, which are the same hand shape.
 
+### Per-finger direction
+
+Curl says how *bent* a finger is; direction says where it *points*. "Index extended, pointing up" and "index extended, pointing at the user" are different gestures with identical curls, so direction is what tells them apart.
+
+In the editor, click a finger on the hand and pick the directions it may point: `Up`, `Down`, `Forward`, `Back`, `Left`, `Right`, `At user`, `Away`. Picking **several means any one of them counts** — that is how "thumb up or diagonally up" stays a single pose. Pick none to leave the finger free.
+
+**Angle Tolerance** is how far a finger may point from an accepted direction. 45° by default: direction is a coarse signal, and a tight cone makes a pose that looks right to the user fail to register.
+
 ### Tuning
 
 - **Tolerance** — raise it if a pose is hard to trigger, lower it if it fires by accident.
@@ -171,6 +179,65 @@ Optionally add a **direction** requirement: which way the palm, fingers, or thum
 
 A pose does not re-fire while held, and survives a brief hand-tracking dropout rather than flickering.
 
+### Driving game logic
+
+The hooks fire on the entity that declares the pose, so put the component on the object that should react. A few patterns worth knowing:
+
+**Fire once per gesture.** `onHandPoseStart` fires when the pose begins, not every frame, so it is safe to spawn or play something directly.
+
+```ts
+import { Behaviour, type XrHandPoseEventDetail } from "@relu-interactives/spatial-ecs";
+
+export default class Spellcaster extends Behaviour {
+  onHandPoseStart(event: XrHandPoseEventDetail) {
+    if (event.poseId !== "cast") return;
+    this.spawnPrefab("assets/fireball.prefab", {
+      position: this.transform.position,
+    });
+  }
+}
+```
+
+**Hold a state while the pose lasts.** Use both hooks when the pose should gate something continuous.
+
+```ts
+export default class Shield extends Behaviour {
+  private raised = false;
+
+  onHandPoseStart(event: XrHandPoseEventDetail) {
+    if (event.poseId === "open-palm") this.raised = true;
+  }
+
+  onHandPoseEnd(event: XrHandPoseEventDetail) {
+    if (event.poseId === "open-palm") this.raised = false;
+  }
+
+  onUpdate() {
+    if (this.raised) { /* absorb damage, drift the shield toward the hand… */ }
+  }
+}
+```
+
+**React per hand.** `event.handedness` is `"left"` or `"right"`, so one pose can drive two behaviours.
+
+```ts
+onHandPoseStart(event: XrHandPoseEventDetail) {
+  if (event.poseId !== "point") return;
+  if (event.handedness === "right") this.aim();
+  else this.selectMenu();
+}
+```
+
+**Require a confident match.** `event.confidence` is 0–1 at the moment the pose fired. Gate on it when a gesture is destructive.
+
+```ts
+onHandPoseStart(event: XrHandPoseEventDetail) {
+  if (event.poseId === "delete-all" && event.confidence > 0.95) this.clearScene();
+}
+```
+
+Two things to design around: **match on `poseId`, not the pose name** — the id is the contract, the name is a label — and give a destructive gesture a longer **Hold Time** so it cannot fire in passing.
+
 ## Locomotion
 
 Movement is a property of the **XR Rig**, not of scripts: tracking origin (floor or eye level), locomotion mode, move speed, snap turn, and — when locomotion is teleport — the arc's **Color**, **Blocked Color** and **Thickness**. The arc starts a short way out from the head so it never draws through the user's own view, which matters on Vision Pro where the aim ray originates between the eyes. Teleport destinations are **Teleport Area** entities. Scripts should move the rig, never the camera — while a session is presenting, the headset owns the camera and writes its pose every frame.

package/dist/factories/index.cjs

@@ -2304,6 +2304,14 @@ function createHandPoseEntry(partial) {
     preset: partial.preset ?? null,
     curls: { ...DEFAULT_POSE_CURLS, ...partial.curls },
     tolerance: partial.tolerance ?? 0.25,
+    directions: {
+      thumb: [...partial.directions?.thumb ?? []],
+      index: [...partial.directions?.index ?? []],
+      middle: [...partial.directions?.middle ?? []],
+      ring: [...partial.directions?.ring ?? []],
+      pinky: [...partial.directions?.pinky ?? []]
+    },
+    directionTolerance: partial.directionTolerance ?? 45,
     hand: partial.hand ?? null,
     orientation: partial.orientation ?? null,
     minHoldSeconds: partial.minHoldSeconds ?? 0.15,