disko:math

Import with import { … } from "disko:math". Generated from the module's shipped declarations. See Randomness & determinism for a guide.

disko:math — deterministic scalars, vectors, angles, elementary functions and seeded random numbers.

Every function is pure and returns bit-identical results on every host. Wrong types throw TypeError; invalid values (non-finite numbers, zero vectors, empty arrays, reversed ranges) throw RangeError. Error messages name the function and the argument, for example normalize: vector has zero length.

Angles are radians. The y axis points down on screen, so a positive rotation turns clockwise on screen.

Types

Vector

A point or vector. Other properties on input objects are ignored.

export interface Vector {
    readonly x: number;
    readonly y: number;
}

Tolerance

Optional absolute tolerance that widens every boundary comparison.

export interface Tolerance {
    readonly epsilon?: number;
}

RandomState

Seeded xoshiro128** state: four uint32 words, never all zero. Frozen.

export interface RandomState {
    readonly a: number;
    readonly b: number;
    readonly c: number;
    readonly d: number;
}

Draw

One draw: the value and the state to use for the following draw.

export interface Draw<T> {
    value: T;
    next: RandomState;
}

Constants

PI

3.141592653589793.

export const PI: number;

TAU

2 * PI.

export const TAU: number;

ZERO

The frozen zero vector { x: 0, y: 0 }.

export const ZERO: Vector;

Functions

clamp

Clamps value to [min, max].

export function clamp(value: number, min: number, max: number): number;

Throws: RangeError when min > max.

lerp

Linear interpolation a + (b - a) * t; t is not clamped.

export function lerp(a: number, b: number, t: number): number;

inverseLerp

The inverse of lerp: (value - a) / (b - a).

export function inverseLerp(a: number, b: number, value: number): number;

Throws: RangeError when a === b.

remap

Maps value from [fromMin, fromMax] onto [toMin, toMax]: lerp(toMin, toMax, inverseLerp(fromMin, fromMax, value)), unclamped.

export function remap(value: number, fromMin: number, fromMax: number, toMin: number, toMax: number): number;

Throws: RangeError when fromMin === fromMax.

smoothstep

Hermite smoothstep t² (3 − 2t) with t clamped to [0, 1].

export function smoothstep(edge0: number, edge1: number, x: number): number;

Throws: RangeError when edge0 === edge1.

approxEqual

Whether |a − b| <= epsilon. The tolerance is required.

export function approxEqual(a: number, b: number, epsilon: number): boolean;

Throws: RangeError when epsilon is negative.

sin

Sine (FreeBSD msun s_sin.c), identical on every host.

export function sin(x: number): number;

cos

Cosine (FreeBSD msun s_cos.c), identical on every host.

export function cos(x: number): number;

tan

Tangent (FreeBSD msun s_tan.c), identical on every host.

export function tan(x: number): number;

asin

Arcsine in [−π/2, π/2] (msun e_asin.c).

export function asin(x: number): number;

Throws: RangeError outside [−1, 1].

acos

Arccosine in [0, π] (msun e_acos.c).

export function acos(x: number): number;

Throws: RangeError outside [−1, 1].

atan

Arctangent in [−π/2, π/2] (msun s_atan.c).

export function atan(x: number): number;

atan2

Angle of (x, y) in [−π, π] (msun e_atan2.c), with IEEE 754 signed zeros: atan2(0, -0) === PI.

export function atan2(y: number, x: number): number;

exp

e^x (msun e_exp.c); overflows to Infinity above ~709.78.

export function exp(x: number): number;

log

Natural logarithm (msun e_log.c); log(0) === -Infinity.

export function log(x: number): number;

Throws: RangeError when x < 0.

log2

Base-2 logarithm (msun e_log2.c); log2(0) === -Infinity.

export function log2(x: number): number;

Throws: RangeError when x < 0.

pow

x^y (msun e_pow.c, including its IEEE special cases). Overflows to ±Infinity, and pow(±0, y < 0) is ±Infinity.

export function pow(x: number, y: number): number;

Throws: RangeError when x < 0 and y is not an integer (a NaN result).

hypot

sqrt(x² + y²) without intermediate overflow or underflow (msun e_hypot.c); overflows to Infinity only when the result does.

export function hypot(x: number, y: number): number;

vec

Creates the vector { x, y }.

export function vec(x: number, y: number): Vector;

add

Component-wise a + b.

export function add(a: Vector, b: Vector): Vector;

sub

Component-wise a − b.

export function sub(a: Vector, b: Vector): Vector;

scale

v multiplied by the scalar s.

export function scale(v: Vector, s: number): Vector;

negate

{ x: −v.x, y: −v.y }.

export function negate(v: Vector): Vector;

dot

Dot product a.x·b.x + a.y·b.y.

export function dot(a: Vector, b: Vector): number;

cross

2D cross product a.x·b.y − a.y·b.x.

export function cross(a: Vector, b: Vector): number;

length

Euclidean length sqrt(x² + y²).

export function length(v: Vector): number;

lengthSquared

Squared length x² + y².

export function lengthSquared(v: Vector): number;

distance

Euclidean distance between two points.

export function distance(a: Vector, b: Vector): number;

distanceSquared

Squared distance between two points.

export function distanceSquared(a: Vector, b: Vector): number;

normalize

The unit vector in the direction of v.

export function normalize(v: Vector): Vector;

Throws: RangeError on a zero vector.

withLength

v rescaled to length (negative lengths flip it).

export function withLength(v: Vector, length: number): Vector;

Throws: RangeError on a zero vector.

perpendicular

{ x: −v.y, y: v.x }: +90°, clockwise on screen.

export function perpendicular(v: Vector): Vector;

rotate

(x·cos − y·sin, x·sin + y·cos) using the deterministic trigonometry.

export function rotate(v: Vector, angle: number): Vector;

rotateAround

Rotates point around pivot by angle.

export function rotateAround(point: Vector, pivot: Vector, angle: number): Vector;

midpoint

The point halfway between a and b.

export function midpoint(a: Vector, b: Vector): Vector;

lerpVector

Component-wise lerp; t is not clamped.

export function lerpVector(a: Vector, b: Vector, t: number): Vector;

project

The projection of v onto the direction of onto.

export function project(v: Vector, onto: Vector): Vector;

Throws: RangeError when onto is zero.

reflect

v reflected about the line with the given normal, which is normalized internally.

export function reflect(v: Vector, normal: Vector): Vector;

Throws: RangeError when normal is zero.

equals

Exact equality, or each component within opts.epsilon.

export function equals(a: Vector, b: Vector, opts?: Tolerance): boolean;

angleOf

The angle of v in (−π, π].

export function angleOf(v: Vector): number;

Throws: RangeError on a zero vector.

fromAngle

The vector (cos angle, sin angle) · length.

export function fromAngle(angle: number, length?: number): Vector;

normalizeAngle

angle wrapped into (−π, π].

export function normalizeAngle(angle: number): number;

angleDifference

The shortest signed turn from from to to, in (−π, π].

export function angleDifference(from: number, to: number): number;

angleBetween

The signed angle from vector a to vector b, in (−π, π].

export function angleBetween(a: Vector, b: Vector): number;

Throws: RangeError when either vector is zero.

lerpAngle

Interpolates along the shortest turn; the result is normalized.

export function lerpAngle(from: number, to: number, t: number): number;

radians

Degrees to radians.

export function radians(degrees: number): number;

degrees

Radians to degrees.

export function degrees(radians: number): number;

seed

A random state from a safe integer (its low and high 32 bits) or a string (FNV-1a over its UTF-8 bytes), expanded through splitmix32. The same seed gives the same sequence on every host.

export function seed(input: number | string): RandomState;

Throws: RangeError for a number that is not a safe integer.

random

A number in [0, 1) with 53 random bits (two generator outputs).

export function random(state: RandomState): Draw<number>;

randomRange

A number in [min, max).

export function randomRange(state: RandomState, min: number, max: number): Draw<number>;

Throws: RangeError when min >= max or max − min overflows.

randomInt

An unbiased integer in [min, max] (Lemire's method with rejection).

export function randomInt(state: RandomState, min: number, max: number): Draw<number>;

Throws: RangeError unless both are safe integers, min <= max and max − min < 2³².

randomBool

true with the given probability in [0, 1] (default 0.5).

export function randomBool(state: RandomState, probability?: number): Draw<boolean>;

Throws: RangeError outside [0, 1].

pick

One element chosen uniformly.

export function pick<T>(state: RandomState, array: readonly T[]): Draw<T>;

Throws: RangeError on an empty array.

shuffle

A new array shuffled with Fisher–Yates; the input is untouched.

export function shuffle<T>(state: RandomState, array: readonly T[]): Draw<T[]>;

fork

An independent child state seeded through splitmix32 from two parent outputs; next continues the parent.

export function fork(state: RandomState): Draw<RandomState>;