---
title: "Simulate shallow water in C#"
url: https://recursiveai.org/onephysics/cookbook/simulate-shallow-water/
description: "Create a shallow-water grid in C#, add a wave-making disturbance and query surface height and depth with a runnable OnePhysics example."
version: "1.0.0"
---

# Simulate shallow water in C#

**OnePhysics** is a free, open-source physics library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OnePhysics) · [GitHub](https://github.com/recursive-ai-oss/onephysics-csharp) · [Docs](https://recursiveai.org/onephysics/docs/) · [Download example (.zip)](https://recursiveai.org/onephysics/cookbook/simulate-shallow-water/simulate-shallow-water.zip)

Simulate waves on a height grid, not a full 3D fluid volume.

```shell
dotnet add package RecursiveAI.OnePhysics
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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.

```text
Surface: 1.090
```

Unzip [the example](https://recursiveai.org/onephysics/cookbook/simulate-shallow-water/simulate-shallow-water.zip), 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.

```csharp
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:

```text
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.

```csharp
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:

```text
Surface: 2.000
Volume: 128.000
```

## Related recipes

- [Configure physics simulation level of detail in C#](https://recursiveai.org/onephysics/cookbook/configure-physics-simulation-lod/)
- [Simulate a ragdoll in C#](https://recursiveai.org/onephysics/cookbook/simulate-ragdoll/)
- [Move a 3D physics character in C#](https://recursiveai.org/onephysics/cookbook/move-3d-physics-character/)

---

## 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](https://github.com/recursive-ai-oss/onephysics-csharp/blob/11dad30ed91fae25354edb55930c67cc0f71fe25/docs/spec/water.md#L59) 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](https://github.com/recursive-ai-oss/onephysics-csharp/blob/11dad30ed91fae25354edb55930c67cc0f71fe25/docs/guide/water.md) 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.
