@jgengine/core 0.7.0 → 0.9.0

package/dist/session/roundState.d.ts

@@ -1,4 +1,5 @@
-export type RoundPhase = "buy" | "live" | "end";
+export type RoundPhase = string;
+/** Default phase-duration shape for the built-in buy/live/end cycle; pass a wider `Record<string, number>` when using a custom `phaseOrder`. */
 export interface RoundPhaseDurations {
     buy: number;
     live: number;
@@ -9,9 +10,24 @@ export interface LossBonusRule {
     step: number;
     max: number;
 }
-export interface RoundConfig {
-    phases: RoundPhaseDurations;
-    teams: readonly string[];
+/** A team entry with an optional role tag (e.g. "attacker", "defender") retrievable via `RoundState.roleOf`. */
+export interface RoundTeam {
+    id: string;
+    role?: string;
+}
+export interface RoundConfig<TPhase extends string = RoundPhase> {
+    /** Duration in seconds for each phase name in `phaseOrder` (or the default `RoundPhaseDurations` shape). */
+    phases: Record<TPhase, number>;
+    teams: readonly string[] | readonly RoundTeam[];
+    /**
+     * Overrides the default `["buy", "live", "end"]` cycle. Phases other than the first and last are
+     * "conclude-eligible": `concludeRound`/`evaluate` may settle the round only while the current phase
+     * is neither the first nor the last entry, matching the original buy (no conclude) / live (conclude) /
+     * end (no conclude, settles the round) roles. The cycle wraps from the last entry back to the first.
+     */
+    phaseOrder?: readonly TPhase[];
+    /** Evaluated by `evaluate()`; returning a team id concludes the round with that team as winner. */
+    winCondition?: (state: RoundSnapshot<TPhase>) => string | null;
     maxRounds?: number;
     winReward?: number;
     lossBonus?: LossBonusRule;
@@ -23,33 +39,41 @@ export interface RoundEconomy {
     won: boolean;
     lossStreak: number;
 }
-export interface RoundEvent {
+export interface RoundEvent<TPhase extends string = RoundPhase> {
     kind: RoundEventKind;
     round: number;
-    phase?: RoundPhase;
-    nextPhase?: RoundPhase;
+    phase?: TPhase;
+    nextPhase?: TPhase;
     winner?: string;
     economy?: RoundEconomy[];
 }
-export type PhaseEndHook = (endingPhase: RoundPhase, nextPhase: RoundPhase, round: number) => void;
-export interface RoundSnapshot {
+export type PhaseEndHook<TPhase extends string = RoundPhase> = (endingPhase: TPhase, nextPhase: TPhase, round: number) => void;
+export interface RoundSnapshot<TPhase extends string = RoundPhase> {
     round: number;
-    phase: RoundPhase;
+    phase: TPhase;
     timeLeft: number;
     scores: Record<string, number>;
     lossStreaks: Record<string, number>;
+    roles: Record<string, string | undefined>;
     matchOver: boolean;
 }
-export interface RoundState {
-    tick(dt: number): RoundEvent[];
-    concludeRound(winner: string): RoundEvent[];
-    onPhaseEnd(hook: PhaseEndHook): () => void;
-    phase(): RoundPhase;
+export interface RoundState<TPhase extends string = RoundPhase> {
+    tick(dt: number): RoundEvent<TPhase>[];
+    concludeRound(winner: string): RoundEvent<TPhase>[];
+    /** Calls `RoundConfig.winCondition` (a no-op when absent) and concludes the round if it returns a team id. */
+    evaluate(): RoundEvent<TPhase>[];
+    onPhaseEnd(hook: PhaseEndHook<TPhase>): () => void;
+    phase(): TPhase;
     round(): number;
     timeLeft(): number;
     score(team: string): number;
     economyFor(team: string): RoundEconomy;
-    snapshot(): RoundSnapshot;
+    /** The role tag configured for `team`, if any. */
+    roleOf(team: string): string | undefined;
+    snapshot(): RoundSnapshot<TPhase>;
 }
 export declare function lossBonusFor(rule: LossBonusRule | undefined, streak: number): number;
-export declare function createRoundState(config: RoundConfig): RoundState;
+export declare function createRoundState(config: RoundConfig<RoundPhase>): RoundState<RoundPhase>;
+export declare function createRoundState<TPhase extends string>(config: RoundConfig<TPhase> & {
+    phaseOrder: readonly TPhase[];
+}): RoundState<TPhase>;

package/dist/session/roundState.js

@@ -1,31 +1,47 @@
-const PHASE_ORDER = ["buy", "live", "end"];
+const DEFAULT_PHASE_ORDER = ["buy", "live", "end"];
 export function lossBonusFor(rule, streak) {
     if (rule === undefined)
         return 0;
     return Math.min(rule.max, rule.base + rule.step * Math.max(0, streak));
 }
+function normalizeTeams(teams) {
+    if (teams.length === 0)
+        return [{ id: "a" }, { id: "b" }];
+    const normalized = [];
+    for (const team of teams) {
+        normalized.push(typeof team === "string" ? { id: team } : team);
+    }
+    return normalized;
+}
+function isConcludable(order, phase) {
+    const idx = order.indexOf(phase);
+    return idx > 0 && idx < order.length - 1;
+}
 export function createRoundState(config) {
+    const order = config.phaseOrder ?? DEFAULT_PHASE_ORDER;
     const durations = config.phases;
-    const teams = config.teams.length > 0 ? [...config.teams] : ["a", "b"];
+    const teamRecords = normalizeTeams(config.teams);
+    const teamIds = teamRecords.map((t) => t.id);
+    const roles = {};
     const scores = {};
     const lossStreaks = {};
-    for (const team of teams) {
-        scores[team] = 0;
-        lossStreaks[team] = 0;
+    for (const team of teamRecords) {
+        roles[team.id] = team.role;
+        scores[team.id] = 0;
+        lossStreaks[team.id] = 0;
     }
     let round = 1;
-    let phase = "buy";
-    let timeLeft = durations.buy;
+    let phase = order[0];
+    let timeLeft = durations[phase] ?? 0;
     let matchOver = false;
     let pendingWinner = null;
     const hooks = new Set();
     function durationOf(next) {
-        return durations[next];
+        return durations[next] ?? 0;
     }
     function nextPhaseOf(current) {
-        if (current === "end")
-            return "buy";
-        return PHASE_ORDER[PHASE_ORDER.indexOf(current) + 1];
+        const idx = order.indexOf(current);
+        return idx >= order.length - 1 ? order[0] : order[idx + 1];
     }
     function economyFor(team) {
         const won = pendingWinner === team;
@@ -38,12 +54,12 @@ export function createRoundState(config) {
     }
     function settleEconomy(winner) {
         const economy = [];
-        for (const team of teams) {
+        for (const team of teamIds) {
             const won = team === winner;
             const reward = won ? config.winReward ?? 0 : lossBonusFor(config.lossBonus, lossStreaks[team]);
             economy.push({ team, reward, won, lossStreak: lossStreaks[team] });
         }
-        for (const team of teams) {
+        for (const team of teamIds) {
             if (team === winner)
                 lossStreaks[team] = 0;
             else
@@ -58,24 +74,48 @@ export function createRoundState(config) {
     }
     function endPhase(events) {
         const ending = phase;
-        if (ending === "end") {
+        if (ending === order[order.length - 1]) {
             if (config.maxRounds !== undefined && round >= config.maxRounds) {
                 matchOver = true;
-                events.push({ kind: "phase.end", round, phase: ending, nextPhase: "buy" });
+                events.push({ kind: "phase.end", round, phase: ending, nextPhase: order[0] });
                 events.push({ kind: "match.end", round });
                 for (const hook of hooks)
-                    hook(ending, "buy", round);
+                    hook(ending, order[0], round);
                 return;
             }
             round += 1;
             pendingWinner = null;
         }
         const next = nextPhaseOf(ending);
-        events.push({ kind: "phase.end", round: ending === "end" ? round - 1 : round, phase: ending, nextPhase: next });
+        const endedRound = ending === order[order.length - 1] ? round - 1 : round;
+        events.push({ kind: "phase.end", round: endedRound, phase: ending, nextPhase: next });
         for (const hook of hooks)
-            hook(ending, next, ending === "end" ? round - 1 : round);
+            hook(ending, next, endedRound);
         enter(next, events);
     }
+    function currentSnapshot() {
+        return {
+            round,
+            phase,
+            timeLeft: Math.max(0, timeLeft),
+            scores: { ...scores },
+            lossStreaks: { ...lossStreaks },
+            roles: { ...roles },
+            matchOver,
+        };
+    }
+    function concludeRoundImpl(winner) {
+        if (matchOver || !isConcludable(order, phase))
+            return [];
+        const events = [];
+        pendingWinner = winner;
+        scores[winner] = (scores[winner] ?? 0) + 1;
+        events.push({ kind: "round.win", round, winner });
+        const economy = settleEconomy(winner);
+        events.push({ kind: "round.economy", round, winner, economy });
+        endPhase(events);
+        return events;
+    }
     return {
         tick(dt) {
             if (dt <= 0 || matchOver)
@@ -83,9 +123,9 @@ export function createRoundState(config) {
             const events = [];
             timeLeft -= dt;
             let guard = 0;
-            while (timeLeft <= 0 && !matchOver && guard < PHASE_ORDER.length + 2) {
+            while (timeLeft <= 0 && !matchOver && guard < order.length + 2) {
                 const carry = timeLeft;
-                if (phase === "live")
+                if (isConcludable(order, phase))
                     pendingWinner = null;
                 endPhase(events);
                 if (!matchOver)
@@ -94,17 +134,12 @@ export function createRoundState(config) {
             }
             return events;
         },
-        concludeRound(winner) {
-            if (matchOver || phase !== "live")
+        concludeRound: concludeRoundImpl,
+        evaluate() {
+            if (config.winCondition === undefined)
                 return [];
-            const events = [];
-            pendingWinner = winner;
-            scores[winner] = (scores[winner] ?? 0) + 1;
-            events.push({ kind: "round.win", round, winner });
-            const economy = settleEconomy(winner);
-            events.push({ kind: "round.economy", round, winner, economy });
-            endPhase(events);
-            return events;
+            const winner = config.winCondition(currentSnapshot());
+            return winner === null ? [] : concludeRoundImpl(winner);
         },
         onPhaseEnd(hook) {
             hooks.add(hook);
@@ -117,13 +152,7 @@ export function createRoundState(config) {
         timeLeft: () => Math.max(0, timeLeft),
         score: (team) => scores[team] ?? 0,
         economyFor,
-        snapshot: () => ({
-            round,
-            phase,
-            timeLeft: Math.max(0, timeLeft),
-            scores: { ...scores },
-            lossStreaks: { ...lossStreaks },
-            matchOver,
-        }),
+        roleOf: (team) => roles[team],
+        snapshot: currentSnapshot,
     };
 }

package/dist/settings/settingsModel.d.ts

@@ -0,0 +1,97 @@
+import type { GameContext } from "../runtime/gameContext.js";
+export type SettingValue = number | boolean | string;
+export type SettingKind = "slider" | "toggle" | "select";
+export type BuiltInSettingCategory = "sound" | "graphics" | "gameplay" | "controls";
+/** Built-in category ids keep autocomplete; any other string makes a fresh category. */
+export type SettingCategory = BuiltInSettingCategory | (string & {});
+export declare const BUILT_IN_SETTING_CATEGORIES: readonly BuiltInSettingCategory[];
+export interface SettingOption {
+    value: string;
+    label: string;
+}
+/** Declares or relabels/reorders a category tab; use it for a custom category or to reshape the built-ins. */
+export interface SettingCategoryDef {
+    id: SettingCategory;
+    label: string;
+    order?: number;
+}
+/** Extra setting a game appends to a built-in category via `defineGame({ settings: { extra } })`. */
+export interface GameSettingDef {
+    id: string;
+    label: string;
+    category: SettingCategory;
+    kind: SettingKind;
+    default: SettingValue;
+    /** Slider bounds — always pass both for a `slider`; omitted defaults (0..1) collapse the thumb. */
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly SettingOption[];
+    /** Applies the new value to game state; the value is already persisted before this runs. */
+    onChange?: (value: SettingValue, ctx: GameContext) => void;
+}
+/** `quick` shows compact on-screen volume/graphics buttons; `false` (default) mounts no engine trigger — open the menu from your own UI with `<SettingsTrigger>` or `useSettings().open()`. */
+export type SettingsSurface = "quick";
+/** The four themed settings layouts, chosen with `defineGame({ settings: { variant } })`. All read the game's `--jg-*` theme tokens. */
+export type SettingsVariant = "panel" | "sheet" | "sidebar" | "fullscreen";
+/** A game-state action (Restart, Quit to menu, …) shown as rows in the first "Game" settings tab — never a floating button or a rebindable key. */
+export interface SettingsActionDef {
+    id: string;
+    label: string;
+    /** `danger` styles destructive actions (restart, quit) apart from neutral ones. */
+    kind?: "default" | "danger";
+    /** Optional one-line hint under the label. */
+    description?: string;
+    /** Runs the action; the menu closes right after. */
+    run: (ctx: GameContext) => void;
+}
+export interface GameSettingsConfig {
+    /** Layout + skin of the menu; all four theme off `--jg-*`. Default `panel`. */
+    variant?: SettingsVariant;
+    /** `quick` shows compact on-screen volume/graphics buttons; omitted mounts no engine trigger — open the menu yourself with `<SettingsTrigger>` / `useSettings().open()`, or render `useSettings().categories` your own way. */
+    surface?: SettingsSurface | false;
+    /** Rows appended to any category — built-in or a brand-new one named by `category`. */
+    extra?: readonly GameSettingDef[];
+    /** Declare custom category tabs, or relabel/reorder the built-ins. */
+    categories?: readonly SettingCategoryDef[];
+    /** Built-in categories to hide. */
+    hide?: readonly SettingCategory[];
+    /** Game-state actions (Restart, Quit…) — become the first "Game" tab, shown before anything else. */
+    actions?: readonly SettingsActionDef[];
+    /** Input actions to drop from the rebindable Controls list — game-state keys like `restart` that belong in `actions`, not the rebind grid. */
+    hideBindings?: readonly string[];
+}
+export declare const SETTINGS_STORAGE_PREFIX = "jgengine:setting:";
+export declare const SETTING_IDS: {
+    readonly masterVolume: "sound.master";
+    readonly graphicsQuality: "graphics.quality";
+    readonly graphicsShadows: "graphics.shadows";
+    readonly graphicsUiScale: "graphics.uiScale";
+};
+export type GraphicsQuality = "low" | "medium" | "high";
+export declare const GRAPHICS_QUALITY_OPTIONS: readonly SettingOption[];
+export declare const DEFAULT_MASTER_VOLUME = 1;
+export declare const DEFAULT_GRAPHICS_QUALITY: GraphicsQuality;
+export declare const DEFAULT_GRAPHICS_SHADOWS = true;
+/** Player-controlled multiplier on the HUD's computed fit scale — one lever on desktop and mobile alike. */
+export declare const DEFAULT_UI_SCALE = 1;
+export declare const UI_SCALE_MIN = 0.5;
+export declare const UI_SCALE_MAX = 1.5;
+/** Device-pixel-ratio ceiling per quality tier — the shell's `Canvas` dpr cap. */
+export declare const GRAPHICS_QUALITY_DPR: Record<GraphicsQuality, number>;
+export declare function busVolumeSettingId(busId: string): string;
+export declare function settingStorageKey(id: string): string;
+interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export declare function loadSettingValue<T extends SettingValue>(id: string, fallback: T, storage?: Pick<WebStorageLike, "getItem"> | null | undefined): T;
+export declare function saveSettingValue(id: string, value: SettingValue, storage?: Pick<WebStorageLike, "setItem"> | null | undefined): void;
+export interface SettingsStore {
+    get<T extends SettingValue>(id: string, fallback: T): T;
+    set(id: string, value: SettingValue): void;
+    subscribe(listener: () => void): () => void;
+}
+/** Reactive, localStorage-backed settings store shared by the shell wiring and React hooks. */
+export declare function createSettingsStore(storage?: Pick<WebStorageLike, "getItem" | "setItem"> | null | undefined): SettingsStore;
+export {};

package/dist/settings/settingsModel.js

@@ -0,0 +1,100 @@
+import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+export const BUILT_IN_SETTING_CATEGORIES = [
+    "sound",
+    "graphics",
+    "gameplay",
+    "controls",
+];
+export const SETTINGS_STORAGE_PREFIX = "jgengine:setting:";
+export const SETTING_IDS = {
+    masterVolume: "sound.master",
+    graphicsQuality: "graphics.quality",
+    graphicsShadows: "graphics.shadows",
+    graphicsUiScale: "graphics.uiScale",
+};
+export const GRAPHICS_QUALITY_OPTIONS = [
+    { value: "low", label: "Low" },
+    { value: "medium", label: "Medium" },
+    { value: "high", label: "High" },
+];
+export const DEFAULT_MASTER_VOLUME = 1;
+export const DEFAULT_GRAPHICS_QUALITY = "high";
+export const DEFAULT_GRAPHICS_SHADOWS = true;
+/** Player-controlled multiplier on the HUD's computed fit scale — one lever on desktop and mobile alike. */
+export const DEFAULT_UI_SCALE = 1;
+export const UI_SCALE_MIN = 0.5;
+export const UI_SCALE_MAX = 1.5;
+/** Device-pixel-ratio ceiling per quality tier — the shell's `Canvas` dpr cap. */
+export const GRAPHICS_QUALITY_DPR = {
+    low: 1,
+    medium: 1.5,
+    high: 2,
+};
+export function busVolumeSettingId(busId) {
+    return `sound.bus.${busId}`;
+}
+export function settingStorageKey(id) {
+    return `${SETTINGS_STORAGE_PREFIX}${id}`;
+}
+function defaultStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function coerce(raw, fallback) {
+    if (typeof fallback === "number") {
+        const n = typeof raw === "number" ? raw : Number(raw);
+        return (Number.isFinite(n) ? n : fallback);
+    }
+    if (typeof fallback === "boolean") {
+        if (typeof raw === "boolean")
+            return raw;
+        return (raw === "true" ? true : raw === "false" ? false : fallback);
+    }
+    return (typeof raw === "string" ? raw : fallback);
+}
+export function loadSettingValue(id, fallback, storage = defaultStorage()) {
+    if (storage == null)
+        return fallback;
+    try {
+        const raw = storage.getItem(settingStorageKey(id));
+        if (raw === null)
+            return fallback;
+        return coerce(JSON.parse(raw), fallback);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function saveSettingValue(id, value, storage = defaultStorage()) {
+    if (storage == null)
+        return;
+    try {
+        storage.setItem(settingStorageKey(id), JSON.stringify(value));
+    }
+    catch {
+        /* ignore quota / private-mode failures */
+    }
+}
+/** Reactive, localStorage-backed settings store shared by the shell wiring and React hooks. */
+export function createSettingsStore(storage = defaultStorage()) {
+    const mem = createObservableKeyedStore();
+    return {
+        get(id, fallback) {
+            if (mem.has(id))
+                return coerce(mem.get(id), fallback);
+            return loadSettingValue(id, fallback, storage ?? undefined);
+        },
+        set(id, value) {
+            saveSettingValue(id, value, storage ?? undefined);
+            mem.set(id, value);
+        },
+        subscribe: mem.subscribe,
+    };
+}

package/dist/stats/statModifiers.d.ts

@@ -3,6 +3,9 @@ export interface StatModifier {
     multiply?: number;
 }
 export type StatModifierSet<TStat extends string> = Partial<Record<TStat, StatModifier>>;
+export interface CreateStatsOptions {
+    now?: () => number;
+}
 export interface Stats<TStat extends string> {
     setBase(stat: TStat, value: number): void;
     getBase(stat: TStat): number;
@@ -10,9 +13,9 @@ export interface Stats<TStat extends string> {
         expiresAtMs?: number;
     }): void;
     removeSource(sourceId: string): void;
-    hasSource(sourceId: string): boolean;
+    hasSource(sourceId: string, nowMs?: number): boolean;
     get(stat: TStat, nowMs?: number): number;
     pruneExpired(nowMs: number): string[];
     sources(): string[];
 }
-export declare function createStats<TStat extends string>(base: Record<TStat, number>): Stats<TStat>;
+export declare function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat>;

package/dist/stats/statModifiers.js

@@ -1,9 +1,23 @@
-export function createStats(base) {
+export function createStats(base, options) {
     const baseValues = { ...base };
     const sourceEntries = new Map();
+    const clock = options?.now;
+    function resolveNow(nowMs) {
+        return nowMs ?? clock?.();
+    }
     function isExpired(entry, nowMs) {
         return nowMs !== undefined && entry.expiresAtMs !== undefined && entry.expiresAtMs <= nowMs;
     }
+    function dropExpired(nowMs) {
+        const pruned = [];
+        for (const [sourceId, entry] of sourceEntries) {
+            if (isExpired(entry, nowMs)) {
+                sourceEntries.delete(sourceId);
+                pruned.push(sourceId);
+            }
+        }
+        return pruned;
+    }
     function resolve(stat, nowMs) {
         let total = baseValues[stat];
         let multiplier = 1;
@@ -27,27 +41,31 @@ export function createStats(base) {
         getBase(stat) {
             return baseValues[stat];
         },
-        addSource(sourceId, modifiers, options) {
-            sourceEntries.set(sourceId, { modifiers, expiresAtMs: options?.expiresAtMs });
+        addSource(sourceId, modifiers, sourceOptions) {
+            sourceEntries.set(sourceId, { modifiers, expiresAtMs: sourceOptions?.expiresAtMs });
         },
         removeSource(sourceId) {
             sourceEntries.delete(sourceId);
         },
-        hasSource(sourceId) {
-            return sourceEntries.has(sourceId);
+        hasSource(sourceId, nowMs) {
+            const entry = sourceEntries.get(sourceId);
+            if (entry === undefined)
+                return false;
+            const time = resolveNow(nowMs);
+            if (isExpired(entry, time)) {
+                sourceEntries.delete(sourceId);
+                return false;
+            }
+            return true;
         },
         get(stat, nowMs) {
-            return resolve(stat, nowMs);
+            const time = resolveNow(nowMs);
+            if (time !== undefined)
+                dropExpired(time);
+            return resolve(stat, time);
         },
         pruneExpired(nowMs) {
-            const pruned = [];
-            for (const [sourceId, entry] of sourceEntries) {
-                if (isExpired(entry, nowMs)) {
-                    sourceEntries.delete(sourceId);
-                    pruned.push(sourceId);
-                }
-            }
-            return pruned;
+            return dropExpired(nowMs);
         },
         sources() {
             return Array.from(sourceEntries.keys());

package/dist/store/observableKeyedStore.js

@@ -3,8 +3,9 @@ export function createObservableKeyedStore(areEqual) {
     const listeners = new Set();
     const EMPTY = [];
     let arrayCache = EMPTY;
+    let arrayDirty = false;
     function emit() {
-        arrayCache = store.size === 0 ? EMPTY : Array.from(store.values());
+        arrayDirty = true;
         for (const listener of listeners)
             listener();
     }
@@ -13,7 +14,8 @@ export function createObservableKeyedStore(areEqual) {
             const previous = store.get(key);
             if (previous !== undefined && areEqual?.(previous, value))
                 return;
-            store.set(key, value);
+            if (previous !== value)
+                store.set(key, value);
             emit();
         },
         delete(key) {
@@ -36,6 +38,10 @@ export function createObservableKeyedStore(areEqual) {
             return store;
         },
         arraySnapshot() {
+            if (arrayDirty) {
+                arrayCache = store.size === 0 ? EMPTY : Array.from(store.values());
+                arrayDirty = false;
+            }
             return arrayCache;
         },
     };

package/dist/survival/decayMeter.d.ts

@@ -41,7 +41,7 @@ export interface DecayMeterSet {
     refill(id: string, amount: number): void;
     /** Overwrite the base drain rate (e.g. a game mode with harsher hunger). */
     setRate(id: string, rate: number): void;
-    /** Multiply the drain rate this tick onward — cold biome speeds warmth loss, sprint burns stamina. */
+    /** Multiply drain until cleared via `setRateModifier(id, 1)` — cold biome, sprint, etc. */
     setRateModifier(id: string, multiplier: number): void;
     /** Moodles for every crossed threshold, worst-first per meter. */
     moodles(): Moodle[];

package/dist/survival/decayMeter.js

@@ -43,7 +43,6 @@ export function createDecayMeterSet(configs) {
                 return;
             for (const runtime of meters.values()) {
                 runtime.value = clamp(runtime.value - runtime.rate * runtime.modifier * dt, runtime.min, runtime.max);
-                runtime.modifier = 1;
             }
         },
         value(id) {

package/dist/tactics/fallingGrid.d.ts

@@ -0,0 +1,62 @@
+export type FallingGridCell = readonly [number, number];
+export interface FallingGridConfig {
+    cols: number;
+    rows: number;
+    /** Milliseconds a grounded piece may sit before `lockExpired` fires. Defaults to 500. */
+    lockDelayMs?: number;
+}
+/** Elapsed grounded time for the lock-delay state machine. `null` means airborne / not timing. */
+export interface LockState {
+    elapsedMs: number;
+}
+export interface FallingGridSnapshot<TCell> {
+    cols: number;
+    rows: number;
+    cells: readonly (TCell | null)[];
+}
+export interface FallingGrid<TCell> {
+    readonly cols: number;
+    readonly rows: number;
+    occupied(col: number, row: number): boolean;
+    cellAt(col: number, row: number): TCell | null;
+    setCell(col: number, row: number, value: TCell): void;
+    clearCell(col: number, row: number): void;
+    /** Bounds + collision check for a footprint (`cells`, relative to `offset`). Rows above the grid (`row < 0`) are allowed through, mirroring a piece spawning above the visible board; only columns are bounds-checked there. */
+    canPlace(cells: readonly FallingGridCell[], offset: FallingGridCell): boolean;
+    /** Writes `value` into every in-bounds cell of the footprint if `canPlace` allows it. Cells above the grid are silently skipped. Returns whether the placement happened. */
+    place(cells: readonly FallingGridCell[], offset: FallingGridCell, value: TCell): boolean;
+    /** Row indices that are fully occupied, in ascending order. */
+    fullRows(): readonly number[];
+    /** Removes the given rows and shifts every row above them down, backfilling the top with empty rows. Returns the number of rows cleared. */
+    clearRows(rows: readonly number[]): number;
+    /** Column-gravity collapse: every occupied cell in each column falls to the lowest free row below it, preserving relative order. Returns the number of cells that moved. */
+    settle(): number;
+    /** Advances (or starts) a lock-delay timer while `grounded`, and clears it the instant the piece is airborne. */
+    advanceLock(state: LockState | null, grounded: boolean, dtMs: number): LockState | null;
+    /** Whether a lock-delay timer has run out `lockDelayMs`. */
+    lockExpired(state: LockState | null): boolean;
+    snapshot(): FallingGridSnapshot<TCell>;
+    /** Clears every cell back to empty. */
+    reset(): void;
+}
+export interface GravityIntervalConfig {
+    /** Interval at level 0, in milliseconds. Defaults to 800. */
+    baseMs?: number;
+    /** Milliseconds shaved off per level. Defaults to 70. */
+    perLevel?: number;
+    /** Floor the interval never drops below, in milliseconds. Defaults to 50. */
+    minMs?: number;
+}
+/**
+ * Gravity tick interval for a given level: linear speed-up with a floor, generalizing
+ * `Games/block-stacker`'s `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds
+ * with configurable base/step/floor.
+ */
+export declare function gravityIntervalMs(level: number, config?: GravityIntervalConfig): number;
+/**
+ * A game-agnostic cell grid for gravity-driven falling-block mechanics: bounded occupancy,
+ * footprint placement/collision, line-clear collapse, column-gravity settle (for match-3/sand
+ * style cascades), and a pure lock-delay helper. Extracted from `Games/block-stacker`'s tetris
+ * logic so any falling-block game can adopt it instead of reimplementing the grid.
+ */
+export declare function createFallingGrid<TCell>(config: FallingGridConfig): FallingGrid<TCell>;