Home

GridForge Wiki

GridForge is a deterministic, framework-agnostic voxel grid library for spatial partitioning, simulation, and game-development workflows. It is built around fixed-point math, global grid registration, fast scan-based queries, obstacle and occupant tracking, and allocation-conscious internals.

This page is the wiki's anchor document. The README.md is a concise entry point, while the wiki is the deeper technical companion for consumers and contributors. When the project evolves, update this page first so the rest of the wiki has a stable anchor.

What GridForge Provides

• Deterministic voxel-grid spatial partitioning using FixedMathSharp
• Global registration and lookup across one or more grids
• Snapped world-space bounds through GridConfiguration
• Fast proximity and coverage queries via voxels and scan cells
• Obstacle, blocker, occupant, and partition workflows
• Allocation-conscious internals backed by pooling and SwiftCollections
• Cross-target support for netstandard2.1 and net8.0

Who This Wiki Is For

• Library consumers who need to get a grid online quickly and safely
• Contributors who need a map of the codebase and its invariants
• Maintainers who need a shared documentation source of truth for future pages

Wiki Navigation

The wiki is organized as a set of focused pages. Home stays broad and stable; the rest of the pages serve as targeted deep dives.

Page	Focus
Home	Shared project context, architecture snapshot, invariants, and documentation roadmap
Getting Started	Installation, first grid setup, basic queries, and logging setup
Core Concepts	Grids, voxels, scan cells, occupants, blockers, partitions, and snapped bounds
Common Workflows	Create a grid, resolve a voxel, scan nearby space, apply a blocker, attach a partition
Architecture Overview	How the major subsystems fit together and where responsibilities live
GlobalGridManager	Setup/reset lifecycle, registration, hashing, and top-level query behavior
VoxelGrid and Voxel Model	Grid generation, voxel state, neighbor relationships, and cached data
Scan Cells and Query Flow	Scan-cell overlay structure, neighborhood lookups, and query performance
GridTracer and Coverage	Line and bounds tracing, covered voxel sets, and multi-grid implications
Blockers and Obstacles	Blocker, BoundsBlocker, obstacle propagation, stacked blockers, and removals
Occupants and Partitions	IVoxelOccupant, IVoxelPartition, PartitionProvider, and lifecycle rules
Diagnostics and Logging	GridForgeLogger, verbosity, tracing support, and safe debugging patterns
Repository Layout and Build	Solution structure, package generation, CI expectations, and release notes
Testing and Benchmarking	xUnit layout, global-state isolation, benchmark usage, and validation strategy
Determinism, Snapping, and Pooling	Core invariants that must remain true across framework targets
Recipes	End-to-end usage patterns for gameplay, simulation, and server-side systems
FAQ and Troubleshooting	Common mistakes, debugging checklists, and "why is this voxel result odd?" guidance

Quick Technical Snapshot

• Language: C# 11
• Main library: src/GridForge
• Test suite: tests/GridForge.Tests
• Benchmarks: tests/GridForge.Benchmarks
• Target frameworks: netstandard2.1, net8.0
• Test framework: xUnit v3
• Benchmark framework: BenchmarkDotNet
• Key packages: FixedMathSharp, SwiftCollections, MemoryPack
• Packaging note: GeneratePackageOnBuild is enabled, so library builds also emit NuGet packages

The Core Mental Model

The library is easiest to reason about in this order:

1. Define world-space bounds with GridConfiguration.
2. Register the grid through GlobalGridManager.
3. Resolve world positions into a VoxelGrid and Voxel.
4. Use scan cells and tracing helpers for broader spatial queries.
5. Apply blockers, occupants, or partitions to mutate grid state.
6. Reset global state explicitly when tests or tools need a clean world.

The most important architectural reality is that GridForge is not primarily instance-scoped. Shared global state is part of the design, and most contributor mistakes come from forgetting setup, reset, snapping, or pooled lifetime rules.

Architecture At A Glance

Type	Role
GlobalGridManager	Static entry point for setup, reset, grid registration, spatial hashing, and top-level queries
VoxelGrid	Owns a single grid's dimensions, voxels, scan cells, neighbor relationships, and versioned state
Voxel	Represents one snapped cell and tracks occupants, obstacles, partitions, and cached neighbor data
ScanCell	Overlay node used to accelerate neighborhood and area queries
GridTracer	Converts lines and bounds into covered voxel sets across one or more grids
GridObstacleManager	Applies and clears obstacle state on voxels
GridOccupantManager	Adds, removes, and queries occupant state
GridScanManager	Performs scan-driven spatial queries
Blocker / BoundsBlocker	Turns traced world-space regions into obstacle mutations
IVoxelOccupant / IVoxelPartition / PartitionProvider	Extension points for custom occupancy and metadata workflows

Repository Map

Path	Purpose
src/GridForge/Configuration	Grid configuration and identity types such as GridConfiguration
src/GridForge/Grids/Managers	Global and per-grid behavior managers
src/GridForge/Grids/Nodes	Voxel and ScanCell node types
src/GridForge/Grids/Support	Event info types and pools
src/GridForge/Spatial	Shared indices, directions, occupants, partitions, and awareness abstractions
src/GridForge/Blockers	World-space blocker abstractions built on grid coverage
src/GridForge/Utility	Tracing and logging helpers
tests/GridForge.Tests/Grids	Grid and manager behavior tests
tests/GridForge.Tests/Blockers	Blocker coverage and removal tests
tests/GridForge.Tests/Spatial	Spatial type and index tests
tests/GridForge.Tests/Utility	Logger and tracer tests

Non-Negotiable Invariants

• Call GlobalGridManager.Setup() before using most grid APIs.
• Call GlobalGridManager.Reset() when tests or tools need isolated global state.
• Keep core spatial logic in fixed-point math. Do not casually introduce float or double.
• Expect bounds and incoming positions to be snapped to voxel size.
• Treat pooled objects and collections as short-lived unless ownership is explicit.
• Preserve deterministic behavior across both target frameworks.
• Respect existing synchronization around shared mutable state.
• Route logging through GridForgeLogger, not direct console output.

Build And Validation

Useful commands when working in the repository:

dotnet restore GridForge.sln
dotnet build GridForge.sln --configuration Debug
dotnet test GridForge.sln --configuration Debug --no-build
dotnet run --project tests/GridForge.Benchmarks/GridForge.Benchmarks.csproj -c Release -- list

Benchmarks are most valuable when changing tracing, registration, pooling, caching, or other allocation-sensitive paths.

Documentation Notes

• Keep the README concise and external-facing; use the wiki for depth.
• Prefer one focused page per subsystem instead of one giant reference dump.
• When a new page is added, link it from Home and state the page's scope clearly.
• If code behavior changes in a way that affects setup, determinism, pooling, tracing, blockers, or tests, reflect that here before expanding the deeper pages.
• Treat source and tests as the behavioral contract when README examples lag behind the implementation.

Recommended Reading Order

If you are new to the project, read in this order:

1. README.md
2. This Home page
3. src/GridForge/GridForge.csproj
4. src/GridForge/Grids/Managers/GlobalGridManager.cs
5. src/GridForge/Grids/VoxelGrid.cs
6. src/GridForge/Grids/Nodes/Voxel.cs
7. src/GridForge/Utility/GridTracer.cs
8. The closest matching test file under tests/GridForge.Tests

Documentation Approach

The wiki is not trying to restate every public API member in prose. Its job is to make the library understandable quickly: what the system does, where behavior lives, which invariants matter, and where someone should go next. If we keep this page accurate, the rest of the wiki stays easier to extend without drifting.