Dig holes in 3D collision terrain by clearing voxels, the solid cells of a grid. Fill cells again to rebuild support.
dotnet add package RecursiveAI.OnePhysicsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OnePhysics.Physics3D; var world = new PhysicsWorld3D(); var solid = new bool[16 * 4 * 16]; Array.Fill(solid, true); var ground = world.AddVoxelGrid( 16, 4, 16, solid); int dug = ground.Voxels.DigSphere( new(8, 4, 8), 2); Console.WriteLine( $"Cells removed: {dug}");
Cells removed: 16Unzip the example, then dotnet run.
The full program
The program creates all terrain data in memory. It rests a box on the grid, digs under it and fills a small block inside the hole before stepping again.
using RecursiveAI.OneMath; using RecursiveAI.OnePhysics; using RecursiveAI.OnePhysics.Physics3D; var world = new PhysicsWorld3D(); var solid = new bool[16 * 4 * 16]; Array.Fill(solid, true); var ground = world.AddVoxelGrid(16, 4, 16, solid, cellSize: 0.5f); var voxels = ground.Voxels; var box = world.AddBox(new(0.5f, 0.5f, 0.5f), at: new(4, 2.5, 4)); for (int i = 0; i < 120; i++) world.Step(1f / 60); Console.WriteLine($"Before dig: y={box.Position.Y:F2}"); byte[] before = world.Snapshot(); ulong EditAndStep() { Console.WriteLine($"Cells removed: {voxels.DigSphere(new(4, 2, 4), 1.5)}"); Console.WriteLine($"Cells filled: {voxels.SetVoxels(7, 1, 7, 2, 1, 2, solid: true)}"); for (int i = 0; i < 60; i++) world.Step(1f / 60); Console.WriteLine($"After dig: y={box.Position.Y:F2}"); return world.ComputeHash(); } ulong first = EditAndStep(); world.Restore(before); Console.WriteLine("Restored edit:"); ulong second = EditAndStep(); Console.WriteLine($"Repeated hash matches: {first == second}");
dotnet run prints:
Before dig: y=2.25 Cells removed: 68 Cells filled: 4 After dig: y=1.25 Restored edit: Cells removed: 68 Cells filled: 4 After dig: y=1.25 Repeated hash matches: True
Variations
Fill a block of cells. Append this to the snippet at the top:
int filled = ground.Voxels.SetVoxels( 7, 2, 7, 2, 2, 2, solid: true); Console.WriteLine($"Cells filled: {filled}");
The additional line is:
Cells filled: 8Related recipes
The short answer
Add a solid/empty occupancy array with PhysicsWorld3D.AddVoxelGrid. Get the grid’s shape from ground.Voxels, then call DigSphere to remove cells or SetVoxels to fill a rectangular block. These edit collision geometry. They do not generate a rendered landscape, texture or navigation map.
The snippet at the top fills the entire input array, digs into its upper surface and prints the number of cells removed. The full program adds a supported body so you can see a physical consequence: after the edit and more steps, the box settles lower. There are no external model or terrain files.
How does voxel terrain collision work?
A voxel grid records whether each cell contains solid material. The input array is x-fastest: the full index is (z * height + y) * width + x. Width, height and depth are cell counts. cellSize determines their size in world units. The full program uses 0.5, making its four-cell-high grid two units tall.
The editing methods take different coordinate types on purpose. DigSphere takes a world-space center and a radius. It removes cells whose centers are inside that sphere. A cell is not partly excavated according to the percentage of its volume intersected by the sphere. This matters for a small tool: if the sphere reaches no cell center, it need not remove any cells.
SetVoxels takes integer cell coordinates and integer block dimensions instead. Its first three arguments identify the beginning cell; the next three are the block’s width, height and depth. solid: true fills that block. In the full program, the refill lies inside the dug region. It changes four cells, and the box settles on the resulting support at y = 1.25 instead of its earlier y = 2.25. The smaller variation uses a unit-sized grid and fills eight cleared cells.
Both methods return how many cells changed, not the number of triangles rebuilt or a new body handle. A return of zero can simply mean the requested cells already have the requested state. Repeating the same fill is therefore not a way to add height above the existing cells. Use another layer’s coordinates when you want a taller solid block.
OnePhysics identifies boundary triangles with 12 * cell + 2 * face + half. Faces untouched by an edit keep their IDs. Bodies near changed geometry wake and find the new surface; characters and bodies elsewhere retain their state bit for bit, as described in the terrain guide. This lets an edit change local collision support without discarding unrelated surface identities throughout the grid.
Keep simulation geometry separate from its display. If your application draws cubes, update that display from the occupancy edits. If it draws another surface, make sure its apparent holes agree with the cells used for collision. This example handles the physics side only; it does not claim to be a complete voxel engine.
The terrain state is saved in snapshots and included in world hashes. In the full program, restoring the pre-edit snapshot and repeating the same dig, fill and steps produces a matching hash. The saved state is taken after the box has settled, so it includes that contact state too. Preserve both the edit sequence and the fixed step size when reproducing a result. Merely starting with the same occupancy array is not a substitute for restoring the rest of a running world.