# WaterHandle

> Talos next · Since 0.7; changed in next

The scene's water: the sea, its lakes and rivers, exactly as the engine floats `buoyancy` bodies on them, at `ctx.time.now`.

A replay reads the same numbers.

## Signature

```ts
export interface WaterHandle {
  /**
   * The water at world (x, z), or null where there is none. Throws a `RangeError`
   * (`fluid.sample-invalid`) for a coordinate that is not a finite number.
   */
  sample(x: number, z: number): WaterSample | null
  /**
   * A disturbance for the water's ripples at world (x, z): a bump of `height` metres (default 0.25; negative presses
   * the water down) over `radius` metres (default 0.6) that runs out as a ring and fades. Render only (nothing
   * floats differently), drawn where the scene has `meta.environment.ripples` (HD). False when the frame already has
   * 256 pokes. Throws a `RangeError` (`fluid.sample-invalid`) for a value that is not finite or a radius of 0 or less.
   */
  poke(x: number, z: number, height?: number, radius?: number): boolean
  /**
   * Changes the running sea with no reload: what the bodies float on and what is drawn, together. It starts a
   * quarter of a second after the call, blends from the sea as it is then over `blendS` seconds (default 5), and
   * replaces any weather keys still to come. A later call before the start replaces this one. False when the scene
   * has no sea, or 32 changes are still blending. Throws a `RangeError` (`water.sea-invalid`) for a bad argument.
   */
  setSea(sea: WaterSea): boolean
}
```

Import: `import type { WaterHandle } from "@argus/api"`

## Members

| Member | Signature | Description |
|---|---|---|
| `sample` | `sample(x: number, z: number): WaterSample \| null` | The water at world (x, z), or null where there is none. Throws a `RangeError` (`fluid.sample-invalid`) for a coordinate that is not a finite number. |
| `poke` | `poke(x: number, z: number, height?: number, radius?: number): boolean` | A disturbance for the water's ripples at world (x, z): a bump of `height` metres (default 0.25; negative presses the water down) over `radius` metres (default 0.6) that runs out as a ring and fades. Render only (nothing floats differently), drawn where the scene has `meta.environment.ripples` (HD). False when the frame already has 256 pokes. Throws a `RangeError` (`fluid.sample-invalid`) for a value that is not finite or a radius of 0 or less. |
| `setSea` | `setSea(sea: WaterSea): boolean` | Changes the running sea with no reload: what the bodies float on and what is drawn, together. It starts a quarter of a second after the call, blends from the sea as it is then over `blendS` seconds (default 5), and replaces any weather keys still to come. A later call before the start replaces this one. False when the scene has no sea, or 32 changes are still blending. Throws a `RangeError` (`water.sea-invalid`) for a bad argument. |