GridForge 3.0.0

GridForge

A high-performance, deterministic voxel grid system for spatial partitioning, simulation, and game development.

Lightweight, framework-agnostic, and optimized for lockstep engines.

🚀 Key Features

• Voxel-Based Spatial Partitioning – Build efficient 3D voxel grids with fast access & updates.
• Deterministic & Lockstep Ready – Designed for synchronized multiplayer and physics-safe environments.
• ScanCell Overlay System – Accelerated proximity and radius queries using spatial hashing.
• Dynamic Occupancy & Obstacle Tracking – Manage moving occupants, dynamic obstacles, and voxel metadata.
• Minimal Allocations & Fast Queries – Built with SwiftCollections and FixedMathSharp for optimal performance.
• Framework Agnostic – Works in Unity, .NET, lockstep engines, and server-side simulations.
• Multi-Layered Grid System – Dynamic, hierarchical, and persistent grids.

❓ Why GridForge?

GridForge is built for developers who need deterministic, high-performance, and framework-agnostic spatial grids. Whether you're building a lockstep multiplayer game, a server-driven simulation, or a high-fidelity physics system, GridForge provides the tools to manage voxelized spatial data with predictable and efficient results — all without relying on any specific engine.

📦 Installation

Non-Unity Projects

1. Install via NuGet:

   dotnet add package GridForge
   

2. Or Download/Clone:

   git clone https://github.com/mrdav30/GridForge.git
   

3. Include in Project:

   • Add GridForge to your solution or reference its compiled DLL.

Unity

GridForge is maintained as a separate Unity package. For Unity-specific implementations, refer to:

🔗 GridForge-Unity Repository.

🧩 Dependencies

GridForge depends on the following libraries:

• FixedMathSharp
• SwiftCollections

These dependencies are automatically included when installing.

📖 Library Overview

🗂 Core Components

📖 Usage Examples

🔹 Creating a Grid

GridConfiguration config = new GridConfiguration(new Vector3d(-10, 0, -10), new Vector3d(10, 0, 10));
GlobalGridManager.TryAddGrid(config, out ushort gridIndex);

🔹 Querying a Grid for Voxels

Vector3d queryPosition = new Vector3d(5, 0, 5);
if (GlobalGridManager.TryGetGridAndVoxel(queryPosition, out VoxelGrid grid, out Voxel voxel))
 Console.WriteLine($"Voxel at {queryPosition} is {(voxel.IsOccupied ? "occupied" : "empty")}");
}

🔹 Adding a Blocker

BoundingArea blockArea = new BoundingArea(new Vector3d(3, 0, 3), new Vector3d(5, 0, 5));
Blocker blocker = new Blocker(blockArea);
blocker.ApplyBlockage();

🔹 Attaching a Partition to a Voxel

if (GlobalGridManager.TryGetGrid(queryPosition, out VoxelGrid grid, out Voxel voxel))
{
    PathPartition partition = new PathPartition();
    partition.Setup(voxel.GlobalVoxelIndex);
    voxel.AddPartition(partition);
}

🔹 Scanning for Nearby Occupants

Vector3d scanCenter = new Vector3d(0, 0, 0);
Fixed64 scanRadius = (Fixed64)5;
foreach (IVoxelOccupant occupant in ScanManager.ScanRadius(scanCenter, scanRadius))
{
    Console.WriteLine($"Found occupant at {occupant.WorldPosition}");
}

🧪 Testing and Validation

GridForge includes comprehensive unit tests and a BenchmarkDotNet performance suite.

Run tests with:

dotnet test

Run benchmarks with:

dotnet run --project tests/GridForge.Benchmarks/GridForge.Benchmarks.csproj -c Release -- list
dotnet run --project tests/GridForge.Benchmarks/GridForge.Benchmarks.csproj -c Release -- all --filter '*'

Benchmark reports are written to BenchmarkDotNet.Artifacts/results/.

🔄 Compatibility

• .NET Standard 2.1+
• .NET 8+
• Unity 2020+ (via - GridForge-Unity)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contributors

• David Oravsky - Lead Developer
• Contributions Welcome! Open a PR or issue.

💬 Community & 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.

We welcome feedback, contributors, and community discussion across all projects.