---
title: "Stream static collision tiles in C#"
url: https://recursiveai.org/onephysics/cookbook/stream-static-collision-tiles/
description: "Queue static collision tile loads and unloads in C#, flush requests, query terrain, and compare contact-aware and immediate removal with OnePhysics."
version: "1.0.0"
---

# Stream static collision tiles 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/stream-static-collision-tiles/stream-static-collision-tiles.zip)

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.

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

```text
Absent
```

Unzip [the example](https://recursiveai.org/onephysics/cookbook/stream-static-collision-tiles/stream-static-collision-tiles.zip), 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.

```csharp
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}");
```

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

```csharp
world.LoadTile(key, tile);
world.FlushTiles();
world.UnloadTile(key, TileUnloadPolicy.WaitForContacts);
world.FlushTiles();
Console.WriteLine(world.GetTileState(key));
```

```text
Absent
```

## Related recipes

- [Simulate a volumetric soft body in C#](https://recursiveai.org/onephysics/cookbook/simulate-volumetric-soft-body/)
- [Decompose a mesh into convex colliders in C#](https://recursiveai.org/onephysics/cookbook/decompose-mesh-into-convex-colliders/)
- [Create a polygon collider from a sprite outline in C#](https://recursiveai.org/onephysics/cookbook/create-collider-from-sprite-outline/)

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