GridForge 1.1.1

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

Run tests with:

dotnet test

🔄 Compatibility

• .NET Framework 4.7.2+
• .NET Core / .NET 6+
• Unity 2020+ (via - GridForge-Unity.)
• Supports FixedMathSharp for deterministic precision
• Supports SwiftCollections for optimal performance

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

📧 Contact

For questions or support, open an issue on GitHub.