Simulate waves on a height grid, not a full 3D fluid volume.
dotnet add package RecursiveAI.OnePhysicsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneMath; using RecursiveAI.OnePhysics.Physics3D; var world = new PhysicsWorld3D(); var water = world.AddShallowWater( 0, 0, 8, 8, level: 1, cellSize: 1, floor: 0); water.AddVolume(0, 0, 2, 8, 4f); for (int i = 0; i < 60; i++) world.Step(1f / 60f); Console.WriteLine( $"Surface: {water.CellSurface(4, 4):F3}");
Adds water at the X = 0 edge and prints the center height after 60 steps.
Surface: 1.090Unzip the example, then dotnet run.
The full program
The full program creates an 8-by-8-meter basin with 1-meter cells and a flat bed at zero. It adds 4 cubic meters over the first two columns (0 ≤ X < 2), steps the waves and queries the water at the center.
using RecursiveAI.OneMath; using RecursiveAI.OnePhysics; using RecursiveAI.OnePhysics.Physics3D; var world = new PhysicsWorld3D(); var water = world.AddShallowWater(0, 0, 8, 8, level: 1, cellSize: 1, floor: 0); Console.WriteLine($"Grid: {water.CellsX} x {water.CellsZ}"); Console.WriteLine($"Volume before: {water.Volume:F3}"); water.AddVolume(0, 0, 2, 8, 4f); Console.WriteLine($"Volume after disturbance: {water.Volume:F3}"); for (int i = 1; i <= 120; i++) { world.Step(1f / 60f); if (i % 60 == 0) Console.WriteLine($"Step {i}: column0={water.CellSurface(0, 4):F3}, center={water.CellSurface(4, 4):F3}"); } if (world.QueryWater(new Vector3D(4.5, 0, 4.5), out var sample)) Console.WriteLine($"Query: surface={sample.Surface:F3}, depth={sample.Depth:F3}"); Console.WriteLine($"Volume at end: {water.Volume:F3}");
dotnet run prints:
Grid: 8 x 8 Volume before: 64.000 Volume after disturbance: 68.000 Step 60: column0=1.053, center=1.090 Step 120: column0=0.996, center=1.066 Query: surface=1.066, depth=1.066 Volume at end: 68.000
A cell index outside the grid throws ArgumentOutOfRangeException; create static terrain before the grid if you want it sampled as the bed.
Variations
Reset the grid to a level surface. Append this to the snippet at the top to replace the disturbance with a flat surface at height 2.
water.Fill(2); world.Step(1f / 60f); Console.WriteLine( $"Surface: {water.CellSurface(4, 4):F3}"); Console.WriteLine($"Volume: {water.Volume:F3}");
The added lines print:
Surface: 2.000 Volume: 128.000
Related recipes
- Configure physics simulation level of detail in C#
- Simulate a ragdoll in C#
- Move a 3D physics character in C#
The short answer
Create a grid with PhysicsWorld3D.AddShallowWater, disturb it with AddVolume and call world.Step at a fixed interval. Read individual cell surfaces with CellSurface, or use QueryWater for surface, depth, current and normal at a world position. The example is a closed basin whose surface changes after water is added on one side.
How do I implement a shallow-water simulation in C#?
The grid covers X and Z, with height along Y. The example spans 0 to 8 on both horizontal axes with a cell size of 1 meter. Initial surface level is 1 and bed height is 0, so it begins with 64 cubic meters. Adding 4 cubic meters over the first two columns (0 ≤ X < 2) raises the total to 68. The added volume spreads over overlapping cells in proportion to their footprint area; it is not a request to set those cells’ height to 4.
The subsequent output shows waves redistributing that water. At step 60 the center surface is above its original level, and at step 120 the first-column cell’s surface is slightly below it. Those are local heights, not changes in total water volume. The final volume still prints 68.000 to the shown precision. The water specification describes volume conservation to float rounding with closed sides and no sources.
For a shaped bed, create static terrain before creating the grid. The bed is sampled once under the cell centers; call ResampleBed after changing terrain. The floor parameter supplies the fallback elevation where no static shape is hit. It is not a solid collider that will stop falling rigid bodies.
Grid resolution changes what waves can be represented. The guide notes that waves shorter than a few cells are lost. Smaller cells over deep water can require more internal substeps. If the required count exceeds MaxSubsteps, the step is stretched and becomes less accurate; a finer grid alone is not a guarantee of a better result at an unchanged step interval.
Is shallow-water simulation the same as 3D fluid simulation?
No. This API evolves water depth and depth-averaged horizontal momentum over a bed using the shallow-water equations. A 3D world still has one surface per horizontal grid position, not a volume filled with freely moving water particles. Use it for a lake, channel or wave tank where a changing surface and current are the behavior you need. It does not represent an overturning wave or a detached splash volume.
The default sides are walls. Definitions also support open sides, held levels and inflows; sources and drains can change the volume continuously. Keep walls while checking a disturbance so water leaving a boundary cannot be mistaken for numerical loss. Damping reduces motion rather than serving as a drain.
A point query returns a wet sample only where the footprint contains the point and depth exceeds 0.001 meters. Check the boolean result before using the sample. Surface is world elevation, while depth is the distance from bed to surface; they happen to match in this example because its flat bed is zero. Floating rigid bodies can also displace and react to this water, but they are not required to generate the wave shown here.