Ocean

Show Private

The module itself: require(game.ReplicatedStorage.Ocean). Everything you need day to day is here: weather, zones, water queries, water events and tag helpers. The other classes are the pieces it is built from; reach for them only when you need something lower level.

local Ocean = require(game.ReplicatedStorage.Ocean)

-- server: define a weather and cross-fade the whole sea into it over 20 seconds
Ocean:CreateWeather("Rough", Ocean.Presets.Ocean["Pirate Seas"])
Ocean:SetWeather("Rough", 20)

-- anywhere: where is the surface right now?
local y = Ocean:GetHeight(boat.Position)

Settings are attributes on the module (see Settings); the server owns them and they replicate. The bootstrap scripts the plugin installs call Ocean.Init once on the server and once on every client, so you never have to.

Properties

Settings

</>

Ocean.Settings: Settings

The settings spec and accessors.

Waves

</>

Ocean.Waves: Waves

The wave function: heights, displacement, obstacles.

Weather

</>

Ocean.Weather: Weather

The replicated weather state.

Presets

</>

Ocean.Presets: Presets

Ready-made physics, looks and whole oceans.

Regions

</>

Ocean.Regions: Regions

Dry regions (OceanDry).

Tracker

</>

Ocean.Tracker: Tracker

Per-instance water state.

Zones

</>

Ocean.Zones: Zones

Tagged OceanZone areas.

Tags

</>

Ocean.Tags: {

Float: string,

Obstacle: string,

Dry: string,

Track: string

}

The current tag names (they follow the FloatTag, ObstacleTag, DryTag and TrackTag settings).

EnteredWater

</>

Ocean.EnteredWater: RBXScriptSignal<Instance>

Fires when a tracked instance or character goes from dry to touching the water.

ExitedWater

</>

Ocean.ExitedWater: RBXScriptSignal<Instance>

Fires when a tracked instance or character leaves the water entirely.

WentUnderWater

</>

Ocean.WentUnderWater: RBXScriptSignal<Instance>

Fires when a tracked instance or character becomes fully submerged.

WentAboveWater

</>

Ocean.WentAboveWater: RBXScriptSignal<Instance>

Fires when a fully submerged instance or character surfaces again.

Functions

Init

</>

Ocean.Init() → ()

Starts the ocean on this side: reads the settings, compiles the weather, starts obstacle and zone tracking, water events and (on a client) the renderer. Safe to call more than once. The installed OceanServer and OceanClient scripts already do this.

CreateWeather

This item only works when running on the server. Server

</>

Ocean:CreateWeather(

name: string,--

any name except "Default"

overrides: {[string]: any}--

setting name to value

) → ()

Defines (or redefines) a named weather: a table of setting overrides, keyed by setting name. Only settings marked as weather settings count (waves, colours, foam, spray, the underwater tint); anything else in the table is ignored, so an entry of Presets.Ocean can be passed straight in.

Ocean:CreateWeather("Storm", Ocean.Presets.Ocean["Pirate Seas"])
Ocean:CreateWeather("Glassy", { WaveHeight = 0.2, FoamOpacity = 0 })

SetWeather

This item only works when running on the server. Server

</>

Ocean:SetWeather(

name: string,

transition: number?--

seconds to fade over (default 0)

) → ()

Cross-fades the whole sea to a weather created with Ocean:CreateWeather, or back to "Default" (the module's own attribute values). The fade is a function of server time, so every client and the server physics stay in step.

GetWeather

</>

Ocean:GetWeather() → string

The name of the weather the whole sea is in (or fading toward).

CreateZone

This item only works when running on the server. Server

</>

Ocean:CreateZone(

name: string,

zone: {

Position: Vector3,

Radius: number,

Blend: number?,

Weather: string

}--

Blend defaults to 35% of the radius

) → ()

Creates a scripted weather zone: a disc of ocean with its own weather, blended into the surrounding sea across Blend studs at its rim. For zones built in Studio, tag a part OceanZone instead (see Zones).

SetZoneWeather

This item only works when running on the server. Server

</>

Ocean:SetZoneWeather(

name: string,--

the zone

weatherName: string,

transition: number?--

seconds (default 0)

) → ()

Cross-fades one scripted zone to another weather.

RemoveZone

This item only works when running on the server. Server

</>

Ocean:RemoveZone(name: string) → ()

Removes a scripted zone; the global weather takes over there.

GetHeight

</>

Ocean:GetHeight(position: Vector3) → number

World Y of the surface directly above or below the point, right now. Works on both sides and accounts for weather, zones, obstacles and FlatSea.

GetWaterHeight

</>

Ocean:GetWaterHeight(position: Vector3) → number

Alias of Ocean:GetHeight.

GetDepth

</>

Ocean:GetDepth(position: Vector3) → number

How far below the surface the point is. Negative means above the water. Ignores dry regions.

IsUnderWater

</>

Ocean:IsUnderWater(position: Vector3) → boolean

True when the point is below the surface and not inside a dry region.

IsAboveWater

</>

Ocean:IsAboveWater(position: Vector3) → boolean

The opposite of Ocean:IsUnderWater.

IsDry

</>

Ocean:IsDry(position: Vector3) → boolean

True inside an OceanDry region (a submarine interior, an underwater room).

GetSurfaceNormal

</>

Ocean:GetSurfaceNormal(position: Vector3) → Vector3

The surface normal at the point, sampled from the height field. Use it to align boats, decals or spray.

GetWaterState

</>

Ocean:GetWaterState(instance: Instance) → Tracker.State?

The current water state of a tracked instance (tagged OceanFloat or OceanTrack, or a player character), or nil if it is not tracked.

IsInWater

</>

Ocean:IsInWater(instance: Instance) → boolean

True when any part of a tracked instance is in the water.

GetInstancesInWater

</>

Ocean:GetInstancesInWater() → {Instance}

Every tracked instance that is currently in the water.

AddFloat

</>

Ocean:AddFloat(part: BasePart) → ()

Tags a part to float (the plugin's Buoyancy addon does the physics). Plain CollectionService tags underneath, so part:AddTag("OceanFloat") does the same.

RemoveFloat

</>

Ocean:RemoveFloat(part: BasePart) → ()

Removes the float tag.

AddObstacle

</>

Ocean:AddObstacle(instance: Instance) → ()

Tags a part or model as an obstacle: the sea calms against it. The OceanShore and OceanCalmness attributes on the instance tune the effect.

RemoveObstacle

</>

Ocean:RemoveObstacle(instance: Instance) → ()

Removes the obstacle tag.

AddDryRegion

</>

Ocean:AddDryRegion(instance: Instance) → ()

Tags a part or model as a dry region: no water inside its box.

RemoveDryRegion

</>

Ocean:RemoveDryRegion(instance: Instance) → ()

Removes the dry-region tag.

Track

</>

Ocean:Track(instance: Instance) → ()

Gets water events and Ocean:GetWaterState for an instance without floating it.

Untrack

</>

Ocean:Untrack(instance: Instance) → ()

Stops tracking an instance.

GetZoneAt

</>

Ocean:GetZoneAt(position: Vector3) → string?

The name of the OceanZone whose box contains the point, or nil.

GetZones

</>

Ocean:GetZones() → {string}

The names of every OceanZone in the place.

GetWeatherAt

</>

Ocean:GetWeatherAt(position: Vector3) → string

The name of the weather with the most influence at a point, zones included.