GoDot Realistic Shoreline & Ocean Waves

Realistic Shoreline Waves

Waves that break, run up the sand, wrap around rocks, and drain back because a real fluid solver says so. A GPU shallow-water simulation for Godot 4.7, free and open.

Not animated water. Simulated water.

Most game water is a surface that pretends: scrolling normal maps, foam decals, a collision ring when something touches it. This package runs the nonlinear shallow water equations on your GPU, the same depth-averaged physics coastal engineers use, on grids up to 2048 x 2048 cells in real time. Waves shoal because the sea floor rises. They break because the equations form bores. Foam rides the actual current field around obstacles. The wet sand line is a memory of where water really reached.

The solver is a second-order central-upwind finite-volume scheme (Kurganov and Petrova, 2007): positivity-preserving at the moving waterline, well-balanced on sloped beds, shock-capturing in the surf zone. In the built-in test box it conserves water volume to six digits over minutes. You can watch the numbers yourself; a diagnostics readout prints volume, peak speeds, and stability counters while you play.

Drop in a binary and press play

No plugins, no build steps, no GDExtension. Download Godot 4.7 for Windows, drop the executable into the folder, run a launcher. Or open the folder as a Godot project and press F5. Inside the demos: switch scenarios live, fire single solitary waves with the space bar, fly anywhere with a free camera, and toggle a false-color view of the raw simulation fields.

Built to be used in your project

The simulation exposes its state as zero-copy GPU textures (Texture2DRD): water surface, momentum, foam, wetness. Bind them to any material. The manual walks through integration with working GDScript, from a minimal setup to custom bathymetry:

var sim := SimController.new()
sim.kind = SimController.Kind.BEACH
add_child(sim)
var mat := ShaderMaterial.new()
mat.shader = load("res://shaders/water.gdshader")
mat.set_shader_parameter("tx_state", sim.tex_state)   # live GPU texture
mat.set_shader_parameter("tx_bottom", sim.tex_bottom)
mat.set_shader_parameter("tx_derived", sim.tex_derived)
water_mesh.material_override = mat
sim.wave_amp = 0.28        # change the sea state any time
sim.trigger_solitary()     # or fire one clean breaker

Your own shoreline is a height function away: edit the beach profile in GDScript, or write islands, reefs, and walls as analytic shapes in the GPU bathymetry generator the archipelago uses. The included documentation (a full HTML manual with screenshots) covers the scheme, the wave generator, every tuning knob with its shipped value, the scientific papers behind it, and a list of worthwhile extensions.

What exactly is in the package

• 9 GLSL compute kernels: the fused KP07 solver step, boundary and wavemaker pass, foam and ground-memory passes, GPU bathymetry generation, diagnostics. Commented, plus an unfused two-kernel reference version of the scheme for readers.
• 6 surface shaders: shoreline water (refraction, depth absorption, aeration, foam lace, optional deep-water swell layer), sand with wetness and caustics, quay wall, island terrain, the standalone Gerstner ocean, diagnostic materials.
• GDScript runtime: solver controller (all RenderingDevice plumbing), scenario builders, demo scenes, free camera, scripted screenshot rig for automated testing.
• All assets bundled: photoscanned rocks, PBR sand and masonry sets with displacement, two sky panoramas (Poly Haven, CC0), and seamless procedural textures with the generator script that made them.
• docs/index.html: the manual. Setup, demos, scientific background with references, integration examples, tuning tables, performance guide, troubleshooting.

Performance and requirements

Demo	Simulation	Measured on an RTX 4070 laptop, 1080p
Beach	608 x 608 cells at 5 cm, real time	60 fps, solver under 5% of the GPU
Island	2048 x 2048 cells at 1 m, real time	about 28 fps (render-bound, FSR2 included)
Open ocean	shader only	200+ fps

• Godot 4.7 or newer, Forward+ renderer (the simulation uses compute shaders).
• A desktop-class GPU. Grid sizes and quality settings scale down; the manual has concrete numbers for weaker hardware.
• Developed and verified on Windows with NVIDIA. The kernels are standard Vulkan GLSL; other Forward+ platforms are untested.
• An on-screen FPS readout also shows the simulation speed factor, so you always know whether the fluid is running at real time.

Honest limits

The solver is depth-averaged: it cannot throw water vertically, so wall-impact spray needs a particle layer on top (the simulation already flags impact locations for exactly that; hooking up particles is on the extension list in the manual). Deep-water waves in the solver are slightly less dispersive than reality, which is why the package pairs it with the Gerstner layer offshore. Close-up swash detail depends on cell size: 5 cm cells give the beach demo its lace, the 1 m island reads best from a few dozen meters up.