@relu-interactives/spatial-ecs 0.2.11 → 0.2.12

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

@@ -109,9 +109,48 @@ export default class AnimationSpeedDriver extends Behaviour {
 ```
 
 ::: tip State machine
-Always use anim.switchState(name)` to change the active clip — do not assign to `active` directly. This ensures the animation system observes the transition and applies the configured cross-fade.
+Always use `anim.switchState(name)` to change the active clip — do not assign to `active` directly. This ensures the animation system observes the transition and applies the configured cross-fade.
 :::
 
+### ⚠️ `addState` — positional args only (critical)
+
+`addState` takes **three positional arguments**: `(name, clipRef, loop)`. Passing an object will silently resolve nothing because `resolveClipRef` won't find a clip named `[object Object]`.
+
+```typescript
+// ✅ Correct — positional args
+anim.addState("Walk", "Walk", true);
+anim.addState("Attack", "Attack", false);
+
+// ❌ Wrong — object arg; the clip will never resolve
+anim.addState({ name: "Walk", clip: "Walk", loop: true }); // ← broken
+```
+
+### Typical deferred setup (model may not be loaded yet)
+
+Guard on `availableClips.length > 0` inside `onUpdate` until the model is ready, then register states once:
+
+```typescript
+import { Behaviour, AnimationComponent } from "@relu-interactives/spatial-ecs";
+
+export default class AnimSetup extends Behaviour {
+  private ready = false;
+
+  protected onUpdate() {
+    if (this.ready) return;
+    const anim = this.getComponent(AnimationComponent);
+    if (!anim || anim.availableClips.length === 0) return;
+
+    const c = anim.availableClips;
+    if (c.includes("Walk"))   anim.addState("Walk",   "Walk",   true);
+    if (c.includes("Run"))    anim.addState("Run",    "Run",    true);
+    if (c.includes("Attack")) anim.addState("Attack", "Attack", false);
+    anim.crossFadeDuration = 0.25;
+    anim.switchState("Walk");
+    this.ready = true;
+  }
+}
+```
+
 ### Via `ComponentInput` in the inspector
 
 You can also pick this component from the inspector using a `ComponentInput` field. Assign any entity in the inspector and the field resolves to the live `AnimationComponent` instance at runtime.

package/dist/docs/guide/components/instanced-mesh.md

@@ -8,10 +8,7 @@ Use instanced meshes when you need tens, hundreds, or thousands of identical obj
 
 ## Editor inspector
 
-::: tip Screenshot
-Add a screenshot of the **Instanced Mesh** component in the editor inspector here.
-Suggested asset path: `/public/images/inspector/instanced-mesh.png`
-:::
+![Instanced Mesh inspector](/images/components/instanced-mesh.png)
 
 ## Properties
 

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

@@ -40,13 +40,35 @@ export default class SpawnSound extends Behaviour {
 
 ### `options`
 
-| Option          | Type           | Default | Description                                      |
-| --------------- | -------------- | ------- | ------------------------------------------------ |
-| `autoplay`      | `boolean`      | `false` | Start playback as soon as the clip is loaded.    |
-| `loop`          | `boolean`      | `false` | Loop playback indefinitely.                      |
-| `volume`        | `number` (0–1) | `1`     | Linear gain.                                     |
-| `refDistance`   | `number`       | `1`     | Distance at which volume is unattenuated.        |
-| `rolloffFactor` | `number`       | `1`     | How quickly volume falls off past `refDistance`. |
+| Option          | Type                                     | Default     | Description                                                       |
+| --------------- | ---------------------------------------- | ----------- | ----------------------------------------------------------------- |
+| `autoplay`      | `boolean`                                | `false`     | Start playback as soon as the clip is loaded.                     |
+| `loop`          | `boolean`                                | `false`     | Loop playback indefinitely.                                       |
+| `volume`        | `number` (0–1)                           | `1`         | Linear gain.                                                      |
+| `pitch`         | `number`                                 | `1`         | Playback rate multiplier (`1` = normal speed/pitch).              |
+| `positional`    | `boolean`                                | `false`     | When `true`, audio is spatialized using the entity's transform.   |
+| `refDistance`   | `number`                                 | `1`         | Distance at which volume is unattenuated (positional only).       |
+| `distanceModel` | `"linear" \| "inverse" \| "exponential"` | `"inverse"` | WebAudio distance model (positional only).                        |
+| `rolloffFactor` | `number`                                 | `1`         | How quickly volume falls off past `refDistance`.                  |
+
+## ⚠️ Common mistake — wrong payload shape
+
+`path` and `options` must be **top-level** keys on the payload. Never nest them inside an `audio:` sub-object.
+
+```ts
+// ✅ Correct
+objects?.requestCreate("audio", {
+  name: "SFX",
+  path: "localasset://assets/sfx/hit.mp3",
+  options: { autoplay: true, volume: 0.8 },
+});
+
+// ❌ Wrong — do NOT wrap inside audio:{}
+objects?.requestCreate("audio", {
+  name: "SFX",
+  audio: { path: "...", options: { autoplay: true } }, // ← this will be ignored
+});
+```
 
 ## Components attached
 

package/dist/docs/guide/systems/object-management-system.md

@@ -32,6 +32,15 @@ Component kinds (e.g. `"animation"`, `"physics"`) are registered with `registerC
 - **Parent reconciliation** — if a `ParentId` refers to an entity that does not yet have an `Object3DRef` (e.g. the parent is still loading), reparenting is deferred to the next frame.
 - **Scene root** — entities without a `ParentId` (or with `ParentId.parentId === null`) are kept as direct children of the THREE.js scene root.
 - **Audio listener** — `getOrCreateAudioListener()` lazily creates a single `THREE.AudioListener` on the world camera and is used by audio object factories.
+- **Entity deletion** — `deleteEntity(world, entityId)` removes the entity from the ECS world and its `Object3D` from the THREE.js scene graph. Pass `dispose = true` as the third argument to also call `.dispose()` on all `BufferGeometry` and `Material` instances in the subtree, freeing GPU memory. Use this for dynamically spawned objects that will not be reused. Avoid it when geometry or materials are shared with other entities.
+
+  ```ts
+  // Remove from scene only (geometry/materials are kept on the GPU — safe if shared)
+  objects.deleteEntity(world, entityId);
+
+  // Remove from scene and free GPU memory
+  objects.deleteEntity(world, entityId, true);
+  ```
 
 ## API reference