@netforge/kit-play 0.1.0 → 0.2.0

package/README.md

@@ -1,48 +1,86 @@
 # @netforge/kit-play
 
-`kit play` runs a game you downloaded from Net Forge on your own computer,
-with play money.
+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
-cd my-game          # the folder from the Source download (netnet.json, src/game.ts)
-npm install         # its package.json lists the engine and kit-play
-npx kit play        # or: npm run play
+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
 ```
 
-It builds the template's browser client with your `src/game.ts` and
-`src/names.json` in place, starts a local room host for the same game
-module, and opens `http://127.0.0.1:4663`. Open the link in more tabs or
-windows for more 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 |
+| `--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.
-
-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.
-Progress (achievements, looks bought with play money) lives in memory and
-is gone when `kit play` stops.
-
-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 studio, so
-a game that plays here plays there. Send changes back with `/agent` in the
-studio (see your game's README).
-
-The build lands in `.netnet/play/` inside the game folder.
+- 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

@@ -1,8 +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

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
-// kit-play [dir] [--port 4663] [--host 127.0.0.1] [--players 1] [--no-open] [--library-url <url>]
-// Also reached as `kit play` through @netforge/kit.
+// 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.
 
@@ -18,6 +24,26 @@ Usage: kit play [dir] [flags]     (inside the folder you downloaded from Net For
 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 = [];
@@ -79,6 +105,116 @@ export async function runPlayCli(argv, io) {
         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));
@@ -88,6 +224,6 @@ const isMain = (() => {
     }
 })();
 if (isMain) {
-    const code = await runPlayCli(process.argv.slice(2), { out: (s) => console.log(s), err: (s) => console.error(s), cwd: process.cwd() });
+    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/server.d.ts

@@ -19,7 +19,10 @@ 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), and only same-origin or non-browser requests may POST.
+ * 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

@@ -161,22 +161,44 @@ async function route(g, o, req, res) {
     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), and only same-origin or non-browser requests may POST.
+ * 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) {
-    if (!LOOPBACK.has(bindHost))
-        return true;
-    const name = (host ?? "").replace(/:\d+$/, "").toLowerCase();
-    if (!LOOPBACK.has(name))
+    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);
-        return LOOPBACK.has(o.hostname.toLowerCase()) && Number(o.port || 80) === port;
+        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;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { HELP, runPlayCli, type PlayCliIo } from "./cli.js";
+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

@@ -1,4 +1,5 @@
-export { HELP, runPlayCli } from "./cli.js";
+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/play.d.ts

@@ -1,3 +1,4 @@
+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). */
@@ -27,12 +28,24 @@ export declare function readGameFolder(dir: string): GameFolder;
 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>;

package/dist/play.js

@@ -14,6 +14,7 @@ import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
+import { networkInterfaces } from "node:os";
 import { namesModule, parseNames } from "./names.js";
 import { templateFor } 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). */
@@ -78,6 +79,27 @@ export function libraryDir(from) {
         return 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 function playLink(base, libraryUrl) {
+    const params = new URLSearchParams({ server: base });
+    if (libraryUrl)
+        params.set("library", libraryUrl);
+    return `${base}/?${params.toString()}`;
+}
+/** Links other devices can open when the host listens on every interface: one per IPv4 network address. */
+export function lanLinks(host, port, interfaces, libraryUrl) {
+    const wildcard = host === "0.0.0.0" || host === "::";
+    const addrs = wildcard
+        ? Object.values(interfaces).flatMap((list) => (list ?? []).flatMap(({ family, internal, address }) => (family === "IPv4" && !internal ? [address] : [])))
+        : host !== "127.0.0.1" && host !== "localhost" && host !== "::1" && /^\d+\.\d+\.\d+\.\d+$/.test(host)
+            ? [host]
+            : [];
+    return [...new Set(addrs)].map((a) => playLink(`http://${a}:${port}`, libraryUrl));
+}
 /** Builds the template client with the game module and labels swapped in. */
 export async function buildClient(g, tplDir, outDir, cacheDir) {
     const vite = await import("vite");
@@ -123,14 +145,9 @@ export async function buildClient(g, tplDir, outDir, cacheDir) {
         build: { outDir, emptyOutDir: true, target: "es2022", chunkSizeWarningLimit: 16384, reportCompressedSize: false },
     });
 }
-/** Bundles the local host with the game module (one copy of the engine and the sim). Returns the bundle path. */
-export async function bundleHost(g, tplDir, outFile) {
-    const esbuild = await import("esbuild");
-    const manifest = realpathSync(join(tplDir, "src", "manifest.ts"));
-    const gameFile = realpathSync(g.gameFile);
-    const here = dirname(fileURLToPath(import.meta.url));
-    const entryFile = existsSync(join(here, "host", "entry.js")) ? join(here, "host", "entry.js") : join(here, "host", "entry.ts");
-    const swap = {
+/** 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 function gameSwap(manifest, gameFile, tplDir) {
+    return {
         name: "kit-play-swap",
         setup(b) {
             b.onResolve({ filter: /^\.\/game\.(js|ts)$/ }, (args) => (args.importer === manifest ? { path: gameFile } : undefined));
@@ -139,10 +156,19 @@ export async function bundleHost(g, tplDir, outFile) {
                     return undefined;
                 if (args.path === ALLOWED_IMPORT)
                     return b.resolve(args.path, { resolveDir: join(tplDir, "src"), kind: args.kind });
-                return { errors: [{ text: `src/game.ts may import only "${ALLOWED_IMPORT}"` }] };
+                return { errors: [{ text: `src/game.ts may import only "${ALLOWED_IMPORT}", not "${args.path}"` }] };
             });
         },
     };
+}
+/** Bundles the local host with the game module (one copy of the engine and the sim). Returns the bundle path. */
+export async function bundleHost(g, tplDir, outFile) {
+    const esbuild = await import("esbuild");
+    const manifest = realpathSync(join(tplDir, "src", "manifest.ts"));
+    const gameFile = realpathSync(g.gameFile);
+    const here = dirname(fileURLToPath(import.meta.url));
+    const entryFile = existsSync(join(here, "host", "entry.js")) ? join(here, "host", "entry.js") : join(here, "host", "entry.ts");
+    const swap = gameSwap(manifest, gameFile, tplDir);
     const contents = [`export { startHost } from ${JSON.stringify(entryFile)};`, `export * as template from ${JSON.stringify(manifest)};`].join("\n");
     const out = await esbuild.build({
         stdin: { contents, resolveDir: here, sourcefile: "kit-play-host.js", loader: "js" },
@@ -195,15 +221,17 @@ export async function play(o) {
         clientDir: clientOut,
         libraryDir: lib,
     });
-    const params = new URLSearchParams({ server: running.url });
-    if (o.libraryUrl)
-        params.set("library", o.libraryUrl);
-    const url = `${running.url}/?${params.toString()}`;
+    const url = playLink(running.url, o.libraryUrl);
+    const lan = lanLinks(o.host, o.port, networkInterfaces(), o.libraryUrl);
     o.log(`Playing locally with play money at ${url}`);
+    for (const l of lan)
+        o.log(`On your network (phones, other computers): ${l}`);
+    if (lan.length === 0 && o.host !== "127.0.0.1" && o.host !== "localhost" && o.host !== "::1")
+        o.log(`Listening on ${o.host}: share a link of the form http://<this computer's address>:${o.port}/?server=http://<this computer's address>:${o.port}`);
     o.log("Open the link in more tabs or windows for more players. Ctrl+C stops.");
     o.log("kit play runs the game's code on this computer with your permissions: play only games whose code you trust.");
     if (o.open)
         for (let i = 0; i < Math.max(1, o.players); i++)
             openBrowser(url);
-    return { url, close: running.close };
+    return { url, lan, close: running.close };
 }

package/llms.txt

@@ -0,0 +1,41 @@
+# @netforge/kit-play
+
+> kit play runs a Net Forge game on your own computer with play money. Inside a game folder (netnet.json and src/game.ts) it builds the template's browser client with that game module, starts a local room host for the same module, and opens http://127.0.0.1:4663. No wallet, no chain, no Net Forge servers; earn rules fire and pay nothing.
+
+## Run a game
+
+- Install: `npm install @netforge/kit-play @netforge/engine` in the game folder (Node 20 or later).
+- Run: `npx kit-play [dir]`, or `kit play` through @netforge/kit. It exits on Ctrl+C.
+- The folder needs netnet.json with `{"template":"<id>"}` and src/game.ts. src/names.json (title and labels) is optional.
+- Template ids: survivor, arena, tower-defense, dungeon, idle, platformer, cards, collector, racer, party.
+- Start from a template: copy node_modules/@netforge/template-<name>/src/game.ts to src/game.ts (the package names are template-survivor, template-arena, template-tower, template-dungeon, template-idle, template-platformer, template-cards, template-collector, template-racer, template-party).
+- The build lands in .netnet/play/ inside the game folder.
+
+## Flags
+
+- `--port <n>`: the page and the room on one port (default 4663).
+- `--host <addr>`: interface to listen on (default 127.0.0.1; 0.0.0.0 lets devices on your network join).
+- `--players <n>`: browser tabs to open, one per local player (1 to 16, default 1).
+- `--no-open`: print the link instead of opening a browser.
+- `--library-url <url>`: load the asset library from an http(s) mirror instead of the installed @netforge/asset-library-files.
+
+## Programmatic API
+
+- `play({ dir, port, host, open, players, libraryUrl, log })` resolves to `{ url, close() }`.
+- `readGameFolder(dir)` checks a folder and throws `PlayError` with a readable message (no netnet.json, unknown template, missing src/game.ts, bad names.json).
+- `runPlayCli(argv, io)` is the CLI; `HELP` is its help text.
+- `TEMPLATES` and `templateFor(id)` describe the runnable templates.
+- `ALLOWED_IMPORT` is "@netforge/engine", the only import a game module may have.
+
+## Rules for agents
+
+- src/game.ts imports only @netforge/engine, the same rule the Net Forge studio enforces.
+- Do not add renderers, netcode, physics or asset URLs to a game; the template draws and runs everything.
+- kit play runs the game's code with the user's permissions. It is not a sandbox.
+- Validate and playtest before playing: the MCP tools netforge_validate_game and netforge_run_playtest, or engine.test.run from @netforge/engine. netforge_play_locally runs kit play for an agent.
+
+## Docs
+
+- https://forge.netnet.capital/docs/packages/kit-play
+- MCP server: `npx -y @netforge/mcp` (package @netforge/mcp, bin netforge-mcp). Tools: netforge_list_templates, netforge_create_game, netforge_search_docs, netforge_explain_api, netforge_validate_game, netforge_run_playtest, netforge_play_locally.
+- Agent setup in a project: `npx netforge setup agent`.

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "@netforge/kit-play",
-  "version": "0.1.0",
-  "description": "kit play: run a game downloaded from Net Forge on your own computer with play money. Builds the template client with your game module and runs a local room host from the engine's open simulation. No wallet, no chain, no Net Forge servers.",
+  "version": "0.2.0",
+  "description": "Make, test and run Net Forge games on your own computer with play money: start a game from a template, run playtest bots, and play it in the browser with a local room host, with no wallet, chain or servers.",
+  "keywords": [
+    "game-engine",
+    "multiplayer",
+    "browser-game",
+    "game-server",
+    "websocket",
+    "game-template",
+    "threejs",
+    "typescript",
+    "gamedev",
+    "ai-agents",
+    "mcp",
+    "vibe-coding",
+    "net-forge"
+  ],
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,7 +26,8 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./llms.txt": "./llms.txt"
   },
   "bin": {
     "kit-play": "./dist/cli.js"
@@ -20,24 +36,22 @@
     "dist",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "llms.txt"
   ],
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://forge.netnet.capital/docs/packages/kit-play",
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/netnetdev/net-forge.git",
     "directory": "packages/kit-play"
   },
-  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/kit-play#readme",
-  "keywords": [
-    "netnet",
-    "net-forge",
-    "game",
-    "local",
-    "three.js"
-  ],
   "engines": {
     "node": ">=20"
   },
@@ -46,30 +60,28 @@
     "@colyseus/ws-transport": "0.18.4",
     "esbuild": "0.25.12",
     "vite": "6.4.3",
-    "@netforge/asset-library": "0.1.0",
-    "@netforge/engine": "0.1.0",
-    "@netforge/engine-sim": "0.1.0",
-    "@netforge/asset-library-files": "0.1.0",
-    "@netforge/template-arena": "0.1.0",
-    "@netforge/tabletop": "0.1.0",
-    "@netforge/template-cards": "0.1.0",
-    "@netforge/template-collector": "0.1.0",
-    "@netforge/template-idle": "0.1.0",
-    "@netforge/template-dungeon": "0.1.0",
-    "@netforge/template-party": "0.1.0",
-    "@netforge/template-platformer": "0.1.0",
-    "@netforge/template-racer": "0.1.0",
-    "@netforge/template-tower": "0.1.0",
-    "@netforge/template-survivor": "0.1.0"
+    "@netforge/engine-sim": "0.2.0",
+    "@netforge/asset-library": "0.2.0",
+    "@netforge/tabletop": "0.2.0",
+    "@netforge/asset-library-files": "0.2.0",
+    "@netforge/template-arena": "0.2.0",
+    "@netforge/engine": "0.2.0",
+    "@netforge/template-cards": "0.2.0",
+    "@netforge/template-dungeon": "0.2.0",
+    "@netforge/template-idle": "0.2.0",
+    "@netforge/template-collector": "0.2.0",
+    "@netforge/template-party": "0.2.0",
+    "@netforge/template-platformer": "0.2.0",
+    "@netforge/template-survivor": "0.2.0",
+    "@netforge/template-tower": "0.2.0",
+    "create-netforge": "0.2.0",
+    "@netforge/template-racer": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "22.20.1",
     "typescript": "5.8.3",
     "vitest": "3.2.7"
   },
-  "bugs": {
-    "url": "https://github.com/netnetdev/net-forge/issues"
-  },
   "scripts": {
     "build": "node ../engine/scripts/fresh-dist.mjs && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",