Skip to main content

Settings reference

Every setting is an attribute on ReplicatedStorage.Ocean. The plugin panel edits them; scripts can too (server side): Ocean:SetAttribute("WaveHeight", 1.5) or, with validation and clamping, Settings.Set. Settings marked weather can be overridden per weather (see Scripting); settings marked rebuilds mesh rebuild the surface when changed.

General Physics​

SettingTypeDefaultRangeWhat it does
SeaLevelnumber0-500 to 500World Y of the resting surface
FlatSeabooleanfalseNo waves at all: the sea is the flat water at SeaLevel, in the water's colour and material, with the underwater tint. Buoyancy, swimming and water events work on that flat surface
SeafloorHeightnumber-436-10000 to 10000World Y of the seafloor slab the plugin places (Flat Water and Seafloor). Kept under the deepest wave trough and that much above the fallen-parts height

Wave Physics​

SettingTypeDefaultRangeWhat it does
WaveModechoiceGerstnerGerstner, FFTGerstner = six waves set by the Wave1 to Wave6 settings; FFT = a simulated wave spectrum set by the FFT settings, with crests that sharpen, hook over and break (rebuilds mesh)
WaveGravitynumber605 to 2000Wave speed: higher is faster (weather)
WaveHeightnumber10 to 12Size of the whole sea: every wave's height and length times this, so giant waves keep their shape (weather)
TimeScalenumber10 to 3Overall wave speed: the wave clock runs this many times faster
UseWindbooleanfalseWaves follow workspace.GlobalWind: the Wave angles become offsets from the wind direction

FFT Waves​

Used when WaveMode is FFT.

SettingTypeDefaultRangeWhat it does
FFTWaveHeightnumber90.2 to 40FFT mode: the significant wave height in studs (the average of the highest third of the waves)
FFTWindSpeednumber253 to 60FFT mode: wind speed in studs per second; a stronger wind makes longer, faster waves
FFTWindAnglenumber30-180 to 180FFT mode: the direction the wind blows the waves, in degrees (0 = +X, 90 = +Z)
FFTChoppinessnumber1.30 to 2FFT mode: how far crests lean over and sharpen; higher hooks and breaks them (foam forms where they fold)
FFTFoamnumber10 to 1FFT mode: how much of the surface can foam where the waves fold (0 = none)

Buoyancy Physics​

These need the Buoyancy addon.

SettingTypeDefaultRangeWhat it does
BuoyancyEnabledbooleantrueFloats parts tagged "OceanFloat"
WaterDensitynumber10.1 to 5Density of the water: parts denser than this sink, lighter ones float
LinearDragnumber1.50 to 10Resistance to floating parts moving through the water
AngularDragnumber20 to 10Resistance to floating parts turning
MaxLiftnumber1.31 to 6Cap on total lift, as a multiple of the part's weight
BuoyancyFalloffDepthnumber401 to 500Lift fades from full at the surface to DeepBuoyancy this many studs down (submarines)
DeepBuoyancynumber0.70 to 1Lift multiplier once deeper than the falloff depth

Visuals​

SettingTypeDefaultRangeWhat it does
ShallowColorcolourrgb(18, 98, 108)Crests (weather)
DeepColorcolourrgb(12, 84, 92)Troughs (weather)
FoamColorcolourrgb(255, 255, 255)Colour of the crest foam (weather)
NightBrightnessnumber0.550 to 1Colour multiplier once the sun is down
UnderwaterEnabledbooleantrueTint the view while the camera is under the surface
UnderwaterTintcolourrgb(12, 84, 92)Underwater tint colour (weather)
UnderwaterOpacitynumber0.750 to 1How strongly the underwater tint covers the view (0 = none) (weather)
UnderwaterBlurnumber40 to 24How much the view blurs while the camera is under the surface (0 = none)
UnderwaterFocusnumber600 to 500Underwater, how far from the camera (studs) things stay in focus before the view blurs into the distance (0 = no depth of field)
Reflectancenumber0.150 to 1How much of the sky the surface mirrors
WaterTransparencynumber00 to 1How see-through the water surface is: 0 = opaque, 1 = invisible
WaveShadingnumber10 to 2How strongly the waves' slopes catch the light: faces toward the sun brighten, the far sides darken (0 = lit like a flat sheet)
SurfaceDetailchoiceRipplesRipples, Custom, NoneSmall ripples lit per pixel, finer than the waves: Ripples = the built-in animated ones; Custom = a SurfaceAppearance named WaterSurface you put inside the Ocean module; None = plain WaterMaterial
RippleStrengthnumber0.040 to 1How choppy the Ripples are (their average slope)
WaterRoughnessnumber0.10 to 1With Ripples: 0 = glassy, sharp sun glints and sky reflection; 1 = matte
FoamStylechoiceSolidAnimated, Texture, Solid, NoneCrest foam: Animated = the built-in moving rings; Texture = your FoamTexture image; Solid = plain FoamColor; None = no foam layer (rebuilds mesh)
FoamStartnumber0.04-1 to 1Crest height (0 to 1 of the tallest crest) where foam begins (weather)
FoamFullnumber0.58-1 to 1Crest height where the foam is fully opaque (weather)
FoamOpacitynumber0.750 to 1Opacity of the crest foam (weather)
WebOpacitynumber00 to 1Semi-transparent animated foam over the whole near surface, not only the crests (0 = off) (weather)
ContactFoambooleantrueFFT mode: foam in the water around every part crossing it (pillars, hulls, rocks), joining the part it touches; a part or model opts out with the attribute OceanContactFoam = false
ContactFoamWidthnumber3.50.5 to 12How far the foam reaches out from the part (studs). It is part of the water surface, so only the FFT sea has it: the Gerstner sea's mesh is too coarse to hold a ring that small
ContactFoamOpacitynumber0.80 to 1How strong the foam is against the part
SplashRatenumber20 to 40Crest spray bursts per second near the camera (drawn by the WaterSplash addon) (weather)
SplashHeightnumber0.40 to 1Crest height (0 to 1 of the tallest crest) a wave must reach to throw spray (weather)
FilmOpacitynumber00 to 1Translucent skin on the surface in the water's colour: things crossing it get a clear waterline (weather)
WaterMaterialstringSmoothPlasticA material name (SmoothPlastic, Foil, Glass, Ice...) or one of the place's MaterialVariants; an unknown name lands on the closest
WaterTexturestring(blank)Image asset id tiled over the water (multiplies the colour), or blank for none
FoamTexturestring(blank)Image asset id for the crest foam (white with alpha), used when FoamStyle is Texture

Performance​

SettingTypeDefaultRangeWhat it does
QualitychoiceRegularFast, Regular, RealisticFast, Regular or Realistic: how many vertices animate and how often foam and film update (rebuilds mesh)
StaticWavesbooleanfalseThe waves hold still: the wave clock stops, so the surface (and everything floating on it) is built once and left
DynamicLightingbooleantrueThe water darkens with the sun (NightBrightness) as the day passes; off keeps daytime colours
DynamicColorsbooleantrueThe crest foam follows the waves every update; off writes it once
LitbooleantrueThe scene lights the water: shadows and the sun's highlights fall on it. Off draws it in flat colour
HighlightsbooleantrueThe translucent skin layer over the near water: the surface sheen and the waterline on things crossing it (rebuilds mesh)
ShowLODColorsbooleanfalseFFT mode: colours the sea by level of detail, one colour per level (red is the finest), blending into the next level's colour where its vertices merge
AdaptiveQualitybooleantrueThe sea lowers its detail (foam, ripples, then how much of it is animated) while the frame rate is under TargetFPS, and raises it again once the frame rate is well above
TargetFPSnumber3010 to 120The frame rate AdaptiveQuality tries to keep
UpdateRatenumber6015 to 240How many times per second the surface mesh is updated
CellSizenumber82 to 32Finest quad size (studs) (rebuilds mesh)
InnerCellsnumber244 to 44Full-detail cells each side (inner + outer at most 49) (rebuilds mesh)
OuterCellsnumber254 to 45Coarser cells past the inner ring, each Growth times larger than the last (rebuilds mesh)
Growthnumber1.21.02 to 5How much larger each outer cell is than the one before it; the moving sea never reaches past a quarter of RenderDistance (rebuilds mesh)
RenderDistancenumber400002000 to 100000How far the sea is drawn from the camera (studs): the flat horizon skirt reaches this far (rebuilds mesh)

Tags​

The tag names the module listens for. Rename them to match tags your game already uses.

SettingTypeDefaultWhat it does
FloatTagstringOceanFloatTag: unanchored parts float
ObstacleTagstringOceanObstacleTag: the sea goes idle against it
DryTagstringOceanDryTag: the surface is cut out of it
TrackTagstringOceanTrackTag: water events only
ZoneTagstringOceanZoneTag: an area with its own sea, physics and lighting

Wave1 to Wave6​

The sea is the sum of six Gerstner waves. Each has three settings, all of them weather settings.

SettingTypeRangeWhat it does
Wave{i}Anglenumber-180 to 180Direction this wave travels (degrees)
Wave{i}Lengthnumber10 to 1000Distance between crests (studs)
Wave{i}Steepnessnumber0 to 0.5How peaked this wave is (0 = flat)

Defaults (angle, length, steepness):

WaveAngleLengthSteepness
115°3200.1
2-30°1900.12
350°1200.15
4-65°800.15
5100°560.12
6-10°480.1

Keep the sum of the steepness values under about 1, or crests fold over into loops; WaveHeight scales wavelength with height, so it never changes steepness. Wavelengths shorter than about six times CellSize are smoothed away by the mesh, though the physics still feels them.