@netforge/engine 0.0.0-stage → 0.1.0

package/dist/runtime/feel/kit.d.ts

@@ -0,0 +1,159 @@
+/**
+ * FeelKit: the engine's game-feel kit behind one-liners a
+ * template calls from game events:
+ *
+ *   const feel = new FeelKit({ camera: rig, particles, project, preset: "default" });
+ *   const { now, dt } = feel.tick(performance.now());   // hit-stop aware render clock
+ *   feel.hit({ id, x, y, z, amount, dirX, dirZ });       // flash, knockback, number, sound, a touch of shake
+ *   feel.kill({ x, y, z, big });                          // burst, shake, hit-stop when big
+ *   feel.hurt(12);                                        // shake, stop, rumble, `hurtPulse` for a vignette
+ *   feel.update(dt);                                      // once per frame, after the events
+ *
+ * Nothing here needs three.js: the camera is any TraumaTarget (a CameraRig,
+ * or the kit's own Trauma), particles any ParticleSink, and world to screen
+ * an injected projector.
+ */
+import { FeelAudio, Footsteps } from "./audio.js";
+import type { Surface } from "./audio.js";
+import { FeelClock } from "./clock.js";
+import type { ClockTick } from "./clock.js";
+import { HitFlash } from "./flash.js";
+import { KnockbackOffsets } from "./knockback.js";
+import { DamageNumbers } from "./numbers.js";
+import { Rumble } from "./rumble.js";
+import { Trauma } from "./trauma.js";
+import { Tweens } from "./tween.js";
+import type { ParticleSink, Projector, TraumaTarget } from "./types.js";
+/** Tunables for every one-liner. Pick a named preset or override fields. */
+export interface FeelPreset {
+    /** Trauma per hit, and the most hits may add in one frame (a nova through 50 enemies is one kick). */
+    readonly hitTrauma: number;
+    readonly hitTraumaPerFrame: number;
+    readonly killTrauma: number;
+    readonly bigKillTrauma: number;
+    /** Hurt trauma at a hit of 10% max health; scales with damage up to 2x. */
+    readonly hurtTrauma: number;
+    readonly bigKillStopMs: number;
+    readonly hurtStopMs: number;
+    readonly levelUpStopMs: number;
+    /** Visual knockback strength (m of offset) of a normal and a big hit. */
+    readonly knockback: number;
+    readonly bigKnockback: number;
+    readonly flashSeconds: number;
+    /** FOV punches, degrees (negative zooms in). */
+    readonly bigKillPunch: number;
+    readonly hurtPunch: number;
+    readonly levelUpPunch: number;
+    readonly dashPunch: number;
+    readonly landTrauma: number;
+    /** Rumble [strong, weak, ms]. */
+    readonly hurtRumble: readonly [number, number, number];
+    readonly bigKillRumble: readonly [number, number, number];
+    readonly landRumble: readonly [number, number, number];
+    /** Particle counts for kill bursts. */
+    readonly killParticles: number;
+    readonly bigKillParticles: number;
+    /** Most damage numbers started per frame. */
+    readonly numbersPerFrame: number;
+}
+export type FeelPresetName = "subtle" | "default" | "heavy";
+export declare const FEEL_PRESETS: Readonly<Record<FeelPresetName, FeelPreset>>;
+export interface HitEvent {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly amount: number;
+    /** Entity id (flash, knockback and number merging key on it). */
+    readonly id?: number;
+    readonly big?: boolean;
+    /** Direction the hit pushes, in the ground plane. */
+    readonly dirX?: number;
+    readonly dirZ?: number;
+    /** Damage-number colour key. */
+    readonly kind?: string;
+}
+export interface KillEvent {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly big?: boolean;
+    readonly id?: number;
+    /** Burst tint 0xRRGGBB. */
+    readonly color?: number;
+    /** Particle preset name. Default "kill" or "bigKill". */
+    readonly particles?: string;
+    readonly dirX?: number;
+    readonly dirZ?: number;
+}
+export interface FeelKitOptions {
+    readonly preset?: FeelPresetName | (Partial<FeelPreset> & {
+        readonly base?: FeelPresetName;
+    });
+    /** Where shake and punches go (a CameraRig). Default: the kit's own `trauma`, which a template applies itself. */
+    readonly camera?: TraumaTarget;
+    readonly particles?: ParticleSink | null;
+    /** World to screen, for damage numbers and sound panning. */
+    readonly project?: Projector;
+    /** Screen width in px for panning (read each call). */
+    readonly screenWidth?: () => number;
+    /** Damage numbers: an existing pool, a host element to build one in, or null for none. Default: document.body in a browser. */
+    readonly numbers?: DamageNumbers | HTMLElement | null;
+    readonly audio?: FeelAudio | null;
+    readonly rumble?: Rumble | null;
+    readonly clock?: FeelClock;
+}
+export declare class FeelKit {
+    readonly preset: FeelPreset;
+    readonly clock: FeelClock;
+    readonly flash: HitFlash;
+    readonly knock: KnockbackOffsets;
+    /** The kit's own shake when no camera is given (apply trauma.x/y/roll yourself). */
+    readonly trauma: Trauma;
+    readonly tweens: Tweens;
+    readonly numbers: DamageNumbers | null;
+    readonly audio: FeelAudio | null;
+    readonly rumble: Rumble | null;
+    readonly footsteps: Footsteps | null;
+    particles: ParticleSink | null;
+    /** 0..1, jumps to 1 on hurt and fades: drive a red vignette with it. */
+    hurtPulse: number;
+    /** Effects fired so far (playtest counters). */
+    readonly counts: {
+        hits: number;
+        kills: number;
+        bigKills: number;
+        hurts: number;
+        levelUps: number;
+        lands: number;
+        dashes: number;
+    };
+    /** Where shake and punches go. Assignable, so a template can build the kit before its camera. */
+    camera: TraumaTarget;
+    /** World to screen for numbers and panning. Assignable for the same reason. */
+    project: Projector | undefined;
+    private readonly width;
+    private frameTrauma;
+    private frameNumbers;
+    private stepSpeed;
+    private stepGrounded;
+    constructor(opts?: FeelKitOptions);
+    /** The render clock for this frame (hit-stop and slow motion aware). */
+    tick(realNow?: number): ClockTick;
+    private shake;
+    private punch;
+    private pan;
+    /** An enemy (or anything) took a hit. */
+    hit(e: HitEvent): void;
+    /** Something died. Big kills (bosses, elites) stop time, punch the camera and rumble. */
+    kill(e: KillEvent): void;
+    /** The local player took `amount` damage (pass maxHealth to scale by how much it hurt). */
+    hurt(amount: number, maxHealth?: number): void;
+    levelUp(): void;
+    /** Landed from a jump or fall; `intensity` 0..1 (fall speed over a hard landing's). */
+    land(intensity?: number): void;
+    dash(): void;
+    /** The local character's ground speed this frame (m/s); steps play at a cadence from it during `update`. */
+    footstep(speed: number, grounded?: boolean, surface?: Surface): void;
+    /** Advance every effect; call once per frame after the frame's events, with the clock's dt. */
+    update(dt: number, realDt?: number): void;
+}

package/dist/runtime/feel/kit.js

@@ -0,0 +1,226 @@
+/**
+ * FeelKit: the engine's game-feel kit behind one-liners a
+ * template calls from game events:
+ *
+ *   const feel = new FeelKit({ camera: rig, particles, project, preset: "default" });
+ *   const { now, dt } = feel.tick(performance.now());   // hit-stop aware render clock
+ *   feel.hit({ id, x, y, z, amount, dirX, dirZ });       // flash, knockback, number, sound, a touch of shake
+ *   feel.kill({ x, y, z, big });                          // burst, shake, hit-stop when big
+ *   feel.hurt(12);                                        // shake, stop, rumble, `hurtPulse` for a vignette
+ *   feel.update(dt);                                      // once per frame, after the events
+ *
+ * Nothing here needs three.js: the camera is any TraumaTarget (a CameraRig,
+ * or the kit's own Trauma), particles any ParticleSink, and world to screen
+ * an injected projector.
+ */
+import { FeelAudio, Footsteps } from "./audio.js";
+import { FeelClock } from "./clock.js";
+import { HitFlash } from "./flash.js";
+import { KnockbackOffsets } from "./knockback.js";
+import { DamageNumbers } from "./numbers.js";
+import { Rumble } from "./rumble.js";
+import { Trauma } from "./trauma.js";
+import { Tweens } from "./tween.js";
+export const FEEL_PRESETS = {
+    subtle: {
+        hitTrauma: 0.01, hitTraumaPerFrame: 0.04, killTrauma: 0.015, bigKillTrauma: 0.3, hurtTrauma: 0.3,
+        bigKillStopMs: 35, hurtStopMs: 20, levelUpStopMs: 30, knockback: 0.12, bigKnockback: 0.25, flashSeconds: 0.07,
+        bigKillPunch: 1.5, hurtPunch: 1, levelUpPunch: -2, dashPunch: 1.5, landTrauma: 0.12,
+        hurtRumble: [0.35, 0.2, 90], bigKillRumble: [0.4, 0.25, 120], landRumble: [0.15, 0.1, 60],
+        killParticles: 5, bigKillParticles: 18, numbersPerFrame: 8,
+    },
+    default: {
+        hitTrauma: 0.02, hitTraumaPerFrame: 0.08, killTrauma: 0.03, bigKillTrauma: 0.5, hurtTrauma: 0.45,
+        bigKillStopMs: 55, hurtStopMs: 35, levelUpStopMs: 45, knockback: 0.2, bigKnockback: 0.4, flashSeconds: 0.09,
+        bigKillPunch: 3, hurtPunch: 2, levelUpPunch: -4, dashPunch: 3, landTrauma: 0.2,
+        hurtRumble: [0.6, 0.35, 120], bigKillRumble: [0.7, 0.4, 160], landRumble: [0.25, 0.15, 70],
+        killParticles: 8, bigKillParticles: 28, numbersPerFrame: 12,
+    },
+    heavy: {
+        hitTrauma: 0.035, hitTraumaPerFrame: 0.14, killTrauma: 0.05, bigKillTrauma: 0.75, hurtTrauma: 0.6,
+        bigKillStopMs: 85, hurtStopMs: 55, levelUpStopMs: 70, knockback: 0.32, bigKnockback: 0.6, flashSeconds: 0.12,
+        bigKillPunch: 5, hurtPunch: 3, levelUpPunch: -6, dashPunch: 4.5, landTrauma: 0.32,
+        hurtRumble: [0.85, 0.5, 160], bigKillRumble: [1, 0.6, 220], landRumble: [0.4, 0.25, 90],
+        killParticles: 12, bigKillParticles: 40, numbersPerFrame: 16,
+    },
+};
+const realNowMs = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+export class FeelKit {
+    preset;
+    clock;
+    flash;
+    knock;
+    /** The kit's own shake when no camera is given (apply trauma.x/y/roll yourself). */
+    trauma;
+    tweens = new Tweens();
+    numbers;
+    audio;
+    rumble;
+    footsteps;
+    particles;
+    /** 0..1, jumps to 1 on hurt and fades: drive a red vignette with it. */
+    hurtPulse = 0;
+    /** Effects fired so far (playtest counters). */
+    counts = { hits: 0, kills: 0, bigKills: 0, hurts: 0, levelUps: 0, lands: 0, dashes: 0 };
+    /** Where shake and punches go. Assignable, so a template can build the kit before its camera. */
+    camera;
+    /** World to screen for numbers and panning. Assignable for the same reason. */
+    project;
+    width;
+    frameTrauma = 0;
+    frameNumbers = 0;
+    stepSpeed = 0;
+    stepGrounded = true;
+    constructor(opts = {}) {
+        const p = opts.preset ?? "default";
+        this.preset = typeof p === "string" ? FEEL_PRESETS[p] : { ...FEEL_PRESETS[p.base ?? "default"], ...p };
+        this.clock = opts.clock ?? new FeelClock();
+        this.flash = new HitFlash(this.preset.flashSeconds);
+        this.knock = new KnockbackOffsets();
+        this.trauma = new Trauma();
+        this.camera = opts.camera ?? this.trauma;
+        this.particles = opts.particles ?? null;
+        this.project = opts.project;
+        this.width = opts.screenWidth ?? (() => (typeof innerWidth !== "undefined" ? innerWidth : 0));
+        const hasDom = typeof document !== "undefined";
+        if (opts.numbers === null)
+            this.numbers = null;
+        else if (opts.numbers instanceof DamageNumbers)
+            this.numbers = opts.numbers;
+        else if (opts.numbers !== undefined)
+            this.numbers = new DamageNumbers(opts.numbers);
+        else
+            this.numbers = hasDom && document.body ? new DamageNumbers(document.body) : null;
+        this.audio = opts.audio === undefined ? new FeelAudio() : opts.audio;
+        this.rumble = opts.rumble === undefined ? new Rumble() : opts.rumble;
+        const audio = this.audio;
+        this.footsteps = audio ? new Footsteps((pitch, gain) => void audio.play("step", { pitch, gain })) : null;
+    }
+    /** The render clock for this frame (hit-stop and slow motion aware). */
+    tick(realNow = realNowMs()) {
+        return this.clock.tick(realNow);
+    }
+    shake(amount) {
+        if (amount > 0)
+            this.camera.addTrauma(amount);
+    }
+    punch(deg) {
+        if (deg !== 0)
+            this.camera.punch?.(deg);
+    }
+    pan(x, y, z) {
+        if (!this.project)
+            return {};
+        const s = this.project(x, y, z);
+        return { screenX: s.x, width: this.width() };
+    }
+    /** An enemy (or anything) took a hit. */
+    hit(e) {
+        const P = this.preset;
+        this.counts.hits++;
+        if (e.id !== undefined) {
+            this.flash.trigger(e.id);
+            if (e.dirX !== undefined || e.dirZ !== undefined)
+                this.knock.kick(e.id, e.dirX ?? 0, e.dirZ ?? 0, e.big ? P.bigKnockback : P.knockback);
+        }
+        if (this.numbers && this.project && this.frameNumbers < P.numbersPerFrame) {
+            const s = this.project(e.x, e.y, e.z);
+            if (s.onScreen) {
+                this.frameNumbers++;
+                this.numbers.add({ x: s.x, y: s.y, amount: e.amount, big: e.big === true, ...(e.id !== undefined ? { id: e.id } : {}), ...(e.kind ? { kind: e.kind } : {}) });
+            }
+        }
+        this.audio?.impact(e.amount, this.pan(e.x, e.y, e.z));
+        const room = P.hitTraumaPerFrame - this.frameTrauma;
+        if (room > 0) {
+            const t = Math.min(room, e.big ? P.hitTrauma * 3 : P.hitTrauma);
+            this.frameTrauma += t;
+            this.shake(t);
+        }
+    }
+    /** Something died. Big kills (bosses, elites) stop time, punch the camera and rumble. */
+    kill(e) {
+        const P = this.preset;
+        this.counts.kills++;
+        const big = e.big === true;
+        this.particles?.burst(e.particles ?? (big ? "bigKill" : "kill"), e.x, e.y, e.z, {
+            count: big ? P.bigKillParticles : P.killParticles,
+            ...(e.color !== undefined ? { color: e.color } : {}),
+            ...(e.dirX !== undefined ? { dirX: e.dirX } : {}),
+            ...(e.dirZ !== undefined ? { dirZ: e.dirZ } : {}),
+        });
+        this.audio?.play(big ? "bigKill" : "kill", this.pan(e.x, e.y, e.z));
+        if (!big) {
+            const room = P.hitTraumaPerFrame - this.frameTrauma;
+            if (room > 0) {
+                const t = Math.min(room, P.killTrauma);
+                this.frameTrauma += t;
+                this.shake(t);
+            }
+            return;
+        }
+        this.counts.bigKills++;
+        this.shake(P.bigKillTrauma);
+        this.clock.hitStop(P.bigKillStopMs);
+        this.punch(P.bigKillPunch);
+        const [s, w, ms] = P.bigKillRumble;
+        this.rumble?.pulse(s, w, ms);
+    }
+    /** The local player took `amount` damage (pass maxHealth to scale by how much it hurt). */
+    hurt(amount, maxHealth = 100) {
+        if (!(amount > 0))
+            return;
+        const P = this.preset;
+        this.counts.hurts++;
+        const k = Math.min(2, Math.max(0.5, amount / Math.max(1, maxHealth * 0.1)));
+        this.shake(P.hurtTrauma * k);
+        this.clock.hitStop(P.hurtStopMs);
+        this.punch(P.hurtPunch);
+        this.hurtPulse = 1;
+        const [s, w, ms] = P.hurtRumble;
+        this.rumble?.pulse(Math.min(1, s * k), Math.min(1, w * k), ms);
+        this.audio?.play("hurt");
+    }
+    levelUp() {
+        this.counts.levelUps++;
+        this.clock.hitStop(this.preset.levelUpStopMs);
+        this.punch(this.preset.levelUpPunch);
+        this.audio?.play("levelUp");
+    }
+    /** Landed from a jump or fall; `intensity` 0..1 (fall speed over a hard landing's). */
+    land(intensity = 1) {
+        const k = Math.max(0, Math.min(1, intensity));
+        if (k <= 0.05)
+            return;
+        this.counts.lands++;
+        this.shake(this.preset.landTrauma * k);
+        const [s, w, ms] = this.preset.landRumble;
+        this.rumble?.pulse(s * k, w * k, ms);
+        this.audio?.play("land", { gain: 0.5 + 0.5 * k });
+    }
+    dash() {
+        this.counts.dashes++;
+        this.punch(this.preset.dashPunch);
+        this.audio?.play("dash");
+    }
+    /** The local character's ground speed this frame (m/s); steps play at a cadence from it during `update`. */
+    footstep(speed, grounded = true, surface) {
+        this.stepSpeed = speed;
+        this.stepGrounded = grounded;
+        if (surface && this.footsteps)
+            this.footsteps.surface = surface;
+    }
+    /** Advance every effect; call once per frame after the frame's events, with the clock's dt. */
+    update(dt, realDt = dt) {
+        this.flash.update(dt);
+        this.knock.update(dt);
+        this.numbers?.update(dt);
+        this.tweens.tick(realDt);
+        if (this.camera === this.trauma)
+            this.trauma.update(realDt);
+        this.footsteps?.update(dt, this.stepSpeed, this.stepGrounded);
+        this.hurtPulse = Math.max(0, this.hurtPulse - realDt * 2.5);
+        this.frameTrauma = 0;
+        this.frameNumbers = 0;
+    }
+}

package/dist/runtime/feel/knockback.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Client-side visual knockback and squash per entity. The authoritative
+ * sim moves the entity; this adds a springy offset and a squash-stretch on
+ * top of the interpolated position, so a hit reads instantly even ~100 ms
+ * in the past. Read `get(id)` each frame and add it when drawing.
+ */
+export interface KnockbackOptions {
+    /** Offset spring frequency, Hz. Default 7. */
+    readonly frequency?: number;
+    /** Offset damping ratio (below 1 wobbles back). Default 0.5. */
+    readonly damping?: number;
+    /** Largest offset, m. Default 0.6. */
+    readonly maxOffset?: number;
+    /** Squash per unit of strength (0 disables). Default 0.35. */
+    readonly squash?: number;
+}
+export interface KnockbackSample {
+    /** Offset to add to the drawn position, m. */
+    x: number;
+    z: number;
+    /** Scale to multiply the drawn scale by (squash on y, bulge on x and z). */
+    sx: number;
+    sy: number;
+    sz: number;
+}
+export declare class KnockbackOffsets {
+    private readonly m;
+    private readonly out;
+    private readonly o;
+    /** Kicks so far (playtest counters). */
+    kicks: number;
+    constructor(opts?: KnockbackOptions);
+    /** Shove `id` along (dirX, dirZ) with `strength` (about metres of peak offset). */
+    kick(id: number, dirX: number, dirZ: number, strength?: number): void;
+    /** This frame's offset and scale for `id` (a shared object: read it before the next call). */
+    get(id: number): Readonly<KnockbackSample>;
+    update(dt: number): void;
+    /** Entities still moving. */
+    get size(): number;
+    clear(): void;
+}

package/dist/runtime/feel/knockback.js

@@ -0,0 +1,70 @@
+import { stepSpring } from "./spring.js";
+const REST = Object.freeze({ x: 0, z: 0, sx: 1, sy: 1, sz: 1 });
+export class KnockbackOffsets {
+    m = new Map();
+    out = { x: 0, z: 0, sx: 1, sy: 1, sz: 1 };
+    o;
+    /** Kicks so far (playtest counters). */
+    kicks = 0;
+    constructor(opts = {}) {
+        this.o = { frequency: 7, damping: 0.5, maxOffset: 0.6, squash: 0.35, ...opts };
+    }
+    /** Shove `id` along (dirX, dirZ) with `strength` (about metres of peak offset). */
+    kick(id, dirX, dirZ, strength = 1) {
+        if (!(strength > 0))
+            return;
+        const len = Math.hypot(dirX, dirZ);
+        const nx = len > 1e-6 ? dirX / len : 0;
+        const nz = len > 1e-6 ? dirZ / len : 0;
+        let e = this.m.get(id);
+        if (!e) {
+            e = { x: 0, z: 0, vx: 0, vz: 0, s: 0, vs: 0 };
+            this.m.set(id, e);
+        }
+        this.kicks++;
+        // A peak offset of about `strength` for this spring: v0 = strength * omega (scaled for damping).
+        const v = strength * this.o.frequency * Math.PI * 2 * 0.6;
+        e.vx += nx * v;
+        e.vz += nz * v;
+        e.vs += this.o.squash * strength * 30;
+    }
+    /** This frame's offset and scale for `id` (a shared object: read it before the next call). */
+    get(id) {
+        const e = this.m.get(id);
+        if (!e)
+            return REST;
+        const o = this.out;
+        o.x = e.x;
+        o.z = e.z;
+        const s = Math.max(-0.5, Math.min(0.5, e.s));
+        o.sy = 1 - s;
+        o.sx = o.sz = 1 + s * 0.5;
+        return o;
+    }
+    update(dt) {
+        if (dt <= 0)
+            return;
+        const w = this.o.frequency * Math.PI * 2;
+        const z = this.o.damping;
+        const max = this.o.maxOffset;
+        for (const [id, e] of this.m) {
+            [e.x, e.vx] = stepSpring(e.x, e.vx, 0, w, z, dt);
+            [e.z, e.vz] = stepSpring(e.z, e.vz, 0, w, z, dt);
+            [e.s, e.vs] = stepSpring(e.s, e.vs, 0, w * 1.6, 0.35, dt);
+            const len = Math.hypot(e.x, e.z);
+            if (len > max) {
+                e.x *= max / len;
+                e.z *= max / len;
+            }
+            if (Math.abs(e.x) + Math.abs(e.z) + Math.abs(e.s) < 1e-3 && Math.abs(e.vx) + Math.abs(e.vz) + Math.abs(e.vs) < 1e-2)
+                this.m.delete(id);
+        }
+    }
+    /** Entities still moving. */
+    get size() {
+        return this.m.size;
+    }
+    clear() {
+        this.m.clear();
+    }
+}

package/dist/runtime/feel/noise.d.ts

@@ -0,0 +1,6 @@
+/** Seeded integer hash to -1..1 (deterministic, no Math.random). */
+export declare function hashSigned(i: number, seed: number): number;
+/** Smooth 1D value noise in -1..1, continuous in `t`, fixed for a seed. */
+export declare function valueNoise1(t: number, seed: number): number;
+/** A small seeded PRNG (mulberry32), 0..1, for cosmetic variation that should not use Math.random. */
+export declare function seededRandom(seed: number): () => number;

package/dist/runtime/feel/noise.js

@@ -0,0 +1,30 @@
+/** Seeded integer hash to -1..1 (deterministic, no Math.random). */
+export function hashSigned(i, seed) {
+    let h = Math.imul((i | 0) ^ Math.imul(seed | 0, 0x9e3779b1), 0x27d4eb2d);
+    h ^= h >>> 15;
+    h = Math.imul(h, 0x85ebca6b);
+    h ^= h >>> 13;
+    h = Math.imul(h, 0xc2b2ae35);
+    h ^= h >>> 16;
+    return ((h >>> 0) / 4294967295) * 2 - 1;
+}
+/** Smooth 1D value noise in -1..1, continuous in `t`, fixed for a seed. */
+export function valueNoise1(t, seed) {
+    const i = Math.floor(t);
+    const f = t - i;
+    const u = f * f * (3 - 2 * f);
+    const a = hashSigned(i, seed);
+    const b = hashSigned(i + 1, seed);
+    return a + (b - a) * u;
+}
+/** A small seeded PRNG (mulberry32), 0..1, for cosmetic variation that should not use Math.random. */
+export function seededRandom(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/runtime/feel/numbers.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Floating damage numbers. `NumberStack` is the DOM-free core (slots,
+ * merging, motion); `DamageNumbers` draws it with a fixed pool of DOM nodes
+ * moved by transforms only (no layout per frame).
+ */
+export interface NumberInput {
+    /** Screen position in CSS pixels. */
+    readonly x: number;
+    readonly y: number;
+    readonly amount: number;
+    /** Entity id: rapid hits on one id merge into one growing number. */
+    readonly id?: number;
+    /** Big hits (bosses, crits) pop larger. */
+    readonly big?: boolean;
+    /** A colour key ("damage", "crit", "heal", "xp", ...) mapped by DamageNumbers. */
+    readonly kind?: string;
+}
+export interface NumberSlot {
+    active: boolean;
+    id: number;
+    amount: number;
+    /** 0..1 through its life. */
+    t: number;
+    x: number;
+    y: number;
+    /** Sideways drift, px over the whole life. */
+    drift: number;
+    big: boolean;
+    kind: string;
+    /** When it was last added to (ms, the caller's clock). */
+    at: number;
+    /** Generation, bumped on reuse (renderers compare it to restyle). */
+    gen: number;
+}
+export interface NumberStackOptions {
+    /** Hits on the same id within this many ms merge. Default 120. */
+    readonly mergeMs?: number;
+    /** Seconds a number lives. Default 0.75. */
+    readonly lifeSeconds?: number;
+    /** Rise over its life, px. Default 34. */
+    readonly rise?: number;
+}
+export interface NumberDraw {
+    readonly x: number;
+    readonly y: number;
+    readonly scale: number;
+    readonly opacity: number;
+}
+export declare class NumberStack {
+    readonly slots: NumberSlot[];
+    /** Numbers shown (merges do not count). */
+    shown: number;
+    merged: number;
+    private readonly o;
+    private seq;
+    constructor(capacity?: number, opts?: NumberStackOptions);
+    /** Add a number; returns its slot index and whether it merged into an existing one. */
+    add(nowMs: number, n: NumberInput): {
+        index: number;
+        merged: boolean;
+    };
+    update(dt: number): void;
+    /** Where and how to draw a slot: an arc (rise with ease-out, sideways drift), a pop, then a fade. */
+    draw(s: NumberSlot): NumberDraw;
+    get active(): number;
+}
+export interface DamageNumbersOptions extends NumberStackOptions {
+    /** Pool size (most numbers on screen). Default 48. */
+    readonly capacity?: number;
+    /** Class on every node (style it in the template). Default "dmg"; big ones also get "big". */
+    readonly className?: string;
+    /** Colour per kind (CSS colours). */
+    readonly colors?: Readonly<Record<string, string>>;
+    /** Number formatting. Default rounds. */
+    readonly format?: (amount: number) => string;
+}
+/** The DOM pool. Construct only in a browser (it creates nodes under `host`). */
+export declare class DamageNumbers {
+    readonly stack: NumberStack;
+    private readonly els;
+    private readonly colors;
+    private readonly format;
+    private readonly cls;
+    constructor(host: HTMLElement, opts?: DamageNumbersOptions | number);
+    /** Numbers shown so far (playtest counters). */
+    get shown(): number;
+    /** The classic call: show(x, y, amount, big). */
+    show(x: number, y: number, amount: number, big?: boolean): void;
+    add(n: NumberInput, nowMs?: number): void;
+    update(dt: number): void;
+}