@jgengine/node 0.1.0

package/dist/host.d.ts

@@ -0,0 +1,72 @@
+import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
+import type { HostPersistence, ServerListing } from "@jgengine/core/runtime/hostPersistence";
+import type { GameRuntimePlayerView, GameRuntimeServerView, JoinServerResult, TransportRunCommandResult } from "@jgengine/core/runtime/transport";
+export type HostChangeEvent = {
+    type: "server";
+    serverId: string;
+} | {
+    type: "player";
+    serverId: string;
+    userId: string;
+} | {
+    type: "feed";
+    serverId: string;
+    action: string;
+};
+export type GameHostOptions = {
+    runtimes?: GameRuntime[];
+    persistence: HostPersistence;
+    tickMs?: number;
+    slotsPerServer?: number;
+    now?: () => number;
+    createServerId?: () => string;
+};
+export type GameHost = {
+    joinServer: (args: {
+        userId: string;
+        gameId: string;
+        serverId?: string;
+    }) => Promise<JoinServerResult>;
+    leaveServer: (args: {
+        userId: string;
+        serverId: string;
+    }) => Promise<void>;
+    runCommand: (args: {
+        userId: string;
+        serverId: string;
+        command: string;
+        input: unknown;
+    }) => Promise<TransportRunCommandResult>;
+    getServerView: (args: {
+        userId: string;
+        serverId: string;
+    }) => Promise<GameRuntimeServerView | null>;
+    getPlayerView: (args: {
+        userId: string;
+        serverId: string;
+    }) => Promise<GameRuntimePlayerView | null>;
+    getFeed: (args: {
+        userId: string;
+        serverId: string;
+        action: string;
+    }) => Promise<unknown[]>;
+    pushFeedEntry: (args: {
+        userId: string;
+        serverId: string;
+        action: string;
+        entry: unknown;
+    }) => Promise<void>;
+    listOpenServers: (args: {
+        gameId: string;
+        limit?: number;
+    }) => Promise<ServerListing[]>;
+    tickOnce: () => Promise<{
+        ticked: number;
+        saved: number;
+    }>;
+    flushAll: () => Promise<number>;
+    start: () => void;
+    stop: () => Promise<void>;
+    subscribe: (listener: (event: HostChangeEvent) => void) => () => void;
+};
+export declare function createGameHost(options: GameHostOptions): GameHost;

package/dist/host.js

@@ -0,0 +1,336 @@
+import { randomUUID } from "node:crypto";
+import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
+import { buildHydratePlayers, planServerPersist, shouldAutoSave, toServerListing, } from "@jgengine/core/runtime/hostPersistence";
+import { clearDirtyFlags, createEmptyServerRow, splitProfilePlayer } from "@jgengine/core/runtime/snapshot";
+const builtinCommands = {
+    "engine.ping": {
+        validate: () => null,
+        apply: (snapshot) => snapshot,
+    },
+};
+export function createGameHost(options) {
+    const now = options.now ?? Date.now;
+    const tickMs = options.tickMs ?? 1_000;
+    const defaultSlots = options.slotsPerServer ?? 16;
+    const createServerId = options.createServerId ?? (() => `srv-${randomUUID()}`);
+    const persistence = options.persistence;
+    const runtimes = new Map();
+    for (const runtime of options.runtimes ?? []) {
+        runtimes.set(runtime.gameId, runtime);
+    }
+    const resolveRuntime = (gameId) => {
+        const existing = runtimes.get(gameId);
+        if (existing)
+            return existing;
+        const fallback = createGameRuntime({ gameId, save: "none", commands: builtinCommands });
+        runtimes.set(gameId, fallback);
+        return fallback;
+    };
+    const live = new Map();
+    const listeners = new Set();
+    const emit = (event) => {
+        for (const listener of listeners)
+            listener(event);
+    };
+    let queue = Promise.resolve();
+    const enqueue = (operation) => {
+        const run = queue.then(operation);
+        queue = run.catch(() => undefined);
+        return run;
+    };
+    const hydrate = async (record) => {
+        const runtime = resolveRuntime(record.gameId);
+        const profiles = {};
+        for (const userId of record.memberUserIds) {
+            profiles[userId] = await persistence.loadProfile({ userId, gameId: record.gameId });
+        }
+        const chunkRecords = await persistence.loadChunks(record.serverId);
+        const chunksByKey = {};
+        for (const chunk of chunkRecords) {
+            chunksByKey[chunk.chunkKey] = chunk.snapshot;
+        }
+        const snapshot = runtime.hydrate({
+            gameId: record.gameId,
+            serverId: record.serverId,
+            serverRow: record.serverState,
+            playersByUserId: buildHydratePlayers(record, profiles),
+            chunksByKey,
+        });
+        const existing = live.get(record.serverId);
+        if (existing)
+            return existing;
+        const entry = { record, snapshot };
+        live.set(record.serverId, entry);
+        return entry;
+    };
+    const getLive = async (serverId) => {
+        const existing = live.get(serverId);
+        if (existing)
+            return existing;
+        const record = await persistence.loadServer(serverId);
+        if (record === null)
+            return null;
+        return hydrate(record);
+    };
+    const flushServer = async (entry) => {
+        const timestamp = now();
+        const plan = planServerPersist(entry.record, entry.snapshot, entry.record.save, timestamp);
+        const cleared = { ...plan, server: { ...plan.server, dirtyAt: undefined } };
+        if (persistence.savePlan) {
+            await persistence.savePlan(cleared);
+        }
+        else {
+            if (cleared.leaderboard.length > 0) {
+                await persistence.applyLeaderboardIncrements(entry.record.gameId, cleared.leaderboard);
+            }
+            for (const profile of cleared.profiles) {
+                await persistence.saveProfile(profile);
+            }
+            if (cleared.chunks.length > 0) {
+                await persistence.saveChunks(entry.record.serverId, cleared.chunks);
+            }
+            await persistence.saveServer(cleared.server);
+        }
+        entry.record = cleared.server;
+        entry.snapshot = clearDirtyFlags({ ...entry.snapshot, server: cleared.server.serverState });
+    };
+    const markMutated = (entry) => {
+        const timestamp = now();
+        entry.record = {
+            ...entry.record,
+            revision: entry.snapshot.revision,
+            dirtyAt: entry.record.dirtyAt ?? timestamp,
+            updatedAt: timestamp,
+        };
+    };
+    let interval = null;
+    const tickOnce = () => enqueue(async () => {
+        const timestamp = now();
+        let ticked = 0;
+        let saved = 0;
+        for (const entry of live.values()) {
+            if (entry.record.status !== "running")
+                continue;
+            if (entry.record.memberUserIds.length === 0)
+                continue;
+            const elapsedMs = timestamp - entry.record.tickAnchorMs;
+            if (elapsedMs < tickMs)
+                continue;
+            const runtime = resolveRuntime(entry.record.gameId);
+            const before = entry.snapshot.revision;
+            entry.snapshot = runtime.tick(entry.snapshot, elapsedMs / 1_000);
+            entry.record = { ...entry.record, tickAnchorMs: timestamp, updatedAt: timestamp };
+            ticked += 1;
+            if (entry.snapshot.revision !== before) {
+                markMutated(entry);
+                emit({ type: "server", serverId: entry.record.serverId });
+            }
+            if (shouldAutoSave(entry.record.save, entry.record.dirtyAt, entry.record.lastSavedAt, timestamp)) {
+                await flushServer(entry);
+                saved += 1;
+            }
+        }
+        return { ticked, saved };
+    });
+    return {
+        joinServer: (args) => enqueue(async () => {
+            const timestamp = now();
+            const runtime = resolveRuntime(args.gameId);
+            let entry = args.serverId === undefined ? null : await getLive(args.serverId);
+            if (entry !== null && entry.record.gameId !== args.gameId) {
+                throw new Error("Server belongs to a different game");
+            }
+            if (entry === null) {
+                const record = {
+                    serverId: createServerId(),
+                    gameId: args.gameId,
+                    status: "running",
+                    memberUserIds: [],
+                    slotsPerServer: defaultSlots,
+                    save: runtime.save,
+                    serverState: createEmptyServerRow(),
+                    sessionPlayers: {},
+                    revision: 0,
+                    tickAnchorMs: timestamp,
+                    createdAt: timestamp,
+                    updatedAt: timestamp,
+                };
+                entry = await hydrate(record);
+            }
+            const { record } = entry;
+            if (record.memberUserIds.length >= record.slotsPerServer &&
+                !record.memberUserIds.includes(args.userId)) {
+                throw new Error("Server is full");
+            }
+            const profile = await persistence.loadProfile({ userId: args.userId, gameId: args.gameId });
+            const isNew = profile === null;
+            entry.record = {
+                ...record,
+                memberUserIds: record.memberUserIds.includes(args.userId)
+                    ? record.memberUserIds
+                    : [...record.memberUserIds, args.userId],
+                status: "running",
+                updatedAt: timestamp,
+                dirtyAt: timestamp,
+            };
+            entry.snapshot = runtime.joinPlayer(entry.snapshot, args.userId, isNew);
+            await flushServer(entry);
+            emit({ type: "server", serverId: entry.record.serverId });
+            emit({ type: "player", serverId: entry.record.serverId, userId: args.userId });
+            return { serverId: entry.record.serverId, isNew };
+        }),
+        leaveServer: (args) => enqueue(async () => {
+            const entry = await getLive(args.serverId);
+            if (entry === null)
+                return;
+            if (!entry.record.memberUserIds.includes(args.userId))
+                return;
+            await flushServer(entry);
+            const timestamp = now();
+            const memberUserIds = entry.record.memberUserIds.filter((id) => id !== args.userId);
+            const sessionPlayers = { ...entry.record.sessionPlayers };
+            delete sessionPlayers[args.userId];
+            const players = { ...entry.snapshot.players };
+            delete players[args.userId];
+            entry.record = {
+                ...entry.record,
+                memberUserIds,
+                sessionPlayers,
+                updatedAt: timestamp,
+                status: memberUserIds.length === 0 ? "open" : entry.record.status,
+            };
+            entry.snapshot = { ...entry.snapshot, players };
+            await persistence.saveServer(entry.record);
+            if (memberUserIds.length === 0) {
+                live.delete(entry.record.serverId);
+            }
+            emit({ type: "server", serverId: args.serverId });
+        }),
+        runCommand: (args) => enqueue(async () => {
+            const entry = await getLive(args.serverId);
+            if (entry === null) {
+                return { ok: false, reason: "Server not found" };
+            }
+            if (!entry.record.memberUserIds.includes(args.userId)) {
+                return { ok: false, reason: "Not a member of this server" };
+            }
+            const runtime = resolveRuntime(entry.record.gameId);
+            const result = runtime.runCommand(entry.snapshot, args.userId, args.command, args.input);
+            if (!result.ok) {
+                return { ok: false, reason: result.reason };
+            }
+            entry.snapshot = result.snapshot;
+            markMutated(entry);
+            emit({ type: "server", serverId: args.serverId });
+            emit({ type: "player", serverId: args.serverId, userId: args.userId });
+            return { ok: true };
+        }),
+        getServerView: async (args) => {
+            const entry = await getLive(args.serverId);
+            if (entry === null)
+                return null;
+            if (!entry.record.memberUserIds.includes(args.userId))
+                return null;
+            return {
+                serverId: entry.record.serverId,
+                gameId: entry.record.gameId,
+                revision: entry.snapshot.revision,
+                memberUserIds: entry.record.memberUserIds,
+                serverState: entry.snapshot.server,
+                updatedAt: entry.record.updatedAt,
+            };
+        },
+        getPlayerView: async (args) => {
+            const entry = await getLive(args.serverId);
+            if (entry === null)
+                return null;
+            if (!entry.record.memberUserIds.includes(args.userId))
+                return null;
+            const player = entry.snapshot.players[args.userId];
+            if (player !== undefined) {
+                return {
+                    userId: args.userId,
+                    gameId: entry.record.gameId,
+                    playerState: splitProfilePlayer(player).persistent,
+                    updatedAt: entry.record.updatedAt,
+                };
+            }
+            const profile = await persistence.loadProfile({ userId: args.userId, gameId: entry.record.gameId });
+            if (profile === null)
+                return null;
+            return {
+                userId: profile.userId,
+                gameId: profile.gameId,
+                playerState: profile.playerState,
+                updatedAt: profile.updatedAt,
+            };
+        },
+        getFeed: async (args) => {
+            const entry = await getLive(args.serverId);
+            if (entry === null)
+                return [];
+            if (!entry.record.memberUserIds.includes(args.userId))
+                return [];
+            return persistence.loadFeed({ serverId: args.serverId, action: args.action });
+        },
+        pushFeedEntry: (args) => enqueue(async () => {
+            const entry = await getLive(args.serverId);
+            if (entry === null || !entry.record.memberUserIds.includes(args.userId)) {
+                throw new Error("Not a member of this server");
+            }
+            await persistence.appendFeed({ serverId: args.serverId, action: args.action, entry: args.entry });
+            emit({ type: "feed", serverId: args.serverId, action: args.action });
+        }),
+        listOpenServers: async (args) => {
+            const limit = args.limit ?? 20;
+            const byId = new Map();
+            for (const record of await persistence.listServers(args.gameId)) {
+                byId.set(record.serverId, toServerListing(record));
+            }
+            for (const entry of live.values()) {
+                if (entry.record.gameId !== args.gameId)
+                    continue;
+                byId.set(entry.record.serverId, toServerListing(entry.record));
+            }
+            return [...byId.values()]
+                .filter((listing) => listing.status === "running")
+                .sort((a, b) => b.updatedAt - a.updatedAt)
+                .slice(0, limit);
+        },
+        tickOnce,
+        flushAll: () => enqueue(async () => {
+            let saved = 0;
+            for (const entry of live.values()) {
+                if (entry.record.dirtyAt === undefined)
+                    continue;
+                await flushServer(entry);
+                saved += 1;
+            }
+            return saved;
+        }),
+        start: () => {
+            if (interval !== null)
+                return;
+            interval = setInterval(() => {
+                void tickOnce();
+            }, tickMs);
+        },
+        stop: async () => {
+            if (interval !== null) {
+                clearInterval(interval);
+                interval = null;
+            }
+            await enqueue(async () => {
+                for (const entry of live.values()) {
+                    if (entry.record.dirtyAt === undefined)
+                        continue;
+                    await flushServer(entry);
+                }
+            });
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/dist/persistence.d.ts

@@ -0,0 +1,4 @@
+import type { HostPersistence } from "@jgengine/core/runtime/hostPersistence";
+export declare function memoryPersistence(now?: () => number): HostPersistence;
+export declare function filePersistence(dir: string, now?: () => number): HostPersistence;
+export declare function clearFilePersistence(dir: string): Promise<void>;

package/dist/persistence.js

@@ -0,0 +1,224 @@
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { trimFeedEntries } from "@jgengine/core/runtime/hostPersistence";
+const MAX_TOP_LIMIT = 100;
+function leaderboardRowKey(row) {
+    return [row.gameId, row.scope, row.stat, row.serverId ?? "", row.userId].join("|");
+}
+function applyIncrements(rows, gameId, entries, now) {
+    for (const entry of entries) {
+        const key = leaderboardRowKey({ ...entry, gameId });
+        const existing = rows.get(key);
+        if (existing) {
+            rows.set(key, { ...existing, value: existing.value + entry.by, updatedAt: now });
+        }
+        else {
+            rows.set(key, {
+                gameId,
+                stat: entry.stat,
+                scope: entry.scope,
+                serverId: entry.serverId,
+                userId: entry.userId,
+                value: entry.by,
+                updatedAt: now,
+            });
+        }
+    }
+}
+function topRows(rows, args) {
+    const limit = Math.min(Math.max(args.limit ?? MAX_TOP_LIMIT, 1), MAX_TOP_LIMIT);
+    return [...rows]
+        .filter((row) => row.gameId === args.gameId &&
+        row.stat === args.stat &&
+        row.scope === args.scope &&
+        (args.serverId === undefined || row.serverId === args.serverId))
+        .sort((a, b) => b.value - a.value)
+        .slice(0, limit)
+        .map((row) => ({ userId: row.userId, value: row.value }));
+}
+function profileStats(rows, gameId, userId) {
+    const profile = {};
+    for (const row of rows) {
+        if (row.gameId === gameId && row.userId === userId && row.scope === "profile") {
+            profile[row.stat] = row.value;
+        }
+    }
+    return profile;
+}
+export function memoryPersistence(now = Date.now) {
+    const servers = new Map();
+    const profiles = new Map();
+    const chunks = new Map();
+    const feeds = new Map();
+    const leaderboard = new Map();
+    const clone = (value) => structuredClone(value);
+    return {
+        async loadServer(serverId) {
+            const record = servers.get(serverId);
+            return record === undefined ? null : clone(record);
+        },
+        async saveServer(record) {
+            servers.set(record.serverId, clone(record));
+        },
+        async listServers(gameId) {
+            return [...servers.values()].filter((record) => record.gameId === gameId).map(clone);
+        },
+        async loadProfile({ userId, gameId }) {
+            const record = profiles.get(`${gameId}|${userId}`);
+            return record === undefined ? null : clone(record);
+        },
+        async saveProfile(record) {
+            profiles.set(`${record.gameId}|${record.userId}`, clone(record));
+        },
+        async loadChunks(serverId) {
+            return [...(chunks.get(serverId)?.values() ?? [])].map(clone);
+        },
+        async saveChunks(serverId, records) {
+            const byKey = chunks.get(serverId) ?? new Map();
+            for (const record of records) {
+                byKey.set(record.chunkKey, clone(record));
+            }
+            chunks.set(serverId, byKey);
+        },
+        async loadFeed({ serverId, action }) {
+            return clone(feeds.get(`${serverId}|${action}`) ?? []);
+        },
+        async appendFeed({ serverId, action, entry }) {
+            const key = `${serverId}|${action}`;
+            const entries = trimFeedEntries([...(feeds.get(key) ?? []), clone(entry)]);
+            feeds.set(key, entries);
+            return clone(entries);
+        },
+        async applyLeaderboardIncrements(gameId, entries) {
+            applyIncrements(leaderboard, gameId, entries, now());
+        },
+        async getLeaderboardTop(args) {
+            return topRows(leaderboard.values(), args);
+        },
+        async getLeaderboardProfile({ gameId, userId }) {
+            return profileStats(leaderboard.values(), gameId, userId);
+        },
+    };
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function writeJson(path, value) {
+    const temp = `${path}.tmp`;
+    await writeFile(temp, JSON.stringify(value), "utf8");
+    await rename(temp, path);
+}
+const enc = encodeURIComponent;
+export function filePersistence(dir, now = Date.now) {
+    const serversDir = join(dir, "servers");
+    const profilesDir = join(dir, "profiles");
+    const chunksDir = join(dir, "chunks");
+    const feedsDir = join(dir, "feeds");
+    const leaderboardPath = join(dir, "leaderboard.json");
+    let ready = null;
+    const ensureDirs = () => {
+        ready ??= Promise.all([serversDir, profilesDir, chunksDir, feedsDir].map((path) => mkdir(path, { recursive: true }))).then(() => undefined);
+        return ready;
+    };
+    const loadLeaderboard = async () => {
+        const rows = (await readJson(leaderboardPath)) ?? [];
+        return new Map(rows.map((row) => [leaderboardRowKey(row), row]));
+    };
+    let leaderboardLock = Promise.resolve();
+    return {
+        async loadServer(serverId) {
+            await ensureDirs();
+            return readJson(join(serversDir, `${enc(serverId)}.json`));
+        },
+        async saveServer(record) {
+            await ensureDirs();
+            await writeJson(join(serversDir, `${enc(record.serverId)}.json`), record);
+        },
+        async listServers(gameId) {
+            await ensureDirs();
+            const files = await readdir(serversDir);
+            const records = [];
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const record = await readJson(join(serversDir, file));
+                if (record !== null && record.gameId === gameId)
+                    records.push(record);
+            }
+            return records;
+        },
+        async loadProfile({ userId, gameId }) {
+            await ensureDirs();
+            return readJson(join(profilesDir, `${enc(gameId)}__${enc(userId)}.json`));
+        },
+        async saveProfile(record) {
+            await ensureDirs();
+            await writeJson(join(profilesDir, `${enc(record.gameId)}__${enc(record.userId)}.json`), record);
+        },
+        async loadChunks(serverId) {
+            await ensureDirs();
+            const serverDir = join(chunksDir, enc(serverId));
+            let files;
+            try {
+                files = await readdir(serverDir);
+            }
+            catch {
+                return [];
+            }
+            const records = [];
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const record = await readJson(join(serverDir, file));
+                if (record !== null)
+                    records.push(record);
+            }
+            return records;
+        },
+        async saveChunks(serverId, records) {
+            await ensureDirs();
+            const serverDir = join(chunksDir, enc(serverId));
+            await mkdir(serverDir, { recursive: true });
+            for (const record of records) {
+                await writeJson(join(serverDir, `${enc(record.chunkKey)}.json`), record);
+            }
+        },
+        async loadFeed({ serverId, action }) {
+            await ensureDirs();
+            return (await readJson(join(feedsDir, `${enc(serverId)}__${enc(action)}.json`))) ?? [];
+        },
+        async appendFeed({ serverId, action, entry }) {
+            await ensureDirs();
+            const path = join(feedsDir, `${enc(serverId)}__${enc(action)}.json`);
+            const entries = trimFeedEntries([...((await readJson(path)) ?? []), entry]);
+            await writeJson(path, entries);
+            return entries;
+        },
+        async applyLeaderboardIncrements(gameId, entries) {
+            const run = leaderboardLock.then(async () => {
+                await ensureDirs();
+                const rows = await loadLeaderboard();
+                applyIncrements(rows, gameId, entries, now());
+                await writeJson(leaderboardPath, [...rows.values()]);
+            });
+            leaderboardLock = run.catch(() => undefined);
+            await run;
+        },
+        async getLeaderboardTop(args) {
+            await ensureDirs();
+            return topRows((await loadLeaderboard()).values(), args);
+        },
+        async getLeaderboardProfile({ gameId, userId }) {
+            await ensureDirs();
+            return profileStats((await loadLeaderboard()).values(), gameId, userId);
+        },
+    };
+}
+export async function clearFilePersistence(dir) {
+    await rm(dir, { recursive: true, force: true });
+}

package/dist/wsServer.d.ts

@@ -0,0 +1,22 @@
+import type { Server as HttpServer } from "node:http";
+import { WebSocketServer } from "ws";
+import type { PoseSyncRules } from "@jgengine/core/multiplayer/presenceModel";
+import type { GameHost } from "./host.js";
+export type GameWsServerOptions = {
+    host: GameHost;
+    server?: HttpServer;
+    port?: number;
+    path?: string;
+    authenticate?: (args: {
+        userId: string;
+        token?: string;
+    }) => Promise<string | null> | string | null;
+    poseRules?: PoseSyncRules;
+    now?: () => number;
+};
+export type GameWsServer = {
+    wss: WebSocketServer;
+    port: () => number;
+    close: () => Promise<void>;
+};
+export declare function createGameWsServer(options: GameWsServerOptions): GameWsServer;