Simulate liquid as moving particles, with a tank and floating crate in the full example.
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.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);
400Unzip the example, 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.
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:
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:
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:
Nearby: 8 copied, 24 totalRelated recipes
Shallow-water buoyancy · Simulate cloth · 3D physics
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 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.