@jgengine/core 0.11.0 → 0.13.0

package/dist/stats/spawnLevelStats.js

@@ -0,0 +1,140 @@
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function normalizeLevel(level) {
+    const floored = Math.floor(level);
+    return floored < 1 ? 1 : floored;
+}
+/**
+ * Scatter `count` points one at a time across `statIds`, choosing each target uniformly from the
+ * injected rng. Mutates `into` in place; bounded by `count`. The rng draws the sole source of
+ * randomness, so an identical rng sequence reproduces an identical distribution.
+ */
+function distributePoints(statIds, count, rng, into) {
+    const n = statIds.length;
+    if (n === 0 || count <= 0)
+        return;
+    for (let i = 0; i < count; i++) {
+        let index = Math.floor(rng() * n);
+        if (index >= n)
+            index = n - 1;
+        if (index < 0)
+            index = 0;
+        const stat = statIds[index];
+        into[stat] = (into[stat] ?? 0) + 1;
+    }
+}
+function zeroedPoints(statIds) {
+    const points = {};
+    for (const stat of statIds)
+        points[stat] = 0;
+    return points;
+}
+/**
+ * Roll a fresh wild creature at `level`: distribute `(level - 1)` points randomly across the
+ * species' stats using the injected rng and return a serializable {@link CreatureStatInstance}.
+ * Deterministic — the same rng sequence yields the same point spread. Levels below 1 clamp to 1
+ * (no points). Use `seededRng` from `../random/rng` for a persisted, reproducible stream.
+ *
+ * @capability spawn-level-roll distribute a wild creature's spawn level into random per-stat points
+ */
+export function rollSpawnInstance(speciesId, species, level, rng) {
+    const statIds = Object.keys(species);
+    const points = zeroedPoints(statIds);
+    const normalized = normalizeLevel(level);
+    distributePoints(statIds, normalized - 1, rng, points);
+    return { speciesId, level: normalized, points, domesticLevels: 0 };
+}
+/**
+ * Resolve an instance's live stat values from its distributed points:
+ * `value = base * (1 + points * growth)` per stat. Stats with zero points return their base.
+ *
+ * @capability spawn-stat-values resolve a creature's per-stat values from its distributed points
+ */
+export function resolveSpawnStats(species, instance) {
+    const out = {};
+    for (const stat of Object.keys(species)) {
+        const def = species[stat];
+        const pts = instance.points[stat] ?? 0;
+        out[stat] = def.base * (1 + pts * def.growth);
+    }
+    return out;
+}
+/**
+ * Bonus levels granted by a capture at the given effectiveness:
+ * `floor(level * clamp01(effectiveness) / 2)`. A perfect (1.0) capture grants half the wild
+ * level; a botched (0) capture grants none. Effectiveness outside `[0,1]` clamps.
+ *
+ * @capability capture-bonus-levels convert wild level and capture effectiveness into bonus levels
+ */
+export function captureBonusLevels(level, effectiveness) {
+    return Math.floor((normalizeLevel(level) * clamp01(effectiveness)) / 2);
+}
+/**
+ * Apply a capture at the given effectiveness: compute bonus levels via {@link captureBonusLevels},
+ * distribute those extra points randomly with the injected rng, and return the post-capture
+ * instance (level raised to the tamed total) alongside the granted bonus levels and tamed level.
+ * The input instance is not mutated.
+ *
+ * @capability capture-effectiveness-tame apply capture effectiveness to grant and distribute bonus levels
+ */
+export function applyCaptureEffectiveness(species, instance, effectiveness, rng) {
+    const bonusLevels = captureBonusLevels(instance.level, effectiveness);
+    const statIds = Object.keys(species);
+    const points = { ...instance.points };
+    distributePoints(statIds, bonusLevels, rng, points);
+    const tamedLevel = instance.level + bonusLevels;
+    return {
+        bonusLevels,
+        tamedLevel,
+        instance: { ...instance, level: tamedLevel, points },
+    };
+}
+/**
+ * Spend one earned post-capture level into `stat`, adding a single growth increment (one point)
+ * and raising both `level` and `domesticLevels`. When `maxDomesticLevels` is set and already
+ * reached, the spend is refused (`spent: false`) and the instance is returned untouched. Pure:
+ * returns a new instance rather than mutating the input.
+ *
+ * @capability domestic-level-spend spend an earned post-capture level into a chosen stat under a cap
+ */
+export function spendDomesticLevel(instance, stat, options) {
+    const cap = options?.maxDomesticLevels;
+    if (cap !== undefined && instance.domesticLevels >= cap) {
+        return { instance, spent: false };
+    }
+    const points = { ...instance.points };
+    points[stat] = (points[stat] ?? 0) + 1;
+    return {
+        instance: {
+            ...instance,
+            points,
+            level: instance.level + 1,
+            domesticLevels: instance.domesticLevels + 1,
+        },
+        spent: true,
+    };
+}
+/**
+ * Deep-copy an instance into a detached, serializable record — the transport/save counterpart of
+ * {@link restoreSpawnInstance}. Copies the points map so later edits don't leak into the snapshot.
+ *
+ * @capability spawn-instance-snapshot deep-copy a creature stat instance into a serializable record
+ */
+export function snapshotSpawnInstance(instance) {
+    return {
+        speciesId: instance.speciesId,
+        level: instance.level,
+        domesticLevels: instance.domesticLevels,
+        points: { ...instance.points },
+    };
+}
+/**
+ * Rehydrate a creature stat instance from decoded data (e.g. `JSON.parse` output), returning a
+ * fresh deep copy the caller owns. Inverse of {@link snapshotSpawnInstance}.
+ *
+ * @capability spawn-instance-restore rehydrate a creature stat instance from decoded snapshot data
+ */
+export function restoreSpawnInstance(data) {
+    return snapshotSpawnInstance(data);
+}

package/dist/stats/statModifiers.d.ts

@@ -6,6 +6,17 @@ export type StatModifierSet<TStat extends string> = Partial<Record<TStat, StatMo
 export interface CreateStatsOptions {
     now?: () => number;
 }
+/** One serializable modifier source in a {@link StatsSnapshot}. */
+interface StatModifierSourceSnapshot<TStat extends string> {
+    id: string;
+    modifiers: StatModifierSet<TStat>;
+    expiresAtMs?: number;
+}
+/** Complete plain-data state for a {@link Stats} runtime. */
+export interface StatsSnapshot<TStat extends string> {
+    base: Record<TStat, number>;
+    sources: StatModifierSourceSnapshot<TStat>[];
+}
 export interface Stats<TStat extends string> {
     setBase(stat: TStat, value: number): void;
     getBase(stat: TStat): number;
@@ -17,6 +28,10 @@ export interface Stats<TStat extends string> {
     get(stat: TStat, nowMs?: number): number;
     pruneExpired(nowMs: number): string[];
     sources(): string[];
+    /** Return a detached JSON-serializable copy of base values and modifier sources. */
+    snapshot(): StatsSnapshot<TStat>;
+    /** Replace all runtime state from caller-owned decoded snapshot data. */
+    restore(snapshot: StatsSnapshot<TStat>): void;
 }
 /**
  * A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
@@ -24,3 +39,4 @@ export interface Stats<TStat extends string> {
  * @capability stat-block base stats with stacking, expiring buffs and debuffs applied on read
  */
 export declare function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat>;
+export {};

package/dist/stats/statModifiers.js

@@ -1,10 +1,19 @@
+function cloneModifierSet(modifiers) {
+    const copy = {};
+    for (const stat of Object.keys(modifiers)) {
+        const modifier = modifiers[stat];
+        if (modifier !== undefined)
+            copy[stat] = { ...modifier };
+    }
+    return copy;
+}
 /**
  * A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
  *
  * @capability stat-block base stats with stacking, expiring buffs and debuffs applied on read
  */
 export function createStats(base, options) {
-    const baseValues = { ...base };
+    let baseValues = { ...base };
     const sourceEntries = new Map();
     const clock = options?.now;
     function resolveNow(nowMs) {
@@ -75,5 +84,25 @@ export function createStats(base, options) {
         sources() {
             return Array.from(sourceEntries.keys());
         },
+        snapshot() {
+            return {
+                base: { ...baseValues },
+                sources: Array.from(sourceEntries, ([id, entry]) => ({
+                    id,
+                    modifiers: cloneModifierSet(entry.modifiers),
+                    ...(entry.expiresAtMs === undefined ? {} : { expiresAtMs: entry.expiresAtMs }),
+                })),
+            };
+        },
+        restore(snapshot) {
+            baseValues = { ...snapshot.base };
+            sourceEntries.clear();
+            for (const source of snapshot.sources) {
+                sourceEntries.set(source.id, {
+                    modifiers: cloneModifierSet(source.modifiers),
+                    expiresAtMs: source.expiresAtMs,
+                });
+            }
+        },
     };
 }

package/dist/stats/statPool.d.ts

@@ -0,0 +1,70 @@
+/** Serializable state for any bounded named resource. The caller defines what the resource means. */
+export interface StatPool {
+    current: number;
+    max: number;
+    min: number;
+}
+/** Input used to create a normalized pool. `current` defaults to `max`; `min` defaults to zero. */
+export interface StatPoolInput {
+    current?: number;
+    max: number;
+    min?: number;
+}
+/** Partial update applied without mutating the previous pool. */
+export interface StatPoolPatch {
+    current?: number;
+    max?: number;
+    min?: number;
+}
+/**
+ * Structural bridge to caller-owned resource state. Implement it over an ECS,
+ * Redux/Zustand store, plain object, database-backed model, or JGengine's native
+ * entity stats without moving ownership into the SDK.
+ */
+export interface StatPoolAccess<TOwnerId extends string = string, TStatId extends string = string> {
+    get(ownerId: TOwnerId, statId: TStatId): StatPool | null;
+    set(ownerId: TOwnerId, statId: TStatId, next: StatPool): unknown;
+}
+/** Inspectable result of a bounded pool change. */
+export interface StatPoolChange {
+    previous: StatPool;
+    pool: StatPool;
+    /** Actual applied amount after clamping. */
+    applied: number;
+    hitMin: boolean;
+    hitMax: boolean;
+}
+/** Outcome of changing a pool through {@link StatPoolAccess}. */
+export type StatPoolAccessResult = ({
+    status: "ok";
+} & StatPoolChange) | {
+    status: "rejected";
+    reason: string;
+};
+/**
+ * Normalize caller data into a complete plain-data pool.
+ *
+ * @capability stat-pool create a serializable current/min/max pool for any caller-named resource
+ */
+export declare function createStatPool(input: StatPoolInput): StatPool;
+/**
+ * Apply new bounds/current to a pool, clamping the result and leaving the input untouched.
+ *
+ * @capability stat-pool-patch immutably retune a bounded resource's current value or bounds
+ */
+export declare function patchStatPool(pool: StatPool, patch: StatPoolPatch): StatPool;
+/**
+ * Pure bounded delta transition with the exact applied amount and boundary flags.
+ *
+ * @capability stat-pool-change immutably increase or decrease any named bounded resource with clamp evidence
+ */
+export declare function changeStatPool(pool: StatPool, amount: number): StatPoolChange;
+/**
+ * Read, transition, and write a caller-owned pool through the structural
+ * adapter. Positive amounts increase the resource; negative amounts decrease
+ * it. The adapter receives a complete replacement value, never a hidden
+ * mutation.
+ *
+ * @capability portable-stat-pool apply deterministic bounded resource changes through a caller-owned stat adapter
+ */
+export declare function applyStatPoolDelta<TOwnerId extends string, TStatId extends string>(access: StatPoolAccess<TOwnerId, TStatId>, ownerId: TOwnerId, statId: TStatId, amount: number): StatPoolAccessResult;

package/dist/stats/statPool.js

@@ -0,0 +1,62 @@
+import { clamp } from "../math/scalar.js";
+/**
+ * Normalize caller data into a complete plain-data pool.
+ *
+ * @capability stat-pool create a serializable current/min/max pool for any caller-named resource
+ */
+export function createStatPool(input) {
+    const min = input.min ?? 0;
+    return {
+        current: clamp(input.current ?? input.max, min, input.max),
+        max: input.max,
+        min,
+    };
+}
+/**
+ * Apply new bounds/current to a pool, clamping the result and leaving the input untouched.
+ *
+ * @capability stat-pool-patch immutably retune a bounded resource's current value or bounds
+ */
+export function patchStatPool(pool, patch) {
+    const max = patch.max ?? pool.max;
+    const min = patch.min ?? pool.min;
+    return {
+        current: clamp(patch.current ?? pool.current, min, max),
+        max,
+        min,
+    };
+}
+/**
+ * Pure bounded delta transition with the exact applied amount and boundary flags.
+ *
+ * @capability stat-pool-change immutably increase or decrease any named bounded resource with clamp evidence
+ */
+export function changeStatPool(pool, amount) {
+    const next = patchStatPool(pool, { current: pool.current + amount });
+    const applied = next.current - pool.current;
+    return {
+        previous: pool,
+        // Preserve the input reference on a no-op change (regen at max, damage at 0,
+        // clamp to a bound) so reference-equality guards in HUD hooks don't churn.
+        pool: applied === 0 ? pool : next,
+        applied,
+        hitMin: next.current === next.min,
+        hitMax: next.current === next.max,
+    };
+}
+/**
+ * Read, transition, and write a caller-owned pool through the structural
+ * adapter. Positive amounts increase the resource; negative amounts decrease
+ * it. The adapter receives a complete replacement value, never a hidden
+ * mutation.
+ *
+ * @capability portable-stat-pool apply deterministic bounded resource changes through a caller-owned stat adapter
+ */
+export function applyStatPoolDelta(access, ownerId, statId, amount) {
+    const pool = access.get(ownerId, statId);
+    if (pool === null)
+        return { status: "rejected", reason: `unknown stat "${statId}"` };
+    const change = changeStatPool(pool, amount);
+    access.set(ownerId, statId, change.pool);
+    return { status: "ok", ...change };
+}

package/dist/store/changeSignal.d.ts

@@ -1,7 +1,10 @@
+/** @internal */
 export interface ChangeSignal {
     subscribe(listener: () => void): () => void;
     notify(): void;
     version(): number;
 }
+/** @internal */
 export declare function createChangeSignal(): ChangeSignal;
+/** @internal */
 export declare function notifyAfter<T extends object, K extends keyof T>(target: T, methods: readonly K[], notify: () => void): T;

package/dist/store/changeSignal.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createChangeSignal() {
     const listeners = new Set();
     let version = 0;
@@ -18,6 +19,7 @@ export function createChangeSignal() {
         },
     };
 }
+/** @internal */
 export function notifyAfter(target, methods, notify) {
     const wrapped = { ...target };
     for (const method of methods) {

package/dist/store/observableKeyedStore.d.ts

@@ -1,3 +1,4 @@
+/** @internal */
 export interface ObservableKeyedStore<T> {
     set(key: string, value: T): void;
     delete(key: string): void;
@@ -16,4 +17,5 @@ export interface ObservableKeyedStore<T> {
     /** Replace all entries with `data` (clears keys absent from it), emitting once. */
     hydrate(data: readonly (readonly [string, T])[]): void;
 }
+/** @internal */
 export declare function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean): ObservableKeyedStore<T>;

package/dist/store/observableKeyedStore.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createObservableKeyedStore(areEqual) {
     const store = new Map();
     const listeners = new Set();

package/dist/survival/decayMeter.js

@@ -1,6 +1,4 @@
-function clamp(value, min, max) {
-    return value < min ? min : value > max ? max : value;
-}
+import { clamp } from "../math/scalar.js";
 function meterMin(def) {
     return def.min ?? 0;
 }

package/dist/survival/regionHealth.js

@@ -1,6 +1,4 @@
-function clamp(value, min, max) {
-    return value < min ? min : value > max ? max : value;
-}
+import { clamp } from "../math/scalar.js";
 /**
  * Per-region/limb health tracked separately, so each body part takes and heals damage on its own.
  *

package/dist/ui/hudLayout.d.ts

@@ -86,5 +86,10 @@ export declare function rectFromPlacement(placement: HudPlacement, size: HudSize
 export declare function registerActiveHudLayout(store: HudLayoutStore): () => void;
 /** @internal */
 export declare function listActiveHudLayouts(): HudLayoutStore[];
+/**
+ * @internal Notified whenever a `HudCanvas` mounts or unmounts (the active-layout set changes).
+ * Lets the editor's HUD-layout surface enable editing on layouts that mount after it opens.
+ */
+export declare function subscribeActiveHudLayouts(listener: () => void): () => void;
 /** @internal */
 export declare function createHudLayout(options?: HudLayoutOptions): HudLayoutStore;

package/dist/ui/hudLayout.js

@@ -116,17 +116,33 @@ function parseSerialized(raw) {
     return out;
 }
 const activeHudLayouts = new Set();
+const activeHudLayoutListeners = new Set();
 /** @internal Agent bridge seam — HudCanvas registers its store while mounted so headless drivers can reach canvas mode. */
 export function registerActiveHudLayout(store) {
     activeHudLayouts.add(store);
+    for (const listener of [...activeHudLayoutListeners])
+        listener();
     return () => {
-        activeHudLayouts.delete(store);
+        if (!activeHudLayouts.delete(store))
+            return;
+        for (const listener of [...activeHudLayoutListeners])
+            listener();
     };
 }
 /** @internal */
 export function listActiveHudLayouts() {
     return [...activeHudLayouts];
 }
+/**
+ * @internal Notified whenever a `HudCanvas` mounts or unmounts (the active-layout set changes).
+ * Lets the editor's HUD-layout surface enable editing on layouts that mount after it opens.
+ */
+export function subscribeActiveHudLayouts(listener) {
+    activeHudLayoutListeners.add(listener);
+    return () => {
+        activeHudLayoutListeners.delete(listener);
+    };
+}
 function panelToUi(panel) {
     const layout = {
         anchor: panel.placement.anchor,

package/dist/ui/panelModel.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Headless, serializable model for a set of player-toggled windows/panels — the data layer behind a
+ * WoW-style UI where B opens the bag, C the character sheet, and ESC closes the topmost window. It
+ * carries *which panels are open*, their focus/z stacking order, per-panel position overrides, and
+ * exclusive-group membership, with zero rendering opinion. The React chrome in
+ * `@jgengine/react/panels` consumes this; a game keeps layout, skin, keybinds, and window content
+ * caller-owned. Pure and immutable: every reducer returns a new state and never mutates its input.
+ */
+/** A pixel position override for a panel (top-left, relative to the host surface). */
+export interface PanelPosition {
+    x: number;
+    y: number;
+}
+/**
+ * A caller-authored panel/window declaration — the DATA input to the model. Only `id` is required so
+ * a bag, a character sheet, and a one-off dialog all share the shape.
+ */
+export interface PanelDef {
+    id: string;
+    /** Human title shown in the window's title bar; falls back to `id`. */
+    title?: string;
+    /** Keybind that opens/toggles the panel — a `KeyboardEvent.code` (`"KeyB"`) or key (`"b"`), matched case-insensitively by {@link panelByHotkey}. */
+    hotkey?: string;
+    /** Open on {@link createPanelState} (default false). */
+    initial?: boolean;
+    /** Exclusive group: opening one panel in a group closes the others in it (e.g. only one center window). */
+    group?: string;
+    /** Whether the player can close it (title-bar button / ESC). Default true; `false` pins it open. */
+    closable?: boolean;
+}
+/** @internal Serializable per-panel metadata lifted from {@link PanelDef} so reducers stay `(state, id)` pure. */
+export interface PanelMeta {
+    group?: string;
+    closable?: boolean;
+}
+/**
+ * Serializable state for a set of panels: which are `open`, their `z` focus stack (higher renders on
+ * top), optional per-panel `pos` overrides, and the `meta` registry (group/closable) captured from
+ * the defs so the reducers below need no defs argument. Plain JSON — persist and rehydrate it freely.
+ */
+export interface PanelState {
+    /** Open panels, keyed by id (`true` for open). Closed panels are absent. */
+    open: Record<string, true>;
+    /** z / focus order per open panel — the panel with the highest value is focused/on top. */
+    z: Record<string, number>;
+    /** Per-panel position overrides; remembered across close/reopen. */
+    pos: Record<string, PanelPosition>;
+    /** Group/closable metadata captured from the defs at construction. */
+    meta: Record<string, PanelMeta>;
+    /** Next z value to assign on open/focus — monotonic so focus order is deterministic. */
+    nextZ: number;
+}
+/**
+ * Build the initial {@link PanelState} from the panel defs: panels flagged `initial` start open (in
+ * declaration order, respecting group exclusivity), and every def's group/closable is captured into
+ * the state so later reducers need no defs.
+ *
+ * @capability panel-state serializable open/z/position state for a set of toggleable game windows
+ */
+export declare function createPanelState(defs: readonly PanelDef[]): PanelState;
+/** Whether panel `id` is currently open. */
+export declare function isOpen(state: PanelState, id: string): boolean;
+/**
+ * Open panel `id`, raising it to the top of the focus stack. If it belongs to a `group`, the other
+ * open panels in that group are closed (exclusive windows). Opening an already-open panel just
+ * refocuses it. Position overrides are preserved.
+ *
+ * @capability panel-open open a window, raise its z, and enforce exclusive-group membership
+ */
+export declare function openPanel(state: PanelState, id: string): PanelState;
+/**
+ * Close panel `id`. No-op if it is already closed. Its position override is kept so reopening restores
+ * the last placement.
+ *
+ * @capability panel-close close a window while remembering its last position
+ */
+export declare function closePanel(state: PanelState, id: string): PanelState;
+/**
+ * Toggle panel `id` — open it (with group exclusivity) if closed, close it if open. The one-key
+ * behavior behind a keybind like `B` for the bag.
+ *
+ * @capability panel-toggle toggle a window open/closed from a single keybind
+ */
+export declare function togglePanel(state: PanelState, id: string): PanelState;
+/**
+ * Raise open panel `id` to the top of the focus stack (assign it the highest z). No-op if it is
+ * closed or already on top, so a pointer-down that refocuses the top window returns the same state.
+ *
+ * @capability panel-focus raise a window to the top of the focus/z stack
+ */
+export declare function focusPanel(state: PanelState, id: string): PanelState;
+/**
+ * Close the topmost closable open panel — the ESC handler. Skips panels pinned with `closable: false`
+ * and returns the same state when nothing closable is open.
+ *
+ * @capability panel-close-top close the focused (topmost) closable window — the ESC behavior
+ */
+export declare function closeTopPanel(state: PanelState): PanelState;
+/**
+ * Find the panel whose `hotkey` matches `code`, case-insensitively — the keybind router. `code` may be
+ * a `KeyboardEvent.code` (`"KeyB"`) or key (`"b"`); it is compared verbatim to each def's `hotkey`, so
+ * author the hotkey in whichever form the caller feeds in. Returns the first match's id, or null.
+ *
+ * @capability panel-hotkey resolve a keybind (code or key) to the panel id it toggles
+ */
+export declare function panelByHotkey(defs: readonly PanelDef[], code: string): string | null;
+/**
+ * Set panel `id`'s position override — the drag commit. Does not require the panel to be open, so a
+ * caller can pre-place a window before it is shown.
+ *
+ * @capability panel-move override a window's on-surface position (the drag commit)
+ */
+export declare function movePanel(state: PanelState, id: string, pos: PanelPosition): PanelState;
+/**
+ * The open panels' defs sorted ascending by z — the render order for a window host (map to elements
+ * so the last, highest-z window paints on top). Defs unknown to the state are skipped.
+ *
+ * @capability panel-ordered-open open panels' defs in z/render order for a window host
+ */
+export declare function orderedOpen(state: PanelState, defs: readonly PanelDef[]): PanelDef[];