---
title: "Simulate particle fluids in C#"
url: https://recursiveai.org/onephysics/cookbook/simulate-particle-fluid/
description: "Fill and step a particle fluid in C#. Add a tank and floating crate, read stable particle IDs, inspect submerged fraction, and collect fluid events."
version: "1.0.0"
---

# Simulate particle fluids 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-particle-fluid/simulate-particle-fluid.zip)

Simulate liquid as moving particles, with a tank and floating crate in the full example.

```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.AddParticleWater(0.1f);
world.FillFluidBox(water, new(-0.5, 0, -0.5),
    new(0.5, 0.4, 0.5));
world.Step(1f / 60f);
Console.WriteLine(world.FluidParticleCount);
```

```text
400
```

Unzip [the example](https://recursiveai.org/onephysics/cookbook/simulate-particle-fluid/simulate-particle-fluid.zip), then `dotnet run`.

## The full program

The snippet at the top creates 400 water particles and advances them once under gravity; it has no container. The full program adds a floor and four walls, drops a crate into the water, and steps for 120 frames. Inputs are created entirely in code. Lengths are in meters, density in kg/m³, and each step is in seconds.

It sets a budget of 2,000 particles, saves the initial IDs, and compares them after stepping. It reads events inside the loop because `FluidEvents` contains only the last step’s entries and exits.

```csharp
using RecursiveAI.OneMath;
using RecursiveAI.OnePhysics;
using RecursiveAI.OnePhysics.Fluids;
using RecursiveAI.OnePhysics.Physics3D;

var world = new PhysicsWorld3D();
var settings = FluidSettings.Default;
settings.MaxParticles = 2000;
world.FluidSettings = settings;
world.AddBox(new Vector3F(2, 0.2f, 2),
    at: new Vector3D(0, -0.1, 0), type: BodyType.Static);
world.AddBox(new Vector3F(0.2f, 2, 2),
    at: new Vector3D(-0.6, 0.9, 0), type: BodyType.Static);
world.AddBox(new Vector3F(0.2f, 2, 2),
    at: new Vector3D(0.6, 0.9, 0), type: BodyType.Static);
world.AddBox(new Vector3F(2, 2, 0.2f),
    at: new Vector3D(0, 0.9, -0.6), type: BodyType.Static);
world.AddBox(new Vector3F(2, 2, 0.2f),
    at: new Vector3D(0, 0.9, 0.6), type: BodyType.Static);
var water = world.AddParticleWater(spacing: 0.1f);
world.FillFluidBox(water, new Vector3D(-0.5, 0, -0.5),
    new Vector3D(0.5, 0.4, 0.5));
var crate = world.AddBox(new Vector3F(0.25f, 0.25f, 0.25f),
    at: new Vector3D(0, 0.55, 0), density: 400f);
var particles = new FluidParticleInfo[world.FluidParticleCount];
world.GetFluidParticles(particles);
var ids = particles.Select(p => p.Id).Order().ToArray();
int events = 0;
for (int i = 0; i < 120; i++)
{
    world.Step(1f / 60f);
    foreach (var change in world.FluidEvents)
    {
        events++;
        Console.WriteLine($"Fluid event: {change.Kind}");
    }
}
world.GetFluidParticles(particles);
Console.WriteLine($"Particles: {world.FluidParticleCount}");
Console.WriteLine($"Same IDs: {ids.SequenceEqual(particles.Select(p => p.Id).Order())}");
Console.WriteLine($"Submerged: {world.GetFluidState(crate, water).SubmergedFraction:F3}");
Console.WriteLine($"Events: {events}");
```

`dotnet run` prints:

```text
Fluid event: Enter
Fluid event: Exit
Fluid event: Enter
Fluid event: Exit
Fluid event: Enter
Particles: 400
Same IDs: True
Submerged: 0.375
Events: 5
```

Adding particles beyond `FluidSettings.MaxParticles` throws `FluidBudgetException` and adds nothing; start from `FluidSettings.Default` when changing a single setting.

## Variations

After the full program’s step loop, copy nearby particles into a buffer you own. `total` reports all matches even when the buffer only holds eight:

```csharp
var near = new FluidParticleInfo[8];
int written = world.OverlapFluidSphere(
    new Vector3D(0, 0.2, 0), 0.2f, near, out int total);
Console.WriteLine($"Nearby: {written} copied, {total} total");
```

The extra line is:

```text
Nearby: 8 copied, 24 total
```

## Related recipes

[Shallow-water buoyancy](https://recursiveai.org/onephysics/cookbook/simulate-buoyancy/) · [Simulate cloth](https://recursiveai.org/onephysics/cookbook/simulate-cloth/) · [3D physics](https://recursiveai.org/onephysics/cookbook/3d-preview/)

---

## The short answer

Use `PhysicsWorld3D.AddParticleWater`, fill it with `FillFluidBox`, and call `world.Step`. This is a position-based particle simulation: density constraints keep the liquid near its rest density. It is not just a force applied below an invisible water plane. Rigid bodies and fluid particles push each other, so the crate changes the water as the water moves the crate. The [particle-fluid guide](https://recursiveai.org/onephysics/docs/fluids/) describes this coupling.

The example deliberately uses a small tank with a coarse spacing of 0.1 m. Its printed submerged fraction is one sampled result from that setup, not a promise of an exact waterline at every resolution.

## How do I simulate particle fluids in C#?

Create the world’s solid boundaries before filling the water. `FillFluidBox` places particles on the fluid’s lattice inside the minimum and maximum corners; it does not create walls around that volume. Without solid shapes to contain it, gravity carries the water away. The short snippet demonstrates that distinction, while the download includes the tank and crate.

Spacing controls the resolution and particle count. The guide states that halving spacing requires eight times as many particles in 3D or four times as many in 2D. It gives a default particle budget of 262144. The full program instead caps this small example at 2,000. A particle has mass equal to density times spacing cubed in 3D. A finer lattice therefore changes both the number and mass of the samples, rather than simply adding identical particles.

All particle fluids in one world share the spacing established by the first fluid. Start another world if you need an independent simulation at a different spacing. Surface meshing is left to the application: the output here is particle data, not a rendered water mesh.

## What are some common fluid simulation techniques?

For this library, choose between actual liquid particles and the simpler water representations based on what must move. Particle fluids let the liquid flow and splash around colliders. The guide distinguishes them from `AddFluid`, an analytic buoyancy volume that floats bodies on a water plane without simulating the water. Those two systems do not interact.

Shallow water is a separate surface-height grid, used in the related buoyancy recipe. It is not the arbitrary 3D particle volume shown here. A scene that only needs a floating box on a water surface need not also manage hundreds of water particles. A tank whose liquid must move around the box calls for the particle model.

Within the particle model, density iterations and substeps control how the constraints are solved. The guide gives defaults of two substeps and four iterations. These are solver settings, not additional liquid emitters or extra volume.

## How do I read particles from a fluid simulation?

Use `GetFluidParticles` with a caller-owned span, or use a spatial query such as the variation’s `OverlapFluidSphere`. Particle storage order can change every step; track `Id`, not an array index. The full program compares sorted ID sets because it neither emits nor drains particles. This checks identity across the run without assuming that the storage order stayed fixed.

`GetFluidState(crate, water).SubmergedFraction` is an estimate at the resolution of a sample lattice. Do not interpret three printed decimals as three-decimal physical accuracy. Read entry and exit events after each step if you need a complete event history: waiting until the end only gives the final step’s events. The coarse sample enters and exits several times before the final reading.
