@relu-interactives/spatial-ecs 0.3.9 → 0.3.11

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 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-C-KJeYcJ.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-DPRnnSI-.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 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-B6I4y1lj.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-CEZp7qLL.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-TXEGYR76.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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

@@ -39,11 +39,15 @@ Add an **XR Interactable** component in the inspector. The useful fields:
 - **Reach** — `physical` (hand must touch it), `distance` (grab along the pointer ray), or `both`.
 - **At Distance** — `snap` brings it to the hand, `remote` manipulates it where it stands.
 - **Gesture** — `pinch`, `full` grip, or `any`.
-- **Grab Mode** — `kinematic` follows the hand exactly; `physics` keeps the body simulated.
 - **Hold Offset** — where the object sits in the hand once held.
-- **Throw on Release** — carries hand momentum into the body.
+- **Throw on Release** — carries hand momentum into the body (on by default).
+- **Hover** — `Outline`, `Grow`, `Outline + grow`, or `None`, plus the colour and grow amount.
 
-For a throwable ball, the object needs a **dynamic rigidbody**, Grab Mode `physics`, and Throw on Release enabled. Release velocity is taken from the peak of a short window of hand motion, so throws match the motion the user made rather than the frame they opened their hand.
+A held object follows the hand exactly and does not collide with the world while held.
+
+**To make something throwable, give it a Physics component with a DYNAMIC rigidbody.** That is the only requirement — throwing is on by default. Release velocity is taken from the peak of a short window of hand motion, so throws match the motion the user made rather than the frame they opened their hand.
+
+The pointer ray stops at whatever it is pointing at, and hover feedback tells the user what they are about to pick up.
 
 ```ts
 import { Behaviour } from "@relu-interactives/spatial-ecs";
@@ -60,6 +64,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

@@ -2333,7 +2333,6 @@ var _XRInteractableComponent = class _XRInteractableComponent extends Component
     this.enabled = options?.enabled ?? true;
     this.grabbable = options?.grabbable ?? true;
     this.pointable = options?.pointable ?? true;
-    this.grabMode = options?.grabMode ?? "kinematic";
     this.grabReach = options?.grabReach ?? "both";
     this.distanceBehavior = options?.distanceBehavior ?? "snap";
     this.grabGesture = options?.grabGesture ?? "any";
@@ -2348,13 +2347,34 @@ 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;
+    this.hoverBehavior = options?.hoverBehavior ?? "color";
+    this.hoverColor = options?.hoverColor ?? "#4da3ff";
+    this.hoverScale = options?.hoverScale ?? 1.06;
   }
 };
 __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) {