@relu-interactives/spatial-ecs 0.2.2

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

@@ -0,0 +1,108 @@
+# Postprocessing
+
+The `Postprocessing` component owns the scene-wide effect chain (bloom, vignette, depth-of-field, tone mapping, SSAO, and more). Each effect has its own `enabled` flag plus per-effect parameters.
+
+It is a **singleton** there is exactly one `Postprocessing` entity per scene, owned by the editor.
+
+> [!IMPORTANT]
+> The render system only applies effects when the master toggle `postEnabled` is `true`. Enabling an individual effect alone has no visual impact unless the master toggle is also on.
+
+> **Managed by:** [`PostprocessingSyncSystem`](../systems/postprocessing-sync-system)
+
+## Get the component from the world
+
+```ts
+import { Behaviour, Postprocessing } from "@relu-interactives/spatial-ecs";
+
+export default class ReadPostprocessing extends Behaviour {
+  init() {
+    const [entityId] = this.world.query(Postprocessing);
+    if (entityId === undefined) return;
+
+    const post = this.world.getComponent(entityId, Postprocessing);
+    if (!post) return;
+
+    console.log("post enabled?", post.values.postEnabled);
+  }
+}
+```
+
+`post.values` is the live state object mutate fields on it directly. The `PostprocessingSyncSystem` reads it every frame and rebuilds the composer pipeline as effects are toggled.
+
+## Change values at runtime
+
+### Enable the master toggle and a few effects
+
+```ts
+post.values.postEnabled = true;
+
+post.values.bloom.enabled = true;
+post.values.bloom.intensity = 1.5;
+post.values.bloom.threshold = 0.25;
+post.values.bloom.radius = 0.8;
+
+post.values.vignette.enabled = true;
+post.values.vignette.darkness = 1.4;
+```
+
+### Toggle a single effect from a script
+
+```ts
+function setBloom(post, on) {
+  post.values.postEnabled = on || somethingElseEnabled(post);
+  post.values.bloom.enabled = on;
+}
+```
+
+### Cinematic depth of field
+
+```ts
+post.values.dof.enabled = true;
+post.values.dof.focusDistance = 0.02; // distance from the camera (normalised)
+post.values.dof.focalLength = 0.05;
+post.values.dof.bokehScale = 4;
+```
+
+### Color grading
+
+```ts
+post.values.toneMapping.enabled = true;
+post.values.toneMapping.exposure = 1.1;
+
+post.values.hueSaturation.enabled = true;
+post.values.hueSaturation.hue = 0.05;       // radians
+post.values.hueSaturation.saturation = 0.2; // 0 = unchanged
+```
+
+## Authorable values
+
+Top-level master toggle:
+
+| Path | Type | Default |
+| --- | --- | --- |
+| `postEnabled` | `boolean` | `false` |
+
+Each effect lives under its own key with `enabled` plus parameters:
+
+| Effect | Path prefix | Key parameters |
+| --- | --- | --- |
+| Depth of field | `dof` | `focusDistance`, `focalLength`, `bokehScale` |
+| Bloom | `bloom` | `intensity`, `threshold`, `radius` |
+| Vignette | `vignette` | `offset`, `darkness` |
+| Chromatic aberration | `chromAberration` | `offsetX`, `offsetY` |
+| Film noise | `noise` | `opacity` |
+| Pixelation | `pixelation` | `granularity` |
+| Tone mapping | `toneMapping` | `exposure` |
+| Hue / saturation | `hueSaturation` | `hue`, `saturation` |
+| Sepia | `sepia` | `intensity` |
+| SMAA | `smaa` | _(toggle only)_ |
+| SSAO | `ssao` | `intensity`, `radius` |
+| Dot screen | `dotScreen` | `scale`, `angle`, `opacity` |
+| Glitch | `glitch` | `delay`, `duration`, `strength`, `mode`, `active` |
+
+For the full type, including every legacy/optional parameter, see [`PostprocessingState`](../../api/components/classes/Postprocessing.md).
+
+## API reference
+
+- Class: [`Postprocessing`](../../api/components/classes/Postprocessing.md)
+- Source: [`core/components/Postprocessing.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Postprocessing.ts)

package/dist/docs/guide/spawning/ambient-light.md

@@ -0,0 +1,28 @@
+# Ambient Light
+
+A scene-wide light that adds uniform color to every surface. No shadows, no direction.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnAmbient extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("ambientLight", { name: "Fill" });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Ambient Light"` | Display name. |
+| `transform` | `TransformData` | identity | Position has no visual effect (ambient is uniform). |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+Default color is `#ffffff` and intensity is `0.6`. To change them after spawn, update the `Light` component.
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Light`.

package/dist/docs/guide/spawning/area-light.md

@@ -0,0 +1,32 @@
+# Area Light
+
+A rectangular area light (`THREE.RectAreaLight`). Great for soft "softbox" lighting. Only `MeshStandardMaterial` and `MeshPhysicalMaterial` are affected.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnSoftbox extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("areaLight", {
+      name: "Softbox",
+      transform: { position: { x: 0, y: 4, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Area Light"` | Display name. |
+| `transform.position` | `{ x, y, z }` | `(0, 4, 0)` | Light position. The light initially looks at the world origin. |
+| `transform.rotation` / `scale` | — | identity | Standard transform fields. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+Default color `#ffffff`, intensity `5`, dimensions `4 × 4`.
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Light`.

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

@@ -0,0 +1,42 @@
+# Audio
+
+A 3D positional audio source attached to the active camera's `AudioListener`.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnSound extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("audio", {
+      name: "Ambience",
+      path: "/assets/audio/ambience.mp3",
+      transform: { position: { x: 0, y: 1, z: 0 } },
+      options: { autoplay: true, loop: true, volume: 0.5 },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Audio"` | Display name. |
+| `path` | `string` | `""` | URL or local-asset path to the audio clip (MP3, WAV, OGG). |
+| `transform` | `TransformData` | identity | Position / rotation / scale (position drives spatialization). |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+### `options`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | Start playback as soon as the clip is loaded. |
+| `loop` | `boolean` | `false` | Loop playback indefinitely. |
+| `volume` | `number` (0–1) | `1` | Linear gain. |
+| `refDistance` | `number` | `1` | Distance at which volume is unattenuated. |
+| `rolloffFactor` | `number` | `1` | How quickly volume falls off past `refDistance`. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Audio`.

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

@@ -0,0 +1,50 @@
+# Camera
+
+Spawn an additional camera entity. Useful for cinematics, picture-in-picture, or AR cameras.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnCamera extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("camera", {
+      name: "Cinematic",
+      transform: { position: { x: 0, y: 2, z: 5 } },
+      options: {
+        type: "3d",
+        projection: "perspective",
+        fov: 50,
+        near: 0.1,
+        far: 1000,
+      },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Camera"` | Display name. |
+| `transform` | `TransformData` | identity | Position / rotation / scale. |
+| `useWorldCamera` | `boolean` | `false` | Reuse the existing world camera object instead of creating a new one (only honored at runtime, not in the editor). |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+### `options`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"3d" \| "ar"` | `"3d"` | Logical camera type (used by tracking systems). |
+| `isDefault` | `boolean` | `false` | Mark this camera as the default render camera. |
+| `projection` | `"perspective" \| "orthographic"` | `"perspective"` | Projection model. |
+| `fov` | `number` | `60` | Vertical field of view (degrees). Perspective only. |
+| `near` | `number` | `0.1` | Near clip plane. |
+| `far` | `number` | `1000` | Far clip plane. |
+| `left` / `right` / `top` / `bottom` | `number` | ±half-height | Orthographic frustum edges. |
+| `zoom` | `number` | `1` | Orthographic zoom. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Camera`.

package/dist/docs/guide/spawning/capsule.md

@@ -0,0 +1,29 @@
+# Capsule
+
+A `THREE.CapsuleGeometry` with radius `0.5`, length `1`, 4 cap subdivisions, and 8 radial segments.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnCapsule extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("capsule", {
+      name: "Player",
+      transform: { position: { x: 0, y: 1, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Capsule"` | Display name. |
+| `transform` | `TransformData` | identity | Position / rotation (radians) / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Mesh`, `Material`, `MeshGeometry`.

package/dist/docs/guide/spawning/cube.md

@@ -0,0 +1,31 @@
+# Cube
+
+A unit `1×1×1` `THREE.BoxGeometry` mesh with a default white `MeshStandardMaterial`.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnCube extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("cube", {
+      name: "Crate",
+      transform: { position: { x: 0, y: 1, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Cube"` | Display name. |
+| `transform` | `TransformData` | identity | Position / rotation (radians) / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+Default size is `1` along each axis — adjust by changing `transform.scale` after spawn (e.g. `getComponent(id, TransformComponent).scale.x = 2`).
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Mesh`, `Material`, `MeshGeometry`.

package/dist/docs/guide/spawning/cylinder.md

@@ -0,0 +1,29 @@
+# Cylinder
+
+A `THREE.CylinderGeometry` with radius `0.5`, height `1`, and 20 radial segments.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnCylinder extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("cylinder", {
+      name: "Pillar",
+      transform: { position: { x: 0, y: 0.5, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Cylinder"` | Display name. |
+| `transform` | `TransformData` | identity | Position / rotation (radians) / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Mesh`, `Material`, `MeshGeometry`.

package/dist/docs/guide/spawning/directional-light.md

@@ -0,0 +1,32 @@
+# Directional Light
+
+A parallel-ray light source — like the sun. Casts shadows by default.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnSun extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("directionalLight", {
+      name: "Sun",
+      transform: { position: { x: 5, y: 8, z: 5 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Directional Light"` | Display name. |
+| `transform.position` | `{ x, y, z }` | `(3, 6, 4)` | Light position (direction is `target − position`). |
+| `transform.rotation` / `scale` | — | identity | Standard transform fields. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+Default color `#ffffff`, intensity `1.5`, `castShadow: true`.
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Light`.

package/dist/docs/guide/spawning/empty.md

@@ -0,0 +1,31 @@
+# Empty
+
+An invisible `THREE.Group`. Useful as a parent / pivot / spawn anchor.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnAnchor extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("empty", {
+      name: "SpawnPoint",
+      transform: { position: { x: 0, y: 0, z: -3 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Empty"` | Display name. |
+| `transform` | `TransformData` | identity | Position / rotation (radians) / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`.
+
+(No mesh/material — Empties are pure transform anchors.)

package/dist/docs/guide/spawning/image-target.md

@@ -0,0 +1,48 @@
+# Image Target
+
+An AR image-tracking anchor. Children of an image-target entity are revealed and aligned when the tracker recognizes the printed image at runtime.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnTarget extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("imageTarget", {
+      name: "PosterTarget",
+      path: "/assets/targets/poster.png",
+      options: {
+        compiledTargetUrl: "/assets/targets/poster.mind",
+      },
+    }, (entityId) => {
+      // Parent renderable content under the target so it shows when tracked.
+      objects?.requestCreate("model", {
+        name: "Reveal",
+        path: "/assets/models/reveal.glb",
+        parentId: entityId,
+      });
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Image Target"` | Display name. |
+| `path` | `string` | `""` | URL of the source image used as a visual reference in the editor. |
+| `transform` | `TransformData` | identity | Position / rotation / scale (usually left at identity — the tracker drives the transform). |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+### `options`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `targets` | `ImageTargetReference[]` | Optional list of target references when bundling multiple images into one compiled file. |
+| `compiledTargetUrl` | `string` | URL to the compiled `.mind` file used by the tracker. |
+| `compiledTargetDir` | `string` | Optional directory containing compiled target files. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `ImageTarget`, `ImageTargetAnchor`.

package/dist/docs/guide/spawning/image.md

@@ -0,0 +1,33 @@
+# Image
+
+A flat textured plane that auto-sizes to the loaded image's aspect ratio. Useful for billboards, UI quads, or photo planes.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnPoster extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("image", {
+      name: "Poster",
+      path: "/assets/images/poster.png",
+      transform: { position: { x: 0, y: 1.5, z: -2 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Image"` | Display name. |
+| `path` | `string` | `""` | URL or local-asset path to the image (PNG / JPG). |
+| `transform` | `TransformData` | identity | Position / rotation / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+The plane is created at `1×1` and rescaled in X by `width / height` once the texture loads.
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Image`.

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

@@ -0,0 +1,79 @@
+# Spawning Objects
+
+`ObjectManagementSystem` is the runtime factory the editor uses to create every built-in object kind. From inside a `Behaviour` you can ask it to spawn the same primitives at runtime — pre-wired with all of their default components.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("cube", { name: "MyCube" }, (entityId) => {
+      console.log("spawned", entityId);
+    });
+  }
+}
+```
+
+## The `requestCreate` payload
+
+Every kind accepts the same envelope:
+
+```ts
+objects.requestCreate(
+  kind,        // one of the supported kinds below
+  payload,     // common + kind-specific fields (see each page)
+  onCreated?,  // optional callback (entityId) => void
+);
+```
+
+Common payload fields available on every kind:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Display name. Defaults to a sensible label per kind (e.g. `"Cube"`). |
+| `transform.position` | `{ x, y, z }` | World-space position. |
+| `transform.rotation` | `{ x, y, z }` | Euler rotation in radians. |
+| `transform.scale` | `{ x, y, z }` | Per-axis scale. Defaults to `1`. |
+| `parentId` | `EntityId \| null` | Attach the new entity under another entity. |
+
+Kind-specific fields go on `payload.path` (asset URL) or `payload.options` (typed options bag). Each page below lists exactly what is read.
+
+## Use `requestCreate` (queued) vs `createNow` (immediate)
+
+| Method | Returns | When to use |
+| --- | --- | --- |
+| `requestCreate(kind, payload, onCreated?)` | `void` (callback fires after creation) | Default. Schedules creation to run between frames so it never collides with other systems. |
+| `createNow(kind, world, payload)` | `EntityId` | When you need the id synchronously (rare). Skips the queue. |
+
+## Supported kinds
+
+### Primitives
+
+- [Cube](./cube)
+- [Sphere](./sphere)
+- [Plane](./plane)
+- [Capsule](./capsule)
+- [Cylinder](./cylinder)
+- [Empty](./empty)
+
+### Media
+
+- [Model](./model)
+- [Image](./image)
+- [Sprite](./sprite)
+- [Video](./video)
+- [Audio](./audio)
+
+### Tracking & Camera
+
+- [Image Target](./image-target)
+- [Camera](./camera)
+
+### Lights
+
+- [Ambient Light](./ambient-light)
+- [Directional Light](./directional-light)
+- [Point Light](./point-light)
+- [Spot Light](./spot-light)
+- [Area Light](./area-light)

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

@@ -0,0 +1,31 @@
+# Model
+
+Loads a glTF / glb model (with optional Draco compression). The entity is created immediately; the model meshes attach asynchronously once the file is loaded.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnModel extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("model", {
+      name: "Robot",
+      path: "/assets/models/robot.glb",
+      transform: { position: { x: 0, y: 0, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Model"` | Display name. |
+| `path` | `string` | `""` | URL or local-asset path to a `.glb` / `.gltf`. If empty, an anchor is created with no mesh. |
+| `transform` | `TransformData` | identity | Position / rotation / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Model`, `MeshGeometry`. If the loaded file contains animation clips, an `Animation` component is also attached automatically.

package/dist/docs/guide/spawning/plane.md

@@ -0,0 +1,31 @@
+# Plane
+
+A `100 × 100` double-sided `THREE.PlaneGeometry`. By default it is rotated `-π/2` on the X-axis so it lies flat (XZ ground plane).
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnFloor extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("plane", { name: "Floor" });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Plane"` | Display name. |
+| `transform.position` | `{ x, y, z }` | `(0, 0, 0)` | Position. |
+| `transform.rotation` | `{ x, y, z }` | `(-π/2, 0, 0)` | Default lies the plane flat. Pass your own to override. |
+| `transform.scale` | `{ x, y, z }` | `(1, 1, 1)` | Per-axis scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+> [!TIP]
+> Pass `transform.rotation` explicitly to make a wall: `{ x: 0, y: 0, z: 0 }` keeps it vertical.
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Mesh`, `Material`, `MeshGeometry`.

package/dist/docs/guide/spawning/point-light.md

@@ -0,0 +1,32 @@
+# Point Light
+
+An omnidirectional light that radiates equally in all directions, with falloff over `distance`.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnTorch extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("pointLight", {
+      name: "Torch",
+      transform: { position: { x: 0, y: 2, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Point Light"` | Display name. |
+| `transform.position` | `{ x, y, z }` | `(2, 3, 2)` | Light position. |
+| `transform.rotation` / `scale` | — | identity | Standard transform fields. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+Default color `#ffffff`, intensity `1`, distance `10`.
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Light`.