@jgengine/core 0.6.0 → 0.8.0

package/dist/survival/moodle.js

@@ -0,0 +1,91 @@
+export const MOODLE_SEVERITY_ORDER = {
+    critical: 0,
+    warning: 1,
+    neutral: 2,
+    good: 3,
+};
+function mergeStack(into, moodle) {
+    const existing = into.get(moodle.id);
+    if (existing === undefined) {
+        into.set(moodle.id, { ...moodle });
+        return;
+    }
+    into.set(moodle.id, {
+        ...existing,
+        stacks: existing.stacks + moodle.stacks,
+        severity: MOODLE_SEVERITY_ORDER[moodle.severity] < MOODLE_SEVERITY_ORDER[existing.severity]
+            ? moodle.severity
+            : existing.severity,
+    });
+}
+/**
+ * Merge any number of moodle groups into one stack — meters, ailments, and buffs
+ * share this display. Same-id moodles fold together (stacks add, worst severity wins);
+ * the result is ordered worst-first so the HUD reads critical statuses at a glance.
+ */
+export function stackMoodles(...groups) {
+    const merged = new Map();
+    for (const group of groups)
+        for (const moodle of group)
+            mergeStack(merged, moodle);
+    return [...merged.values()].sort((a, b) => MOODLE_SEVERITY_ORDER[a.severity] - MOODLE_SEVERITY_ORDER[b.severity]);
+}
+/**
+ * A stateful holder for timed status moodles (food buffs, temporary shelter, warmth).
+ * Meters and multi-region health derive their own moodles on read; combine all three
+ * through `stackMoodles(stack.list(), meterMoodles, ailmentMoodles)` for one display.
+ */
+export function createMoodleStack() {
+    const moodles = new Map();
+    return {
+        add(input) {
+            moodles.set(input.id, {
+                label: input.label,
+                severity: input.severity ?? "good",
+                stacks: input.stacks ?? 1,
+                ...(input.icon === undefined ? {} : { icon: input.icon }),
+                ...(input.note === undefined ? {} : { note: input.note }),
+                remaining: input.duration ?? null,
+                total: input.duration ?? null,
+            });
+        },
+        remove(id) {
+            moodles.delete(id);
+        },
+        has(id) {
+            return moodles.has(id);
+        },
+        tick(dt) {
+            if (dt <= 0)
+                return;
+            for (const [id, state] of moodles) {
+                if (state.remaining === null)
+                    continue;
+                state.remaining -= dt;
+                if (state.remaining <= 0)
+                    moodles.delete(id);
+            }
+        },
+        list() {
+            const out = [];
+            for (const [id, state] of moodles) {
+                out.push({
+                    id,
+                    label: state.label,
+                    severity: state.severity,
+                    source: "buff",
+                    stacks: state.stacks,
+                    ...(state.icon === undefined ? {} : { icon: state.icon }),
+                    ...(state.note === undefined ? {} : { note: state.note }),
+                    ...(state.remaining !== null && state.total !== null && state.total > 0
+                        ? { fraction: Math.max(0, Math.min(1, state.remaining / state.total)) }
+                        : {}),
+                });
+            }
+            return out;
+        },
+        clear() {
+            moodles.clear();
+        },
+    };
+}

package/dist/survival/regionHealth.d.ts

@@ -0,0 +1,72 @@
+import type { Moodle, MoodleSeverity } from "./moodle.js";
+export interface HealthRegionConfig {
+    id: string;
+    label: string;
+    max: number;
+    /** A vital part (head, thorax): the entity dies when it empties. Defaults to false. */
+    vital?: boolean;
+    /** Extra multiplier on incoming damage — a head takes more per hit. Defaults to 1. */
+    vulnerability?: number;
+}
+export interface AilmentConfig {
+    id: string;
+    label: string;
+    /** The part this injury belongs to; drain (bleed) applies here. */
+    region?: string;
+    severity?: MoodleSeverity;
+    icon?: string;
+    /** Health lost per game-second per stack while untreated (bleed, infection). */
+    drainPerSecond?: number;
+    /** Can queue multiple instances (three bleeds stack); otherwise re-applying refreshes. */
+    stacking?: boolean;
+    /** Treatment item ids that clear this injury — bandage, tourniquet, splint. */
+    treatedBy?: readonly string[];
+}
+export interface MultiRegionHealthConfig {
+    regions: readonly HealthRegionConfig[];
+    /** Ailment catalog keyed by id — the queue references these. */
+    ailments?: Record<string, AilmentConfig>;
+}
+export interface RegionHealthState {
+    id: string;
+    label: string;
+    current: number;
+    max: number;
+    fraction: number;
+    vital: boolean;
+}
+export interface AilmentInstance {
+    id: string;
+    stacks: number;
+}
+export interface DamageResult {
+    region: RegionHealthState;
+    /** Damage actually applied after vulnerability. */
+    applied: number;
+    dead: boolean;
+}
+export interface TreatResult {
+    /** Ailment ids fully or partially cleared by the item. */
+    treated: readonly string[];
+}
+export interface MultiRegionHealth {
+    damage(regionId: string, amount: number): DamageResult;
+    heal(regionId: string, amount: number): RegionHealthState;
+    region(regionId: string): RegionHealthState;
+    regions(): RegionHealthState[];
+    /** 0..1 aggregate across all parts (share-weighted by max). */
+    overall(): number;
+    /** Queue an ailment from the catalog; stacking ailments increment, others refresh. */
+    applyAilment(ailmentId: string): void;
+    /** Clear ailments treated by an item id; one item clears one stack of each match. */
+    treat(itemId: string): TreatResult;
+    /** Apply ailment drains over game-time `dt`; may kill via a vital part. */
+    tick(dt: number): {
+        dead: boolean;
+    };
+    ailments(): AilmentInstance[];
+    /** Wounds as moodles for the shared status stack (#78 shares #90's moodle display). */
+    ailmentMoodles(): Moodle[];
+    readonly dead: boolean;
+}
+export declare function createMultiRegionHealth(config: MultiRegionHealthConfig): MultiRegionHealth;

package/dist/survival/regionHealth.js

@@ -0,0 +1,129 @@
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+export function createMultiRegionHealth(config) {
+    if (config.regions.length === 0) {
+        throw new Error("createMultiRegionHealth: regions must be non-empty");
+    }
+    const regions = new Map();
+    const order = [];
+    for (const region of config.regions) {
+        regions.set(region.id, { config: region, current: region.max });
+        order.push(region.id);
+    }
+    const catalog = config.ailments ?? {};
+    const queue = new Map();
+    let dead = false;
+    const requireRegion = (id) => {
+        const runtime = regions.get(id);
+        if (runtime === undefined)
+            throw new Error(`unknown health region "${id}"`);
+        return runtime;
+    };
+    const toState = (runtime) => ({
+        id: runtime.config.id,
+        label: runtime.config.label,
+        current: runtime.current,
+        max: runtime.config.max,
+        fraction: runtime.config.max > 0 ? runtime.current / runtime.config.max : 0,
+        vital: runtime.config.vital ?? false,
+    });
+    const applyDamage = (runtime, amount) => {
+        const before = runtime.current;
+        runtime.current = clamp(runtime.current - amount, 0, runtime.config.max);
+        if ((runtime.config.vital ?? false) && runtime.current <= 0)
+            dead = true;
+        return before - runtime.current;
+    };
+    return {
+        damage(regionId, amount) {
+            const runtime = requireRegion(regionId);
+            const scaled = Math.max(0, amount) * (runtime.config.vulnerability ?? 1);
+            const applied = applyDamage(runtime, scaled);
+            return { region: toState(runtime), applied, dead };
+        },
+        heal(regionId, amount) {
+            const runtime = requireRegion(regionId);
+            runtime.current = clamp(runtime.current + Math.max(0, amount), 0, runtime.config.max);
+            return toState(runtime);
+        },
+        region(regionId) {
+            return toState(requireRegion(regionId));
+        },
+        regions() {
+            return order.map((id) => toState(regions.get(id)));
+        },
+        overall() {
+            let current = 0;
+            let max = 0;
+            for (const runtime of regions.values()) {
+                current += runtime.current;
+                max += runtime.config.max;
+            }
+            return max > 0 ? current / max : 0;
+        },
+        applyAilment(ailmentId) {
+            const def = catalog[ailmentId];
+            if (def === undefined)
+                throw new Error(`unknown ailment "${ailmentId}"`);
+            const current = queue.get(ailmentId) ?? 0;
+            queue.set(ailmentId, def.stacking ?? false ? current + 1 : 1);
+        },
+        treat(itemId) {
+            const treated = [];
+            for (const [ailmentId, stacks] of queue) {
+                const def = catalog[ailmentId];
+                if (def === undefined)
+                    continue;
+                if (!(def.treatedBy ?? []).includes(itemId))
+                    continue;
+                treated.push(ailmentId);
+                if (stacks <= 1)
+                    queue.delete(ailmentId);
+                else
+                    queue.set(ailmentId, stacks - 1);
+            }
+            return { treated };
+        },
+        tick(dt) {
+            if (dt > 0) {
+                for (const [ailmentId, stacks] of queue) {
+                    const def = catalog[ailmentId];
+                    if (def === undefined || def.drainPerSecond === undefined)
+                        continue;
+                    const target = def.region ?? order[0];
+                    const runtime = regions.get(target);
+                    if (runtime === undefined)
+                        continue;
+                    applyDamage(runtime, def.drainPerSecond * stacks * dt);
+                }
+            }
+            return { dead };
+        },
+        ailments() {
+            return [...queue].map(([id, stacks]) => ({ id, stacks }));
+        },
+        ailmentMoodles() {
+            const out = [];
+            for (const [ailmentId, stacks] of queue) {
+                const def = catalog[ailmentId];
+                if (def === undefined)
+                    continue;
+                const untreated = (def.treatedBy ?? []).length > 0;
+                out.push({
+                    id: ailmentId,
+                    label: def.label,
+                    severity: def.severity ?? "warning",
+                    source: "ailment",
+                    stacks,
+                    ...(def.icon === undefined ? {} : { icon: def.icon }),
+                    ...(untreated ? { note: `needs ${def.treatedBy[0]}` } : {}),
+                });
+            }
+            return out;
+        },
+        get dead() {
+            return dead;
+        },
+    };
+}

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>;

package/dist/tactics/fallingGrid.js

@@ -0,0 +1,158 @@
+/**
+ * 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 function gravityIntervalMs(level, config = {}) {
+    const baseMs = config.baseMs ?? 800;
+    const perLevel = config.perLevel ?? 70;
+    const minMs = config.minMs ?? 50;
+    return Math.max(minMs, baseMs - level * perLevel);
+}
+/**
+ * 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 function createFallingGrid(config) {
+    const cols = config.cols;
+    const rows = config.rows;
+    const lockDelayMs = config.lockDelayMs ?? 500;
+    if (cols <= 0 || rows <= 0)
+        throw new Error("falling grid needs positive dimensions");
+    let cells = new Array(cols * rows).fill(null);
+    function index(col, row) {
+        return row * cols + col;
+    }
+    function inBounds(col, row) {
+        return col >= 0 && col < cols && row >= 0 && row < rows;
+    }
+    function cellAt(col, row) {
+        if (!inBounds(col, row))
+            return null;
+        return cells[index(col, row)] ?? null;
+    }
+    function occupied(col, row) {
+        return cellAt(col, row) !== null;
+    }
+    function setCell(col, row, value) {
+        if (!inBounds(col, row))
+            return;
+        cells[index(col, row)] = value;
+    }
+    function clearCell(col, row) {
+        if (!inBounds(col, row))
+            return;
+        cells[index(col, row)] = null;
+    }
+    function canPlace(footprint, offset) {
+        for (const [dc, dr] of footprint) {
+            const col = offset[0] + dc;
+            const row = offset[1] + dr;
+            if (col < 0 || col >= cols || row >= rows)
+                return false;
+            if (row >= 0 && occupied(col, row))
+                return false;
+        }
+        return true;
+    }
+    function place(footprint, offset, value) {
+        if (!canPlace(footprint, offset))
+            return false;
+        for (const [dc, dr] of footprint) {
+            const col = offset[0] + dc;
+            const row = offset[1] + dr;
+            if (row >= 0)
+                setCell(col, row, value);
+        }
+        return true;
+    }
+    function fullRows() {
+        const full = [];
+        for (let row = 0; row < rows; row += 1) {
+            let rowFull = true;
+            for (let col = 0; col < cols; col += 1) {
+                if (!occupied(col, row)) {
+                    rowFull = false;
+                    break;
+                }
+            }
+            if (rowFull)
+                full.push(row);
+        }
+        return full;
+    }
+    function clearRows(rowsToClear) {
+        const toClear = new Set(rowsToClear);
+        if (toClear.size === 0)
+            return 0;
+        const kept = [];
+        for (let row = 0; row < rows; row += 1) {
+            if (toClear.has(row))
+                continue;
+            kept.push(cells.slice(index(0, row), index(0, row) + cols));
+        }
+        const cleared = rows - kept.length;
+        const next = [];
+        for (let i = 0; i < cleared; i += 1)
+            next.push(...new Array(cols).fill(null));
+        for (const row of kept)
+            next.push(...row);
+        cells = next;
+        return cleared;
+    }
+    function settle() {
+        let moved = 0;
+        for (let col = 0; col < cols; col += 1) {
+            const values = [];
+            for (let row = 0; row < rows; row += 1) {
+                const value = cellAt(col, row);
+                if (value !== null)
+                    values.push({ row, value });
+            }
+            for (let row = 0; row < rows; row += 1)
+                clearCell(col, row);
+            const count = values.length;
+            for (let i = 0; i < count; i += 1) {
+                const newRow = rows - count + i;
+                const { row: oldRow, value } = values[i];
+                setCell(col, newRow, value);
+                if (oldRow !== newRow)
+                    moved += 1;
+            }
+        }
+        return moved;
+    }
+    function advanceLock(state, grounded, dtMs) {
+        if (!grounded)
+            return null;
+        return { elapsedMs: (state?.elapsedMs ?? 0) + dtMs };
+    }
+    function lockExpired(state) {
+        return state !== null && state.elapsedMs >= lockDelayMs;
+    }
+    function snapshot() {
+        return { cols, rows, cells: cells.slice() };
+    }
+    function reset() {
+        cells = new Array(cols * rows).fill(null);
+    }
+    return {
+        cols,
+        rows,
+        occupied,
+        cellAt,
+        setCell,
+        clearCell,
+        canPlace,
+        place,
+        fullRows,
+        clearRows,
+        settle,
+        advanceLock,
+        lockExpired,
+        snapshot,
+        reset,
+    };
+}

package/dist/tactics/predictiveQuery.d.ts

@@ -0,0 +1,34 @@
+import { type AreaTargetInput, type CombatSpatialDeps } from "../combat/effects.js";
+import type { EntityPosition } from "../scene/entityStore.js";
+import type { Aim, QueryArcOptions } from "../scene/spatial.js";
+import type { Tile } from "./tacticalGrid.js";
+export interface PredictiveDeps {
+    spatial: CombatSpatialDeps;
+    queryArc(options: QueryArcOptions): string[];
+    canReceive?(instanceId: string, effect: string): string | null;
+}
+export interface PredictedTarget {
+    instanceId: string;
+    scale: number;
+}
+export interface AreaPredictInput extends AreaTargetInput {
+    effect?: string;
+    requireReceive?: boolean;
+}
+export interface ArcPredictInput {
+    from: string;
+    aim: Aim;
+    radius: number;
+    halfAngleDeg?: number;
+    effect?: string;
+    requireReceive?: boolean;
+}
+export declare function predictAreaEffect(deps: PredictiveDeps, input: AreaPredictInput): PredictedTarget[];
+export declare function predictArcEffect(deps: PredictiveDeps, input: ArcPredictInput): PredictedTarget[];
+export interface TilePredictInput {
+    at: EntityPosition;
+    radius: number;
+    originTile: Tile;
+    tileSize: number;
+}
+export declare function predictTiles(input: TilePredictInput): Tile[];

package/dist/tactics/predictiveQuery.js

@@ -0,0 +1,44 @@
+import { resolveAreaTargets, } from "../combat/effects.js";
+function receiveGate(deps, effect, requireReceive) {
+    if (!requireReceive || effect === undefined || deps.canReceive === undefined)
+        return undefined;
+    const gate = deps.canReceive;
+    return (instanceId) => gate(instanceId, effect) === null;
+}
+export function predictAreaEffect(deps, input) {
+    const requireReceive = input.requireReceive ?? true;
+    return resolveAreaTargets(deps.spatial, input, receiveGate(deps, input.effect, requireReceive));
+}
+export function predictArcEffect(deps, input) {
+    const requireReceive = input.requireReceive ?? true;
+    const gate = receiveGate(deps, input.effect, requireReceive);
+    const hit = deps.queryArc({
+        from: input.from,
+        aim: input.aim,
+        radius: input.radius,
+        ...(input.halfAngleDeg === undefined ? {} : { halfAngleDeg: input.halfAngleDeg }),
+    });
+    const targets = [];
+    for (const instanceId of hit) {
+        if (gate !== undefined && !gate(instanceId))
+            continue;
+        targets.push({ instanceId, scale: 1 });
+    }
+    return targets;
+}
+export function predictTiles(input) {
+    const reach = Math.ceil(input.radius / input.tileSize);
+    const tiles = [];
+    for (let dc = -reach; dc <= reach; dc += 1) {
+        for (let dr = -reach; dr <= reach; dr += 1) {
+            const worldX = input.at[0] + dc * input.tileSize;
+            const worldZ = input.at[2] + dr * input.tileSize;
+            const dx = worldX - input.at[0];
+            const dz = worldZ - input.at[2];
+            if (Math.sqrt(dx * dx + dz * dz) <= input.radius) {
+                tiles.push([input.originTile[0] + dc, input.originTile[1] + dr]);
+            }
+        }
+    }
+    return tiles;
+}

package/dist/tactics/snapshot.d.ts

@@ -0,0 +1,18 @@
+export interface SnapshotSlice<T = unknown> {
+    capture(): T;
+    restore(state: T): void;
+}
+export type Snapshot = Record<string, unknown>;
+export interface SnapshotStore {
+    register<T>(id: string, slice: SnapshotSlice<T>): void;
+    unregister(id: string): void;
+    capture(): Snapshot;
+    restore(snapshot: Snapshot): void;
+    push(): Snapshot;
+    pop(): boolean;
+    peek(): Snapshot | null;
+    depth(): number;
+    clear(): void;
+}
+export declare function deepClone<T>(value: T): T;
+export declare function createSnapshotStore(): SnapshotStore;

package/dist/tactics/snapshot.js

@@ -0,0 +1,65 @@
+export function deepClone(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => deepClone(item));
+    if (value instanceof Map) {
+        const clone = new Map();
+        for (const [k, v] of value)
+            clone.set(deepClone(k), deepClone(v));
+        return clone;
+    }
+    if (value instanceof Set) {
+        const clone = new Set();
+        for (const item of value)
+            clone.add(deepClone(item));
+        return clone;
+    }
+    const clone = {};
+    for (const [k, v] of Object.entries(value))
+        clone[k] = deepClone(v);
+    return clone;
+}
+export function createSnapshotStore() {
+    const slices = new Map();
+    const stack = [];
+    function capture() {
+        const snapshot = {};
+        for (const [id, slice] of slices)
+            snapshot[id] = deepClone(slice.capture());
+        return snapshot;
+    }
+    function restore(snapshot) {
+        for (const [id, slice] of slices) {
+            if (id in snapshot)
+                slice.restore(deepClone(snapshot[id]));
+        }
+    }
+    return {
+        register: (id, slice) => {
+            slices.set(id, slice);
+        },
+        unregister: (id) => {
+            slices.delete(id);
+        },
+        capture,
+        restore,
+        push: () => {
+            const snapshot = capture();
+            stack.push(snapshot);
+            return snapshot;
+        },
+        pop: () => {
+            const snapshot = stack.pop();
+            if (snapshot === undefined)
+                return false;
+            restore(snapshot);
+            return true;
+        },
+        peek: () => (stack.length === 0 ? null : stack[stack.length - 1]),
+        depth: () => stack.length,
+        clear: () => {
+            stack.length = 0;
+        },
+    };
+}