@relu-interactives/spatial-ecs 0.3.8 → 0.3.10

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 XrGrabMode, ai as XrHandPoseEntry, aj as XrHandPreset, ak as XrInteractorSide, al as XrInteractorType, am as XrLocomotionMode, an as XrTrackingOrigin, ao as createHandPoseEntry, ap as defaultMaterialValue, aq as handPoseDefinitionFor, ar as normalizePhysicsState, as as setPhysicsLiveRef } from '../XRHandPose-VuSbe4iz.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_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 XrGrabMode, 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-hAtj9wm-.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-31wk-A0g.cjs';
-export { P as PrefabInstance, a as PrefabNode } from '../index-BIQoaKAA.cjs';
+export { P as PrefabInstance, a as PrefabNode } from '../index-B9JqYr3Q.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import '../handPose-dFxqbFFY.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 XrGrabMode, ai as XrHandPoseEntry, aj as XrHandPreset, ak as XrInteractorSide, al as XrInteractorType, am as XrLocomotionMode, an as XrTrackingOrigin, ao as createHandPoseEntry, ap as defaultMaterialValue, aq as handPoseDefinitionFor, ar as normalizePhysicsState, as as setPhysicsLiveRef } from '../XRHandPose-CxPz8VBp.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_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 XrGrabMode, 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-CjacJ_16.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-31wk-A0g.js';
-export { P as PrefabInstance, a as PrefabNode } from '../index-BxdXgqiI.js';
+export { P as PrefabInstance, a as PrefabNode } from '../index-B7JDsx4a.js';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import '../handPose-dFxqbFFY.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, createHandPoseEntry, defaultMaterialValue, handPoseDefinitionFor, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-KVGGAL5V.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_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-ELSZ5U3F.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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

@@ -60,6 +60,54 @@ export default class Basketball extends Behaviour {
 }
 ```
 
+### Two hands, hand-off, and attach points
+
+An object decides how many hands may hold it, via **Hands**:
+
+| Setting | Behaviour |
+| --- | --- |
+| `handOff` (default) | Grabbing with the other hand **takes** it — passing something between your hands. |
+| `two` | Both hands hold it. The first anchors it, the second aims it. |
+| `single` | Stays with whichever hand grabbed first. |
+
+**Attach points** are authored hand-holds: a local position and rotation, optionally restricted to one `hand`, and given a `role`. The `primary` role is the anchoring hand (a rifle's trigger grip) and `secondary` the steering hand (the foregrip) — setting roles is what makes a two-hand grab assemble correctly no matter which hand grabs first. Among eligible points the nearest to the hand wins, so reaching for the foregrip picks the foregrip.
+
+Leave the list empty and hands grab wherever they touch. Two-hand grabbing and resizing still work in that case, anchored wherever the hands landed.
+
+For a two-handed rifle: **Hands** `two`, **Second Hand** `Aims the object`, and two attach points — one `primary` at the grip, one `secondary` at the foregrip.
+
+The primary hand is anchored and the secondary steers. Twist about the line between the hands comes from the primary hand's own roll, so banking your trigger hand banks the weapon.
+
+### Two-hand resizing
+
+Turn on **Resize** and moving both hands apart or together scales the object. Scale is uniform — two grab points give one distance measurement, so there is nothing to drive a second axis independently — and limited by **Min/Max Size**, which bound a single gesture relative to the size when the second hand grabbed. Repeated gestures compound.
+
+A small deadzone means ordinary hand drift while carrying something does not resize it.
+
+Releasing one hand does not drop the object. Let go with the support hand and the anchoring hand keeps it; let go with the anchoring hand and the other is promoted, so a two-hand hold released one hand at a time can still be thrown.
+
+### Reacting to grabs in script
+
+```ts
+import { Behaviour, type XrInputState } from "@relu-interactives/spatial-ecs";
+
+export default class Rifle extends Behaviour {
+  onGrab(input: XrInputState) {
+    console.log("held by", input.handedness);
+  }
+
+  onSecondaryGrab() {
+    // Both hands are on it now — steady the aim, show a bipod, whatever.
+  }
+
+  onSecondaryRelease() {
+    // Back to one hand.
+  }
+}
+```
+
+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.
+
 ## 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/factories/index.cjs

@@ -2348,6 +2348,14 @@ var _XRInteractableComponent = class _XRInteractableComponent extends Component
       y: 0,
       z: 0
     };
+    this.grabHands = options?.grabHands ?? "handOff";
+    this.twoHandRotation = options?.twoHandRotation ?? "align";
+    this.allowTwoHandScale = options?.allowTwoHandScale ?? false;
+    this.minScale = options?.minScale ?? 0.25;
+    this.maxScale = options?.maxScale ?? 4;
+    this.attachPoints = (options?.attachPoints ?? []).map(
+      (point) => createAttachPoint(point)
+    );
     this.throwOnRelease = options?.throwOnRelease ?? true;
     this.throwStrength = options?.throwStrength ?? 1;
     this.highlightOnHover = options?.highlightOnHover ?? true;
@@ -2355,6 +2363,17 @@ var _XRInteractableComponent = class _XRInteractableComponent extends Component
 };
 __name(_XRInteractableComponent, "XRInteractableComponent");
 var XRInteractableComponent = _XRInteractableComponent;
+function createAttachPoint(partial) {
+  return {
+    id: partial.id,
+    name: partial.name ?? partial.id,
+    position: { x: 0, y: 0, z: 0, ...partial.position },
+    rotation: { x: 0, y: 0, z: 0, ...partial.rotation },
+    hand: partial.hand ?? "any",
+    role: partial.role ?? "any"
+  };
+}
+__name(createAttachPoint, "createAttachPoint");
 
 // core/factories/components/XRInteractableFactory.ts
 function createXRInteractableComponent(world, entityId, ...args) {