@relu-interactives/spatial-ecs 0.2.16 → 0.2.20

package/dist/components/index.d.cts

@@ -1,4 +1,5 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as normalizePhysicsState } from '../Video-D4B-z74P.cjs';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BeuJ1xt5.cjs';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-B8yVI1tF.cjs';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BjwOBx81.cjs';
+export { P as PrefabInstance, a as PrefabNode } from '../index-LHLKpJhZ.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';

package/dist/components/index.d.ts

@@ -1,4 +1,5 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as normalizePhysicsState } from '../Video-Cym2C52L.js';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BeuJ1xt5.js';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-B9z5AtIf.js';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BjwOBx81.js';
+export { P as PrefabInstance, a as PrefabNode } from '../index-BBI2YdCu.js';
 import 'three';
 import '@dimforge/rapier3d-compat';

package/dist/components/index.js

@@ -1,4 +1,4 @@
-export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, ScriptComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, normalizePhysicsState } from '../chunk-FTIQQK62.js';
+export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, defaultMaterialValue, normalizePhysicsState } from '../chunk-Z6OMYEXU.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/docs/guide/accessing-components.md

@@ -10,7 +10,7 @@ getComponent<T extends Component>(componentClass: ComponentClass<T>): T | null
 
 Returns the component instance of the requested type attached to the **same entity** as the script, or `null` if the entity does not have that component. Always null-check the result — components are optional and may not be present on every object.
 
-The recommended pattern is to cache the reference in `onInit` so you avoid the lookup overhead every frame:
+The recommended pattern is to cache the reference in `init()` (called once before the first `onUpdate`) so you avoid the lookup overhead every frame:
 
 ```ts
 import { Behaviour } from "@relu-interactives/spatial-ecs";
@@ -19,7 +19,7 @@ import { PhysicsComponent } from "@relu-interactives/spatial-ecs/components";
 export default class Example extends Behaviour {
   private physics: PhysicsComponent | null = null;
 
-  onInit() {
+  protected init() {
     this.physics = this.getComponent(PhysicsComponent);
   }
 
@@ -76,7 +76,7 @@ export default class Jumper extends Behaviour {
 
   private physics: PhysicsComponent | null = null;
 
-  onInit() {
+  protected init() {
     this.physics = this.getComponent(PhysicsComponent);
   }
 
@@ -124,7 +124,7 @@ export default class SoundController extends Behaviour {
 
   private audio: AudioComponent | null = null;
 
-  onInit() {
+  protected init() {
     this.audio = this.getComponent(AudioComponent);
   }
 
@@ -180,7 +180,7 @@ export default class AnimationController extends Behaviour {
 
   private anim: AnimationComponent | null = null;
 
-  onInit() {
+  protected init() {
     this.anim = this.getComponent(AnimationComponent);
     if (this.anim) {
       this.anim.switchState(this.data.state.value);
@@ -234,7 +234,7 @@ export default class LightPulse extends Behaviour {
   private light: LightComponent | null = null;
   private t = 0;
 
-  onInit() {
+  protected init() {
     this.light = this.getComponent(LightComponent);
     if (this.light) {
       this.light.setValues({ color: this.data.color });
@@ -288,7 +288,7 @@ export default class MaterialSwap extends Behaviour {
 
   private mat: MaterialComponent | null = null;
 
-  onInit() {
+  protected init() {
     this.mat = this.getComponent(MaterialComponent);
   }
 
@@ -332,7 +332,7 @@ import { VideoComponent } from "@relu-interactives/spatial-ecs/components";
 export default class VideoController extends Behaviour {
   private video: VideoComponent | null = null;
 
-  onInit() {
+  protected init() {
     this.video = this.getComponent(VideoComponent);
   }
 
@@ -380,7 +380,7 @@ export default class RemoteControl extends Behaviour {
     const entity = this.world.getEntityByName("Sun");
     if (!entity) return;
 
-    const light = this.world.getComponent(entity.id, LightComponent);
+    const light = this.world.getComponent(entity.entityId, LightComponent);
     if (light) light.setValues({ intensity: 2 });
   }
 }

package/dist/docs/guide/camera-rigs.md

@@ -0,0 +1,525 @@
+# Camera Rigs
+
+Recipes for the three camera setups almost every experience needs: **orbit** (rotate around a target), **third-person follow**, and **first-person**. Each is a complete, working `Behaviour` script — copy it, attach it, and tune the inspector fields.
+
+## The pattern
+
+All camera rigs follow the same rules:
+
+1. **Attach the rig script to the camera entity** and drive `this.transform` — `CameraSyncSystem` keeps the live camera in sync. Never mutate `this.threeRef.object.position/rotation` on transform-synced entities; `TransformSyncSystem` overwrites raw Object3D transforms every frame.
+2. **Input comes from `this.world`** — `getKey` / `getKeyDown` (import `KeyboardKeys`), `getMouse("left")` / `getMouseDown`, `consumeMouseDelta()`, `consumeScrollDelta()`, `lockMousePointer()` / `unlockMousePointer()` / `isMousePointerLocked()`. There is no `world.input` object.
+3. **Angles are radians.** Own your yaw/pitch as private numbers and build positions/rotations from them — never read angles back out of a quaternion each frame (Euler extraction can gimbal-flip).
+4. **Position a camera on a sphere around its target** with spherical coordinates:
+   ```ts
+   x = target.x + distance * Math.sin(yaw) * Math.cos(pitch);
+   y = target.y + distance * Math.sin(pitch);
+   z = target.z + distance * Math.cos(yaw) * Math.cos(pitch);
+   ```
+   then `this.lookAt(targetPosition)`.
+5. **Smooth with framerate-independent damping:** `alpha = Math.min(1, smoothSpeed * this.deltaTime)`, then `pos += (desired - pos) * alpha`.
+6. **Resolve targets lazily.** Look the target up in `init()` AND retry in `onUpdate()` when it is missing — this survives hot reloads and late model/physics initialization.
+
+---
+
+## Recipe 1 — Orbit camera (rotate around a target)
+
+Orbits a target entity: optional auto-rotate, drag with the left mouse button to orbit manually, scroll to zoom. Falls back to orbiting the world origin when no target is set, so it always does something visible.
+
+**Setup:** attach to the **camera entity**. Pick the target with the `target` entity field in the inspector (or type its name into `targetName`).
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import type {
+  EntityInput,
+  FloatInput,
+  TextInput,
+  ToggleInput,
+  WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+import { TransformComponent } from "@relu-interactives/spatial-ecs/components";
+import { Vector3 } from "three";
+
+export default class OrbitCamera extends Behaviour {
+  data = {
+    // Pick the entity to orbit in the inspector…
+    target: { type: "entity", value: null } as unknown as EntityInput,
+    // …or find it by name (used when no entity is picked).
+    targetName: "" as TextInput,
+
+    distance: 6 as FloatInput,
+    minDistance: 2 as FloatInput,
+    maxDistance: 20 as FloatInput,
+    /** Vertical offset of the orbit centre above the target's origin. */
+    height: 0.5 as FloatInput,
+
+    autoRotate: true as ToggleInput,
+    /** Radians per second when autoRotate is on. */
+    autoRotateSpeed: 0.4 as FloatInput,
+
+    mouseSensitivity: 0.005 as FloatInput,
+    minPitch: -0.2 as FloatInput,
+    maxPitch: 1.3 as FloatInput,
+    smoothSpeed: 8 as FloatInput,
+  };
+
+  private yaw = 0;
+  private pitch = 0.5;
+  private currentDistance = 6;
+  private targetTransform: TransformComponent | null = null;
+  private orbitCentre = new Vector3();
+
+  protected init() {
+    this.currentDistance = this.data.distance;
+    this.resolveTarget();
+  }
+
+  /** Prefer the inspector-picked entity; fall back to lookup by name. */
+  private resolveTarget() {
+    const picked = this.data.target.value as WorldEntityView | null;
+    if (picked) {
+      this.targetTransform = this.world.getComponent(
+        picked.entityId,
+        TransformComponent,
+      ) as TransformComponent | null;
+      if (this.targetTransform) return;
+    }
+    if (this.data.targetName) {
+      const byName = this.world.getEntityByName(this.data.targetName);
+      if (byName) {
+        this.targetTransform = this.world.getComponent(
+          byName.entityId,
+          TransformComponent,
+        ) as TransformComponent | null;
+      }
+    }
+  }
+
+  protected onUpdate() {
+    // Lazy re-resolve so the rig survives hot reloads / late target creation.
+    if (!this.targetTransform) this.resolveTarget();
+
+    // Consume the mouse delta EVERY frame (deltas accumulate until consumed —
+    // skipping frames would cause a jump when the drag starts) but only apply
+    // it while the left button is held.
+    const delta = this.world.consumeMouseDelta();
+    const dragging = this.world.getMouse("left");
+    if (dragging) {
+      this.yaw -= delta.x * this.data.mouseSensitivity;
+      this.pitch += delta.y * this.data.mouseSensitivity;
+      this.pitch = Math.max(
+        this.data.minPitch,
+        Math.min(this.data.maxPitch, this.pitch),
+      );
+    } else if (this.data.autoRotate) {
+      this.yaw += this.data.autoRotateSpeed * this.deltaTime;
+    }
+
+    // Scroll to zoom.
+    const scroll = this.world.consumeScrollDelta();
+    this.currentDistance += scroll.y * 0.01;
+    this.currentDistance = Math.max(
+      this.data.minDistance,
+      Math.min(this.data.maxDistance, this.currentDistance),
+    );
+
+    // Orbit centre: the target's position (world origin when no target).
+    if (this.targetTransform) {
+      this.orbitCentre.set(
+        this.targetTransform.position.x,
+        this.targetTransform.position.y + this.data.height,
+        this.targetTransform.position.z,
+      );
+    } else {
+      this.orbitCentre.set(0, this.data.height, 0);
+    }
+
+    // Desired position on the orbit sphere.
+    const desiredX =
+      this.orbitCentre.x +
+      this.currentDistance * Math.sin(this.yaw) * Math.cos(this.pitch);
+    const desiredY =
+      this.orbitCentre.y + this.currentDistance * Math.sin(this.pitch);
+    const desiredZ =
+      this.orbitCentre.z +
+      this.currentDistance * Math.cos(this.yaw) * Math.cos(this.pitch);
+
+    // Framerate-independent smoothing, then aim at the centre.
+    const alpha = Math.min(1, this.data.smoothSpeed * this.deltaTime);
+    this.transform.position.x += (desiredX - this.transform.position.x) * alpha;
+    this.transform.position.y += (desiredY - this.transform.position.y) * alpha;
+    this.transform.position.z += (desiredZ - this.transform.position.z) * alpha;
+    this.lookAt(this.orbitCentre);
+  }
+}
+```
+
+---
+
+## Recipe 2 — Third-person camera + character controller
+
+Two cooperating scripts: the **camera** orbits behind the character under pointer-lock mouse control, and the **controller** moves the character relative to the camera. This is the classic third-person setup.
+
+**Setup:**
+- Attach `ThirdPersonCamera` to the **camera entity**; set `targetName` to the character entity's name.
+- Attach `CharacterController` to the **character entity** (must have a `PhysicsComponent` — dynamic rigid body + capsule collider); pick the camera entity in its `cameraEntity` field.
+- The character's `AnimationComponent` state names are configurable through the `animStates` fields.
+
+```ts
+// ThirdPersonCamera.ts — attach to the CAMERA entity
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import type { FloatInput, TextInput } from "@relu-interactives/spatial-ecs";
+import {
+  PhysicsComponent,
+  TransformComponent,
+} from "@relu-interactives/spatial-ecs/components";
+import { Vector3 } from "three";
+
+export default class ThirdPersonCamera extends Behaviour {
+  data = {
+    targetName: "Player" as TextInput,
+    distance: 5 as FloatInput,
+    /** Look-at height above the character origin (aim at the upper body). */
+    height: 1.5 as FloatInput,
+    smoothSpeed: 10 as FloatInput,
+    mouseSensitivity: 0.003 as FloatInput,
+    minPitch: -0.4 as FloatInput,
+    maxPitch: 1.2 as FloatInput,
+    minDistance: 1 as FloatInput,
+    maxDistance: 15 as FloatInput,
+  };
+
+  private targetPhysics: PhysicsComponent | null = null;
+  private targetTransform: TransformComponent | null = null;
+  private yaw = 0;
+  private pitch = 0.4;
+  private currentDistance = 5;
+
+  protected init() {
+    this.currentDistance = this.data.distance;
+    this.findTarget();
+  }
+
+  private findTarget() {
+    const target = this.world.getEntityByName(this.data.targetName);
+    if (!target) return;
+    this.targetPhysics = this.world.getComponent(
+      target.entityId,
+      PhysicsComponent,
+    ) as PhysicsComponent | null;
+    this.targetTransform = this.world.getComponent(
+      target.entityId,
+      TransformComponent,
+    ) as TransformComponent | null;
+  }
+
+  protected onUpdate() {
+    if (!this.targetTransform) {
+      this.findTarget();
+      if (!this.targetTransform) return;
+    }
+
+    // Pointer lock on click; Escape releases it.
+    if (this.world.getMouseDown("left")) this.world.lockMousePointer();
+    if (this.world.getKeyDown("Escape")) this.world.unlockMousePointer();
+
+    // Orbit with the mouse while locked.
+    if (this.world.isMousePointerLocked()) {
+      const delta = this.world.consumeMouseDelta();
+      this.yaw -= delta.x * this.data.mouseSensitivity;
+      this.pitch -= delta.y * this.data.mouseSensitivity;
+      this.pitch = Math.max(
+        this.data.minPitch,
+        Math.min(this.data.maxPitch, this.pitch),
+      );
+    }
+
+    // Scroll to zoom.
+    const scroll = this.world.consumeScrollDelta();
+    this.currentDistance -= scroll.y * 0.01;
+    this.currentDistance = Math.max(
+      this.data.minDistance,
+      Math.min(this.data.maxDistance, this.currentDistance),
+    );
+
+    // Follow the live rigid body when present (avoids one-frame physics lag).
+    let tx: number, ty: number, tz: number;
+    if (this.targetPhysics?.rigidBody) {
+      const t = this.targetPhysics.rigidBody.translation();
+      tx = t.x; ty = t.y; tz = t.z;
+    } else {
+      tx = this.targetTransform.position.x;
+      ty = this.targetTransform.position.y;
+      tz = this.targetTransform.position.z;
+    }
+
+    const lookAtY = ty + this.data.height;
+    const desiredX =
+      tx + this.currentDistance * Math.sin(this.yaw) * Math.cos(this.pitch);
+    const desiredY = lookAtY + this.currentDistance * Math.sin(this.pitch);
+    const desiredZ =
+      tz + this.currentDistance * Math.cos(this.yaw) * Math.cos(this.pitch);
+
+    const alpha = Math.min(1, this.data.smoothSpeed * this.deltaTime);
+    this.transform.position.x += (desiredX - this.transform.position.x) * alpha;
+    this.transform.position.y += (desiredY - this.transform.position.y) * alpha;
+    this.transform.position.z += (desiredZ - this.transform.position.z) * alpha;
+
+    this.lookAt(new Vector3(tx, lookAtY, tz));
+  }
+
+  dispose() {
+    this.world.unlockMousePointer();
+  }
+}
+```
+
+```ts
+// CharacterController.ts — attach to the CHARACTER entity (needs PhysicsComponent)
+import { Behaviour, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+import type {
+  EntityInput,
+  FloatInput,
+  TextInput,
+  WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+import {
+  AnimationComponent,
+  PhysicsComponent,
+  TransformComponent,
+} from "@relu-interactives/spatial-ecs/components";
+import { Euler, Quaternion } from "three";
+
+export default class CharacterController extends Behaviour {
+  data = {
+    walkSpeed: 4 as FloatInput,
+    sprintSpeed: 8 as FloatInput,
+    rotationSpeed: 8 as FloatInput,
+    /** Pick the camera entity in the inspector. */
+    cameraEntity: { type: "entity", value: null } as unknown as EntityInput,
+    // Animation state names (must match states on the AnimationComponent).
+    idleState: "idle" as TextInput,
+    runState: "run_forward" as TextInput,
+    sprintState: "sprint" as TextInput,
+  };
+
+  // Own the Y facing angle — never read it back from the rigid-body
+  // quaternion (Euler extraction gimbal-flips at some orientations).
+  private facingY = 0;
+
+  protected init() {
+    const physics = this.getComponent(PhysicsComponent);
+    // Lock physical tipping; we drive yaw manually.
+    physics?.rigidBody?.setEnabledRotations(false, true, false, true);
+    this.facingY = this.transform.rotation.y;
+  }
+
+  protected onUpdate() {
+    const rb = this.getComponent(PhysicsComponent)?.rigidBody;
+    if (!rb) return;
+
+    // Camera-relative forward/right on the XZ plane.
+    const camEntity = this.data.cameraEntity.value as WorldEntityView | null;
+    if (!camEntity) return;
+    const camTransform = this.world.getComponent(
+      camEntity.entityId,
+      TransformComponent,
+    ) as TransformComponent | null;
+    if (!camTransform) return;
+
+    const myPos = rb.translation();
+    let fwdX = 0, fwdZ = -1, rightX = 1, rightZ = 0;
+    const dx = myPos.x - camTransform.position.x;
+    const dz = myPos.z - camTransform.position.z;
+    const len = Math.sqrt(dx * dx + dz * dz);
+    if (len > 0.001) {
+      fwdX = dx / len; fwdZ = dz / len;
+      rightX = -fwdZ; rightZ = fwdX;
+    }
+
+    const w = this.world.getKey(KeyboardKeys.W);
+    const s = this.world.getKey(KeyboardKeys.S);
+    const a = this.world.getKey(KeyboardKeys.A);
+    const d = this.world.getKey(KeyboardKeys.D);
+    const sprint = this.world.getKey(KeyboardKeys.ShiftLeft);
+
+    let moveX = 0, moveZ = 0;
+    if (w) { moveX += fwdX; moveZ += fwdZ; }
+    if (s) { moveX -= fwdX; moveZ -= fwdZ; }
+    if (d) { moveX += rightX; moveZ += rightZ; }
+    if (a) { moveX -= rightX; moveZ -= rightZ; }
+
+    const moveLen = Math.sqrt(moveX * moveX + moveZ * moveZ);
+    const isMoving = moveLen > 0.001;
+    if (isMoving) { moveX /= moveLen; moveZ /= moveLen; }
+
+    // Horizontal velocity; PRESERVE vel.y so gravity keeps working.
+    const speed = sprint && w && !s ? this.data.sprintSpeed : this.data.walkSpeed;
+    const vel = rb.linvel();
+    rb.setLinvel(
+      { x: isMoving ? moveX * speed : 0, y: vel.y, z: isMoving ? moveZ * speed : 0 },
+      true,
+    );
+
+    // Smoothly rotate to face camera-forward (shortest way around).
+    const targetAngle = Math.atan2(fwdX, fwdZ);
+    let diff = targetAngle - this.facingY;
+    while (diff > Math.PI) diff -= 2 * Math.PI;
+    while (diff < -Math.PI) diff += 2 * Math.PI;
+    this.facingY += diff * Math.min(1, this.data.rotationSpeed * this.deltaTime);
+    const q = new Quaternion().setFromEuler(new Euler(0, this.facingY, 0));
+    rb.setRotation({ x: q.x, y: q.y, z: q.z, w: q.w }, false);
+
+    // Animation — retry switchState until external clips finish loading.
+    const anim = this.getComponent(AnimationComponent);
+    let stateName = this.data.idleState;
+    if (isMoving) stateName = sprint && w && !s ? this.data.sprintState : this.data.runState;
+    if (anim && anim.activeStateName !== stateName) anim.switchState(stateName);
+  }
+}
+```
+
+---
+
+## Recipe 3 — First-person controller
+
+Mouse-look with pointer lock, WASD movement on a physics body, jump, and the camera riding at eye height. The **camera entity is the player's head**; a separate body entity carries the physics.
+
+**Setup:** attach to the **camera entity**. Create a body entity (e.g. an invisible capsule) named per `bodyName` with a `PhysicsComponent` (dynamic rigid body + capsule collider). Without a body the script falls back to direct (fly-style) movement.
+
+```ts
+import { Behaviour, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+import type { FloatInput, TextInput } from "@relu-interactives/spatial-ecs";
+import { PhysicsComponent } from "@relu-interactives/spatial-ecs/components";
+import * as THREE from "three";
+
+export default class FirstPersonController extends Behaviour {
+  data = {
+    bodyName: "Player" as TextInput,
+    moveSpeed: 4 as FloatInput,
+    sprintSpeed: 6.5 as FloatInput,
+    lookSensitivity: 2 as FloatInput,
+    jumpForce: 8 as FloatInput,
+    /** Y of the capsule centre when standing on the ground (for the ground check). */
+    groundLevel: 0.85 as FloatInput,
+    /** Camera height above the capsule centre. */
+    eyeHeight: 0.85 as FloatInput,
+  };
+
+  private isLocked = false;
+  // YXZ order: yaw first, then pitch — the FPS standard (no roll drift).
+  private euler = new THREE.Euler(0, 0, 0, "YXZ");
+  private forward = new THREE.Vector3();
+  private right = new THREE.Vector3();
+  private camera: THREE.PerspectiveCamera | null = null;
+  private bodyPhysics: PhysicsComponent | null = null;
+
+  protected init() {
+    this.camera = this.world.getCamera() as THREE.PerspectiveCamera;
+    this.camera.rotation.order = "YXZ";
+    this.euler.setFromQuaternion(this.camera.quaternion);
+    this.transform.rotation.x = this.euler.x;
+    this.transform.rotation.y = this.euler.y;
+    this.transform.rotation.z = this.euler.z;
+  }
+
+  protected onUpdate() {
+    // Pointer lock on click; detect external unlock (Escape).
+    if (!this.isLocked && this.world.getMouseDown("left")) {
+      this.world.lockMousePointer();
+      this.isLocked = true;
+    }
+    if (this.isLocked && !this.world.isMousePointerLocked()) this.isLocked = false;
+    if (!this.isLocked) return;
+
+    // Lazy-resolve the physics body.
+    if (!this.bodyPhysics) {
+      const body = this.world.getEntityByName(this.data.bodyName);
+      if (body) {
+        this.bodyPhysics = this.world.getComponent(
+          body.entityId,
+          PhysicsComponent,
+        ) as PhysicsComponent | null;
+      }
+    }
+    const rb = this.bodyPhysics?.rigidBody ?? null;
+
+    // Mouse look — yaw + pitch, pitch clamped just short of straight up/down.
+    const delta = this.world.consumeMouseDelta();
+    if (delta.x !== 0 || delta.y !== 0) {
+      this.euler.y -= delta.x * 0.002 * this.data.lookSensitivity;
+      this.euler.x -= delta.y * 0.002 * this.data.lookSensitivity;
+      this.euler.x = Math.max(
+        -Math.PI / 2 + 0.01,
+        Math.min(Math.PI / 2 - 0.01, this.euler.x),
+      );
+      this.transform.rotation.x = this.euler.x;
+      this.transform.rotation.y = this.euler.y;
+      this.transform.rotation.z = this.euler.z;
+    }
+
+    // Movement basis from camera yaw only — strafing stays horizontal.
+    this.forward.set(0, 0, -1).applyQuaternion(this.camera!.quaternion);
+    this.forward.y = 0;
+    this.forward.normalize();
+    this.right.set(1, 0, 0).applyQuaternion(this.camera!.quaternion);
+    this.right.y = 0;
+    this.right.normalize();
+
+    let mx = 0, mz = 0;
+    if (this.world.getKey(KeyboardKeys.W)) { mx += this.forward.x; mz += this.forward.z; }
+    if (this.world.getKey(KeyboardKeys.S)) { mx -= this.forward.x; mz -= this.forward.z; }
+    if (this.world.getKey(KeyboardKeys.A)) { mx -= this.right.x; mz -= this.right.z; }
+    if (this.world.getKey(KeyboardKeys.D)) { mx += this.right.x; mz += this.right.z; }
+    const len = Math.sqrt(mx * mx + mz * mz);
+    if (len > 0) { mx /= len; mz /= len; }
+
+    const sprinting =
+      this.world.getKey(KeyboardKeys.ShiftLeft) ||
+      this.world.getKey(KeyboardKeys.ShiftRight);
+    const speed = sprinting ? this.data.sprintSpeed : this.data.moveSpeed;
+
+    if (rb) {
+      const vel = rb.linvel();
+      const pos = rb.translation();
+
+      // Horizontal velocity; preserve vel.y so gravity keeps working.
+      rb.setLinvel({ x: mx * speed, y: vel.y, z: mz * speed }, true);
+
+      // Grounded: capsule centre near standing height and not rising.
+      const isGrounded = pos.y <= this.data.groundLevel + 0.08 && vel.y < 0.5;
+      if (isGrounded && this.world.getKeyDown(KeyboardKeys.Space)) {
+        rb.setLinvel({ x: vel.x, y: this.data.jumpForce, z: vel.z }, true);
+      }
+
+      // Camera rides the body at eye height.
+      this.transform.position.x = pos.x;
+      this.transform.position.y = pos.y + this.data.eyeHeight;
+      this.transform.position.z = pos.z;
+    } else {
+      // No body: direct fly-style movement.
+      this.transform.position.x += mx * speed * this.deltaTime;
+      this.transform.position.z += mz * speed * this.deltaTime;
+    }
+  }
+
+  dispose() {
+    if (this.isLocked) this.world.unlockMousePointer();
+  }
+}
+```
+
+**Optional additions:** a crosshair can be parented to the camera object (`this.world.getCamera().add(mesh)` with `depthTest: false`, positioned at `z: -0.5`) — remove it in `dispose()`. One-shot sounds can be spawned with `getObjectManagementSystem().requestCreate("audio", { path, options: { autoplay: true } }, …)`.
+
+---
+
+## Common mistakes
+
+| Mistake | Why it fails | Do instead |
+|---|---|---|
+| Mutating `this.threeRef.object.position/rotation` | `TransformSyncSystem` overwrites it every frame | Mutate `this.transform` |
+| `world.input.getKey(...)` | There is no `world.input` | `this.world.getKey(KeyboardKeys.W)` |
+| Reading yaw back from a quaternion each frame | Euler extraction gimbal-flips | Own yaw/pitch as private numbers |
+| `rb.setLinvel({ x, y: 0, z })` | Kills gravity — the body floats | Preserve `vel.y` |
+| Degrees for rotation | Everything is radians | `Math.PI / 2`, not `90` |
+| Consuming mouse delta only while dragging | Deltas accumulate → jump on click | `consumeMouseDelta()` every frame, apply conditionally |
+| `onInit()` lifecycle hook | Never called — the hook is `init()` | `protected init() { … }` |

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

@@ -53,12 +53,12 @@ Transition between an idle and a walk state based on arrow-key input. The cross-
 
 ```typescript
 import { Behaviour, AnimationComponent, KeyboardKeys } from "@relu-interactives/spatial-ecs";
-import type { StringInput, FloatInput } from "@relu-interactives/spatial-ecs";
+import type { TextInput, FloatInput } from "@relu-interactives/spatial-ecs";
 
 export default class AnimationController extends Behaviour {
   data = {
-    idleState: "Idle" as StringInput,
-    walkState: "Walk" as StringInput,
+    idleState: "Idle" as TextInput,
+    walkState: "Walk" as TextInput,
     crossFadeDuration: 0.3 as FloatInput,
   };
 
@@ -91,12 +91,12 @@ Drive `timeScale` and `paused` live from inspector fields, useful for slow-motio
 
 ```typescript
 import { Behaviour, AnimationComponent } from "@relu-interactives/spatial-ecs";
-import type { FloatInput, BooleanInput } from "@relu-interactives/spatial-ecs";
+import type { FloatInput, ToggleInput } from "@relu-interactives/spatial-ecs";
 
 export default class AnimationSpeedDriver extends Behaviour {
   data = {
     timeScale: 1 as FloatInput,
-    paused: false as BooleanInput,
+    paused: false as ToggleInput,
   };
 
   protected onUpdate() {