# water

> Talos next · Since 0.6

A bounded body of water (lake, pond): level from the entity's height, a box or ellipse outline, flat or small waves, its own look.

Bodies with buoyancy float on it. The highest level wins where bodies overlap.

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

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `size` | `Vec2` | yes |  |  | Full extent along the entity's own x and z axes before its scale, metres; both finite and above 0 (`water-shape-invalid`). |
| `shape` | `WaterShape` | no |  | `box`, `ellipse` | "box" (default) or "ellipse" (inscribed in the box). |
| `windMps` | `number` | no |  |  | Wind over the lake, m/s, 0..30. 0 (default) is flat water. Above 0 the lake has small waves: a fetch-limited wind sea whose fetch is the lake's longer side, so a bigger lake makes bigger waves (`water-waves-invalid` outside 0..30). |
| `windDirectionRad` | `number` | no | `0` |  | Compass bearing the wind blows toward, radians, as `sky.clouds.windDirectionRad`: 0 toward -Z, increasing toward +X. Default 0. |
| `seed` | `number` | no | `1` |  | Wave pattern, a whole number from 0. Same seed and time, same water, bit for bit. Default 1. |
| `priority` | `number` | no | `0` |  | Breaks a tie between overlapping bodies at the same level: the higher wins. A whole number -100..100. Default 0. |
| `look` | `LakeLook` | no |  |  | How the water looks (water type, foam). Render only. Absent: clear fresh water (`alpine-clear`); set a sea class for sea water. |

## Rules that can refuse it

- `buoyancy-without-ocean`
- `fluid.sample-invalid`
- `physics.water.lake-cap`
- `render.hd.water.river-junction-gap`
- `vfx-collide-invalid`
- `water-shape-invalid`
- `water-waves-invalid`
- `watercraft-invalid`
- `watercraft-without-buoyancy`