@relu-interactives/spatial-ecs 0.2.2

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

@@ -0,0 +1,367 @@
+# 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;
+  }
+}
+```

package/dist/docs/guide/reading-input.md

@@ -0,0 +1,202 @@
+# Reading Input
+
+Call input methods directly on `this.world` inside `onUpdate()` to query keyboard and mouse state each frame. There is no `world.input` accessor — all methods are on the `World` instance itself.
+
+```ts
+import { Behaviour, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  onUpdate() {
+    // held this frame
+    if (this.world.getKey(KeyboardKeys.Space)) { /* … */ }
+
+    // only true on the first frame the key goes down
+    if (this.world.getKeyDown(KeyboardKeys.E)) { /* … */ }
+
+    // only true on the frame the key is released
+    if (this.world.getKeyUp(KeyboardKeys.E)) { /* … */ }
+  }
+}
+```
+
+## API
+
+All methods are called directly on `this.world`:
+
+| Method | Description |
+| --- | --- |
+| `this.world.getKey(key)` | `true` while the key is held. |
+| `this.world.getKeyDown(key)` | `true` only on the first frame the key is pressed. |
+| `this.world.getKeyUp(key)` | `true` only on the frame the key is released. |
+| `this.world.getMouse(button)` | `true` while the mouse button is held. `"left"` / `"middle"` / `"right"`. |
+| `this.world.getMouseDown(button)` | `true` only on the first frame the button is pressed. |
+| `this.world.getMouseUp(button)` | `true` only on the frame the button is released. |
+| `this.world.getMousePosition()` | `{ x, y }` in viewport pixels. |
+| `this.world.getMouseDelta()` | `{ x, y }` pointer movement since the last frame. |
+| `this.world.consumeMouseDelta()` | `{ x, y }` movement since last frame; zeroes the delta after reading. |
+| `this.world.getScrollDelta()` | `{ x, y }` scroll wheel delta since the last frame. |
+
+## KeyboardKeys reference
+
+All constants are available from the `KeyboardKeys` import. Pass any of them to `getKey` / `getKeyDown` / `getKeyUp`.
+
+```ts
+import { KeyboardKeys } from "@relu-interactives/spatial-ecs";
+```
+
+### Letters
+
+`KeyboardKeys.A` through `KeyboardKeys.Z`
+
+### Digits
+
+`KeyboardKeys.Digit0` through `KeyboardKeys.Digit9`
+
+### Navigation & editing
+
+| Constant | Key |
+| --- | --- |
+| `KeyboardKeys.ArrowUp` | ↑ Arrow |
+| `KeyboardKeys.ArrowDown` | ↓ Arrow |
+| `KeyboardKeys.ArrowLeft` | ← Arrow |
+| `KeyboardKeys.ArrowRight` | → Arrow |
+| `KeyboardKeys.Space` | Space |
+| `KeyboardKeys.Enter` | Enter / Return |
+| `KeyboardKeys.Escape` | Escape |
+| `KeyboardKeys.Tab` | Tab |
+| `KeyboardKeys.Backspace` | Backspace |
+| `KeyboardKeys.Delete` | Delete |
+| `KeyboardKeys.Insert` | Insert |
+| `KeyboardKeys.Home` | Home |
+| `KeyboardKeys.End` | End |
+| `KeyboardKeys.PageUp` | Page Up |
+| `KeyboardKeys.PageDown` | Page Down |
+
+### Modifier keys
+
+Generic variants match either the left or right physical key. Use the specific variant when the side matters.
+
+| Constant | Physical key |
+| --- | --- |
+| `KeyboardKeys.Shift` | Either Shift key |
+| `KeyboardKeys.ShiftLeft` | Left Shift |
+| `KeyboardKeys.ShiftRight` | Right Shift |
+| `KeyboardKeys.Control` | Either Ctrl key |
+| `KeyboardKeys.ControlLeft` | Left Ctrl |
+| `KeyboardKeys.ControlRight` | Right Ctrl |
+| `KeyboardKeys.Alt` | Alt / Option |
+| `KeyboardKeys.Meta` | Cmd (macOS) / Win key |
+| `KeyboardKeys.CapsLock` | Caps Lock |
+
+### Function keys
+
+`KeyboardKeys.F1` through `KeyboardKeys.F12`
+
+### Punctuation & symbols
+
+| Constant | Key |
+| --- | --- |
+| `KeyboardKeys.Minus` | `-` |
+| `KeyboardKeys.Equal` | `=` |
+| `KeyboardKeys.BracketLeft` | `[` |
+| `KeyboardKeys.BracketRight` | `]` |
+| `KeyboardKeys.Backslash` | `\` |
+| `KeyboardKeys.Semicolon` | `;` |
+| `KeyboardKeys.Quote` | `'` |
+| `KeyboardKeys.Backquote` | `` ` `` |
+| `KeyboardKeys.Comma` | `,` |
+| `KeyboardKeys.Period` | `.` |
+| `KeyboardKeys.Slash` | `/` |
+
+### Other
+
+| Constant | Key |
+| --- | --- |
+| `KeyboardKeys.NumLock` | Num Lock |
+| `KeyboardKeys.ScrollLock` | Scroll Lock |
+| `KeyboardKeys.Pause` | Pause / Break |
+| `KeyboardKeys.PrintScreen` | Print Screen |
+| `KeyboardKeys.ContextMenu` | Context Menu |
+
+## Examples
+
+### WASD movement with sprint
+
+```ts
+import { Behaviour, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+
+export default class Movement extends Behaviour {
+  speed = 5;
+  sprintMultiplier = 2;
+
+  onUpdate() {
+    const step = this.speed * (this.world.getKey(KeyboardKeys.Shift) ? this.sprintMultiplier : 1) * this.deltaTime;
+
+    if (this.world.getKey(KeyboardKeys.W)) this.transform.position.z -= step;
+    if (this.world.getKey(KeyboardKeys.S)) this.transform.position.z += step;
+    if (this.world.getKey(KeyboardKeys.A)) this.transform.position.x -= step;
+    if (this.world.getKey(KeyboardKeys.D)) this.transform.position.x += step;
+  }
+}
+```
+
+### One-shot action on key press and mouse click
+
+`getKeyDown` fires only on the frame the key transitions from up to down, so it is safe to use for one-shot actions.
+
+```ts
+import { Behaviour, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+
+export default class ActionHandler extends Behaviour {
+  onUpdate() {
+    if (this.world.getKeyDown(KeyboardKeys.Space)) {
+      console.log("Jump!");
+    }
+
+    if (this.world.getMouseDown("left")) {
+      const pos = this.world.getMousePosition();
+      console.log("Fired at", pos.x, pos.y);
+    }
+  }
+}
+```
+
+### Distinguishing left vs right modifier
+
+```ts
+import { Behaviour, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+
+export default class ModifierDemo extends Behaviour {
+  onUpdate() {
+    if (this.world.getKeyDown(KeyboardKeys.ControlLeft)) {
+      console.log("Left Ctrl");
+    }
+    if (this.world.getKeyDown(KeyboardKeys.ControlRight)) {
+      console.log("Right Ctrl");
+    }
+
+    // Matches either Shift key
+    if (this.world.getKey(KeyboardKeys.Shift)) {
+      console.log("Shift held");
+    }
+  }
+}
+```
+
+### Mouse-delta camera look
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class CameraLook extends Behaviour {
+  sensitivity = 0.002;
+
+  onUpdate() {
+    const { x, y } = this.world.consumeMouseDelta();
+    this.transform.rotation.y -= x * this.sensitivity;
+    this.transform.rotation.x -= y * this.sensitivity;
+  }
+}
+```
+
+For `InputSystem` internals and pointer-lock details, see the [InputSystem guide](./systems/input-system).

package/dist/docs/guide/scene/environment.md

@@ -0,0 +1,101 @@
+# Environment
+
+The `Environment` component holds scene-wide settings:
+
+- **Skybox:** gradient, solid color, equirectangular image, or none.
+- **Fog:** linear, exponential, or none.
+- **Gravity:** the world gravity vector applied by the physics system (in m/s²).
+
+It is a **singleton** there is exactly one `Environment` entity per scene, owned by the editor.
+
+> **Managed by:** [`EnvironmentSyncSystem`](../systems/environment-sync-system)
+
+## Get the component from the world
+
+```ts
+import { Behaviour, Environment } from "@relu-interactives/spatial-ecs";
+
+export default class ReadEnvironment extends Behaviour {
+  init() {
+    const [entityId] = this.world.query(Environment);
+    if (entityId === undefined) return;
+
+    const env = this.world.getComponent(entityId, Environment);
+    if (!env) return;
+
+    console.log("skybox type", env.values.skybox.type);
+    console.log("gravity", env.values.gravity);
+  }
+}
+```
+
+`env.values` is the live state object. Mutating fields on it is enough, the `EnvironmentSyncSystem` reads it every frame and pushes changes into the three.js scene.
+
+## Change values at runtime
+
+### Switch the skybox
+
+```ts
+env.values.skybox.type = "gradient";
+env.values.skybox.gradient.colors = ["#0b1026", "#3b6dd6", "#f7d488"];
+env.values.skybox.gradient.effect = "linear"; // "linear" | "radial" | "angular"
+
+// Or use a solid color:
+env.values.skybox.type = "color";
+env.values.skybox.color = "#101010";
+
+// Or an equirectangular image:
+env.values.skybox.type = "image";
+env.values.skybox.imageUrl = "/assets/skies/studio.hdr";
+
+// Or disable it:
+env.values.skybox.type = "none";
+```
+
+### Configure fog
+
+```ts
+// Linear fog
+env.values.fog.type = "linear";
+env.values.fog.color = "#aabbcc";
+env.values.fog.linear.near = 1;
+env.values.fog.linear.far = 50;
+
+// Exponential fog
+env.values.fog.type = "exponential";
+env.values.fog.exponential.density = 0.05;
+
+// Off
+env.values.fog.type = "none";
+```
+
+### Change physics gravity
+
+```ts
+// Moon-like gravity
+env.values.gravity = { x: 0, y: -1.62, z: 0 };
+
+// Zero-G
+env.values.gravity = { x: 0, y: 0, z: 0 };
+```
+
+## Authorable values
+
+| Path | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `skybox.type` | `"gradient" \| "color" \| "image" \| "none"` | `"none"` | Active skybox mode. |
+| `skybox.color` | `string` (hex) | `"#1e1e1e"` | Used when `type` is `"color"`. |
+| `skybox.imageUrl` | `string` | `""` | Used when `type` is `"image"`. |
+| `skybox.gradient.colors` | `string[]` | `["#464766", "#657ea6", "#0f0e1a"]` | Hex color stops. |
+| `skybox.gradient.effect` | `"linear" \| "radial" \| "angular"` | `"linear"` | Gradient distribution. |
+| `fog.type` | `"linear" \| "exponential" \| "none"` | `"none"` | Fog model. |
+| `fog.color` | `string` (hex) | `"#1e1e1e"` | Fog color. |
+| `fog.linear.near` | `number` | `1` | Distance where fog starts. |
+| `fog.linear.far` | `number` | `100` | Distance where fog reaches full opacity. |
+| `fog.exponential.density` | `number` | `0.002` | Higher = thicker fog. |
+| `gravity` | `{ x, y, z }` | `(0, -9.81, 0)` | World units per second squared. |
+
+## API reference
+
+- Class: [`Environment`](../../api/components/classes/Environment.md)
+- Source: [`core/components/Environment.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Environment.ts)

package/dist/docs/guide/scene/index.md

@@ -0,0 +1,36 @@
+# Scene
+
+Some settings live on the **scene** rather than on a single object the skybox, fog, gravity, and the post-processing stack. They are stored on a singleton entity so you can read and mutate them from any `Behaviour`.
+
+| Page | What it covers |
+| --- | --- |
+| [Environment](./environment) | Skybox (gradient / color / image), fog (linear / exponential), and physics gravity. |
+| [Postprocessing](./postprocessing) | Bloom, vignette, depth-of-field, tone mapping, and other full-screen effects. |
+
+## Pattern
+
+Both components follow the same access pattern from a script:
+
+```ts
+import { Behaviour, Environment, Postprocessing } from "@relu-interactives/spatial-ecs";
+
+export default class TweakScene extends Behaviour {
+  init() {
+    // 1. Find the singleton entity that owns the component.
+    const [entityId] = this.world.query(Environment);
+    if (entityId === undefined) return;
+
+    // 2. Read the component instance.
+    const env = this.world.getComponent(entityId, Environment);
+    if (!env) return;
+
+    // 3. Mutate `env.values` — sync systems pick the change up next frame.
+    env.values.fog.type = "linear";
+    env.values.fog.color = "#88aaff";
+    env.values.fog.linear.near = 5;
+    env.values.fog.linear.far = 60;
+  }
+}
+```
+
+The same shape works for `Postprocessing` — see each page for the full set of authorable values.