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:

Approach	Best fit	Tradeoff
Single large grid	Small or fixed worlds	Simple, but can become wasteful or awkward to stream
Multiple conjoined grids	Large worlds, loaded regions, tiled simulation spaces	More flexible, but needs reliable ownership and neighbor handling
Hierarchical grids	Very large or multi-scale worlds	Powerful, but easy to overbuild too early

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
• 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
• 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:

Package	Use when
GridForge	You want the default package with MemoryPack, FixedMathSharp, and SwiftCollections.
GridForge.Lean	You want the same core voxel-grid API without the direct MemoryPack dependency, using FixedMathSharp.Lean and SwiftCollections.Lean.

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

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.

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

Concept	Role
GridWorld	Owns voxel size, spatial hashing, active grids, lifecycle, events, and top-level lookup for one isolated world.
VoxelGrid	Owns one grid's snapped bounds, voxels, scan cells, neighbor relationships, obstacle summary state, and versioning.
Voxel	Represents one snapped cell with obstacle, occupant, partition, boundary, and cached neighbor state.
ScanCell	Groups voxels into query buckets so radius scans can skip empty regions.
GridTracer	Converts lines and bounds into covered voxels or scan cells across the active grids in a world.
BoundsBlocker	Applies and removes obstacle state over traced world-space bounds.
IVoxelOccupant	Represents dynamic entities that can be registered, deregistered, and scanned.
IVoxelPartition	Attaches typed voxel-local metadata or behavior directly to a voxel.

Documentation

Start with the wiki:

• Wiki Home
• Getting Started
• Core Concepts
• 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, or other allocation-sensitive paths.

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.