@relu-interactives/spatial-ecs 0.2.10 → 0.2.12

package/dist/docs/api/types/type-aliases/IntersectionResult.md

@@ -13,7 +13,7 @@ type IntersectionResult = {
 };
 ```
 
-Defined in: [types.ts:151](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L151)
+Defined in: [types.ts:155](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L155)
 
 Single hit returned by `World.raycast` / `World.raycastFrom`. Pairs the
 standard `THREE.Intersection` (`threeResult`) with the owning entity id
@@ -25,5 +25,5 @@ editor helper).
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="entityid"></a> `entityId` | [`EntityId`](EntityId.md) \| `null` | The entity that owns the hit object, or `null` if untracked. | [types.ts:153](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L153) |
-| <a id="threeresult"></a> `threeResult` | `THREE.Intersection` | The underlying three.js intersection record. | [types.ts:155](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L155) |
+| <a id="entityid"></a> `entityId` | [`EntityId`](EntityId.md) \| `null` | The entity that owns the hit object, or `null` if untracked. | [types.ts:157](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L157) |
+| <a id="threeresult"></a> `threeResult` | `THREE.Intersection` | The underlying three.js intersection record. | [types.ts:159](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L159) |

package/dist/docs/api/types/type-aliases/ParentLookup.md

@@ -13,7 +13,7 @@ type ParentLookup = {
 };
 ```
 
-Defined in: [types.ts:128](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L128)
+Defined in: [types.ts:132](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L132)
 
 Result of a parent lookup. `parent` is `null` for entities at the root or
 for entities without a [ParentId](../../components/classes/ParentId.md) component.
@@ -22,5 +22,5 @@ for entities without a [ParentId](../../components/classes/ParentId.md) componen
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="parentidcomponent"></a> `parentIdComponent` | [`ParentId`](../../components/classes/ParentId.md) \| `null` | The entity's `ParentId` component, or `null` if it has none. | [types.ts:130](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L130) |
-| <a id="parent"></a> `parent` | [`WorldEntityView`](WorldEntityView.md) \| `null` | The resolved parent entity view, or `null` if the entity is at the root. | [types.ts:132](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L132) |
+| <a id="parentidcomponent"></a> `parentIdComponent` | [`ParentId`](../../components/classes/ParentId.md) \| `null` | The entity's `ParentId` component, or `null` if it has none. | [types.ts:134](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L134) |
+| <a id="parent"></a> `parent` | [`WorldEntityView`](WorldEntityView.md) \| `null` | The resolved parent entity view, or `null` if the entity is at the root. | [types.ts:136](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L136) |

package/dist/docs/api/types/type-aliases/SelectionListener.md

@@ -10,7 +10,7 @@
 type SelectionListener = (entityId) => void;
 ```
 
-Defined in: [types.ts:43](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L43)
+Defined in: [types.ts:45](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L45)
 
 Callback invoked when the selected entity changes. `null` indicates a deselection.
 

package/dist/docs/api/types/type-aliases/SliderInput.md

@@ -15,13 +15,13 @@ type SliderInput = {
 };
 ```
 
-Defined in: [types.ts:53](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L53)
+Defined in: [types.ts:55](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L55)
 
 ## Properties
 
 | Property | Type | Defined in |
 | ------ | ------ | ------ |
-| <a id="min"></a> `min` | `number` | [types.ts:54](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L54) |
-| <a id="max"></a> `max` | `number` | [types.ts:55](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L55) |
-| <a id="step"></a> `step` | `number` | [types.ts:56](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L56) |
-| <a id="value"></a> `value` | `number` | [types.ts:57](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L57) |
+| <a id="min"></a> `min` | `number` | [types.ts:56](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L56) |
+| <a id="max"></a> `max` | `number` | [types.ts:57](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L57) |
+| <a id="step"></a> `step` | `number` | [types.ts:58](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L58) |
+| <a id="value"></a> `value` | `number` | [types.ts:59](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L59) |

package/dist/docs/api/types/type-aliases/TextInput.md

@@ -10,4 +10,4 @@
 type TextInput = string;
 ```
 
-Defined in: [types.ts:48](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L48)
+Defined in: [types.ts:50](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L50)

package/dist/docs/api/types/type-aliases/ToggleInput.md

@@ -10,4 +10,4 @@
 type ToggleInput = boolean;
 ```
 
-Defined in: [types.ts:62](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L62)
+Defined in: [types.ts:64](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L64)

package/dist/docs/api/types/type-aliases/Vec3.md

@@ -16,7 +16,7 @@ type Vec3 =
 };
 ```
 
-Defined in: [types.ts:140](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L140)
+Defined in: [types.ts:144](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L144)
 
 Loose 3D vector accepted by raycast and other spatial helpers. Either a
 live `THREE.Vector3` or a plain `{ x, y, z }` object — both are normalized

package/dist/docs/api/types/type-aliases/Vector2Input.md

@@ -13,11 +13,11 @@ type Vector2Input = {
 };
 ```
 
-Defined in: [types.ts:51](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L51)
+Defined in: [types.ts:53](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L53)
 
 ## Properties
 
 | Property | Type | Defined in |
 | ------ | ------ | ------ |
-| <a id="x"></a> `x` | `number` | [types.ts:51](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L51) |
-| <a id="y"></a> `y` | `number` | [types.ts:51](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L51) |
+| <a id="x"></a> `x` | `number` | [types.ts:53](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L53) |
+| <a id="y"></a> `y` | `number` | [types.ts:53](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L53) |

package/dist/docs/api/types/type-aliases/Vector3Input.md

@@ -14,12 +14,12 @@ type Vector3Input = {
 };
 ```
 
-Defined in: [types.ts:52](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L52)
+Defined in: [types.ts:54](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L54)
 
 ## Properties
 
 | Property | Type | Defined in |
 | ------ | ------ | ------ |
-| <a id="x"></a> `x` | `number` | [types.ts:52](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L52) |
-| <a id="y"></a> `y` | `number` | [types.ts:52](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L52) |
-| <a id="z"></a> `z` | `number` | [types.ts:52](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L52) |
+| <a id="x"></a> `x` | `number` | [types.ts:54](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L54) |
+| <a id="y"></a> `y` | `number` | [types.ts:54](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L54) |
+| <a id="z"></a> `z` | `number` | [types.ts:54](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L54) |

package/dist/docs/api/types/type-aliases/WorldEntityView.md

@@ -10,7 +10,7 @@
 type WorldEntityView = NonNullable<ReturnType<World["getEntityById"]>>;
 ```
 
-Defined in: [types.ts:122](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/bdd9282dee928f9a7d192d992833af9bda98772b/core/types.ts#L122)
+Defined in: [types.ts:126](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L126)
 
 Lightweight, read-only view of an entity returned by `World.getEntityById`.
 Contains the entity id and its current component list at the moment of the

package/dist/docs/guide/component-catalog.md

@@ -27,6 +27,8 @@ Every entity in `@relu-interactives/spatial-ecs` is a bag of components. This ca
 - [Sprite](./components/sprite) — camera-facing billboard.
 - [Video](./components/video) — video texture with optional green-screen keying.
 - [Model](./components/model) — GLTF/GLB asset reference loaded asynchronously.
+- [Instanced Mesh](./components/instanced-mesh) — groups instance-slot entities into a single GPU-instanced draw call for high-count identical objects.
+- [Instance Slot](./components/instance-slot) — marks an entity as a single instance within an `InstancedMeshComponent` group.
 
 ## Lighting & atmosphere
 

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/instance-slot.md

@@ -0,0 +1,102 @@
+# Instance Slot
+
+Marks an entity as a single instance within an [`InstancedMeshComponent`](./instanced-mesh) group. Instance slot entities are lightweight data containers — they carry a `TransformComponent` (the per-instance local transform) and this component, but do **not** have an `Object3DRef`. `InstancedMeshSystem` reads every slot's `TransformComponent` each frame to compose the instance matrix for that slot's index.
+
+Slot entities appear in the hierarchy as children of their owning `instancedMesh` group entity. Removing a slot entity from the world (or removing its ID from `InstancedMeshComponent.instanceEntityIds`) retires that instance.
+
+> **Used by:** [`InstancedMeshSystem`](../systems/instanced-mesh-system), [`InstancedMeshComponent`](./instanced-mesh)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `groupEntityId` | `number` | Entity ID of the owning `InstancedMeshComponent` group entity. |
+| `slotIndex` | `number` | Zero-based index of this slot within the group's `instanceEntityIds` array. Used by `InstancedMeshSystem` to write the correct column of the instance-matrix buffer. |
+
+## API reference
+
+- Class: [`InstanceSlotComponent`](../../api/components/classes/InstanceSlotComponent.md)
+- Source: [`core/components/InstanceSlotComponent.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/InstanceSlotComponent.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const slot = this.getComponent(InstanceSlotComponent);
+
+// Component on another entity
+const other = this.world.getEntityByName("Instance 3");
+if (other) {
+  const slot = this.world.getComponent(other.entityId, InstanceSlotComponent);
+}
+```
+:::
+
+### Find the group from a slot
+
+```typescript
+import {
+  Behaviour,
+  InstanceSlotComponent,
+  InstancedMeshComponent,
+} from "@relu-interactives/spatial-ecs";
+
+export default class SlotInfo extends Behaviour {
+  protected init() {
+    const slot = this.getComponent(InstanceSlotComponent);
+    if (!slot) return;
+
+    const groupEntity = this.world.getEntityById(slot.groupEntityId);
+    if (!groupEntity) return;
+
+    const group = this.world.getComponent(slot.groupEntityId, InstancedMeshComponent);
+    console.log(
+      `This is slot #${slot.slotIndex} of a group with ${group?.instanceEntityIds.length} instances`,
+    );
+  }
+}
+```
+
+### Accept a slot reference via ComponentInput
+
+Use a `ComponentInput` field so the inspector can wire any instance slot entity to this script.
+
+```typescript
+import {
+  Behaviour,
+  InstanceSlotComponent,
+  TransformComponent,
+} from "@relu-interactives/spatial-ecs";
+import type { ComponentInput, FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class MoveSlot extends Behaviour {
+  data = {
+    targetSlot: {
+      type: "component",
+      componentKind: "InstanceSlot",
+      value: null,
+    } as unknown as ComponentInput<InstanceSlotComponent>,
+    offsetX: 1 as FloatInput,
+  };
+
+  protected init() {
+    const slot = this.data.targetSlot.value as InstanceSlotComponent | null;
+    if (!slot) return;
+
+    const transform = this.world.getComponentById(slot.groupEntityId, TransformComponent);
+    // Operate on the slot entity's own transform instead:
+    const slotEntity = this.world.getEntityById(
+      // find the slot entity ID from the group
+      (this.world.getComponent(slot.groupEntityId, { prototype: {} } as never) as never) ?? -1,
+    );
+    // Simpler: if this script is on the slot entity itself:
+    const ownTransform = this.getComponent(TransformComponent);
+    if (ownTransform) {
+      ownTransform.position.x += this.data.offsetX;
+    }
+  }
+}
+```

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

@@ -0,0 +1,186 @@
+# Instanced Mesh
+
+Groups one or more instance-slot entities into a single GPU-instanced draw call. Each instance's transform comes from its corresponding `InstanceSlotComponent` entity; `InstancedMeshSystem` reads those transforms every frame and writes the instance matrices into the underlying `THREE.InstancedMesh`.
+
+Use instanced meshes when you need tens, hundreds, or thousands of identical objects (trees, tiles, particles, projectiles, obstacles) without paying individual draw-call cost per object.
+
+> **Managed by:** [`InstancedMeshSystem`](../systems/instanced-mesh-system)
+
+## Editor inspector
+
+![Instanced Mesh inspector](/images/components/instanced-mesh.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `meshKind` | `InstancedMeshKind` | Geometry used for every instance. One of `"cube"`, `"sphere"`, `"plane"`, `"cylinder"`, `"capsule"`, `"model"`. |
+| `modelPath` | `string` | Source URL or `localasset://` path of the GLTF/GLB asset. Only read when `meshKind === "model"`. |
+| `meshParameters` | `MeshGeometryParameters` | Geometry dimensions (width/height/depth for box, radius/height for cylinder/capsule, radius for sphere, width/height for plane). Ignored when `meshKind === "model"`. |
+| `castShadow` | `boolean` | Whether all instances cast shadows. |
+| `receiveShadow` | `boolean` | Whether all instances receive shadows. |
+| `instanceEntityIds` | `number[]` | Ordered list of entity IDs for the `InstanceSlotComponent` entities owned by this group. Each slot carries its own `TransformComponent`. |
+| `instancedMesh` | `THREE.Object3D \| null` | Live runtime object managed by `InstancedMeshSystem`. `null` until the system builds the mesh. **Not serialized — do not persist or clone this field.** |
+
+## API reference
+
+- Class: [`InstancedMeshComponent`](../../api/components/classes/InstancedMeshComponent.md)
+- Source: [`core/components/InstancedMesh.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/InstancedMesh.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const instanced = this.getComponent(InstancedMeshComponent);
+
+// Component on another named entity
+const other = this.world.getEntityByName("Tree Group");
+if (other) {
+  const instanced = this.world.getComponent(other.entityId, InstancedMeshComponent);
+}
+```
+:::
+
+### Read instance count
+
+```typescript
+import { Behaviour, InstancedMeshComponent } from "@relu-interactives/spatial-ecs";
+
+export default class InstanceCounter extends Behaviour {
+  protected init() {
+    const instanced = this.getComponent(InstancedMeshComponent);
+    if (instanced) {
+      console.log(`This group has ${instanced.instanceEntityIds.length} instances`);
+    }
+  }
+}
+```
+
+### Toggle shadows on all instances at runtime
+
+```typescript
+import { Behaviour, InstancedMeshComponent } from "@relu-interactives/spatial-ecs";
+import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+
+export default class ToggleShadows extends Behaviour {
+  data = {
+    castShadow: true as BooleanInput,
+    receiveShadow: true as BooleanInput,
+  };
+
+  protected init() {
+    const instanced = this.getComponent(InstancedMeshComponent);
+    if (!instanced) return;
+    instanced.castShadow = this.data.castShadow;
+    instanced.receiveShadow = this.data.receiveShadow;
+  }
+}
+```
+
+### Animate every instance's Y position
+
+Move each slot entity up and down using a sine wave. `InstancedMeshSystem` reads the `TransformComponent` of each slot every frame, so mutating the transform is all that is needed.
+
+```typescript
+import {
+  Behaviour,
+  InstancedMeshComponent,
+  TransformComponent,
+} from "@relu-interactives/spatial-ecs";
+
+export default class WaveInstances extends Behaviour {
+  private elapsed = 0;
+
+  protected onUpdate() {
+    const instanced = this.getComponent(InstancedMeshComponent);
+    if (!instanced) return;
+
+    this.elapsed += this.deltaTime;
+
+    for (let i = 0; i < instanced.instanceEntityIds.length; i++) {
+      const slotId = instanced.instanceEntityIds[i];
+      const transform = this.world.getComponentById(slotId, TransformComponent);
+      if (transform) {
+        transform.position.y = Math.sin(this.elapsed + i * 0.5) * 2;
+      }
+    }
+  }
+}
+```
+
+### Accept a group reference via ComponentInput
+
+Use a `ComponentInput` field so the inspector can wire any `InstancedMeshComponent` entity to this script — useful when the script lives on a different entity than the group.
+
+```typescript
+import {
+  Behaviour,
+  InstancedMeshComponent,
+  TransformComponent,
+} from "@relu-interactives/spatial-ecs";
+import type { ComponentInput } from "@relu-interactives/spatial-ecs";
+
+export default class ScatterInstances extends Behaviour {
+  data = {
+    group: {
+      type: "component",
+      componentKind: "InstancedMesh",
+      value: null,
+    } as unknown as ComponentInput<InstancedMeshComponent>,
+  };
+
+  protected init() {
+    const instanced = this.data.group.value as InstancedMeshComponent | null;
+    if (!instanced) return;
+
+    // Scatter each instance randomly within a 10-unit area
+    for (const slotId of instanced.instanceEntityIds) {
+      const transform = this.world.getComponentById(slotId, TransformComponent);
+      if (transform) {
+        transform.position.x = (Math.random() - 0.5) * 10;
+        transform.position.z = (Math.random() - 0.5) * 10;
+      }
+    }
+  }
+}
+```
+
+### Spawn a new instance slot at runtime
+
+Add a new slot entity to an existing group from a script. The new slot's transform is registered with the group and `InstancedMeshSystem` picks it up on the next frame.
+
+```typescript
+import {
+  Behaviour,
+  InstancedMeshComponent,
+} from "@relu-interactives/spatial-ecs";
+
+export default class DynamicSpawner extends Behaviour {
+  protected init() {
+    const instanced = this.getComponent(InstancedMeshComponent);
+    if (!instanced) return;
+
+    const groupId = this.entityId;
+    const objects = this.world.getObjectManagementSystem();
+    objects?.requestCreate(
+      "instanceSlot",
+      {
+        name: `Instance ${instanced.instanceEntityIds.length + 1}`,
+        transform: { position: { x: 2, y: 0, z: 0 } },
+        options: {
+          groupEntityId: groupId,
+          slotIndex: instanced.instanceEntityIds.length,
+        },
+      },
+      (slotId) => {
+        instanced.instanceEntityIds.push(slotId);
+      },
+    );
+  }
+}
+```
+
+See the [Spawning Instanced Meshes](../spawning/instanced-mesh) guide for the full `requestCreate` API reference.

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/spawning/index.md

@@ -57,6 +57,10 @@ Kind-specific fields go on `payload.path` (asset URL) or `payload.options` (type
 - [Cylinder](./cylinder)
 - [Empty](./empty)
 
+### Instanced Meshes
+
+- [Instanced Mesh](./instanced-mesh) — GPU-instanced groups with dynamic slot management
+
 ### Media
 
 - [Model](./model)