@netforge/kit-play 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetNet Capital Management
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,13 @@
+@netforge/kit-play
+Copyright (c) 2026 NetNet Capital Management
+
+Dependencies (unmodified, via npm)
+- @colyseus/core 0.18.18 and @colyseus/ws-transport 0.18.4 (https://github.com/colyseus/colyseus), MIT, Endel Dreyer.
+- vite 6.4.3 (https://github.com/vitejs/vite), MIT.
+- esbuild 0.25.12 (https://github.com/evanw/esbuild), MIT.
+- The Net Forge engine packages (@netforge/engine, -sim, asset-library,
+  asset-library-files, tabletop, template-*); see each package's NOTICE.
+
+The local host (src/host) is written for this package on the engine's open
+netcode (@netforge/engine/net). It holds no code from the hosted room
+server or the referee.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @netforge/kit-play
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of Net Forge, the open-source multiplayer browser game engine built for AI coding agents (`@netforge` on npm, https://github.com/netnetdev/net-forge and https://forge.netnet.capital/docs). Not affiliated with other projects named NetForge.
+
+`kit play` runs a Net Forge game on your own computer with play money: it builds the template's browser client with your `src/game.ts` and starts a local room host for the same game module, with no wallet, no chain and no Net Forge servers.
+It also starts new games from a template and tests them with playtest bots.
+
+| Command | What it does |
+|---|---|
+| `kit-play play [dir]` | Build the game in `dir` (default: here) and play it. `kit-play [dir]` does the same. |
+| `kit-play test [dir]` | Compile `src/game.ts` as the play build does and run the playtest bots. No browser. Exits 1 on a failure; `--json` prints the report. |
+| `kit-play check [dir]` | `kit-play test` with the report as JSON on stdout. |
+| `kit-play new [folder] --template <id>` | Start a new game. The same as `npm create netforge@latest`; see [create-netforge](../create-netforge). |
+| `kit-play templates [--json]` | List the ten templates. |
+
+`kit-play test` takes `--minutes <n>` (minutes of game time at the
+template's own tick rate, default 1), `--bots <n>` and `--seed <n>`.
+
+With `--host 0.0.0.0`, `kit-play play` also prints a link for each network
+address of this computer. Open that link on a phone or another computer:
+it carries `?server=`, which tells the page which room to join.
+
+## Install
+
+```sh
+npm install @netforge/kit-play
+```
+
+Node 20 or later. The package brings the engine, the asset library files and every template with it. The bin is `kit-play`; `kit play` through `@netforge/kit` runs the same command.
+
+## Example
+
+A game folder needs `netnet.json` (which template) and `src/game.ts` (the game). `src/names.json` (the title and labels) is optional. To start from a template:
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine
+cp node_modules/@netforge/template-survivor/src/game.ts src/
+echo '{"template":"survivor"}' > netnet.json
+npx kit-play                 # opens http://127.0.0.1:4663
+npx kit-play --players 2     # two tabs, two local players
+```
+
+Edit `src/game.ts` and run it again to try a change. Open the link in more tabs or windows for more players. The build lands in `.netnet/play/` inside the game folder.
+
+Template ids for `netnet.json`: `survivor`, `arena`, `tower-defense`, `dungeon`, `idle`, `platformer`, `cards`, `collector`, `racer`, `party`.
+
+## Flags
+
+| Flag | Default | |
+|---|---|---|
+| `--port <n>` | 4663 | the page and the room, one port |
+| `--host <addr>` | 127.0.0.1 | `0.0.0.0` lets devices on your network join |
+| `--players <n>` | 1 | browser tabs to open (1 to 16) |
+| `--no-open` | | print the link only |
+| `--library-url <url>` | the installed library | load models and sounds from a mirror instead |
+
+From code: `import { play } from "@netforge/kit-play"` takes `{ dir, port, host, open, players, libraryUrl, log }` and resolves to `{ url, close() }`. `readGameFolder(dir)` checks a folder without running it, and `TEMPLATES` lists the templates it can run.
+
+## What it does not do
+
+- No wallet, no chain, no real tokens. Coins are play money in the page.
+- No calls to Net Forge servers. The page is built with no `VITE_*` environment and talks only to the local host; sign-in, the referee and every money route answer 403.
+- No stakes, pots or claims. Earn rules still fire, so you can see them, and pay nothing.
+- No saved progress. Achievements and looks bought with play money live in memory and are gone when `kit play` stops.
+
+The local host is built from the engine's open simulation (`@netforge/engine`, `@netforge/engine-sim`). The hosted room server and the referee that decides real payouts are not part of it.
+
+kit play is not a sandbox: it runs the game's code (the room host in Node, the client in your browser) with your permissions. Play only games whose code you trust, as with any program you run.
+
+`src/game.ts` may import only `@netforge/engine`, as in the Net Forge studio, so a game that plays here plays there.
+
+## For AI agents
+
+- Read `llms.txt` in this package, and the template's own `AGENTS.md` and `llms.txt`.
+- The Net Forge MCP server runs local play for an agent with the `netforge_play_locally` tool, next to `netforge_validate_game` and `netforge_run_playtest`: `npx -y @netforge/mcp` (package `@netforge/mcp`, bin `netforge-mcp`).
+- `npx netforge setup agent` writes AGENTS.md, CLAUDE.md, Cursor rules and `.mcp.json` into a game project. In Claude Code: `claude mcp add netforge -- npx -y @netforge/mcp`.
+
+## Docs
+
+- https://forge.netnet.capital/docs/packages/kit-play
+- `llms.txt` in this package
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.

package/dist/check.d.ts

@@ -0,0 +1,43 @@
+export interface CheckOptions {
+    readonly dir: string;
+    /** Minutes of game time to play, at the template's own tick rate. */
+    readonly minutes: number;
+    /** Bots playing; null for the template's default. */
+    readonly bots: number | null;
+    readonly seed: number;
+    readonly log: (s: string) => void;
+}
+/** What the engine's playtest reports (the fields this command reads; the rest pass through to --json). */
+export interface CheckReport {
+    readonly ticks: number;
+    readonly bots: number;
+    readonly kills: number;
+    readonly deaths: number;
+    readonly wave: number;
+    readonly maxLevel: number;
+    readonly earnEmitted: number;
+    readonly earned: Readonly<Record<string, number>>;
+    readonly softlock: boolean;
+    readonly msPerTick: number;
+    readonly rules?: {
+        readonly template: string;
+        readonly checks: readonly {
+            readonly ok: boolean;
+            readonly line: string;
+        }[];
+        readonly progress: number;
+    };
+    readonly failed: readonly string[];
+}
+export interface CheckResult {
+    readonly ok: boolean;
+    readonly template: string;
+    /** Why it failed, one line each (empty when ok). */
+    readonly problems: readonly string[];
+    /** Simulation ticks per second of game time (the template's own rate). */
+    readonly tickRate?: number;
+    readonly report: CheckReport | null;
+}
+export declare function check(o: CheckOptions): Promise<CheckResult>;
+/** The report in a few lines. */
+export declare function summary(r: CheckResult): string[];

package/dist/check.js

@@ -0,0 +1,106 @@
+// `kit-play test`: compile the game folder's src/game.ts the way the play
+// build does and run the engine's headless playtest (engine.test.run) on
+// it with bots. No browser, no server, no network: a quick check after
+// every change, made for coding agents as much as for people.
+import { mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { gameSwap, PlayError, readGameFolder, templateDir } from "./play.js";
+/** Bundles the template's manifest with the folder's game module, plus the engine's playtest. Returns the bundle path. */
+async function bundleCheck(gameFile, tplDir, outFile) {
+    const esbuild = await import("esbuild");
+    const manifest = realpathSync(join(tplDir, "src", "manifest.ts"));
+    const contents = [`export * as template from ${JSON.stringify(manifest)};`, `export { engine } from "@netforge/engine";`, `export { initSim } from "@netforge/engine-sim";`].join("\n");
+    const out = await esbuild.build({
+        stdin: { contents, resolveDir: join(tplDir, "src"), sourcefile: "kit-play-test.js", loader: "js" },
+        bundle: true,
+        platform: "node",
+        format: "esm",
+        target: "node20",
+        write: false,
+        logLevel: "silent",
+        plugins: [gameSwap(manifest, realpathSync(gameFile), tplDir)],
+        banner: { js: "import { createRequire as __kpRequire } from 'node:module'; const require = __kpRequire(import.meta.url);" },
+    });
+    const file = out.outputFiles[0];
+    if (!file)
+        throw new PlayError("the test bundle produced no output");
+    mkdirSync(dirname(outFile), { recursive: true });
+    writeFileSync(outFile, file.text);
+    return outFile;
+}
+/** esbuild's and the engine's errors as the lines a person (or an agent) needs. */
+function problemLines(e) {
+    const errors = e.errors;
+    if (Array.isArray(errors) && errors.length > 0)
+        return errors.map((x) => (x.location ? `${x.location.file}:${x.location.line}:${x.location.column}: ${x.text}` : x.text));
+    return [e instanceof Error ? e.message : String(e)];
+}
+export async function check(o) {
+    const dir = resolve(o.dir);
+    const g = readGameFolder(dir);
+    const tplDir = templateDir(g.template, dir);
+    const t = g.template;
+    o.log(`Compiling src/game.ts (${t.label})...`);
+    let mod;
+    try {
+        // A fresh file name per run: a module imported once stays cached for the process.
+        const bundle = await bundleCheck(g.gameFile, tplDir, join(dir, ".netnet", "play", `test-${process.pid}-${Date.now()}.mjs`));
+        try {
+            mod = (await import(pathToFileURL(bundle).href));
+        }
+        finally {
+            rmSync(bundle, { force: true });
+        }
+    }
+    catch (e) {
+        return { ok: false, template: t.id, problems: problemLines(e), report: null };
+    }
+    let tickRate = 30;
+    try {
+        await mod.initSim();
+        const get = mod.template[t.manifest.fn];
+        const make = mod.template[t.adapter];
+        if (typeof get !== "function" || typeof make !== "function")
+            throw new PlayError(`the template does not export ${t.manifest.fn} and ${t.adapter}`);
+        const got = get();
+        tickRate = (t.manifest.field ? got.manifest?.game?.tickRate : got.game?.tickRate) ?? 30;
+        make();
+    }
+    catch (e) {
+        return { ok: false, template: t.id, problems: problemLines(e), report: null };
+    }
+    const bots = o.bots ?? Math.min(t.seats, 2);
+    // The template's own tick rate (the racer and the arena shooter run at 60 Hz), so a minute is a minute of game time.
+    const ticks = Math.round(o.minutes * 60 * tickRate);
+    o.log(`Playtest: ${bots} bot${bots === 1 ? "" : "s"} for ${o.minutes} minute${o.minutes === 1 ? "" : "s"} of game time...`);
+    let report;
+    try {
+        report = await mod.engine.test.run({ ticks, bots, seed: o.seed, tickRate });
+    }
+    catch (e) {
+        return { ok: false, template: t.id, problems: problemLines(e), report: null };
+    }
+    const problems = [...report.failed.map((f) => `check failed: ${f}`), ...(report.rules?.checks ?? []).filter((c) => !c.ok).map((c) => `check failed: ${c.line}`)];
+    if (report.softlock)
+        problems.push("softlock: nothing changed for 30 seconds of game time (no kills, no damage, no movement)");
+    return { ok: problems.length === 0, template: t.id, problems: [...new Set(problems)], tickRate, report };
+}
+/** The report in a few lines. */
+export function summary(r) {
+    if (!r.report)
+        return [];
+    const x = r.report;
+    const earned = Object.entries(x.earned)
+        .map(([k, v]) => `${k} ${v}`)
+        .join(", ");
+    return [
+        `  kills ${x.kills}, downs ${x.deaths}, wave ${x.wave}, top level ${x.maxLevel}`,
+        `  earn rules fired ${x.earnEmitted} time${x.earnEmitted === 1 ? "" : "s"}${earned ? ` (${earned})` : ""}`,
+        // A check's line says what went wrong, so only failing ones are shown.
+        ...(x.rules ? [`  ${x.rules.checks.filter((c) => c.ok).length} of ${x.rules.checks.length} genre checks passed`] : []),
+        ...(x.rules ? x.rules.checks.filter((c) => !c.ok).map((c) => `  FAIL ${c.line}`) : []),
+        ...(x.rules ? [`  progress ${Math.round(x.rules.progress * 100)}%`] : []),
+        `  ${x.msPerTick.toFixed(2)} ms per tick on this computer`,
+    ];
+}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+export declare const HELP = "kit play: run a Net Forge game on this computer with play money.\n\nUsage: kit play [dir] [flags]     (inside the folder you downloaded from Net Forge)\n\n  --port <n>          Port for the page and the local room (default 4663).\n  --host <addr>       Interface to listen on (default 127.0.0.1, this computer only).\n                      Use 0.0.0.0 to let devices on your network join.\n  --players <n>       Browser tabs to open, one per local player (default 1).\n  --no-open           Print the link instead of opening a browser.\n  --library-url <u>   Load the asset library from this URL instead of the installed copy.\n\nNo wallet, no chain, no Net Forge servers: coins are play money and nothing pays out.\nkit play runs the game's own code on this computer with your permissions (it is not a\nsandbox): play only games whose code you trust.";
+export declare const COMMANDS_HELP = "kit-play: make, test and play Net Forge games on this computer with play money.\n\nUsage:\n  kit-play play [dir] [flags]       Build the game in dir (default: here) and play it. kit-play play --help for flags.\n  kit-play test [dir] [flags]       Compile src/game.ts and run the playtest bots, no browser.\n  kit-play check [dir] [flags]      The same, with the report as JSON on stdout.\n  kit-play new [folder] [flags]     Start a new game from a template (the same as npm create netforge).\n  kit-play templates [--json]       List the templates.\n\nkit-play [dir] without a command plays, as before.";
+export declare const TEST_HELP = "kit-play test: compile src/game.ts as the play build does and run the playtest bots.\n\nUsage: kit-play test [dir] [flags]\n\n  --minutes <n>   Minutes of game time the bots play, at the template's own tick rate (default 1, up to 30).\n  --bots <n>      Bots playing (default: 2, or fewer when the template seats fewer).\n  --seed <n>      Random seed (default 1).\n  --json          Print the result as JSON on stdout.\n\nExits 0 when the game compiles and every playtest check passes, 1 otherwise.";
+export interface PlayCliIo {
+    out(s: string): void;
+    err(s: string): void;
+    cwd: string;
+}
+export declare function runPlayCli(argv: readonly string[], io: PlayCliIo): Promise<number>;
+export declare function runTestCli(argv: readonly string[], io: PlayCliIo): Promise<number>;
+/** The kit-play command: play (the default), test, new and templates. */
+export declare function runKitPlayCli(argv: readonly string[], io: PlayCliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+// kit-play [play] [dir] [--port 4663] [--host 127.0.0.1] [--players 1] [--no-open] [--library-url <url>]
+// kit-play test [dir] [--minutes 1] [--bots n] [--seed 1] [--json]
+// kit-play check [dir] ...                          (test --json)
+// kit-play new [folder] [--template <id>] ...      (create-netforge)
+// kit-play templates [--json]
+// `kit play` through @netforge/kit reaches runPlayCli directly.
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { listTemplates, nodeIo, runCreate } from "create-netforge";
+import { check, summary } from "./check.js";
+import { play, PlayError } from "./play.js";
+export const HELP = `kit play: run a Net Forge game on this computer with play money.
+
+Usage: kit play [dir] [flags]     (inside the folder you downloaded from Net Forge)
+
+  --port <n>          Port for the page and the local room (default 4663).
+  --host <addr>       Interface to listen on (default 127.0.0.1, this computer only).
+                      Use 0.0.0.0 to let devices on your network join.
+  --players <n>       Browser tabs to open, one per local player (default 1).
+  --no-open           Print the link instead of opening a browser.
+  --library-url <u>   Load the asset library from this URL instead of the installed copy.
+
+No wallet, no chain, no Net Forge servers: coins are play money and nothing pays out.
+kit play runs the game's own code on this computer with your permissions (it is not a
+sandbox): play only games whose code you trust.`;
+export const COMMANDS_HELP = `kit-play: make, test and play Net Forge games on this computer with play money.
+
+Usage:
+  kit-play play [dir] [flags]       Build the game in dir (default: here) and play it. kit-play play --help for flags.
+  kit-play test [dir] [flags]       Compile src/game.ts and run the playtest bots, no browser.
+  kit-play check [dir] [flags]      The same, with the report as JSON on stdout.
+  kit-play new [folder] [flags]     Start a new game from a template (the same as npm create netforge).
+  kit-play templates [--json]       List the templates.
+
+kit-play [dir] without a command plays, as before.`;
+export const TEST_HELP = `kit-play test: compile src/game.ts as the play build does and run the playtest bots.
+
+Usage: kit-play test [dir] [flags]
+
+  --minutes <n>   Minutes of game time the bots play, at the template's own tick rate (default 1, up to 30).
+  --bots <n>      Bots playing (default: 2, or fewer when the template seats fewer).
+  --seed <n>      Random seed (default 1).
+  --json          Print the result as JSON on stdout.
+
+Exits 0 when the game compiles and every playtest check passes, 1 otherwise.`;
+export async function runPlayCli(argv, io) {
+    const flags = new Map();
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a.startsWith("--")) {
+            const [k, v] = a.slice(2).split("=", 2);
+            const next = argv[i + 1];
+            if (v !== undefined)
+                flags.set(k, v);
+            else if (k !== "no-open" && k !== "help" && next !== undefined && !next.startsWith("--"))
+                flags.set(k, argv[++i] ?? "");
+            else
+                flags.set(k, true);
+        }
+        else if (a === "-h")
+            flags.set("help", true);
+        else
+            positional.push(a);
+    }
+    if (flags.has("help")) {
+        io.out(HELP);
+        return 0;
+    }
+    const num = (k, d, min, max) => {
+        const v = flags.get(k);
+        if (v === undefined)
+            return d;
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < min || n > max)
+            throw new PlayError(`--${k} must be a whole number from ${min} to ${max}`);
+        return n;
+    };
+    try {
+        const lib = flags.get("library-url");
+        if (lib !== undefined && (typeof lib !== "string" || !/^https?:\/\/[^\s]+$/.test(lib)))
+            throw new PlayError("--library-url must be an http(s) URL");
+        const host = flags.get("host");
+        const playing = await play({
+            dir: positional[0] ?? io.cwd,
+            port: num("port", 4663, 1, 65535),
+            host: typeof host === "string" && host.length > 0 ? host : "127.0.0.1",
+            open: !flags.has("no-open"),
+            players: num("players", 1, 1, 16),
+            libraryUrl: typeof lib === "string" ? lib.replace(/\/$/, "") : null,
+            log: io.out,
+        });
+        await new Promise((done) => {
+            const stop = () => {
+                void playing.close().finally(done);
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+        });
+        return 0;
+    }
+    catch (e) {
+        io.err(e instanceof PlayError ? e.message : e instanceof Error ? (e.stack ?? e.message) : String(e));
+        return 1;
+    }
+}
+/** Splits flags (--k v, --k=v, bare --k when listed in `bare`) from positional arguments. */
+function split(argv, bare) {
+    const flags = new Map();
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a.startsWith("--")) {
+            const [k, v] = a.slice(2).split("=", 2);
+            const next = argv[i + 1];
+            if (v !== undefined)
+                flags.set(k, v);
+            else if (!bare.has(k) && next !== undefined && !next.startsWith("--"))
+                flags.set(k, argv[++i] ?? "");
+            else
+                flags.set(k, true);
+        }
+        else if (a === "-h")
+            flags.set("help", true);
+        else
+            positional.push(a);
+    }
+    return { flags, positional };
+}
+export async function runTestCli(argv, io) {
+    const { flags, positional } = split(argv, new Set(["json", "help"]));
+    if (flags.has("help")) {
+        io.out(TEST_HELP);
+        return 0;
+    }
+    const json = flags.has("json");
+    const num = (k, d, min, max, whole) => {
+        const v = flags.get(k);
+        if (v === undefined)
+            return d;
+        const n = Number(v);
+        if (!Number.isFinite(n) || (whole && !Number.isInteger(n)) || n < min || n > max)
+            throw new PlayError(`--${k} must be a ${whole ? "whole " : ""}number from ${min} to ${max}`);
+        return n;
+    };
+    const known = new Set(["json", "help", "minutes", "bots", "seed"]);
+    try {
+        for (const k of flags.keys())
+            if (!known.has(k))
+                throw new PlayError(`unknown flag --${k} (kit-play test --help lists the flags)`);
+        const bots = flags.has("bots") ? num("bots", 2, 1, 16, true) : null;
+        const r = await check({
+            dir: positional[0] ?? io.cwd,
+            minutes: num("minutes", 1, 0.1, 30, false),
+            bots,
+            seed: num("seed", 1, 0, 2 ** 31 - 1, true),
+            log: json ? io.err : io.out,
+        });
+        if (json)
+            io.out(JSON.stringify(r, null, 2));
+        else {
+            for (const l of summary(r))
+                io.out(l);
+            if (r.ok)
+                io.out("PASS: the game compiles and the playtest checks pass.");
+            else {
+                io.err("FAIL:");
+                for (const p of r.problems)
+                    io.err(`  ${p}`);
+            }
+        }
+        return r.ok ? 0 : 1;
+    }
+    catch (e) {
+        const msg = e instanceof PlayError ? e.message : e instanceof Error ? (e.stack ?? e.message) : String(e);
+        if (json)
+            io.out(JSON.stringify({ ok: false, problems: [msg], report: null }, null, 2));
+        else
+            io.err(msg);
+        return 1;
+    }
+}
+/** The kit-play command: play (the default), test, new and templates. */
+export async function runKitPlayCli(argv, io) {
+    const [first, ...rest] = argv;
+    switch (first) {
+        case "play":
+            return runPlayCli(rest, io);
+        case "test":
+            return runTestCli(rest, io);
+        case "check":
+            // test with the report as JSON on stdout: what scripts and coding agents read.
+            return runTestCli(rest.includes("--json") ? rest : [...rest, "--json"], io);
+        case "new":
+        case "create":
+            return runCreate(rest, { ...nodeIo("kit-play new"), out: io.out, err: io.err, cwd: io.cwd });
+        case "templates":
+            if (rest.includes("--help") || rest.includes("-h")) {
+                io.out("kit-play templates [--json]: list the templates a new game can start from.");
+                return 0;
+            }
+            io.out(listTemplates(rest.includes("--json")));
+            return 0;
+        case "help":
+            io.out(COMMANDS_HELP);
+            return 0;
+        case undefined:
+            return runPlayCli([], io);
+        default:
+            if (first === "--help" || first === "-h") {
+                io.out(`${COMMANDS_HELP}\n\n${HELP}`);
+                return 0;
+            }
+            return runPlayCli(argv, io);
+    }
+}
+const isMain = (() => {
+    try {
+        return process.argv[1] !== undefined && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain) {
+    const code = await runKitPlayCli(process.argv.slice(2), { out: (s) => console.log(s), err: (s) => console.error(s), cwd: process.cwd() });
+    process.exit(code);
+}

package/dist/host/core.d.ts

@@ -0,0 +1,50 @@
+import { type Hitbox, type HitscanRequest, type PlayerId, type PlayerRights, type SimAdapter, type SimCommand, type SimEvent } from "@netforge/engine/net";
+/** What each player is sent: everything within `radius` of them (world units), nearest first, up to the caps. */
+export interface LocalAoi {
+    readonly radius: number;
+    readonly maxEntities: number;
+    /** Most entities of one kind (EntityKind number) a snapshot carries. */
+    readonly kindCaps?: Readonly<Record<number, number>>;
+    /** Kinds every player always receives (players, so the HUD sees teammates). */
+    readonly alwaysKinds?: readonly number[];
+}
+export declare const SNAPSHOT_HZ = 20;
+export interface LocalTick {
+    readonly tick: number;
+    readonly events: readonly SimEvent[];
+    readonly snapshots: ReadonlyMap<PlayerId, Uint8Array>;
+}
+/** Distance along a unit ray to a circle, or null. */
+export declare function rayCircle(ox: number, oy: number, ux: number, uy: number, cx: number, cy: number, r: number): number | null;
+/** The nearest hitbox a hitscan meets that the shooter does not own, or null. */
+export declare function resolveHitscan(boxes: readonly Hitbox[], req: HitscanRequest): Hitbox | null;
+export declare class LocalCore<W, I> {
+    private readonly sim;
+    private readonly aoi;
+    private worldRef;
+    private tickN;
+    private snapAccum;
+    private readonly conns;
+    private readonly rights;
+    private nextPlayer;
+    private readonly freeIds;
+    private boxes;
+    constructor(sim: SimAdapter<W, I>, aoi: LocalAoi, seed: number);
+    get world(): W;
+    get tick(): number;
+    get players(): PlayerId[];
+    addPlayer(): {
+        player: PlayerId;
+        entity: number;
+    };
+    removePlayer(player: PlayerId): void;
+    setRights(player: PlayerId, rights: PlayerRights | null): void;
+    command(player: PlayerId, cmd: SimCommand): boolean;
+    startRun(player: PlayerId): void;
+    receiveInput(player: PlayerId, bytes: Uint8Array): void;
+    step(): LocalTick;
+    /** A fresh world at a run boundary; every player is re-added under the same id. Returns the new entity ids. */
+    rebase(seed: number): Map<PlayerId, number>;
+    dispose(): void;
+    private buildSnapshots;
+}