@relu-interactives/spatial-ecs 0.2.2

package/dist/docs/guide/components/_sidebar.json

@@ -0,0 +1,78 @@
+[
+  {
+    "text": "Animation",
+    "link": "/guide/components/animation"
+  },
+  {
+    "text": "Audio",
+    "link": "/guide/components/audio"
+  },
+  {
+    "text": "Camera",
+    "link": "/guide/components/camera"
+  },
+  {
+    "text": "Entity Type",
+    "link": "/guide/components/entity-type"
+  },
+  {
+    "text": "Image",
+    "link": "/guide/components/image"
+  },
+  {
+    "text": "Image Target",
+    "link": "/guide/components/image-target"
+  },
+  {
+    "text": "Image Target Anchor",
+    "link": "/guide/components/image-target-anchor"
+  },
+  {
+    "text": "Light",
+    "link": "/guide/components/light"
+  },
+  {
+    "text": "Material",
+    "link": "/guide/components/material"
+  },
+  {
+    "text": "Mesh",
+    "link": "/guide/components/mesh"
+  },
+  {
+    "text": "Mesh Geometry",
+    "link": "/guide/components/mesh-geometry"
+  },
+  {
+    "text": "Model",
+    "link": "/guide/components/model"
+  },
+  {
+    "text": "Name",
+    "link": "/guide/components/name"
+  },
+  {
+    "text": "Object3D Reference",
+    "link": "/guide/components/object3d-ref"
+  },
+  {
+    "text": "Parent",
+    "link": "/guide/components/parent-id"
+  },
+  {
+    "text": "Script",
+    "link": "/guide/components/script"
+  },
+  {
+    "text": "Sprite",
+    "link": "/guide/components/sprite"
+  },
+  {
+    "text": "Transform",
+    "link": "/guide/components/transform"
+  },
+  {
+    "text": "Video",
+    "link": "/guide/components/video"
+  }
+]

package/dist/docs/guide/components/animation.md

@@ -0,0 +1,171 @@
+# Animation
+
+Animation catalog and runtime state for an entity. Combines clips imported from a model with externally added clips, exposes a state machine for named transitions, and is queried each frame by the animation system to advance mixer time.  Use the `addState` / `switchState` helpers rather than mutating the state machine directly so the animation system observes transitions.
+
+> **Managed by:** [`AnimationSystem`](../systems/animation-system)
+
+## Editor inspector
+
+![Animation inspector](/images/components/Animation.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `clips` | `THREE.AnimationClip[]` | Combined ordered list of clips (model + external) currently loaded. |
+| `clipCatalog` | `AnimationClipCatalogEntry[]` | Per-clip metadata used by the inspector. |
+| `availableClips` | `string[]` | Display names of clips available for state-machine bindings. |
+| `externalClipSources` | `string[]` | URLs/paths of external clip sources (saved with the project). |
+| `paused` | `boolean` | Whether playback is currently paused. |
+| `reverse` | `boolean` | Play the active clip in reverse. |
+| `timeScale` | `number` | Playback speed multiplier (`1` = real-time). |
+| `crossFadeDuration` | `number` | Default cross-fade duration in seconds when switching states. |
+| `states` | `AnimationStateMachine[]` | All state-machine entries authored on this entity. |
+| `active` | `AnimationStateMachine \| null` | State currently being played, or `null` if none. |
+| `activeStateName` | `string \| null` | Name of the `active` state, or `null` if none. |
+| `stateManager` | `AnimationStateManager` | Manager that drives state transitions; mutate via `addState`/`switchState`. |
+
+## API reference
+
+- Class: [`AnimationComponent`](../../api/components/classes/AnimationComponent.md)
+- Source: [`core/components/Animation.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Animation.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const anim = this.getComponent(AnimationComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Character");
+if (other) {
+  const anim = this.world.getComponent(other.entityId, AnimationComponent);
+}
+```
+:::
+
+### Switch states on keyboard input
+
+Transition between an idle and a walk state based on arrow-key input. The cross-fade duration is set from the inspector.
+
+```typescript
+import { Behaviour, AnimationComponent, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+import type { StringInput, FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class AnimationController extends Behaviour {
+  data = {
+    idleState: "Idle" as StringInput,
+    walkState: "Walk" as StringInput,
+    crossFadeDuration: 0.3 as FloatInput,
+  };
+
+  protected init() {
+    const anim = this.getComponent(AnimationComponent);
+    if (anim) {
+      anim.crossFadeDuration = this.data.crossFadeDuration;
+      anim.switchState(this.data.idleState);
+    }
+  }
+
+  protected onUpdate() {
+    const anim = this.getComponent(AnimationComponent);
+    if (!anim) return;
+
+    const moving =
+      this.world.getKey(KeyboardKeys.ArrowUp) || this.world.getKey(KeyboardKeys.ArrowDown);
+    const target = moving ? this.data.walkState : this.data.idleState;
+
+    if (anim.activeStateName !== target) {
+      anim.switchState(target);
+    }
+  }
+}
+```
+
+### Control playback speed and pause
+
+Drive `timeScale` and `paused` live from inspector fields, useful for slow-motion or freeze effects.
+
+```typescript
+import { Behaviour, AnimationComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput, BooleanInput } from "@relu-interactives/spatial-ecs";
+
+export default class AnimationSpeedDriver extends Behaviour {
+  data = {
+    timeScale: 1 as FloatInput,
+    paused: false as BooleanInput,
+  };
+
+  protected onUpdate() {
+    const anim = this.getComponent(AnimationComponent);
+    if (!anim) return;
+    anim.timeScale = this.data.timeScale;
+    anim.paused = this.data.paused;
+  }
+}
+```
+
+::: 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.
+:::
+
+### 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.
+
+```typescript
+import {
+  Behaviour,
+  AnimationComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetAnimation: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const anim = this.data.targetAnimation.value as AnimationComponent | null;
+    if (!anim) return;
+    // Use the live component instance.
+  }
+}
+```
+
+### Via `EntityInput` in the inspector
+
+Alternatively, pick an entity from the inspector using an `EntityInput` field and then read the component off that entity via `world.getComponent`:
+
+```typescript
+import {
+  Behaviour,
+  AnimationComponent,
+  type EntityInput,
+  type WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetEntity: { type: "entity", value: null } as unknown as EntityInput,
+  };
+
+  protected onUpdate() {
+    const entity = this.data.targetEntity.value as WorldEntityView | null;
+    if (!entity) return;
+
+    const anim = this.world.getComponent(
+      entity.entityId,
+      AnimationComponent,
+    ) as AnimationComponent | null;
+    if (!anim) return;
+    // Use the component on the picked entity.
+  }
+}
+```

package/dist/docs/guide/components/audio.md

@@ -0,0 +1,181 @@
+# Audio
+
+Plays an audio clip from `path`. Supports both global stereo (`positional: false`) and 3D positional audio with the configured distance model. Runtime fields (`object`, `audio`, `isPlaying`, `isPaused`) are recreated when the project loads and are never persisted to saved snapshots.
+
+> **Managed by:** [`AudioSystem`](../systems/audio-system)
+
+## Editor inspector
+
+![Audio inspector](/images/components/Audio.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Source URL or `localasset://` path of the audio file. |
+| `options` | `typeof DEFAULT_AUDIO_OPTIONS` | Playback options.  | Field | Default | Description | |---|---|---| | `autoplay` | `false` | Start playback as soon as the clip is loaded. | | `loop` | `false` | Loop playback indefinitely. | | `pitch` | `1` | Playback rate multiplier (`1` = normal speed/pitch). | | `volume` | `1` | Linear gain in `[0, 1]`. | | `positional` | `false` | When `true`, audio is spatialized using the entity's transform. | | `refDistance` | `1` | Distance at which volume is unattenuated (positional only). | | `distanceModel` | `"inverse"` | WebAudio distance model (`linear`, `inverse`, `exponential`). | | `rolloffFactor` | `1` | How quickly volume falls off past `refDistance`. | |
+| `object` | `THREE.Object3D \| null` | Live three.js object hosting the audio (a parented `Audio`/`PositionalAudio`). `null` until built. |
+| `audio` | `THREE.Audio<GainNode> \| THREE.PositionalAudio \| null` | Live three.js audio source. `null` until built. Recreated when the project loads. |
+| `isPlaying` | `boolean` | Whether the audio should be playing. Managed by `AudioSystem` in preview. Non-enumerable — not persisted to snapshots or save data. Set via `play` / `stop`. |
+| `isPaused` | `boolean` | Whether the audio is paused mid-playback (position is preserved). Non-enumerable — not persisted to snapshots or save data. Set via `pause` / `play` / `stop`. |
+
+## API reference
+
+- Class: [`AudioComponent`](../../api/components/classes/AudioComponent.md)
+- Source: [`core/components/Audio.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Audio.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const audio = this.getComponent(AudioComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("AmbientSpeaker");
+if (other) {
+  const audio = this.world.getComponent(other.entityId, AudioComponent);
+}
+```
+:::
+
+### Play / stop on key press
+
+Toggle audio playback when the player presses Space. Volume is exposed as an inspector field.
+
+```typescript
+import { Behaviour, AudioComponent, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class AudioController extends Behaviour {
+  data = {
+    volume: 1 as FloatInput,
+  };
+
+  protected init() {
+    const audio = this.getComponent(AudioComponent);
+    if (audio) audio.options.volume = this.data.volume;
+  }
+
+  protected onUpdate() {
+    const audio = this.getComponent(AudioComponent);
+    if (!audio) return;
+
+    // Keep volume in sync with the inspector slider
+    audio.options.volume = this.data.volume;
+
+    if (this.world.getKeyDown(KeyboardKeys.Space)) {
+      if (audio.isPlaying) {
+        audio.stop();
+      } else {
+        audio.play();
+      }
+    }
+  }
+}
+```
+
+### Proximity-triggered audio
+
+Start playing when the camera comes within a configurable range, and stop when it moves away.
+
+```typescript
+import { Behaviour, AudioComponent, TransformComponent, CameraComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class ProximityAudio extends Behaviour {
+  data = {
+    triggerDistance: 3 as FloatInput,
+  };
+
+  protected onUpdate() {
+    const audio = this.getComponent(AudioComponent);
+    if (!audio) return;
+
+    // Find the default camera entity
+    let cameraPos = { x: 0, y: 0, z: 0 };
+    for (const [id, cam] of this.world.query([CameraComponent])) {
+      if (cam.isDefault) {
+        const ct = this.world.getComponent(id, TransformComponent);
+        if (ct) cameraPos = ct.position;
+        break;
+      }
+    }
+
+    const dx = this.transform.position.x - cameraPos.x;
+    const dy = this.transform.position.y - cameraPos.y;
+    const dz = this.transform.position.z - cameraPos.z;
+    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (dist < this.data.triggerDistance && !audio.isPlaying) {
+      audio.play();
+    } else if (dist >= this.data.triggerDistance && audio.isPlaying) {
+      audio.stop();
+    }
+  }
+}
+```
+
+::: tip Playback methods
+Use `audio.play()`, `audio.pause()`, and `audio.stop()` rather than calling methods on `audio.audio` directly. These helpers update `isPlaying` / `isPaused` so the `AudioSystem` applies the correct THREE.js call in preview.
+:::
+
+### 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 `AudioComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  AudioComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetAudio: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const audio = this.data.targetAudio.value as AudioComponent | null;
+    if (!audio) return;
+    // Use the live component instance.
+  }
+}
+```
+
+### Via `EntityInput` in the inspector
+
+Alternatively, pick an entity from the inspector using an `EntityInput` field and then read the component off that entity via `world.getComponent`:
+
+```typescript
+import {
+  Behaviour,
+  AudioComponent,
+  type EntityInput,
+  type WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetEntity: { type: "entity", value: null } as unknown as EntityInput,
+  };
+
+  protected onUpdate() {
+    const entity = this.data.targetEntity.value as WorldEntityView | null;
+    if (!entity) return;
+
+    const audio = this.world.getComponent(
+      entity.entityId,
+      AudioComponent,
+    ) as AudioComponent | null;
+    if (!audio) return;
+    // Use the component on the picked entity.
+  }
+}
+```

package/dist/docs/guide/components/camera.md

@@ -0,0 +1,179 @@
+# Camera
+
+Camera entity state. Supports perspective and orthographic projections, a `3d` or `ar` runtime type, and an `isDefault` flag for the camera that the preview/editor renders through. Field-of-view, near/far, ortho frustum, and zoom are persisted; the live `THREE.Camera` is recreated when the project loads.
+
+> **Managed by:** [`CameraSyncSystem`](../systems/camera-sync-system)
+
+## Editor inspector
+
+![Camera inspector](/images/components/Camera.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `camera` | `THREE.Camera` | Live three.js camera. Recreated when the project loads to match `projection`. |
+| `type` | `CameraRuntimeType` | Runtime camera mode (`3d` or `ar`). |
+| `isDefault` | `boolean` | When `true`, this is the active rendering camera. Only one camera per scene should be the default. |
+| `projection` | `CameraProjection` | Active projection model (`perspective` or `orthographic`). |
+| `fov` | `number` | Vertical field of view in **degrees**. Used when `projection` is `perspective`. |
+| `near` | `number` | Near clip plane in world units. |
+| `far` | `number` | Far clip plane in world units. |
+| `left` | `number` | Left edge of the orthographic frustum (orthographic only). |
+| `right` | `number` | Right edge of the orthographic frustum (orthographic only). |
+| `top` | `number` | Top edge of the orthographic frustum (orthographic only). |
+| `bottom` | `number` | Bottom edge of the orthographic frustum (orthographic only). |
+| `zoom` | `number` | Zoom multiplier applied to the projection. |
+
+## API reference
+
+- Class: [`CameraComponent`](../../api/components/classes/CameraComponent.md)
+- Source: [`core/components/Camera.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Camera.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const cam = this.getComponent(CameraComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("CinematicCam");
+if (other) {
+  const cam = this.world.getComponent(other.entityId, CameraComponent);
+}
+```
+:::
+
+### Zoom with a hold key
+
+Smoothly lerp the field-of-view toward a zoomed-in value while Shift is held, then lerp back out.
+
+```typescript
+import { Behaviour, CameraComponent, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class CameraZoom extends Behaviour {
+  data = {
+    normalFov: 60 as FloatInput,
+    zoomedFov: 30 as FloatInput,
+    zoomSpeed: 5 as FloatInput,
+  };
+
+  protected onUpdate() {
+    const cam = this.getComponent(CameraComponent);
+    if (!cam) return;
+
+    const targetFov = this.world.getKey(KeyboardKeys.ShiftLeft)
+      ? this.data.zoomedFov
+      : this.data.normalFov;
+
+    cam.fov += (targetFov - cam.fov) * this.data.zoomSpeed * this.deltaTime;
+
+    // Propagate the change to the live THREE.PerspectiveCamera
+    const live = cam.camera as {
+      isPerspectiveCamera?: boolean;
+      fov?: number;
+      updateProjectionMatrix?(): void;
+    };
+    if (live.isPerspectiveCamera && live.updateProjectionMatrix) {
+      live.fov = cam.fov;
+      live.updateProjectionMatrix();
+    }
+  }
+}
+```
+
+### Orbit the camera around a point
+
+Rotate the camera entity's position around the scene origin at a configurable radius and height.
+
+```typescript
+import { Behaviour, CameraComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class OrbitCamera extends Behaviour {
+  data = {
+    radius: 5 as FloatInput,
+    height: 2 as FloatInput,
+    speed: 0.5 as FloatInput,
+  };
+
+  private elapsed = 0;
+
+  protected onUpdate() {
+    const cam = this.getComponent(CameraComponent);
+    if (!cam?.isDefault) return;
+
+    this.elapsed += this.deltaTime;
+    const angle = this.elapsed * this.data.speed;
+
+    this.transform.position.x = Math.sin(angle) * this.data.radius;
+    this.transform.position.y = this.data.height;
+    this.transform.position.z = Math.cos(angle) * this.data.radius;
+
+    // Always look toward the origin
+    this.transform.rotation.y = -angle;
+  }
+}
+```
+
+### 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 `CameraComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  CameraComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetCamera: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const cam = this.data.targetCamera.value as CameraComponent | null;
+    if (!cam) return;
+    // Use the live component instance.
+  }
+}
+```
+
+### Via `EntityInput` in the inspector
+
+Alternatively, pick an entity from the inspector using an `EntityInput` field and then read the component off that entity via `world.getComponent`:
+
+```typescript
+import {
+  Behaviour,
+  CameraComponent,
+  type EntityInput,
+  type WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetEntity: { type: "entity", value: null } as unknown as EntityInput,
+  };
+
+  protected onUpdate() {
+    const entity = this.data.targetEntity.value as WorldEntityView | null;
+    if (!entity) return;
+
+    const cam = this.world.getComponent(
+      entity.entityId,
+      CameraComponent,
+    ) as CameraComponent | null;
+    if (!cam) return;
+    // Use the component on the picked entity.
+  }
+}
+```