@jgengine/core 0.9.0 → 0.11.0

package/dist/game/systemRuntime.js

@@ -0,0 +1,157 @@
+import { compileSystemSchedule, } from "./systemSchedule.js";
+function resolveModule(spec, ctx) {
+    if (spec === undefined)
+        return undefined;
+    return typeof spec === "function" ? spec(ctx) : spec;
+}
+/**
+ * Install systems on a live context: `create` → bind events → register save/replicate → `start`.
+ * Call once per world boot (from the composed loop's `onInit`).
+ * @internal
+ */
+export function installSystems(ctx, systems, options) {
+    const schedule = compileSystemSchedule(systems, options);
+    const list = systems;
+    const unsubs = [];
+    const intervalAcc = new Map();
+    const fixedAcc = new Map();
+    for (const system of list) {
+        system.create?.(ctx);
+    }
+    for (const system of list) {
+        if (system.events !== undefined) {
+            for (const [name, handler] of Object.entries(system.events)) {
+                if (handler === undefined)
+                    continue;
+                const off = ctx.game.events.on(name, ((event) => {
+                    handler(ctx, event);
+                }));
+                unsubs.push(off);
+            }
+        }
+        const save = resolveModule(system.save, ctx);
+        if (save !== undefined)
+            options?.modules?.registerSave(save);
+        const replicate = resolveModule(system.replicate, ctx);
+        if (replicate !== undefined)
+            options?.modules?.registerReplicate(replicate);
+    }
+    for (const system of list) {
+        system.start?.(ctx);
+    }
+    for (const group of schedule.fixed) {
+        fixedAcc.set(group.rate, 0);
+    }
+    for (const interval of schedule.intervals) {
+        intervalAcc.set(interval.id, 0);
+    }
+    function runIds(ctx, ids, dt) {
+        for (const id of ids) {
+            schedule.systemsById.get(id)?.update?.(ctx, dt);
+        }
+    }
+    function tick(ctx, dt) {
+        if (!(dt > 0))
+            return;
+        for (const group of schedule.fixed) {
+            const step = 1 / group.rate;
+            let acc = (fixedAcc.get(group.rate) ?? 0) + dt;
+            while (acc >= step) {
+                runIds(ctx, group.order, step);
+                acc -= step;
+            }
+            fixedAcc.set(group.rate, acc);
+        }
+        runIds(ctx, schedule.frameOrder, dt);
+        for (const interval of schedule.intervals) {
+            const every = interval.every ?? 1;
+            let acc = (intervalAcc.get(interval.id) ?? 0) + dt;
+            while (acc >= every) {
+                schedule.systemsById.get(interval.id)?.update?.(ctx, every);
+                acc -= every;
+            }
+            intervalAcc.set(interval.id, acc);
+        }
+    }
+    function reset(ctx) {
+        for (const system of list)
+            system.reset?.(ctx);
+        for (const group of schedule.fixed)
+            fixedAcc.set(group.rate, 0);
+        for (const interval of schedule.intervals)
+            intervalAcc.set(interval.id, 0);
+    }
+    function dispose(ctx) {
+        for (const off of unsubs)
+            off();
+        unsubs.length = 0;
+        for (let i = list.length - 1; i >= 0; i -= 1) {
+            list[i]?.dispose?.(ctx);
+        }
+    }
+    function runManual(ctx, id, dt = 0) {
+        if (!schedule.manual.includes(id))
+            return;
+        schedule.systemsById.get(id)?.update?.(ctx, dt);
+    }
+    return { schedule, tick, reset, dispose, runManual };
+}
+const installedByCtx = new WeakMap();
+/**
+ * Look up systems installed on `ctx` (if any). Used by hosts that need `reset`/`dispose` after boot.
+ * @internal
+ */
+export function systemsOf(ctx) {
+    return installedByCtx.get(ctx);
+}
+/**
+ * Merge a system list with an optional classic `GameLoop` into one loop the shell/runners drive.
+ * Systems install on first `onInit`; classic hooks still run for incremental migration.
+ *
+ * @capability compose-game-loop fold composable systems into the game loop without a manual tick fan-out
+ */
+export function composeGameLoop(systems, loop, options) {
+    if (systems === undefined || systems.length === 0) {
+        return loop ?? {};
+    }
+    let installed;
+    const loopBefore = options?.loopBeforeSystems === true;
+    return {
+        onInit(ctx) {
+            const modules = ctx.game.registerSave !== undefined && ctx.game.registerReplicate !== undefined
+                ? {
+                    registerSave: (m) => ctx.game.registerSave(m),
+                    registerReplicate: (m) => ctx.game.registerReplicate(m),
+                }
+                : undefined;
+            installed = installSystems(ctx, systems, { ...options, modules });
+            installedByCtx.set(ctx, installed);
+            loop?.onInit?.(ctx);
+        },
+        onNewPlayer(ctx, player) {
+            loop?.onNewPlayer?.(ctx, player);
+        },
+        onTick(ctx, dt) {
+            if (loopBefore) {
+                loop?.onTick?.(ctx, dt);
+                installed?.tick(ctx, dt);
+            }
+            else {
+                installed?.tick(ctx, dt);
+                loop?.onTick?.(ctx, dt);
+            }
+        },
+        onPlayerLeave(ctx, player) {
+            loop?.onPlayerLeave?.(ctx, player);
+        },
+        onReset(ctx) {
+            installed?.reset(ctx);
+            loop?.onReset?.(ctx);
+        },
+        onDispose(ctx) {
+            installed?.dispose(ctx);
+            installedByCtx.delete(ctx);
+            loop?.onDispose?.(ctx);
+        },
+    };
+}

package/dist/game/systemSchedule.d.ts

@@ -0,0 +1,72 @@
+import type { SystemDefinition } from "./defineSystem.js";
+/** Default fixed-sim stage order — systems pick a stage; most need only this. */
+export declare const DEFAULT_FIXED_STAGES: readonly ["input", "movement", "combat", "ai", "activities", "cleanup"];
+/**
+ * Default frame stage order. Gameplay stages mirror the fixed table so once-per-frame systems
+ * (`type: "frame"`) can pick `combat`/`ai`/… without falling into the unknown-stage bucket;
+ * presentation stages follow.
+ */
+export declare const DEFAULT_FRAME_STAGES: readonly ["input", "movement", "combat", "ai", "activities", "cleanup", "animation", "camera", "effects"];
+/** @internal */
+export type TimingChannel = "fixed" | "frame" | "interval" | "manual" | "event";
+/** @internal */
+export interface ScheduledSystem {
+    readonly id: string;
+    readonly channel: TimingChannel;
+    readonly stage: string;
+    readonly rate?: number;
+    readonly every?: number;
+    readonly after: readonly string[];
+    readonly before: readonly string[];
+    readonly dependsOn: readonly string[];
+}
+/** @internal */
+export interface StageBucket {
+    readonly stage: string;
+    /** System ids in deterministic order within this stage. */
+    readonly systems: readonly string[];
+}
+/** @internal */
+export interface FixedRateGroup {
+    readonly rate: number;
+    readonly stages: readonly StageBucket[];
+    /** Flat ordered ids for this rate (all stages). */
+    readonly order: readonly string[];
+}
+/**
+ * Deterministic compiled schedule: stage buckets, multi-subscribe channels, dependency validation.
+ * Order never depends on import order — only stage tables + explicit before/after constraints.
+ */
+export interface CompiledSystemSchedule {
+    readonly systemsById: ReadonlyMap<string, SystemDefinition>;
+    readonly scheduled: readonly ScheduledSystem[];
+    /** Fixed-sim groups keyed by rate (Hz); multiple systems may share a rate. */
+    readonly fixed: readonly FixedRateGroup[];
+    readonly frame: readonly StageBucket[];
+    readonly frameOrder: readonly string[];
+    /** Interval systems — each keeps its own period; multi-subscribe is per-system. */
+    readonly intervals: readonly ScheduledSystem[];
+    readonly manual: readonly string[];
+    readonly eventOnly: readonly string[];
+    /** All auto-ticking systems in a diagnostic flat order (fixed rates → frame → intervals). */
+    readonly tickOrder: readonly string[];
+}
+/** @internal */
+export interface CompileSystemScheduleOptions {
+    fixedStages?: readonly string[];
+    frameStages?: readonly string[];
+    defaultFixedRate?: number;
+}
+/**
+ * Topological sort with a stable tie-break on original declaration index, then id.
+ * Edges: `after: "x"` means this runs after x (x → this); `before: "y"` means this → y.
+ * @internal
+ */
+export declare function orderWithConstraints(ids: readonly string[], after: ReadonlyMap<string, readonly string[]>, before: ReadonlyMap<string, readonly string[]>, indexOf: ReadonlyMap<string, number>): string[];
+/**
+ * Compile system definitions into a deterministic schedule.
+ * Validates unique ids, `dependsOn`, and before/after cycles.
+ *
+ * @capability system-schedule compile fixed/frame/interval system ticks into deterministic ordered stages
+ */
+export declare function compileSystemSchedule(systems: readonly SystemDefinition[], options?: CompileSystemScheduleOptions): CompiledSystemSchedule;

package/dist/game/systemSchedule.js

@@ -0,0 +1,242 @@
+/** Default fixed-sim stage order — systems pick a stage; most need only this. */
+export const DEFAULT_FIXED_STAGES = [
+    "input",
+    "movement",
+    "combat",
+    "ai",
+    "activities",
+    "cleanup",
+];
+/**
+ * Default frame stage order. Gameplay stages mirror the fixed table so once-per-frame systems
+ * (`type: "frame"`) can pick `combat`/`ai`/… without falling into the unknown-stage bucket;
+ * presentation stages follow.
+ */
+export const DEFAULT_FRAME_STAGES = [
+    "input",
+    "movement",
+    "combat",
+    "ai",
+    "activities",
+    "cleanup",
+    "animation",
+    "camera",
+    "effects",
+];
+const DEFAULT_FIXED_RATE = 60;
+function asList(value) {
+    if (value === undefined)
+        return [];
+    return typeof value === "string" ? [value] : value;
+}
+function channelOf(tick) {
+    if (tick === undefined)
+        return "event";
+    return tick.type;
+}
+function stageOf(tick, channel) {
+    if (tick === undefined || tick.type === "manual")
+        return "";
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return tick.stage ?? defaultStage(channel);
+    }
+    return "";
+}
+function defaultStage(channel) {
+    if (channel === "fixed")
+        return "combat";
+    if (channel === "frame")
+        return "effects";
+    if (channel === "interval")
+        return "activities";
+    return "";
+}
+function rateOf(tick, defaultFixedRate) {
+    if (tick?.type === "fixed")
+        return tick.rate ?? defaultFixedRate;
+    return undefined;
+}
+function everyOf(tick) {
+    if (tick?.type === "interval")
+        return tick.every;
+    return undefined;
+}
+function afterOf(tick) {
+    if (tick === undefined || tick.type === "manual")
+        return [];
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return asList(tick.after);
+    }
+    return [];
+}
+function beforeOf(tick) {
+    if (tick === undefined || tick.type === "manual")
+        return [];
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return asList(tick.before);
+    }
+    return [];
+}
+/**
+ * Topological sort with a stable tie-break on original declaration index, then id.
+ * Edges: `after: "x"` means this runs after x (x → this); `before: "y"` means this → y.
+ * @internal
+ */
+export function orderWithConstraints(ids, after, before, indexOf) {
+    const idSet = new Set(ids);
+    const preds = new Map();
+    const succs = new Map();
+    for (const id of ids) {
+        preds.set(id, new Set());
+        succs.set(id, new Set());
+    }
+    const addEdge = (from, to) => {
+        if (!idSet.has(from) || !idSet.has(to) || from === to)
+            return;
+        succs.get(from).add(to);
+        preds.get(to).add(from);
+    };
+    for (const id of ids) {
+        for (const a of after.get(id) ?? [])
+            addEdge(a, id);
+        for (const b of before.get(id) ?? [])
+            addEdge(id, b);
+    }
+    const ready = ids
+        .filter((id) => preds.get(id).size === 0)
+        .sort((a, b) => {
+        const ia = indexOf.get(a) ?? 0;
+        const ib = indexOf.get(b) ?? 0;
+        if (ia !== ib)
+            return ia - ib;
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+    const ordered = [];
+    while (ready.length > 0) {
+        const next = ready.shift();
+        ordered.push(next);
+        for (const succ of succs.get(next) ?? []) {
+            const set = preds.get(succ);
+            set.delete(next);
+            if (set.size === 0) {
+                ready.push(succ);
+                ready.sort((a, b) => {
+                    const ia = indexOf.get(a) ?? 0;
+                    const ib = indexOf.get(b) ?? 0;
+                    if (ia !== ib)
+                        return ia - ib;
+                    return a < b ? -1 : a > b ? 1 : 0;
+                });
+            }
+        }
+    }
+    if (ordered.length !== ids.length) {
+        const leftover = ids.filter((id) => !ordered.includes(id));
+        throw new Error(`system schedule: cyclic before/after constraints among: ${leftover.join(", ")}`);
+    }
+    return ordered;
+}
+function bucketByStage(items, stageOrder, indexOf) {
+    const stageIndex = new Map();
+    stageOrder.forEach((s, i) => stageIndex.set(s, i));
+    const unknownStages = new Set();
+    for (const item of items) {
+        if (item.stage !== "" && !stageIndex.has(item.stage))
+            unknownStages.add(item.stage);
+    }
+    const stages = [...stageOrder, ...[...unknownStages].sort()];
+    const buckets = [];
+    for (const stage of stages) {
+        const inStage = items.filter((s) => s.stage === stage);
+        if (inStage.length === 0)
+            continue;
+        const after = new Map();
+        const before = new Map();
+        for (const s of inStage) {
+            after.set(s.id, s.after);
+            before.set(s.id, s.before);
+        }
+        const order = orderWithConstraints(inStage.map((s) => s.id), after, before, indexOf);
+        buckets.push({ stage, systems: order });
+    }
+    return buckets;
+}
+/**
+ * Compile system definitions into a deterministic schedule.
+ * Validates unique ids, `dependsOn`, and before/after cycles.
+ *
+ * @capability system-schedule compile fixed/frame/interval system ticks into deterministic ordered stages
+ */
+export function compileSystemSchedule(systems, options) {
+    const fixedStages = options?.fixedStages ?? DEFAULT_FIXED_STAGES;
+    const frameStages = options?.frameStages ?? DEFAULT_FRAME_STAGES;
+    const defaultFixedRate = options?.defaultFixedRate ?? DEFAULT_FIXED_RATE;
+    const systemsById = new Map();
+    const indexOf = new Map();
+    systems.forEach((system, index) => {
+        if (systemsById.has(system.id)) {
+            throw new Error(`system schedule: duplicate system id "${system.id}"`);
+        }
+        systemsById.set(system.id, system);
+        indexOf.set(system.id, index);
+    });
+    for (const system of systems) {
+        for (const dep of system.dependsOn ?? []) {
+            if (!systemsById.has(dep)) {
+                throw new Error(`system schedule: "${system.id}" dependsOn unknown system "${dep}"`);
+            }
+        }
+    }
+    const scheduled = systems.map((system) => {
+        const channel = channelOf(system.tick);
+        return {
+            id: system.id,
+            channel,
+            stage: stageOf(system.tick, channel),
+            rate: rateOf(system.tick, defaultFixedRate),
+            every: everyOf(system.tick),
+            after: afterOf(system.tick),
+            before: beforeOf(system.tick),
+            dependsOn: system.dependsOn ?? [],
+        };
+    });
+    const fixedItems = scheduled.filter((s) => s.channel === "fixed");
+    const rates = [...new Set(fixedItems.map((s) => s.rate ?? defaultFixedRate))].sort((a, b) => b - a);
+    const fixed = rates.map((rate) => {
+        const group = fixedItems.filter((s) => (s.rate ?? defaultFixedRate) === rate);
+        const stages = bucketByStage(group, fixedStages, indexOf);
+        return {
+            rate,
+            stages,
+            order: stages.flatMap((b) => b.systems),
+        };
+    });
+    const frameItems = scheduled.filter((s) => s.channel === "frame");
+    const frame = bucketByStage(frameItems, frameStages, indexOf);
+    const frameOrder = frame.flatMap((b) => b.systems);
+    const intervals = scheduled.filter((s) => s.channel === "interval");
+    // Stable order for intervals: stage buckets then constraints across all interval systems
+    const intervalBuckets = bucketByStage(intervals, fixedStages, indexOf);
+    const intervalOrder = intervalBuckets.flatMap((b) => b.systems);
+    const intervalsOrdered = intervalOrder.map((id) => intervals.find((s) => s.id === id));
+    const manual = scheduled.filter((s) => s.channel === "manual").map((s) => s.id);
+    const eventOnly = scheduled
+        .filter((s) => s.channel === "event")
+        .map((s) => s.id);
+    const tickOrder = [
+        ...fixed.flatMap((g) => g.order),
+        ...frameOrder,
+        ...intervalOrder,
+    ];
+    return {
+        systemsById,
+        scheduled,
+        fixed,
+        frame,
+        frameOrder,
+        intervals: intervalsOrdered,
+        manual,
+        eventOnly,
+        tickOrder,
+    };
+}

package/dist/game/toasts.d.ts

@@ -0,0 +1,43 @@
+/** A transient HUD message that expires on its own — banner, pickup note, alert. */
+export interface Toast<T = string> {
+    /** Stable id for keying in a UI list. */
+    id: string;
+    /** Message payload (a string, or any structured content the HUD renders). */
+    body: T;
+    /** Wall-clock time (seconds) after which the toast should be dropped. */
+    expiresAt: number;
+}
+/**
+ * Append `toast`, keeping only the newest `cap` entries.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export declare function appendToast<T>(toasts: readonly Toast<T>[], toast: Toast<T>, cap: number): readonly Toast<T>[];
+/** Drop every toast whose `expiresAt` is at or before `now`. Returns the same array when nothing expired. */
+export declare function pruneToasts<T>(toasts: readonly Toast<T>[], now: number): readonly Toast<T>[];
+/** Stateful transient-toast list with a size cap and time-to-live eviction. */
+export interface ToastQueue<T = string> {
+    /** Raise a toast at `now` living `ttlSeconds` (falling back to the queue default); returns it. */
+    push(body: T, now: number, ttlSeconds?: number): Toast<T>;
+    /** Evict toasts that have expired as of `now`. */
+    prune(now: number): void;
+    /** Current live toasts, oldest first. */
+    list(): readonly Toast<T>[];
+    /** Remove all toasts. */
+    clear(): void;
+}
+/** Options for {@link createToastQueue}. */
+export interface ToastQueueOptions {
+    /** Maximum toasts retained; older ones fall off. Defaults to 4. */
+    cap?: number;
+    /** Default lifetime in seconds when `push` is not given one. Defaults to 3. */
+    ttlSeconds?: number;
+}
+/**
+ * A capped, self-expiring toast queue — the append-with-limit plus TTL-prune list every HUD hand-rolled
+ * on top of a plain array. Feed it game time: `push` raises a message, `prune(now)` drops expired ones,
+ * `list()` is what the HUD renders. Unlike the append-only event feed, toasts evict themselves.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export declare function createToastQueue<T = string>(options?: ToastQueueOptions): ToastQueue<T>;

package/dist/game/toasts.js

@@ -0,0 +1,44 @@
+/**
+ * Append `toast`, keeping only the newest `cap` entries.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export function appendToast(toasts, toast, cap) {
+    const next = [...toasts, toast];
+    return cap > 0 && next.length > cap ? next.slice(next.length - cap) : next;
+}
+/** Drop every toast whose `expiresAt` is at or before `now`. Returns the same array when nothing expired. */
+export function pruneToasts(toasts, now) {
+    const kept = toasts.filter((toast) => toast.expiresAt > now);
+    return kept.length === toasts.length ? toasts : kept;
+}
+/**
+ * A capped, self-expiring toast queue — the append-with-limit plus TTL-prune list every HUD hand-rolled
+ * on top of a plain array. Feed it game time: `push` raises a message, `prune(now)` drops expired ones,
+ * `list()` is what the HUD renders. Unlike the append-only event feed, toasts evict themselves.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export function createToastQueue(options = {}) {
+    const cap = options.cap ?? 4;
+    const defaultTtl = options.ttlSeconds ?? 3;
+    let toasts = [];
+    let counter = 0;
+    return {
+        push(body, now, ttlSeconds) {
+            const toast = { id: `toast-${counter}`, body, expiresAt: now + (ttlSeconds ?? defaultTtl) };
+            counter += 1;
+            toasts = appendToast(toasts, toast, cap);
+            return toast;
+        },
+        prune(now) {
+            toasts = pruneToasts(toasts, now);
+        },
+        list() {
+            return toasts;
+        },
+        clear() {
+            toasts = [];
+        },
+    };
+}

package/dist/game/trade.d.ts

@@ -32,6 +32,7 @@ export interface TradeSystem {
     sell(itemId: string, count: number | undefined, party: TradeParty): TradeRejection | null;
     tradableAt(shopId: string, allItemIds: string[]): string[];
 }
+/** @internal */
 export declare function canAffordCosts(balances: Record<string, number>, costs: Record<string, number>): string | null;
 export interface TradeOutcome {
     itemId: string;
@@ -45,8 +46,11 @@ export type TradeResolution = {
     status: "rejected";
     reason: string;
 };
+/** @internal */
 export declare function resolveBuy(itemId: string, trade: TradeField | null | undefined, shopId: string, count: number, balances: Record<string, number>): TradeResolution;
+/** @internal */
 export declare function resolveSell(itemId: string, trade: TradeField | null | undefined, count: number): TradeResolution;
+/** @internal */
 export declare function applyTradeOutcome(outcome: TradeOutcome, appliers: {
     adjustItem(itemId: string, count: number): {
         reason: string;
@@ -55,4 +59,10 @@ export declare function applyTradeOutcome(outcome: TradeOutcome, appliers: {
 }): {
     reason: string;
 } | null;
+/**
+ * Buy and sell goods against player currency balances, resolving affordability and price.
+ *
+ * @capability shop-trade buy and sell goods against player currency balances
+  * @internal
+  */
 export declare function createTradeSystem(deps: TradeSystemDeps): TradeSystem;

package/dist/game/trade.js

@@ -10,6 +10,7 @@ function negate(amounts) {
         out[currency] = -amount;
     return out;
 }
+/** @internal */
 export function canAffordCosts(balances, costs) {
     for (const [currency, amount] of Object.entries(costs)) {
         if ((balances[currency] ?? 0) < amount)
@@ -27,6 +28,7 @@ function buyEligibility(trade, shopId) {
 function sellEligibility(trade) {
     return trade?.sell ? null : "not-sellable";
 }
+/** @internal */
 export function resolveBuy(itemId, trade, shopId, count, balances) {
     const ineligible = buyEligibility(trade, shopId);
     if (ineligible)
@@ -37,12 +39,14 @@ export function resolveBuy(itemId, trade, shopId, count, balances) {
         return { status: "rejected", reason: unaffordable };
     return { status: "ok", outcome: { itemId, count, currency: negate(costs) } };
 }
+/** @internal */
 export function resolveSell(itemId, trade, count) {
     const ineligible = sellEligibility(trade);
     if (ineligible)
         return { status: "rejected", reason: ineligible };
     return { status: "ok", outcome: { itemId, count: -count, currency: scale(trade.sell, count) } };
 }
+/** @internal */
 export function applyTradeOutcome(outcome, appliers) {
     const itemResult = appliers.adjustItem(outcome.itemId, outcome.count);
     if (itemResult)
@@ -50,6 +54,12 @@ export function applyTradeOutcome(outcome, appliers) {
     appliers.adjustCurrency(outcome.currency);
     return null;
 }
+/**
+ * Buy and sell goods against player currency balances, resolving affordability and price.
+ *
+ * @capability shop-trade buy and sell goods against player currency balances
+  * @internal
+  */
 export function createTradeSystem(deps) {
     const { resolveTrade, wallet, inventory } = deps;
     function canBuy(itemId, shopId, count = 1) {

package/dist/game/unlocks.d.ts

@@ -10,6 +10,11 @@ export interface UnlockCatalog {
     has(unlockId: string): boolean;
     tree(categoryId: string): UnlockDef[];
 }
+/**
+ * A catalog of unlockable content gated behind conditions the player earns, tracking what is unlocked.
+ *
+ * @capability unlockables gate content behind unlock conditions the player earns
+ */
 export declare function createUnlockCatalog(defs?: readonly UnlockDef[]): UnlockCatalog;
 export interface Unlocks {
     has(userId: string, unlockId: string): boolean;
@@ -18,5 +23,8 @@ export interface Unlocks {
     tree(categoryId: string): UnlockDef[];
     snapshot(userId: string): string[];
     hydrate(userId: string, ids: string[]): void;
+    /** Whole-store capture across every user — the world-save/replication seam (per-user `snapshot` can't enumerate users). */
+    snapshotAll(): Record<string, string[]>;
+    hydrateAll(data: Record<string, string[]>): void;
 }
 export declare function createUnlocks(defs?: UnlockDef[]): Unlocks;

package/dist/game/unlocks.js

@@ -7,6 +7,11 @@ export function grantUnlock(granted, unlockId) {
 export function unlockTree(defs, categoryId) {
     return defs.filter((def) => def.category === categoryId);
 }
+/**
+ * A catalog of unlockable content gated behind conditions the player earns, tracking what is unlocked.
+ *
+ * @capability unlockables gate content behind unlock conditions the player earns
+ */
 export function createUnlockCatalog(defs = []) {
     const byId = new Map();
     for (const def of defs)
@@ -48,5 +53,16 @@ export function createUnlocks(defs = []) {
         hydrate(userId, ids) {
             granted.set(userId, new Set(ids));
         },
+        snapshotAll() {
+            const out = {};
+            for (const [userId, ids] of granted)
+                out[userId] = Array.from(ids);
+            return out;
+        },
+        hydrateAll(data) {
+            granted.clear();
+            for (const [userId, ids] of Object.entries(data))
+                granted.set(userId, new Set(ids));
+        },
     };
 }