Thunder.UnitsNET.Vectors

A unit-aware 2D/3D vector library for physics-driven game loops. Built on UnitsNet, every vector component carries its physical unit — so LengthVector2 / Duration returns a SpeedVector2, not a dimensionless float.

📖 API docs

Packages

Package	Purpose	NuGet
Thunder.UnitsNET.Vectors	Core vector types and physics operators
Thunder.UnitsNET.Vectors.MonoGame	XNA/MonoGame Vector2/Vector3 conversion extensions
Thunder.UnitsNET.Vectors.Geometry	Unit-aware 2D geometry shapes
Thunder.UnitsNET.Vectors.Geometry.MonoGame	Geometry → MonoGame rendering primitives

Quick start

// Install
// dotnet add package Thunder.UnitsNET.Vectors
// dotnet add package Thunder.UnitsNET.Vectors.MonoGame  (optional)

using Thunder.UnitsNET.Vectors;
using Thunder.UnitsNET.Vectors.MonoGame;
using UnitsNet;
using UnitsNet.Units;

// Create a position vector
var position = new LengthVector2(Length.FromMeters(3), Length.FromMeters(4));

// Kinematics: v = Δx / Δt
var velocity = position / Duration.FromSeconds(1);          // SpeedVector2

// Dynamics: F = ma
var mass     = Mass.FromKilograms(10);
var accel    = new AccelerationVector2(
    Acceleration.FromMetersPerSecondSquared(2),
    Acceleration.FromMetersPerSecondSquared(0));
var force    = accel * mass;                                 // ForceVector2

// Dot product: work W = F · d  (returns Energy)
Energy work = force.Dot(position);

// Convert to XNA Vector2 for rendering (pixels per metre = 64)
const double ppm = 64;
Vector2 screenPos = position.ToXnaVector2(LengthUnit.Meter, ppm);

Architecture

Type model

All concrete vector types are readonly partial record struct values. Component types come from UnitsNet (Length, Speed, Force, …); DoubleVector2/DoubleVector3 hold bare Double components.

Each type is composed from three layers:

Layer	Example file	What it provides
Stub	LengthVector2.cs	Declares the type and its primary constructor
Generated	LengthVector2.g.cs (build output)	Arithmetic, Zero, Magnitude, As, Normalize
Hand-written partials	LengthVector2.Kinematics.cs	Cross-type physics operators (/ Duration → SpeedVector2)

Source generator

Thunder.UnitsNET.Vectors.Generators is a Roslyn incremental source generator. It reads every [GenerateVector2] / [GenerateVector3] attribute and emits the arithmetic partial. Consumers never reference the generator directly — it is wired as an Analyzer reference and compiled into the core DLL.

Package structure

Thunder.UnitsNET.Vectors.sln
├── src/
│   ├── Thunder.UnitsNET.Vectors/            ← published
│   │   ├── Vector2/                         ← 2D quantity types + partials
│   │   └── Vector3/                         ← 3D quantity types + partials
│   ├── Thunder.UnitsNET.Vectors.MonoGame/   ← published
│   │   └── Extensions/                      ← ToXnaVector2 / ToXnaVector3
│   ├── Thunder.UnitsNET.Vectors.Generators/ ← not published (Roslyn tooling)
│   └── Thunder.UnitsNET.Vectors.GoDot/      ← not published (incomplete scaffold)
└── tests/
    ├── Thunder.UnitsNET.Vectors.Tests/
    └── Thunder.UnitsNET.Vectors.MonoGame.Tests/

Supported vector types

2D — DoubleVector2, LengthVector2, SpeedVector2, AccelerationVector2, ForceVector2, JerkVector2, ImpulseVector2, MagneticFieldVector2, MagnetizationVector2, LinearDensityVector2, ElectricFieldVector2

3D — DoubleVector3, LengthVector3, SpeedVector3, AccelerationVector3, ForceVector3, JerkVector3, ImpulseVector3, MagneticFieldVector3, MagnetizationVector3, MassFluxVector3, ElectricFieldVector3, ElectricCurrentDensityVector3, TemperatureGradientVector3

Building and testing

Requires .NET 10 SDK.

dotnet build
dotnet test

Milestone status

See docs/STATUS.md for the current implementation milestone.

The full roadmap — including design decisions and upcoming work — is in docs/roadmap.md.

Contributing

1. Read docs/CLAUDE.md for the project conventions (branch naming, step progression, how decisions are surfaced).
2. Each feature follows TDD: RED commit (failing build or test) → GREEN commit (passing) → merge to develop.
3. Open a PR against develop; main is reserved for release-tagged commits.

License

MIT — see LICENSE.