@relu-interactives/spatial-ecs 0.2.12 → 0.2.14

package/dist/docs/guide/inspector-data-binding.md

@@ -1,367 +0,0 @@
-# Inspector 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 reference
-
-| Type | Import | Inspector control | Runtime value |
-| --- | --- | --- | --- |
-| `FloatInput` | ✓ | Number input | `number` |
-| `TextInput` | ✓ | Text input | `string` |
-| `ColorInput` | ✓ | Color picker | `string` (hex, e.g. `"#ff0000"`) |
-| `Vector2Input` | ✓ | XY number pair | `{ x: number; y: number }` |
-| `Vector3Input` | ✓ | XYZ number triple | `{ x: number; y: number; z: number }` |
-| `SliderInput` | ✓ | Range slider | `{ min, max, step, value }` (read `field.value` at runtime) |
-| `DropdownInput` | ✓ | Select dropdown | `{ options: DropdownOption[]; value: string }` (read `field.value`) |
-| `CheckboxInput` | ✓ | Checkbox | `boolean` |
-| `ToggleInput` | ✓ | Toggle switch | `boolean` |
-| `AssetInput` | ✓ | Asset file picker | `{ path: string; type: string }` — read `field.path`; `.value` is always `null` |
-| `EntityInput` | ✓ | Entity picker | `{ type: "entity"; value: WorldEntityView \| null }` — read `field.value` |
-| `ComponentInput` | ✓ | 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: true as CheckboxInput,
-    texture: { path: "", type: "texture" } as AssetInput,
-    target: { type: "entity", value: null } as EntityInput,
-    camera: { type: "component", componentKind: "Camera", value: null } as ComponentInput,
-  };
-}
-```
-
-## Reading values at runtime
-
-Most types map directly to their underlying primitive. The exceptions are `SliderInput`, `DropdownInput`, `AssetInput`, `EntityInput`, and `ComponentInput`, which are objects — read the nested value:
-
-```ts
-export default class Demo extends Behaviour {
-  data = {
-    speed:   1 as FloatInput,
-    active:  true as ToggleInput,
-    range:   { min: 0, max: 1, step: 0.1, value: 0.8 } as SliderInput,
-    axis:    { value: "y", options: [{ label: "X", value: "x" }, { label: "Y", value: "y" }, { label: "Z", value: "z" }] } as DropdownInput,
-    texture: { path: "", type: "texture" } as AssetInput,
-    target: { type: "entity", value: null } as EntityInput,
-    camera: { type: "component", componentKind: "Camera", value: null } as ComponentInput,
-  };
-
-  onUpdate() {
-    // FloatInput / TextInput / ColorInput / CheckboxInput / ToggleInput
-    // → use directly
-    this.transform.rotation.y += this.data.speed * this.deltaTime;
-    const isOn = this.data.active;
-
-    // SliderInput → read .value
-    const volume = this.data.range.value;
-
-    // DropdownInput → read .value
-    const axis = this.data.axis.value as "x" | "y" | "z";
-    this.transform.rotation[axis] += this.data.speed * this.deltaTime;
-
-    // AssetInput → read .path (see AssetInput section below)
-    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;
-  }
-}
-```
-
-## EntityInput — picking and using scene entities
-
-`EntityInput` lets the editor user pick any entity from the scene. Declare it with `{ type: "entity", value: null }` as the default (no entity selected).
-
-```ts
-import {
-  Behaviour,
-  type EntityInput,
-} from "@relu-interactives/spatial-ecs";
-
-export default class Follower extends Behaviour {
-  data = {
-    target: { type: "entity", value: null } as EntityInput,
-  };
-}
-```
-
-At runtime, `this.data.target.value` is resolved to a **`WorldEntityView`** — not a raw ID. You can import and use this type directly:
-
-```ts
-import { type WorldEntityView } from "@relu-interactives/spatial-ecs";
-```
-
-`WorldEntityView` has the following shape:
-
-```ts
-type WorldEntityView = {
-  name: string;       // entity name from the 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;  // no entity assigned in the inspector
-
-  // 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 `getEntity()` on `WorldEntityView` to get the entity's transform and mutate it:
-
-```ts
-import {
-  Behaviour,
-  TransformComponent,
-  type EntityInput,
-  type WorldEntityView,
-} 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;
-
-    // Find the TransformComponent on the picked entity
-    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 new scenes.
-
-## ComponentInput — picking and using a specific component
-
-`ComponentInput` lets the user pick an entity **and** a specific component kind from that entity. Use this when you want to read or drive a particular component (e.g. a `CameraComponent`, `AudioComponent`, or `AnimationComponent`).
-
-```ts
-import {
-  Behaviour,
-  type ComponentInput,
-} from "@relu-interactives/spatial-ecs";
-
-export default class CameraController extends Behaviour {
-  data = {
-    cam: { type: "component", componentKind: "CameraComponent", value: null } as ComponentInput,
-  };
-}
-```
-
-At runtime, `this.data.cam.value` is resolved to the **live component instance** — the actual class instance that the ECS manages each frame.
-
-### Reading component properties
-
-```ts
-import {
-  Behaviour,
-  CameraComponent,
-  type ComponentInput,
-} 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,
-  };
-
-  onUpdate() {
-    const cam = this.data.camera.value as CameraComponent | null;
-    if (!cam) return;  // no component assigned
-
-    // Read a property
-    console.log(cam.fov); // current field of view in degrees
-  }
-}
-```
-
-### Changing component properties
-
-Mutate the instance directly — the system that owns the component will pick up the change 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]
-> Cast the resolved value to the concrete component type (e.g. `as CameraComponent | null`) to get full TypeScript autocompletion on its properties. Always guard the null case — the field is `null` until the user picks both an entity and a component in the inspector.
-
-## AssetInput — referencing project assets
-
-`AssetInput` exposes a file picker in the inspector. The user selects a file from the project's `assets/` folder. The field stores the relative path to that file.
-
-```ts
-import {
-  Behaviour,
-  type AssetInput,
-} from "@relu-interactives/spatial-ecs";
-
-export default class AudioPlayer extends Behaviour {
-  data = {
-    clip: { path: "", type: "audio" } as AssetInput,
-  };
-}
-```
-
-At runtime, **`this.data.clip.value` is always `null`** — `AssetInput` does not resolve to a loaded asset object. Use `this.data.clip.path` to get the relative file path, then load the asset yourself if needed:
-
-```ts
-onUpdate() {
-  const path = this.data.clip.path;
-  if (!path) return;
-
-  // path is the relative asset path, e.g. "./assets/sounds/click.mp3"
-  console.log(path);
-}
-```
-
-The `type` field on the default value (`"audio"`, `"texture"`, `"model"`, etc.) is used by the editor to filter the file picker to relevant asset types.
-
-## 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;
-  }
-}
-```