Math Helpers (Numerics)

Altruist ships the math a game simulation keeps rewriting: clamps and approaches, angle wrapping, safe normalization, components along a surface, tuning curves, a replayable random generator, box and ray tests, arc tessellation. This page covers the math layer; the physics layer and the gameplay verbs are built on it, and the TypeScript package mirrors all three for game clients.

Three Layers

Each layer is built only on the one below it. Game code should read like its rules, so it usually calls the top layer.

// Gameplay layer: reads like the rule.
car.JumpOff(groundNormal, jumpSpeed);

// ...which is the physics layer:
car.LinearVelocity = VectorMath2D.AddAlong(Velocity2D.CancelInto(car.LinearVelocity, groundNormal), groundNormal, jumpSpeed);

// ...which is the math layer:
var into = v.X * n.X + v.Y * n.Y;
if (into < 0) v = new Vector2(v.X - n.X * into, v.Y - n.Y * into);
v = new Vector2(v.X + n.X * jumpSpeed, v.Y + n.Y * jumpSpeed);

Determinism

Every helper on these pages is deterministic: the same inputs give the same bits on the same runtime. More than that, each one evaluates exactly the expression written in its XML summary (same operands, same grouping, float / MathF, no fused multiply-add). Replacing that expression written inline with the helper therefore changes no bit, which matters when golden tests hash a simulation's state every tick.

Scalars (Scalar)

using Altruist.Numerics;

speed = Scalar.Approach(speed, maxSpeed, acceleration * dt);
var facing = Scalar.SignOr(velocity.X, fallback: lastFacing);
var stick = Scalar.Quantize(rawStickX);            // same value on client, server and wire
var difficulty = Scalar.Lerp(easy, hard, Scalar.Pow01(skill, 1.5f));

Angles (Angle)

Radians, dimension-agnostic.

Curves (PiecewiseLinear)

Tuning tables as (X, Y) points sorted by X (any ReadOnlySpan<(float, float)>, so an array of named tuples works).

(float Level, float Skill)[] byLevel = { (1, 0.05f), (10, 0.3f), (30, 0.7f), (50, 1f) };
var skill = PiecewiseLinear.Evaluate(byLevel, playerLevel);   // clamped at both ends

(float Time, float Height)[] jumpRise = { (0, 0), (0.17f, 2.6f), (0.33f, 4.5f), (0.5f, 5.4f) };
var t = PiecewiseLinear.Inverse(jumpRise, 3f);                 // when the curve reaches 3; +∞ if never

Deterministic Random (DeterministicRandom)

A seedable xorshift32 whose sequence is fixed forever, identical on every runtime and in the TypeScript package. Use it for anything that must replay exactly (authoritative simulations, bots, golden tests); System.Random may change its algorithm between .NET versions.

var rng = new DeterministicRandom(seed: matchId);
double u   = rng.Next();        // [0, 1)
float  s   = rng.Signed();      // [-1, 1)
float  g   = rng.Gaussian();    // approx. normal, mean 0, std-dev 1 (sum of three uniforms)
int    j   = rng.Jitter(3);     // integer in [-3, 3]
bool   hit = rng.Chance(0.25);  // 25 %

uint saved = rng.State;                         // rollback / replays
var again = DeterministicRandom.FromState(saved);

2D Vectors (VectorMath2D)

using Altruist.TwoD.Numerics; — functions on System.Numerics.Vector2 that the BCL does not offer.

Directions, Yaw and Rotation

Two angle conventions coexist in 2D, and the helpers name them:

• Yaw (Yaw2D, Direction2D.TowardAngle, SpatialQueries2D, BodySteeringExtensions2D): Atan2(dx, dy), 0 faces +Y, positive turns toward +X. Top-down games use it.
• Rotation (Rotation2D, physics bodies, Direction2D.FromPolar): counter-clockwise radians, 0 = +X axis; a body's local +Y is its "up". Side-view games and Box2D use it.

var aim = Direction2D.FromPolarDegrees(35);                   // (cos 35°, sin 35°)
var shot = Direction2D.ClampElevation(aim, minY: -0.3f, maxY: 0.92f);
var tangent = Direction2D.PerpendicularClockwise(groundNormal);

Spatial Queries (SpatialQueries2D)

Stateless yaw-convention predicates for abilities and targeting: IsInRange(from, to, range), IsInCone(origin, yaw, halfAngle, range, target), IsInLine(origin, yaw, length, halfWidth, target). Each has a Position2D overload.

Geometry (Geometry2D, Aabb2D)

Contact and Surface Frames (NormalFrame2D)

A unit normal and its tangent, so contact and surface code says "speed into the wall", "speed along the floor" instead of dot products. Pick the tangent side: NormalFrame2D.Left(n) uses (-n.Y, n.X) (counter-clockwise of the normal), NormalFrame2D.Right(n) uses (n.Y, -n.X) (clockwise: +X on a floor).

var floor = NormalFrame2D.Right(groundNormal);
var speedAlong = floor.Across(body.LinearVelocity);             // + = toward +X on a floor
var forward = floor.TangentToward(nose, fallbackSign: facing);  // along the surface, the way the nose points
var drop = MathF.Max(0, floor.HeightOf(body.Position, hitPoint) - halfHeight);
if (floor.Into(velocity) > 0) Land();

Polylines (Polyline2D)

Build chain / loop shapes from lines and arcs:

var pts = new List<Vector2> { new(-40, 0) };
Polyline2D.AppendArc(pts, centerX: 34, centerY: 6, radius: 6, startDegrees: 270, endDegrees: 360, maxSegmentDegrees: 7.5f);
pts.Add(new Vector2(40, 30));
var loop = Polyline2D.RemoveDuplicates(pts);                  // drops repeats and a closing copy of the first point
world.CreateFixture(boundary, new PhysxFixtureDef2D { Shape = PhysxShape2D.Chain(loop, loop: true) });

Arcs (Trajectory2D)

Trajectory2D (namespace Altruist.TwoD.Numerics.Trajectory) draws designed (not physical) arcs for visuals and lobbed skills: ParabolicY(t, peak, riseEnd, hangEnd) (ease-out rise, hang, ease-in fall), ParabolicSample(start, end, t, ...) and the allocation-free ParabolicPolyline(start, end, ..., Span<Vector2> dest). For real projectile physics use Ballistics2D.