@relu-interactives/spatial-ecs 0.2.10 → 0.2.11

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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/core/types.ts#L56) |
+| <a id="max"></a> `max` | `number` | [types.ts:57](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/557de6ec692f18eb77e7225eb98be3af4dfc0e33/core/types.ts#L57) |
+| <a id="step"></a> `step` | `number` | [types.ts:58](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/557de6ec692f18eb77e7225eb98be3af4dfc0e33/core/types.ts#L58) |
+| <a id="value"></a> `value` | `number` | [types.ts:59](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/core/types.ts#L53) |
+| <a id="y"></a> `y` | `number` | [types.ts:53](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/core/types.ts#L54) |
+| <a id="y"></a> `y` | `number` | [types.ts:54](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/557de6ec692f18eb77e7225eb98be3af4dfc0e33/core/types.ts#L54) |
+| <a id="z"></a> `z` | `number` | [types.ts:54](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/557de6ec692f18eb77e7225eb98be3af4dfc0e33/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/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,189 @@
+# 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
+
+::: tip Screenshot
+Add a screenshot of the **Instanced Mesh** component in the editor inspector here.
+Suggested asset path: `/public/images/inspector/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/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)