Load only the static collision tiles your world needs. Tiles can contain height fields, meshes, boxes or voxel grids. Requests are queued; flush them before querying newly loaded geometry.
dotnet add package RecursiveAI.OnePhysicsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneMath; using RecursiveAI.OnePhysics; using RecursiveAI.OnePhysics.Physics3D; var world = new PhysicsWorld3D(); var key = new TileKey(0, 0); var tile = new TileDef3D(); tile.Boxes.Add(new() { Size = new(8, 1, 8) }); world.LoadTile(key, tile); world.FlushTiles(); world.UnloadTile(key, TileUnloadPolicy.Immediate); world.FlushTiles(); Console.WriteLine(world.GetTileState(key));
Prints:
AbsentUnzip the example, then dotnet run.
The full program
The snippet at the top loads and immediately removes one box tile. The full program also raycasts the floor, rests a sphere on it, then compares contact-aware removal with immediate removal.
using RecursiveAI.OneMath; using RecursiveAI.OnePhysics; using RecursiveAI.OnePhysics.Physics3D; var world = new PhysicsWorld3D(); var key = new TileKey(0, 0); var tile = new TileDef3D(); tile.Boxes.Add(new TileBox3D { Size = new Vector3F(8, 1, 8), Offset = new Vector3F(0, -0.5f, 0) }); world.LoadTile(key, tile); world.FlushTiles(); Console.WriteLine($"Loaded: {world.IsTileLoaded(key)}"); Console.WriteLine($"Ground hit: {world.RaycastAny( new Vector3D(2, 2, 0), new Vector3F(0, -1, 0), 4)}"); var ball = world.AddSphere(0.4f, new Vector3D(0, 0.41, 0)); for (int i = 0; i < 60; i++) world.Step(1f / 60); world.UnloadTile(key, TileUnloadPolicy.WaitForContacts); world.FlushTiles(); Console.WriteLine($"Waiting state: {world.GetTileState(key)}"); world.UnloadTile(key, TileUnloadPolicy.Immediate); world.FlushTiles(); Console.WriteLine($"After immediate: {world.GetTileState(key)}"); for (int i = 0; i < 60; i++) world.Step(1f / 60); Console.WriteLine($"Ball below floor: {ball.Position.Y < 0}");
Loaded: True Ground hit: True Waiting state: Unloading After immediate: Absent Ball below floor: True
A duplicate tile key throws InvalidOperationException; geometry rejected during a flush is dropped and reported by FailedTileLoads and LastTileError rather than thrown.
Variations
Remove an unoccupied tile with the default contact policy. Append this after the sphere has fallen away in the full program.
world.LoadTile(key, tile); world.FlushTiles(); world.UnloadTile(key, TileUnloadPolicy.WaitForContacts); world.FlushTiles(); Console.WriteLine(world.GetTileState(key));
AbsentRelated recipes
- Simulate a volumetric soft body in C#
- Decompose a mesh into convex colliders in C#
- Create a polygon collider from a sprite outline in C#
The short answer
Use LoadTile to queue a TileDef3D, then FlushTiles to build its static collision bodies before a query. Queue removal with UnloadTile. Use WaitForContacts when geometry supporting a dynamic body should remain, or Immediate when removal must happen at the next flush regardless of contacts.
This is explicit collision streaming. Your application chooses which tile definitions to load and when to unload them. The API does not fetch terrain files, select tiles around a camera, or conceal the physical consequences of removing the ground beneath a body.
How do you add collision to terrain tiles?
A tile has a TileKey and a definition containing static geometry. In 3D, definitions can contain height fields, triangle meshes, boxes and voxel grids. Each part becomes one static body. The example uses a box with its top at zero so the input is entirely visible in code and no terrain asset is needed.
LoadTile queues a copy of the definition. A queue request is not yet a built collider. Call FlushTiles before the raycast when you need geometry immediately, or let the start of the next simulation step apply it. Hashing, snapshot operations, forking, and creating or destroying bodies or shapes can also trigger a flush.
Loads and unloads are applied in key order, with unloads first. The world-scale specification defines this ordering. Do not use the order in which asynchronous asset requests finish as a substitute for deciding which tile set belongs in the world.
Why is a collision tile still present after unloading?
WaitForContacts marks the tile as unloading but retains it while a live contact or joint constraint connects one of its bodies to a dynamic body. Sleeping dynamic bodies count too. Every subsequent flush retries removal. A player standing on a floor can therefore keep that floor in the collision world after an unload request.
Inspect GetTileState to distinguish Loaded, Unloading and Absent. In particular, IsTileLoaded is false while the tile is unloading even though its bodies still exist. The full program prints Unloading after contact-aware removal; checking only a boolean would obscure that state.
Immediate removes the tile at the next flush and ends its contacts. The demonstration then steps again and confirms that the unsupported sphere falls below the former floor. Choose this policy deliberately for destruction or an authoritative world change, not as a silent fallback whenever contact-aware removal waits.
How do you avoid collision seams between terrain tiles?
For height fields, supply the neighboring sample ring with HeightFieldEdges3D. Those samples help decide whether border edges should be active. They do not create collision beyond the field itself, so adjacent tile geometry must still meet correctly.
Triangle meshes and 2D tile grids do not have that neighbor information; their boundary edges remain active. A body crossing between mesh tiles can encounter a seam bump. Choose a height field when its shape fits the terrain and seamless height-field borders are important.
Keep keys unique while tiles are queued, loaded or unloading. Some invalid definitions are rejected at queue time; invalid geometry discovered while building is dropped at flush time and reported through the failure properties. A successful call to LoadTile alone is therefore not confirmation that a terrain collider was built. A restore also discards queued requests, so reconstruct any desired pending tile operations after restoring state.