@relu-interactives/spatial-ecs 0.2.11 → 0.2.13

package/dist/docs/guide/runtime-entity-management.md

@@ -0,0 +1,302 @@
+# Runtime Entity Management
+
+From a `Behaviour` script you have full control over the entity lifecycle: spawning new objects, adding or removing components on existing ones, re-parenting entities in the hierarchy, and deleting with proper resource cleanup.
+
+## The ObjectManagementSystem
+
+Every world exposes `ObjectManagementSystem` via `this.world.getObjectManagementSystem()`. It is the hub for all runtime entity and component creation:
+
+```ts
+const oms = this.world.getObjectManagementSystem();
+```
+
+Always null-check — `oms` returns `null` if the world has not been set up yet.
+
+---
+
+## 1. Spawning new objects
+
+Use `requestCreate` to queue a new entity from a built-in kind. The factory runs on the next frame and the optional `onCreated` callback fires with the new `entityId`:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class Spawner extends Behaviour {
+  private spawnedId: number | null = null;
+
+  protected init() {
+    const oms = this.world.getObjectManagementSystem();
+
+    oms?.requestCreate("cube", {
+      name: "RuntimeCube",
+      transform: { position: { x: 0, y: 1, z: 0 } },
+    }, (entityId) => {
+      this.spawnedId = entityId;
+    });
+  }
+
+  dispose(world: any) {
+    if (this.spawnedId !== null) {
+      this.world.getObjectManagementSystem()?.deleteEntity(this.world, this.spawnedId, true);
+    }
+  }
+}
+```
+
+Supported kinds: `"cube"`, `"sphere"`, `"plane"`, `"capsule"`, `"cylinder"`, `"empty"`, `"model"`, `"image"`, `"sprite"`, `"video"`, `"audio"`, `"camera"`, `"ambient-light"`, `"directional-light"`, `"point-light"`, `"spot-light"`, `"area-light"`, `"instanced-mesh"`.
+
+See the [Spawning reference](./spawning/) for per-kind payload schemas.
+
+---
+
+## 2. Adding components to existing entities
+
+### `world.addComponent` — simple data components
+
+Use `world.addComponent` to attach data-only components that carry no runtime handles:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import { Name } from "@relu-interactives/spatial-ecs/components";
+
+export default class Tagger extends Behaviour {
+  protected init() {
+    const entity = this.world.getEntityByName("Target");
+    if (!entity) return;
+
+    this.world.addComponent(entity.entityId, new Name({ value: "Tagged" }));
+  }
+}
+```
+
+### `oms.createComponentNow` — factory-initialized components
+
+For components that need runtime setup (Rapier physics bodies, Web Audio nodes, Three.js material instances, AnimationMixers) use `createComponentNow`. It calls the same registered factory used during scene construction, so all runtime handles are correctly wired up:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class AddPhysics extends Behaviour {
+  protected init() {
+    const oms = this.world.getObjectManagementSystem();
+    if (!oms) return;
+
+    oms.createComponentNow("physics", this.world, this.entityId, {
+      rigidbody: { type: "dynamic", mass: 1, gravityScale: 1 },
+      collider: { shape: "box" },
+    });
+  }
+}
+```
+
+**When to use which:**
+
+| Scenario | Method |
+|----------|--------|
+| Name, EntityType, Transform (data only) | `world.addComponent(id, new ComponentClass(...))` |
+| Physics with Rapier body/collider | `oms.createComponentNow("physics", world, id, config)` |
+| Audio with Web Audio node | `oms.createComponentNow("audio", world, id, path, options, ctx)` |
+| Material with Three.js material instance | `oms.createComponentNow("material", world, id, values)` |
+| Animation with clip catalog | `oms.createComponentNow("animation", world, id)` |
+
+**Registered factory kinds:**
+
+`"animation"`, `"audio"`, `"camera"`, `"physics"`, `"environment"`, `"entityType"`, `"image"`, `"imageTarget"`, `"imageTargetAnchor"`, `"light"`, `"material"`, `"mesh"`, `"meshGeometry"`, `"model"`, `"name"`, `"object3DRef"`, `"parentId"`, `"postprocessing"`, `"script"`, `"sprite"`, `"transform"`, `"video"`, `"instancedMesh"`.
+
+---
+
+## 3. Removing components
+
+Remove a component by passing its class to `world.removeComponent`. The associated runtime handles are not disposed — call system-specific cleanup first if needed:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import { PhysicsComponent } from "@relu-interactives/spatial-ecs/components";
+
+export default class Freezer extends Behaviour {
+  protected init() {
+    // Remove physics from this entity to freeze it in place
+    this.world.removeComponent(this.entityId, PhysicsComponent);
+  }
+}
+```
+
+---
+
+## 4. Re-parenting at runtime
+
+`oms.setParent(world, entityId, parentId, options?)` updates the `ParentId` component and reconciles the Three.js scene graph in the same frame. By default (`preserveWorldTransform: true`) the entity's world-space position and rotation are preserved by adjusting the local transform:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class Attach extends Behaviour {
+  protected init() {
+    const oms = this.world.getObjectManagementSystem();
+    if (!oms) return;
+
+    const anchor = this.world.getEntityByName("Anchor");
+    if (!anchor) return;
+
+    // Attach this entity under Anchor, preserving world position
+    oms.setParent(this.world, this.entityId, anchor.entityId);
+  }
+}
+```
+
+Detach from parent (become a direct child of the scene root):
+
+```ts
+oms.setParent(this.world, this.entityId, null);
+```
+
+`setParent` guards against cycles and returns `false` if the operation would create a loop or if either entity does not exist.
+
+---
+
+## 5. Deleting entities and freeing GPU memory
+
+`oms.deleteEntity(world, entityId, dispose?)` removes the entity from the ECS world and its `Object3D` from the Three.js scene graph:
+
+- Pass `dispose = false` (default) when geometry or materials are shared — GPU resources stay allocated.
+- Pass `dispose = true` for dynamically spawned, one-off objects to immediately free `BufferGeometry` and `Material` GPU memory.
+
+```ts
+// Safe remove (shared geometry/materials stay on GPU)
+oms.deleteEntity(this.world, entityId);
+
+// Full cleanup (frees GPU memory — use for unique spawned objects)
+oms.deleteEntity(this.world, entityId, true);
+```
+
+Always delete spawned entities in `dispose()` to prevent leaks when the script is removed:
+
+```ts
+dispose(world: any) {
+  if (this.spawnedId !== null) {
+    this.world.getObjectManagementSystem()?.deleteEntity(this.world, this.spawnedId, true);
+  }
+}
+```
+
+---
+
+## 6. Async loading patterns
+
+Models and audio load asynchronously. The entity is created immediately but the asset is not available until the loader fires. Use the `onCreated` callback for setup that doesn't need the asset, and poll component state in `onUpdate` for setup that does:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import { AnimationComponent } from "@relu-interactives/spatial-ecs/components";
+
+export default class ModelSpawner extends Behaviour {
+  private modelId: number | null = null;
+  private animSetup = false;
+
+  protected init() {
+    const oms = this.world.getObjectManagementSystem();
+
+    oms?.requestCreate("model", {
+      name: "Character",
+      path: "localasset://assets/character.glb",
+      transform: { position: { x: 0, y: 0, z: 0 } },
+    }, (entityId) => {
+      this.modelId = entityId;
+
+      // Safe immediately — entity exists, physics factory is synchronous
+      oms.createComponentNow("physics", this.world, entityId, {
+        rigidbody: { type: "dynamic", mass: 1 },
+        collider: { shape: "capsule" },
+      });
+    });
+  }
+
+  protected onUpdate() {
+    if (this.modelId === null || this.animSetup) return;
+
+    // availableClips populates after the GLB finishes loading
+    const anim = this.world.getComponent(this.modelId, AnimationComponent);
+    if (anim && anim.availableClips.length > 0) {
+      anim.addState("Idle", anim.availableClips[0], true);
+      anim.switchState("Idle");
+      this.animSetup = true;
+    }
+  }
+
+  dispose(world: any) {
+    if (this.modelId !== null) {
+      this.world.getObjectManagementSystem()?.deleteEntity(this.world, this.modelId, true);
+    }
+  }
+}
+```
+
+---
+
+## 7. Complete worked example
+
+Spawn a model, add physics, parent it under an AR anchor, set up animation once clips are ready, and clean everything up on dispose:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import { AnimationComponent } from "@relu-interactives/spatial-ecs/components";
+
+export default class ARCharacter extends Behaviour {
+  private characterId: number | null = null;
+  private animReady = false;
+
+  protected init() {
+    const oms = this.world.getObjectManagementSystem();
+    if (!oms) return;
+
+    const anchor = this.world.getEntityByName("ImageTargetAnchor");
+
+    oms.requestCreate("model", {
+      name: "ARCharacter",
+      path: "localasset://assets/character.glb",
+      transform: { position: { x: 0, y: 0, z: 0 } },
+    }, (entityId) => {
+      this.characterId = entityId;
+
+      // Parent under AR anchor so it tracks with the target
+      if (anchor) {
+        oms.setParent(this.world, entityId, anchor.entityId);
+      }
+
+      // Add physics (Rapier body wired immediately by the factory)
+      oms.createComponentNow("physics", this.world, entityId, {
+        rigidbody: { type: "kinematic-position" },
+        collider: { shape: "capsule" },
+      });
+    });
+  }
+
+  protected onUpdate() {
+    if (this.characterId === null || this.animReady) return;
+
+    const anim = this.world.getComponent(this.characterId, AnimationComponent);
+    if (anim && anim.availableClips.length > 0) {
+      if (anim.availableClips.includes("Idle")) anim.addState("Idle", "Idle", true);
+      if (anim.availableClips.includes("Walk")) anim.addState("Walk", "Walk", true);
+      anim.crossFadeDuration = 0.3;
+      anim.switchState("Idle");
+      this.animReady = true;
+    }
+  }
+
+  dispose(world: any) {
+    if (this.characterId !== null) {
+      this.world.getObjectManagementSystem()?.deleteEntity(this.world, this.characterId, true);
+    }
+  }
+}
+```
+
+---
+
+## See also
+
+- [Spawning reference](./spawning/) — per-kind payload schemas for `requestCreate`
+- [ObjectManagementSystem](./systems/object-management-system) — system internals and API reference
+- [Accessing Components](./accessing-components) — reading and writing component state
+- [World API](./world-api) — entity queries, input, raycasting, scene access

package/dist/docs/guide/scene/environment.md

@@ -12,15 +12,14 @@ It is a **singleton** there is exactly one `Environment` entity per scene, owned
 
 ## Get the component from the world
 
+Use `world.getEnvironmentComponent()` — a convenience method that handles the entity lookup for you:
+
 ```ts
-import { Behaviour, Environment } from "@relu-interactives/spatial-ecs";
+import { Behaviour } from "@relu-interactives/spatial-ecs";
 
 export default class ReadEnvironment extends Behaviour {
   init() {
-    const [entityId] = this.world.query(Environment);
-    if (entityId === undefined) return;
-
-    const env = this.world.getComponent(entityId, Environment);
+    const env = this.world.getEnvironmentComponent();
     if (!env) return;
 
     console.log("skybox type", env.values.skybox.type);
@@ -29,7 +28,7 @@ export default class ReadEnvironment extends Behaviour {
 }
 ```
 
-`env.values` is the live state object. Mutating fields on it is enough, the `EnvironmentSyncSystem` reads it every frame and pushes changes into the three.js scene.
+`env.values` is the live state object. Mutating fields on it is enough — `EnvironmentSyncSystem` reads it every frame and pushes changes into the three.js scene.
 
 ## Change values at runtime
 

package/dist/docs/guide/scene/index.md

@@ -9,22 +9,17 @@ Some settings live on the **scene** rather than on a single object the skybox, f
 
 ## Pattern
 
-Both components follow the same access pattern from a script:
+Both components expose a convenience method on `world` — no manual entity lookup needed:
 
 ```ts
-import { Behaviour, Environment, Postprocessing } from "@relu-interactives/spatial-ecs";
+import { Behaviour } from "@relu-interactives/spatial-ecs";
 
 export default class TweakScene extends Behaviour {
   init() {
-    // 1. Find the singleton entity that owns the component.
-    const [entityId] = this.world.query(Environment);
-    if (entityId === undefined) return;
-
-    // 2. Read the component instance.
-    const env = this.world.getComponent(entityId, Environment);
+    const env = this.world.getEnvironmentComponent();
     if (!env) return;
 
-    // 3. Mutate `env.values` — sync systems pick the change up next frame.
+    // Mutate `env.values` — sync systems pick the change up next frame.
     env.values.fog.type = "linear";
     env.values.fog.color = "#88aaff";
     env.values.fog.linear.near = 5;
@@ -33,4 +28,4 @@ export default class TweakScene extends Behaviour {
 }
 ```
 
-The same shape works for `Postprocessing` — see each page for the full set of authorable values.
+The same pattern works for `Postprocessing` via `this.world.getPostprocessingComponent()` — see each page for the full set of authorable values.

package/dist/docs/guide/scene/postprocessing.md

@@ -11,15 +11,14 @@ It is a **singleton** there is exactly one `Postprocessing` entity per scene, ow
 
 ## Get the component from the world
 
+Use `world.getPostprocessingComponent()` — a convenience method that handles the entity lookup for you:
+
 ```ts
-import { Behaviour, Postprocessing } from "@relu-interactives/spatial-ecs";
+import { Behaviour } from "@relu-interactives/spatial-ecs";
 
 export default class ReadPostprocessing extends Behaviour {
   init() {
-    const [entityId] = this.world.query(Postprocessing);
-    if (entityId === undefined) return;
-
-    const post = this.world.getComponent(entityId, Postprocessing);
+    const post = this.world.getPostprocessingComponent();
     if (!post) return;
 
     console.log("post enabled?", post.values.postEnabled);
@@ -27,7 +26,7 @@ export default class ReadPostprocessing extends Behaviour {
 }
 ```
 
-`post.values` is the live state object mutate fields on it directly. The `PostprocessingSyncSystem` reads it every frame and rebuilds the composer pipeline as effects are toggled.
+`post.values` is the live state object — mutate fields on it directly. The `PostprocessingSyncSystem` reads it every frame and rebuilds the composer pipeline as effects are toggled.
 
 ## Change values at runtime
 

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,7 +32,77 @@ 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
 
+### `requestCreate(kind, payload?, onCreated?)`
+
+Queue a new entity creation request. The factory for the given `kind` runs on the next frame; the optional `onCreated` callback fires with the new `entityId`:
+
+```ts
+const oms = this.world.getObjectManagementSystem();
+
+oms?.requestCreate("cube", {
+  name: "DynamicCube",
+  transform: { position: { x: 0, y: 2, z: 0 } },
+}, (entityId) => {
+  // entityId is ready — add more components here
+});
+```
+
+### `createComponentNow(kind, world, entityId, ...args)`
+
+Synchronously call the registered component factory for `kind` on an existing entity. Use this instead of `world.addComponent` when the component needs runtime setup (Rapier bodies, Web Audio nodes, Three.js material instances):
+
+```ts
+// Add physics with full Rapier body + collider setup
+oms.createComponentNow("physics", world, entityId, {
+  rigidbody: { type: "dynamic", mass: 1, gravityScale: 1 },
+  collider: { shape: "box" },
+});
+
+// Add a material with a Three.js material instance
+oms.createComponentNow("material", world, entityId, { color: "#ff0000" });
+```
+
+Registered factory kinds: `"animation"`, `"audio"`, `"camera"`, `"physics"`, `"environment"`, `"entityType"`, `"image"`, `"imageTarget"`, `"imageTargetAnchor"`, `"light"`, `"material"`, `"mesh"`, `"meshGeometry"`, `"model"`, `"name"`, `"object3DRef"`, `"parentId"`, `"postprocessing"`, `"script"`, `"sprite"`, `"transform"`, `"video"`, `"instancedMesh"`.
+
+### `deleteEntity(world, entityId, dispose?)`
+
+Remove an entity from the ECS world and its `Object3D` from the Three.js scene graph. Pass `dispose = true` to also free GPU memory by calling `.dispose()` on all `BufferGeometry` and `Material` instances in the subtree:
+
+```ts
+// Remove from scene, keep GPU resources (safe if geometry is shared)
+oms.deleteEntity(world, entityId);
+
+// Remove from scene and free GPU memory (use for dynamically spawned objects)
+oms.deleteEntity(world, entityId, true);
+```
+
+### `setParent(world, entityId, parentId, options?)`
+
+Re-parent an entity at runtime. Updates the `ParentId` component and reconciles the Three.js scene graph on the same frame. By default (`preserveWorldTransform: true`), world-space position and rotation are preserved by adjusting the local transform:
+
+```ts
+// Attach child to a parent entity (preserves world position)
+oms.setParent(world, childEntityId, parentEntityId);
+
+// Detach from parent — make direct child of scene root
+oms.setParent(world, childEntityId, null);
+
+// Reparent without preserving world position (local transform reset)
+oms.setParent(world, childEntityId, parentEntityId, { preserveWorldTransform: false });
+```
+
+`setParent` guards against cycles and returns `false` if the operation would create a loop or if either entity does not exist.
+
 - Source: [`core/systems/ObjectManagementSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/ObjectManagementSystem.ts)

package/dist/docs/guide/world-api.md

@@ -102,6 +102,8 @@ Both methods accept `Vec3` (`THREE.Vector3` or `{ x, y, z }`) and return `Inters
 | `getSystem(SystemClass)` | Resolve a registered system instance. |
 | `hasSystem(SystemClass)` | `true` if the system is registered. |
 | `getObjectManagementSystem()` | Shorthand for the built-in `ObjectManagementSystem`. Use this to spawn or destroy entities at runtime (`requestCreate`, `createNow`, `deleteEntity`). |
+| `getEnvironmentComponent()` | Returns the singleton [`Environment`](./scene/environment) component, or `undefined` if not yet initialized. Mutate `values` to change skybox, fog, or gravity at runtime. |
+| `getPostprocessingComponent()` | Returns the singleton [`Postprocessing`](./scene/postprocessing) component, or `undefined` if not yet initialized. Mutate `values` to toggle effects or adjust parameters at runtime. |
 
 ### World lifecycle
 
@@ -398,6 +400,6 @@ export default class PauseOnHit extends Behaviour {
 ## See also
 
 - [Custom Behaviours](./authoring-a-behaviour) — `init`, `onUpdate`, `dispose`, `data`, lifecycle.
-- [Inspector Data Binding](./inspector-data-binding) — exposing fields to the inspector through `data`.
+- [Behaviour Data Binding](./behaviour-data-binding/) — exposing fields to the inspector through `data`.
 - [Behaviour Lifecycle & Events](./behaviour-lifecycle) — when each hook fires.
 - [Component Catalog](./component-catalog) — the components you'll read and mutate from scripts.