Performance
The sea is built to hold a high frame rate on ordinary clients. This page explains what costs what, so you can spend where it shows.
Loading
Physics comes first. Ocean.Init sets up the waves and their physics and returns at once; the sea's meshes are built in the background after the game has loaded, with a plain water picture covering the gap and the wave physics (heights, buoyancy, swimming) already running. The FFT workers load one after another, each doing its heavy set-up off the main thread, and the adaptive quality does not count the load's own frames against the sea.
How it is drawn
- The surface near the camera is a small set of skinned
EditableMeshtiles. Each vertex hangs on a bone, and the module moves bones every update; moving a bone is far cheaper than rewriting the mesh. - The camera sits at the corner of a 32-cell block, so only four tiles are ever animated, and the mesh never has to move when you walk: a root bone carries the re-centring.
- Past the animated ring, one static mesh with a flat skirt runs out to
RenderDistance. - Foam is a fine plain mesh over the inner area with a soft edge; the film is one translucent skinned mesh. Both are optional layers.
- The wave function is Gerstner math with fixed-size arrays and no allocation in the hot loop. Foam and film sit on the surface's own vertices and reuse its result there instead of summing the waves again.
In a running game the drawing runs in parallel: four Actors each take a share of the surface's points and work out its waves, foam and film on their own threads, then write their bones. The main thread only publishes the frame and pays for those writes. The OceanSurface model's UpdateMs attribute is the main thread's cost, and DrawMs the slowest worker's, which runs alongside the rest of the frame. The Edit-mode preview in Studio draws on the main thread, as Actors don't run there.
With WaveMode set to FFT the sea is a simulated wave spectrum drawn as a clipmap of about 130 small meshes with 2 stud cells near the camera, so it costs more than the Gerstner sea. It runs in parallel too, and the sea is simulated once: an Actor per cascade steps the FFT and hands the result to four Actors that each work out every vertex's waves, colour and UV for a share of the tiles, then write those tiles' meshes. The same result goes to the main thread 30 times a second for the height queries buoyancy and swimming make, so a client's main thread steps no simulation; the server steps its own, heights only, 20 times a second. Only what changed is written: a vertex's colour when it changes, and the levels past 250 studs every other frame. What cannot go parallel stays on the main thread: the mesh writes, the largest part of an FFT frame. ShowLODColors colours each level of detail so you can see the clipmap.
Everything updates at UpdateRate (60 per second by default), not at the render rate, so a 240 fps client does no more mesh work than a 60 fps one. Vertices outside the camera's view (with a margin for their waves) are updated a quarter at a time, one quarter each update, so each is at most four updates old when the camera turns onto it. The outer ring updates every other update. With FilmOpacity at 0 the film is not built at all.
What to turn
| Want | Turn |
|---|---|
| The biggest single saving | Quality = Fast (fewer animated vertices, no film, foam every fourth update) |
| Fewer updates per second | UpdateRate (30 is fine for slow seas) |
| Smaller animated area | InnerCells down, or CellSize up |
| No foam | FoamStyle = None |
| No film | Highlights off |
| Flat lighting | Lit off draws the water unlit |
| A still sea | StaticWaves builds the surface once and stops the clock; FlatSea removes the waves entirely |
Ocean presets set sensible values for their look; Island (the default) is the balanced one.
Streaming
When streaming loads a new area, Roblox rebuilds every skinned mesh it finds. The module keeps its meshes small and few so that rebuild stays at a few tens of milliseconds rather than a stall.
EditableMesh access
The wave mesh is an EditableMesh, which an experience has to allow in its Experience Settings. Without it the module never builds the mesh: the sea is flat at SeaLevel for visuals and physics alike (the flat water stands in as the surface), and the Output says so once. Ocean.Waves.MeshAvailable() reports which case you are in.
Adaptive quality
Studio has a generous EditableMesh memory budget; phones and low-end PCs do not, so a sea that builds in Studio can be refused in the live game. The renderer handles that on its own with a ladder of rungs:
| Rung | What is drawn |
|---|---|
| full | Everything the settings ask for: four tiles, the horizon mesh, foam, film |
| no film | The surface film is dropped |
| no foam | Foam (and its animated image) is dropped too, and so are the SurfaceDetail ripples |
| one tile | A single tile for the whole lattice, fewer bones |
| half lattice | One tile with half the cells per side |
| quarter lattice | One tile with a quarter of the cells per side |
| flat | No EditableMesh at all: a flat slab in the water's colour |
- If a build is refused, the sea drops to flat at once, so there is always water on screen, and this client's own queries (swimming, the underwater tint) follow the flat surface.
- It then climbs from the bottom, one rung at a time, every few seconds. A refused climb keeps the current rung and doubles the wait before the next try, up to three minutes.
- If a mesh update costs more than 7 ms for three seconds, it steps down a rung and holds off climbing for a while.
So each device settles on the best rung it can hold and keeps probing upward slowly. The rung in use is the Level attribute on the OceanSurface model, and a warning in the Output says when a build was refused. Renderer.SetLevel(n) (0 to 6) forces a rung for testing; the sea climbs back from there.
To give weak devices an easier start, set Quality to Fast, keep FoamStyle off Animated and SurfaceDetail off Ripples: that removes the film, the foam image and the two ripple maps before the ladder has to.
Physics side
Heights, buoyancy and swimming use the waves the mesh can draw. A wave shorter than three of the finest cells (CellSize times the quality's scale) cannot be shown, and fades in up to six; the physics applies the same fade, so things float on the water you see. With large cells (say CellSize 32 on Fast) only the long swell remains, in the mesh and in the physics alike.
Buoyancy samples the surface at up to eight points per floating part every physics step; hundreds of floating parts are fine, thousands are not. Water events are checked once per tracked instance per frame. Obstacles, dry regions and zones are re-read twice a second, so tagging a moving ship as an obstacle costs nothing extra; a dry region's box follows its part every frame, and the water near one is cut every frame.
Measuring
The Performance section has a Run benchmark button: it samples ten seconds of the running sea (a Preview or a playtest) and draws a frame-time graph, the sea's cost over time stacked by part (the main-thread update, mesh writes, the FFT hand-off, the main thread's FFT simulation, the contact foam scan, the underwater effects, and the worker Actors' maths, which runs on other cores), the average of each with its share of the frame, and a verdict on the biggest cost and what lowers it. The rest of the frame (rendering, physics, your other scripts) is shown as "everything else", next to Studio's own CPU and GPU times, so you can tell whether the sea or something else is the bottleneck. The sea times its own parts and writes them to the OceanSurface as Prof_* attributes (milliseconds per frame), so any script can read them too.
It also shows live stats while a preview or playtest runs: frames per second, milliseconds per mesh update, animated and moved vertex counts. The OceanSurface model (under Terrain at runtime, under the Camera in a preview) carries the same numbers as attributes: UpdateMs, Animated, Bones, Tiles, Hitches, WorstMs.