@jgengine/core 0.14.0 → 0.15.0

package/dist/time/dayNightCycle.js

@@ -0,0 +1,208 @@
+/**
+ * Turnkey day-night cycle: one serializable brain that advances a normalized day
+ * fraction on an injected clock and blends per-keyframe phase labels and tint/light
+ * colors. A game wires this one model and drives an existing sky/daylight seam from
+ * `sample()` instead of hand-rolling a clock plus a color lerp.
+ *
+ * The model is genre-agnostic: `phase` labels and colors are free-form values the
+ * game styles. The model never branches on what a phase string "means" — it only
+ * interpolates between the keyframes you give it.
+ */
+/** Clamp a number into [0,1]. */
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/** Wrap a number into [0,1), so `-0.1` → `0.9` and `1.2` → `0.2`. */
+function wrap01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return ((value % 1) + 1) % 1;
+}
+/** Linear interpolation between `a` and `b` by `t`. */
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/** Parse `"#rrggbb"` (or `"rrggbb"`) into an `[r,g,b]` byte triple. */
+function hexToRgb(hex) {
+    const clean = hex.startsWith("#") ? hex.slice(1) : hex;
+    const value = Number.parseInt(clean, 16);
+    return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+}
+/** Clamp and round a channel into a 0-255 byte. */
+function clampByte(value) {
+    return Math.max(0, Math.min(255, Math.round(value)));
+}
+/** Encode an `[r,g,b]` triple back into `"#rrggbb"`. */
+function rgbToHex(rgb) {
+    return `#${rgb.map((channel) => clampByte(channel).toString(16).padStart(2, "0")).join("")}`;
+}
+/** Interpolate two `"#rrggbb"` colors in RGB space by `t`. */
+function lerpHex(a, b, t) {
+    const [ar, ag, ab] = hexToRgb(a);
+    const [br, bg, bb] = hexToRgb(b);
+    return rgbToHex([lerp(ar, br, t), lerp(ag, bg, t), lerp(ab, bb, t)]);
+}
+/** Sanitize a positive finite number, falling back to `fallback`. */
+function positiveOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+/** Sort keyframes by wrapped `at` and fill in color/intensity fallbacks; never mutates the input. */
+function normalizeKeyframes(keyframes) {
+    if (keyframes.length === 0) {
+        throw new Error("createDayNightCycle requires at least one keyframe");
+    }
+    return keyframes
+        .map((keyframe) => ({
+        at: wrap01(keyframe.at),
+        phase: keyframe.phase,
+        color: keyframe.color,
+        lightColor: keyframe.lightColor ?? keyframe.color,
+        intensity: keyframe.intensity ?? 1,
+    }))
+        .sort((a, b) => a.at - b.at);
+}
+/** Blend the normalized keyframe ring at a wrapped day fraction. */
+function sampleKeyframes(sorted, fraction) {
+    const dayFraction = wrap01(fraction);
+    if (sorted.length === 1) {
+        const only = sorted[0];
+        return { dayFraction, phase: only.phase, color: only.color, lightColor: only.lightColor, intensity: only.intensity };
+    }
+    // Find the last keyframe at or before the fraction; the following one (wrapping past
+    // 1.0 back to the first) is the segment we interpolate across.
+    let fromIndex = sorted.length - 1;
+    for (let index = 0; index < sorted.length; index += 1) {
+        if (sorted[index].at <= dayFraction)
+            fromIndex = index;
+        else
+            break;
+    }
+    const from = sorted[fromIndex];
+    const to = sorted[(fromIndex + 1) % sorted.length];
+    const span = (to.at - from.at + 1) % 1;
+    const localRaw = (dayFraction - from.at + 1) % 1;
+    const localT = span <= 0 ? 0 : clamp01(localRaw / span);
+    return {
+        dayFraction,
+        phase: from.phase,
+        color: lerpHex(from.color, to.color, localT),
+        lightColor: lerpHex(from.lightColor, to.lightColor, localT),
+        intensity: lerp(from.intensity, to.intensity, localT),
+    };
+}
+/**
+ * Creates a turnkey day-night cycle: a serializable model that advances a normalized
+ * day fraction on an injected clock and blends per-keyframe phase labels and tint/light
+ * colors. Wire this one model, then drive an existing sky/daylight seam from `sample()`
+ * (or drop it straight into a `{ calendar(): { dayFraction } }` seam via `calendar()`)
+ * to get a moving day-night cycle with color grading — no hand-rolled clock or lerp.
+ * `phase` labels and colors are free-form; the model never interprets their meaning.
+ *
+ * @capability day-night-cycle one wired model gives a moving day-night cycle — running clock plus keyframed phase labels and tint/light colors a game drives an existing sky/daylight seam from
+ */
+export function createDayNightCycle(options) {
+    const sorted = normalizeKeyframes(options.keyframes);
+    const keyframes = sorted.map((keyframe) => ({ ...keyframe }));
+    const dayLengthMs = positiveOr(options.dayLengthMs, 120_000);
+    const now = options.now ?? Date.now;
+    const listeners = new Set();
+    let elapsedMs = wrap01(options.start ?? 0) * dayLengthMs;
+    let paused = options.startPaused ?? false;
+    let speed = positiveOr(options.speed, 1);
+    let anchor = now();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Accrue elapsed game-time from the injected clock since the last sync, then re-anchor. */
+    function sync() {
+        const t = now();
+        if (!paused)
+            elapsedMs += Math.max(0, t - anchor) * speed;
+        anchor = t;
+    }
+    function dayFraction() {
+        sync();
+        return wrap01(elapsedMs / dayLengthMs);
+    }
+    return {
+        keyframes,
+        dayLengthMs,
+        dayFraction,
+        phase() {
+            return sampleKeyframes(sorted, dayFraction()).phase;
+        },
+        sample() {
+            return sampleKeyframes(sorted, dayFraction());
+        },
+        sampleAt(fraction) {
+            return sampleKeyframes(sorted, fraction);
+        },
+        calendar() {
+            return { dayFraction: dayFraction() };
+        },
+        setDayFraction(fraction) {
+            sync();
+            elapsedMs = wrap01(fraction) * dayLengthMs;
+            notify();
+        },
+        isPaused() {
+            return paused;
+        },
+        pause() {
+            if (paused)
+                return;
+            sync();
+            paused = true;
+            notify();
+        },
+        play() {
+            if (!paused)
+                return;
+            sync();
+            paused = false;
+            notify();
+        },
+        toggle() {
+            if (paused)
+                this.play();
+            else
+                this.pause();
+        },
+        speed() {
+            return speed;
+        },
+        setSpeed(multiplier) {
+            sync();
+            if (!Number.isFinite(multiplier) || multiplier <= 0) {
+                if (!paused) {
+                    paused = true;
+                    notify();
+                }
+                return;
+            }
+            const changed = paused || multiplier !== speed;
+            speed = multiplier;
+            paused = false;
+            if (changed)
+                notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        snapshot() {
+            sync();
+            return { elapsedMs, paused, speed };
+        },
+        restore(snapshot) {
+            elapsedMs = Number.isFinite(snapshot.elapsedMs) ? snapshot.elapsedMs : 0;
+            paused = snapshot.paused;
+            speed = positiveOr(snapshot.speed, 1);
+            anchor = now();
+            notify();
+        },
+    };
+}

package/dist/time/timerSet.d.ts

@@ -0,0 +1,132 @@
+/**
+ * A serializable set of named countdown / countup timers evaluated against an
+ * injected clock. One primitive covers round timers, respawn clocks, and ability
+ * cooldown/charge — they are the same mechanic (elapsed vs. duration on a clock),
+ * so `id` and any labels are free strings the engine never interprets.
+ *
+ * No hidden interval math: the set stores only accumulated elapsed time plus a
+ * clock anchor while running, and derives every read on demand. `subscribe`
+ * reports structural changes (start/pause/stop/reset); `poll` reports expiry
+ * edges so a game can react (respawn, round end, ability ready). `snapshot` /
+ * `restore` round-trip through a save by resolving elapsed at snapshot time and
+ * re-anchoring on restore, so pause/resume survives serialization.
+ */
+/** Direction a timer counts. `"down"` leads with `remainingMs` (countdown); `"up"` leads with `elapsedMs` (charge). */
+export type TimerDirection = "down" | "up";
+/** Options for {@link TimerSet.start}. */
+export interface TimerStartOptions {
+    /** Full span of the timer in milliseconds. Non-positive spans read as instantly expired. */
+    durationMs: number;
+    /** Count direction. Default `"down"`. Purely a read convenience — expiry is the same either way. */
+    direction?: TimerDirection;
+    /** When true the timer wraps at its duration and emits an expiry edge each cycle instead of stopping. Default `false`. */
+    loop?: boolean;
+}
+/**
+ * A single timer's resolved state for one read. All fields are plain numbers so
+ * a HUD can render without touching the model. For a looping timer the values
+ * describe the current cycle; `expired` is only ever `true` for a finished
+ * non-looping timer (loops signal completion through {@link TimerSet.poll}).
+ */
+export interface TimerRead {
+    /** The timer's id (free string). */
+    id: string;
+    /** The configured count direction — lets a readout auto-pick remaining (`"down"`) vs elapsed (`"up"`). */
+    direction: TimerDirection;
+    /** Milliseconds left in this cycle, clamped to `0`. */
+    remainingMs: number;
+    /** Milliseconds elapsed in this cycle, clamped to `durationMs`. */
+    elapsedMs: number;
+    /** The configured span in milliseconds. */
+    durationMs: number;
+    /** Fill fraction `0..1` = `elapsedMs / durationMs` — a ring or bar fills as time passes. */
+    progress01: number;
+    /** Whether the timer is counting (not paused/stopped). */
+    running: boolean;
+    /** True once a non-looping timer has reached its duration. Always `false` for a looping timer. */
+    expired: boolean;
+}
+/** One timer's serializable state — elapsed resolved at snapshot time, ready to re-anchor on restore. */
+export interface TimerSnapshot {
+    id: string;
+    durationMs: number;
+    direction: TimerDirection;
+    loop: boolean;
+    /** Elapsed milliseconds at the moment of the snapshot. */
+    elapsedMs: number;
+    running: boolean;
+    /** Whether this non-looping timer had already emitted its expiry edge. */
+    fired: boolean;
+}
+/** Serializable state of a whole {@link TimerSet}. */
+export interface TimerSetSnapshot {
+    timers: TimerSnapshot[];
+}
+/** Options for {@link createTimerSet}. */
+export interface TimerSetOptions {
+    /** Injected clock (ms). Default `Date.now`. Inject a sim clock for determinism. */
+    now?: () => number;
+}
+/** Listener notified when a timer newly expires. Receives the timer id. */
+export type TimerExpiryListener = (id: string) => void;
+/**
+ * A named set of countdown / countup timers on an injected clock. Start, pause,
+ * resume, stop, reset, and read timers by free-string id; observe structural
+ * changes with {@link TimerSet.subscribe} and expiry edges with
+ * {@link TimerSet.poll} / {@link TimerSet.onExpire}.
+ */
+export interface TimerSet {
+    /** Start (or replace) a timer by id, running from zero. */
+    start(id: string, options: TimerStartOptions): void;
+    /** Pause a running timer, freezing its elapsed time. No-op if unknown or already paused. */
+    pause(id: string): void;
+    /** Resume a paused timer from where it stopped. No-op if unknown or already running. */
+    resume(id: string): void;
+    /** Halt a timer and reset its elapsed time to zero, keeping it in the set (not running). */
+    stop(id: string): void;
+    /** Restart a timer's elapsed time from zero, preserving its running state. */
+    reset(id: string): void;
+    /** Remove a timer from the set entirely. */
+    remove(id: string): void;
+    /** Pause every running timer (e.g. a global game pause). */
+    pauseAll(): void;
+    /** Resume every paused timer. */
+    resumeAll(): void;
+    /** Whether a timer with this id exists. */
+    has(id: string): boolean;
+    /** Every timer id currently in the set. */
+    ids(): readonly string[];
+    /**
+     * Resolve a timer's current state. Pass `out` to reuse an object and avoid
+     * per-read allocation in a hot HUD loop. Returns `null` for an unknown id.
+     */
+    read(id: string, out?: TimerRead): TimerRead | null;
+    /** Resolve every timer, newest reads. Allocates an array — for per-frame reads prefer {@link TimerSet.read} with `out`. */
+    list(): TimerRead[];
+    /**
+     * Advance expiry detection to the current clock time and return the ids that
+     * newly expired since the last poll (firing {@link TimerSet.onExpire}
+     * listeners for each). Looping timers report once per completed cycle. Call
+     * once per frame/tick to react to finished timers.
+     */
+    poll(): readonly string[];
+    /** Observe structural changes (start/pause/resume/stop/reset/remove/restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Observe expiry edges surfaced by {@link TimerSet.poll}. Returns an unsubscribe fn. */
+    onExpire(listener: TimerExpiryListener): () => void;
+    /** Serializable state for a save. */
+    snapshot(): TimerSetSnapshot;
+    /** Restore from a {@link TimerSetSnapshot}, re-anchoring running timers to the current clock. */
+    restore(snapshot: TimerSetSnapshot): void;
+}
+/**
+ * Create a serializable set of named countdown / countup timers on an injected
+ * clock — one primitive for round timers, respawn clocks, and ability
+ * cooldown/charge. Start/pause/resume/stop/reset timers by free-string id, read
+ * `{ remainingMs, elapsedMs, durationMs, progress01, running, expired }` for a
+ * mm:ss readout or a radial/bar fill, and `poll` for expiry edges. Ids and
+ * labels carry no genre meaning; `snapshot`/`restore` round-trip through a save.
+ *
+ * @capability countdown-timers named countdown/countup timer set on an injected clock — round timers, respawn clocks, ability cooldown/charge; read remaining/elapsed/progress + expiry, snapshot/restore
+ */
+export declare function createTimerSet(options?: TimerSetOptions): TimerSet;

package/dist/time/timerSet.js

@@ -0,0 +1,243 @@
+/**
+ * A serializable set of named countdown / countup timers evaluated against an
+ * injected clock. One primitive covers round timers, respawn clocks, and ability
+ * cooldown/charge — they are the same mechanic (elapsed vs. duration on a clock),
+ * so `id` and any labels are free strings the engine never interprets.
+ *
+ * No hidden interval math: the set stores only accumulated elapsed time plus a
+ * clock anchor while running, and derives every read on demand. `subscribe`
+ * reports structural changes (start/pause/stop/reset); `poll` reports expiry
+ * edges so a game can react (respawn, round end, ability ready). `snapshot` /
+ * `restore` round-trip through a save by resolving elapsed at snapshot time and
+ * re-anchoring on restore, so pause/resume survives serialization.
+ */
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+function rawElapsed(rec, t) {
+    const live = rec.running ? Math.max(0, t - rec.anchor) : 0;
+    return rec.base + live;
+}
+/**
+ * Create a serializable set of named countdown / countup timers on an injected
+ * clock — one primitive for round timers, respawn clocks, and ability
+ * cooldown/charge. Start/pause/resume/stop/reset timers by free-string id, read
+ * `{ remainingMs, elapsedMs, durationMs, progress01, running, expired }` for a
+ * mm:ss readout or a radial/bar fill, and `poll` for expiry edges. Ids and
+ * labels carry no genre meaning; `snapshot`/`restore` round-trip through a save.
+ *
+ * @capability countdown-timers named countdown/countup timer set on an injected clock — round timers, respawn clocks, ability cooldown/charge; read remaining/elapsed/progress + expiry, snapshot/restore
+ */
+export function createTimerSet(options = {}) {
+    const now = options.now ?? Date.now;
+    const timers = new Map();
+    const listeners = new Set();
+    const expiryListeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function completedCycles(rec, t) {
+        if (rec.durationMs <= 0)
+            return rec.loop ? 0 : 1;
+        const raw = rawElapsed(rec, t);
+        if (rec.loop)
+            return Math.floor(raw / rec.durationMs);
+        return raw >= rec.durationMs ? 1 : 0;
+    }
+    function fill(rec, t, out) {
+        const duration = rec.durationMs;
+        const raw = rawElapsed(rec, t);
+        let cycleElapsed;
+        let expired;
+        if (duration <= 0) {
+            cycleElapsed = 0;
+            expired = !rec.loop;
+        }
+        else if (rec.loop) {
+            cycleElapsed = raw % duration;
+            expired = false;
+        }
+        else {
+            cycleElapsed = raw < duration ? raw : duration;
+            expired = raw >= duration;
+        }
+        out.id = rec.id;
+        out.direction = rec.direction;
+        out.durationMs = duration;
+        out.elapsedMs = cycleElapsed;
+        out.remainingMs = duration > 0 ? duration - cycleElapsed : 0;
+        out.progress01 = duration > 0 ? clamp01(cycleElapsed / duration) : 1;
+        out.running = rec.running;
+        out.expired = expired;
+        return out;
+    }
+    function blankRead() {
+        return {
+            id: "",
+            direction: "down",
+            remainingMs: 0,
+            elapsedMs: 0,
+            durationMs: 0,
+            progress01: 0,
+            running: false,
+            expired: false,
+        };
+    }
+    return {
+        start(id, startOptions) {
+            timers.set(id, {
+                id,
+                durationMs: startOptions.durationMs,
+                direction: startOptions.direction ?? "down",
+                loop: startOptions.loop ?? false,
+                base: 0,
+                running: true,
+                anchor: now(),
+                reported: 0,
+            });
+            notify();
+        },
+        pause(id) {
+            const rec = timers.get(id);
+            if (rec === undefined || !rec.running)
+                return;
+            rec.base = rawElapsed(rec, now());
+            rec.running = false;
+            notify();
+        },
+        resume(id) {
+            const rec = timers.get(id);
+            if (rec === undefined || rec.running)
+                return;
+            rec.anchor = now();
+            rec.running = true;
+            notify();
+        },
+        stop(id) {
+            const rec = timers.get(id);
+            if (rec === undefined)
+                return;
+            rec.base = 0;
+            rec.running = false;
+            rec.reported = 0;
+            notify();
+        },
+        reset(id) {
+            const rec = timers.get(id);
+            if (rec === undefined)
+                return;
+            rec.base = 0;
+            rec.anchor = now();
+            rec.reported = 0;
+            notify();
+        },
+        remove(id) {
+            if (timers.delete(id))
+                notify();
+        },
+        pauseAll() {
+            const t = now();
+            let changed = false;
+            for (const rec of timers.values()) {
+                if (rec.running) {
+                    rec.base = rawElapsed(rec, t);
+                    rec.running = false;
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        resumeAll() {
+            const t = now();
+            let changed = false;
+            for (const rec of timers.values()) {
+                if (!rec.running) {
+                    rec.anchor = t;
+                    rec.running = true;
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        has(id) {
+            return timers.has(id);
+        },
+        ids() {
+            return [...timers.keys()];
+        },
+        read(id, out) {
+            const rec = timers.get(id);
+            if (rec === undefined)
+                return null;
+            return fill(rec, now(), out ?? blankRead());
+        },
+        list() {
+            const t = now();
+            const reads = [];
+            for (const rec of timers.values())
+                reads.push(fill(rec, t, blankRead()));
+            return reads;
+        },
+        poll() {
+            const t = now();
+            const fired = [];
+            for (const rec of timers.values()) {
+                const cycles = completedCycles(rec, t);
+                if (cycles > rec.reported) {
+                    const times = cycles - rec.reported;
+                    rec.reported = cycles;
+                    for (let i = 0; i < times; i += 1) {
+                        fired.push(rec.id);
+                        for (const listener of expiryListeners)
+                            listener(rec.id);
+                    }
+                }
+            }
+            return fired;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        onExpire(listener) {
+            expiryListeners.add(listener);
+            return () => expiryListeners.delete(listener);
+        },
+        snapshot() {
+            const t = now();
+            const out = [];
+            for (const rec of timers.values()) {
+                out.push({
+                    id: rec.id,
+                    durationMs: rec.durationMs,
+                    direction: rec.direction,
+                    loop: rec.loop,
+                    elapsedMs: rawElapsed(rec, t),
+                    running: rec.running,
+                    fired: rec.reported > 0,
+                });
+            }
+            return { timers: out };
+        },
+        restore(snapshot) {
+            timers.clear();
+            const t = now();
+            for (const snap of snapshot.timers) {
+                timers.set(snap.id, {
+                    id: snap.id,
+                    durationMs: snap.durationMs,
+                    direction: snap.direction,
+                    loop: snap.loop,
+                    base: snap.elapsedMs,
+                    running: snap.running,
+                    anchor: t,
+                    reported: snap.fired ? 1 : 0,
+                });
+            }
+            notify();
+        },
+    };
+}

package/dist/ui/accessibility.d.ts

@@ -0,0 +1,51 @@
+/** Colorblind simulation/daltonization modes the engine ships matrices for. */
+export type ColorblindMode = "none" | "protanopia" | "deuteranopia" | "tritanopia" | "grayscale";
+/** Serializable accessibility preferences a game reads to adapt its presentation. */
+export interface AccessibilityState {
+    /** Suppress non-essential motion/animation. */
+    reducedMotion: boolean;
+    /** Boost contrast (stronger borders/backgrounds, less transparency). */
+    highContrast: boolean;
+    /** UI text scale multiplier (`1` = default). See {@link clampTextScale} for bounds. */
+    textScale: number;
+    /** Colorblind filter applied to the presentation. */
+    colorblind: ColorblindMode;
+    /** Show subtitles/captions for dialogue and important audio. */
+    captions: boolean;
+}
+/** The out-of-the-box accessibility state (all assistance off, `textScale` 1). */
+export declare const DEFAULT_ACCESSIBILITY: AccessibilityState;
+/** Minimum UI text scale. */
+export declare const TEXT_SCALE_MIN = 0.75;
+/** Maximum UI text scale. */
+export declare const TEXT_SCALE_MAX = 2;
+/** Clamp a text-scale multiplier into the supported `[TEXT_SCALE_MIN, TEXT_SCALE_MAX]` range. */
+export declare function clampTextScale(scale: number): number;
+/** Return `ms` when motion is allowed, or `reduced` (default 0) when `reducedMotion` is set — the animation-duration gate. */
+export declare function reducedMotionDuration(state: AccessibilityState, ms: number, reduced?: number): number;
+/**
+ * `feColorMatrix` `values` strings for each colorblind mode — simulate how a
+ * viewer with that condition perceives color (and a grayscale mode). `"none"`
+ * maps to `null` (no filter). Consumed by the React `ColorblindFilters` defs.
+ */
+export declare const COLORBLIND_MATRICES: Record<ColorblindMode, string | null>;
+/** Observable, serializable accessibility-preferences store. */
+export interface AccessibilityStore {
+    get(): AccessibilityState;
+    /** Merge a partial update (text scale is clamped); notifies on an actual change. */
+    set(patch: Partial<AccessibilityState>): void;
+    /** Restore defaults. */
+    reset(): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): AccessibilityState;
+    restore(snapshot: Partial<AccessibilityState>): void;
+}
+/**
+ * Serializable, observable store of accessibility preferences (reduced motion,
+ * high contrast, text scale, colorblind mode, captions). Genre-agnostic plumbing
+ * like input rebinding — a game binds these to its settings UI and adapts its
+ * presentation; `snapshot`/`restore` round-trip through a save or settings blob.
+ *
+ * @capability accessibility-store serializable, observable accessibility preferences (reduced motion, high contrast, text scale, colorblind mode, captions) a game binds to its settings and presentation
+ */
+export declare function createAccessibilityStore(initial?: Partial<AccessibilityState>): AccessibilityStore;