@jgengine/node 0.10.0 → 0.11.0

package/README.md

@@ -1,3 +1,3 @@
 # @jgengine/node
 
-Standalone authoritative game host for [JGengine](https://github.com/Noisemaker111/jgengine): in-memory server snapshots, tick loop, save-cadence flush, WebSocket server, memory/file persistence. AGPL-3.0-only.
+Standalone authoritative game host for [JGengine](https://github.com/Noisemaker111/jgengine): in-memory server snapshots, tick loop, save-cadence flush, WebSocket server, memory/file persistence. Apache-2.0.

package/dist/devSavePlugin.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { SaveEndpointResponse } from "@jgengine/core/devtools/saveEndpoint";
+/** Route the dev save middleware answers on; matches `installSaveEndpoint` defaults. */
+export declare const SAVE_ENDPOINT_PATH = "/__jgengine/save";
+/** Filename editor scene documents are saved under inside a game's `src/`. */
+export declare const EDITOR_SCENE_FILENAME = "editor.scene.json";
+type SrcDirResolver = (gameId: string) => string | null;
+/** Applies one parsed save request against a resolved game `src/` directory. */
+export declare function handleSaveRequest(resolveSrcDir: SrcDirResolver, body: string): SaveEndpointResponse;
+interface DevSavePluginShape {
+    name: string;
+    apply: "serve";
+    configureServer(server: {
+        middlewares: {
+            use(route: string, handler: (req: IncomingMessage, res: ServerResponse, next: () => void) => void): void;
+        };
+    }): void;
+}
+/**
+ * Dev-only Vite middleware that gives the F2 chord family its write path:
+ * editor mode's Save (Ctrl+S / `save_scene`) writes `editor.scene.json` and
+ * debug mode's Tune "Save to source" rewrites tunable literals, both into the
+ * directory `resolveSrcDir(gameId)` returns.
+ */
+export declare function devSavePlugin(resolveSrcDir: SrcDirResolver): DevSavePluginShape;
+/**
+ * `devSavePlugin` preset for a standalone game project (one game, `src/` at
+ * the project root): every gameId maps to `<rootDir>/src`. Drop into the
+ * scaffolded `vite.config.ts` plugins array.
+ */
+export declare function standaloneSavePlugin(rootDir?: string): DevSavePluginShape;
+export {};

package/dist/devSavePlugin.js

@@ -0,0 +1,142 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { rewriteTunableExport } from "@jgengine/core/devtools/rewriteTunables";
+import { splitTunablePath } from "@jgengine/core/devtools/tunableSchema";
+import { importEditorDocumentJson } from "@jgengine/core/editor/document";
+/** Route the dev save middleware answers on; matches `installSaveEndpoint` defaults. */
+export const SAVE_ENDPOINT_PATH = "/__jgengine/save";
+/** Filename editor scene documents are saved under inside a game's `src/`. */
+export const EDITOR_SCENE_FILENAME = "editor.scene.json";
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+function saveEditorDocument(dir, json) {
+    const document = importEditorDocumentJson(json);
+    const path = join(dir, EDITOR_SCENE_FILENAME);
+    writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`);
+    return { ok: true, path };
+}
+function listSourceFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listSourceFiles(full));
+        else if (/\.(ts|tsx)$/.test(entry.name) && !entry.name.includes(".test."))
+            out.push(full);
+    }
+    return out;
+}
+function moduleFileForTable(dir, table) {
+    if (table.includes(".."))
+        return null;
+    for (const extension of [".ts", ".tsx"]) {
+        const candidate = join(dir, `${table}${extension}`);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function fileExportingTable(files, table) {
+    const pattern = new RegExp(`export\\s+(?:const|let)\\s+${table.replace(/[$]/g, "\\$&")}\\b`);
+    for (const file of files) {
+        if (pattern.test(readFileSync(file, "utf8")))
+            return file;
+    }
+    return null;
+}
+function saveTunables(dir, deltas) {
+    const files = listSourceFiles(dir);
+    const pending = new Map();
+    const skipped = [];
+    let applied = 0;
+    for (const delta of deltas) {
+        const moduleFile = moduleFileForTable(dir, delta.table);
+        const file = moduleFile ?? fileExportingTable(files, delta.table);
+        if (file === null) {
+            skipped.push({ table: delta.table, key: delta.key, reason: "no source file found" });
+            continue;
+        }
+        const exportName = moduleFile !== null ? delta.key : delta.table;
+        const path = moduleFile !== null ? [] : splitTunablePath(delta.key);
+        const code = pending.get(file) ?? readFileSync(file, "utf8");
+        const rewritten = rewriteTunableExport(code, exportName, path, delta.value);
+        if (rewritten === null) {
+            skipped.push({ table: delta.table, key: delta.key, reason: "could not locate literal" });
+            continue;
+        }
+        pending.set(file, rewritten);
+        applied += 1;
+    }
+    for (const [file, code] of pending)
+        writeFileSync(file, code);
+    return { ok: true, applied, skipped };
+}
+function readBody(req) {
+    return new Promise((resolvePromise, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolvePromise(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+/** Applies one parsed save request against a resolved game `src/` directory. */
+export function handleSaveRequest(resolveSrcDir, body) {
+    const request = JSON.parse(body);
+    const dir = resolveSrcDir(request.gameId);
+    if (dir === null)
+        return { ok: false, error: `unknown game: ${request.gameId}` };
+    if (request.kind === "editor-document")
+        return saveEditorDocument(dir, request.json);
+    if (request.kind === "tunables")
+        return saveTunables(dir, request.deltas);
+    return { ok: false, error: "unknown save kind" };
+}
+/**
+ * Dev-only Vite middleware that gives the F2 chord family its write path:
+ * editor mode's Save (Ctrl+S / `save_scene`) writes `editor.scene.json` and
+ * debug mode's Tune "Save to source" rewrites tunable literals, both into the
+ * directory `resolveSrcDir(gameId)` returns.
+ */
+export function devSavePlugin(resolveSrcDir) {
+    return {
+        name: "jgengine-dev-save",
+        apply: "serve",
+        configureServer(server) {
+            server.middlewares.use(SAVE_ENDPOINT_PATH, (req, res, next) => {
+                if (req.method !== "POST") {
+                    next();
+                    return;
+                }
+                void readBody(req)
+                    .then((body) => {
+                    const response = handleSaveRequest(resolveSrcDir, body);
+                    res.statusCode = response.ok ? 200 : 400;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify(response));
+                })
+                    .catch((error) => {
+                    res.statusCode = 400;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+                });
+            });
+        },
+    };
+}
+/**
+ * `devSavePlugin` preset for a standalone game project (one game, `src/` at
+ * the project root): every gameId maps to `<rootDir>/src`. Drop into the
+ * scaffolded `vite.config.ts` plugins array.
+ */
+export function standaloneSavePlugin(rootDir = process.cwd()) {
+    const srcDir = resolve(rootDir, "src");
+    return devSavePlugin(() => (existsSync(srcDir) ? srcDir : null));
+}

package/dist/editorHostPlugin.d.ts

@@ -0,0 +1,43 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** One placeable model the standalone editor lists — a stable id and a URL the dev server serves it from. */
+export interface EditorManifestAsset {
+    id: string;
+    url: string;
+    label: string;
+}
+/** What the standalone editor loads on boot: the on-disk scene document (if any) and every model in the asset folder. */
+export interface EditorManifest {
+    scene: unknown | null;
+    assets: EditorManifestAsset[];
+}
+/**
+ * Reads the scene document and scans the asset folder — the pure core the dev server serves at `/__jgengine/manifest`.
+ * @internal
+ */
+export declare function buildEditorManifest(sceneDir: string, assetsDir: string): EditorManifest;
+interface DevServerLike {
+    middlewares: {
+        use(route: string, handler: (req: IncomingMessage, res: ServerResponse, next: () => void) => void): void;
+    };
+}
+interface EditorHostPluginShape {
+    name: string;
+    apply: "serve";
+    configureServer(server: DevServerLike): void;
+}
+/** Where the standalone editor reads and writes: the scene folder and the model folder it scans. */
+export interface EditorHostOptions {
+    /** Directory the scene document lives in and Save writes back to. Default `process.cwd()`. */
+    dir?: string;
+    /** Directory scanned for placeable `.glb`/`.gltf` models. Default `<dir>/assets` if present, else `<dir>`. */
+    assetsDir?: string;
+}
+/**
+ * Dev-server plugin that turns any folder into a standalone-editor workspace: it serves the folder's
+ * `editor.scene.json` and every model under it at `/__jgengine/manifest`, streams the model bytes at
+ * `/__jgengine/assets/*`, and writes Save back to `editor.scene.json` — the server half of
+ * `jgengine editor`, drop-in for a Vite dev config.
+ * @internal
+ */
+export declare function editorHostPlugin(options?: EditorHostOptions): EditorHostPluginShape;
+export {};

package/dist/editorHostPlugin.js

@@ -0,0 +1,85 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative, resolve, sep } from "node:path";
+import { EDITOR_SCENE_FILENAME, devSavePlugin } from "./devSavePlugin.js";
+const MODEL_EXT = /\.(glb|gltf)$/i;
+const ASSET_ROUTE = "/__jgengine/assets/";
+const MANIFEST_ROUTE = "/__jgengine/manifest";
+function assetIdFromRel(rel) {
+    const cleaned = rel
+        .replace(MODEL_EXT, "")
+        .replace(/[^a-z0-9]+/gi, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+    return cleaned.length > 0 ? cleaned : "asset";
+}
+function walkModels(root, dir = root) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walkModels(root, full));
+        else if (MODEL_EXT.test(entry.name))
+            out.push(relative(root, full));
+    }
+    return out.sort();
+}
+/**
+ * Reads the scene document and scans the asset folder — the pure core the dev server serves at `/__jgengine/manifest`.
+ * @internal
+ */
+export function buildEditorManifest(sceneDir, assetsDir) {
+    const scenePath = join(sceneDir, EDITOR_SCENE_FILENAME);
+    let scene = null;
+    if (existsSync(scenePath)) {
+        try {
+            scene = JSON.parse(readFileSync(scenePath, "utf8"));
+        }
+        catch {
+            scene = null;
+        }
+    }
+    const assets = walkModels(assetsDir).map((rel) => {
+        const web = rel.split(sep).join("/");
+        return { id: assetIdFromRel(web), url: ASSET_ROUTE + web, label: web };
+    });
+    return { scene, assets };
+}
+/**
+ * Dev-server plugin that turns any folder into a standalone-editor workspace: it serves the folder's
+ * `editor.scene.json` and every model under it at `/__jgengine/manifest`, streams the model bytes at
+ * `/__jgengine/assets/*`, and writes Save back to `editor.scene.json` — the server half of
+ * `jgengine editor`, drop-in for a Vite dev config.
+ * @internal
+ */
+export function editorHostPlugin(options = {}) {
+    const dir = resolve(options.dir ?? process.cwd());
+    const assetsDir = resolve(options.assetsDir ?? (existsSync(join(dir, "assets")) ? join(dir, "assets") : dir));
+    const save = devSavePlugin(() => dir);
+    return {
+        name: "jgengine-editor-host",
+        apply: "serve",
+        configureServer(server) {
+            save.configureServer(server);
+            server.middlewares.use(MANIFEST_ROUTE, (req, res, next) => {
+                if (req.method !== "GET") {
+                    next();
+                    return;
+                }
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify(buildEditorManifest(dir, assetsDir)));
+            });
+            server.middlewares.use(ASSET_ROUTE, (req, res, next) => {
+                const rel = decodeURIComponent((req.url ?? "").split("?")[0]).replace(/^\/+/, "");
+                const full = resolve(assetsDir, rel);
+                if (!full.startsWith(assetsDir) || !existsSync(full) || !statSync(full).isFile()) {
+                    next();
+                    return;
+                }
+                res.setHeader("content-type", extname(full).toLowerCase() === ".glb" ? "model/gltf-binary" : "model/gltf+json");
+                res.end(readFileSync(full));
+            });
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./host.js";
 export * from "./persistence.js";
+export * from "./shutdown.js";
 export * from "./socketIoServer.js";
 export * from "./webHandler.js";
 export * from "./worldServer.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./host.js";
 export * from "./persistence.js";
+export * from "./shutdown.js";
 export * from "./socketIoServer.js";
 export * from "./webHandler.js";
 export * from "./worldServer.js";

package/dist/persistence.d.ts

@@ -1,4 +1,21 @@
 import type { HostPersistence } from "@jgengine/core/runtime/hostPersistence";
+import { type HostedWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
 export { memoryPersistence } from "@jgengine/ws/host";
+/** Per-world key a {@link WorldPersistence} resolves a {@link HostedWorldStore} for. */
+export interface WorldPersistenceKey {
+    gameId: string;
+    serverId: string;
+}
+/**
+ * The persistence plug-point for {@link createWorldGameServer}: resolves one {@link HostedWorldStore}
+ * per hosted world, called once when the world host session is created. Structural — a SQL, file, or
+ * Convex-backed store all conform without `node` importing a concrete driver; only a `store()` factory
+ * is required. Mirrors `HostPersistence` (the reducer host's persistence seam).
+ */
+export interface WorldPersistence {
+    store(key: WorldPersistenceKey): HostedWorldStore;
+}
+/** Default {@link WorldPersistence}: an isolated in-memory {@link HostedWorldStore} per `gameId`/`serverId`, lost on process exit. */
+export declare function memoryWorldPersistence(): WorldPersistence;
 export declare function filePersistence(dir: string, now?: () => number): HostPersistence;
 export declare function clearFilePersistence(dir: string): Promise<void>;

package/dist/persistence.js

@@ -2,7 +2,23 @@ import { randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { applyLeaderboardRows, leaderboardRowKey, profileLeaderboardStats, topLeaderboardRows, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
+import { memoryWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
 export { memoryPersistence } from "@jgengine/ws/host";
+/** Default {@link WorldPersistence}: an isolated in-memory {@link HostedWorldStore} per `gameId`/`serverId`, lost on process exit. */
+export function memoryWorldPersistence() {
+    const stores = new Map();
+    return {
+        store({ gameId, serverId }) {
+            const key = `${gameId} ${serverId}`;
+            const existing = stores.get(key);
+            if (existing !== undefined)
+                return existing;
+            const created = memoryWorldStore();
+            stores.set(key, created);
+            return created;
+        },
+    };
+}
 function isMissing(error) {
     return error?.code === "ENOENT";
 }
@@ -26,7 +42,11 @@ async function stageJson(path, value) {
 async function writeJson(path, value) {
     await rename(await stageJson(path, value), path);
 }
-const enc = encodeURIComponent;
+function encodeSegment(key) {
+    const encoded = encodeURIComponent(key);
+    return encoded === "." || encoded === ".." ? encoded.replaceAll(".", "%2E") : encoded;
+}
+const enc = encodeSegment;
 export function filePersistence(dir, now = Date.now) {
     const serversDir = join(dir, "servers");
     const profilesDir = join(dir, "profiles");
@@ -130,8 +150,15 @@ export function filePersistence(dir, now = Date.now) {
                 await writeJson(path, entries);
                 return entries;
             });
-            feedLocks.set(path, run.catch(() => undefined));
-            return run;
+            const tracked = run.catch(() => undefined);
+            feedLocks.set(path, tracked);
+            try {
+                return await run;
+            }
+            finally {
+                if (feedLocks.get(path) === tracked)
+                    feedLocks.delete(path);
+            }
         },
         async applyLeaderboardIncrements(gameId, entries) {
             const run = leaderboardLock.then(async () => {

package/dist/shutdown.d.ts

@@ -0,0 +1,23 @@
+/** A live signal listener installed by {@link installShutdownHook}; call `remove()` to uninstall it (tests, embedders opting out). */
+export interface ShutdownHook {
+    remove(): void;
+}
+/** Config for {@link installShutdownHook}. */
+export interface InstallShutdownHookOptions {
+    /** Signals to listen for; default `["SIGINT", "SIGTERM"]`. */
+    signals?: readonly NodeJS.Signals[];
+    /** Bound on how long `shutdown()` may run before the hook gives up and exits anyway; default 5000ms. */
+    timeoutMs?: number;
+    /** Called with `0` on a clean shutdown, `1` on error or timeout; default `process.exit`. Override in tests to avoid killing the test process. */
+    exit?: (code: number) => void;
+    /** Called when `shutdown()` rejects or times out; default logs to `console.error`. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Wires `SIGINT`/`SIGTERM` (or a custom signal list) to a clean-shutdown callback — e.g.
+ * `() => worldServer.close()` or `() => Promise.all([wsServer.close(), host.stop()])`. Bounded by
+ * `timeoutMs` so a stuck flush can't hang the process forever; idempotent — a second signal delivered
+ * mid-shutdown reuses the same in-flight run instead of flushing twice. Returns a {@link ShutdownHook}
+ * whose `remove()` uninstalls the listeners, for tests and embedders that want their own handling.
+ */
+export declare function installShutdownHook(shutdown: () => Promise<void> | void, options?: InstallShutdownHookOptions): ShutdownHook;

package/dist/shutdown.js

@@ -0,0 +1,50 @@
+const DEFAULT_SIGNALS = ["SIGINT", "SIGTERM"];
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Wires `SIGINT`/`SIGTERM` (or a custom signal list) to a clean-shutdown callback — e.g.
+ * `() => worldServer.close()` or `() => Promise.all([wsServer.close(), host.stop()])`. Bounded by
+ * `timeoutMs` so a stuck flush can't hang the process forever; idempotent — a second signal delivered
+ * mid-shutdown reuses the same in-flight run instead of flushing twice. Returns a {@link ShutdownHook}
+ * whose `remove()` uninstalls the listeners, for tests and embedders that want their own handling.
+ */
+export function installShutdownHook(shutdown, options = {}) {
+    const signals = options.signals ?? DEFAULT_SIGNALS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const onError = options.onError ?? ((error) => console.error("shutdown failed:", error));
+    let inFlight = null;
+    function run() {
+        inFlight ??= (async () => {
+            let timer;
+            try {
+                await Promise.race([
+                    Promise.resolve(shutdown()),
+                    new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => reject(new Error(`shutdown exceeded ${timeoutMs}ms`)), timeoutMs);
+                    }),
+                ]);
+                exit(0);
+            }
+            catch (error) {
+                onError(error);
+                exit(1);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+        })();
+        return inFlight;
+    }
+    function handler() {
+        void run();
+    }
+    for (const signal of signals)
+        process.on(signal, handler);
+    return {
+        remove() {
+            for (const signal of signals)
+                process.off(signal, handler);
+        },
+    };
+}

package/dist/worldServer.d.ts

@@ -2,6 +2,7 @@ import type { GameDefinition } from "@jgengine/core/game/defineGame";
 import type { GameContextContent } from "@jgengine/core/runtime/gameContext";
 import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
 import { type WorldGameHost } from "@jgengine/ws/worldHost";
+import { type WorldPersistence } from "./persistence.js";
 import { type GameWsServer, type GameWsServerOptions } from "./wsServer.js";
 /** A game the world server can host — its authoritative {@link GameDefinition} and the content lookup a `GameContext` reads. */
 export interface HostedGameDefinition {
@@ -14,6 +15,8 @@ export interface WorldGameServerOptions extends Omit<GameWsServerOptions, "host"
     resolveGame(gameId: string): HostedGameDefinition | null;
     /** Ticks per second for the real-clock loop {@link WorldGameServer.start} drives; default 30. Tests call {@link WorldGameServer.tick} manually instead. */
     tickHz?: number;
+    /** Where each hosted world's authoritative state persists; defaults to an isolated in-memory store per world (lost on exit). Inject a file/SQL/Convex-backed {@link WorldPersistence} to survive a redeploy or crash. */
+    persistence?: WorldPersistence;
 }
 /** A runnable ws host for GameContext worlds: {@link createWorldGameHost} + {@link createGameWsServer} + a tick loop, with a manual `tick(dt)` seam so a fake clock can drive it in tests. */
 export interface WorldGameServer {
@@ -25,7 +28,9 @@ export interface WorldGameServer {
     start(): void;
     /** Stop the tick interval (idempotent). */
     stop(): void;
-    /** Stop the tick loop and tear down the ws server. */
+    /** Force-persist every live world's current state via the injected {@link WorldPersistence} (idempotent — safe to call repeatedly). */
+    flush(): void;
+    /** Stop the tick loop, flush persistence, and tear down the ws server — the clean-shutdown path for a SIGINT/SIGTERM handler. */
     close(): Promise<void>;
     /** The bound ws port. */
     port(): number;

package/dist/worldServer.js

@@ -1,18 +1,27 @@
 import { createHostedWorldSession } from "@jgengine/core/runtime/hostedWorldSession";
 import { createWorldGameHost } from "@jgengine/ws/worldHost";
+import { memoryWorldPersistence } from "./persistence.js";
 import { createGameWsServer } from "./wsServer.js";
 const DEFAULT_TICK_HZ = 30;
 /** Build a {@link WorldGameServer} — one process hosting authoritative GameContext worlds over ws, ready for two-client play once {@link WorldGameServer.start} runs. */
 export function createWorldGameServer(options) {
-    const { resolveGame, tickHz = DEFAULT_TICK_HZ, ...serverOptions } = options;
+    const { resolveGame, tickHz = DEFAULT_TICK_HZ, persistence = memoryWorldPersistence(), ...serverOptions } = options;
     const clock = options.now ?? (() => Date.now());
+    const liveSessions = new Map();
     const host = createWorldGameHost({
         now: clock,
-        session: ({ gameId }) => {
+        session: ({ gameId, serverId }) => {
             const resolved = resolveGame(gameId);
             if (resolved === null)
                 return null;
-            return createHostedWorldSession({ definition: resolved.game, content: resolved.content, now: clock });
+            const session = createHostedWorldSession({
+                definition: resolved.game,
+                content: resolved.content,
+                now: clock,
+                store: persistence.store({ gameId, serverId }),
+            });
+            liveSessions.set(serverId, session);
+            return session;
         },
     });
     const ws = createGameWsServer({ ...serverOptions, host });
@@ -27,11 +36,16 @@ export function createWorldGameServer(options) {
             interval = null;
         }
     }
+    function flush() {
+        for (const session of liveSessions.values())
+            session.save();
+    }
     return {
         host,
         ws,
         tick,
         stop,
+        flush,
         port: ws.port,
         start() {
             if (interval !== null)
@@ -45,6 +59,7 @@ export function createWorldGameServer(options) {
         },
         async close() {
             stop();
+            flush();
             await ws.close();
         },
     };

package/dist/wsServer.d.ts

@@ -2,10 +2,22 @@ import type { Server as HttpServer } from "node:http";
 import { WebSocketServer } from "ws";
 import { type HostRouterOptions, type RewoundPosition } from "@jgengine/ws/hostRouter";
 export type { RewoundPosition };
+/** Default per-message payload cap (bytes) — `ws` closes the socket with 1009 past this. */
+export declare const DEFAULT_MAX_PAYLOAD_BYTES = 1048576;
+/** Default max concurrent sockets this server accepts before rejecting new ones. */
+export declare const DEFAULT_MAX_CONNECTIONS = 10000;
+/** Default ping/pong interval; a socket that misses one round-trip is terminated. */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
 export type GameWsServerOptions = HostRouterOptions & {
     server?: HttpServer;
     port?: number;
     path?: string;
+    /** Per-message payload cap in bytes. Defaults to {@link DEFAULT_MAX_PAYLOAD_BYTES}. */
+    maxPayloadBytes?: number;
+    /** Max concurrent sockets accepted; connections beyond this are closed immediately. Defaults to {@link DEFAULT_MAX_CONNECTIONS}. */
+    maxConnections?: number;
+    /** Ping/pong heartbeat interval in ms; a socket that misses a round-trip is terminated. Defaults to {@link DEFAULT_HEARTBEAT_INTERVAL_MS}. */
+    heartbeatIntervalMs?: number;
 };
 export type GameWsServer = {
     wss: WebSocketServer;

package/dist/wsServer.js

@@ -1,11 +1,40 @@
 import { WebSocketServer } from "ws";
 import { createHostRouter } from "@jgengine/ws/hostRouter";
+/** Default per-message payload cap (bytes) — `ws` closes the socket with 1009 past this. */
+export const DEFAULT_MAX_PAYLOAD_BYTES = 1_048_576;
+/** Default max concurrent sockets this server accepts before rejecting new ones. */
+export const DEFAULT_MAX_CONNECTIONS = 10_000;
+/** Default ping/pong interval; a socket that misses one round-trip is terminated. */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
 export function createGameWsServer(options) {
     const router = createHostRouter(options);
+    const maxPayload = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+    const maxConnections = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
+    const heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
     const wss = options.server !== undefined
-        ? new WebSocketServer({ server: options.server, path: options.path })
-        : new WebSocketServer({ port: options.port ?? 0, path: options.path });
+        ? new WebSocketServer({ server: options.server, path: options.path, maxPayload })
+        : new WebSocketServer({ port: options.port ?? 0, path: options.path, maxPayload });
+    const heartbeat = setInterval(() => {
+        for (const client of wss.clients) {
+            const socket = client;
+            if (socket.isAlive === false) {
+                socket.terminate();
+                continue;
+            }
+            socket.isAlive = false;
+            socket.ping();
+        }
+    }, heartbeatIntervalMs);
+    wss.on("close", () => clearInterval(heartbeat));
     wss.on("connection", (socket) => {
+        if (wss.clients.size > maxConnections) {
+            socket.close(1013, "Server at capacity");
+            return;
+        }
+        socket.isAlive = true;
+        socket.on("pong", () => {
+            socket.isAlive = true;
+        });
         const connection = router.connect({
             send: (data) => {
                 if (socket.readyState !== socket.OPEN)
@@ -28,6 +57,7 @@ export function createGameWsServer(options) {
         },
         rewind: router.rewind,
         close: () => new Promise((resolve) => {
+            clearInterval(heartbeat);
             router.close();
             for (const client of wss.clients) {
                 client.terminate();