@relu-interactives/spatial-ecs 0.11.0 → 0.11.1

package/dist/docs/guide/bone-attachments-and-ik.md

@@ -75,6 +75,51 @@ Moving an attached entity to another parent (`setParent`) also ends its attachme
 
 Until the parent's model has loaded, or when the named bone doesn't exist in it, the entity sits under the character as an ordinary child. The attachment is kept and takes effect as soon as the bone appears.
 
+### Different places in different clips
+
+A character rarely holds something the same way through every clip. `holds` say where the entity goes while particular clips play, on the attachment itself, so no script has to move it. Here a rifle rides the right hand in the rifle clips, is slung on the back in `Idle`, and is hidden in the rest:
+
+```ts
+import { Behaviour, type EntityInput } from "@relu-interactives/spatial-ecs";
+import { BoneAttachmentComponent, normalizeBoneHold } from "@relu-interactives/spatial-ecs/components";
+
+export default class SlungRifle extends Behaviour {
+  data = {
+    rifle: { type: "entity", value: null } as EntityInput,
+  };
+
+  init() {
+    const rifle = this.data.rifle.value;
+    if (rifle === null) return;
+    const attachment = this.world.getComponent(rifle, BoneAttachmentComponent);
+    if (!attachment) return;
+    attachment.holds = [
+      { clips: ["Rifle_run", "Rifle_stand"] },
+      {
+        clips: ["Idle"],
+        humanoid: "chest",
+        position: { x: 0.1, y: 0.1, z: -0.2 },
+        rotation: { x: 0, y: 0, z: 1.2 },
+      },
+    ].map(normalizeBoneHold);
+    attachment.hideInOtherClips = true;
+  }
+}
+```
+
+The first hold that names the playing clip wins. Its fields:
+
+| Field | Meaning |
+| --- | --- |
+| `clips` | Clip names this hold is for. |
+| `bone`, `humanoid` | Another bone for these clips, by node name or humanoid name. Leave both `null` to stay on the attachment's own bone. |
+| `hidden` | Hide the entity in these clips. |
+| `position`, `rotation` | Where it sits from the bone in these clips, in place of its Transform's. Leave one `null` to keep the Transform's. `rotation` is in radians. |
+
+`hideInOtherClips` hides the entity while a clip no hold names is playing. With no clip playing, or on a character with no Animation component, the attachment is as its own fields say and nothing is hidden. A hold never changes the entity's Transform, so saving a scene keeps it as authored. Moving between holds is immediate: there is no blend.
+
+The clip comes from the Animation component on the entity's parent. Holds use clip names, so they follow whatever state plays that clip.
+
 ## Reach for targets with IK
 
 Add an `IKComponent` to the CHARACTER (the entity with the model) and give it one chain per limb. Each chain names the hand or foot (`limb`) and a `target` entity whose world position it reaches:
@@ -111,9 +156,15 @@ Chain fields:
 | `weight` | 0 = the animation, 1 = the target; blend in between (fade a grip in or out by animating it). |
 | `matchRotation` | Also turn the hand/foot to the target's rotation. |
 | `enabled` | Turn one chain off. |
+| `clips` | Run only while one of these clips plays; `null` runs whatever plays. |
+| `fade` | Seconds a chain with `clips` takes to fade in or out when the clip changes; `null` follows the Animation component's cross-fade. |
+
+`clips` lets a character use IK only where it belongs. A left hand on a rifle's foregrip applies to the rifle clips and lets go in the rest, fading along with the clip. A chain with `clips` needs an Animation component on the character: with none, no clip is playing, so it stays off. One limb can have several chains with different `clips`, to reach different things in different clips. If a chain's clip is the first one playing, it starts on rather than fading in.
 
 Change chains at runtime by editing `chains` on the component; turn all of them off with `enabled = false`, which puts every bone back to the animation's pose.
 
+A limb that is dead straight has no bend of its own, so with no `pole` an arm out to the side drops its elbow, and a limb upright or hanging bends toward the way the character faces.
+
 Targets out of reach are reached for as far as the limb allows. Ask the system how far a limb fell short. It answers `null` for a limb whose chain didn't run that frame, because the chain is off or has no target:
 
 ```ts

package/dist/docs/guide/components/audio.md

@@ -13,7 +13,7 @@ Plays an audio clip from `path`. Supports both global stereo (`positional: false
 | Property | Type | Description |
 | --- | --- | --- |
 | `path` | `string` | Source URL or `localasset://` path of the audio file. |
-| `options` | `typeof DEFAULT_AUDIO_OPTIONS` | Playback options.  | Field | Default | Description | |---|---|---| | `autoplay` | `false` | Start playback as soon as the clip is loaded. | | `loop` | `false` | Loop playback indefinitely. | | `pitch` | `1` | Playback rate multiplier (`1` = normal speed/pitch). | | `volume` | `1` | Linear gain in `[0, 1]`. | | `positional` | `false` | When `true`, audio is spatialized using the entity's transform. | | `refDistance` | `1` | Distance at which volume is unattenuated (positional only). | | `distanceModel` | `"inverse"` | WebAudio distance model (`linear`, `inverse`, `exponential`). | | `rolloffFactor` | `1` | How quickly volume falls off past `refDistance`. | |
+| `options` | `typeof DEFAULT_AUDIO_OPTIONS` | Playback options.  | Field | Default | Description | |---|---|---| | `autoplay` | `false` | Start playback as soon as the clip is loaded. | | `loop` | `false` | Loop playback indefinitely. | | `pitch` | `1` | Playback rate multiplier (`1` = normal speed/pitch). | | `volume` | `1` | Linear gain in `[0, 1]`. | | `positional` | `false` | When `true`, audio is spatialized using the entity's transform. | | `refDistance` | `1` | Distance at which volume is unattenuated (positional only). | | `distanceModel` | `"inverse"` | WebAudio distance model (`linear`, `inverse`, `exponential`). | | `rolloffFactor` | `1` | How quickly volume falls off past `refDistance`. | | `bus` | `"sfx"` | The mixer group it plays through: `sfx`, `voice` or `music`. Music dips while a voice plays. | |
 | `object` | `THREE.Object3D \| null` | Live three.js object hosting the audio (a parented `Audio`/`PositionalAudio`). `null` until built. |
 | `audio` | `THREE.Audio<GainNode> \| THREE.PositionalAudio \| null` | Live three.js audio source. `null` until built. Recreated when the project loads. |
 | `isPlaying` | `boolean` | Whether the audio should be playing. Managed by `AudioSystem` in preview. Non-enumerable — not persisted to snapshots or save data. Set via `play` / `stop`. |

package/dist/factories/index.cjs

@@ -2454,6 +2454,21 @@ function createXRAnchorComponent(world, entityId, ...args) {
 __name(createXRAnchorComponent, "createXRAnchorComponent");
 
 // core/components/BoneAttachment.ts
+var xyz = /* @__PURE__ */ __name((value) => {
+  const v = value;
+  return typeof v?.x === "number" && typeof v.y === "number" && typeof v.z === "number" ? { x: v.x, y: v.y, z: v.z } : null;
+}, "xyz");
+function normalizeBoneHold(hold) {
+  return {
+    clips: Array.isArray(hold.clips) ? hold.clips.filter((c) => typeof c === "string") : [],
+    bone: typeof hold.bone === "string" && hold.bone ? hold.bone : null,
+    humanoid: typeof hold.humanoid === "string" && hold.humanoid ? hold.humanoid : null,
+    hidden: hold.hidden === true,
+    position: xyz(hold.position),
+    rotation: xyz(hold.rotation)
+  };
+}
+__name(normalizeBoneHold, "normalizeBoneHold");
 var _BoneAttachmentComponent = class _BoneAttachmentComponent extends Component {
   constructor(options) {
     super();
@@ -2461,6 +2476,8 @@ var _BoneAttachmentComponent = class _BoneAttachmentComponent extends Component
     this.humanoid = options?.humanoid ?? null;
     this.compensateScale = options?.compensateScale ?? true;
     this.enabled = options?.enabled ?? true;
+    this.holds = (options?.holds ?? []).map(normalizeBoneHold);
+    this.hideInOtherClips = options?.hideInOtherClips ?? false;
   }
 };
 __name(_BoneAttachmentComponent, "BoneAttachmentComponent");
@@ -2483,7 +2500,9 @@ function normalizeIKChain(chain) {
     pole: typeof chain.pole === "number" ? chain.pole : null,
     weight: Math.min(1, Math.max(0, weight)),
     matchRotation: chain.matchRotation ?? false,
-    enabled: chain.enabled ?? true
+    enabled: chain.enabled ?? true,
+    clips: Array.isArray(chain.clips) ? chain.clips.filter((c) => typeof c === "string") : null,
+    fade: typeof chain.fade === "number" && Number.isFinite(chain.fade) && chain.fade >= 0 ? chain.fade : null
   };
 }
 __name(normalizeIKChain, "normalizeIKChain");
@@ -3210,6 +3229,15 @@ __name(loadModelInto, "loadModelInto");
 // core/systems/ObjectManagementSystem.ts
 new THREE2__namespace.Vector3();
 new THREE2__namespace.Vector3();
+new THREE2__namespace.Vector3();
+new THREE2__namespace.Quaternion();
+new THREE2__namespace.Vector3();
+new THREE2__namespace.Quaternion();
+new THREE2__namespace.Matrix4();
+new THREE2__namespace.Matrix4();
+new THREE2__namespace.Euler();
+new THREE2__namespace.Vector3(1, 1, 1);
+new THREE2__namespace.Vector3();
 function createTransform(input) {
   return new TransformComponent(input);
 }