Gravitas 1.0.0

Gravitas

Deterministic physics for lockstep simulations and games.

Gravitas is an engine-agnostic fixed-point physics library for simulation-heavy .NET projects. It is designed to sit above the LSF stack:

• FixedMathSharp for deterministic fixed-point math, transforms, and reusable fixed-point geometry algebra.
• SwiftCollections for low-allocation collections and pools.
• GridForge for explicit voxel worlds, spatial partitioning, and topology-aware traversal helpers.
• Chronicler.Core for deterministic state transfer and shared save/apply lifecycle helpers.

API Stability

Gravitas maintains first-class 3D, pure 2D, and mixed 2D/3D runtime paths. Public API changes should be intentional and documented; major-version changes may refine contracts when determinism, physics correctness, physical plausibility, or maintainability requires it.

The unit test project includes focused runtime, settings, query, partition, coroutine, collision, CCD, constraints, ragdolls, serialization, 2D, and mixed-dimension coverage. The benchmark project covers context lifecycle, registration, partitioning, simulation, queries, diagnostics, mesh paths, constraints, mixed broad phase, and CCD scaling. Use AGENTS.md for detailed contributor guidance.

Why Gravitas?

• Deterministic runtime math through Fixed64, Vector2d, Vector3d, and FixedQuaternion.
• Engine-agnostic host boundary through IMatterAgent instead of direct renderer or ECS coupling.
• Grid-backed broad-phase partitioning through GridForge GridWorld, voxel tracing, PhysicsPartition, and PhysicsPartition2D.
• Runtime systems for 3D, pure 2D, and mixed 2D/3D bodies/colliders, authored shape definitions, compound collision assets, collision pairs, collision detection/response, 2D/3D joints and ragdolls, opt-in CCD, raycasts, swept-sphere and swept-circle queries, pure 2D overlap/raycast queries, and physics settings.
• Mixed 2D/3D simulation where 2D bodies are embedded as explicit finite slabs/prisms and constrained to X/Z impulse response.

Install

dotnet add package Gravitas

Gravitas targets netstandard2.1 and net8.0.

Package Variants

Gravitas is configured for two package variants:

• Gravitas: Includes MemoryPack and depends on the standard FixedMathSharp, SwiftCollections, SwiftCollections.FixedMathSharp, FixedMathSharp.Chronicler, GridForge, and Chronicler.Core packages.
• Gravitas.Lean: Excludes the direct MemoryPack package and swaps to the lean dependency chain: FixedMathSharp.Lean, SwiftCollections.Lean, SwiftCollections.FixedMathSharp.Lean, FixedMathSharp.Chronicler.Lean, GridForge.Lean, Chronicler.Core.Lean, and Chronicler.MemoryPackShim.

Both variants are intended to expose the same core physics API. The difference is whether built-in MemoryPack support and the standard dependency chain are present.

FixedMathSharp Ownership Boundary

FixedMathSharp owns reusable deterministic arithmetic, exact geometry, and its internal fixed-width wide mechanics. Gravitas is its sole intentional non-test friend and owns the rigid-body meaning built from those mechanics: mass and inertia interpretation, contact levers, impulses, restitution, friction, warm-start accumulation, and CCD response. FixedMathSharp internal types never appear in Gravitas public or serialized APIs.

This is a one-way, release-coupled implementation boundary, not a public FixedMathSharp extension mechanism or a precedent for SwiftCollections, GridForge, Trailblazer, or host adapters. FixedMathSharp is released first; SwiftCollections and GridForge are then validated and released in dependency order before Gravitas is rebuilt against the exact released FixedMathSharp version and the complete package-only lower stack.

The install command above selects the standard package. To use the lean dependency profile instead:

dotnet add package Gravitas.Lean

If you build from source, the repository provides matching configurations:

• Release builds the standard Gravitas package.
• ReleaseLean builds the Gravitas.Lean package.

For local development against the repository, reference the project directly:

<ItemGroup>
  <ProjectReference Include="path/to/Gravitas/src/Gravitas/Gravitas.csproj" />
</ItemGroup>

Mental Model

Gravitas is centered around explicit world-context ownership:

1. A host creates or attaches a GravitasWorldContext, which owns an explicit GridForge.Grids.GridWorld.
2. Host objects expose deterministic transform and world context access through IMatterAgent.
3. GravitasWorldContext owns fixed-step clock state, settings, physical environment values, lifecycle hooks, and context-local services.
4. GravitasPhysicsService owns 3D body/collider registration, collider ID lookup, collision-pair pooling, and physics lifecycle work for one context.
5. GravitasConstraint3DService and GravitasConstraint2DService own deterministic joint IDs, endpoint-bound joint lifetimes, atomic ragdoll runtimes, linked-collider self-filtering, motor targets, replay hashing, and joint diagnostics.
6. GravitasPhysics2DService owns pure 2D registration, pair state, response, and visualization publishing for one context.
7. GravitasMixedCollisionService owns the explicit mixed 2D/3D broad-phase, pair lifecycle, and constrained response path when PhysicsRuntimeMode.Mixed is active.
8. GravitasCollisionService and GravitasCollision2DService map colliders into GridForge voxels and activate partition payloads for collision checks.
9. GravitasQuery2DService, GravitasQuery3DService, GravitasQueryMixedService, and GravitasCoroutineService own query and coroutine state per context.
10. SolidBody and SolidBody2D own simulated body state and Chronicler state recording for their runtime path. Their explicit BodyMotionType selects solver-controlled Dynamic, host-controlled Kinematic, or immobile Static ownership; FreezeAxes independently constrains the degrees of freedom available to a dynamic body.
11. LSCollider and LSCollider2D are closed public runtime hierarchies that own shape state, bounds, layers, collider-local physical ignore masks, trigger/contact events, and GridForge partition coordinates. Engine adapters should map host assets into ColliderShapeDefinition or ColliderShapeDefinition2D, then call CreateCollider() to obtain the common runtime base type.

Typical integration creates or attaches a context, initializes bodies and colliders against agents bound to that context, then advances the simulation through Simulate(), LateSimulate(), Visualize(), and LateVisualize() according to the host's fixed-frame loop.

Main Systems

Repository Map

Build And Test

Install the SDK selected by global.json and the .NET 8 runtime used by the test and benchmark executables.

dotnet restore Gravitas.slnx
dotnet build Gravitas.slnx --configuration Release
dotnet test Gravitas.slnx --configuration Release

Validate the lean package path when changing package references, serialization, or conditional MemoryPack behavior:

dotnet build Gravitas.slnx --configuration ReleaseLean
dotnet test Gravitas.slnx --configuration ReleaseLean

For focused unit-test work:

dotnet test tests/Gravitas.Tests/Gravitas.Tests.csproj --configuration Release

Release builds generate NuGet packages because GeneratePackageOnBuild is enabled.

Benchmarks

The benchmark project includes physics hot-path measurements for context lifecycle, body/collider registration, partitioning, simulation, query services, diagnostics, mesh paths, 3D constraints, mixed broad phase, and CCD scaling.

List available benchmark selections:

dotnet build tests/Gravitas.Benchmarks/Gravitas.Benchmarks.csproj -c Release -f net8.0
dotnet tests/Gravitas.Benchmarks/bin/Release/net8.0/Gravitas.Benchmarks.dll list

Run all benchmarks:

dotnet build tests/Gravitas.Benchmarks/Gravitas.Benchmarks.csproj -c Release -f net8.0
dotnet tests/Gravitas.Benchmarks/bin/Release/net8.0/Gravitas.Benchmarks.dll all

See the benchmark README for runner details and benchmark authoring notes.

Documentation

• Documentation site
• API reference
• GitHub Wiki
• Coverage report
• AGENTS.md for deterministic, performance-sensitive, and physics-design contributor guidance
• docs/wiki/OVERVIEW.md for context ownership, host integration, collisions, queries, serialization/replay, and diagnostics

Build the API site locally from the repository root:

dotnet build src/Gravitas/Gravitas.csproj --configuration Release --framework net8.0
dotnet tool restore
dotnet tool run docfx docs/api/docfx.json

If behavior changes, keep code, tests, this README, and benchmark documentation aligned.

Compatibility

• netstandard2.1
• net8.0
• Windows, Linux, and macOS host environments supported by .NET

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and AGENTS.md before opening a pull request.

Prefer focused changes with release-mode validation. Determinism, physics correctness, low time complexity, and allocation behavior are first-order design constraints.

Community And 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.

License

Gravitas is licensed under the MIT License. See LICENSE, NOTICE, and COPYRIGHT for the project terms and attribution details.