@relu-interactives/spatial-ecs 0.5.2 → 0.8.0

package/dist/docs/guide/getting-started/project-types/vr.md

@@ -1,6 +1,274 @@
 # VR
 
-::: warning Coming Soon
-VR (immersive virtual reality) project support is planned for a future release. Documentation will be published when the feature is available.
+A **VR** project creates fully immersive virtual reality experiences that run on WebXR-compatible headsets. Users enter an immersive session where they can look around, move through the scene, grab objects, and interact with 3D content using tracked hands or controllers.
+
+Use this for games, training simulations, virtual showrooms, social spaces, architectural walkthroughs, and any experience that places the user inside a virtual world.
+
+## What's different in this project type
+
+When you create a VR project, the editor provides:
+
+1. **XR Rig entity** - the player's movable origin that contains the camera. The rig handles locomotion (teleport or smooth movement), tracking origin (floor vs. eye-level), and comfort settings.
+2. **XR Interactor entities** - configured hand/controller representation with pointer rays for grabbing and pointing at objects.
+3. **Teleport-first locomotion** - the default is teleport with snap turning, the most comfort-safe movement style recommended by all platform guidelines.
+4. **Immersive preview** - the preview button launches a WebXR session on a connected headset or simulator.
+
+## Supported platforms
+
+- **Meta Quest** (Quest 2, 3, Pro) - hands and controllers, full feature set
+- **Pico** - hands and controllers  
+- **Android XR** - hands-first interaction
+- **Apple Vision Pro** - gaze + pinch only (no controllers), `immersive-vr` mode only (no passthrough on web)
+- **Desktop VR** (SteamVR, Windows Mixed Reality) - controller-based
+
+## Workflow
+
+1. **Set up the XR Rig** - configure locomotion mode, tracking origin, and comfort settings in the inspector.
+2. **Add scene content** - models, lights, interactable objects. Everything is authored at its world position.
+3. **Mark grabbable objects** - add an **XR Interactable** component to objects users should be able to pick up, and optionally a **Physics** component for throwing.
+4. **Define teleport areas** - add **VR Teleport Area** components to surfaces where users can teleport (if using teleport locomotion).
+5. **Customize hands/controllers** - configure the **XR Interactor** to show hands, controllers, or both, with preset visual styles.
+6. **Wire up interactions** - use `Behaviour` scripts with XR hooks (`onGrab`, `onRelease`, `onSelectStart`, etc.).
+7. **Preview** - enter the immersive session on your headset to test interactions and comfort.
+
+## Core Components
+
+### XR Rig
+
+The rig is the player's movable origin. Key settings:
+
+- **Tracking Origin**: 
+  - `floor` - Y=0 is the user's real floor (for standing experiences)
+  - `eye` - Y=0 is where the headset started (for seated/cockpit experiences)
+- **Locomotion**:
+  - `teleport` (default) - point and teleport, most comfort-safe
+  - `smooth` - continuous movement with thumbstick
+  - `none` - no movement (for fixed-position experiences)
+- **Snap Turn** - rotate in fixed steps instead of continuously (reduces nausea)
+- **Teleport Arc Colors** - visual feedback for valid vs. invalid destinations
+
+::: tip Getting tracking origin right
+The classic "I spawned inside/under the geometry" bug comes from mismatched tracking origin. If your scene is authored with content sitting on Y=0 and you use `eye` origin, the user's eyes will be at ground level. Use `floor` for standing experiences where content sits on the ground.
+:::
+
+### XR Interactor
+
+Controls what users see as their hands and how they interact:
+
+- **Interactor Type**: `hands`, `controllers`, `both` (default - shows whatever the device reports), or `none`
+- **Hand Preset**: visual style for tracked hands
+  - `default` - realistic skin tone
+  - `ghost` - translucent
+  - `neon` - glowing edges
+  - `skeleton` - bone structure
+  - `custom` - use your own shader
+- **Ray Visibility**: 
+  - `interacting` (default) - shows only when pointing at something actionable
+  - `always` - always visible
+  - `never` - hidden
+- **Ray Color/Thickness** - customize the pointer beam
+
+### XR Interactable
+
+Makes objects respond to hands and pointers:
+
+- **Grabbable** - can be picked up
+- **Pointable** - responds to pointer selection without grabbing
+- **Reach**: 
+  - `physical` - hand must touch it
+  - `distance` - grab along the ray from across the room
+  - `both` (default) - accepts either
+- **At Distance**: 
+  - `snap` - brings object to hand (Half-Life: Alyx style)
+  - `remote` - manipulate where it stands
+- **Gesture**: `pinch` (trigger/finger), `full` (grip squeeze), or `any`
+- **Hands**: 
+  - `single` - one hand only
+  - `handOff` (default) - pass between hands
+  - `two` - both hands hold it simultaneously (for aiming, resizing)
+- **Apply Velocity** - thrown objects inherit hand motion (for physics-enabled objects)
+- **Attach Points** - authored hand-holds (position, rotation, hand/role restrictions)
+- **Hover Behavior** - visual feedback when ray lands on object (`color`, `scale`, `both`, or `none`)
+
+### VR Teleport Area
+
+Marks surfaces as valid teleport destinations. Teleport is an **allow-list** - only entities with this component can be teleported onto.
+
+- **Shape**: `plane` (rectangular) or `circle`
+- **Width/Depth** - physical size in metres
+- **Enabled** - toggle without removing the component
+
+## Grabbing and Throwing
+
+To make an object **throwable**:
+1. Add **XR Interactable** component
+2. Add **Physics** component with **Dynamic** rigidbody type
+3. Ensure **Apply Velocity** is enabled (it's on by default)
+
+The engine automatically:
+- Disables physics while held
+- Tracks hand motion
+- Applies release velocity from the peak of recent hand movement
+- Makes throws feel natural and match the gesture
+
+```ts
+import { Behaviour, type XrInputState } from "@relu-interactives/spatial-ecs";
+
+export default class Basketball extends Behaviour {
+  onGrab(input: XrInputState) {
+    console.log("picked up by", input.handedness);
+  }
+
+  onRelease(input: XrInputState) {
+    // Velocity already applied - react here
+    console.log("thrown!");
+  }
+}
+```
+
+## Two-Hand Interactions
+
+Objects can be held with both hands for:
+
+- **Aiming** (like a rifle) - primary hand anchors, secondary hand steers
+- **Resizing** - move hands apart/together to scale uniformly
+- **Hand-off** - pass between hands
+
+**Attach points** define where hands should grip:
+- Set **role** to `primary` (anchoring hand) or `secondary` (steering hand)
+- Restrict to `left`, `right`, or `any` hand
+- The nearest eligible point wins when a hand grabs
+
+For a two-handed rifle:
+- **Hands**: `two`
+- **Second Hand**: `Aims the object`  
+- Two attach points: one `primary` at trigger grip, one `secondary` at foregrip
+
+## Locomotion
+
+### Teleport (Default)
+
+- Point at a surface with **VR Teleport Area** component
+- Arc shows valid (green) or invalid (red) landing
+- Release to teleport
+- Only commits if you aimed first (letting go of a grabbed object won't teleport you)
+- Grabbing an object or pointing at a grabbable object suppresses teleport on that hand
+
+### Smooth
+
+- Continuous thumbstick movement
+- Higher nausea risk - use teleport as the default and smooth as an option
+- Speed configurable on XR Rig
+
+### None
+
+- No movement system (for fixed cockpit, turret, or observation experiences)
+
+## Apple Vision Pro Considerations
+
+Vision Pro uses **gaze + pinch** interaction with specific limitations:
+
+- **No controllers** - only hand tracking via pinch gestures
+- **Gaze-driven aiming** - look at an object, then pinch to select
+- **No hover before pinch** - the input source is created when pinch starts, so pointer rays appear *during* pinch, not while looking
+- **No grip/squeeze** - set interactable **Gesture** to `Pinch` or `Any`, never `Full grip`
+- **VR only** - Safari on visionOS does not support `immersive-ar` (no web passthrough)
+- **Hand tracking requires permission** - on visionOS 2+, but asks the user separately
+
+::: tip Vision Pro fallback
+VR projects automatically fall back to `immersive-vr` mode on Vision Pro. Mixed-reality projects offer "View in your room" via AR Quick Look (a `.usdz` export placed natively) as an alternative.
 :::
 
+## Mixed Reality Support
+
+Add passthrough, depth occlusion, and real-world physics by enabling **Mixed Reality** settings on the XR Rig:
+
+- **Passthrough** - show the real room (Quest and Android XR only; switches session to `immersive-ar`)
+- **Depth Occlusion** - real objects hide virtual ones
+- **Environment Physics** - make the real room solid (`planes`, `mesh`, or `auto`)
+- **Environment Debug** - visualize detected geometry on-device
+- **Hit Test** - allow scripts to raycast against the real room
+- **Anchors** - pin content to real-world features
+
+::: warning Room scan required
+Plane and mesh detection replay a scan captured earlier through the headset's room setup. If the user hasn't scanned their room, detected surfaces will be empty. On Quest: *Settings > Guardian > Mixed Reality > Space Setup*.
+:::
+
+See [Mixed Reality](../../mixed-reality.md) for full details.
+
+## Scripting VR Interactions
+
+Use `Behaviour` hooks to react to XR events:
+
+### Session Lifecycle
+
+```ts
+import { Behaviour, type XrCapabilities } from "@relu-interactives/spatial-ecs";
+
+export default class SessionManager extends Behaviour {
+  onXRSessionStart(capabilities: XrCapabilities) {
+    // Check what was actually granted
+    if (capabilities.handTracking) { /* … */ }
+  }
+
+  onXRSessionEnd() { /* … */ }
+}
+```
+
+### Interaction Hooks
+
+| Hook | When it fires |
+|------|---------------|
+| `onSelectStart(input)` | Trigger pressed / finger pinched |
+| `onSelectEnd(input)` | Released |
+| `onGrab(input)` | This entity was picked up |
+| `onRelease(input)` | This entity was let go |
+| `onSecondaryGrab()` | Second hand grabbed (two-hand mode) |
+| `onSecondaryRelease()` | Second hand released |
+| `onHandPoseStart(event)` | A configured hand pose began |
+| `onHandPoseEnd(event)` | That pose ended |
+
+`input` is an `XrInputState` containing: `handedness`, `kind`, `rayOrigin`, `rayDirection`, `gripPosition`, `gripQuaternion`, `select`, `squeeze`, `axes`, `buttons`, and `joints` (for tracked hands).
+
+See [VR, Grabbing and Hand Poses](../../vr-and-hand-poses.md) for comprehensive interaction patterns.
+
+## Tips
+
+### Comfort and Safety
+
+- **Start with teleport locomotion** - it's the most comfortable for the widest audience
+- **Enable snap turn** - rotating in fixed steps greatly reduces nausea
+- **Use `floor` tracking origin** for standing experiences where content sits on the ground
+- **Test on actual hardware** - comfort and presence cannot be validated in desktop preview
+- **Respect the guardian boundary** - users define their safe space, don't fight it
+
+### Performance
+
+- VR must maintain **72fps minimum** (90fps or 120fps on newer headsets) or users will feel sick
+- **Reduce draw calls** - combine meshes where possible, use instancing for repeated objects
+- **Bake lighting** when you can - real-time shadows are expensive
+- **Test on Quest** if targeting mobile VR - it's the most constrained platform
+- **Profile early** - don't wait until polish phase to check frame rate
+
+### Interaction Design
+
+- **Show hover feedback** - users need to know what they're pointing at before they grab
+- **Make important objects grabbable from both physical and distance reach** - seated and standing users have different comfort zones
+- **Avoid forcing physical reach for small objects** - distance grab makes fine pickups accessible
+- **Use attach points for tools and weapons** - hands should land in the right place
+- **Teleport is an allow-list** - deliberately mark where users can stand, don't make every surface walkable
+
+### Cross-Platform
+
+- **Set XR Interactor to `both`** - Quest users may switch from controllers to hands mid-session, Android XR leads with hands
+- **Support pinch gesture** - required for Vision Pro, optional elsewhere
+- **Test gaze + pinch** - Vision Pro interaction feels different from controller pointing
+- **Provide controller and hand alternatives** - not everyone has hand tracking enabled
+
+## Related
+
+- [VR, Grabbing and Hand Poses](../../vr-and-hand-poses.md) - comprehensive interaction patterns and scripting examples
+- [Mixed Reality](../../mixed-reality.md) - passthrough, environment physics, depth occlusion
+- [Spatial UI](../../spatial-ui.md) - in-world panels, buttons, and controls for VR menus
+- [Custom Behaviours](../../authoring-a-behaviour.md) - scripting interactive XR logic
+

package/dist/docs/guide/getting-started/projects.md

@@ -25,7 +25,7 @@ Each project is a folder under your projects path.
 
 ## Create a new project
 
-From the dashboard, click **New project**.
+From the dashboard, click on **Project type** _(see [Project types](./project-types/) for the differences)_ card to create a new project.
 
 ![New project Dialog.](/images/getting-started/projects-new-dialog.png)
 
@@ -33,9 +33,8 @@ From the dashboard, click **New project**.
 You'll be asked for:
 
 - **Project name:** used to derive the folder slug.
-- **Project type:** see [Project types](./project-types/) for the differences.
 
-Click **Create**. The editor scaffolds the project, opens it, and seeds the default scene for the chosen project type.
+Click **Create & Open**. The editor scaffolds the project, opens it, and seeds the default scene for the chosen project type.
 
 ## Open an existing project
 
@@ -49,5 +48,5 @@ The dashboard lists every project found in your projects folder.
 
 ## Next
 
-- [Project types](./project-types/) — pick the right type for your experience.
-- [Understanding the editor](./editor/) — what each region of the editor window does.
+- [Project types](./project-types/): pick the right type for your experience.
+- [Understanding the editor](./editor/): what each region of the editor window does.

package/dist/docs/guide/getting-started/shortcuts.md

@@ -1,6 +1,6 @@
 # Keyboard Shortcuts
 
-The editor supports keyboard shortcuts for common actions. You can also open the shortcuts panel at any time by clicking the **keyboard icon** in the top-right corner of the navbar (next to the logo).
+The editor supports keyboard shortcuts for common actions. You can also open the shortcuts panel at any time by selecting the **shortcuts option** from the avatar menu in the top-right corner of the navbar.
 
 ## Navigation
 
@@ -13,9 +13,10 @@ The editor supports keyboard shortcuts for common actions. You can also open the
 
 | Shortcut | Action |
 | --- | --- |
-| `W` | Switch to **Translate** gizmo |
-| `E` | Switch to **Scale** gizmo |
-| `R` | Switch to **Rotate** gizmo |
+| **`q`** | All transform modes |
+| **`w`** | Ground mode (_moves objects on the ground plane_). |
+| **`e`** | Front mode (_moves objects on the front plane_). |
+| **`r`** | Side mode (_moves objects on the side plane_). |
 
 ## Selection
 

package/dist/docs/guide/multiplayer.md

@@ -0,0 +1,92 @@
+# Multiplayer
+
+A shared world runs in a room on a [Colyseus](https://colyseus.io) server. Turn multiplayer on in the editor's Environment panel; it adds a `server/` folder to the project and runs that server for you while you test.
+
+## Who moves what
+
+Everything shared has one **owner**, the client that simulates it. The owner moves it at once and sends updates; everyone else plays them back a moment in the past, which is what makes it smooth.
+
+- A **scene object** with a Network Identity is owned by the **host**: the first player in the room, then the longest connected. When the host leaves, the next player takes over.
+- A **spawned object** is owned by whoever spawned it, and leaves with them.
+
+## Components
+
+| Component | What it does |
+|---|---|
+| Network Identity | Marks an entity as shared. |
+| Network Transform | Shares its position and rotation. `interpolationMs` trades smoothness for how current it looks. |
+| Networked Props | Named values shared with everyone, such as health. Only the owner can change them. |
+| Network Spawner | Gives each player a prefab of their own, placed around this entity. |
+
+## From a script
+
+`this.network` is `null` in a single-player run, so a script can work both ways. A script on a shared entity should only drive it when it's the owner:
+
+```ts
+import { Behaviour, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+
+export class Player extends Behaviour {
+  protected onUpdate() {
+    if (this.network && !this.network.isOwner) return; // someone else moves this one
+    if (this.world.getKey(KeyboardKeys.W)) {
+      this.transform.position.z -= 3 * this.deltaTime;
+    }
+  }
+}
+```
+
+Shared values, and hearing them change:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export class Health extends Behaviour {
+  takeHit(damage: number) {
+    const hp = Number(this.network?.getProp("hp") ?? 100);
+    this.network?.setProp("hp", hp - damage);
+  }
+
+  onNetworkProp(key: string, value: unknown) {
+    if (key === "hp") console.log("health is now", value);
+  }
+}
+```
+
+Messages go to everyone else in the room. Spawn something everyone sees with `spawn`:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export class Gun extends Behaviour {
+  protected init() {
+    this.network?.onMessage("shot", (payload, from) => {
+      console.log(from, "fired", payload);
+    });
+  }
+
+  fire() {
+    this.network?.send("shot", { power: 3 });
+    this.network?.spawn("assets/bullet.prefab", {
+      position: this.transform.position,
+    });
+  }
+
+  onPlayerJoin(playerId: string) {
+    console.log(playerId, "joined; there are", this.network?.players.length);
+  }
+}
+```
+
+## Server rules
+
+Clients can't be trusted, so anything that decides who won belongs on the server, in `server/rooms/game.ts`. Every hook is optional, and with none the room just relays:
+
+```ts
+const game: RoomHooks = {
+  maxClients: 8,
+  // false moves the player back
+  onPose: (room, client, entity, next) => next.y > -50,
+  // false keeps a message from the other players
+  onMessage: (room, client, name, payload) => name !== "cheat",
+};
+```

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

@@ -2,9 +2,10 @@
 
 The `Environment` component holds scene-wide settings:
 
-- **Skybox:** gradient, solid color, equirectangular image, or none.
+- **Skybox:** gradient, solid color, image (flat backdrop or 360° panorama), or none.
 - **Fog:** linear, exponential, or none.
 - **Gravity:** the world gravity vector applied by the physics system (in m/s²).
+- **Lighting** (optional): an HDRI environment map for image-based lighting, plus tone mapping and exposure. See [Image-based lighting and HDRI](#image-based-lighting-and-hdri).
 
 It is a **singleton** there is exactly one `Environment` entity per scene, owned by the editor.
 
@@ -12,7 +13,7 @@ It is a **singleton** there is exactly one `Environment` entity per scene, owned
 
 ## Get the component from the world
 
-Use `world.getEnvironmentComponent()` — a convenience method that handles the entity lookup for you:
+Use `world.getEnvironmentComponent()`, a convenience method that handles the entity lookup for you:
 
 ```ts
 import { Behaviour } from "@relu-interactives/spatial-ecs";
@@ -28,7 +29,7 @@ export default class ReadEnvironment extends Behaviour {
 }
 ```
 
-`env.values` is the live state object. Mutating fields on it is enough — `EnvironmentSyncSystem` reads it every frame and pushes changes into the three.js scene.
+`env.values` is the live state object. Mutating fields on it is enough, `EnvironmentSyncSystem` reads it every frame and pushes changes into the three.js scene.
 
 ## Change values at runtime
 
@@ -43,9 +44,13 @@ env.values.skybox.gradient.effect = "linear"; // "linear" | "radial" | "angular"
 env.values.skybox.type = "color";
 env.values.skybox.color = "#101010";
 
-// Or an equirectangular image:
+// Or a 360° panorama that turns with the camera (.hdr, .exr, .jpg, .png):
 env.values.skybox.type = "image";
 env.values.skybox.imageUrl = "/assets/skies/studio.hdr";
+env.values.skybox.imageProjection = "equirect";
+
+// Leave imageProjection unset for a flat backdrop stretched over the screen.
+// That mode only loads ordinary images (.jpg, .png, .webp), not .hdr/.exr.
 
 // Or disable it:
 env.values.skybox.type = "none";
@@ -78,6 +83,88 @@ env.values.gravity = { x: 0, y: -1.62, z: 0 };
 env.values.gravity = { x: 0, y: 0, z: 0 };
 ```
 
+## Image-based lighting and HDRI
+
+Without an environment map, PBR materials only see your lights. Metallic surfaces reflect nothing, so a sci-fi kit or a chrome prop renders close to black. An HDRI fixes that: it lights every material from all directions and gives metals something to reflect.
+
+Set `values.lighting` to turn it on:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class StudioLighting extends Behaviour {
+  init() {
+    const env = this.world.getEnvironmentComponent();
+    if (!env) return;
+
+    env.values.lighting = {
+      envMapUrl: "localasset://assets/hdri/studio_small.hdr",
+      envIntensity: 1,        // strength of the image-based light
+      envRotationY: Math.PI / 2, // turn the HDRI to move the key highlight
+      useAsBackground: true,  // also show the HDRI as the sky
+      backgroundBlurriness: 0.2,
+      backgroundIntensity: 1,
+      toneMapping: "aces",    // "none" | "aces" | "agx" | "neutral"
+      exposure: 1,
+    };
+  }
+}
+```
+
+How each field behaves:
+
+- **`envMapUrl`** picks the loader from the file extension. `.hdr` and `.exr` load as linear HDR. Any other extension loads as an sRGB image. On WebGL the system pre-filters the map with three's `PMREMGenerator` and assigns it to `scene.environment`; on WebGPU it assigns the equirect texture and the renderer pre-filters it. An empty string removes the map.
+- **`envIntensity`** and **`envRotationY`** apply immediately, even while the map is still loading. You can animate them every frame without reloading anything.
+- **`useAsBackground`** shows the same HDRI behind the scene and replaces the skybox while it is on. Turn it off and the skybox comes back. Use this instead of loading the same file twice as both an equirect skybox and an env map.
+- **`backgroundBlurriness`** (0 to 1) softens the background, which keeps a low-resolution HDRI from looking pixelated. It only applies when `useAsBackground` is on.
+- **`toneMapping`** and **`exposure`** set `renderer.toneMapping` and `renderer.toneMappingExposure`. Exposure has no visible effect while `toneMapping` is `"none"`. Use `"aces"` or `"agx"` with an HDRI: without tone mapping, bright HDR values clip to flat white.
+
+Changing `envMapUrl` loads the new map in the background and swaps it in when ready. If you change the URL twice in a row, the last one wins even when the first finishes loading later. The system disposes the old map's GPU resources on every swap.
+
+A quick recipe for a dark metallic model:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class FixDarkMetal extends Behaviour {
+  init() {
+    const env = this.world.getEnvironmentComponent();
+    if (!env) return;
+
+    env.values.lighting = {
+      ...env.values.lighting,
+      envMapUrl: "localasset://assets/hdri/warehouse.hdr",
+      envIntensity: 1.5,
+      toneMapping: "agx",
+      exposure: 1.1,
+    };
+  }
+}
+```
+
+### When the block is absent
+
+Scenes without `values.lighting` keep working exactly as before: the system never touches `scene.environment` or the renderer's tone mapping. Removing the block at runtime restores the values the scene and renderer had before it was applied.
+
+### Tone mapping and the post-processing stack
+
+`Postprocessing.values.toneMapping` also controls tone mapping. When both are set, they combine like this:
+
+| Environment `lighting.toneMapping` | Post `toneMapping.enabled` (and `postEnabled`) | Operator used | Exposure used |
+| --- | --- | --- | --- |
+| absent or `"none"` | off | none | (no effect) |
+| `"aces"` / `"agx"` / `"neutral"` | off | the environment's | `lighting.exposure` |
+| `"aces"` / `"agx"` / `"neutral"` | on | the environment's | post `toneMapping.exposure` |
+| absent or `"none"` | on | ACES Filmic | post `toneMapping.exposure` |
+
+In short: the environment picks the operator, the post effect overrides the exposure, and the post effect alone means ACES.
+
+### Mixed reality and the editor
+
+In a passthrough session (`world.isXrPassthrough()`) the background stays hidden so the real room shows through, including an HDRI with `useAsBackground`. Image-based lighting and tone mapping still apply to your virtual objects.
+
+The editor viewport runs the same system, so the lighting you author is the lighting you see while editing.
+
 ## Authorable values
 
 | Path | Type | Default | Notes |
@@ -85,6 +172,7 @@ env.values.gravity = { x: 0, y: 0, z: 0 };
 | `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.imageProjection` | `"screen" \| "equirect"` | absent (`"screen"`) | `"equirect"` wraps the image around the scene and loads `.hdr`/`.exr`. |
 | `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. |
@@ -93,6 +181,15 @@ env.values.gravity = { x: 0, y: 0, z: 0 };
 | `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. |
+| `lighting` | object | absent | Optional. Absent leaves `scene.environment` and tone mapping untouched. |
+| `lighting.envMapUrl` | `string` | `""` | Equirectangular env map. `.hdr`/`.exr` load as HDR. |
+| `lighting.envIntensity` | `number` | `1` | `scene.environmentIntensity`. |
+| `lighting.envRotationY` | `number` (radians) | `0` | Rotates the env map (and the background when used as one). |
+| `lighting.useAsBackground` | `boolean` | `false` | Show the env map as the background, replacing the skybox. |
+| `lighting.backgroundBlurriness` | `number` (0 to 1) | `0` | Background blur when `useAsBackground` is on. |
+| `lighting.backgroundIntensity` | `number` | `1` | Background brightness when `useAsBackground` is on. |
+| `lighting.toneMapping` | `"none" \| "aces" \| "agx" \| "neutral"` | `"none"` | Renderer tone-mapping operator. |
+| `lighting.exposure` | `number` | `1` | Renderer exposure. Needs a tone-mapping operator to have an effect. |
 
 ## API reference
 

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

@@ -1,15 +1,15 @@
 # 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`.
+Some settings live on the **scene** rather than on a single object: the skybox, fog, gravity, image-based lighting, 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. |
+| [Environment](./environment) | Skybox (gradient / color / image / 360° panorama), fog (linear / exponential), physics gravity, and HDRI lighting with tone mapping and exposure. |
 | [Postprocessing](./postprocessing) | Bloom, vignette, depth-of-field, tone mapping, and other full-screen effects. |
 
 ## Pattern
 
-Both components expose a convenience method on `world` — no manual entity lookup needed:
+Both components expose a convenience method on `world`, no manual entity lookup needed:
 
 ```ts
 import { Behaviour } from "@relu-interactives/spatial-ecs";
@@ -28,4 +28,4 @@ export default class TweakScene extends Behaviour {
 }
 ```
 
-The same pattern works for `Postprocessing` via `this.world.getPostprocessingComponent()` — see each page for the full set of authorable values.
+The same pattern works for `Postprocessing` via `this.world.getPostprocessingComponent()`, see each page for the full set of authorable values.