Guide
Minecraft water shaders: what the water engine does
By Ryleigh Newman · Published
The water in Rockstar Shaders is not a moving texture. It is a surface with its own engine: a wind-driven wave spectrum that grows with how much open water there is, so a pond ripples and an ocean swells; a simulated ripple field that carries rain rings, boat wakes and your own steps through the shallows; reflections traced against the world when the screen cannot supply them; caustics on the bed and, under water, on the eye; surf that shoals toward a beach; and falling water with a plunge pool under it. This page explains each part in plain words and says what is on by default and what is not.
I made Rockstar Shaders, a Fabric mod for Minecraft Java 26.3 on Apple Silicon Macs, and the water is the part I have spent the most time on and the part that costs the most to draw. Everything below is the current code, including the two things that are compiled out at the defaults, because a page about realistic water should say where the white water went.
Download free (1.0.0) Modrinth (pending)Minecraft 26.3, Fabric, macOS on Apple silicon. Install guide. Releases and bug reports on GitHub.
Waves that depend on how much water there is
A real sea is rougher than a real pond because the wind has had a longer run over it. The engine models that with a fetch map: a top-down map of how much open water surrounds each point. The wave spectrum is a directional, wind-driven ladder of up to five wind-sea rungs, and each point gets as much of the ladder as its fetch allows. A pond a few blocks across carries small ripples. A lake carries chop. An ocean carries swell, because only an ocean has the fetch for it. Nothing is chosen per biome; the shape of the water decides.
Below the wind sea there is a detail band of up to three finer rungs, the 5 to 50 cm ripples that make a surface read as wet at close range. Two settings on the Water page control the ladder: Wave octaves, 2 to 5, default 5, which the tip calls the calibrated sea, and Detail rungs, 0 to 3, default 3. Fewer of either is cheaper and smoother. Crests hide troughs through a parallax march, Parallax steps, default 12, so a wave in front of you occludes the one behind it instead of both drawing flat.
The ripple field
The waves above are analytic; they never react to anything. The ripple field does. It is a simulated grid of 512 cells, each 6.25 cm, 32 meters across, centerd on the camera and moving with it. Rain drops put rings into it. Falling water puts a churn under the fall. The player walking through shallows, and a boat, put a wake into it. It is advanced every frame by the damped wave equation, so rings spread, cross and die out the way rings do, and the foam term rides on top of it.
Because integrating a flat surface still costs 3.4 to 4.0 ms a frame at my window size, the field goes to sleep 18 seconds after its last disturbance and costs nothing until the next drop. The switch is Ripple simulation on the Water page, on by default. One limit to know: the field restarts from flat whenever the settings screen rebuilds the renderer, which happens each time a tune setting is changed and the page is closed with Done.
Reflections: the screen first, then a ray
Two systems share the mirror. A screen-space trace, Screen reflections, mirrors whatever is already on screen, which covers the shoreline and the sky above it while they are in view. For what is off screen, the tower behind you, the underside of a bridge, the Metal side-car fires one mirror ray per water pixel into the real chunk geometry, with a cone of jitter for roughness, and shades the hit with block light and sky light; clouds are drawn along the reflected ray as well while Clouds in reflections is on. That traced reflection is what stops the water from showing a smeared copy of the screen when you look down at it. Far water mirrors the shore out to about 240 blocks.
Ray-traced reflections is on the Reflections and Materials page and is restart-only. Two honest notes. Your own body in the traced reflection is built and self-tested but has not yet been shown in a capture, so I do not call it a finished visual. And a custom sky from a resource pack is not yet reflected in water or in the screen trace.
Under the surface
Light entering the water is refracted in screen space, so the bed bends with the waves. The column of water tints what is below it by Beer-Lambert absorption in the biome's color, so depth darkens and a biome's water keeps its own hue. Sunlight glitters off the crests, and the edges of the refraction split slightly by wavelength. Ice is treated as a dielectric slab, a transparent sheet with a real surface. From underneath, the surface shows Snell's window, the circle of sky above you with the mirror around it, and Underwater shafts, default 3, are the god rays through it. Caustics are analytic, drawn on the bed and, when you are under water, on the eye. Sea grass and kelp move with the water, Sea grass sway, on by default. Far water at the horizon keeps the color of its bed instead of turning into flat sky.
Shores, falls and plunge pools
A shoreline is not a hard edge. A depth-field surf runs up the beach, shoaling and breaking toward the sand; Surf amplitude sets its height in meters, default 0.045, from 0 to 0.20. Falling water, Falling water, is drawn as a flowing, tinted, distorting column with ropes and streaks of aeration, and a plunge pool churns under it. Mist over the fall, Spray over falls with Spray strength % for how dense it is, exists and works, but on a fresh install the toggle reads Off, for the reason in the next section.
Why there is no white water by default
The shipped look is the one I wanted: no white on the water. Foam, aeration, splash crowns and spray are all in the code, and all of them are multiplied by one Advanced key, waterWhite, whose default is 0, which compiles them out. Two consequences follow. Shore foam % on the Water page does nothing until waterWhite is 1. And Spray over falls follows waterWhite, so it reads Off on a fresh install; turning it On works on its own. If you want lace along the shore and a white curtain under a fall, set waterWhite to 1 on the Advanced page and the two sliders start to mean something. At the defaults, falling water is a clear, tinted column, not a white one, and I say so here so nobody reports the missing foam as a bug.
The ten settings on the Water page
| Setting | Default | What it does |
|---|---|---|
| Wave octaves | 5 | Wind-sea rungs of the ladder, 2 to 5 |
| Detail rungs | 3 | The 5 to 50 cm ripples, 0 to 3 |
| Screen reflections | On | Mirror what is on screen; the ray trace covers the rest |
| Ripple simulation | On | Rings, wakes and foam from rain, falls, the player and boats |
| Falling water | On | Ropes, streaks and aeration on falls and cascades |
| Spray over falls | Off on a fresh install | Mist and droplets over a plunge pool |
| Parallax steps | 12 | Crests occlude troughs, 0 to 16; 0 is flat |
| Shore foam % | 25 | Lace along open shores; no effect until waterWhite is 1 |
| Surf amplitude | 0.045 m | The roller that runs up a beach, 0 to 0.20 |
| Spray strength % | 25 | How dense the mist over a fall is, when spray is on |
All ten are tune settings: they apply when the page is closed with Done, which rebuilds the pipelines in about a second. Ray-traced reflections, Clouds in reflections and Underwater shafts live on other pages. The help page for Water has every tip as it appears in the game.
What the water costs
Water is the most expensive pass in the pack, and I say so rather than hide it. At my window, 1706x1966, on an M4 Max with 48 GB, looking down at a bay at sunset, the water pass is 8.7 to 8.9 ms of a 46 ms frame. Each knob is worth what it is worth: the Advanced key oceanTriplets at 0 brings the pass to 7.27 ms, Screen reflections off to 7.81, Detail rungs 0 to 8.02, Wave octaves 4 to 8.20, Parallax steps 0 to 8.40. None of them is worth as much as Render scale, which is why 75% is the default; the frames page puts the whole frame in order. Turning Ray-traced reflections off does not save time, it costs it: the screen-space fallback measured slower than the trace.
Download free (1.0.0) Modrinth (pending)Minecraft 26.3, Fabric, macOS on Apple silicon. Install guide. Releases and bug reports on GitHub.
Related
Questions
Is the water a texture or a simulation?
Both, in layers. The waves are an analytic wind-driven spectrum limited by how much open water surrounds each point. On top of that a simulated ripple field, 512 cells of 6.25 cm around the camera, carries rain rings, wakes and the churn under falls, and sleeps 18 seconds after its last disturbance.
Why is there no foam or white water?
By choice. Foam, aeration, splash crowns and spray are multiplied by the Advanced key waterWhite, which defaults to 0. Set it to 1 and the Shore foam % and Spray over falls settings start to do something.
Does a boat leave a wake?
Yes. Boats and the player put a wake into the ripple field, rain puts rings into it and falling water puts a churn under the fall. It is advanced by the damped wave equation every frame.
Why did the water go flat after I changed a setting?
Closing the settings with a changed tune setting rebuilds the shader pipelines, and the ripple field restarts from flat when that happens. It fills again with the next rain, wake or fall.
Can I see myself in the water?
The Player in reflections toggle is on by default and the code that puts your body into the traced reflection is built and self-tested, but it has not yet been shown in a capture, so I do not count it as a finished visual.
Does this water run on Windows?
No. Rockstar Shaders is macOS on Apple Silicon only in this release, tested on one M4 Max. The reflections and the fog occlusion come from a Metal side-car, so Windows, Linux and Intel Macs are not supported.