https://github.com/mrdav30/gridforge
A high-performance, deterministic spatial grid management system for simulations and game development.
https://github.com/mrdav30/gridforge
ai deterministic game-development grid lockstep pathfinding spatial
Last synced: 23 days ago
JSON representation
A high-performance, deterministic spatial grid management system for simulations and game development.
- Host: GitHub
- URL: https://github.com/mrdav30/gridforge
- Owner: mrdav30
- License: mit
- Created: 2025-02-17T03:13:58.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-17T04:11:18.000Z (over 1 year ago)
- Last Synced: 2025-02-17T04:28:17.700Z (over 1 year ago)
- Topics: ai, deterministic, game-development, grid, lockstep, pathfinding, spatial
- Language: C#
- Homepage:
- Size: 0 Bytes
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# GridForge
[](https://github.com/mrdav30/GridForge/actions/workflows/dotnet.yml)
[](https://mrdav30.github.io/GridForge/)
[](https://www.nuget.org/packages/GridForge)
[](https://www.nuget.org/packages/GridForge)
[](https://github.com/mrdav30/GridForge/blob/main/LICENSE)
[](https://github.com/mrdav30/GridForge)
**GridForge** is a deterministic, high-performance voxel-grid library for spatial partitioning, simulation, and game-development workflows.
The core unit is an explicit `GridWorld`. That lets you run multiple isolated worlds in one process without leaking grid registration, tracing, blockers, occupants, or scan queries across world boundaries.
## Install
```bash
dotnet add package GridForge
```
GridForge targets `netstandard2.1` and `net8.0`.
### Package Variants
GridForge is published in two build variants so you can choose between built-in `MemoryPack` support and a leaner dependency set:
- `GridForge`
Includes `MemoryPack` and depends on the standard `FixedMathSharp` and `SwiftCollections` packages. This is the best default choice for most .NET applications.
- `GridForge.Lean`
Excludes the `MemoryPack` package, swaps to `FixedMathSharp.NoMemoryPack` and `SwiftCollections.Lean`, and uses internal shim attributes so the same source can compile without the dependency. Choose this when you do not need built-in MemoryPack serialization, when you prefer a different serializer, or when you want the leanest dependency surface.
Both variants expose the same core voxel-grid API. The main difference is whether `MemoryPack` and the standard dependency chain are included.
Install via NuGet:
- Standard package:
```bash
dotnet add package GridForge
```
- Lean package:
```bash
dotnet add package GridForge.Lean
```
If you build from source, the repository also provides matching release configurations:
- `Release` builds the standard `GridForge` package and release archives.
- `ReleaseLean` builds the `GridForge.Lean` package and release archives.
### Unity
Unity-specific integration lives in the separate [GridForge-Unity](https://github.com/mrdav30/GridForge-Unity) repository.
## Quick Start
```csharp
using System;
using FixedMathSharp;
using GridForge.Configuration;
using GridForge.Grids;
using GridWorld world = new GridWorld();
GridConfiguration configuration = new(
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(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}");
}
```
Key ideas:
- `GridWorld` owns runtime state such as voxel size, spatial hash size, active grids, tracing, blocker reactivity, and world-space lookup.
- `VoxelGrid` is world-local. `GridIndex` is unique only within its owning world.
- `WorldVoxelIndex` is the cross-system identity for a voxel and includes world scope.
## Why Explicit Worlds
Having `GridWorld` own world state makes it practical to build:
- multi-world simulations with overlapping local coordinates
- streamed loading and unloading without cross-world state leakage
- save and load flows keyed by world identity
- higher-level orchestration such as galaxies, sectors, or planet registries above the library
## Start With The Wiki
- [Wiki Home](https://github.com/mrdav30/GridForge/wiki/Home)
- [Getting Started](https://github.com/mrdav30/GridForge/wiki/Getting-Started)
- [Core Concepts](https://github.com/mrdav30/GridForge/wiki/Core-Concepts)
- [Common Workflows](https://github.com/mrdav30/GridForge/wiki/Common-Workflows)
- [Architecture Overview](https://github.com/mrdav30/GridForge/wiki/Architecture-Overview)
- [Recipes](https://github.com/mrdav30/GridForge/wiki/Recipes)
- [FAQ and Troubleshooting](https://github.com/mrdav30/GridForge/wiki/FAQ-and-Troubleshooting)
## Local Validation
```bash
dotnet restore GridForge.slnx
dotnet build GridForge.slnx --configuration Debug
dotnet test GridForge.slnx --configuration Debug --no-build
```
For benchmark discovery:
```bash
dotnet run --project tests/GridForge.Benchmarks/GridForge.Benchmarks.csproj -c Release -- list
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and workflow details.
## Community & Support
For questions, discussions, or general support, join the official Discord community:
👉 **[Join the Discord Server](https://discord.gg/mhwK2QFNBA)**
For bug reports or feature requests, please open an issue in this repository.
## License
GridForge is licensed under the MIT License. See [LICENSE](LICENSE), [NOTICE](NOTICE), and [COPYRIGHT](COPYRIGHT) for details.