Skip to main content

Waves

The wave function: Gerstner waves, shared by the renderer (client) and the physics (both sides). It is deterministic in the settings, the weather state and server time, so a height sampled on the server matches the surface a client sees.

Each weather compiles to a set of six waves plus its look. The sea at a point is a weighted sum of whole sets (zones cross-fading at their rims, the global weather for the rest, and two sets while a weather is transitioning), never a blend of wave parameters.

Properties​

SeaLevel​

</>
Waves.SeaLevel: number

The SeaLevel setting, cached.

Sets​

</>
Waves.Sets: {[string]: Set}

Compiled wave sets by weather name.

Version​

</>
Waves.Version: number

Increments every time the sets are recompiled.

Functions​

MeshAvailable​

</>
Waves.MeshAvailable() → boolean

Whether this experience may create EditableMeshes. When it may not, the sea falls back to a flat surface at SeaLevel (as if FlatSea were on) and the wave mesh is never built.

SetLocalFlat​

This item only works when running on the client. Client
</>
Waves.SetLocalFlat(on: boolean) → ()

Makes this client's sea flat (heights, swimming and the tint follow the flat surface it is drawing) without touching the setting. The renderer turns it on while a device cannot hold the wave mesh and off again once it can.

Refresh​

</>
Waves.Refresh() → ()

Recompiles every weather into wave sets from the current settings and weather state. Runs automatically whenever a setting or the weather changes.

RefreshObstacles​

</>
Waves.RefreshObstacles() → ()

Re-reads every OceanObstacle in the workspace. Runs twice a second on its own.

ObstaclesNear​

</>
Waves.ObstaclesNear(
x: number?,
z: number?,
radius: number?
) → {any}

Obstacles whose calming ring touches the circle (x, z, radius); with no arguments, all of them.

Damp​

</>
Waves.Damp(
list: {any},--

from Waves.ObstaclesNear

x: number,
z: number
) → number

The wave multiplier at (x, z) from the given obstacles: 1 in open water, down to 1 - OceanCalmness against an obstacle, easing across its shore ring.

Time​

</>
Waves.Time() → number

The synced wave clock: server time times TimeScale, or 0 while StaticWaves is on.

ZonesNear​

</>
Waves.ZonesNear(
x: number?,
z: number?,
radius: number?
) → {any}

Scripted weather zones whose disc touches the circle (x, z, radius); with no arguments, all of them.

IsBlending​

</>
Waves.IsBlending(
now: number--

workspace:GetServerTimeNow()

) → boolean

True while the global weather is mid-transition.

Gather​

</>
Waves.Gather(
zoneList: {any},--

from Waves.ZonesNear

x: number,
z: number,
now: number--

workspace:GetServerTimeNow()

) → number

Fills Waves.LayerSets and Waves.LayerWeights with the wave sets that apply at (x, z) and returns how many there are. The weights sum to 1.

Displace​

</>
Waves.Displace(
x: number,
z: number,
t: number?,--

wave clock (default: now)

now: number?--

server time (default: now)

) → (
number,--

X offset

number,--

Y offset

number--

Z offset

)

Displacement of the surface point that rests at (x, z): how far it has been pushed along X, up along Y and along Z. Zero everywhere while FlatSea is on.

Height​

</>
Waves.Height(
x: number,
z: number,
t: number?,--

wave clock (default: now)

now: number?--

server time (default: now)

) → number

World Y of the surface above (x, z). Gerstner waves move points sideways, so this iterates to find the rest point that lands on (x, z); the answer is within a quarter stud. Ocean:GetHeight calls this.

LookNumber​

</>
Waves.LookNumber(
name: string,
x: number,
z: number
) → number

One numeric weather setting blended at a point, for example Waves.LookNumber("SplashRate", x, z). "MaxAmp" gives the tallest possible crest there.

SelfTest​

</>
Waves.SelfTest() → string

Checks that Waves.Height inverts Waves.Displace and that layer weights sum to 1. Run it from the command bar: require(game.ReplicatedStorage.Ocean.Waves).SelfTest().

Show raw api
{
    "functions": [
        {
            "name": "MeshAvailable",
            "desc": "Whether this experience may create EditableMeshes. When it may not, the sea falls back to a\nflat surface at `SeaLevel` (as if `FlatSea` were on) and the wave mesh is never built.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 134,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "SetLocalFlat",
            "desc": "Makes this client's sea flat (heights, swimming and the tint follow the flat surface it is\ndrawing) without touching the setting. The renderer turns it on while a device cannot hold the\nwave mesh and off again once it can.",
            "params": [
                {
                    "name": "on",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "static",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 154,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Refresh",
            "desc": "Recompiles every weather into wave sets from the current settings and weather state. Runs\nautomatically whenever a setting or the weather changes.",
            "params": [],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 167,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "RefreshObstacles",
            "desc": "Re-reads every `OceanObstacle` in the workspace. Runs twice a second on its own.",
            "params": [],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 208,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "ObstaclesNear",
            "desc": "Obstacles whose calming ring touches the circle `(x, z, radius)`; with no arguments, all of them.",
            "params": [
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "radius",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ any }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 254,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Damp",
            "desc": "The wave multiplier at `(x, z)` from the given obstacles: 1 in open water, down to\n`1 - OceanCalmness` against an obstacle, easing across its shore ring.",
            "params": [
                {
                    "name": "list",
                    "desc": "from [Waves.ObstaclesNear]",
                    "lua_type": "{ any }"
                },
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 280,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Init",
            "desc": "",
            "params": [],
            "returns": [],
            "function_type": "static",
            "private": true,
            "source": {
                "line": 313,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Stop",
            "desc": "",
            "params": [],
            "returns": [],
            "function_type": "static",
            "private": true,
            "source": {
                "line": 328,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Time",
            "desc": "The synced wave clock: server time times `TimeScale`, or 0 while `StaticWaves` is on.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 341,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "ZonesNear",
            "desc": "Scripted weather zones whose disc touches the circle `(x, z, radius)`; with no arguments, all of them.",
            "params": [
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "radius",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ any }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 360,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "IsBlending",
            "desc": "True while the global weather is mid-transition.",
            "params": [
                {
                    "name": "now",
                    "desc": "`workspace:GetServerTimeNow()`",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 381,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Gather",
            "desc": "Fills `Waves.LayerSets` and `Waves.LayerWeights` with the wave sets that apply at `(x, z)` and\nreturns how many there are. The weights sum to 1.",
            "params": [
                {
                    "name": "zoneList",
                    "desc": "from [Waves.ZonesNear]",
                    "lua_type": "{ any }"
                },
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "now",
                    "desc": "`workspace:GetServerTimeNow()`",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 414,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Displace",
            "desc": "Displacement of the surface point that rests at `(x, z)`: how far it has been pushed along X, up\nalong Y and along Z. Zero everywhere while `FlatSea` is on.",
            "params": [
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "t",
                    "desc": "wave clock (default: now)",
                    "lua_type": "number?"
                },
                {
                    "name": "now",
                    "desc": "server time (default: now)",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "X offset",
                    "lua_type": "number"
                },
                {
                    "desc": "Y offset",
                    "lua_type": "number"
                },
                {
                    "desc": "Z offset",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 475,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Height",
            "desc": "World Y of the surface above `(x, z)`. Gerstner waves move points sideways, so this iterates to find\nthe rest point that lands on `(x, z)`; the answer is within a quarter stud. [Ocean:GetHeight] calls this.",
            "params": [
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "t",
                    "desc": "wave clock (default: now)",
                    "lua_type": "number?"
                },
                {
                    "name": "now",
                    "desc": "server time (default: now)",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 501,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "LookNumber",
            "desc": "One numeric weather setting blended at a point, for example `Waves.LookNumber(\"SplashRate\", x, z)`.\n`\"MaxAmp\"` gives the tallest possible crest there.",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 530,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "SelfTest",
            "desc": "Checks that [Waves.Height] inverts [Waves.Displace] and that layer weights sum to 1. Run it from the\ncommand bar: `require(game.ReplicatedStorage.Ocean.Waves).SelfTest()`.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 547,
                "path": "src/Ocean/Waves.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "SeaLevel",
            "desc": "The `SeaLevel` setting, cached.",
            "lua_type": "number",
            "source": {
                "line": 36,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Sets",
            "desc": "Compiled wave sets by weather name.",
            "lua_type": "{ [string]: Set }",
            "source": {
                "line": 41,
                "path": "src/Ocean/Waves.luau"
            }
        },
        {
            "name": "Version",
            "desc": "Increments every time the sets are recompiled.",
            "lua_type": "number",
            "source": {
                "line": 46,
                "path": "src/Ocean/Waves.luau"
            }
        }
    ],
    "types": [],
    "name": "Waves",
    "desc": "The wave function: Gerstner waves, shared by the renderer (client) and the physics (both sides).\nIt is deterministic in the settings, the weather state and server time, so a height sampled on the\nserver matches the surface a client sees.\n\nEach weather compiles to a *set* of six waves plus its look. The sea at a point is a weighted sum of\nwhole sets (zones cross-fading at their rims, the global weather for the rest, and two sets while a\nweather is transitioning), never a blend of wave parameters.",
    "source": {
        "line": 31,
        "path": "src/Ocean/Waves.luau"
    }
}