@netforge/kit-play 0.0.0-stage → 0.2.0

package/dist/host/room.js

@@ -0,0 +1,199 @@
+// The local play room: one Colyseus room per place, speaking the engine's
+// room protocol (@netforge/engine/net protocol.ts) so the template
+// clients connect to it exactly as they connect to a hosted room. Play
+// money only: there are no wallets, no sign-in, no stakes, no pots and no
+// claims here, and earn events are shown to the player but pay nothing.
+import { Room } from "@colyseus/core";
+import { packMeta, RESERVED_COMMANDS } from "@netforge/engine/game";
+import { MSG_INPUT, MSG_SNAPSHOT, } from "@netforge/engine/net";
+import { LocalCore, SNAPSHOT_HZ } from "./core.js";
+import { isGuestId } from "./profile.js";
+let current = null;
+export function setLocalGame(g) {
+    current = g;
+}
+function game() {
+    if (!current)
+        throw new Error("local game not set");
+    return current;
+}
+/** Why local play turns these down, in the words the client shows. */
+export const LOCAL_ONLY = "Local play uses play money only";
+const INFO_EVERY_TICKS = 15;
+function parseCommand(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const o = raw;
+    if (typeof o.name !== "string" || o.name.length === 0 || o.name.length > 32)
+        return null;
+    const value = typeof o.value === "number" && Number.isFinite(o.value) ? o.value : undefined;
+    return { name: o.name, ...(value !== undefined ? { value } : {}) };
+}
+export class LocalRoom extends Room {
+    core;
+    g;
+    seats = new Map();
+    clients_ = new Map();
+    unsubscribe = null;
+    onCreate(options) {
+        this.g = game();
+        if (options?.template !== this.g.template)
+            throw new Error(`this host plays the ${this.g.template} template`);
+        const sim = this.g.sim;
+        this.maxClients = this.g.instanceCap;
+        this.autoDispose = true;
+        this.setPatchRate(null);
+        void this.setMetadata({ place: this.g.place, template: this.g.template });
+        this.core = new LocalCore(sim, this.g.aoi, (Math.random() * 2 ** 31) | 0);
+        this.unsubscribe = this.g.profiles.onChange((id) => {
+            for (const seat of this.seats.values())
+                if (seat.profile === id)
+                    this.applyProfile(seat);
+        });
+        this.onMessageBytes(MSG_INPUT, (client, bytes) => {
+            const seat = this.seats.get(client.sessionId);
+            if (seat)
+                this.core.receiveInput(seat.player, bytes);
+        });
+        this.onMessage("command", (client, raw) => {
+            const seat = this.seats.get(client.sessionId);
+            const cmd = parseCommand(raw);
+            if (!seat || !cmd)
+                return;
+            const reply = (r) => client.send("command-result", r);
+            if (!sim.command)
+                return reply({ name: cmd.name, ok: false, reason: "no store in this game" });
+            if (RESERVED_COMMANDS.has(cmd.name))
+                return reply({ name: cmd.name, ok: false, reason: "not for sale" });
+            const sold = cmd.name === "cosmetic" ? this.g.profiles.ownsCosmetic(seat.profile, cmd.value ?? 0) : this.g.storeCommands.has(cmd.name);
+            if (!sold)
+                return reply({ name: cmd.name, ok: false, reason: "not for sale" });
+            const ok = this.core.command(seat.player, { name: cmd.name, ...(cmd.value !== undefined ? { value: cmd.value } : {}) });
+            reply(ok ? { name: cmd.name, ok } : { name: cmd.name, ok, reason: "not applicable now" });
+        });
+        this.onMessage("stake", (client) => client.send("stake", { state: "refused", stake: 0, reason: LOCAL_ONLY }));
+        this.onMessage("pot", (client) => client.send("pot", { state: "refused", entry: 0, reason: LOCAL_ONLY }));
+        this.onMessage("sign-in", (client) => client.send("sign-in-result", { ok: false, runId: null, earnRefused: "guest" }));
+        this.onMessage("claim", (client) => client.send("attest-error", LOCAL_ONLY));
+        this.onMessage("ping", (client, t) => client.send("pong", t));
+        this.setSimulationInterval(() => this.tickOnce(), 1000 / sim.tickHz);
+    }
+    onJoin(client, options) {
+        const { player, entity } = this.core.addPlayer();
+        const seat = { sessionId: client.sessionId, player, entity, profile: isGuestId(options?.guest) ? `g:${options.guest}` : null, metaApplied: 0 };
+        this.seats.set(client.sessionId, seat);
+        this.clients_.set(player, client);
+        const sim = this.g.sim;
+        const welcome = {
+            player,
+            entity,
+            tickHz: sim.tickHz,
+            snapshotHz: SNAPSHOT_HZ,
+            sim: sim.name,
+            version: sim.version,
+            place: this.g.place,
+            template: this.g.template,
+            runId: null,
+            earnLive: false,
+        };
+        client.send("welcome", welcome);
+        this.applyProfile(seat);
+        this.sendInfo(seat, client, true);
+    }
+    onLeave(client) {
+        const seat = this.seats.get(client.sessionId);
+        if (!seat)
+            return;
+        this.seats.delete(client.sessionId);
+        this.clients_.delete(seat.player);
+        this.core.removePlayer(seat.player);
+    }
+    onDispose() {
+        this.unsubscribe?.();
+        this.core?.dispose();
+    }
+    applyProfile(seat) {
+        const keepers = this.g.profiles.keepers(seat.profile);
+        this.core.setRights(seat.player, keepers ? { keepers } : null);
+        const spec = this.g.profile;
+        if (spec && spec.economy.metaUpgrades && spec.meta.size > 0) {
+            const value = packMeta(spec, this.g.profiles.metaLevels(seat.profile));
+            if (value !== seat.metaApplied) {
+                this.core.command(seat.player, { name: "meta", value });
+                seat.metaApplied = value;
+            }
+        }
+        this.clients_.get(seat.player)?.send("profile", this.g.profiles.view(seat.profile));
+    }
+    sendInfo(seat, client, force) {
+        const sim = this.g.sim;
+        if (sim.infoFor) {
+            const v = sim.infoFor(this.core.world, seat.player);
+            if (v === null || v === undefined)
+                return;
+            const json = JSON.stringify(v);
+            if (!force && json === seat.lastInfo)
+                return;
+            seat.lastInfo = json;
+            client.send("run", v);
+            return;
+        }
+        const info = sim.info?.(this.core.world);
+        if (info)
+            client.send("run", info);
+    }
+    recordProgress(e) {
+        if (!this.g.profile)
+            return;
+        const c = this.clients_.get(e.player);
+        const seat = c ? this.seats.get(c.sessionId) : undefined;
+        if (seat?.profile)
+            this.g.profiles.record(seat.profile, e.kind, e.id);
+    }
+    tickOnce() {
+        const res = this.core.step();
+        let reset = false;
+        for (const e of res.events) {
+            if (e.type === "run.reset")
+                reset = true;
+            else if (e.type === "progress")
+                this.recordProgress(e);
+            else
+                this.clients_.get(e.player)?.send("earn", { rule: e.rule, units: e.units });
+        }
+        for (const [player, bytes] of res.snapshots)
+            this.clients_.get(player)?.sendBytes(MSG_SNAPSHOT, bytes);
+        const sim = this.g.sim;
+        if (res.tick % (sim.infoEveryTicks ?? INFO_EVERY_TICKS) === 0) {
+            if (sim.infoFor) {
+                for (const seat of this.seats.values()) {
+                    const c = this.clients_.get(seat.player);
+                    if (c)
+                        this.sendInfo(seat, c, false);
+                }
+            }
+            else if (sim.info) {
+                const info = sim.info(this.core.world);
+                if (info)
+                    this.broadcast("run", info);
+            }
+        }
+        if (reset)
+            this.newRun();
+    }
+    /** The sim ended a run: a fresh world, as the hosted room does between runs. Players stay connected. */
+    newRun() {
+        const entities = this.core.rebase((Math.random() * 2 ** 31) | 0);
+        const sim = this.g.sim;
+        for (const seat of this.seats.values()) {
+            const entity = entities.get(seat.player);
+            if (entity === undefined)
+                continue;
+            seat.entity = entity;
+            seat.lastInfo = undefined;
+            seat.metaApplied = 0;
+            this.clients_.get(seat.player)?.send("rebase", { entity, sim: sim.name, version: sim.version });
+            this.applyProfile(seat);
+        }
+    }
+}

package/dist/host/server.d.ts

@@ -0,0 +1,28 @@
+import { type LocalGame } from "./room.js";
+export interface HostOptions {
+    readonly port: number;
+    /** Interface to bind; 127.0.0.1 keeps the game on this computer. */
+    readonly host: string;
+    /** The built client (index.html and its assets). */
+    readonly clientDir: string;
+    /** The built asset library (index.json and the style folders), or null to serve none. */
+    readonly libraryDir: string | null;
+}
+export interface RunningHost {
+    readonly url: string;
+    close(): Promise<void>;
+}
+/** Rooms one local host keeps open at once (each runs its own sim). */
+export declare const MAX_ROOMS = 8;
+/** A file under `root` for a request path, or null (never outside root). */
+export declare function fileUnder(root: string, urlPath: string): string | null;
+/**
+ * On a loopback bind, only requests addressed to this computer by name are
+ * answered (a page elsewhere that rebinds its own host name to 127.0.0.1
+ * gets 403). On any other bind (--host 0.0.0.0 for phones on the network)
+ * the Host must still be an address, not a DNS name, so the same rebinding
+ * trick fails there too. Either way only same-origin or non-browser
+ * requests may POST or open a WebSocket.
+ */
+export declare function allowedRequest(bindHost: string, port: number, host: string | undefined, origin: string | undefined, method: string | undefined): boolean;
+export declare function startServer(g: LocalGame, o: HostOptions): Promise<RunningHost>;

package/dist/host/server.js

@@ -0,0 +1,255 @@
+// The local play host's HTTP side, on one port: the built game page, the
+// asset library, the seat request (POST /world/join) and in-memory profiles,
+// with Colyseus behind them for the room itself. It binds to 127.0.0.1
+// unless told otherwise. Sign-in, the referee and every money route answer
+// 403: local play has none of them.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { extname, normalize, resolve, sep } from "node:path";
+import { defineRoom, defineServer, matchMaker } from "@colyseus/core";
+import { WebSocketTransport } from "@colyseus/ws-transport";
+import { ROOM_NAME } from "@netforge/engine/net";
+import { LOCAL_ONLY, LocalRoom, setLocalGame } from "./room.js";
+import { isGuestId } from "./profile.js";
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".wasm": "application/wasm",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".jpg": "image/jpeg",
+    ".glb": "model/gltf-binary",
+    ".ktx2": "image/ktx2",
+    ".ogg": "audio/ogg",
+    ".mp3": "audio/mpeg",
+    ".woff2": "font/woff2",
+};
+const MAX_BODY = 64 * 1024;
+/** Rooms one local host keeps open at once (each runs its own sim). */
+export const MAX_ROOMS = 8;
+function send(res, status, body) {
+    if (res.headersSent)
+        return;
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+}
+/** A file under `root` for a request path, or null (never outside root). */
+export function fileUnder(root, urlPath) {
+    let rel;
+    try {
+        rel = decodeURIComponent(urlPath);
+    }
+    catch {
+        return null;
+    }
+    if (rel.includes("\0"))
+        return null;
+    const base = resolve(root);
+    const file = resolve(base, "." + normalize("/" + rel));
+    if (file !== base && !file.startsWith(base + sep))
+        return null;
+    if (!existsSync(file) || !statSync(file).isFile())
+        return null;
+    return file;
+}
+function serveFile(res, file) {
+    res.writeHead(200, { "content-type": TYPES[extname(file).toLowerCase()] ?? "application/octet-stream", "cache-control": "no-cache" });
+    res.end(readFileSync(file));
+}
+function readBody(req) {
+    return new Promise((ok, fail) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_BODY) {
+                fail(new Error("body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => {
+            if (chunks.length === 0)
+                return ok({});
+            try {
+                ok(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                ok({});
+            }
+        });
+        req.on("error", fail);
+    });
+}
+const obj = (v) => (typeof v === "object" && v !== null && !Array.isArray(v) ? v : {});
+async function joinSeat(g, body) {
+    if (body.template !== g.template)
+        throw new Error(`this host plays the ${g.template} template`);
+    const place = typeof body.place === "string" && body.place.length > 0 && body.place.length <= 64 ? body.place : g.place;
+    const rooms = await matchMaker.query({ name: ROOM_NAME });
+    const open = rooms.find((r) => r.metadata?.place === place && !r.locked && r.clients < r.maxClients);
+    if (!open && rooms.length >= MAX_ROOMS)
+        throw new Error("too many rooms on this computer");
+    const room = open ?? (await matchMaker.createRoom(ROOM_NAME, { place, template: g.template }));
+    const reservation = await matchMaker.reserveSeatFor(room, isGuestId(body.guest) ? { guest: body.guest } : {});
+    return { roomId: room.roomId, reason: open ? "joined" : "created", reservations: [reservation] };
+}
+async function route(g, o, req, res) {
+    const url = new URL(req.url ?? "/", "http://local");
+    const path = url.pathname;
+    if (path === "/health")
+        return send(res, 200, { ok: true, local: true, template: g.template }), true;
+    if (path.startsWith("/auth/") || path.startsWith("/referee/") || path.startsWith("/admin/"))
+        return send(res, 403, { error: LOCAL_ONLY }), true;
+    if (path === "/world/join" && req.method === "POST") {
+        try {
+            send(res, 200, await joinSeat(g, obj(await readBody(req))));
+        }
+        catch (e) {
+            send(res, 409, { error: e instanceof Error ? e.message : "join failed" });
+        }
+        return true;
+    }
+    if (path.startsWith("/profile")) {
+        const guest = req.headers["x-guest-id"];
+        const id = isGuestId(guest) ? `g:${guest}` : null;
+        if (req.method === "GET" && path.startsWith("/profile/game/"))
+            return send(res, 200, g.profiles.view(id)), true;
+        if (req.method === "GET" && path === "/profile")
+            return send(res, 200, { kind: id ? "guest" : null, wallet: null, displayName: null, settings: {}, totals: { achievements: 0, titles: 0, games: 0 }, games: [] }), true;
+        if (req.method !== "POST")
+            return send(res, 405, { error: "method" }), true;
+        let body;
+        try {
+            body = obj(await readBody(req));
+        }
+        catch {
+            return send(res, 413, { error: "body too large" }), true;
+        }
+        if (!id)
+            return send(res, 400, { error: "a guest id is required" }), true;
+        if (path === "/profile/settings")
+            g.profiles.settings(id, body.settings);
+        else if (path === "/profile/name")
+            g.profiles.name(id, body.displayName);
+        else if (path === "/profile/redeem") {
+            const r = g.profiles.redeem(id, typeof body.item === "string" ? body.item : "");
+            if (!r.ok)
+                return send(res, 400, { error: r.error ?? "refused" }), true;
+        }
+        else if (path !== "/profile/import" && path !== "/profile/claim")
+            return send(res, 404, { error: "not found" }), true;
+        return send(res, 200, g.profiles.view(id)), true;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD")
+        return send(res, 404, { error: "not found" }), true;
+    if (path.startsWith("/library/")) {
+        const file = o.libraryDir ? fileUnder(o.libraryDir, path.slice("/library/".length)) : null;
+        if (!file)
+            return send(res, 404, { error: "not in the asset library" }), true;
+        return serveFile(res, file), true;
+    }
+    const file = fileUnder(o.clientDir, path === "/" ? "index.html" : path.slice(1));
+    if (!file)
+        return send(res, 404, { error: "not found" }), true;
+    serveFile(res, file);
+    return true;
+}
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+/** The host name of a Host header value ("192.168.1.5:4663", "[fe80::1]:4663"), lower case. */
+function hostName(host) {
+    const h = host.trim().toLowerCase();
+    if (h.startsWith("[")) {
+        const end = h.indexOf("]");
+        return end > 0 ? h.slice(0, end + 1) : h;
+    }
+    return h.replace(/:\d+$/, "");
+}
+/**
+ * A name a DNS rebinding page cannot put in the Host header: an IP literal,
+ * localhost, or an mDNS .local name (resolved on the network itself, never
+ * by a public DNS server an attacker controls).
+ */
+function directName(name) {
+    return LOOPBACK.has(name) || /^\d{1,3}(\.\d{1,3}){3}$/.test(name) || /^\[[0-9a-f:.]+\]$/.test(name) || /^[a-z0-9-]+(\.[a-z0-9-]+)*\.local$/.test(name);
+}
+/**
+ * On a loopback bind, only requests addressed to this computer by name are
+ * answered (a page elsewhere that rebinds its own host name to 127.0.0.1
+ * gets 403). On any other bind (--host 0.0.0.0 for phones on the network)
+ * the Host must still be an address, not a DNS name, so the same rebinding
+ * trick fails there too. Either way only same-origin or non-browser
+ * requests may POST or open a WebSocket.
+ */
+export function allowedRequest(bindHost, port, host, origin, method) {
+    const loopback = LOOPBACK.has(bindHost);
+    const name = hostName(host ?? "");
+    if (loopback ? !LOOPBACK.has(name) : !directName(name))
+        return false;
+    if (method === "GET" || method === "HEAD" || origin === undefined)
+        return true;
+    try {
+        const o = new URL(origin);
+        const oName = o.hostname.toLowerCase();
+        if (o.protocol !== "http:" || Number(o.port || 80) !== port)
+            return false;
+        return loopback ? LOOPBACK.has(oName) : oName === name || (LOOPBACK.has(oName) && LOOPBACK.has(name));
+    }
+    catch {
+        return false;
+    }
+}
+export async function startServer(g, o) {
+    setLocalGame(g);
+    const http = createServer();
+    const emit = http.emit.bind(http);
+    // Our routes answer first; Colyseus sees only what is left (the WebSocket upgrades that consume a seat).
+    http.emit = ((event, ...args) => {
+        if (event !== "request")
+            return emit(event, ...args);
+        const req = args[0];
+        const res = args[1];
+        const path = (req.url ?? "/").split("?")[0] ?? "/";
+        const origin = typeof req.headers.origin === "string" ? req.headers.origin : undefined;
+        if (!allowedRequest(o.host, o.port, req.headers.host, origin, req.method))
+            return send(res, 403, { error: "local play answers this computer only" }), true;
+        // Seats come only from /world/join; Colyseus' own HTTP matchmaking (which could open rooms without limit) is closed.
+        if (path.startsWith("/matchmake"))
+            return send(res, 403, { error: "seats come from /world/join" }), true;
+        void route(g, o, req, res).catch(() => send(res, 500, { error: "local host error" }));
+        return true;
+    });
+    // WebSocket upgrades pass the same Host and Origin check as requests.
+    const upgradeEmit = http.emit;
+    http.emit = ((event, ...args) => {
+        if (event === "upgrade") {
+            const req = args[0];
+            const origin = typeof req.headers.origin === "string" ? req.headers.origin : undefined;
+            if (!allowedRequest(o.host, o.port, req.headers.host, origin, "POST")) {
+                args[1].destroy();
+                return true;
+            }
+        }
+        return upgradeEmit.call(http, event, ...args);
+    });
+    const server = defineServer({
+        transport: new WebSocketTransport({ server: http, pingInterval: 5000, pingMaxRetries: 3 }),
+        rooms: { [ROOM_NAME]: defineRoom(LocalRoom) },
+        greet: false,
+        gracefullyShutdown: false,
+    });
+    await server.listen(o.port, o.host);
+    const shown = o.host === "0.0.0.0" || o.host === "::" ? "localhost" : o.host;
+    return {
+        url: `http://${shown}:${o.port}`,
+        close: async () => {
+            await server.gracefullyShutdown(false).catch(() => undefined);
+            http.close();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { COMMANDS_HELP, HELP, runKitPlayCli, runPlayCli, runTestCli, TEST_HELP, type PlayCliIo } from "./cli.js";
+export { check, summary, type CheckOptions, type CheckReport, type CheckResult } from "./check.js";
+export { ALLOWED_IMPORT, play, PlayError, readGameFolder, type GameFolder, type PlayOptions, type Playing } from "./play.js";
+export { TEMPLATES, templateFor, type TemplateEntry, type TemplateId } from "./templates.js";
+export { namesModule, parseNames, type Names } from "./names.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { COMMANDS_HELP, HELP, runKitPlayCli, runPlayCli, runTestCli, TEST_HELP } from "./cli.js";
+export { check, summary } from "./check.js";
+export { ALLOWED_IMPORT, play, PlayError, readGameFolder } from "./play.js";
+export { TEMPLATES, templateFor } from "./templates.js";
+export { namesModule, parseNames } from "./names.js";

package/dist/names.d.ts

@@ -0,0 +1,18 @@
+export interface Names {
+    readonly title: string;
+    readonly weapons: Readonly<Record<string, {
+        readonly name: string;
+        readonly line: string;
+    }>>;
+    readonly upgrades: Readonly<Record<string, {
+        readonly name: string;
+        readonly line: string;
+    }>>;
+    readonly enemies: Readonly<Record<string, string>>;
+    readonly rules: Readonly<Record<string, string>>;
+    readonly skus: Readonly<Record<string, string>>;
+}
+/** Parses src/names.json; throws with the first problem. */
+export declare function parseNames(text: string): Names;
+/** The names module: everything the template's names.ts exports, with these labels in place of its tables. */
+export declare function namesModule(n: Names, templateNamesPath: string): string;

package/dist/names.js

@@ -0,0 +1,64 @@
+// src/names.json, the labels file next to game.ts, as the template client's
+// names module: the template's own names.ts with the creator's labels in
+// place of its tables. The labels are data written as JSON literals, so
+// nothing in the file can execute.
+const ID = /^[a-z][a-z0-9_]{0,47}$/;
+const label = (v) => typeof v === "string" && v.trim().length > 0 && v.length <= 40;
+function table(v, ok, what) {
+    if (v === undefined)
+        return {};
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        throw new Error(`src/names.json ${what} must be an object`);
+    const out = {};
+    for (const [k, x] of Object.entries(v)) {
+        if (!ID.test(k))
+            throw new Error(`src/names.json ${what}.${k}: ids are lower case letters, digits and _`);
+        if (!ok(x))
+            throw new Error(`src/names.json ${what}.${k}: not a label (1 to 40 characters)`);
+        out[k] = x;
+    }
+    return out;
+}
+const named = (x) => {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const o = x;
+    return label(o.name) && label(o.line) && Object.keys(o).length === 2;
+};
+/** Parses src/names.json; throws with the first problem. */
+export function parseNames(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`src/names.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("src/names.json must be an object");
+    const o = raw;
+    if (!label(o.title))
+        throw new Error("src/names.json title: 1 to 40 characters");
+    return {
+        title: o.title.trim(),
+        weapons: table(o.weapons, named, "weapons"),
+        upgrades: table(o.upgrades, named, "upgrades"),
+        enemies: table(o.enemies, label, "enemies"),
+        rules: table(o.rules, label, "rules"),
+        skus: table(o.skus, label, "skus"),
+    };
+}
+/** The names module: everything the template's names.ts exports, with these labels in place of its tables. */
+export function namesModule(n, templateNamesPath) {
+    const j = (v) => JSON.stringify(v);
+    return [
+        `export * from ${j(templateNamesPath)};`,
+        `export const TITLE = ${j(n.title)};`,
+        `export const WEAPON_NAMES = ${j(n.weapons)};`,
+        `export const UPGRADE_NAMES = ${j(n.upgrades)};`,
+        `export const ENEMY_NAMES = ${j(n.enemies)};`,
+        `export const RULE_NAMES = ${j(n.rules)};`,
+        `export const SKU_NAMES = ${j(n.skus)};`,
+        "",
+    ].join("\n");
+}

package/dist/play.d.ts

@@ -0,0 +1,51 @@
+import { networkInterfaces } from "node:os";
+import { type Names } from "./names.js";
+import { type TemplateEntry } from "./templates.js";
+/** The only import a game module may make (the studio's rule, kept here so a game that plays locally plays in the studio). */
+export declare const ALLOWED_IMPORT = "@netforge/engine";
+export interface PlayOptions {
+    readonly dir: string;
+    readonly port: number;
+    readonly host: string;
+    readonly open: boolean;
+    /** Browser tabs to open, one per local player. */
+    readonly players: number;
+    /** A base URL the page loads the asset library from instead of this host (any mirror of the published library). */
+    readonly libraryUrl: string | null;
+    readonly log: (s: string) => void;
+}
+export interface GameFolder {
+    readonly dir: string;
+    readonly template: TemplateEntry;
+    readonly gameFile: string;
+    readonly names: Names | null;
+}
+export declare class PlayError extends Error {
+}
+/** Reads and checks the game folder. */
+export declare function readGameFolder(dir: string): GameFolder;
+/** The template package's root (its "." export is src/manifest.ts). */
+export declare function templateDir(t: TemplateEntry, from: string): string;
+/** The built asset library shipped in @netforge/asset-library-files, or null when it is not installed. */
+export declare function libraryDir(from: string): string | null;
+/**
+ * The page link for a host base URL. The template clients connect to the
+ * room named by ?server= (without it they fall back to their dev port), so
+ * every link carries the server it was served from.
+ */
+export declare function playLink(base: string, libraryUrl: string | null): string;
+/** Links other devices can open when the host listens on every interface: one per IPv4 network address. */
+export declare function lanLinks(host: string, port: number, interfaces: ReturnType<typeof networkInterfaces>, libraryUrl: string | null): string[];
+/** Builds the template client with the game module and labels swapped in. */
+export declare function buildClient(g: GameFolder, tplDir: string, outDir: string, cacheDir: string): Promise<void>;
+/** The esbuild plugin that puts the game folder's src/game.ts in place of the template's and holds it to ALLOWED_IMPORT. */
+export declare function gameSwap(manifest: string, gameFile: string, tplDir: string): import("esbuild").Plugin;
+/** Bundles the local host with the game module (one copy of the engine and the sim). Returns the bundle path. */
+export declare function bundleHost(g: GameFolder, tplDir: string, outFile: string): Promise<string>;
+export interface Playing {
+    readonly url: string;
+    /** Links for other devices on the network (with --host 0.0.0.0), each carrying its own ?server=. */
+    readonly lan: readonly string[];
+    close(): Promise<void>;
+}
+export declare function play(o: PlayOptions): Promise<Playing>;