@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/core/loop.d.ts

@@ -0,0 +1,113 @@
+import type { FrameSource } from '../host/types.js';
+export interface FixedStepperOptions {
+    /** Simulation step in seconds. Default 1/60. */
+    step?: number;
+    /** Real frame delta is clamped to this before accumulating (tab switches, breakpoints). */
+    maxFrameDt?: number;
+    /** Hard cap on steps per frame (spiral-of-death guard). Extra time is dropped. */
+    maxSteps?: number;
+}
+export declare class FixedStepper {
+    readonly step: number;
+    readonly maxFrameDt: number;
+    readonly maxSteps: number;
+    accumulator: number;
+    constructor(opts?: FixedStepperOptions);
+    /** Feed a real frame delta (seconds). Returns how many fixed steps to run now. */
+    advance(frameDt: number): number;
+    /** Interpolation factor in [0,1) between the last and next simulation state. */
+    get alpha(): number;
+    reset(): void;
+}
+/** Read-only time info shared with systems. Mutated in place by the loop. */
+export interface Time {
+    /** Fixed step (seconds). */
+    readonly step: number;
+    /** Total simulated time (seconds); advances only while running and not paused. */
+    simTime: number;
+    /** Total real time since start (seconds), excluding hidden/paused gaps. */
+    realTime: number;
+    /** Last real frame delta (clamped, seconds). */
+    frameDt: number;
+    /** Rendered frame counter. */
+    frame: number;
+    /** Simulation step counter. */
+    tick: number;
+}
+export interface LoopCallbacks {
+    /**
+     * Fixed-step update: `dt` is always `time.step`. With `fixed: false`, once per rendered frame
+     * before render, `dt` the real frame delta (`time.frameDt`).
+     */
+    update(dt: number, time: Time): void;
+    /**
+     * Variable-rate render. `alpha` is the interpolation factor between sim states (always 1 with
+     * `fixed: false`, 0 while paused).
+     */
+    render(alpha: number, time: Time): void;
+}
+export interface GameLoopOptions extends FixedStepperOptions {
+    /**
+     * Default true: update runs in fixed steps of `step`. False: once per rendered frame with the
+     * real frame delta (render-rate only, no accumulator); `time.tick` then counts those updates.
+     */
+    fixed?: boolean;
+    /** Clock for frame deltas (ms). Default `performance.now`. */
+    now?: () => number;
+    /**
+     * Where frames come from: the game's `Host` (`createGame` passes its own), or a stub a test
+     * steps by hand. Default: `defaultHost()`, read when the loop first starts.
+     */
+    frames?: FrameSource;
+}
+export declare class GameLoop {
+    readonly time: Time;
+    private readonly stepper;
+    private readonly cb;
+    private readonly fixed;
+    private readonly now;
+    private source;
+    private frameId;
+    private last;
+    private running;
+    private _paused;
+    private _halted;
+    private minFrameMs;
+    /** True while `frame` runs its callbacks (so `setFrames` leaves rescheduling to it). */
+    private inFrame;
+    constructor(cb: LoopCallbacks, opts?: GameLoopOptions);
+    get isRunning(): boolean;
+    /** While paused, update is skipped but render keeps running (so menus/overlays still draw). */
+    get paused(): boolean;
+    set paused(v: boolean);
+    /**
+     * Cap the render rate (null = every display frame). With 30 on a 60 Hz display the loop runs
+     * on every other vsync: a steady 30 fps instead of a GPU-bound jitter between 30 and 60.
+     * Frames are skipped whole (no update, no render), so the fixed step still keeps time.
+     */
+    get maxFps(): number | null;
+    set maxFps(fps: number | null);
+    /** True after `halt()`: the loop is stopped for good. */
+    get halted(): boolean;
+    start(): void;
+    /** Stop scheduling frames entirely (e.g. tab hidden, device lost). */
+    stop(): void;
+    /**
+     * Swap the frame source while the loop runs (or before): a pending frame on the old source
+     * is cancelled and the next is requested from `src`. Called from inside a frame callback
+     * (an action handler), the current frame finishes and reschedules through `src`. Entering and
+     * leaving an XR session swaps between the XR host and the page's host this way (ws/xr).
+     */
+    setFrames(src: FrameSource): void;
+    /** The frame source, resolved on first use so a loop that is only ticked by hand needs none. */
+    private get frames();
+    /**
+     * Stop for good (e.g. the GPU device is lost): later `start()` calls, such as a
+     * tab-visible handler, are ignored, and `tickOnce` does nothing.
+     */
+    halt(): void;
+    /** Run one frame manually with an explicit delta (tests, frame stepping). */
+    tickOnce(frameDt: number): void;
+    private readonly frame;
+    private runFrame;
+}

package/dist/core/loop.js

@@ -0,0 +1,185 @@
+/**
+ * Fixed-step simulation + variable-rate render.
+ *
+ * `FixedStepper` is the pure accumulator (unit-tested); `GameLoop` drives it from the host's
+ * frames (`Host.requestFrame`: the browser's requestAnimationFrame, a test's manual stepping).
+ * With `fixed: false` the loop has no fixed step: update runs once per rendered frame with the
+ * real (clamped) delta, for a client that applies another's state.
+ */
+import { defaultHost } from '../host/default.js';
+export class FixedStepper {
+    step;
+    maxFrameDt;
+    maxSteps;
+    accumulator = 0;
+    constructor(opts = {}) {
+        this.step = opts.step ?? 1 / 60;
+        this.maxFrameDt = opts.maxFrameDt ?? 0.25;
+        this.maxSteps = opts.maxSteps ?? 8;
+    }
+    /** Feed a real frame delta (seconds). Returns how many fixed steps to run now. */
+    advance(frameDt) {
+        const dt = Math.min(Math.max(frameDt, 0), this.maxFrameDt);
+        this.accumulator += dt;
+        let steps = Math.floor(this.accumulator / this.step + 1e-9);
+        if (steps > this.maxSteps) {
+            steps = this.maxSteps;
+            this.accumulator = 0;
+            return steps;
+        }
+        this.accumulator -= steps * this.step;
+        if (this.accumulator < 0)
+            this.accumulator = 0;
+        return steps;
+    }
+    /** Interpolation factor in [0,1) between the last and next simulation state. */
+    get alpha() {
+        return this.accumulator / this.step;
+    }
+    reset() {
+        this.accumulator = 0;
+    }
+}
+/** Early-frame tolerance for `GameLoop.maxFps`, ms. */
+const FRAME_CAP_SLACK_MS = 3;
+export class GameLoop {
+    time;
+    stepper;
+    cb;
+    fixed;
+    now;
+    source;
+    frameId = 0;
+    last = 0;
+    running = false;
+    _paused = false;
+    _halted = false;
+    minFrameMs = 0;
+    /** True while `frame` runs its callbacks (so `setFrames` leaves rescheduling to it). */
+    inFrame = false;
+    constructor(cb, opts = {}) {
+        this.cb = cb;
+        this.stepper = new FixedStepper(opts);
+        this.fixed = opts.fixed !== false;
+        this.now = opts.now ?? (() => performance.now());
+        this.source = opts.frames ?? null;
+        this.time = { step: this.stepper.step, simTime: 0, realTime: 0, frameDt: 0, frame: 0, tick: 0 };
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /** While paused, update is skipped but render keeps running (so menus/overlays still draw). */
+    get paused() {
+        return this._paused;
+    }
+    set paused(v) {
+        this._paused = v;
+        if (v)
+            this.stepper.reset();
+    }
+    /**
+     * Cap the render rate (null = every display frame). With 30 on a 60 Hz display the loop runs
+     * on every other vsync: a steady 30 fps instead of a GPU-bound jitter between 30 and 60.
+     * Frames are skipped whole (no update, no render), so the fixed step still keeps time.
+     */
+    get maxFps() {
+        return this.minFrameMs > 0 ? 1000 / this.minFrameMs : null;
+    }
+    set maxFps(fps) {
+        this.minFrameMs = fps && fps > 0 ? 1000 / fps : 0;
+    }
+    /** True after `halt()`: the loop is stopped for good. */
+    get halted() {
+        return this._halted;
+    }
+    start() {
+        if (this.running || this._halted)
+            return;
+        this.running = true;
+        this.last = this.now();
+        this.stepper.reset();
+        this.frameId = this.frames.requestFrame(this.frame);
+    }
+    /** Stop scheduling frames entirely (e.g. tab hidden, device lost). */
+    stop() {
+        this.running = false;
+        this.source?.cancelFrame(this.frameId);
+    }
+    /**
+     * Swap the frame source while the loop runs (or before): a pending frame on the old source
+     * is cancelled and the next is requested from `src`. Called from inside a frame callback
+     * (an action handler), the current frame finishes and reschedules through `src`. Entering and
+     * leaving an XR session swaps between the XR host and the page's host this way (ws/xr).
+     */
+    setFrames(src) {
+        if (src === this.source)
+            return;
+        const prev = this.source;
+        this.source = src;
+        if (!this.running || this.inFrame)
+            return;
+        prev?.cancelFrame(this.frameId);
+        this.frameId = src.requestFrame(this.frame);
+    }
+    /** The frame source, resolved on first use so a loop that is only ticked by hand needs none. */
+    get frames() {
+        this.source ??= defaultHost();
+        return this.source;
+    }
+    /**
+     * Stop for good (e.g. the GPU device is lost): later `start()` calls, such as a
+     * tab-visible handler, are ignored, and `tickOnce` does nothing.
+     */
+    halt() {
+        this._halted = true;
+        this.stop();
+    }
+    /** Run one frame manually with an explicit delta (tests, frame stepping). */
+    tickOnce(frameDt) {
+        if (this._halted)
+            return;
+        this.runFrame(frameDt);
+    }
+    frame = () => {
+        if (!this.running)
+            return;
+        const t = this.now();
+        // A few ms of slack: vsync timestamps jitter, and a 33.3 ms target must not miss 33.2.
+        if (this.minFrameMs > 0 && t - this.last < this.minFrameMs - FRAME_CAP_SLACK_MS) {
+            this.frameId = this.frames.requestFrame(this.frame);
+            return;
+        }
+        const dt = (t - this.last) / 1000;
+        this.last = t;
+        this.inFrame = true;
+        try {
+            this.runFrame(dt);
+        }
+        finally {
+            this.inFrame = false;
+        }
+        if (this.running)
+            this.frameId = this.frames.requestFrame(this.frame);
+    };
+    runFrame(rawDt) {
+        const time = this.time;
+        const dt = Math.min(Math.max(rawDt, 0), this.stepper.maxFrameDt);
+        time.frameDt = dt;
+        time.realTime += dt;
+        if (!this._paused && !this.fixed) {
+            time.simTime += dt;
+            time.tick++;
+            this.cb.update(dt, time);
+        }
+        else if (!this._paused) {
+            const steps = this.stepper.advance(dt);
+            for (let i = 0; i < steps; i++) {
+                time.simTime += this.stepper.step;
+                time.tick++;
+                this.cb.update(this.stepper.step, time);
+            }
+        }
+        time.frame++;
+        this.cb.render(this._paused ? 0 : this.fixed ? this.stepper.alpha : 1, time);
+    }
+}

package/dist/core/math.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A small 4×4 matrix module. Matrices are column-major `Float32Array(16)` (the layout WGSL's
+ * `mat4x4f` expects): element (row r, column c) is `m[c * 4 + r]`, and the translation sits in
+ * `m[12..14]`.
+ *
+ * Every function writes into `out` and returns it, so a caller that keeps its matrices
+ * allocates nothing per frame. `out` may alias an input.
+ *
+ * Conventions: right-handed view space looking down -z; clip depth is WebGPU's 0..1.
+ */
+export type Mat4 = Float32Array;
+/** A new identity matrix (allocates; keep it). */
+declare function create(): Mat4;
+declare function identity(out: Mat4): Mat4;
+declare function copy(out: Mat4, a: ArrayLike<number>): Mat4;
+/** `out = a × b` (apply `b` first, then `a`). */
+declare function multiply(out: Mat4, a: ArrayLike<number>, b: ArrayLike<number>): Mat4;
+/**
+ * Orthographic projection: x in `left..right` and y in `bottom..top` map to clip -1..1; view
+ * depth `-near..-far` maps to 0..1. Pass `bottom > top` for a y-down space.
+ */
+declare function ortho(out: Mat4, left: number, right: number, bottom: number, top: number, near: number, far: number): Mat4;
+/**
+ * Perspective projection, vertical field of view `fovY` (radians). View depth `-near` maps to
+ * 0 and `-far` to 1; `far = Infinity` gives an infinite far plane.
+ */
+declare function perspective(out: Mat4, fovY: number, aspect: number, near: number, far: number): Mat4;
+/** View matrix for an eye at `eye` looking at `target`, with `up` roughly up. */
+declare function lookAt(out: Mat4, eye: ArrayLike<number>, target: ArrayLike<number>, up: ArrayLike<number>): Mat4;
+/**
+ * 2D view over a `width × height` space (y down): the world point `(width/2 + x, height/2 + y)`
+ * lands on the space's centre, scaled by `zoom` about it. `rotation` (radians) turns the view
+ * clockwise on screen, so the world appears to turn counter-clockwise. With `x = y = rotation = 0` and `zoom = 1` it is the identity.
+ */
+declare function view2d(out: Mat4, x: number, y: number, zoom: number, rotation: number, width: number, height: number): Mat4;
+/** `out = a⁻¹`. Returns null (and leaves `out` untouched) when `a` is singular. */
+declare function invert(out: Mat4, a: ArrayLike<number>): Mat4 | null;
+/**
+ * Transform the point `(x, y, z, 1)` by `m` and divide by w: `out[0..2]` get the result.
+ * Returns w (before the divide), which is ≤ 0 for a point behind a perspective camera.
+ */
+declare function transformPoint(out: {
+    [i: number]: number;
+}, m: ArrayLike<number>, x: number, y: number, z?: number): number;
+/** Column-major 4×4 matrix helpers. See the module comment for conventions. */
+export declare const mat4: {
+    readonly create: typeof create;
+    readonly identity: typeof identity;
+    readonly copy: typeof copy;
+    readonly multiply: typeof multiply;
+    readonly ortho: typeof ortho;
+    readonly perspective: typeof perspective;
+    readonly lookAt: typeof lookAt;
+    readonly view2d: typeof view2d;
+    readonly invert: typeof invert;
+    readonly transformPoint: typeof transformPoint;
+};
+export {};

package/dist/core/math.js

@@ -0,0 +1,210 @@
+/**
+ * A small 4×4 matrix module. Matrices are column-major `Float32Array(16)` (the layout WGSL's
+ * `mat4x4f` expects): element (row r, column c) is `m[c * 4 + r]`, and the translation sits in
+ * `m[12..14]`.
+ *
+ * Every function writes into `out` and returns it, so a caller that keeps its matrices
+ * allocates nothing per frame. `out` may alias an input.
+ *
+ * Conventions: right-handed view space looking down -z; clip depth is WebGPU's 0..1.
+ */
+/** A new identity matrix (allocates; keep it). */
+function create() {
+    return identity(new Float32Array(16));
+}
+function identity(out) {
+    out.fill(0);
+    out[0] = 1;
+    out[5] = 1;
+    out[10] = 1;
+    out[15] = 1;
+    return out;
+}
+function copy(out, a) {
+    for (let i = 0; i < 16; i++)
+        out[i] = a[i];
+    return out;
+}
+/** `out = a × b` (apply `b` first, then `a`). */
+function multiply(out, a, b) {
+    const a00 = a[0], a01 = a[1], a02 = a[2], a03 = a[3];
+    const a10 = a[4], a11 = a[5], a12 = a[6], a13 = a[7];
+    const a20 = a[8], a21 = a[9], a22 = a[10], a23 = a[11];
+    const a30 = a[12], a31 = a[13], a32 = a[14], a33 = a[15];
+    for (let c = 0; c < 4; c++) {
+        const b0 = b[c * 4], b1 = b[c * 4 + 1], b2 = b[c * 4 + 2], b3 = b[c * 4 + 3];
+        out[c * 4] = a00 * b0 + a10 * b1 + a20 * b2 + a30 * b3;
+        out[c * 4 + 1] = a01 * b0 + a11 * b1 + a21 * b2 + a31 * b3;
+        out[c * 4 + 2] = a02 * b0 + a12 * b1 + a22 * b2 + a32 * b3;
+        out[c * 4 + 3] = a03 * b0 + a13 * b1 + a23 * b2 + a33 * b3;
+    }
+    return out;
+}
+/**
+ * Orthographic projection: x in `left..right` and y in `bottom..top` map to clip -1..1; view
+ * depth `-near..-far` maps to 0..1. Pass `bottom > top` for a y-down space.
+ */
+function ortho(out, left, right, bottom, top, near, far) {
+    out.fill(0);
+    out[0] = 2 / (right - left);
+    out[5] = 2 / (top - bottom);
+    out[10] = -1 / (far - near);
+    out[12] = -(right + left) / (right - left);
+    out[13] = -(top + bottom) / (top - bottom);
+    out[14] = -near / (far - near);
+    out[15] = 1;
+    return out;
+}
+/**
+ * Perspective projection, vertical field of view `fovY` (radians). View depth `-near` maps to
+ * 0 and `-far` to 1; `far = Infinity` gives an infinite far plane.
+ */
+function perspective(out, fovY, aspect, near, far) {
+    const f = 1 / Math.tan(fovY / 2);
+    out.fill(0);
+    out[0] = f / aspect;
+    out[5] = f;
+    out[11] = -1;
+    if (Number.isFinite(far)) {
+        out[10] = far / (near - far);
+        out[14] = (near * far) / (near - far);
+    }
+    else {
+        out[10] = -1;
+        out[14] = -near;
+    }
+    return out;
+}
+/** View matrix for an eye at `eye` looking at `target`, with `up` roughly up. */
+function lookAt(out, eye, target, up) {
+    const ex = eye[0], ey = eye[1], ez = eye[2];
+    // z axis: from target to eye.
+    let zx = ex - target[0], zy = ey - target[1], zz = ez - target[2];
+    let len = Math.hypot(zx, zy, zz);
+    if (len === 0)
+        return identity(out);
+    zx /= len;
+    zy /= len;
+    zz /= len;
+    // x axis: up × z.
+    let xx = up[1] * zz - up[2] * zy, xy = up[2] * zx - up[0] * zz, xz = up[0] * zy - up[1] * zx;
+    len = Math.hypot(xx, xy, xz);
+    if (len === 0) {
+        xx = 0;
+        xy = 0;
+        xz = 0;
+    }
+    else {
+        xx /= len;
+        xy /= len;
+        xz /= len;
+    }
+    // y axis: z × x.
+    const yx = zy * xz - zz * xy, yy = zz * xx - zx * xz, yz = zx * xy - zy * xx;
+    out[0] = xx;
+    out[1] = yx;
+    out[2] = zx;
+    out[3] = 0;
+    out[4] = xy;
+    out[5] = yy;
+    out[6] = zy;
+    out[7] = 0;
+    out[8] = xz;
+    out[9] = yz;
+    out[10] = zz;
+    out[11] = 0;
+    out[12] = -(xx * ex + xy * ey + xz * ez);
+    out[13] = -(yx * ex + yy * ey + yz * ez);
+    out[14] = -(zx * ex + zy * ey + zz * ez);
+    out[15] = 1;
+    return out;
+}
+/**
+ * 2D view over a `width × height` space (y down): the world point `(width/2 + x, height/2 + y)`
+ * lands on the space's centre, scaled by `zoom` about it. `rotation` (radians) turns the view
+ * clockwise on screen, so the world appears to turn counter-clockwise. With `x = y = rotation = 0` and `zoom = 1` it is the identity.
+ */
+function view2d(out, x, y, zoom, rotation, width, height) {
+    const c = Math.cos(-rotation) * zoom;
+    const s = Math.sin(-rotation) * zoom;
+    const cx = width / 2 + x;
+    const cy = height / 2 + y;
+    out.fill(0);
+    out[0] = c;
+    out[1] = s;
+    out[4] = -s;
+    out[5] = c;
+    out[10] = 1;
+    out[12] = width / 2 - c * cx + s * cy;
+    out[13] = height / 2 - s * cx - c * cy;
+    out[15] = 1;
+    return out;
+}
+/** `out = a⁻¹`. Returns null (and leaves `out` untouched) when `a` is singular. */
+function invert(out, a) {
+    const a00 = a[0], a01 = a[1], a02 = a[2], a03 = a[3];
+    const a10 = a[4], a11 = a[5], a12 = a[6], a13 = a[7];
+    const a20 = a[8], a21 = a[9], a22 = a[10], a23 = a[11];
+    const a30 = a[12], a31 = a[13], a32 = a[14], a33 = a[15];
+    const b00 = a00 * a11 - a01 * a10;
+    const b01 = a00 * a12 - a02 * a10;
+    const b02 = a00 * a13 - a03 * a10;
+    const b03 = a01 * a12 - a02 * a11;
+    const b04 = a01 * a13 - a03 * a11;
+    const b05 = a02 * a13 - a03 * a12;
+    const b06 = a20 * a31 - a21 * a30;
+    const b07 = a20 * a32 - a22 * a30;
+    const b08 = a20 * a33 - a23 * a30;
+    const b09 = a21 * a32 - a22 * a31;
+    const b10 = a21 * a33 - a23 * a31;
+    const b11 = a22 * a33 - a23 * a32;
+    const det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
+    if (!det || !Number.isFinite(det))
+        return null;
+    const d = 1 / det;
+    out[0] = (a11 * b11 - a12 * b10 + a13 * b09) * d;
+    out[1] = (a02 * b10 - a01 * b11 - a03 * b09) * d;
+    out[2] = (a31 * b05 - a32 * b04 + a33 * b03) * d;
+    out[3] = (a22 * b04 - a21 * b05 - a23 * b03) * d;
+    out[4] = (a12 * b08 - a10 * b11 - a13 * b07) * d;
+    out[5] = (a00 * b11 - a02 * b08 + a03 * b07) * d;
+    out[6] = (a32 * b02 - a30 * b05 - a33 * b01) * d;
+    out[7] = (a20 * b05 - a22 * b02 + a23 * b01) * d;
+    out[8] = (a10 * b10 - a11 * b08 + a13 * b06) * d;
+    out[9] = (a01 * b08 - a00 * b10 - a03 * b06) * d;
+    out[10] = (a30 * b04 - a31 * b02 + a33 * b00) * d;
+    out[11] = (a21 * b02 - a20 * b04 - a23 * b00) * d;
+    out[12] = (a11 * b07 - a10 * b09 - a12 * b06) * d;
+    out[13] = (a00 * b09 - a01 * b07 + a02 * b06) * d;
+    out[14] = (a31 * b01 - a30 * b03 - a32 * b00) * d;
+    out[15] = (a20 * b03 - a21 * b01 + a22 * b00) * d;
+    return out;
+}
+/**
+ * Transform the point `(x, y, z, 1)` by `m` and divide by w: `out[0..2]` get the result.
+ * Returns w (before the divide), which is ≤ 0 for a point behind a perspective camera.
+ */
+function transformPoint(out, m, x, y, z = 0) {
+    const w = m[3] * x + m[7] * y + m[11] * z + m[15];
+    const k = w !== 0 ? 1 / w : 1;
+    const ox = (m[0] * x + m[4] * y + m[8] * z + m[12]) * k;
+    const oy = (m[1] * x + m[5] * y + m[9] * z + m[13]) * k;
+    const oz = (m[2] * x + m[6] * y + m[10] * z + m[14]) * k;
+    out[0] = ox;
+    out[1] = oy;
+    out[2] = oz;
+    return w;
+}
+/** Column-major 4×4 matrix helpers. See the module comment for conventions. */
+export const mat4 = {
+    create,
+    identity,
+    copy,
+    multiply,
+    ortho,
+    perspective,
+    lookAt,
+    view2d,
+    invert,
+    transformPoint,
+};

package/dist/core/noise.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Seeded coherent noise (ws/core-2): value, Perlin (gradient) and simplex noise in 2D and 3D,
+ * plus fractal Brownian motion over any of them.
+ *
+ * `createNoise(seed)` shuffles a 256-entry permutation table with `createRandom(seed)` (the same
+ * seed hash as `Random`) and fills a 256-entry lattice value table in [-1, 1]. Every function
+ * returns a value in [-1, 1] (gradient and simplex noise are scaled to that span and clamped),
+ * is continuous in its inputs, and allocates nothing. The functions are plain closures, so
+ * `noise.perlin2` can be passed around unbound (`fbm(noise.perlin2, x, y)`).
+ */
+import { type Seed } from './random.js';
+/** A noise function; 2D ones ignore `z`. */
+export type NoiseFn = (x: number, y: number, z: number) => number;
+export interface FbmOptions {
+    /** Layers summed. Default 4. */
+    octaves?: number;
+    /** Frequency multiplier per octave. Default 2. */
+    lacunarity?: number;
+    /** Amplitude multiplier per octave. Default 0.5. */
+    gain?: number;
+}
+export interface Noise {
+    /** Lattice values smoothly interpolated (quintic fade). */
+    value2(x: number, y: number): number;
+    value3(x: number, y: number, z: number): number;
+    /** Improved Perlin gradient noise; 0 on every integer lattice point. */
+    perlin2(x: number, y: number): number;
+    perlin3(x: number, y: number, z: number): number;
+    /** Simplex noise (Gustavson's formulation). */
+    simplex2(x: number, y: number): number;
+    simplex3(x: number, y: number, z: number): number;
+    /**
+     * `octaves` layers of `fn`, each at `lacunarity` times the frequency and `gain` times the
+     * amplitude of the last, divided by the summed amplitude so the result stays in [-1, 1]. One
+     * octave is exactly `fn(x, y, z)`. Hoist the options object: a literal per call allocates.
+     */
+    fbm(fn: NoiseFn, x: number, y: number, z?: number, opts?: FbmOptions): number;
+}
+/** Seeded noise; see the module comment. Builds two small tables (allocates once). */
+export declare function createNoise(seed: Seed): Noise;