GridForge Guides

GridForge is a deterministic voxel-world library for games, simulations, tooling, and server runtimes. It gives you the grid infrastructure that often gets rebuilt project by project: fixed-point snapping, world-scoped lookup, conjoined grids, dense and sparse storage, spatial queries, blockers, occupants, and diagnostic geometry.

The central idea is simple: a GridWorld owns one isolated spatial world. That world may contain a single grid, many neighboring grids, or a changing set of streamed regions. Higher-level concepts such as sectors, planets, and shards can sit above GridForge without changing the voxel layer.

Start here

If you are new to GridForge, follow this path:

1. Getting Started — install the package and resolve your first voxel.
2. Core Concepts — learn the world, grid, voxel, identity, and ownership model.
3. Common Workflows — copy practical patterns for sparse grids, hex grids, occupants, blockers, tracing, and teardown.
4. FAQ and Troubleshooting — diagnose the mistakes that are easiest to make early.

Already know what you need? Jump straight to the topic map below.

Choose a topic

Build a world

Guide	Use it for
VoxelGrid and Voxel Model	Grid construction, physical voxels, lookup, neighbors, and reuse
Sparse Grid Storage	Large address spaces where only selected voxels exist
Architecture Overview	Ownership boundaries and subsystem flow
Determinism, Snapping, and Pooling	Numerical and lifetime rules that keep behavior reproducible

Query and mutate it

Guide	Use it for
GridTracer and Coverage	Line, box, XZ-area, and explicit-layer planar body coverage
Scan Cells and Query Flow	Nearby-occupant queries and scan-cell performance
Blockers and Obstacles	Stackable blocked regions and direct obstacle state
Occupants and Partitions	Dynamic entities and typed voxel-local metadata

Build tools and maintain the library

Guide	Use it for
Grid Diagnostics and Geometry	Renderer-neutral cells, topology geometry, and dirty changes
Diagnostics and Logging	Runtime messages, logging adapters, and debugging patterns
Recipes	End-to-end gameplay, simulation, and server examples
Repository Layout and Build	Projects, packages, CI, DocFX, and release tooling
Testing and Benchmarking	Test layout, coverage, and benchmark commands

The mental model

Most GridForge workflows follow the same shape:

1. Create an explicit GridWorld.
2. Describe a grid with GridConfiguration.
3. Register it through GridWorld.TryAddGrid(...).
4. Resolve world positions into a VoxelGrid and Voxel.
5. Trace, scan, block, occupy, or attach partitions as the simulation runs.
6. Reset or dispose the world when its lifetime ends.

Each grid chooses its own topology and storage:

• Rectangular-prism grids use local (x, y, z) voxel indices.
• Hex-prism grids use axial (q, layer, r) values stored in the same VoxelIndex shape.
• Dense grids materialize every voxel in the normalized address space.
• Sparse grids materialize only explicitly configured voxels; a missing address is intentional absence, not an empty voxel.

Flat simulations can use Vector2d overloads. Vector2d.X maps to world X, Vector2d.Y maps to world Z, and layerY selects world Y. These overloads are a convenience over the same 3D runtime, not a separate grid implementation.

Exact geometry and integration

• Cell Geometry and Navigation distinguishes AABB neighbors from exact contacts, portals, and body clearance.
• Segment Intervals and Slabs covers bounded interval evidence and synchronous completed-slab observation.
• Navigation Body Coverage explains 3D and native planar coverage proofs, sparse alternatives, and hard capacity ceilings.
• World Changes and Composition covers committed changes, baseline capture, and bounded composition cursors.

Important lifetime rules

• GridIndex is a reusable storage slot, not durable identity.
• Use WorldVoxelIndex for exact references within the current runtime.
• ObstacleToken and OccupantTicket identify one transient registration lifetime; do not serialize them as content IDs.
• Consume pooled tracer and grouped query results within the operation that produced them.
• Keep deterministic runtime math in Fixed64, Vector2d, and Vector3d.
• Keep engine-specific authoring and rendering in adapters such as GridForge-Unity.

Packages and compatibility

GridForge targets netstandard2.1 and net10.0 and is published in two variants:

Package	Profile
GridForge	Standard package with MemoryPack support
GridForge.Lean	Same grid APIs without the MemoryPack runtime dependency

Both variants use FixedMathSharp and SwiftCollections. Source builds use the matching Release and ReleaseLean configurations.

Project links

• API reference
• Migration guide
• Coverage report
• Source repository
• Unity packages

Conceptual documentation lives with the API reference in docs/api/guides. The repository Markdown is the source of truth; generated HTML is disposable.