@jgengine/core 0.5.0 → 0.7.0

package/dist/survival/decayMeter.d.ts

@@ -0,0 +1,59 @@
+import type { Moodle, MoodleSeverity } from "./moodle.js";
+export interface MeterThreshold {
+    /** Moodle id raised while the meter is on the wrong side of `at`. */
+    id: string;
+    label: string;
+    /** Boundary value. */
+    at: number;
+    /** Raise the moodle when the meter is `below` (hunger/thirst) or `above` (temperature, radiation) this value. */
+    when: "below" | "above";
+    severity?: MoodleSeverity;
+    icon?: string;
+}
+export interface DecayMeterConfig {
+    id: string;
+    max: number;
+    min?: number;
+    /** Starting value; defaults to `max` (a full stomach). */
+    start?: number;
+    /**
+     * Units changed per game-second at rate-modifier 1. Positive drains toward `min`
+     * (hunger, oxygen), negative fills toward `max` (a warmth meter recovering by a fire).
+     */
+    rate: number;
+    /** Status thresholds → moodles, distinct from the raw numeric bar. */
+    thresholds?: readonly MeterThreshold[];
+}
+export interface DecayMeterState {
+    id: string;
+    value: number;
+    max: number;
+    min: number;
+    /** 0..1 fill. */
+    fraction: number;
+}
+export interface DecayMeterSet {
+    /** Drain/fill every meter by `rate * rateModifier * dt`. Call once per game tick. */
+    tick(dt: number): void;
+    value(id: string): number;
+    state(id: string): DecayMeterState;
+    /** Consumable/action refill: `refill("hunger", 40)` after eating. Negative drains. */
+    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. */
+    setRateModifier(id: string, multiplier: number): void;
+    /** Moodles for every crossed threshold, worst-first per meter. */
+    moodles(): Moodle[];
+    /** True while any threshold with the given severity (or worse) is active — cheap game gate. */
+    snapshot(): Record<string, DecayMeterState>;
+    ids(): readonly string[];
+}
+/**
+ * Named decay meters — hunger, thirst, oxygen, sanity, warmth, stamina. Each drains
+ * (or recovers) on game-time `dt` at a configurable rate, refills from consumables or
+ * actions, and raises moodle statuses at thresholds. Rate modifiers let the environment
+ * drive them (colder → faster warmth loss; toxic biome → oxygen drops), so a game reads
+ * an environment field then calls `setRateModifier`.
+ */
+export declare function createDecayMeterSet(configs: readonly DecayMeterConfig[]): DecayMeterSet;

package/dist/survival/decayMeter.js

@@ -0,0 +1,95 @@
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+function toState(runtime) {
+    const span = runtime.max - runtime.min;
+    return {
+        id: runtime.config.id,
+        value: runtime.value,
+        max: runtime.max,
+        min: runtime.min,
+        fraction: span > 0 ? (runtime.value - runtime.min) / span : 0,
+    };
+}
+function crossed(threshold, value) {
+    return threshold.when === "below" ? value < threshold.at : value > threshold.at;
+}
+/**
+ * Named decay meters — hunger, thirst, oxygen, sanity, warmth, stamina. Each drains
+ * (or recovers) on game-time `dt` at a configurable rate, refills from consumables or
+ * actions, and raises moodle statuses at thresholds. Rate modifiers let the environment
+ * drive them (colder → faster warmth loss; toxic biome → oxygen drops), so a game reads
+ * an environment field then calls `setRateModifier`.
+ */
+export function createDecayMeterSet(configs) {
+    const meters = new Map();
+    const order = [];
+    for (const config of configs) {
+        const min = config.min ?? 0;
+        const max = config.max;
+        const value = clamp(config.start ?? max, min, max);
+        meters.set(config.id, { config, min, max, value, rate: config.rate, modifier: 1 });
+        order.push(config.id);
+    }
+    const require = (id) => {
+        const runtime = meters.get(id);
+        if (runtime === undefined)
+            throw new Error(`unknown decay meter "${id}"`);
+        return runtime;
+    };
+    return {
+        tick(dt) {
+            if (dt <= 0)
+                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) {
+            return require(id).value;
+        },
+        state(id) {
+            return toState(require(id));
+        },
+        refill(id, amount) {
+            const runtime = require(id);
+            runtime.value = clamp(runtime.value + amount, runtime.min, runtime.max);
+        },
+        setRate(id, rate) {
+            require(id).rate = rate;
+        },
+        setRateModifier(id, multiplier) {
+            require(id).modifier = multiplier;
+        },
+        moodles() {
+            const out = [];
+            for (const id of order) {
+                const runtime = meters.get(id);
+                for (const threshold of runtime.config.thresholds ?? []) {
+                    if (!crossed(threshold, runtime.value))
+                        continue;
+                    out.push({
+                        id: threshold.id,
+                        label: threshold.label,
+                        severity: threshold.severity ?? "warning",
+                        source: "meter",
+                        stacks: 1,
+                        ...(threshold.icon === undefined ? {} : { icon: threshold.icon }),
+                        fraction: toState(runtime).fraction,
+                    });
+                }
+            }
+            return out;
+        },
+        snapshot() {
+            const out = {};
+            for (const id of order)
+                out[id] = toState(meters.get(id));
+            return out;
+        },
+        ids() {
+            return order;
+        },
+    };
+}

package/dist/survival/moodle.d.ts

@@ -0,0 +1,48 @@
+export type MoodleSeverity = "good" | "neutral" | "warning" | "critical";
+export type MoodleSource = "meter" | "ailment" | "buff";
+export interface Moodle {
+    id: string;
+    label: string;
+    severity: MoodleSeverity;
+    source: MoodleSource;
+    stacks: number;
+    icon?: string;
+    /** 0..1 progress ring — remaining buff time, wound treatment, meter fill. Absent = no ring. */
+    fraction?: number;
+    /** Free-form note surfaced under the label (e.g. "-3°C", "needs bandage"). */
+    note?: string;
+}
+export declare const MOODLE_SEVERITY_ORDER: Record<MoodleSeverity, number>;
+/**
+ * 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 declare function stackMoodles(...groups: readonly (readonly Moodle[])[]): Moodle[];
+export interface TimedMoodleInput {
+    id: string;
+    label: string;
+    severity?: MoodleSeverity;
+    icon?: string;
+    note?: string;
+    stacks?: number;
+    /** Game-seconds until the moodle drops. Omit for a moodle that stays until removed. */
+    duration?: number;
+}
+export interface MoodleStack {
+    /** Add or refresh a timed moodle (Valheim food buff, a temporary shelter status). */
+    add(input: TimedMoodleInput): void;
+    remove(id: string): void;
+    has(id: string): boolean;
+    /** Advance timers by a game-time delta; drops expired moodles. */
+    tick(dt: number): void;
+    /** The live timed moodles (buffs, temporary statuses). */
+    list(): Moodle[];
+    clear(): void;
+}
+/**
+ * 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 declare function createMoodleStack(): MoodleStack;

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/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;
+        },
+    };
+}