Getting Started

This guide gets a .NET project using FixedMathSharp, then points you to the deeper behavior contracts when you need them.

1. Choose a package

Most applications should start here:

dotnet add package FixedMathSharp
If you need... Choose...
Core math with MemoryPack support FixedMathSharp
Core math without a direct MemoryPack dependency FixedMathSharp.Lean
Record hashes or exact Chronicler simulation-time interop FixedMathSharp.Chronicler or .Lean
FluentAssertions helpers for fixed-point tests FixedMathSharp.FluentAssertions or .Lean
Unity packages and Unity-specific interop FixedMathSharp-Unity

Pair standard companion packages with FixedMathSharp, and Lean companion packages with FixedMathSharp.Lean.

See the companion guide for exact duration conversions and complete-step counting.

2. Run a fixed-point calculation

The main numeric types live in FixedMathSharp. Geometry types live in FixedMathSharp.Geometry, and deterministic random streams live in FixedMathSharp.Random.

using FixedMathSharp;
using FixedMathSharp.Geometry;
using FixedMathSharp.Random;

Fixed64 tick = Fixed64.One / 60;
Vector3d position = Vector3d.Zero;
Vector3d velocity = new(6, 0, 2);

position += velocity * tick;

var random = DeterministicRandom.FromWorldFeature(
    worldSeed: 123456789UL,
    featureKey: 0xC0FFEEUL);

int variant = random.Next(0, 4); // [0, 4)

FixedBoundSphere playableWorld = new(
    Vector3d.Zero,
    new Fixed64(100));

bool positionIsValid = playableWorld.Contains(position);

Creating the same random stream with the same seed, feature key, and index produces the same sequence. Keep stream ownership and call order explicit; a deterministic generator cannot make a changing call sequence deterministic.

3. Create values intentionally

Fixed64 whole = new Fixed64(12);
Fixed64 decimalValue = Fixed64.FromDecimal(12.5m);
Fixed64 ratio = Fixed64.One / 60;
Fixed64 boundaryValue = Fixed64.FromDouble(externalDouble);

Use FromDouble and floating-point conversions at engine, UI, or file-format boundaries. Prefer fixed-point constants and operators once data enters the deterministic runtime.

Fixed64.FromRaw(long) is different: it interprets the input as an already scaled Q32.32 payload. Use it only for raw-value protocols and exact fixtures. Read Fixed64 Representation before working with raw values, domain limits, or overflow behavior.

4. Know the core conventions

  • 3D semantic forward is +Z; right is +X; up is +Y.
  • 4x4 transforms use row vectors, with translation in M41, M42, and M43.
  • Default geometry containment and intersection include boundaries.
  • Try* methods report the failure described by that member. Invalid arguments may still throw, so check the API reference for the exact contract.
  • Ordinary operators round or saturate at each operator boundary. Fused and full-domain APIs preserve wider intermediates until the final result.

Read Coordinate Conventions, Bounds and Geometry, and Full-Domain Arithmetic when those rules affect your design.

5. Choose serialization deliberately

The standard package includes MemoryPack integration. The Lean package excludes the MemoryPack-specific partial files and replaces the direct MemoryPack dependency with the Chronicler.MemoryPackShim compatibility package.

  • Use MemoryPack for compact binary state, snapshots, and hot serialization paths.
  • Use JSON for tooling, diagnostics, configuration, and interoperability.
  • Do not use ToString() as a persistence format. See Diagnostics Formatting.

Build from source

Install the .NET 10 SDK selected by global.json and the .NET 10 runtime used by the test and benchmark targets.

git clone https://github.com/mrdav30/FixedMathSharp.git
cd FixedMathSharp
dotnet restore FixedMathSharp.slnx --property:Configuration=Debug
dotnet build FixedMathSharp.slnx --configuration Debug --no-restore
dotnet test FixedMathSharp.slnx --configuration Debug --no-build

The contributor workflow and release-configuration checks live in CONTRIBUTING.md. For coordinated development against unreleased Chronicler APIs, use that guide's source-development mode with a sibling checkout. Release validation uses published dependencies.

Next steps

Edit this page