GridForge 7.1.1

GridForge

GridForge is a deterministic voxel-world library for building fast spatial systems in games, simulations, tools, and server runtimes.

It gives you the low-level grid infrastructure that many systems end up reinventing: snapped voxel bounds, world-scoped grid registration, conjoined-grid neighbor awareness, scan-cell query overlays, blocker and obstacle state, occupant tracking, and fixed-point spatial math.

The interesting part is the shape of the model. GridForge does not force you into one giant grid, a hand-managed tile map, or a premature hierarchy. It gives you an explicit GridWorld that can own one grid, many conjoined grids, or a streamed set of active grids, while still leaving room for higher-level sector, region, planet, or shard systems above it.

Why GridForge?

Grid-based systems tend to split into three common approaches:

GridForge is designed around the most flexible foundation: conjoined grids inside explicit worlds.

That means you can start with a single grid, add neighboring grids as the world grows, remove inactive grids as regions unload, and build hierarchy above the library only when your game or simulation actually needs it.

What It Provides

• Explicit GridWorld ownership for isolated runtime state
• Multiple active grids per world, with conjoined boundary neighbor lookup
• Deterministic fixed-point math through FixedMathSharp
• Fast world-space lookup through snapped bounds and a spatial hash
• Rectangular-prism and hex-prism topology through the same VoxelGrid model
• Dense and sparse voxel storage behind the same VoxelGrid query model
• Scan-cell overlays for efficient radius and occupant queries
• Region coverage through GridTracer
• Blocker and obstacle workflows for world-space blocked areas
• Occupant and partition extension points for gameplay or simulation metadata
• Engine-agnostic diagnostic cell, geometry, and dirty-change descriptors for tools and overlays
• Allocation-conscious internals built on SwiftCollections pools and containers
• Standard and lean package variants for different dependency needs

Install

dotnet add package GridForge

GridForge targets netstandard2.1 and net8.0.

Package Variants

GridForge is published in two build variants:

Install the lean package with:

dotnet add package GridForge.Lean

Source builds also expose matching configurations:

• Release builds the standard GridForge package.
• ReleaseLean builds the GridForge.Lean package.

Unity-specific integration lives in the separate GridForge-Unity repository.

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),
    scanCellSize: 8);

if (!world.TryAddGrid(configuration, out ushort gridIndex))
    throw new InvalidOperationException("Failed to add grid.");

VoxelGrid grid = world.ActiveGrids[gridIndex];
Vector3d position = new Vector3d(2, 0, -3);

if (world.TryGetGridAndVoxel(position, out VoxelGrid resolvedGrid, out Voxel voxel))
{
    Console.WriteLine($"Grid: {resolvedGrid.GridIndex}");
    Console.WriteLine($"Voxel: {voxel.Index}");
    Console.WriteLine($"World position: {voxel.WorldPosition}");
}

Use the TryGetClosest... lookup variants when a query should snap to the nearest grid bounds or nearest physical voxel center instead of requiring the position to fall inside an existing voxel. Sparse closest-voxel queries only consider configured physical voxels. In mixed-topology worlds, pass the optional GridTopologyKind argument to GridWorld closest queries to restrict candidate grids to rectangular-prism or hex-prism topology.

For flat XZ simulations, lookup APIs also accept Vector2d positions. In GridForge, Vector2d(x, z) maps to world Vector3d(x, layerY, z), with layerY defaulting to 0. Tracing, coverage, radius scans, obstacle helpers, and bounds blockers use the same XZ-plane projection and stay locked to the selected layer. This is a convenience layer over the 3D voxel runtime, not a separate 2D grid type.

The key mental model is:

1. Create a GridWorld.
2. Register one or more VoxelGrid instances from GridConfiguration.
3. Resolve world-space positions into grids and voxels.
4. Layer scans, blockers, occupants, partitions, or higher-level systems on top.
5. Reset or dispose the world when that simulation boundary is done.

Dense grids are the default: every topology-local voxel inside the registered bounds exists. Sparse grids use the same bounds as an address space, but only explicitly configured voxels exist. Missing sparse voxels are intentional absence for lookup, coverage, blockers, occupants, partitions, and neighbors.

Each grid also chooses its cell topology through GridConfiguration. Rectangular-prism topology is the default and uses VoxelIndex(x, y, z). Hex-prism topology uses axial coordinates in the XZ plane: VoxelIndex.x = q, VoxelIndex.z = r, and VoxelIndex.y = layer. Both HexOrientation.PointyTop and HexOrientation.FlatTop are deterministic fixed-point projections, so a single GridWorld can own rectangular and hex grids without caller-side query branching.

using GridForge.Grids.Topology;

GridConfiguration hexConfiguration = new GridConfiguration(
    new Vector3d(24, 0, 0),
    new Vector3d(40, 0, 16),
    topologyKind: GridTopologyKind.HexPrism,
    topologyMetrics: GridTopologyMetrics.Hex(
        new Fixed64(2),
        Fixed64.One,
        HexOrientation.PointyTop));

Conjoined Grids And Dynamic Worlds

The library is built for worlds that grow, stream, and split responsibility cleanly:

• A small game can use one GridWorld with one VoxelGrid.
• A streamed world can load and unload grids around the player or active simulation area.
• A server can run multiple isolated GridWorld instances in one process.
• A larger architecture can put sectors, planets, regions, or hierarchy above GridForge without reworking the voxel layer.

GridForge tracks world-local grid slots, grid spawn tokens, and WorldVoxelIndex values so systems can reason about identity even as grids are removed, reused, or replaced.

Core Concepts

Documentation

For breaking upgrades from v6 to v7, start with the Migration Guide.

Start with the wiki:

• Wiki Home
• Getting Started
• Core Concepts
• Sparse Grid Storage
• Grid Diagnostics and Geometry
• Common Workflows
• Architecture Overview
• Recipes
• FAQ and Troubleshooting

The source for those pages lives in docs/wiki.

Local Validation

dotnet restore GridForge.slnx
dotnet build GridForge.slnx --configuration Debug
dotnet test GridForge.slnx --configuration Debug --no-build

CI validates both Release and ReleaseLean on Ubuntu and Windows.

For benchmark discovery:

dotnet run --project tests/GridForge.Benchmarks/GridForge.Benchmarks.csproj -c Release -- list

Benchmarks are especially useful when changing pooling, tracing, grid registration, scan flow, diagnostics, or other allocation-sensitive paths. The sparse-voxel-grid alias covers sparse construction, lookup, coverage, blocker, scan, and dense comparison scenarios. The hex-prism-topology alias covers hex lookup, projection, construction, tracing, coverage, blockers, occupants, scans, and rectangular baseline comparison. The grid-diagnostics alias covers diagnostic traversal, sparse missing-address traversal, and GetCellsInto versus VisitCells.

Contributing

See CONTRIBUTING.md for contribution guidelines and workflow details.

When working on core behavior, keep the library deterministic, world-scoped, allocation-conscious, and free of engine-specific assumptions.

Community And Support

For questions, discussions, or general support, join the official Discord community:

Join the Discord Server

For bug reports or feature requests, please open an issue in this repository.

License

GridForge is licensed under the MIT License. See LICENSE, NOTICE, and COPYRIGHT for details.