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

Component	Description
GlobalGridManager	Manages VoxelGrids, global spatial queries, and grid registration.
VoxelGrid	Represents a single grid containing voxels & scan cells.
Voxel	Represents a voxel cell with occupant, obstacle, and partition data..
ScanCell	Handles spatial indexing for fast neighbor and radius queries..
GridTracer	Trace lines, areas, and paths across voxels and scan cells.
GridObstacleManager	Manage dynamic grid obstacles at runtime..
GridOccupantManager	Manage and query occupants in voxels.
GridScanManager	Optimized scan queries (radius, box, path, etc).
Blockers	Define static or dynamic voxel blockers.
Partitions	Adds meta-data and custom logic to voxels.

---

📖 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)

---

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING guide for details on how to propose changes, report issues, and interact with the community.

---

👥 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.

---

License

This project is licensed under the MIT License.

See the following files for details:

• LICENSE – standard MIT license
• NOTICE – additional terms regarding project branding and redistribution
• COPYRIGHT – authorship information