@relu-interactives/spatial-ecs 0.2.12 → 0.2.14

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

@@ -10,7 +10,7 @@
 type WorldEntityView = NonNullable<ReturnType<World["getEntityById"]>>;
 ```
 
-Defined in: [types.ts:126](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/7fc62aaeb41923795e50fda6e082908528d5abe6/core/types.ts#L126)
+Defined in: [types.ts:126](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/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/accessing-components.md

@@ -392,8 +392,142 @@ See [World API](./world-api) for the full set of entity and component query meth
 
 ---
 
+## Adding and removing components at runtime
+
+You can add or remove components on any entity from a Behaviour script at runtime using `this.world` or through `ObjectManagementSystem`.
+
+### `world.addComponent` — attach a data component
+
+Use `world.addComponent` to attach a simple, data-only component that carries 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;
+
+    // Give the entity a display name
+    this.world.addComponent(entity.entityId, new Name({ value: "Tagged" }));
+  }
+}
+```
+
+### `world.removeComponent` — detach a component by class
+
+```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);
+  }
+}
+```
+
+### `oms.createComponentNow` — factory-initialized components
+
+For components that require full runtime setup — Rapier physics bodies, Web Audio nodes, Three.js material instances, animation clip catalogs — use `createComponentNow` on `ObjectManagementSystem`. It calls the same registered factory used during scene construction, ensuring all runtime handles are correctly wired:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class DynamicPhysics extends Behaviour {
+  protected init() {
+    const oms = this.world.getObjectManagementSystem();
+    if (!oms) return;
+
+    // Add a physics component with full Rapier rigidbody and collider setup
+    oms.createComponentNow("physics", this.world, this.entityId, {
+      rigidbody: { type: "dynamic", mass: 1, gravityScale: 1 },
+      collider: { shape: "box" },
+    });
+  }
+}
+```
+
+**Registered component factory kinds:**
+
+| Kind | Component |
+|------|-----------|
+| `"animation"` | AnimationComponent |
+| `"audio"` | AudioComponent |
+| `"camera"` | CameraComponent |
+| `"physics"` | PhysicsComponent |
+| `"environment"` | EnvironmentComponent |
+| `"entityType"` | EntityTypeComponent |
+| `"image"` | ImageComponent |
+| `"imageTarget"` | ImageTargetComponent |
+| `"imageTargetAnchor"` | ImageTargetAnchorComponent |
+| `"light"` | LightComponent |
+| `"material"` | MaterialComponent |
+| `"mesh"` | MeshComponent |
+| `"meshGeometry"` | MeshGeometryComponent |
+| `"model"` | ModelComponent |
+| `"name"` | Name |
+| `"object3DRef"` | Object3DRef |
+| `"parentId"` | ParentId |
+| `"postprocessing"` | PostprocessingComponent |
+| `"script"` | ScriptComponent |
+| `"sprite"` | SpriteComponent |
+| `"transform"` | TransformComponent |
+| `"video"` | VideoComponent |
+| `"instancedMesh"` | InstancedMeshComponent |
+
+**Decision guide:**
+
+| Scenario | Use |
+|----------|-----|
+| Tagging with name, type, or other pure-data component | `world.addComponent(id, new ComponentClass(...))` |
+| Adding physics with Rapier body/collider | `oms.createComponentNow("physics", world, id, config)` |
+| Adding audio with Web Audio node | `oms.createComponentNow("audio", world, id, path, options, ctx)` |
+| Adding a material with Three.js material instance | `oms.createComponentNow("material", world, id, values)` |
+| Detaching any component | `world.removeComponent(id, ComponentClass)` |
+
+### Post-spawn example: add physics to a spawned cube
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class PhysicsCube extends Behaviour {
+  private spawnedId: number | null = null;
+
+  protected init() {
+    const oms = this.world.getObjectManagementSystem();
+    if (!oms) return;
+
+    oms.requestCreate("cube", {
+      name: "PhysicsCube",
+      transform: { position: { x: 0, y: 3, z: 0 } },
+    }, (entityId) => {
+      this.spawnedId = entityId;
+      // Physics factory wires up Rapier body + collider automatically
+      oms.createComponentNow("physics", this.world, entityId, {
+        rigidbody: { type: "dynamic", mass: 1, gravityScale: 1 },
+        collider: { shape: "box" },
+      });
+    });
+  }
+
+  dispose(world: any) {
+    if (this.spawnedId !== null) {
+      this.world.getObjectManagementSystem()?.deleteEntity(this.world, this.spawnedId, true);
+    }
+  }
+}
+```
+
+For the full guide covering `setParent`, async loading patterns, and complete worked examples, see [Runtime Entity Management](./runtime-entity-management).
+
+---
+
 ## See also
 
 - [Custom Behaviours](./authoring-a-behaviour) — script anatomy and lifecycle
-- [Inspector Data Binding](./inspector-data-binding) — exposing fields to the inspector
+- [Behaviour Data Binding](./behaviour-data-binding/) — exposing fields to the inspector
 - [World API](./world-api) — querying entities and components across the scene
+- [Runtime Entity Management](./runtime-entity-management) — addComponent, createComponentNow, setParent, deleteEntity

package/dist/docs/guide/authoring-a-behaviour.md

@@ -116,7 +116,7 @@ export default class Spinner extends Behaviour {
 }
 ```
 
-See [Inspector Data Binding](./inspector-data-binding) for the full reference of all input types (`TextInput`, `ColorInput`, `Vector2Input`, `Vector3Input`, `SliderInput`, `CheckboxInput`, `ToggleInput`, `AssetInput`, and more).
+See [Behaviour Data Binding](./behaviour-data-binding/) for the full reference of all input types (`TextInput`, `ColorInput`, `Vector2Input`, `Vector3Input`, `SliderInput`, `CheckboxInput`, `ToggleInput`, `AssetInput`, and more).
 
 See [Accessing Components](./accessing-components) to read and mutate built-in components such as `PhysicsComponent`, `AudioComponent`, `AnimationComponent`, `LightComponent`, and `MaterialComponent` from script.
 

package/dist/docs/guide/behaviour-data-binding/asset-input.md

@@ -0,0 +1,54 @@
+# AssetInput
+
+A file picker that lets the user select an asset from the project's `assets/` folder. The inspector renders a file browser button showing the selected filename.
+
+**Runtime value:** `{ path: string; type: string }` — read `field.path`.
+
+![AssetInput inspector control](/images/behaviour-data-binding/asset-input.png)
+
+## Declaration
+
+Provide the `type` string to categorize the asset. Set `path` to an empty string for "no file selected".
+
+```ts
+import { Behaviour, type AssetInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    clip:  { path: "", type: "audio" } as AssetInput,
+    model: { path: "", type: "model" } as AssetInput,
+    video: { path: "", type: "video" } as AssetInput,
+    texture: { path: "", type: "image" } as AssetInput,
+  };
+}
+```
+
+> [!IMPORTANT]
+> Do **not** use `type: "texture"` or `type: "texturemap"` — the inspector treats those as a legacy URL text field rather than the asset file picker. Use `"image"` instead for image/texture assets.
+
+## Runtime usage
+
+Read the `.path` property. Guard for an empty string (no file selected):
+
+```ts
+init() {
+  const path = this.data.clip.path;
+  if (!path) return; // no file selected in the inspector
+  console.log(path); // e.g. "./assets/sounds/click.mp3"
+}
+```
+
+## Common `type` values
+
+| `type` | Asset kind |
+| --- | --- |
+| `"audio"` | Audio files (mp3, wav, ogg, …) |
+| `"image"` | Image files (png, jpg, webp, …) |
+| `"model"` | 3D model files (glb, gltf, …) |
+| `"video"` | Video files (mp4, webm, …) |
+
+## Notes
+
+- The `type` string is for categorization only — it has no effect at runtime.
+- `path` is relative to the project root (e.g. `"./assets/audio/click.mp3"`).
+- `AssetInput` provides the path only. Load the asset yourself at runtime if needed.

package/dist/docs/guide/behaviour-data-binding/checkbox-input.md

@@ -0,0 +1,38 @@
+# CheckboxInput
+
+A checkbox. The inspector renders a standard checkbox control.
+
+**Runtime value:** `{ type: "checkbox"; value: boolean }` — read `.value`
+
+![CheckboxInput inspector control](/images/behaviour-data-binding/checkbox-input.png)
+
+## Declaration
+
+Declare with a `type: "checkbox"` envelope and an initial `value`:
+
+```ts
+import { Behaviour, type CheckboxInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    visible:    { type: "checkbox", value: true }  as CheckboxInput,
+    castShadow: { type: "checkbox", value: false } as CheckboxInput,
+  };
+}
+```
+
+## Runtime usage
+
+Read the `.value` property:
+
+```ts
+onUpdate() {
+  if (!this.data.visible.value) return;
+  // ... rest of update logic
+}
+```
+
+## Notes
+
+- Use `CheckboxInput` for property-style options (e.g. "Cast shadow", "Visible") and [`ToggleInput`](./toggle-input) for simple on/off feature flags.
+- `ToggleInput` is a plain `boolean` and requires no envelope — use it when you don't need the checkbox visual.

package/dist/docs/guide/behaviour-data-binding/color-input.md

@@ -0,0 +1,38 @@
+# ColorInput
+
+A color picker field. The inspector renders a swatch that opens a full color picker on click.
+
+**Runtime value:** `string` (hex, e.g. `"#ff0000"`)
+
+![ColorInput inspector control](/images/behaviour-data-binding/color-input.png)
+
+## Declaration
+
+```ts
+import { Behaviour, type ColorInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    tint:     "#ffffff" as ColorInput,
+    emissive: "#000000" as ColorInput,
+  };
+}
+```
+
+## Runtime usage
+
+Use the value directly as a hex string:
+
+```ts
+import * as THREE from "three";
+
+init() {
+  const color = new THREE.Color(this.data.tint);
+  // apply to a material, light, etc.
+}
+```
+
+## Notes
+
+- Value must be a valid hex color string (`#rgb`, `#rrggbb`, or `#rrggbbaa`) — the inspector detects the format automatically and renders the color picker.
+- Alpha is not included in the default 6-digit form — use a separate `FloatInput` if you need opacity control.

package/dist/docs/guide/behaviour-data-binding/component-input.md

@@ -0,0 +1,79 @@
+# ComponentInput
+
+An entity + component picker. The inspector renders an entity dropdown and, once an entity is selected, a component-kind filter. Use this when you need direct access to a specific component on another entity.
+
+**Runtime value:** `{ type: "component"; componentKind?: ComponentKind; value: Component | null }` — read `field.value`
+
+![ComponentInput inspector control](/images/behaviour-data-binding/component-input.png)
+
+## Declaration
+
+Set `componentKind` to pre-filter the picker to a specific component type. Omit it to allow any component.
+
+```ts
+import { Behaviour, type ComponentInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    cam:   { type: "component", componentKind: "CameraComponent", value: null } as ComponentInput,
+    audio: { type: "component", componentKind: "AudioComponent",  value: null } as ComponentInput,
+  };
+}
+```
+
+## Runtime usage
+
+At runtime, `.value` is resolved to the **live component instance**. Cast to the concrete class for full TypeScript autocompletion. Always guard for `null`:
+
+```ts
+import {
+  Behaviour,
+  CameraComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class FovReader extends Behaviour {
+  data = {
+    camera: { type: "component", componentKind: "CameraComponent", value: null } as ComponentInput,
+  };
+
+  onUpdate() {
+    const cam = this.data.camera.value as CameraComponent | null;
+    if (!cam) return; // no component assigned
+
+    console.log(cam.fov); // current field of view in degrees
+  }
+}
+```
+
+## Mutating the component
+
+Mutate the instance directly — the system that owns the component picks up changes next frame:
+
+```ts
+import {
+  Behaviour,
+  CameraComponent,
+  type ComponentInput,
+  type FloatInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class FovAnimator extends Behaviour {
+  data = {
+    camera:    { type: "component", componentKind: "CameraComponent", value: null } as ComponentInput,
+    targetFov: 90 as FloatInput,
+    speed:     30 as FloatInput,
+  };
+
+  onUpdate() {
+    const cam = this.data.camera.value as CameraComponent | null;
+    if (!cam) return;
+
+    // Lerp the field of view toward targetFov
+    cam.fov += (this.data.targetFov - cam.fov) * this.data.speed * this.deltaTime;
+  }
+}
+```
+
+> [!TIP]
+> Always cast to the concrete component type (e.g. `as CameraComponent | null`) for full autocompletion and always guard the null case — the field is `null` until the user picks both an entity and a component in the inspector.

package/dist/docs/guide/behaviour-data-binding/dropdown-input.md

@@ -0,0 +1,53 @@
+# DropdownInput
+
+A select dropdown. The inspector renders a menu populated from the `options` array.
+
+**Runtime value:** `{ options: DropdownOption[]; value: string }` — read `field.value`
+
+![DropdownInput inspector control](/images/behaviour-data-binding/dropdown-input.png)
+
+## Declaration
+
+Provide the full object including `options` and the initial selected `value`. The editor reads `options` to build the dropdown.
+
+```ts
+import { Behaviour, type DropdownInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    axis: {
+      value: "y",
+      options: [
+        { label: "X", value: "x" },
+        { label: "Y", value: "y" },
+        { label: "Z", value: "z" },
+      ],
+    } as DropdownInput,
+    blendMode: {
+      value: "normal",
+      options: [
+        { label: "Normal",   value: "normal" },
+        { label: "Additive", value: "additive" },
+        { label: "Multiply", value: "multiply" },
+      ],
+    } as DropdownInput,
+  };
+}
+```
+
+## Runtime usage
+
+Read the `.value` property. Cast to a union type for TypeScript narrowing:
+
+```ts
+onUpdate() {
+  const axis = this.data.axis.value as "x" | "y" | "z";
+  this.transform.rotation[axis] += 0.01;
+}
+```
+
+## Notes
+
+- Always include the full `options` array in the inline default — the editor needs it to render the dropdown.
+- `label` is what the user sees; `value` is what you read at runtime.
+- The initial `value` must match one of the option `value` strings.

package/dist/docs/guide/behaviour-data-binding/entity-input.md

@@ -0,0 +1,100 @@
+# EntityInput
+
+An entity picker. The inspector renders a dropdown populated with all named entities in the scene.
+
+**Runtime value:** `{ type: "entity"; value: WorldEntityView | null }` — read `field.value`
+
+![EntityInput inspector control](/images/behaviour-data-binding/entity-input.png)
+
+## Declaration
+
+```ts
+import { Behaviour, type EntityInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    target: { type: "entity", value: null } as EntityInput,
+  };
+}
+```
+
+## Runtime usage
+
+At runtime, `.value` is resolved to a **`WorldEntityView`** — not a raw ID. Always guard for `null` (no entity selected):
+
+```ts
+import { type WorldEntityView } from "@relu-interactives/spatial-ecs";
+
+onUpdate() {
+  const target = this.data.target.value as WorldEntityView | null;
+  if (!target) return; // no entity assigned in the inspector
+}
+```
+
+## WorldEntityView shape
+
+```ts
+type WorldEntityView = {
+  name: string;                   // entity name from NameComponent
+  entityId: number;               // runtime entity ID
+  type: string;                   // entity type ("mesh", "camera", "light", …)
+  object: THREE.Object3D | null;  // live three.js scene object
+  components: Component[];        // all components attached to this entity
+};
+```
+
+## Reading entity data
+
+```ts
+onUpdate() {
+  const target = this.data.target.value as WorldEntityView | null;
+  if (!target) return;
+
+  // Name and ID
+  console.log(target.name);     // e.g. "Camera"
+  console.log(target.entityId); // runtime numeric ID
+
+  // Access the three.js object directly
+  const obj = target.object;
+  if (obj) {
+    console.log(obj.position); // THREE.Vector3
+  }
+}
+```
+
+## Moving another entity from a script
+
+Use the entity's `components` array to find and mutate a specific component:
+
+```ts
+import {
+  Behaviour,
+  TransformComponent,
+  type EntityInput,
+  type WorldEntityView,
+  type FloatInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Mover extends Behaviour {
+  data = {
+    target: { type: "entity", value: null } as EntityInput,
+    speed:  5 as FloatInput,
+  };
+
+  onUpdate() {
+    const target = this.data.target.value as WorldEntityView | null;
+    if (!target) return;
+
+    const transform = target.components.find(
+      (c) => c instanceof TransformComponent,
+    ) as TransformComponent | undefined;
+
+    if (transform) {
+      transform.position.x += this.data.speed * this.deltaTime;
+    }
+  }
+}
+```
+
+> [!TIP]
+> Always guard with `if (!target) return;` — the field is `null` until the user picks an entity in the inspector, and may be `null` in freshly opened scenes.

package/dist/docs/guide/behaviour-data-binding/float-input.md

@@ -0,0 +1,35 @@
+# FloatInput
+
+A numeric input field. The inspector renders a number input that the user can type into or scrub with a drag.
+
+**Runtime value:** `number`
+
+![Floating input inspector](/images/behaviour-data-binding/float-input.png)
+
+## Declaration
+
+```ts
+import { Behaviour, type FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    speed: 1 as FloatInput,
+    mass:  0.5 as FloatInput,
+  };
+}
+```
+
+## Runtime usage
+
+Use the value directly as a `number`:
+
+```ts
+onUpdate() {
+  this.transform.rotation.y += this.data.speed * this.deltaTime;
+}
+```
+
+## Notes
+
+- Supports any finite `number` — positive, negative, or fractional.
+- Use [`SliderInput`](./slider-input) when you want to clamp the value to a min/max range.