GridForge

Deterministic voxel worlds for .NET games, simulations, tools, and server runtimes.

GridForge gives you explicit world ownership, snapped fixed-point grids, streamable multi-grid spaces, spatial queries, blockers, occupants, and diagnostic geometry—without tying the core runtime to a game engine.

Why GridForge?

• Worlds that grow with your project. Start with one grid, join neighboring grids, or load and unload regions inside an explicit GridWorld.
• Deterministic spatial math. Rectangular-prism and hex-prism grids use FixedMathSharp throughout the runtime.
• Dense or sparse storage. Model solid voxel volumes or large address spaces where only selected cells exist.
• Queries and state built in. Trace lines and bounds, scan nearby occupants, stack blockers, attach typed partitions, and observe dirty diagnostic regions.
• Engine-agnostic by design. Unity authoring and visualization live in the separate GridForge-Unity packages.
• Allocation-conscious internals. Hot paths build on SwiftCollections containers and pools.

Install

dotnet add package GridForge

Choose one package variant:

Package	Use it when
GridForge	You want the default package with MemoryPack serialization support.
GridForge.Lean	You want the same grid API without the MemoryPack runtime dependency.

Both variants target netstandard2.1 and net8.0.

Quick start

using System;
using FixedMathSharp;
using GridForge.Configuration;
using GridForge.Grids;

using GridWorld world = new GridWorld();

GridConfiguration configuration = new GridConfiguration(
    new Vector3d(-10, 0, -10),
    new Vector3d(10, 0, 10));

if (!world.TryAddGrid(configuration, out _))
    throw new InvalidOperationException("Could not add the grid.");

Vector3d position = new Vector3d(2, 0, -3);
if (world.TryGetGridAndVoxel(
        position,
        out VoxelGrid? grid,
        out Voxel? voxel)
    && grid is not null
    && voxel is not null)
{
    Console.WriteLine($"Grid {grid.GridIndex}, voxel {voxel.Index}");
}

That same GridWorld can own multiple conjoined grids, mix rectangular and hex topologies, and combine dense and sparse storage. Higher-level regions, sectors, or streaming policy remain yours to shape above the voxel layer.

Learn more

• Getting started
• Core concepts
• Common workflows
• API reference
• Migration guide
• Contributing and local validation

The GridForge wiki covers topology, sparse storage, tracing, scan cells, blockers, occupants, diagnostics, determinism, testing, and benchmarks in depth.

Questions and discussion are welcome in the Discord community. GridForge is available under the MIT License.