@jgengine/core 0.9.0 → 0.11.0

package/dist/game/saveStore.js

@@ -0,0 +1,312 @@
+import { defaultKeyValueStorage } from "./keyValueStore.js";
+function readSafe(storage, key) {
+    if (storage === null)
+        return null;
+    try {
+        return storage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A {@link SaveBackend} over a synchronous {@link KeyValueStorage} — the
+ * browser's `localStorage` by default (offline, on-device saves), a test stub,
+ * or `null` for memory-only. Storage errors (quota exceeded, private mode, no
+ * DOM) degrade to no-ops, so a save never throws into a game tick.
+ *
+ * @capability local-save persist a game to on-device localStorage (offline)
+ */
+export function localSaveBackend(storage) {
+    const store = storage === undefined ? defaultKeyValueStorage() : storage;
+    return {
+        read: (key) => Promise.resolve(readSafe(store, key)),
+        write: (key, value) => {
+            if (store !== null) {
+                try {
+                    store.setItem(key, value);
+                }
+                catch {
+                    // storage rejected the write; the store keeps the value in memory
+                }
+            }
+            return Promise.resolve();
+        },
+        remove: (key) => {
+            if (store !== null) {
+                try {
+                    store.removeItem(key);
+                }
+                catch {
+                    // ignore removal failure
+                }
+            }
+            return Promise.resolve();
+        },
+    };
+}
+/** A memory-only {@link SaveBackend} — saves survive a reload only within the same session. For tests, SSR, or a "no persistence" mode that still exercises the same save code path. */
+export function memorySaveBackend() {
+    const map = new Map();
+    return {
+        read: (key) => Promise.resolve(map.get(key) ?? null),
+        write: (key, value) => {
+            map.set(key, value);
+            return Promise.resolve();
+        },
+        remove: (key) => {
+            map.delete(key);
+            return Promise.resolve();
+        },
+    };
+}
+/** Adopt any async `read`/`write`/`remove` trio as a {@link SaveBackend} — the seam for cloud saves backed by a database, an HTTP endpoint, or Convex (see `@jgengine/convex/convexSaveBackend`). Reads/writes may reject; the save store surfaces the failure as `"error"` status instead of throwing. */
+export function remoteSaveBackend(backend) {
+    return backend;
+}
+function defaultTimers() {
+    return {
+        set: (handler, ms) => globalThis.setTimeout(handler, ms),
+        clear: (handle) => globalThis.clearTimeout(handle),
+    };
+}
+function normalizeAuto(config) {
+    if (config === undefined || config === false)
+        return null;
+    if (config === true)
+        return { debounceMs: 1000, maxWaitMs: 15000 };
+    return { debounceMs: config.debounceMs ?? 1000, maxWaitMs: config.maxWaitMs ?? 15000 };
+}
+function isEnvelope(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.version === "number" &&
+        "value" in value);
+}
+/**
+ * Create a {@link SaveStore}. Same call for offline and cloud — only the
+ * `backend` differs (localStorage, memory, or an async DB/Convex endpoint). Turn
+ * on `autosave` and every `set`/`patch` persists on a debounce; leave it off and
+ * call `save()` at checkpoints. Bump `version` + pass `migrate` when the save
+ * shape changes so old players keep their progress.
+ *
+ * @capability game-save save/load game state with a pluggable backend, autosave, slots, and migration
+ */
+export function createSaveStore(config) {
+    const namespace = config.key ?? "save";
+    const formatVersion = config.version ?? 1;
+    const initial = config.initial;
+    const backend = config.backend;
+    const clock = config.now ?? (() => Date.now());
+    const timers = config.timers ?? defaultTimers();
+    const auto = normalizeAuto(config.autosave);
+    const serialize = config.serialize ?? ((envelope) => JSON.stringify(envelope));
+    const deserialize = config.deserialize ?? ((raw) => JSON.parse(raw));
+    const onError = config.onError;
+    let currentSlot = config.slot ?? "default";
+    let current = initial;
+    let status = "idle";
+    let revision = 0;
+    let dirty = false;
+    let firstDirtyAt = null;
+    let pendingTimer = null;
+    let saveChain = Promise.resolve();
+    let disposed = false;
+    const listeners = new Set();
+    function emit() {
+        revision += 1;
+        for (const listener of listeners)
+            listener();
+    }
+    function setStatus(next) {
+        if (status === next)
+            return;
+        status = next;
+        emit();
+    }
+    function reportError(error) {
+        onError?.(error);
+    }
+    const dataKey = (slot) => `${namespace}:${slot}`;
+    const indexKey = () => `${namespace}:__slots__`;
+    function decode(raw) {
+        const parsed = deserialize(raw);
+        if (isEnvelope(parsed)) {
+            if (parsed.version === formatVersion)
+                return parsed.value;
+            if (config.migrate)
+                return config.migrate(parsed.value, parsed.version);
+            return parsed.value;
+        }
+        if (config.migrate)
+            return config.migrate(parsed, 0);
+        return parsed;
+    }
+    async function readSlots() {
+        try {
+            const raw = await backend.read(indexKey());
+            if (raw === null)
+                return [];
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed.filter((entry) => typeof entry === "string") : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async function rememberSlot(slot) {
+        try {
+            const list = await readSlots();
+            if (list.includes(slot))
+                return;
+            await backend.write(indexKey(), JSON.stringify([...list, slot]));
+        }
+        catch (error) {
+            reportError(error);
+        }
+    }
+    async function forgetSlot(slot) {
+        try {
+            const list = await readSlots();
+            if (!list.includes(slot))
+                return;
+            await backend.write(indexKey(), JSON.stringify(list.filter((entry) => entry !== slot)));
+        }
+        catch (error) {
+            reportError(error);
+        }
+    }
+    function clearTimer() {
+        if (pendingTimer !== null) {
+            timers.clear(pendingTimer);
+            pendingTimer = null;
+        }
+    }
+    function markDirty() {
+        dirty = true;
+        if (auto === null)
+            return;
+        const now = clock();
+        if (firstDirtyAt === null)
+            firstDirtyAt = now;
+        if (auto.maxWaitMs > 0 && now - firstDirtyAt >= auto.maxWaitMs) {
+            clearTimer();
+            void save();
+            return;
+        }
+        clearTimer();
+        pendingTimer = timers.set(() => {
+            pendingTimer = null;
+            void save();
+        }, auto.debounceMs);
+    }
+    async function flush() {
+        if (disposed)
+            return;
+        clearTimer();
+        const slot = currentSlot;
+        const value = current;
+        setStatus("saving");
+        try {
+            const envelope = { version: formatVersion, savedAt: clock(), value };
+            await backend.write(dataKey(slot), serialize(envelope));
+            await rememberSlot(slot);
+            if (current === value) {
+                dirty = false;
+                firstDirtyAt = null;
+            }
+            setStatus("saved");
+        }
+        catch (error) {
+            setStatus("error");
+            reportError(error);
+        }
+    }
+    function save() {
+        const run = saveChain.then(() => flush());
+        saveChain = run.catch(() => undefined);
+        return run;
+    }
+    async function load() {
+        setStatus("loading");
+        try {
+            const raw = await backend.read(dataKey(currentSlot));
+            let value;
+            try {
+                value = raw === null ? initial : decode(raw);
+            }
+            catch {
+                value = initial;
+            }
+            current = value;
+            dirty = false;
+            firstDirtyAt = null;
+            setStatus("idle");
+            emit();
+            void rememberSlot(currentSlot);
+            return current;
+        }
+        catch (error) {
+            setStatus("error");
+            reportError(error);
+            return current;
+        }
+    }
+    return {
+        value: () => current,
+        status: () => status,
+        slot: () => currentSlot,
+        revision: () => revision,
+        load,
+        set(value) {
+            current = value;
+            emit();
+            markDirty();
+        },
+        patch(mutate) {
+            current = mutate(current);
+            emit();
+            markDirty();
+            return current;
+        },
+        save,
+        async clear() {
+            clearTimer();
+            const slot = currentSlot;
+            setStatus("saving");
+            try {
+                await backend.remove(dataKey(slot));
+                await forgetSlot(slot);
+                current = initial;
+                dirty = false;
+                firstDirtyAt = null;
+                setStatus("idle");
+                emit();
+            }
+            catch (error) {
+                setStatus("error");
+                reportError(error);
+            }
+        },
+        async switchSlot(slot) {
+            if (dirty)
+                await save();
+            clearTimer();
+            currentSlot = slot;
+            current = initial;
+            dirty = false;
+            firstDirtyAt = null;
+            return load();
+        },
+        slots: readSlots,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        dispose() {
+            disposed = true;
+            clearTimer();
+            listeners.clear();
+        },
+    };
+}

package/dist/game/snapshotHistory.d.ts

@@ -0,0 +1,67 @@
+/** Bounded past/future snapshot stacks — a serializable undo/redo record for any state `T`. */
+export interface HistoryStacks<T> {
+    /** Prior states, oldest first; the last entry is the step an undo restores. */
+    readonly past: readonly T[];
+    /** Undone states awaiting redo, oldest first; the last entry is the step a redo restores. */
+    readonly future: readonly T[];
+}
+/** The snapshot an undo/redo restores plus the advanced stacks. */
+export interface HistoryStep<T> {
+    /** State to apply as the new present. */
+    snapshot: T;
+    /** Stacks after the step. */
+    stacks: HistoryStacks<T>;
+}
+/** Empty history stacks for state `T`.
+ * @internal
+ */
+export declare function emptyHistory<T>(): HistoryStacks<T>;
+/** True when there is a prior state to undo to.
+ * @internal
+ */
+export declare function canUndo<T>(stacks: HistoryStacks<T>): boolean;
+/** True when there is an undone state to redo.
+ * @internal
+ */
+export declare function canRedo<T>(stacks: HistoryStacks<T>): boolean;
+/**
+ * Record `present` as the newest undo step and clear the redo future (a fresh action forks history).
+ * The oldest past entries beyond `limit` are dropped so the stack stays bounded for save/transport.
+  * @internal
+  */
+export declare function recordSnapshot<T>(stacks: HistoryStacks<T>, present: T, limit?: number): HistoryStacks<T>;
+/**
+ * Step back: pop the newest past snapshot to apply as the new present, and push the given `present`
+ * onto the future for a later redo. Returns `null` when there is nothing to undo.
+  * @internal
+  */
+export declare function undoSnapshot<T>(stacks: HistoryStacks<T>, present: T): HistoryStep<T> | null;
+/**
+ * Step forward: pop the newest future snapshot to apply as the new present, and push the given
+ * `present` back onto the past. Returns `null` when there is nothing to redo.
+  * @internal
+  */
+export declare function redoSnapshot<T>(stacks: HistoryStacks<T>, present: T): HistoryStep<T> | null;
+/** Stateful undo/redo handle over {@link HistoryStacks}, holding the stacks in a closure. */
+export interface SnapshotHistory<T> {
+    /** Record `present` as a new undo step and clear the redo future. */
+    record(present: T): void;
+    /** Undo, returning the restored snapshot or `null` if there is nothing to undo. */
+    undo(present: T): T | null;
+    /** Redo, returning the restored snapshot or `null` if there is nothing to redo. */
+    redo(present: T): T | null;
+    /** True when an undo is available. */
+    canUndo(): boolean;
+    /** True when a redo is available. */
+    canRedo(): boolean;
+    /** Drop all history. */
+    clear(): void;
+    /** Current immutable stacks (for serialization). */
+    stacks(): HistoryStacks<T>;
+}
+/**
+ * Stateful undo/redo handle wrapping the pure snapshot functions. Call `record(state)` before each
+ * mutation; `undo`/`redo` return the state to apply. `limit` bounds the past stack.
+  * @internal
+  */
+export declare function createSnapshotHistory<T>(limit?: number): SnapshotHistory<T>;

package/dist/game/snapshotHistory.js

@@ -0,0 +1,95 @@
+/** Empty history stacks for state `T`.
+ * @internal
+ */
+export function emptyHistory() {
+    return { past: [], future: [] };
+}
+/** True when there is a prior state to undo to.
+ * @internal
+ */
+export function canUndo(stacks) {
+    return stacks.past.length > 0;
+}
+/** True when there is an undone state to redo.
+ * @internal
+ */
+export function canRedo(stacks) {
+    return stacks.future.length > 0;
+}
+/**
+ * Record `present` as the newest undo step and clear the redo future (a fresh action forks history).
+ * The oldest past entries beyond `limit` are dropped so the stack stays bounded for save/transport.
+  * @internal
+  */
+export function recordSnapshot(stacks, present, limit = 100) {
+    const past = [...stacks.past, present];
+    const trimmed = limit > 0 && past.length > limit ? past.slice(past.length - limit) : past;
+    return { past: trimmed, future: [] };
+}
+/**
+ * Step back: pop the newest past snapshot to apply as the new present, and push the given `present`
+ * onto the future for a later redo. Returns `null` when there is nothing to undo.
+  * @internal
+  */
+export function undoSnapshot(stacks, present) {
+    if (stacks.past.length === 0)
+        return null;
+    const snapshot = stacks.past[stacks.past.length - 1];
+    return {
+        snapshot,
+        stacks: { past: stacks.past.slice(0, -1), future: [...stacks.future, present] },
+    };
+}
+/**
+ * Step forward: pop the newest future snapshot to apply as the new present, and push the given
+ * `present` back onto the past. Returns `null` when there is nothing to redo.
+  * @internal
+  */
+export function redoSnapshot(stacks, present) {
+    if (stacks.future.length === 0)
+        return null;
+    const snapshot = stacks.future[stacks.future.length - 1];
+    return {
+        snapshot,
+        stacks: { past: [...stacks.past, present], future: stacks.future.slice(0, -1) },
+    };
+}
+/**
+ * Stateful undo/redo handle wrapping the pure snapshot functions. Call `record(state)` before each
+ * mutation; `undo`/`redo` return the state to apply. `limit` bounds the past stack.
+  * @internal
+  */
+export function createSnapshotHistory(limit = 100) {
+    let stacks = emptyHistory();
+    return {
+        record(present) {
+            stacks = recordSnapshot(stacks, present, limit);
+        },
+        undo(present) {
+            const step = undoSnapshot(stacks, present);
+            if (step === null)
+                return null;
+            stacks = step.stacks;
+            return step.snapshot;
+        },
+        redo(present) {
+            const step = redoSnapshot(stacks, present);
+            if (step === null)
+                return null;
+            stacks = step.stacks;
+            return step.snapshot;
+        },
+        canUndo() {
+            return canUndo(stacks);
+        },
+        canRedo() {
+            return canRedo(stacks);
+        },
+        clear() {
+            stacks = emptyHistory();
+        },
+        stacks() {
+            return stacks;
+        },
+    };
+}

package/dist/game/social.d.ts

@@ -135,6 +135,36 @@ export interface WorldInvites {
     decline(userId: string, inviteId: string): void;
     listFor(userId: string): WorldInvite[];
 }
+/** One party's replicated membership — id, current leader, and ordered member ids. */
+export interface SocialPartySnapshot {
+    id: string;
+    leader: string;
+    members: string[];
+}
+/**
+ * Full friends/party/world-invite state as one serializable baseline — the host→client replication
+ * payload behind the `social` snapshot module. Presence and emotes are derived from live deps, not stored.
+ */
+export interface SocialSnapshot {
+    friendships: Record<string, string[]>;
+    blocked: Record<string, string[]>;
+    friendRequests: Record<string, {
+        from: string;
+        to: string;
+    }>;
+    requestCounter: number;
+    partyConfig: PartyConfig | null;
+    parties: SocialPartySnapshot[];
+    partyInvites: Record<string, {
+        from: string;
+        to: string;
+        createdAt: number;
+    }>;
+    partyCounter: number;
+    inviteCounter: number;
+    worldInvites: WorldInvite[];
+    worldInviteCounter: number;
+}
 export interface Social {
     friends: Friends;
     party: Party;
@@ -143,5 +173,12 @@ export interface Social {
     };
     emotes: Emotes;
     worldInvites: WorldInvites;
-}
+    snapshot(): SocialSnapshot;
+    hydrate(data: SocialSnapshot): void;
+}
+/**
+ * Emotes and lightweight social interactions between nearby players.
+ *
+ * @capability social-emotes emotes and social interactions between nearby players
+ */
 export declare function createSocial(deps: SocialDeps): Social;

package/dist/game/social.js

@@ -1,5 +1,10 @@
 export const DEFAULT_EMOTE_RADIUS = 20;
 const DEFAULT_INVITE_TTL_MS = 60_000;
+/**
+ * Emotes and lightweight social interactions between nearby players.
+ *
+ * @capability social-emotes emotes and social interactions between nearby players
+ */
 export function createSocial(deps) {
     const now = deps.now ?? Date.now;
     const events = deps.events;
@@ -351,6 +356,70 @@ export function createSocial(deps) {
             return result;
         },
     };
+    function snapshot() {
+        const friendshipsOut = {};
+        for (const [userId, set] of friendships)
+            friendshipsOut[userId] = Array.from(set);
+        const blockedOut = {};
+        for (const [userId, set] of blocked)
+            blockedOut[userId] = Array.from(set);
+        const friendRequestsOut = {};
+        for (const [id, request] of friendRequests)
+            friendRequestsOut[id] = { from: request.from, to: request.to };
+        const partyInvitesOut = {};
+        for (const [id, invite] of partyInvites) {
+            partyInvitesOut[id] = { from: invite.from, to: invite.to, createdAt: invite.createdAt };
+        }
+        return {
+            friendships: friendshipsOut,
+            blocked: blockedOut,
+            friendRequests: friendRequestsOut,
+            requestCounter,
+            partyConfig,
+            parties: Array.from(parties.values(), (state) => ({
+                id: state.id,
+                leader: state.leader,
+                members: state.members.slice(),
+            })),
+            partyInvites: partyInvitesOut,
+            partyCounter,
+            inviteCounter,
+            worldInvites: Array.from(worldInviteEntries.values(), (entry) => ({ ...entry })),
+            worldInviteCounter,
+        };
+    }
+    function hydrate(data) {
+        friendships.clear();
+        for (const [userId, list] of Object.entries(data.friendships))
+            friendships.set(userId, new Set(list));
+        blocked.clear();
+        for (const [userId, list] of Object.entries(data.blocked))
+            blocked.set(userId, new Set(list));
+        friendRequests.clear();
+        for (const [id, request] of Object.entries(data.friendRequests)) {
+            friendRequests.set(id, { from: request.from, to: request.to });
+        }
+        requestCounter = data.requestCounter;
+        partyConfig = data.partyConfig;
+        parties.clear();
+        memberToParty.clear();
+        for (const state of data.parties) {
+            const restored = { id: state.id, leader: state.leader, members: state.members.slice() };
+            parties.set(restored.id, restored);
+            for (const member of restored.members)
+                memberToParty.set(member, restored.id);
+        }
+        partyInvites.clear();
+        for (const [id, invite] of Object.entries(data.partyInvites)) {
+            partyInvites.set(id, { from: invite.from, to: invite.to, createdAt: invite.createdAt });
+        }
+        partyCounter = data.partyCounter;
+        inviteCounter = data.inviteCounter;
+        worldInviteEntries.clear();
+        for (const entry of data.worldInvites)
+            worldInviteEntries.set(entry.id, { ...entry });
+        worldInviteCounter = data.worldInviteCounter;
+    }
     return {
         friends,
         party,
@@ -361,5 +430,7 @@ export function createSocial(deps) {
         },
         emotes,
         worldInvites,
+        snapshot,
+        hydrate,
     };
 }

package/dist/game/spawnPoints.d.ts

@@ -16,4 +16,9 @@ export interface SpawnPoints {
     })[];
     respawn(entities: RespawnTarget, entityId: string, spawnId: string): boolean;
 }
+/**
+ * Register spawn locations and choose where entities spawn or respawn.
+ *
+ * @capability spawn-points register spawn locations and pick where entities respawn
+ */
 export declare function createSpawnPoints(): SpawnPoints;

package/dist/game/spawnPoints.js

@@ -1,3 +1,8 @@
+/**
+ * Register spawn locations and choose where entities spawn or respawn.
+ *
+ * @capability spawn-points register spawn locations and pick where entities respawn
+ */
 export function createSpawnPoints() {
     const points = new Map();
     return {

package/dist/game/systemRuntime.d.ts

@@ -0,0 +1,50 @@
+import type { GameLoop } from "./defineGame.js";
+import type { SystemDefinition } from "./defineSystem.js";
+import { type CompiledSystemSchedule, type CompileSystemScheduleOptions } from "./systemSchedule.js";
+import type { GameContext } from "../runtime/gameContext.js";
+import type { SnapshotModule } from "../runtime/worldSnapshot.js";
+/** @internal */
+export interface SystemModuleRegistration {
+    registerSave(module: SnapshotModule): void;
+    registerReplicate(module: SnapshotModule): void;
+}
+/** @internal */
+export interface InstalledSystems {
+    readonly schedule: CompiledSystemSchedule;
+    /** Advance fixed/frame/interval systems for one game-time step of `dt` seconds. */
+    tick(ctx: GameContext, dt: number): void;
+    /** Invoke every system's `reset` (scenario/run wipe). */
+    reset(ctx: GameContext): void;
+    /** Invoke every system's `dispose` in reverse install order. */
+    dispose(ctx: GameContext): void;
+    /** Run one manual system by id (no-op if missing or not manual). */
+    runManual(ctx: GameContext, id: string, dt?: number): void;
+}
+/**
+ * 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 declare function installSystems(ctx: GameContext, systems: readonly SystemDefinition[], options?: CompileSystemScheduleOptions & {
+    modules?: SystemModuleRegistration;
+}): InstalledSystems;
+/**
+ * Look up systems installed on `ctx` (if any). Used by hosts that need `reset`/`dispose` after boot.
+ * @internal
+ */
+export declare function systemsOf(ctx: GameContext): InstalledSystems | undefined;
+/** @internal */
+export interface ComposeGameLoopOptions extends CompileSystemScheduleOptions {
+    /**
+     * When true, the user loop's `onTick` runs before system ticks (default: systems first, then
+     * residual loop work — the incremental-migration path).
+     */
+    loopBeforeSystems?: boolean;
+}
+/**
+ * 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 declare function composeGameLoop(systems: readonly SystemDefinition[] | undefined, loop: GameLoop<GameContext> | undefined, options?: ComposeGameLoopOptions): GameLoop<GameContext>;