math 0.0.3 → 0.1.0

package/dist/src/ik/index.d.ts

@@ -0,0 +1,2 @@
+export * as fabrik2 from './fabrik2.js';
+export * as fabrik3 from './fabrik3.js';

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export * from './core/index.js';

package/dist/src/noise/fractal.d.ts

@@ -0,0 +1,95 @@
+import type { Vec2 } from '../core/vec2.js';
+import type { Vec3 } from '../core/vec3.js';
+/**
+ * Fractional Brownian motion: sums octaves of a noise source at increasing
+ * frequency and decreasing amplitude - the workhorse for natural-looking
+ * heightmaps and clouds. Given a source in [-1, 1], returns a value in [-1, 1].
+ *
+ * @param sample receives an octave frequency, returns the base noise scaled by it
+ * @param octaves number of octaves to sum
+ * @param lacunarity frequency multiplier between octaves
+ * @param gain amplitude multiplier between octaves
+ * @returns the summed, normalized noise value
+ */
+export declare function fbm(sample: (frequency: number) => number, octaves: number, lacunarity: number, gain: number): number;
+/**
+ * Ridged multifractal: like {@link fbm}, but each octave is folded to
+ * `1 - abs(noise)`, filling the field with sharp ridges - the classic mountain
+ * range / canyon look. Given a source in [-1, 1], returns a value in [0, 1].
+ *
+ * @param sample receives an octave frequency, returns the base noise scaled by it
+ * @param octaves number of octaves to sum
+ * @param lacunarity frequency multiplier between octaves
+ * @param gain amplitude multiplier between octaves
+ * @returns the summed, normalized ridged value
+ */
+export declare function ridged(sample: (frequency: number) => number, octaves: number, lacunarity: number, gain: number): number;
+/**
+ * Billow noise: like {@link fbm}, but each octave is folded to `2*abs(noise) - 1`,
+ * giving puffy, rounded, cloud-like lobes. Given a source in [-1, 1], returns a
+ * value in [-1, 1].
+ *
+ * @param sample receives an octave frequency, returns the base noise scaled by it
+ * @param octaves number of octaves to sum
+ * @param lacunarity frequency multiplier between octaves
+ * @param gain amplitude multiplier between octaves
+ * @returns the summed, normalized billow value
+ */
+export declare function billow(sample: (frequency: number) => number, octaves: number, lacunarity: number, gain: number): number;
+/**
+ * Domain warping (2D): offsets a point by a noise-derived vector, so feeding the
+ * result back into a noise source bends and swirls it - marble, meandering
+ * terrain, organic distortion. The two axes sample the warp noise at
+ * decorrelated offsets so they don't move in lockstep.
+ *
+ * @param out the receiving Vec2 (the warped point)
+ * @param sample the warp noise source, sampled at (x, y)
+ * @param x x coordinate
+ * @param y y coordinate
+ * @param amount displacement scale (default 1)
+ * @returns out
+ */
+export declare function domainWarp2(out: Vec2, sample: (x: number, y: number) => number, x: number, y: number, amount?: number): Vec2;
+/**
+ * Domain warping (3D): offsets a point by a noise-derived vector so a noise
+ * source sampled at the result is bent and swirled. See {@link domainWarp2}.
+ *
+ * @param out the receiving Vec3 (the warped point)
+ * @param sample the warp noise source, sampled at (x, y, z)
+ * @param x x coordinate
+ * @param y y coordinate
+ * @param z z coordinate
+ * @param amount displacement scale (default 1)
+ * @returns out
+ */
+export declare function domainWarp3(out: Vec3, sample: (x: number, y: number, z: number) => number, x: number, y: number, z: number, amount?: number): Vec3;
+/**
+ * Curl of a 2D scalar noise potential - a divergence-free (incompressible) flow
+ * field. Particles advected through it swirl like a fluid and never converge to
+ * sinks or fly apart, which is why it's the cheap go-to for procedural smoke /
+ * flow. Given a scalar potential psi(x, y), the flow is (d psi/dy, -d psi/dx),
+ * with the derivatives taken by central differences of step `eps`.
+ *
+ * @param out the receiving Vec2 (the flow velocity)
+ * @param sample the scalar potential noise, sampled at (x, y)
+ * @param x x coordinate
+ * @param y y coordinate
+ * @param eps finite-difference step (default 1e-4)
+ * @returns out
+ */
+export declare function curl2(out: Vec2, sample: (x: number, y: number) => number, x: number, y: number, eps?: number): Vec2;
+/**
+ * Curl of a 3D noise vector potential - a divergence-free 3D flow field for
+ * volumetric smoke / fluid motion. The three potential components reuse a single
+ * `sample` at large, decorrelating offsets, and the flow is their curl,
+ * `∇ × psi`, with derivatives taken by central differences of step `eps`.
+ *
+ * @param out the receiving Vec3 (the flow velocity)
+ * @param sample the scalar potential noise, sampled at (x, y, z)
+ * @param x x coordinate
+ * @param y y coordinate
+ * @param z z coordinate
+ * @param eps finite-difference step (default 1e-4)
+ * @returns out
+ */
+export declare function curl3(out: Vec3, sample: (x: number, y: number, z: number) => number, x: number, y: number, z: number, eps?: number): Vec3;

package/dist/src/noise/index.d.ts

@@ -0,0 +1,9 @@
+export * from './fractal.js';
+export * as perlin2d from './perlin2d.js';
+export * as perlin3d from './perlin3d.js';
+export type { Permutation } from './permutation.js';
+export * as simplex2d from './simplex2d.js';
+export * as simplex3d from './simplex3d.js';
+export * as simplex4d from './simplex4d.js';
+export * as worley2d from './worley2d.js';
+export * as worley3d from './worley3d.js';

package/dist/src/noise/perlin2d.d.ts

@@ -0,0 +1,19 @@
+import { type Permutation } from './permutation.js';
+/** A seeded 2D Perlin noise generator. Create one with {@link create}. */
+export type Perlin2DGenerator = Permutation;
+/**
+ * Creates a 2D Perlin noise generator with the given seed.
+ *
+ * @param seed The seed value for the noise generator
+ * @returns A generator to pass to {@link sample}
+ */
+export declare function create(seed: number): Perlin2DGenerator;
+/**
+ * Samples 2D Perlin noise.
+ *
+ * @param generator A generator created with {@link create}
+ * @param x X coordinate
+ * @param y Y coordinate
+ * @returns The noise value at (x, y)
+ */
+export declare function sample({ perm, grad3 }: Perlin2DGenerator, x: number, y: number): number;

package/dist/src/noise/perlin3d.d.ts

@@ -0,0 +1,20 @@
+import { type Permutation } from './permutation.js';
+/** A seeded 3D Perlin noise generator. Create one with {@link create}. */
+export type Perlin3DGenerator = Permutation;
+/**
+ * Creates a 3D Perlin noise generator with the given seed.
+ *
+ * @param seed The seed value for the noise generator
+ * @returns A generator to pass to {@link sample}
+ */
+export declare function create(seed: number): Perlin3DGenerator;
+/**
+ * Samples 3D Perlin noise.
+ *
+ * @param generator A generator created with {@link create}
+ * @param x X coordinate
+ * @param y Y coordinate
+ * @param z Z coordinate
+ * @returns The noise value at (x, y, z)
+ */
+export declare function sample({ perm, grad3 }: Perlin3DGenerator, x: number, y: number, z: number): number;

package/dist/src/noise/permutation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Seeded permutation and gradient tables that back a noise generator.
+ *
+ * All noise variants (simplex/perlin, 2D/3D/4D) share this same table shape, so
+ * each generator type is a structural alias of this. `perm` is the doubled
+ * (512 entry) permutation table. `grad3` holds the 3D gradient for each
+ * permutation index as flat xyz triples (used by 2D and 3D noise), and `grad4`
+ * holds the 4D gradient for each index as flat xyzw quads. Flat typed arrays
+ * keep sampling free of nested array loads and allocation.
+ */
+export type Permutation = {
+    perm: Uint8Array;
+    grad3: Float64Array;
+    grad4: Float64Array;
+};
+/**
+ * Creates the seeded permutation and gradient tables for a noise generator.
+ *
+ * @param seed The seed value for the noise generator
+ * @returns The permutation tables derived from the seed
+ */
+export declare function createPermutation(seed: number): Permutation;

package/dist/src/noise/simplex2d.d.ts

@@ -0,0 +1,19 @@
+import { type Permutation } from './permutation.js';
+/** A seeded 2D simplex noise generator. Create one with {@link create}. */
+export type Simplex2DGenerator = Permutation;
+/**
+ * Creates a 2D simplex noise generator with the given seed.
+ *
+ * @param seed The seed value for the noise generator
+ * @returns A generator to pass to {@link sample}
+ */
+export declare function create(seed: number): Simplex2DGenerator;
+/**
+ * Samples 2D simplex noise, returning a value in the interval [-1, 1].
+ *
+ * @param generator A generator created with {@link create}
+ * @param x X coordinate
+ * @param y Y coordinate
+ * @returns The noise value at (x, y)
+ */
+export declare function sample({ perm, grad3 }: Simplex2DGenerator, x: number, y: number): number;

package/dist/src/noise/simplex3d.d.ts

@@ -0,0 +1,20 @@
+import { type Permutation } from './permutation.js';
+/** A seeded 3D simplex noise generator. Create one with {@link create}. */
+export type Simplex3DGenerator = Permutation;
+/**
+ * Creates a 3D simplex noise generator with the given seed.
+ *
+ * @param seed The seed value for the noise generator
+ * @returns A generator to pass to {@link sample}
+ */
+export declare function create(seed: number): Simplex3DGenerator;
+/**
+ * Samples 3D simplex noise, returning a value in the interval [-1, 1].
+ *
+ * @param generator A generator created with {@link create}
+ * @param x X coordinate
+ * @param y Y coordinate
+ * @param z Z coordinate
+ * @returns The noise value at (x, y, z)
+ */
+export declare function sample({ perm, grad3 }: Simplex3DGenerator, x: number, y: number, z: number): number;

package/dist/src/noise/simplex4d.d.ts

@@ -0,0 +1,24 @@
+import { type Permutation } from './permutation.js';
+/** A seeded 4D simplex noise generator. Create one with {@link create}. */
+export type Simplex4DGenerator = Permutation;
+/**
+ * Creates a 4D simplex noise generator with the given seed.
+ *
+ * @param seed The seed value for the noise generator
+ * @returns A generator to pass to {@link sample}
+ */
+export declare function create(seed: number): Simplex4DGenerator;
+/**
+ * Samples 4D simplex noise, returning a value in the interval [-1, 1].
+ *
+ * The fourth axis is commonly used as time (for animated 3D noise) or as a wrap
+ * dimension (map a coordinate around a circle in w for seamless looping).
+ *
+ * @param generator A generator created with {@link create}
+ * @param x X coordinate
+ * @param y Y coordinate
+ * @param z Z coordinate
+ * @param w W coordinate
+ * @returns The noise value at (x, y, z, w)
+ */
+export declare function sample({ perm, grad4 }: Simplex4DGenerator, x: number, y: number, z: number, w: number): number;

package/dist/src/noise/worley2d.d.ts

@@ -0,0 +1,22 @@
+import { type Permutation } from './permutation.js';
+/** A seeded 2D Worley (cellular) noise generator. Create one with {@link create}. */
+export type Worley2DGenerator = Permutation;
+/**
+ * Creates a 2D Worley noise generator with the given seed.
+ *
+ * @param seed The seed value for the noise generator
+ * @returns A generator to pass to {@link sample}
+ */
+export declare function create(seed: number): Worley2DGenerator;
+/**
+ * Samples 2D Worley (cellular) noise: the Euclidean distance to the nearest of a
+ * set of feature points, one scattered per unit cell. Gives organic cell / scale
+ * / caustic patterns; values are roughly in [0, 1] (0 right at a feature point,
+ * rising between them). Threshold it for cracks, cells, or region masks.
+ *
+ * @param generator A generator created with {@link create}
+ * @param x X coordinate
+ * @param y Y coordinate
+ * @returns The distance to the nearest feature point (F1)
+ */
+export declare function sample({ perm }: Worley2DGenerator, x: number, y: number): number;

package/dist/src/noise/worley3d.d.ts

@@ -0,0 +1,23 @@
+import { type Permutation } from './permutation.js';
+/** A seeded 3D Worley (cellular) noise generator. Create one with {@link create}. */
+export type Worley3DGenerator = Permutation;
+/**
+ * Creates a 3D Worley noise generator with the given seed.
+ *
+ * @param seed The seed value for the noise generator
+ * @returns A generator to pass to {@link sample}
+ */
+export declare function create(seed: number): Worley3DGenerator;
+/**
+ * Samples 3D Worley (cellular) noise: the Euclidean distance to the nearest of a
+ * set of feature points, one scattered per unit cell. Values are roughly in
+ * [0, 1] (0 right at a feature point). Threshold a 3D field for cave networks,
+ * ore pockets, or volumetric cell structures.
+ *
+ * @param generator A generator created with {@link create}
+ * @param x X coordinate
+ * @param y Y coordinate
+ * @param z Z coordinate
+ * @returns The distance to the nearest feature point (F1)
+ */
+export declare function sample({ perm }: Worley3DGenerator, x: number, y: number, z: number): number;

package/dist/src/random/index.d.ts

@@ -0,0 +1,8 @@
+export * as isaac32 from './isaac32.js';
+export type { Isaac32 } from './isaac32.js';
+export * as isaac64 from './isaac64.js';
+export type { Isaac64 } from './isaac64.js';
+export * as mulberry32 from './mulberry32.js';
+export type { Mulberry32 } from './mulberry32.js';
+export type { RandomGenerator } from './random.js';
+export * as random from './random.js';

package/dist/src/random/isaac32.d.ts

@@ -0,0 +1,62 @@
+/**
+ * State of an ISAAC-32 PRNG: two 256-word arrays plus three accumulators and a
+ * cursor into the current batch of results. Create one with {@link create}.
+ *
+ * ISAAC (Indirection, Shift, Accumulate, Add, Count) generates 256 words per
+ * round and hands them out one at a time; {@link next}/{@link sample} refill the
+ * batch automatically when it runs dry.
+ *
+ * The state is a plain object, so it can be inspected,
+ * cloned (to fork a sequence), or serialised. `m`/`r` are typed arrays, so a
+ * structural clone (e.g. `structuredClone`) forks correctly; a shallow `{...}`
+ * copy shares them and does not.
+ */
+export type Isaac32 = {
+    /** internal state ("mem"), 256 words */
+    m: Uint32Array;
+    /** current batch of results, 256 words */
+    r: Uint32Array;
+    /** accumulator */
+    a: number;
+    /** previous result */
+    b: number;
+    /** counter, incremented once per batch */
+    c: number;
+    /** cursor into `r`; a value of 256 means the batch is spent */
+    i: number;
+};
+/**
+ * Creates ISAAC-32 PRNG state seeded with `seed`.
+ *
+ * ISAAC is a fast, high-quality generator: its cycle length is at least 2^40 and
+ * ~2^8295 on average, and its output passes stringent statistical tests. Bob
+ * Jenkins designed it to resist prediction, but it is not founded on
+ * cryptographic theory, so **do not rely on it for cryptography** — use the Web
+ * Crypto API for that.
+ *
+ * A `seed` of 0 reproduces the reference implementation's unseeded output. For
+ * the full-strength 64-bit variant see {@link Isaac64}.
+ *
+ * @param seed the seed value (32-bit integer), defaults to 0
+ * @returns state to pass to {@link sample} or {@link next}
+ */
+export declare function create(seed?: number): Isaac32;
+/**
+ * Advances `state` and returns the next raw 32-bit unsigned integer.
+ *
+ * @param state PRNG state created with {@link create}, mutated in place
+ * @returns an integer in the range [0, 2^32)
+ */
+export declare function next(state: Isaac32): number;
+/**
+ * Advances `state` and returns the next number in the range [0, 1).
+ *
+ * @param state PRNG state created with {@link create}, mutated in place
+ * @returns a number in the range [0, 1)
+ */
+export declare function sample(state: Isaac32): number;
+/**
+ * Generates a random 32-bit unsigned integer seed, suitable for use with
+ * {@link create}.
+ */
+export declare function seed(): number;

package/dist/src/random/isaac64.d.ts

@@ -0,0 +1,75 @@
+/**
+ * State of an ISAAC64 PRNG. Create one with {@link create}.
+ *
+ * ISAAC64 is the 64-bit variant of ISAAC (Indirection, Shift, Accumulate, Add,
+ * Count): same design as {@link Isaac32} but on 64-bit words, giving a larger
+ * state and 64-bit output. JavaScript has no native 64-bit integers, so each
+ * 64-bit word is split into two 32-bit lanes — `*Hi` (bits 63..32) and `*Lo`
+ * (bits 31..0) — and the hot loop does 64-bit math with explicit carries in
+ * plain `number`s. That keeps the whole generator in fast Word32 arithmetic
+ * (see the note on {@link Isaac32}'s typed arrays); a `bigint` implementation is
+ * ~6x slower. `next` reassembles a `bigint`; `sample` skips `bigint` entirely.
+ *
+ * The state is a plain object, so it can be inspected, cloned (to fork a
+ * sequence), or serialised. The lanes are typed arrays, so a structural clone
+ * (e.g. `structuredClone`) forks correctly; a shallow `{...}` copy shares them.
+ */
+export type Isaac64 = {
+    /** internal state ("mem") high/low lanes, 256 words */
+    mHi: Uint32Array;
+    mLo: Uint32Array;
+    /** current batch of results, high/low lanes, 256 words */
+    rHi: Uint32Array;
+    rLo: Uint32Array;
+    /** accumulator */
+    aHi: number;
+    aLo: number;
+    /** previous result */
+    bHi: number;
+    bLo: number;
+    /** counter, incremented once per batch */
+    cHi: number;
+    cLo: number;
+    /** cursor into `r`; a value of 256 means the batch is spent */
+    i: number;
+};
+/**
+ * Creates ISAAC64 PRNG state seeded with `seed`.
+ *
+ * ISAAC64 is a fast, high-quality generator with an enormous cycle length
+ * (~2^8295 on average). Bob Jenkins designed it to resist prediction, but it is
+ * not founded on cryptographic theory, so **do not rely on it for
+ * cryptography** — use the Web Crypto API for that.
+ *
+ * A `seed` of 0 reproduces the reference implementation's unseeded output.
+ *
+ * @param seed the seed value (64-bit integer), defaults to 0n
+ * @returns state to pass to {@link sample} or {@link next}
+ */
+export declare function create(seed?: bigint): Isaac64;
+/**
+ * Advances `state` and returns the next raw 64-bit unsigned integer.
+ *
+ * This reassembles a `bigint` from the two lanes, so it allocates; for a value
+ * in [0, 1) prefer {@link sample}, which stays in `number` arithmetic.
+ *
+ * @param state PRNG state created with {@link create}, mutated in place
+ * @returns an integer in the range [0, 2^64)
+ */
+export declare function next(state: Isaac64): bigint;
+/**
+ * Advances `state` and returns the next number in the range [0, 1).
+ *
+ * The result carries 53 bits of randomness (the width of a double's mantissa),
+ * taken from the high bits of a 64-bit word — read straight from the lanes, so
+ * no `bigint` is allocated.
+ *
+ * @param state PRNG state created with {@link create}, mutated in place
+ * @returns a number in the range [0, 1)
+ */
+export declare function sample(state: Isaac64): number;
+/**
+ * Generates a random 64-bit unsigned integer seed, suitable for use with
+ * {@link create}.
+ */
+export declare function seed(): bigint;

package/dist/src/random/mulberry32.d.ts

@@ -0,0 +1,43 @@
+/**
+ * State of a Mulberry32 PRNG: a single 32-bit accumulator that {@link sample}
+ * advances on each call. Create one with {@link create}.
+ *
+ * Unlike a closure-based generator, the state is a plain object — so it can be
+ * inspected, cloned (to fork a sequence), or serialised.
+ */
+export type Mulberry32 = {
+    a: number;
+};
+/**
+ * Creates Mulberry32 PRNG state seeded with `seed`.
+ *
+ * Mulberry32 is a simple, fast, and effective PRNG that passes statistical tests
+ * and has good distribution properties.
+ *
+ * @param seed the seed value (32-bit integer)
+ * @returns state to pass to {@link sample}
+ */
+export declare function create(seed: number): Mulberry32;
+/**
+ * Advances `state` and returns the next raw 32-bit unsigned integer.
+ *
+ * The accumulator is kept to 32 bits with `| 0`; without it, `state.a` would grow
+ * as an unbounded float and lose integer precision past 2^53 (~5M draws),
+ * corrupting the sequence.
+ *
+ * @param state PRNG state created with {@link create}, mutated in place
+ * @returns an integer in the range [0, 2^32)
+ */
+export declare function next(state: Mulberry32): number;
+/**
+ * Advances `state` and returns the next number in the range [0, 1).
+ *
+ * @param state PRNG state created with {@link create}, mutated in place
+ * @returns a number in the range [0, 1)
+ */
+export declare function sample(state: Mulberry32): number;
+/**
+ * Generates a random 32-bit unsigned integer seed, suitable for use with
+ * {@link create}.
+ */
+export declare function seed(): number;

package/dist/src/random/random.d.ts

@@ -0,0 +1,67 @@
+import type { Quat } from '../core/quat.js';
+import type { Vec2 } from '../core/vec2.js';
+import type { Vec3 } from '../core/vec3.js';
+import type { Vec4 } from '../core/vec4.js';
+/** A function that returns a random number in the range [0, 1). */
+export type RandomGenerator = () => number;
+/**
+ * Returns a random float in the range [min, max).
+ * @param random the random generator to use
+ * @param min the minimum value (inclusive)
+ * @param max the maximum value (exclusive)
+ */
+export declare function float(random: RandomGenerator, min: number, max: number): number;
+/**
+ * Returns a random integer in the range [min, max] (inclusive).
+ * @param random the random generator to use
+ * @param min the minimum value (inclusive)
+ * @param max the maximum value (inclusive)
+ */
+export declare function int(random: RandomGenerator, min: number, max: number): number;
+/**
+ * Returns a random boolean.
+ * @param random the random generator to use
+ * @param chance the probability of returning true, in the range [0, 1]. Defaults to 0.5.
+ */
+export declare function bool(random: RandomGenerator, chance?: number): boolean;
+/**
+ * Returns a random sign, either 1 or -1.
+ * @param random the random generator to use
+ * @param plusChance the probability of returning 1, in the range [0, 1]. Defaults to 0.5.
+ */
+export declare function sign(random: RandomGenerator, plusChance?: number): number;
+/**
+ * Returns a random item from an array.
+ * @param random the random generator to use
+ * @param items the array to choose from
+ * @throws if the array is empty
+ */
+export declare function choice<T>(random: RandomGenerator, items: T[]): T;
+/**
+ * Writes a random unit-length Vec2 into out.
+ * @param out the receiving vector
+ * @param random the random generator to use
+ * @returns out
+ */
+export declare function vec2(out: Vec2, random: RandomGenerator): Vec2;
+/**
+ * Writes a random unit-length Vec3 into out.
+ * @param out the receiving vector
+ * @param random the random generator to use
+ * @returns out
+ */
+export declare function vec3(out: Vec3, random: RandomGenerator): Vec3;
+/**
+ * Writes a random unit-length Vec4 into out.
+ * @param out the receiving vector
+ * @param random the random generator to use
+ * @returns out
+ */
+export declare function vec4(out: Vec4, random: RandomGenerator): Vec4;
+/**
+ * Writes a random unit quaternion into out.
+ * @param out the receiving quaternion
+ * @param random the random generator to use
+ * @returns out
+ */
+export declare function quat(out: Quat, random: RandomGenerator): Quat;