Repository Layout and Build

This page is the operational map of the repo: where things live, how the solution is put together, and what the build actually does.

If you are onboarding as a contributor, this is the page that turns "I know what GridForge is" into "I know where to work and which command to run."

Install the SDK selected by global.json and the runtimes targeted by the test and benchmark projects before running repository commands.

Solution Shape

The solution contains three projects:

Project	Path	Purpose
`GridForge`	`src/GridForge/GridForge.csproj`	Main deterministic voxel-grid library
`GridForge.Tests`	`tests/GridForge.Tests/GridForge.Tests.csproj`	xUnit validation suite
`GridForge.Benchmarks`	`tests/GridForge.Benchmarks/GridForge.Benchmarks.csproj`	BenchmarkDotNet performance and allocation benchmarks

The root solution file is GridForge.slnx.

Repository Layout

Path	What it contains
`src/GridForge`	Library source, package metadata, XML docs generation, and NuGet packaging configuration
`src/GridForge/Configuration`	Grid creation inputs and snapped bounds identity
`src/GridForge/Grids`	Core grid model, managers, node types, storage, topology, and pooling
`src/GridForge/Grids/Storage`	Dense and sparse physical voxel storage
`src/GridForge/Grids/Topology`	Per-grid topology metrics, snapping, dimensions, and world/index projection
`src/GridForge/Spatial`	Shared indices, occupants, partitions, directions, and awareness types
`src/GridForge/Blockers`	Bounds-based obstacle application built on tracer coverage
`src/GridForge/Diagnostics`	Engine-agnostic diagnostic descriptors, geometry, and dirty sessions
`src/GridForge/Support`	Cross-cutting support types and pooled query results
`src/GridForge/Utility`	Tracing and logging support
`tests/GridForge.Tests`	Unit tests organized by subsystem
`tests/GridForge.Benchmarks`	Focused perf and allocation scenarios
`.github/workflows`	CI automation
`.assets/scripts`	Release-oriented PowerShell helpers
`docs/api/guides`	Conceptual guides published alongside the API reference
`docs/api`	DocFX landing page, navigation, and API build configuration

The solution also exposes a small set of root-level "solution items" such as .editorconfig, README.md, AGENTS.md, and LICENSE. Coverage settings live at tests/GridForge.Tests/coverlet.runsettings.

Main Library Build Facts

The library project in src/GridForge/GridForge.csproj establishes a few important build behaviors:

language version defaults to C# 14, with C# 11 for netstandard2.1
target frameworks are netstandard2.1 and net10.0
ImplicitUsings is disabled
Nullable is enabled in the library project
XML documentation files are generated
deterministic and CI build flags are enabled
GeneratePackageOnBuild is enabled
the supported configurations are Debug, Release, and ReleaseLean

That last item is easy to miss: building the library also produces NuGet artifacts.

Package And Dependency Notes

The standard package depends on:

FixedMathSharp
SwiftCollections
SwiftCollections.FixedMathSharp
MemoryPack
Chronicler.Diagnostics

The lean package is built by ReleaseLean or DisableMemoryPack=true and uses:

FixedMathSharp.Lean
SwiftCollections.Lean
SwiftCollections.FixedMathSharp.Lean
Chronicler.MemoryPackShim for annotation compatibility without the MemoryPack runtime dependency
Chronicler.Diagnostics for the same logging and guard surface
the GRIDFORGE_DISABLE_MEMORYPACK compilation symbol

Both package variants also reference System.Text.Json for the netstandard2.1 target only and expose the same core voxel-grid API.

The v10 dependency baseline is FixedMathSharp 8.0.0, SwiftCollections and its FixedMathSharp integration 8.0.0, and Chronicler diagnostics/shim 1.0.0. The source-mode FixedMathSharp package exclusions in the library, tests, and benchmarks use the same 8.0.0 version; compilation and runtime assets come from the sibling projects in that mode.

Packaging also includes the root README.md, LICENSE, NOTICE, COPYRIGHT, and icon.png.

Versioning Behavior

The project is wired to consume GitVersion environment variables when they are available.

In practice that means:

CI can stamp semantic version, assembly version, and informational version automatically
local builds still work without GitVersion and fall back to version 0.0.0

That fallback is intentional and keeps local iteration simple.

What `dotnet build` Produces

When you build src/GridForge/GridForge.csproj, expect:

compiled library outputs under src/GridForge/bin/<Configuration>/<TargetFramework>/
XML documentation alongside the assembly
.nupkg and .snupkg package artifacts because package generation is enabled on build

If you are only expecting a DLL and a testable build, this packaging behavior can look surprising the first time you notice it.

Validation Project Facts

`GridForge.Tests`

The test project:

targets net10.0
is marked as a test project and not packable
references the main library project directly
supports Debug, Release, and ReleaseLean
uses xUnit v3 plus the Visual Studio runner and console runner
includes coverlet.collector
points to coverlet.runsettings

The runsettings exclude generated MemoryPack files from coverage collection so the report measures maintained source.

`GridForge.Benchmarks`

The benchmark project:

targets net10.0
is an executable
references the main library project directly
supports Debug, Release, and ReleaseLean
uses BenchmarkDotNet
is optimized for benchmark runs

This project is where allocation-sensitive or throughput-sensitive changes should be checked.

Common Build Commands

The usual local flow is:

dotnet restore GridForge.slnx
dotnet build GridForge.slnx --configuration Debug
dotnet test GridForge.slnx --configuration Debug --no-build

When iterating across sibling LSF repositories, set $env:UseLocalLsfStack = 'true' and pass -p:DisableTransitiveProjectReferences=true on restore, build and test commands. The global property preserves explicit dependency identities in sibling projects. Library, test and benchmark projects then use sibling FixedMathSharp, SwiftCollections and Chronicler projects, plus the local Chronicler.MemoryPackShim in Lean builds. Without that switch, normal package references and versions remain authoritative.

When you specifically want release-like library artifacts:

dotnet build src/GridForge/GridForge.csproj --configuration Release

Because packaging is enabled on build, this also emits the package artifacts.

API Documentation And GitHub Pages

The Release build produces the assembly and XML documentation consumed by DocFX. Build the local documentation site with:

dotnet build src/GridForge/GridForge.csproj --configuration Release
dotnet tool restore
dotnet tool run docfx docs/api/docfx.json --warningsAsErrors

The authored site surface lives under docs/api:

index.md is the user-facing landing page
guides owns conceptual Markdown published beside the API reference
overrides adds namespace-level orientation and Unity adapter links
templates/gridforge supplies the blue/cyan theme and GitHub header icon
.assets/icon_128x128.png is copied as the site logo and favicon
obj contains generated metadata and HTML and should not be edited

The generated site is written to docs/api/obj/_site. On successful pushes to main, .github/workflows/coverage.yml validates the landing page, API roots, theme, icon, and repository links before publishing the site to GitHub Pages. The coverage report is placed beneath /coverage.

CI Expectations

The CI workflow lives in .github/workflows/build-and-test.yml.

At a high level it:

runs on ubuntu-latest and windows-latest
triggers on pushes except dependabot/**, gh-pages, and version tags like v*
triggers on pull requests targeting main or develop
installs .NET 10
installs and executes GitVersion
restores dependencies
builds the solution in both Release and ReleaseLean
runs the test suite in both Release and ReleaseLean

This is a useful sanity check when deciding whether a change is likely to be cross-platform safe.

Release Helper Script

.assets/scripts/set-version-and-build.ps1 is the repo helper for version-aware release builds.

Its flow is:

locate the solution root
ensure GitVersion environment variables are present
build both Release and ReleaseLean
walk each release target-framework output folder
zip each framework output into a versioned archive under artifacts/releases

That makes it the practical handoff script for release packaging, not just a convenience wrapper around dotnet build.

Build And Repo Pitfalls

Forgetting that the library builds for two target frameworks
Forgetting that build also creates NuGet packages
Assuming CI only validates on one operating system
Editing files under bin, obj, or TestResults instead of the source that produces them
Treating the benchmark project as optional when changing pooling, tracing, storage, topology, or registration behavior