# giVolume

> Talos next · Since 0.6; changed in next

A box that scales the indirect (bounced) light of HD's ray-traced GI, like a post-process volume's indirect lighting intensity.

The box comes from the entity's transform (its position, rotation and scale) and `size`. `mode` picks camera (default) or region; `blend` is the soft edge in metres; `indirectIntensity` is 0..16 (1 changes nothing). Up to 8 volumes of each mode count; overlapping volumes multiply. With `probeSpacing` the box carries its own GI probes, which move with it (a vehicle's cab). Drawn only by HD (hd-only-ignored on other profiles).

Use it in a scene entity's `components` list as `{ "type": "giVolume", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `size` | `Vec3` | yes |  |  | Full extents of the box along the entity's local axes before its scale, metres; each more than 0. |
| `indirectIntensity` | `number` | yes |  |  | Multiplier on the indirect diffuse light, 0..16. 1 changes nothing. |
| `blend` | `number` | no | `0` |  | Width of the soft edge, metres, 0 or more. Default 0.5. In camera mode the band OUTSIDE the box over which the effect fades to nothing as the camera moves away; in region mode the band INSIDE the box's faces. In region mode at most half the smallest extent. |
| `mode` | `GiVolumeMode` | no |  | `camera`, `region` | camera (default): the effect applies to the whole view, weighted by where the camera is: full inside the box, fading over `blend` metres outside (like a post-process volume: walking into a room changes the whole frame smoothly). region: the effect applies only to the surfaces inside the box. |
| `probeSpacing` | `number` | no |  |  | Give the box its own GI probes this far apart, metres, 0.1..2 (0.25 suits a car's cab): a grid fixed in the box that moves and turns with the entity and is re-traced every frame, which the GI inside the box reads instead of the world's. For an interior that moves (a vehicle's cab, a lift, a ship's bridge): the world's probes stay put as it passes through them, so they hold the light of wherever it just was and leak it through the walls as blotches. Absent: the world's probes. At most 16 along an axis and 1024 in all volumes together (the grid is thinned to fit); only the first 4 volumes with one count (gi-volume-limit). Works in either mode; `indirectIntensity` still applies. |

## Example

From the contract's tested fixture `fixtures/contract/full20/scene.json#wall-north`.

```json
{
  "type": "giVolume",
  "size": [
    40,
    4,
    4
  ],
  "indirectIntensity": 0.5,
  "blend": 1,
  "mode": "region"
}
```