@relu-interactives/spatial-ecs 0.5.3 → 0.9.0

package/dist/docs/guide/audio-mixing-and-sound-banks.md

@@ -0,0 +1,71 @@
+# Mixing and sound banks
+
+Every sound plays through a **bus**: `sfx`, `voice` or `music`. A bus has its own volume, so a game can offer a music slider without touching a single sound, and music dips by itself while a voice plays.
+
+## Buses
+
+An `AudioComponent` picks its bus in `options.bus` (default `sfx`). To set a volume at runtime:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export class VolumeMenu extends Behaviour {
+  setMusic(volume: number) {
+    this.world.getAudioSystem()?.setBusVolume("music", volume);
+  }
+}
+```
+
+## Sound banks
+
+A game usually wants a *kind* of sound ("hit", "footstep"), not one file: a few takes so it doesn't repeat, a chance so it doesn't fire every time, a cooldown so a flurry doesn't stack. A `.soundbank.json` asset holds that:
+
+```json
+{
+  "version": 1,
+  "slots": {
+    "hit": {
+      "bus": "sfx",
+      "takes": [{ "file": "assets/sfx/hit-1.mp3" }, { "file": "assets/sfx/hit-2.mp3", "volume": 0.8 }],
+      "cooldownMs": 80
+    },
+    "taunt": {
+      "bus": "voice",
+      "chance": 0.5,
+      "priority": 1,
+      "takes": [{ "file": "assets/voice/taunt.mp3" }]
+    }
+  }
+}
+```
+
+`file` paths start at `assets/`. Files a bank names ship with a publish.
+
+| Field | Default | Description |
+|---|---|---|
+| `takes` | | The recordings. The same take never plays twice running when there's another. |
+| `bus` | `sfx` | The volume group. |
+| `chance` | `1` | Probability it plays at all. |
+| `cooldownMs` | `0` | Asks within this long of the last play are ignored. |
+| `volume` | `1` | Linear gain; a take's `volume` multiplies it. |
+| `priority` | `0` | On the voice bus, a lower priority stays quiet while a higher one speaks, and an equal or higher one cuts in. |
+
+Load a bank once, then play slots by name. `playSlot` says whether it sounded; a slot kept quiet by its chance or cooldown isn't an error.
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export class Fighter extends Behaviour {
+  data = { sounds: { path: "", type: "file" as const } };
+
+  protected init() {
+    void this.loadSoundBank(this.data.sounds);
+  }
+
+  takeHit() {
+    this.playSlot("hit", { position: this.transform.position });
+  }
+}
+```
+
+Without `position`, a slot plays evenly everywhere. Audio needs a user gesture before a browser will play it, so play from input, not from `init`.

package/dist/docs/guide/authoring-a-behaviour.md

@@ -87,7 +87,7 @@ In a Relu Spatial project, scripts live under the project's `assets/` directory.
 
 ## Inspector data binding
 
-The `data` object is the bridge between the editor inspector and your script. Use typed input annotations — `FloatInput`, `ColorInput`, `DropdownInput`, etc. — to control which inspector control renders for each field:
+The `data` object is the bridge between the editor inspector and your script. Use typed input annotations `FloatInput`, `ColorInput`, `DropdownInput`, etc. to control which inspector control renders for each field:
 
 ```ts
 import {
@@ -124,6 +124,6 @@ See [Reading Input](./reading-input) for the full keyboard and mouse input API,
 
 ## Behaviours run at preview/runtime only
 
-`Behaviour` scripts execute **only** at preview and runtime — never inside the editor. Gameplay logic, input handling, physics, and anything that should not run while authoring belongs in a Behaviour.
+`Behaviour` scripts execute **only** at preview and runtime, never inside the editor. Gameplay logic, input handling, physics, and anything that should not run while authoring belongs in a Behaviour.
 
-For a visual that must render and animate **inside the editor** (custom shaders, procedural geometry, grass, particle systems — anything the object palette can't produce), use a [Script Object](./authoring-a-script-object) instead. A `ScriptObject` builds a `THREE.Object3D` that renders in the editor AND at runtime.
+For a visual that must render and animate **inside the editor** (custom shaders, procedural geometry, grass, particle systems, anything the object palette can't produce), use a [Script Object](./authoring-a-script-object) instead. A `ScriptObject` builds a `THREE.Object3D` that renders in the editor AND at runtime.

package/dist/docs/guide/authoring-a-script-object.md

@@ -1,6 +1,6 @@
 # Authoring a Script Object
 
-A **Script Object** is an entity whose THREE.js visual is built entirely by your code — custom shaders, procedural geometry, particle systems, anything the editor's object palette can't produce. Unlike a [Behaviour](./authoring-a-behaviour), a Script Object runs in the **editor AND at runtime**: `build()` and `update()` execute identically in both, so what you see while authoring is exactly what ships.
+A **Script Object** is an entity whose THREE.js visual is built entirely by your code, for example custom shaders, procedural geometry, particle systems, anything the editor's object palette can't produce. Unlike a [Behaviour](./authoring-a-behaviour), a Script Object runs in the **editor AND at runtime**: `build()` and `update()` execute identically in both, so what you see while authoring is exactly what ships.
 
 > [!IMPORTANT]
 > **Do NOT gate anything on `world.isEditorMode()`.** Running everywhere is the whole point of a Script Object. Use a [Behaviour](./authoring-a-behaviour) for gameplay logic that must NOT run in the editor.
@@ -15,14 +15,14 @@ import * as THREE from "three";
 
 export default class WavePlane extends ScriptObject {
   // Inspector fields: an INLINE `data = { … }` literal (same envelopes as
-  // Behaviours). NEVER `declare data` — that is a type-only annotation with no
+  // Behaviours). NEVER `declare data` that is a type-only annotation with no
   // runtime object, so the editor can't discover your fields and the inspector
   // shows nothing to edit.
   data = { color: "#3aa0ff" as ColorInput };
 
   private mat!: THREE.ShaderMaterial;
 
-  // REQUIRED — build and return the visual root.
+  // REQUIRED  build and return the visual root.
   build(): THREE.Object3D {
     this.mat = new THREE.ShaderMaterial({
       uniforms: {
@@ -60,6 +60,9 @@ export default class WavePlane extends ScriptObject {
 }
 ```
 
+> [!NOTE]
+> GLSL (`ShaderMaterial`, `RawShaderMaterial`, `onBeforeCompile`) only renders on a `WebGLRenderer`. When the world runs on `WebGPURenderer` (`this.world.getRendererKind() === "webgpu"`), write the material in TSL instead: see [WebGPU and TSL](./webgpu-and-tsl#tsl-in-script-objects) for pulse, displacement, fresnel, dissolve and scrolling-UV recipes.
+
 `ScriptObjectSystem` calls `build()` once, attaches the returned object under the entity's Object3D (so it inherits the entity's transform, selection, and visibility), then calls `update(deltaTime)` every frame. `dispose()` runs on removal, disable, or hot-reload.
 
 ## Members available
@@ -68,12 +71,12 @@ export default class WavePlane extends ScriptObject {
 | --- | --- | --- |
 | `this.world` | `World` | The owning ECS world. |
 | `this.entityId` | `number` | The entity this script is bound to. |
-| `this.data` | `Record<string, unknown>` | Inspector-bound payload. Declare it with an INLINE literal (`data = { … }`) — never `declare data` (a type-only annotation with no runtime object → no inspector fields). |
+| `this.data` | `Record<string, unknown>` | Inspector-bound payload. Declare it with an INLINE literal (`data = { … }`), never use `declare data` (a type-only annotation with no runtime object → no inspector fields). |
 | `this.root` | `THREE.Object3D \| null` | The object `build()` returned (set after build). |
 
 ## Data fields (inspector)
 
-Declare `data` as an **inline literal** (`data = { … }`) with the same input envelopes as Behaviours. **Never use `declare data`** — it is a type-only annotation that produces no runtime object, so the editor can't discover the fields and the inspector shows nothing to edit. (Likewise, don't set defaults with `this.data.x ??= …` inside `build()` — put the default in the literal.)
+Declare `data` as an **inline literal** (`data = { … }`) with the same input envelopes as Behaviours. **Never use `declare data`** it is a type-only annotation that produces no runtime object, so the editor can't discover the fields and the inspector shows nothing to edit. (Likewise, don't set defaults with `this.data.x ??= …` inside `build()` put the default in the literal.)
 
 Simple scalars take a value plus an `as <Input>` cast and are read directly:
 
@@ -98,12 +101,12 @@ See [Data binding](./behaviour-data-binding/) for the full envelope catalog. Edi
 
 ## Rules
 
-- **`build()` must return a `THREE.Object3D`** — a `Group`, `Mesh`, `Points`, etc. Returning anything else marks the object as errored.
+- **`build()` must return a `THREE.Object3D`**, a `Group`, `Mesh`, `Points`, etc. Returning anything else marks the object as errored.
 - **Do NOT gate on `world.isEditorMode()`.** Build and animate unconditionally.
-- **`dispose()` must free what you allocated** — geometries, materials, textures, render targets. THREE `dispose()` is idempotent, so it's safe to over-dispose. The engine removes the built subtree from the scene for you; freeing GPU memory is yours.
-- **Keep per-frame work in local THREE state / uniforms.** Do NOT write ECS components every frame from `update()` — that churns the editor's undo history.
+- **`dispose()` must free what you allocated**, geometries, materials, textures, render targets. THREE `dispose()` is idempotent, so it's safe to over-dispose. The engine removes the built subtree from the scene for you; freeing GPU memory is yours.
+- **Keep per-frame work in local THREE state / uniforms.** Do NOT write ECS components every frame from `update()`, that churns the editor's undo history.
 - **Pivot at the origin, meters for scale.** The built object rides the entity's transform, so build it centered on `(0,0,0)` at real-world scale.
-- **Imports**: only `three` (and `three/examples/jsm/*`) and `@relu-interactives/spatial-ecs`. Other bare imports won't resolve.
+- **Imports**: only `three` (and `three/examples/jsm/*`) and `@relu-interactives/spatial-ecs`. Other bare imports won't resolve. TSL Script Objects also import `three/tsl` and `three/webgpu`.
 
 ## Behaviour vs Script Object
 

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

@@ -17,13 +17,13 @@ The **type annotation** on each field tells the editor which control to render.
 | [`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` |
+| [`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` |
+| [`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
 
@@ -77,7 +77,7 @@ Each field in `data` maps directly to a live inspector control. The script above
 
 ## 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:
+Most types map directly to their underlying primitive. The exceptions are `SliderInput`, `DropdownInput`, `AssetInput`, `EntityInput`, and `ComponentInput` - read the nested value:
 
 ```ts
 onUpdate() {
@@ -101,7 +101,7 @@ onUpdate() {
 }
 ```
 
-## Practical example — spinner with inspector controls
+## Practical example (spinner with inspector controls)
 
 ```ts
 import {
@@ -137,11 +137,11 @@ export default class Spinner extends Behaviour {
 
 ## 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:
+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.
+- 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.
+- 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
 

package/dist/docs/guide/behaviour-lifecycle.md

@@ -36,6 +36,15 @@ This ordering means:
 
 Behaviours never run in the editor. For a visual that must render and animate in the editor, use a [Script Object](./authoring-a-script-object).
 
+## When a hook throws
+
+The engine catches the error, so one broken script never stops the frame or other scripts. What happens next depends on the hook:
+
+- **Load, `init()` or `onUpdate()`**: the engine disposes the instance, sets the entry's `runtimeState` to `"error"` with the message in `runtimeMessage`, and waits about one second before it loads and initialises the script again. A script that throws on every frame therefore restarts about once a second, not 60 times.
+- **Event hooks** (`onSelect`, `onUiPress`, `onGrab`, `onXRSessionStart` and the rest): the instance keeps running and the next event calls the hook again.
+
+Either way the engine logs the first occurrence of each distinct error with `console.error`, naming the entity, class and phase. Subscribe with [`world.onScriptError`](./world-api#catch-script-errors) to receive the same reports in code.
+
 <!-- ## Tips
 
 - **Do not** capture `this.threeRef.object` outside hooks; the underlying `Object3D` may be replaced during hot reload.

package/dist/docs/guide/bone-attachments-and-ik.md

@@ -0,0 +1,128 @@
+# Bone attachments and IK
+
+Two components make characters hold and touch things:
+
+- **`BoneAttachmentComponent`** fixes an entity to one bone of its parent's model: a sword in a hand, a hat on the head, a backpack on the chest. It then moves with every animation.
+- **`IKComponent`** bends a character's arms or legs after the animation so a hand or foot reaches a target entity: the second hand on a rifle's grip, a hand on a door handle, a foot on a step.
+
+Both find bones by **humanoid name** (`rightHand`, `head`, `leftFoot` …) as well as by node name, so they work on Mixamo rigs, generated auto-rigs, Unreal/UAL rigs and VRM models alike.
+
+> **Managed by:** `ObjectManagementSystem` (attachments) and `IKSystem` (IK, right after the `AnimationSystem`).
+
+## Attach an object to a bone
+
+The attached entity stays a CHILD of the character (`ParentId`); the component names the bone. Its Transform becomes its **offset from the bone**: position in the character's units (metres for an unscaled character, whatever scale the rig itself uses inside), rotation relative to the bone.
+
+Attach from a script with `ObjectManagementSystem.attachToBone`. By default the entity keeps its current place in the world, so place it in the hand first and then attach:
+
+```ts
+import { Behaviour, type EntityInput } from "@relu-interactives/spatial-ecs";
+
+export default class EquipSword extends Behaviour {
+  data = {
+    sword: { type: "entity", value: null } as EntityInput,
+  };
+
+  init() {
+    const swordId = this.data.sword.value;
+    if (swordId === null) return;
+    const oms = this.world.getObjectManagementSystem();
+    // keep the sword where it is, now riding on the right hand
+    const result = oms.attachToBone(this.world, swordId, this.entityId, { humanoid: "rightHand" });
+    if (!result.resolved) console.log("the model is still loading; the sword will attach when it has");
+  }
+}
+```
+
+Pass `{ preserveWorldTransform: false }` to snap the entity onto the bone (zero offset) instead, then set its Transform as the offset.
+
+`attachToBone` accepts `{ bone: "<node name>" }` or `{ humanoid: "<humanoid name>" }`; it fills in the other half so the attachment also resolves if the character's model is swapped for another rig. List the bones of a loaded model with `listModelBones`:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class LogBones extends Behaviour {
+  init() {
+    const bones = this.world.getObjectManagementSystem().listModelBones(this.world, this.entityId);
+    for (const b of bones) console.log(b.name, b.humanoid ?? "-", "depth", b.depth);
+  }
+}
+```
+
+### Detach
+
+```ts
+import { Behaviour, type EntityInput } from "@relu-interactives/spatial-ecs";
+
+export default class DropSword extends Behaviour {
+  data = {
+    sword: { type: "entity", value: null } as EntityInput,
+  };
+
+  // a "Drop" button in a spatial UI panel under this character
+  onUiPress() {
+    const swordId = this.data.sword.value;
+    if (swordId === null) return;
+    // stays where it is in the world; toRoot also unparents it from the character
+    this.world.getObjectManagementSystem().detachFromBone(this.world, swordId, { toRoot: true });
+  }
+}
+```
+
+Moving an attached entity to another parent (`setParent`) also ends its attachment.
+
+### What happens until the model loads
+
+Until the parent's model has loaded, or when the named bone doesn't exist in it, the entity sits under the character as an ordinary child. The attachment is kept and takes effect as soon as the bone appears.
+
+## Reach for targets with IK
+
+Add an `IKComponent` to the CHARACTER (the entity with the model) and give it one chain per limb. Each chain names the hand or foot (`limb`) and a `target` entity whose world position it reaches:
+
+```ts
+import { Behaviour, type EntityInput } from "@relu-interactives/spatial-ecs";
+import { IKComponent } from "@relu-interactives/spatial-ecs/components";
+
+export default class TwoHandedGrip extends Behaviour {
+  data = {
+    foregrip: { type: "entity", value: null } as EntityInput,
+  };
+
+  init() {
+    const grip = this.data.foregrip.value;
+    if (grip === null) return;
+    this.world.addComponent(
+      this.entityId,
+      new IKComponent({ chains: [{ limb: "leftHand", target: grip, weight: 1 }] }),
+    );
+  }
+}
+```
+
+A typical rifle: the rifle is attached to the right hand, an empty child entity of the rifle marks the foregrip, and the left hand's chain targets that child, so the left hand stays on the gun through every animation.
+
+Chain fields:
+
+| Field | Meaning |
+| --- | --- |
+| `limb` | `"leftHand"`, `"rightHand"`, `"leftFoot"` or `"rightFoot"`. |
+| `target` | Entity id the hand/foot reaches. |
+| `pole` | Entity the elbow/knee bends toward; `null` keeps the animation's own bend. |
+| `weight` | 0 = the animation, 1 = the target; blend in between (fade a grip in or out by animating it). |
+| `matchRotation` | Also turn the hand/foot to the target's rotation. |
+| `enabled` | Turn one chain off. |
+
+Change chains at runtime by editing `chains` on the component; turn all of them off with `enabled = false`, which puts every bone back to the animation's pose.
+
+Targets out of reach are reached for as far as the limb allows. Ask the system how far a limb fell short:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class ReachCheck extends Behaviour {
+  onUpdate() {
+    const miss = this.world.getIKSystem()?.getReachError(this.entityId, "leftHand") ?? 0;
+    if (miss > 0.05) console.log(`the left hand is ${miss.toFixed(2)} m short of its target`);
+  }
+}
+```

package/dist/docs/guide/component-catalog.md

@@ -26,20 +26,25 @@ Every entity in `@relu-interactives/spatial-ecs` is a bag of components. This ca
 - [Image](./components/image) — 2D image rendered as a textured quad.
 - [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.
+- [Model](./components/model) — GLTF/GLB asset reference loaded asynchronously; `loadState` reports progress.
 - [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
 
 - [Light](./components/light) — directional, point, spot, ambient, hemisphere, or rect-area light.
-- [Environment](./scene/environment) — singleton skybox, fog, and gravity state.
+- [Environment](./scene/environment) — singleton skybox, fog, gravity, and HDRI lighting / tone mapping state.
 - [Postprocessing](./scene/postprocessing) — singleton postprocessing stack (bloom, DoF, vignette, tonemap, etc.).
 - [Camera](./components/camera) — perspective/orthographic camera with `3d`/`ar` runtime modes.
 
 ## Audio
 
 - [Audio](./components/audio) — audio clip with positional/listener options.
+- [Mixing and sound banks](./audio-mixing-and-sound-banks.md) — volume buses, music ducking, named random-take sounds.
+
+## Multiplayer
+
+- [Multiplayer](./multiplayer.md) — shared entities, who owns what, `this.network`, server rules.
 
 ## Physics
 
@@ -58,4 +63,7 @@ Every entity in `@relu-interactives/spatial-ecs` is a bag of components. This ca
 
 - [Script](./components/script) — authored behaviour scripts attached to an entity.
 
+## Characters
 
+- `BoneAttachmentComponent`: fixes an entity to a bone of its parent's model. See [Bone attachments and IK](./bone-attachments-and-ik).
+- `IKComponent`: makes a character's hands and feet reach target entities after the animation. See [Bone attachments and IK](./bone-attachments-and-ik).

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

@@ -96,6 +96,48 @@ export default class LightColorCycle extends Behaviour {
 }
 ```
 
+### Tune shadow quality
+
+three's shadow defaults suit a small demo: a 512 × 512 shadow map, and for a directional light a shadow camera that only covers a 10 m square around the light's target. In a larger level, shadows past that square vanish and the ones inside look blocky. Set `values.shadow` to fix both:
+
+```typescript
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import { LightComponent } from "@relu-interactives/spatial-ecs/components";
+
+export default class SunShadows extends Behaviour {
+  init() {
+    const light = this.getComponent(LightComponent);
+    if (!light) return;
+
+    light.setValues({
+      castShadow: true,
+      shadow: {
+        mapSize: 2048,     // texels per side; sharper but costs GPU memory
+        cameraSize: 25,    // directional only: covers a 50 m square
+        near: 0.5,
+        far: 120,
+        bias: -0.0005,     // removes "shadow acne" stripes
+        normalBias: 0.02,  // helps on large flat floors
+        radius: 2,         // softer edges (PCF shadow maps)
+      },
+    });
+  }
+}
+```
+
+`LightSyncSystem` writes only the fields you provide and leaves the rest at three's defaults. A light with no `shadow` block keeps every default. If you remove a field later, it returns to its default.
+
+| Field | Applies to | Notes |
+| --- | --- | --- |
+| `mapSize` | directional, spot, point | Square shadow map size, clamped to 16 to 8192. Changing it frees the old map; three rebuilds it next frame. |
+| `bias` | directional, spot, point | Small negative values such as `-0.0005` remove acne. Too large and shadows detach from objects. |
+| `normalBias` | directional, spot, point | Offsets along the surface normal. `0.02` to `0.05` works for big flat surfaces. |
+| `radius` | directional, spot, point | Edge blur for PCF shadow maps. |
+| `cameraSize` | directional | Half-width of the orthographic shadow box. Make it just large enough to cover the play area; a bigger box spreads the same texels thinner. |
+| `near`, `far` | directional, spot, point | Shadow camera clip planes. A spot light with a non-zero `distance` uses that distance as its far plane. |
+
+The light must also have `castShadow: true`, and the meshes need `castShadow` / `receiveShadow` on their `MeshGeometryComponent`. Directional lights spawn with `castShadow` on.
+
 ::: tip Live light access
 Mutate `light.light.intensity` and `light.light.color` directly for immediate per-frame changes. For changes that should survive a save/reload cycle, also update `light.values.intensity` / `light.values.color` so the authoring state stays in sync.
 :::

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

@@ -8,6 +8,8 @@ References a GLTF/GLB asset loaded from `path`. The model loading system resolve
 | --- | --- | --- |
 | `path` | `string` | Source URL or `localasset://` path of the GLTF/GLB asset. |
 | `object` | `THREE.Object3D \| null` | Loaded model object, populated asynchronously by the model loader. `null` until loaded. |
+| `loadState` | `ModelLoadState` | `"loading"` while the asset is being fetched and parsed, `"loaded"` once it is attached to the entity, `"error"` when it failed (see `loadError`). A model with an empty `path` reports `"error"`. Runtime-only: never saved. |
+| `loadError` | `string` | Why the load failed, when `loadState` is `"error"`. Runtime-only. |
 
 ## API reference
 
@@ -33,7 +35,7 @@ if (other) {
 
 ### Fade the model in after it loads
 
-Wait for the async model load to complete, then animate opacity to 1 over one second.
+Wait for the async model load to complete (`loadState === "loaded"`), then animate opacity to 1 over one second.
 
 ```typescript
 import { Behaviour } from "@relu-interactives/spatial-ecs";
@@ -45,7 +47,8 @@ export default class ModelFadeIn extends Behaviour {
 
   protected onUpdate() {
     const model = this.getComponent(ModelComponent);
-    if (!model?.object) return; // wait for async load to complete
+    // `object` is an empty anchor until the GLB arrives, so wait on loadState.
+    if (!model?.object || model.loadState !== "loaded") return;
 
     if (!this.started) {
       this.started = true;
@@ -68,6 +71,32 @@ export default class ModelFadeIn extends Behaviour {
 }
 ```
 
+### Check whether the model loaded
+
+`loadState` starts as `"loading"`, then becomes `"loaded"` once the GLB is attached to the entity, or `"error"` if the fetch or parse failed. `loadError` holds the reason. A model entity with an empty `path` reports `"error"` with the message `"No model path set."`. Neither field is saved with the project.
+
+```typescript
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import { ModelComponent } from "@relu-interactives/spatial-ecs/components";
+
+export default class ModelLoadWatcher extends Behaviour {
+  private reported = false;
+
+  onUpdate() {
+    const model = this.getComponent(ModelComponent);
+    if (!model || this.reported) return;
+
+    if (model.loadState === "loaded") {
+      this.reported = true;
+      console.log("model ready", model.path);
+    } else if (model.loadState === "error") {
+      this.reported = true;
+      console.warn(`model failed: ${model.path}: ${model.loadError}`);
+    }
+  }
+}
+```
+
 ### Toggle model visibility
 
 Show or hide the loaded model at runtime using the `Object3DRef` visibility flag.
@@ -93,6 +122,6 @@ export default class ModelVisibility extends Behaviour {
 ```
 
 ::: tip Async loading
-Always guard with `model?.object` before traversing or mutating sub-meshes. The `object` property is `null` until the GLTF/GLB asset finishes loading.
+Always guard before traversing or mutating sub-meshes. Check `model.loadState === "loaded"`, or guard with `model?.object`. `object` starts as the empty anchor group, or `null` on a bare component, until the GLTF/GLB asset finishes loading.
 :::
 

package/dist/docs/guide/concepts.md

@@ -17,13 +17,13 @@ See the [Component Catalog](./component-catalog) for an alphabetical list with f
 
 ## System
 
-A **system** queries entities by component shape and applies side effects each frame. Built-in systems handle object management, geometry, transforms, animation, rendering, and so on. As a script author you rarely interact with systems directly — you read and mutate components, and the systems do the rest.
+A **system** queries entities by component shape and applies side effects each frame. Built-in systems handle object management, geometry, transforms, animation, rendering, and so on. As a script author you rarely interact with systems directly, you read and mutate components, and the systems do the rest.
 
 ## Behaviour (Scripting)
 
 A **Behaviour** is a user-authored class that runs per-frame logic on a single entity. It has full access to `world`, the entity's `transform`, its three.js `Object3D`, and helpers for hierarchy and math.
 
-By default, Behaviours only execute at preview or runtime. Enable the **Execute in editor** toggle on a script entry in the inspector to run the full lifecycle inside the editor as well. This gives direct access to `this.world.getScene()`, `getCamera()`, and `getRenderer()` — useful for custom shaders, procedural geometry, grass, and other Three.js features the editor palette does not expose.
+By default, Behaviours only execute at preview or runtime. Enable the **Execute in editor** toggle on a script entry in the inspector to run the full lifecycle inside the editor as well. This gives direct access to `this.world.getScene()`, `getCamera()`, and `getRenderer()`, useful for custom shaders, procedural geometry, grass, and other Three.js features the editor palette does not expose.
 
 See [Custom Behaviours](./authoring-a-behaviour) and [Running scripts in the editor](./authoring-a-behaviour#running-scripts-in-the-editor).
 

package/dist/docs/guide/getting-started/creating-objects.md

@@ -46,5 +46,5 @@ Drag any asset from the [assets browser](./editor/assets-browser) into the viewp
 
 ## Next
 
-- [Editing inspector values](./editing-objects) — fine-tune components on selected entities.
-- [Spawning](../spawning/) — full reference of every spawnable kind.
+- [Editing inspector values](./editing-objects) - fine-tune components on selected entities.
+- [Spawning](../spawning/) - full reference of every spawnable kind.

package/dist/docs/guide/getting-started/editing-objects.md

@@ -47,7 +47,7 @@ See [Custom Behaviours](../authoring-a-behaviour) for how to declare exposed fie
 
 ## Adding components
 
-Click **`+ Add component`** at the bottom of the inspector to attach additional components — collider, rigidbody, audio, animation, custom script, etc.
+Click **`+ Add component`** at the bottom of the inspector to attach additional components (collider, rigidbody, audio, animation, custom script, etc).
 
 ![Add Component Inspector Gif](/images/getting-started/editing-objects/editing-objects-add-component.png)
 
@@ -59,4 +59,4 @@ Every inspector edit pushes onto the undo stack. Use **⌘Z / Ctrl+Z** to revert
 ## Related
 
 - [Inspector reference](./editor/inspector).
-- [Component Catalog](../component-catalog) — every component and field.
+- [Component Catalog](../component-catalog) - every component and field.