@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/vfx/damageDirection.js

@@ -0,0 +1,188 @@
+const TAU = Math.PI * 2;
+/** Shortest angular distance (magnitude) between two angles, in `0..π`. */
+function angularDistance(a, b) {
+    let d = (a - b) % TAU;
+    if (d < -Math.PI)
+        d += TAU;
+    else if (d > Math.PI)
+        d -= TAU;
+    return Math.abs(d);
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * Create a damage-direction tracker: the classic "hit-from" feedback brain. A
+ * game calls `registerHit({ angle, intensity, kind })` with the bearing from the
+ * player toward the attacker (radians, `0` = front) and the tracker owns the fade
+ * timers and eased strength so the renderer just draws an arc per `active()`
+ * entry. It is renderer-free and genre-agnostic (the `kind` tag is never
+ * interpreted here), allocation-aware (a fixed pool, no per-frame garbage), and
+ * fully serializable via `snapshot`/`restore`. Optional angle merging collapses a
+ * burst from one direction into a single strong arc.
+ *
+ * @capability damage-direction serializable hit-from damage-direction indicator brain — pooled directional arcs that flare on `registerHit(angle, intensity)` and fade on an injected clock, with optional same-direction merging
+ */
+export function createDamageDirectionTracker(options = {}) {
+    const now = options.now ?? Date.now;
+    const defaultDuration = Math.max(1, options.duration ?? 1200);
+    const max = Math.max(1, Math.floor(options.max ?? 32));
+    const mergeWindow = Math.max(0, options.mergeWindow ?? 0);
+    const easing = options.easing ?? ((x) => 1 - (1 - x) * (1 - x));
+    // Fixed pool — slots are reused, never re-allocated.
+    const slots = [];
+    // Reused output views + array, so `active()` allocates nothing on the hot path.
+    const views = [];
+    const out = [];
+    for (let i = 0; i < max; i += 1) {
+        slots.push({ active: false, angle: 0, kind: "default", intensity: 0, bornAt: 0, duration: 0 });
+        views.push({ angle: 0, kind: "default", intensity: 0, age: 0 });
+    }
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Current eased strength of a slot at time `t` (ms), or `0` once fully faded. */
+    function strengthAt(slot, t) {
+        const elapsed = t - slot.bornAt;
+        if (elapsed <= 0)
+            return slot.intensity;
+        if (elapsed >= slot.duration)
+            return 0;
+        return slot.intensity * easing(1 - elapsed / slot.duration);
+    }
+    /** Find a reusable slot: a dead one, else the weakest live one to evict. */
+    function acquireSlot(t) {
+        let weakest = null;
+        let weakestStrength = Infinity;
+        for (const slot of slots) {
+            if (!slot.active)
+                return slot;
+            const s = strengthAt(slot, t);
+            if (s <= 0)
+                return slot;
+            if (s < weakestStrength) {
+                weakestStrength = s;
+                weakest = slot;
+            }
+        }
+        return weakest ?? slots[0];
+    }
+    function writeView(index, slot, t) {
+        const view = views[index];
+        view.angle = slot.angle;
+        view.kind = slot.kind;
+        view.intensity = strengthAt(slot, t);
+        view.age = Math.max(0, (t - slot.bornAt) / 1000);
+        return view;
+    }
+    return {
+        registerHit(hit) {
+            const t = now();
+            const angle = hit.angle;
+            const kind = hit.kind ?? "default";
+            const intensity = clamp01(hit.intensity ?? 1);
+            let slot = null;
+            if (mergeWindow > 0) {
+                // Refresh a live, same-kind indicator from a nearby direction.
+                for (const candidate of slots) {
+                    if (!candidate.active || candidate.kind !== kind)
+                        continue;
+                    if (strengthAt(candidate, t) <= 0)
+                        continue;
+                    if (angularDistance(candidate.angle, angle) <= mergeWindow) {
+                        slot = candidate;
+                        break;
+                    }
+                }
+            }
+            const merged = slot !== null;
+            if (slot === null)
+                slot = acquireSlot(t);
+            // A merged refresh keeps the stronger peak so a burst reads bright.
+            const peak = merged ? Math.max(intensity, slot.intensity) : intensity;
+            slot.active = true;
+            slot.angle = angle;
+            slot.kind = kind;
+            slot.intensity = peak;
+            slot.bornAt = t;
+            slot.duration = defaultDuration;
+            notify();
+            return writeView(slots.indexOf(slot), slot, t);
+        },
+        active() {
+            const t = now();
+            out.length = 0;
+            for (let i = 0; i < slots.length; i += 1) {
+                const slot = slots[i];
+                if (!slot.active)
+                    continue;
+                if (t - slot.bornAt >= slot.duration) {
+                    slot.active = false;
+                    continue;
+                }
+                out.push(writeView(i, slot, t));
+            }
+            out.sort((a, b) => b.intensity - a.intensity);
+            return out;
+        },
+        count() {
+            const t = now();
+            let n = 0;
+            for (const slot of slots) {
+                if (!slot.active)
+                    continue;
+                if (t - slot.bornAt < slot.duration)
+                    n += 1;
+                else
+                    slot.active = false;
+            }
+            return n;
+        },
+        clear() {
+            let changed = false;
+            for (const slot of slots) {
+                if (slot.active) {
+                    slot.active = false;
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            const t = now();
+            const indicators = slots
+                .filter((slot) => slot.active && t - slot.bornAt < slot.duration)
+                .map((slot) => ({
+                angle: slot.angle,
+                kind: slot.kind,
+                intensity: slot.intensity,
+                bornAt: slot.bornAt,
+                duration: slot.duration,
+            }));
+            return { now: t, indicators };
+        },
+        restore(snapshot) {
+            for (const slot of slots)
+                slot.active = false;
+            const limit = Math.min(slots.length, snapshot.indicators.length);
+            for (let i = 0; i < limit; i += 1) {
+                const src = snapshot.indicators[i];
+                const slot = slots[i];
+                slot.active = true;
+                slot.angle = src.angle;
+                slot.kind = src.kind;
+                slot.intensity = clamp01(src.intensity);
+                slot.bornAt = src.bornAt;
+                slot.duration = Math.max(1, src.duration);
+            }
+            notify();
+        },
+    };
+}

package/dist/vfx/particles.d.ts

@@ -0,0 +1,103 @@
+/** A 3D vector `[x, y, z]`. */
+export type Vec3 = readonly [number, number, number];
+/** A `[min, max]` range a spawned particle draws uniformly from. */
+export interface Range {
+    min: number;
+    max: number;
+}
+/** A per-life start→end curve (linear interpolation from birth to death). */
+export interface Curve {
+    start: number;
+    end: number;
+}
+/**
+ * A particle emitter: how particles spawn and how each one evolves over its life.
+ * Every field is data — no functions — so an emitter is fully serializable and an
+ * editor/tunable can drive it. Genre-agnostic: smoke, sparks, rain, magic, dust.
+ */
+export interface EmitterConfig {
+    /** Hard cap on live particles; the pool never grows past this. Default 512. */
+    max?: number;
+    /** Continuous emission rate in particles/second. Default 0 (burst-only). */
+    rate?: number;
+    /** Spawn origin. Default `[0, 0, 0]`. */
+    position?: Vec3;
+    /** Half-extents of a box the spawn point is jittered within. Default `[0, 0, 0]`. */
+    spawnJitter?: Vec3;
+    /** Particle lifetime in seconds. Default `{ min: 1, max: 1 }`. */
+    lifetime?: Range;
+    /** Initial speed along the emit direction, in units/second. Default `{ min: 1, max: 1 }`. */
+    speed?: Range;
+    /** Base emit direction (need not be normalized). Default `[0, 1, 0]` (up). */
+    direction?: Vec3;
+    /** Cone half-angle in radians around `direction`; `Math.PI` emits in all directions. Default 0. */
+    spread?: number;
+    /** Constant acceleration (e.g. gravity `[0, -9.8, 0]`). Default `[0, 0, 0]`. */
+    gravity?: Vec3;
+    /** Linear velocity damping per second, `0` (none) to `1` (stop instantly). Default 0. */
+    drag?: number;
+    /** Particle radius over life. Default `{ start: 1, end: 1 }`. */
+    size?: Curve;
+    /** `0xRRGGBB` color at birth. Default `0xffffff`. */
+    colorStart?: number;
+    /** `0xRRGGBB` color at death. Default = `colorStart`. */
+    colorEnd?: number;
+    /** Opacity over life, each `0..1`. Default `{ start: 1, end: 0 }` (fade out). */
+    alpha?: Curve;
+    /** Injected clock — unused by the sim (it is dt-driven) but reserved; determinism comes from `seed`. */
+    seed?: string | number;
+}
+/**
+ * Read-only packed buffers of the live particles, laid out for a renderer to
+ * upload directly (Structure-of-Arrays, no per-particle objects). Only the first
+ * `count` entries are live; the arrays themselves are reused every frame.
+ */
+export interface ParticleBuffers {
+    count: number;
+    /** `count * 3` floats: x, y, z per particle. */
+    positions: Float32Array;
+    /** `count` floats: current radius per particle. */
+    sizes: Float32Array;
+    /** `count * 3` floats: r, g, b in `0..1` per particle. */
+    colors: Float32Array;
+    /** `count` floats: opacity `0..1` per particle. */
+    alphas: Float32Array;
+}
+/** Serializable simulation state for save/restore and deterministic replay. */
+export interface ParticleSnapshot {
+    seed: number;
+    accumulator: number;
+    count: number;
+    data: number[];
+}
+/** A live, dt-driven particle simulation. */
+export interface ParticleSystem {
+    /** Advance the sim by `dt` seconds: emit from `rate`, integrate, and reap dead particles. */
+    update(dt: number): void;
+    /** Spawn `n` particles immediately (a one-shot puff/explosion), independent of `rate`. */
+    emit(n: number): void;
+    /** Live particle count. */
+    count(): number;
+    /** The packed buffers for rendering (valid until the next `update`/`emit`). */
+    buffers(): ParticleBuffers;
+    /** Kill all particles and reset the emission accumulator (keeps the seed stream). */
+    clear(): void;
+    /** Patch the emitter config in place (e.g. move the origin, change the rate). */
+    configure(patch: Partial<EmitterConfig>): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): ParticleSnapshot;
+    restore(snapshot: ParticleSnapshot): void;
+}
+/**
+ * A generic, allocation-aware particle system: one emitter, a fixed pool, and
+ * Structure-of-Arrays buffers a renderer uploads straight to the GPU. It is
+ * dt-driven (call `update(dt)` each frame) and deterministic — all randomness
+ * flows from an injected `seed`, so the same seed and dt sequence reproduce the
+ * same frames, and `snapshot`/`restore` round-trips the live pool. Nothing here
+ * is combat- or genre-specific: configure it for smoke, sparks, rain, dust,
+ * embers, magic, or confetti. Travel/gameplay stays elsewhere; this owns only
+ * the spawn-integrate-fade lifecycle.
+ *
+ * @capability particle-system deterministic pooled particle emitter with SoA render buffers, burst/continuous emission, gravity/drag, size/color/alpha-over-life, and serializable state
+ */
+export declare function createParticleSystem(config?: EmitterConfig): ParticleSystem;

package/dist/vfx/particles.js

@@ -0,0 +1,256 @@
+import { hashString, randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * A generic, allocation-aware particle system: one emitter, a fixed pool, and
+ * Structure-of-Arrays buffers a renderer uploads straight to the GPU. It is
+ * dt-driven (call `update(dt)` each frame) and deterministic — all randomness
+ * flows from an injected `seed`, so the same seed and dt sequence reproduce the
+ * same frames, and `snapshot`/`restore` round-trips the live pool. Nothing here
+ * is combat- or genre-specific: configure it for smoke, sparks, rain, dust,
+ * embers, magic, or confetti. Travel/gameplay stays elsewhere; this owns only
+ * the spawn-integrate-fade lifecycle.
+ *
+ * @capability particle-system deterministic pooled particle emitter with SoA render buffers, burst/continuous emission, gravity/drag, size/color/alpha-over-life, and serializable state
+ */
+export function createParticleSystem(config = {}) {
+    const cfg = {
+        max: config.max ?? 512,
+        rate: config.rate ?? 0,
+        position: config.position ?? [0, 0, 0],
+        spawnJitter: config.spawnJitter ?? [0, 0, 0],
+        lifetime: config.lifetime ?? { min: 1, max: 1 },
+        speed: config.speed ?? { min: 1, max: 1 },
+        direction: config.direction ?? [0, 1, 0],
+        spread: config.spread ?? 0,
+        gravity: config.gravity ?? [0, 0, 0],
+        drag: config.drag ?? 0,
+        size: config.size ?? { start: 1, end: 1 },
+        colorStart: config.colorStart ?? 0xffffff,
+        colorEnd: config.colorEnd ?? config.colorStart ?? 0xffffff,
+        alpha: config.alpha ?? { start: 1, end: 0 },
+    };
+    const max = Math.max(1, Math.floor(cfg.max));
+    // SoA live pool.
+    const px = new Float32Array(max);
+    const py = new Float32Array(max);
+    const pz = new Float32Array(max);
+    const vx = new Float32Array(max);
+    const vy = new Float32Array(max);
+    const vz = new Float32Array(max);
+    const age = new Float32Array(max);
+    const life = new Float32Array(max);
+    // Per-particle baked endpoints (so mid-flight config changes don't recolor existing particles).
+    const sizeS = new Float32Array(max);
+    const sizeE = new Float32Array(max);
+    const r0 = new Float32Array(max);
+    const g0 = new Float32Array(max);
+    const b0 = new Float32Array(max);
+    const r1 = new Float32Array(max);
+    const g1 = new Float32Array(max);
+    const b1 = new Float32Array(max);
+    const a0 = new Float32Array(max);
+    const a1 = new Float32Array(max);
+    // Render buffers (rebuilt each frame from the live pool).
+    const outPos = new Float32Array(max * 3);
+    const outSize = new Float32Array(max);
+    const outColor = new Float32Array(max * 3);
+    const outAlpha = new Float32Array(max);
+    let live = 0;
+    let accumulator = 0;
+    let seed = randomSeedFrom(typeof config.seed === "number" ? config.seed : hashString(String(config.seed ?? "particles")));
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function rand() {
+        const [value, next] = stepRandomSeed(seed);
+        seed = next;
+        return value;
+    }
+    function range(r) {
+        return r.min + (r.max - r.min) * rand();
+    }
+    function unpackColor(rgb) {
+        return [((rgb >> 16) & 0xff) / 255, ((rgb >> 8) & 0xff) / 255, (rgb & 0xff) / 255];
+    }
+    function spawnOne() {
+        if (live >= max)
+            return;
+        const i = live++;
+        const [cr0, cg0, cb0] = unpackColor(cfg.colorStart);
+        const [cr1, cg1, cb1] = unpackColor(cfg.colorEnd);
+        px[i] = cfg.position[0] + (rand() * 2 - 1) * cfg.spawnJitter[0];
+        py[i] = cfg.position[1] + (rand() * 2 - 1) * cfg.spawnJitter[1];
+        pz[i] = cfg.position[2] + (rand() * 2 - 1) * cfg.spawnJitter[2];
+        // Direction: base dir perturbed within a cone of half-angle `spread`.
+        let dx = cfg.direction[0];
+        let dy = cfg.direction[1];
+        let dz = cfg.direction[2];
+        const dlen = Math.hypot(dx, dy, dz) || 1;
+        dx /= dlen;
+        dy /= dlen;
+        dz /= dlen;
+        if (cfg.spread > 0) {
+            // Sample a random unit vector, then blend toward the base direction by (1 - spread/π).
+            const theta = rand() * Math.PI * 2;
+            const z = rand() * 2 - 1;
+            const rxy = Math.sqrt(Math.max(0, 1 - z * z));
+            const sx = rxy * Math.cos(theta);
+            const sy = rxy * Math.sin(theta);
+            const sz = z;
+            const t = clamp01(cfg.spread / Math.PI);
+            dx = dx * (1 - t) + sx * t;
+            dy = dy * (1 - t) + sy * t;
+            dz = dz * (1 - t) + sz * t;
+            const n = Math.hypot(dx, dy, dz) || 1;
+            dx /= n;
+            dy /= n;
+            dz /= n;
+        }
+        const sp = range(cfg.speed);
+        vx[i] = dx * sp;
+        vy[i] = dy * sp;
+        vz[i] = dz * sp;
+        age[i] = 0;
+        life[i] = Math.max(0.0001, range(cfg.lifetime));
+        sizeS[i] = cfg.size.start;
+        sizeE[i] = cfg.size.end;
+        r0[i] = cr0;
+        g0[i] = cg0;
+        b0[i] = cb0;
+        r1[i] = cr1;
+        g1[i] = cg1;
+        b1[i] = cb1;
+        a0[i] = cfg.alpha.start;
+        a1[i] = cfg.alpha.end;
+    }
+    function swapRemove(i) {
+        const last = live - 1;
+        if (i !== last) {
+            px[i] = px[last];
+            py[i] = py[last];
+            pz[i] = pz[last];
+            vx[i] = vx[last];
+            vy[i] = vy[last];
+            vz[i] = vz[last];
+            age[i] = age[last];
+            life[i] = life[last];
+            sizeS[i] = sizeS[last];
+            sizeE[i] = sizeE[last];
+            r0[i] = r0[last];
+            g0[i] = g0[last];
+            b0[i] = b0[last];
+            r1[i] = r1[last];
+            g1[i] = g1[last];
+            b1[i] = b1[last];
+            a0[i] = a0[last];
+            a1[i] = a1[last];
+        }
+        live--;
+    }
+    const system = {
+        update(dt) {
+            if (dt <= 0)
+                return;
+            const damp = cfg.drag > 0 ? Math.max(0, 1 - cfg.drag * dt) : 1;
+            // Integrate + reap (iterate backwards because we swap-remove).
+            for (let i = live - 1; i >= 0; i--) {
+                age[i] += dt;
+                if (age[i] >= life[i]) {
+                    swapRemove(i);
+                    continue;
+                }
+                vx[i] = (vx[i] + cfg.gravity[0] * dt) * damp;
+                vy[i] = (vy[i] + cfg.gravity[1] * dt) * damp;
+                vz[i] = (vz[i] + cfg.gravity[2] * dt) * damp;
+                px[i] += vx[i] * dt;
+                py[i] += vy[i] * dt;
+                pz[i] += vz[i] * dt;
+            }
+            // Continuous emission.
+            if (cfg.rate > 0) {
+                accumulator += cfg.rate * dt;
+                while (accumulator >= 1) {
+                    accumulator -= 1;
+                    spawnOne();
+                }
+            }
+            notify();
+        },
+        emit(n) {
+            const wanted = Math.max(0, Math.floor(n));
+            for (let k = 0; k < wanted; k++)
+                spawnOne();
+            notify();
+        },
+        count() {
+            return live;
+        },
+        buffers() {
+            for (let i = 0; i < live; i++) {
+                const t = clamp01(age[i] / life[i]);
+                outPos[i * 3] = px[i];
+                outPos[i * 3 + 1] = py[i];
+                outPos[i * 3 + 2] = pz[i];
+                outSize[i] = sizeS[i] + (sizeE[i] - sizeS[i]) * t;
+                outColor[i * 3] = r0[i] + (r1[i] - r0[i]) * t;
+                outColor[i * 3 + 1] = g0[i] + (g1[i] - g0[i]) * t;
+                outColor[i * 3 + 2] = b0[i] + (b1[i] - b0[i]) * t;
+                outAlpha[i] = a0[i] + (a1[i] - a0[i]) * t;
+            }
+            return { count: live, positions: outPos, sizes: outSize, colors: outColor, alphas: outAlpha };
+        },
+        clear() {
+            live = 0;
+            accumulator = 0;
+            notify();
+        },
+        configure(patch) {
+            Object.assign(cfg, patch);
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            const data = [];
+            for (let i = 0; i < live; i++) {
+                data.push(px[i], py[i], pz[i], vx[i], vy[i], vz[i], age[i], life[i], sizeS[i], sizeE[i], r0[i], g0[i], b0[i], r1[i], g1[i], b1[i], a0[i], a1[i]);
+            }
+            return { seed: seed, accumulator, count: live, data };
+        },
+        restore(snapshot) {
+            seed = randomSeedFrom(snapshot.seed);
+            accumulator = snapshot.accumulator;
+            live = Math.min(max, snapshot.count);
+            const stride = 18;
+            for (let i = 0; i < live; i++) {
+                const o = i * stride;
+                px[i] = snapshot.data[o];
+                py[i] = snapshot.data[o + 1];
+                pz[i] = snapshot.data[o + 2];
+                vx[i] = snapshot.data[o + 3];
+                vy[i] = snapshot.data[o + 4];
+                vz[i] = snapshot.data[o + 5];
+                age[i] = snapshot.data[o + 6];
+                life[i] = snapshot.data[o + 7];
+                sizeS[i] = snapshot.data[o + 8];
+                sizeE[i] = snapshot.data[o + 9];
+                r0[i] = snapshot.data[o + 10];
+                g0[i] = snapshot.data[o + 11];
+                b0[i] = snapshot.data[o + 12];
+                r1[i] = snapshot.data[o + 13];
+                g1[i] = snapshot.data[o + 14];
+                b1[i] = snapshot.data[o + 15];
+                a0[i] = snapshot.data[o + 16];
+                a1[i] = snapshot.data[o + 17];
+            }
+            notify();
+        },
+    };
+    return system;
+}

package/dist/vfx/screenEffects.d.ts

@@ -0,0 +1,149 @@
+/** How a transient effect's intensity curves from peak to zero over its life. */
+export type ScreenEffectEasing = "linear" | "easeIn" | "easeOut" | "easeInOut";
+/**
+ * The screen region an effect tints. `"full"` grades the whole frame (a flash);
+ * `"vignette"` grades only the edges, leaving the center clear (a directional or
+ * ambient border tint). Purely a shape hint for the renderer — no genre meaning.
+ */
+export type ScreenEffectShape = "full" | "vignette";
+/**
+ * One screen-feedback effect, fully data-first so a whole controller serializes.
+ * `kind` is a free label the game assigns and styles ("damage", "heal", "poison",
+ * "boost", …); the model never interprets it. Everything visible is a parameter:
+ * color, peak intensity, region shape, easing, and either a transient duration or
+ * a sustained (optionally oscillating) hold.
+ */
+export interface ScreenEffectSpec {
+    /** Free-string label the game owns; the model treats it as opaque. */
+    kind: string;
+    /** CSS color the region is tinted with (e.g. `"#ff2b2b"`, `"rgb(80,200,120)"`). */
+    color: string;
+    /** Peak opacity `0..1` at full strength. Default `1`. */
+    intensity?: number;
+    /** Which region is tinted. Default `"full"`. */
+    shape?: ScreenEffectShape;
+    /** Intensity curve for a transient effect. Default `"easeOut"`. */
+    easing?: ScreenEffectEasing;
+    /**
+     * Lifetime in ms for a transient effect (ignored when `sustained`). The effect
+     * peaks immediately and eases to zero over this window. Default `400`.
+     */
+    durationMs?: number;
+    /**
+     * When true the effect holds until {@link ScreenEffectsController.clear} instead
+     * of expiring — a low-health tint, a status aura. Default `false`.
+     */
+    sustained?: boolean;
+    /**
+     * Oscillation frequency in Hz for a sustained effect (a pulse). `0` holds steady
+     * at `intensity`; `>0` breathes between `minIntensity` and `intensity`. Ignored
+     * for transient effects. Default `0`.
+     */
+    pulseHz?: number;
+    /** Trough opacity `0..1` a pulsing sustained effect dips to. Default `0`. */
+    minIntensity?: number;
+}
+/**
+ * A live effect in the current composite: its label, color, region, and the
+ * eased opacity `0..1` to draw *right now*. These objects are pooled and reused
+ * across {@link ScreenEffectsController.composite} calls — read them, don't retain.
+ */
+export interface ScreenEffect {
+    /** Stable id assigned at trigger time (use it to {@link ScreenEffectsController.clear}). */
+    id: number;
+    /** The game-owned label from the spec. */
+    kind: string;
+    /** CSS color to tint with. */
+    color: string;
+    /** Region to tint. */
+    shape: ScreenEffectShape;
+    /** Current eased opacity `0..1`. */
+    intensity: number;
+}
+/** A persisted effect record (all spec fields resolved plus its start time and id). */
+export interface StoredScreenEffect {
+    id: number;
+    kind: string;
+    color: string;
+    shape: ScreenEffectShape;
+    easing: ScreenEffectEasing;
+    intensity: number;
+    durationMs: number;
+    sustained: boolean;
+    pulseHz: number;
+    minIntensity: number;
+    /** Clock time (ms) the effect started, for elapsed-time evaluation. */
+    startAt: number;
+}
+/** Serializable state of every active effect, for save/restore and replay. */
+export interface ScreenEffectsSnapshot {
+    /** Wall-clock (ms) the snapshot was taken, so restore re-anchors elapsed time. */
+    now: number;
+    /** Next id to hand out. */
+    nextId: number;
+    /** Every active effect, transient and sustained. */
+    effects: readonly StoredScreenEffect[];
+}
+/** A live, clock-driven screen-feedback controller. */
+export interface ScreenEffectsController {
+    /**
+     * Trigger a transient full-screen flash. Convenience for {@link trigger} with
+     * `shape: "full"`. Returns the new effect id.
+     */
+    flash(kind: string, spec: Omit<ScreenEffectSpec, "kind" | "shape" | "sustained">): number;
+    /**
+     * Trigger a transient edge vignette. Convenience for {@link trigger} with
+     * `shape: "vignette"`. Returns the new effect id.
+     */
+    vignette(kind: string, spec: Omit<ScreenEffectSpec, "kind" | "shape" | "sustained">): number;
+    /**
+     * Start a sustained pulse that holds until {@link clear}. Convenience for a
+     * sustained effect; pass `pulseHz > 0` to breathe. Returns the new effect id.
+     */
+    pulse(kind: string, spec: Omit<ScreenEffectSpec, "kind" | "sustained">): number;
+    /** Trigger any effect from a full spec. Returns the new effect id. */
+    trigger(spec: ScreenEffectSpec): number;
+    /** Remove one effect by id (typically a sustained one). No-op if unknown. */
+    clear(id: number): void;
+    /** Remove every active effect. */
+    clearAll(): void;
+    /**
+     * Re-evaluate every effect against the clock: recompute eased intensities, reap
+     * expired transients, and notify subscribers. Allocation-free on the hot path.
+     * Pass an explicit `nowMs` to drive deterministically, else the injected clock.
+     */
+    advance(nowMs?: number): void;
+    /**
+     * The current composite: active effects with their eased `intensity`. The array
+     * and its entries are pooled and overwritten on the next call — do not retain.
+     */
+    composite(): readonly ScreenEffect[];
+    /** Number of active effects. */
+    active(): number;
+    /** Observe changes (trigger, clear, advance). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): ScreenEffectsSnapshot;
+    /** Restore from a {@link ScreenEffectsSnapshot}. */
+    restore(snapshot: ScreenEffectsSnapshot): void;
+}
+/** Options for {@link createScreenEffects}. */
+export interface ScreenEffectsOptions {
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * A serializable screen-feedback controller: a game triggers transient flashes and
+ * edge vignettes (a red damage hit, a green heal flash) or sustained, optionally
+ * oscillating tints (a low-health pulse), and reads back a composite of the effects
+ * to draw right now with their eased opacities. It is clock-driven — call
+ * `advance()` each frame against an injected `now` — and allocation-aware: the
+ * composite array and its entries are pooled and reused, so steady-state ticking
+ * never allocates. Nothing here is genre-specific: `kind` is a free label the game
+ * owns and styles, and vignette / flash / pulse are just parameterizations of the
+ * same data (region shape, decay easing, sustained oscillation). A shell overlay
+ * subscribes and renders; `snapshot`/`restore` round-trips through a save.
+ *
+ * @capability screen-effects serializable, pooled screen-feedback controller — transient flash/vignette and sustained low-health-style pulses with eased opacities, free-string kinds the game styles, and snapshot/restore
+ */
+export declare function createScreenEffects(options?: ScreenEffectsOptions): ScreenEffectsController;