TypeScript Client Package

@altruist/sim2d is the TypeScript twin of the math, physics and gameplay helpers, for game clients that run the same simulation as the server (client-side prediction, replays, offline play, bots in the browser). Same names in camelCase, same semantics, same operation order.

• Dependency-free: plain ESM TypeScript sources, no build step, no runtime dependencies.
• Same layers: @altruist/sim2d/math, @altruist/sim2d/physics, @altruist/sim2d/gameplay (or everything from @altruist/sim2d), plus @altruist/sim2d/flow, the simulation building blocks and the state machine (on the math layer only).
• Works on planck.js bodies directly: the body and world parameters are structural interfaces that a planck Body / World satisfies without a wrapper.

The package lives in the Altruist repository at Clients/TypeScript/sim2d.

Installing

Point a path alias at the sources. The sources import each other with .ts extensions, so a type-checked project enables allowImportingTsExtensions (allowed with noEmit, the usual setup with Vite):

// tsconfig.json
{
  "compilerOptions": {
    "allowImportingTsExtensions": true,
    "paths": { "@altruist/sim2d": ["../altruist/Clients/TypeScript/sim2d/src/index.ts"],
               "@altruist/sim2d/*": ["../altruist/Clients/TypeScript/sim2d/src/*/index.ts"] }
  }
}

// vite.config.ts
resolve: {
  alias: [
    { find: /^@altruist\/sim2d\/(math|physics|gameplay|flow)$/, replacement: fileURLToPath(new URL('../altruist/Clients/TypeScript/sim2d/src/$1/index.ts', import.meta.url)) },
    { find: /^@altruist\/sim2d$/, replacement: fileURLToPath(new URL('../altruist/Clients/TypeScript/sim2d/src/index.ts', import.meta.url)) },
  ],
},

Using It

import { Angle, DeterministicRandom, Scalar, VectorMath2D } from '@altruist/sim2d/math';
import { Ballistics2D, BodyMotion2D, rayCastClosest } from '@altruist/sim2d/physics';
import { GameplayVerbs2D as G } from '@altruist/sim2d/gameplay';

// Gameplay verbs take the body first (C# extension methods there).
G.jumpOff(car.body, surfaceNormal, cfg.jumpSpeed);
G.alignToSurface(car.body, groundNormal, cfg.alignRate);
G.fall(ball.body, gravity, dt, ball.gravityScale);

// Closest surface below, ignoring everything but tagged fixtures.
const below = rayCastClosest(world, from, to, (f) => f.getUserData()?.kind === 'surface', reach);
if (below.found) land(below.point, below.normal, below.distance);

// Same seed, same sequence as the C# DeterministicRandom.
const rng = new DeterministicRandom(seed);

Vectors are plain { x, y } objects (Vec2Like): any object with x and y is accepted (planck Vec2, Pixi points, literals), results are new objects, inputs are never mutated.

Body Interfaces

Each function asks only for what it uses (jumpOff needs a LinearBody), so lightweight test doubles work too.

API Map

C# and TypeScript Results

Each TypeScript function evaluates the same expression in the same order as its C# twin. JavaScript numbers are doubles and C# uses float, so the twins agree to float precision, not bit for bit; what is bit-exact is each language against its own hand-written form of the formula. Two documented rounding differences: Scalar.quantize / roundHalfUp round exact halves up (Math.round) where C# Quantize rounds them to even.

Lengths and speeds are Math.sqrt(x * x + y * y) everywhere, the C# expression. Math.hypot computes the same length more carefully and can differ in the last bit, so client code that measures with Math.hypot keeps its own bits only while it keeps calling Math.hypot; switch both sides of a comparison together. Dot products are the scalar form a.x * b.x + a.y * b.y (C# frames and impacts use Vector2.Dot, which differs from that form only in the sign of a zero result). VectorMath2D.rotateDegrees takes its radians as degrees * (π / 180) (fromPolarDegrees), the C# RotateDegrees as (degrees * π) / 180.

DeterministicRandom is the exception: its integer sequence (nextUint, state) and its next() doubles are identical in both languages (32-bit arithmetic via Math.imul and >>> 0); C# Signed() / Gaussian() round the same double to float.

Tests

The package carries its own tests (Node's built-in runner, no dependencies):

cd Clients/TypeScript/sim2d
node --test "tests/*.test.ts"     # Node 23.6+ runs TypeScript directly

The random-sequence tests assert the same golden values as the C# tests.