world.sea#

The waves and the colour of your world's ocean — something a script can change live, or glide into over half a minute.

The inspector is the usual way

Most creators never touch this page. Select Ocean in the outliner and every dial here is a slider, with a row of ready-made waters at the top (pool, lake, open sea, storm…). A placed water volume has the same page.

world.sea is the same setting through a script, for what a form cannot do: a storm that rolls in when the bell rings, a sea that calms at dawn.

Luau

local world = require("world") -- Several dials at once; an omitted one keeps its value.world.sea:set({ wind = 12, chop = 0.9 }) -- A storm rolling in over thirty seconds.world.sea:tween({ wind = 18, fetch = 60, foam = 1.4, secs = 30 }) -- A whole water by name.world.sea:preset("calm_sea", 20)

Everything on this page#

How the sea is made · set · tween · preset · get · clear · The fields · Water volumes

How the sea is made#

The wind makes the waves. You do not type a wave height; you say how hard the wind blows (wind) and over how much open water (fetch), and the sea that wind would build is what you get:

a strong wind over a lot of open water gives big, long waves;
the same wind over a lake gives short, choppy ones;
a swell is waves from a storm somewhere else — they arrive long and slow even when the local wind is calm.

Things that float ride these same waves: a crate thrown into a storm is thrown around by the storm everybody is watching.

set#

world.sea:set(opts) → true, or nil, reason

Every field is optional, and an omitted one keeps its value. A field this page does not list is refused with the list, not ignored.

Luau

world.sea:set({ color = "#0b2a38", clarity = 20 })

Needs the world.weather capability — the same one the sky and world:set_weather need.

tween#

world.sea:tween(opts) → true, or nil, reason

The same as set, arrived at over secs seconds (default 4, at most 600). A glide started while another is running continues from what is on screen.

Luau

world.sea:tween({ wind = 3, foam = 0.5, secs = 45 })

preset#

world.sea:preset(name, secs?) → true, or nil, reason

A whole water by name: pool, pond, lake, calm_sea, open_sea, storm, tropical, river, swamp. With secs, it glides there.

get#

world.sea:get() → table

The fields below, as they are set (the end of a glide, not a frame of it). Needs no permission.

clear#

world.sea:clear() → true, or nil, reason

Hands the sea back to the world's own setting.

The fields#

field	what it is	range
`wind`	wind speed, m/s	0 – 20
`wind_dir`	which way it blows, degrees	0 – 360
`fetch`	open water the wind crosses, km	0.05 – 2000
`chop`	crest sharpness	0 – 1
`spread`	0 long parallel crests, 1 a confused sea	0 – 1
`swell`	height of a distant swell, m	0 – 4
`swell_length`	distance between its crests, m	10 – 400
`swell_dir`	which way it travels, degrees	0 – 360
`height`	overall height, 0 = still water	0 – 1.5
`foam`	whitecaps and surf	0 – 2
`glow`	light through the crests	0 – 2
`gloss`	0 matte, 1 a mirror	0 – 1
`clarity`	how far you see into it, m	0.05 – 500
`color`	deep water, `"#rrggbb"`
`shallow`	shallow water and crest light, `"#rrggbb"`

The sea level and the current are not here: where the sea is belongs to your coastline, and a storm does not move it.

Water volumes#

A placed water volume keeps the same dials as properties, which a script sets the way it sets any property:

property	field above
`water_wind`	`wind`
`water_wave_dir`	`wind_dir`, as a direction `{x, z}`
`water_fetch`	`fetch`
`water_chop`	`chop`
`water_spread`	`spread`
`water_swell`	`swell`
`water_swell_len`	`swell_length`
`water_swell_dir`	`swell_dir`, as a direction `{x, z}`
`water_wave_scale`	`height`
`water_foam`	`foam`
`water_glow`	`glow`
`water_gloss`	`gloss`
`water_clarity`	`clarity`
`water_tint`	`color`
`water_shallow`	`shallow`