Ground and water

Reference for Slab, Terrain, Water, useWaves, useShore, smoothOutline and the Outline, HeightAt, WaveOptions, Waves and ShoreField types: every prop and default.

import { Slab, smoothOutline, Terrain, useShore, useWaves, Water } from "@apricot/react";
import type { HeightAt, Outline, ShoreField, SlabProps, TerrainProps, WaterProps, WaveOptions, Waves } from "@apricot/react";

All distances are metres. Shapes on the ground are outlines in the x–z plane.

Types#

Type	Definition
`Outline`	`readonly (readonly [x: number, z: number])[]`: corners in order round a shape, closed (the last joins the first). Any shape, bays included
`HeightAt`	`(x: number, z: number) => number`: the ground's height at a point

`smoothOutline(outline, segments = 96)`#

Returns outline with its corners rounded into a smooth closed curve through them, as segments points. Draw an island's shore from a handful of points.

`Slab`#

Flat ground in any shape, standing up from its position: an island, a lawn, a deck round a pool. Its top is at position.y + height.

Prop	Type	Default	Description
`outline`	`Outline`	required	Its shape on the ground
`height`	metres	`0.2`	How thick
`holes`	`Outline[]`	none	Shapes cut through it
`bevel`	metres	`0.03`	Rounding of its edges

Plus every shape prop: material, color, onPress, name, visible, shadows, transforms, ref (Objects). Changing the outline rebuilds it.

`Terrain`#

A tile of ground of any height, cut square at its edges like a slice of the earth, coloured point by point.

Prop	Type	Default	Description
`size`	`[width, depth]`	required	Along x and z, centred on its position
`height`	`HeightAt`	required	The ground's height at each point
`color`	`(x, z, y) => colour`	white	The top's colour at each point
`sides`	`(y) => colour`	the top's edge colour	The cut's colour at each height: layers
`spacing`	metres	`0.1`	Distance between its points
`base`	metres	0.2 below its lowest point	How far down its sides reach
`roughness`	0–1	`0.9`
`water`	object	none	Water in it up to `level`: see below
`name`, `ref`

Plus transforms and shadow props.

water:

Field	Default	Description
`level`	required	Height of the water's surface
`top`		Colour of the water's depth at the surface, seen in the cut
`deep`		Colour further down
`fade`	`1`	Metres of depth until it is all `deep`
`clarity`	`0.25`	How much of what is behind shows through, 0–1

It draws the water's depth in the cut only; add a <Water> of the same size at level for the surface.

`Water`#

A water surface: the sea, a pool, a pond. It lies level and is moved, not turned.

Prop	Type	Default	Description
`size`	`[width, depth]`	required	Centred on its position
`position`	`Vec3` or shared value	`[0, 0, 0]`	Its middle; `y` is the water level
`waves`	`Waves`	still	From `useWaves`, shared with floating things
`shore`	`ShoreField`	none	From `useShore`: shallows, deep water and foam
`shallow`	colour	bright turquoise	Over the shallows, or looked into from above
`deep`	colour	azure blue	Out at sea, or seen at a slant
`beach`	colour	pale aqua	Where it laps the sand (with `shore`)
`foam`	colour or `false`	white	Foam along the shore
`caustics`	0–1	`0.6`	Light dancing on the bottom of the shallows (with `shore`)
`glow`	number	`0.35`	How much it glows with its own colour
`clarity`	0–1	`0`	How much you see through it
`sparkle`	0–1	`0.5`	A pale glint on the crests
`spacing`	metres	`0.25`	Distance between its points: finer carries shorter waves
`ref`	`Ref<SceneObject>`

While it has waves, the scene keeps rendering.

`useWaves(options?)`#

Returns a Waves object, made once and changed live when the options change (no new shader).

`WaveOptions`	Default	Description
`height`	`0.06`	Crest height above the middle. `0`: still water
`length`	`2.5`	Crest to crest
`speed`	`0.8`	Metres per second
`direction`	`0`	Degrees round the vertical; `0` travels towards +x

Waves methods, for your own floating things in useFrame:

Method	Returns
`heightAt(x, z)`	The water's height above its level at that point, now
`slopeAt(x, z)`	`[alongX, alongZ]`: how steeply it rises there, to tilt what floats
`set(options)`	Changes the waves

`useShore(land, bounds, options?)`#

Measures how far each point of bounds is from land, once (again when the inputs change). Returns a ShoreField for <Water shore>.

Argument	Type	Description
`land`	`Outline[]` or `(x, z) => boolean`	The land's outlines, or a test (true on land). Keep a test function stable
`bounds`	`[minX, minZ, maxX, maxZ]`	The area measured. Past it, water counts as far from shore
`options.reach`	metres, default `4`	How far out the water deepens from the shore
`options.size`	texels, default `128`	The field's resolution

ShoreField: { texture, bounds, reach }.

Placement on ground and water#

<Placement areas zones snaps> and <Placeable on="water">: see Placement reference.

Ground and water guide.
Core reference: createTerrainGeometry, createWaterMaterial, createShoreField, createSlabGeometry.

import { Slab, smoothOutline, Terrain, useShore, useWaves, Water } from "@apricot/react";
import type { HeightAt, Outline, ShoreField, SlabProps, TerrainProps, WaterProps, WaveOptions, Waves } from "@apricot/react";

All distances are metres. Shapes on the ground are outlines in the x–z plane.

Types#

Type	Definition
`Outline`	`readonly (readonly [x: number, z: number])[]`: corners in order round a shape, closed (the last joins the first). Any shape, bays included
`HeightAt`	`(x: number, z: number) => number`: the ground's height at a point

`smoothOutline(outline, segments = 96)`#

Returns outline with its corners rounded into a smooth closed curve through them, as segments points. Draw an island's shore from a handful of points.

`Slab`#

Flat ground in any shape, standing up from its position: an island, a lawn, a deck round a pool. Its top is at position.y + height.

Prop	Type	Default	Description
`outline`	`Outline`	required	Its shape on the ground
`height`	metres	`0.2`	How thick
`holes`	`Outline[]`	none	Shapes cut through it
`bevel`	metres	`0.03`	Rounding of its edges

Plus every shape prop: material, color, onPress, name, visible, shadows, transforms, ref (Objects). Changing the outline rebuilds it.

`Terrain`#

A tile of ground of any height, cut square at its edges like a slice of the earth, coloured point by point.

Prop	Type	Default	Description
`size`	`[width, depth]`	required	Along x and z, centred on its position
`height`	`HeightAt`	required	The ground's height at each point
`color`	`(x, z, y) => colour`	white	The top's colour at each point
`sides`	`(y) => colour`	the top's edge colour	The cut's colour at each height: layers
`spacing`	metres	`0.1`	Distance between its points
`base`	metres	0.2 below its lowest point	How far down its sides reach
`roughness`	0–1	`0.9`
`water`	object	none	Water in it up to `level`: see below
`name`, `ref`

Plus transforms and shadow props.

water:

Field	Default	Description
`level`	required	Height of the water's surface
`top`		Colour of the water's depth at the surface, seen in the cut
`deep`		Colour further down
`fade`	`1`	Metres of depth until it is all `deep`
`clarity`	`0.25`	How much of what is behind shows through, 0–1

It draws the water's depth in the cut only; add a <Water> of the same size at level for the surface.

`Water`#

A water surface: the sea, a pool, a pond. It lies level and is moved, not turned.

Prop	Type	Default	Description
`size`	`[width, depth]`	required	Centred on its position
`position`	`Vec3` or shared value	`[0, 0, 0]`	Its middle; `y` is the water level
`waves`	`Waves`	still	From `useWaves`, shared with floating things
`shore`	`ShoreField`	none	From `useShore`: shallows, deep water and foam
`shallow`	colour	bright turquoise	Over the shallows, or looked into from above
`deep`	colour	azure blue	Out at sea, or seen at a slant
`beach`	colour	pale aqua	Where it laps the sand (with `shore`)
`foam`	colour or `false`	white	Foam along the shore
`caustics`	0–1	`0.6`	Light dancing on the bottom of the shallows (with `shore`)
`glow`	number	`0.35`	How much it glows with its own colour
`clarity`	0–1	`0`	How much you see through it
`sparkle`	0–1	`0.5`	A pale glint on the crests
`spacing`	metres	`0.25`	Distance between its points: finer carries shorter waves
`ref`	`Ref<SceneObject>`

While it has waves, the scene keeps rendering.

`useWaves(options?)`#

Returns a Waves object, made once and changed live when the options change (no new shader).

`WaveOptions`	Default	Description
`height`	`0.06`	Crest height above the middle. `0`: still water
`length`	`2.5`	Crest to crest
`speed`	`0.8`	Metres per second
`direction`	`0`	Degrees round the vertical; `0` travels towards +x

Waves methods, for your own floating things in useFrame:

Method	Returns
`heightAt(x, z)`	The water's height above its level at that point, now
`slopeAt(x, z)`	`[alongX, alongZ]`: how steeply it rises there, to tilt what floats
`set(options)`	Changes the waves

`useShore(land, bounds, options?)`#

Measures how far each point of bounds is from land, once (again when the inputs change). Returns a ShoreField for <Water shore>.

Argument	Type	Description
`land`	`Outline[]` or `(x, z) => boolean`	The land's outlines, or a test (true on land). Keep a test function stable
`bounds`	`[minX, minZ, maxX, maxZ]`	The area measured. Past it, water counts as far from shore
`options.reach`	metres, default `4`	How far out the water deepens from the shore
`options.size`	texels, default `128`	The field's resolution

ShoreField: { texture, bounds, reach }.

Placement on ground and water#

<Placement areas zones snaps> and <Placeable on="water">: see Placement reference.

Ground and water guide.
Core reference: createTerrainGeometry, createWaterMaterial, createShoreField, createSlabGeometry.

Types#

smoothOutline(outline, segments = 96)#

Slab#

Terrain#

Water#

useWaves(options?)#

useShore(land, bounds, options?)#

Placement on ground and water#

Related#

Ground and water

Types#

smoothOutline(outline, segments = 96)#

Slab#

Terrain#

Water#

useWaves(options?)#

useShore(land, bounds, options?)#

Placement on ground and water#

Related#

`smoothOutline(outline, segments = 96)`#

`Slab`#

`Terrain`#

`Water`#

`useWaves(options?)`#

`useShore(land, bounds, options?)`#

`smoothOutline(outline, segments = 96)`#

`Slab`#

`Terrain`#

`Water`#

`useWaves(options?)`#

`useShore(land, bounds, options?)`#