@jgengine/core 0.10.0 → 0.12.0

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

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;