@relu-interactives/spatial-ecs 0.2.12 → 0.2.14

package/dist/docs/guide/behaviour-data-binding/index.md

@@ -0,0 +1,158 @@
+# Behaviour Data Binding
+
+The `ScriptComponent.data` field is the bridge between the editor inspector and your `Behaviour` subclass. Anything you place on `data` is:
+
+1. Saved with the project.
+2. Rendered as a live inspector control in the editor.
+3. Available at runtime as `this.data` inside the script.
+
+The **type annotation** on each field tells the editor which control to render. Import the input types from `@relu-interactives/spatial-ecs` and use them as `as` casts on the initial values in your data object.
+
+## Input types
+
+| Type | Inspector control | Runtime value |
+| --- | --- | --- |
+| [`FloatInput`](./float-input) | Number input | `number` |
+| [`TextInput`](./text-input) | Text input | `string` |
+| [`ColorInput`](./color-input) | Color picker | `string` (hex, e.g. `"#ff0000"`) |
+| [`Vector2Input`](./vector2-input) | XY number pair | `{ x: number; y: number }` |
+| [`Vector3Input`](./vector3-input) | XYZ number triple | `{ x: number; y: number; z: number }` |
+| [`SliderInput`](./slider-input) | Range slider | `{ min, max, step, value }` — read `field.value` at runtime |
+| [`DropdownInput`](./dropdown-input) | Select dropdown | `{ options: DropdownOption[]; value: string }` — read `field.value` |
+| [`CheckboxInput`](./checkbox-input) | Checkbox | `{ type: "checkbox"; value: boolean }` — read `.value` |
+| [`ToggleInput`](./toggle-input) | Toggle switch | `boolean` |
+| [`AssetInput`](./asset-input) | Asset file picker | `{ path: string; type: string }` — read `field.path` |
+| [`EntityInput`](./entity-input) | Entity picker | `{ type: "entity"; value: WorldEntityView \| null }` — read `field.value` |
+| [`ComponentInput`](./component-input) | Entity + component picker | `{ type: "component"; componentKind?: ComponentKind; value: Component \| null }` — read `field.value` |
+
+## Declaring inspector fields
+
+Import the input types you need alongside `Behaviour`, then declare them directly on the `data` class property using `as` casts:
+
+```ts
+import {
+  Behaviour,
+  type FloatInput,
+  type TextInput,
+  type ColorInput,
+  type Vector2Input,
+  type Vector3Input,
+  type SliderInput,
+  type DropdownInput,
+  type CheckboxInput,
+  type ToggleInput,
+  type AssetInput,
+  type EntityInput,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    speed:   1 as FloatInput,
+    label:   "Hello" as TextInput,
+    tint:    "#ffffff" as ColorInput,
+    offset:  { x: 0, y: 0 } as Vector2Input,
+    origin:  { x: 0, y: 0, z: 0 } as Vector3Input,
+    range:   { min: 0, max: 10, step: 0.1, value: 5 } as SliderInput,
+    axis: {
+      value: "y",
+      options: [
+        { label: "X", value: "x" },
+        { label: "Y", value: "y" },
+        { label: "Z", value: "z" },
+      ],
+    } as DropdownInput,
+    active:  true as ToggleInput,
+    visible: { type: "checkbox", value: true } as CheckboxInput,
+    texture: { path: "", type: "image" }   as AssetInput,
+    target:  { type: "entity", value: null } as EntityInput,
+    camera:  { type: "component", componentKind: "Camera", value: null } as ComponentInput,
+  };
+}
+```
+
+Each field in `data` maps directly to a live inspector control. The script above produces the following inspector panel:
+
+![Behaviour inspector controls](/images/behaviour-data-binding/behavior-inspector.gif)
+
+## Reading values at runtime
+
+Most types map directly to their underlying primitive. The exceptions are `SliderInput`, `DropdownInput`, `AssetInput`, `EntityInput`, and `ComponentInput` — read the nested value:
+
+```ts
+onUpdate() {
+  // Primitives — use directly
+  this.transform.rotation.y += this.data.speed * this.deltaTime;
+
+  // SliderInput → read .value
+  const volume = this.data.range.value;
+
+  // DropdownInput → read .value
+  const axis = this.data.axis.value as "x" | "y" | "z";
+
+  // AssetInput → read .path
+  const src = this.data.texture.path;
+
+  // EntityInput → cast to WorldEntityView | null
+  const entity = this.data.target.value as WorldEntityView | null;
+
+  // ComponentInput → cast to the concrete component type
+  const cam = this.data.camera.value as CameraComponent | null;
+}
+```
+
+## Practical example — spinner with inspector controls
+
+```ts
+import {
+  Behaviour,
+  type FloatInput,
+  type ColorInput,
+  type DropdownInput,
+  type ToggleInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Spinner extends Behaviour {
+  data = {
+    speed:   1 as FloatInput,
+    color:   "#00aaff" as ColorInput,
+    enabled: true as ToggleInput,
+    axis: {
+      value: "y",
+      options: [
+        { label: "X", value: "x" },
+        { label: "Y", value: "y" },
+        { label: "Z", value: "z" },
+      ],
+    } as DropdownInput,
+  };
+
+  onUpdate() {
+    if (!this.data.enabled) return;
+    const axis = this.data.axis.value as "x" | "y" | "z";
+    this.transform.rotation[axis] += this.data.speed * this.deltaTime;
+  }
+}
+```
+
+## Defaulting fields
+
+Defaults are set inline on the `data` property. When a saved project reloads, saved values take precedence — the inline defaults only apply when a field has never been saved. This means:
+
+- Adding a new field with an inline default is safe — existing saves will pick it up on next load.
+- The inspector always has a valid initial value when the script is first attached.
+- For `SliderInput` and `DropdownInput`, the full object (including `options`) must be present in the inline default — the editor reads `options` to build the control.
+
+## Persistence
+
+`ScriptComponent.data` is serialized and saved with the project. On reload, your `data` payload is restored verbatim. If you rename or restructure a field, migrate it inside `init()`:
+
+```ts
+init() {
+  // migrate renamed field
+  if ((this.data as any).oldSpeed !== undefined) {
+    this.data.speed = (this.data as any).oldSpeed;
+    delete (this.data as any).oldSpeed;
+  }
+}
+```

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

@@ -0,0 +1,37 @@
+# SliderInput
+
+A range slider. The inspector renders a horizontal slider with the current value displayed alongside it.
+
+**Runtime value:** `{ min: number; max: number; step: number; value: number }` — read `field.value`
+
+![SliderInput inspector control](/images/behaviour-data-binding/slider-input.png)
+
+## Declaration
+
+Provide the full object including `min`, `max`, `step`, and the initial `value`. The editor reads `min`/`max`/`step` to configure the slider control.
+
+```ts
+import { Behaviour, type SliderInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    volume:  { min: 0, max: 1, step: 0.01, value: 0.8 } as SliderInput,
+    quality: { min: 1, max: 10, step: 1, value: 5 } as SliderInput,
+  };
+}
+```
+
+## Runtime usage
+
+Read the `.value` property — the other fields (`min`, `max`, `step`) are for the editor control only:
+
+```ts
+onUpdate() {
+  const volume = this.data.volume.value; // number between 0 and 1
+}
+```
+
+## Notes
+
+- Always include `min`, `max`, and `step` in the inline default — the editor needs them to render the control.
+- `step` can be fractional for smooth sliders (e.g. `0.01`).

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

@@ -0,0 +1,35 @@
+# TextInput
+
+A single-line text field. The inspector renders a plain text input.
+
+**Runtime value:** `string`
+
+![TextInput inspector control](/images/behaviour-data-binding/text-input.png)
+
+## Declaration
+
+```ts
+import { Behaviour, type TextInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    label:   "Hello world" as TextInput,
+    apiKey:  "" as TextInput,
+  };
+}
+```
+
+## Runtime usage
+
+Use the value directly as a `string`:
+
+```ts
+init() {
+  console.log(this.data.label); // "Hello world"
+}
+```
+
+## Notes
+
+- The default value is what the user sees when the script is first attached.
+- Useful for URLs, display strings, or any freeform text parameter.

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

@@ -0,0 +1,36 @@
+# ToggleInput
+
+An on/off toggle switch. The inspector renders a pill-shaped toggle.
+
+**Runtime value:** `boolean`
+
+![ToggleInput inspector control](/images/behaviour-data-binding/toggle-input.png)
+
+## Declaration
+
+```ts
+import { Behaviour, type ToggleInput } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    enabled:   true as ToggleInput,
+    loopAudio: false as ToggleInput,
+  };
+}
+```
+
+## Runtime usage
+
+Use the value directly as a `boolean`:
+
+```ts
+onUpdate() {
+  if (!this.data.enabled) return;
+  // ... rest of update logic
+}
+```
+
+## Notes
+
+- Prefer `ToggleInput` for feature flags (e.g. "Enabled", "Loop") and [`CheckboxInput`](./checkbox-input) for property-style options.
+- Both types resolve to a plain `boolean` at runtime.

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

@@ -0,0 +1,36 @@
+# Vector2Input
+
+An XY number pair. The inspector renders two side-by-side number inputs labelled **X** and **Y**.
+
+**Runtime value:** `{ x: number; y: number }`
+
+![Vector2Input inspector control](/images/behaviour-data-binding/vector2-input.png)
+
+## Declaration
+
+```ts
+import { Behaviour, type Vector2Input } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    offset:   { x: 0, y: 0 } as Vector2Input,
+    uvScale:  { x: 1, y: 1 } as Vector2Input,
+  };
+}
+```
+
+## Runtime usage
+
+Read `x` and `y` directly:
+
+```ts
+onUpdate() {
+  this.transform.position.x += this.data.offset.x * this.deltaTime;
+  this.transform.position.y += this.data.offset.y * this.deltaTime;
+}
+```
+
+## Notes
+
+- Suitable for screen-space positions, UV offsets, or any 2D vector parameter.
+- Use [`Vector3Input`](./vector3-input) for 3D world-space values.

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

@@ -0,0 +1,41 @@
+# Vector3Input
+
+An XYZ number triple. The inspector renders three side-by-side number inputs labelled **X**, **Y**, and **Z**.
+
+**Runtime value:** `{ x: number; y: number; z: number }`
+
+![Vector3Input inspector control](/images/behaviour-data-binding/vector3-input.png)
+
+## Declaration
+
+```ts
+import { Behaviour, type Vector3Input } from "@relu-interactives/spatial-ecs";
+
+export default class Demo extends Behaviour {
+  data = {
+    spawnPoint: { x: 0, y: 1, z: 0 } as Vector3Input,
+    force:      { x: 0, y: 0, z: 0 } as Vector3Input,
+  };
+}
+```
+
+## Runtime usage
+
+Read `x`, `y`, and `z` directly:
+
+```ts
+import * as THREE from "three";
+
+init() {
+  const point = new THREE.Vector3(
+    this.data.spawnPoint.x,
+    this.data.spawnPoint.y,
+    this.data.spawnPoint.z,
+  );
+}
+```
+
+## Notes
+
+- Ideal for world-space positions, directions, or scale factors.
+- Values are plain numbers — no automatic unit conversion is applied.

package/dist/docs/guide/components/parent-id.md

@@ -103,6 +103,31 @@ export default class Example extends Behaviour {
 }
 ```
 
+### Navigate the hierarchy with World methods
+
+Instead of querying the `ParentId` component directly, use `world.getEntitiesParent` and `world.getEntitiesChildren` for convenient hierarchy traversal:
+
+```typescript
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class HierarchyLogger extends Behaviour {
+  protected init() {
+    // Get parent entity
+    const parent = this.world.getEntitiesParent(this.entityId);
+    if (parent) {
+      console.log(`Parent: ${parent.name} (ID: ${parent.entityId})`);
+    }
+
+    // Get all children
+    const children = this.world.getEntitiesChildren(this.entityId);
+    console.log(`${children.length} child(ren):`);
+    for (const child of children) {
+      console.log(`  - ${child.name} (ID: ${child.entityId})`);
+    }
+  }
+}
+```
+
 ::: tip ObjectManagementSystem
 Do not call `THREE.Object3D.add` / `remove` directly to reparent. Write to `ParentId.value` instead — the `ObjectManagementSystem` reads this every frame and reconciles the scene graph. This keeps the ECS hierarchy state consistent with the three.js scene graph.
 :::

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