@relu-interactives/spatial-ecs 0.2.11 → 0.2.13

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/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/instanced-mesh.md

@@ -8,10 +8,7 @@ Use instanced meshes when you need tens, hundreds, or thousands of identical obj
 
 ## 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`
-:::
+![Instanced Mesh inspector](/images/components/instanced-mesh.png)
 
 ## Properties