@netforge/kit-play 0.0.0-stage → 0.2.0

package/dist/play.js

@@ -0,0 +1,237 @@
+// `kit play`: run a downloaded Net Forge game on this computer with play
+// money. Inside the game's folder (netnet.json, src/game.ts, src/names.json)
+// it builds the template's browser client with the creator's game module
+// and labels swapped in, bundles a local room host around the same game
+// module, serves both on one port and opens the browser.
+//
+// What it never does: connect a wallet, read or write a chain, talk to a
+// Net Forge server, run the referee, or pay anyone. The page is built with
+// no VITE_* environment, so a hosted room or library URL in the shell can
+// never be baked in; the host binds to 127.0.0.1 unless --host says
+// otherwise, and answers every sign-in and money route with 403.
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+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). */
+export const ALLOWED_IMPORT = "@netforge/engine";
+export class PlayError extends Error {
+}
+/** Reads and checks the game folder. */
+export function readGameFolder(dir) {
+    const metaFile = join(dir, "netnet.json");
+    if (!existsSync(metaFile))
+        throw new PlayError(`No netnet.json in ${dir}. Run kit play inside a game downloaded from Net Forge.`);
+    let meta;
+    try {
+        meta = JSON.parse(readFileSync(metaFile, "utf8"));
+    }
+    catch {
+        throw new PlayError("netnet.json is not valid JSON.");
+    }
+    const template = templateFor(meta.template);
+    if (!template)
+        throw new PlayError(`netnet.json names an unknown template: ${String(meta.template)}`);
+    const gameFile = join(dir, "src", "game.ts");
+    if (!existsSync(gameFile))
+        throw new PlayError("src/game.ts is missing.");
+    const namesFile = join(dir, "src", "names.json");
+    let names = null;
+    if (existsSync(namesFile)) {
+        try {
+            names = parseNames(readFileSync(namesFile, "utf8"));
+        }
+        catch (e) {
+            throw new PlayError(e instanceof Error ? e.message : String(e));
+        }
+    }
+    return { dir, template, gameFile, names };
+}
+/** Where a package is installed, looked up from the game folder first, then from kit-play itself. */
+function packageDir(pkg, from, entryToRoot) {
+    const bases = [join(from, "package.json"), fileURLToPath(import.meta.url)];
+    for (const base of bases) {
+        try {
+            return entryToRoot(createRequire(base).resolve(pkg));
+        }
+        catch {
+            // next
+        }
+    }
+    throw new PlayError(`${pkg} is not installed. Run npm install in the game folder.`);
+}
+/** The template package's root (its "." export is src/manifest.ts). */
+export function templateDir(t, from) {
+    return packageDir(t.pkg, from, (p) => dirname(dirname(p)));
+}
+/** The built asset library shipped in @netforge/asset-library-files, or null when it is not installed. */
+export function libraryDir(from) {
+    try {
+        const dir = packageDir("@netforge/asset-library-files/package.json", from, (p) => dirname(p));
+        const lib = join(dir, "library");
+        return existsSync(join(lib, "index.json")) ? lib : null;
+    }
+    catch {
+        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");
+    // Vite hands plugins real, forward-slash paths: compare in that form (Windows, symlinked folders).
+    const norm = (p) => vite.normalizePath(realpathSync(p));
+    const manifest = norm(join(tplDir, "src", "manifest.ts"));
+    const clientDir = norm(join(tplDir, "client"));
+    const templateNames = norm(join(tplDir, "client", "names.ts"));
+    const gameFile = norm(g.gameFile);
+    const NAMES_ID = "\0kit-play-names.js";
+    const plugin = {
+        name: "kit-play-game",
+        enforce: "pre",
+        async resolveId(source, importer) {
+            if (!importer)
+                return null;
+            if (importer === manifest && (source === "./game.js" || source === "./game.ts"))
+                return gameFile;
+            if (importer === gameFile) {
+                if (source === ALLOWED_IMPORT)
+                    return this.resolve(source, manifest, { skipSelf: true });
+                this.error(`src/game.ts may import only "${ALLOWED_IMPORT}", not "${source}"`);
+            }
+            if (g.names && importer.startsWith(clientDir) && importer !== templateNames && (source === "./names.js" || source === "./names.ts"))
+                return NAMES_ID;
+            return null;
+        },
+        load(id) {
+            return id === NAMES_ID && g.names ? namesModule(g.names, templateNames) : null;
+        },
+    };
+    await vite.build({
+        configFile: false,
+        root: clientDir,
+        base: "./",
+        logLevel: "warn",
+        publicDir: false,
+        cacheDir,
+        // No VITE_* variables from the shell or a .env file reach the page: it always talks to this host.
+        envDir: join(cacheDir, "no-env"),
+        envPrefix: "KIT_PLAY_NEVER_",
+        plugins: [plugin],
+        build: { outDir, emptyOutDir: true, target: "es2022", chunkSizeWarningLimit: 16384, reportCompressedSize: false },
+    });
+}
+/** 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));
+            b.onResolve({ filter: /.*/ }, async (args) => {
+                if (args.importer !== gameFile)
+                    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}", 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" },
+        bundle: true,
+        platform: "node",
+        format: "esm",
+        target: "node20",
+        write: false,
+        logLevel: "silent",
+        external: ["bufferutil", "utf-8-validate"],
+        plugins: [swap],
+        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 host bundle produced no output");
+    mkdirSync(dirname(outFile), { recursive: true });
+    writeFileSync(outFile, file.text);
+    return outFile;
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        // the URL is printed either way
+    }
+}
+export async function play(o) {
+    const dir = resolve(o.dir);
+    const g = readGameFolder(dir);
+    const tplDir = templateDir(g.template, dir);
+    const work = join(dir, ".netnet", "play");
+    const clientOut = join(work, "client");
+    const lib = o.libraryUrl ? null : libraryDir(dir);
+    if (!o.libraryUrl && !lib)
+        o.log("No asset library installed (@netforge/asset-library-files): the game draws simple shapes. Pass --library-url <url> to load one from a mirror.");
+    o.log(`Building ${g.names?.title ?? "your game"} (${g.template.label})...`);
+    await buildClient(g, tplDir, clientOut, join(work, "vite-cache"));
+    const bundle = await bundleHost(g, tplDir, join(work, "host.mjs"));
+    const mod = (await import(pathToFileURL(bundle).href + `?t=${Date.now()}`));
+    const running = await mod.startHost(mod.template, {
+        adapter: g.template.adapter,
+        manifest: g.template.manifest,
+        seats: g.template.seats,
+        aoi: g.template.aoi,
+        port: o.port,
+        host: o.host,
+        clientDir: clientOut,
+        libraryDir: lib,
+    });
+    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, lan, close: running.close };
+}

package/dist/templates.d.ts

@@ -0,0 +1,21 @@
+import type { LocalAoi } from "./host/core.js";
+export type TemplateId = "survivor" | "arena" | "tower-defense" | "dungeon" | "idle" | "platformer" | "cards" | "collector" | "racer" | "party";
+export interface TemplateEntry {
+    readonly id: TemplateId;
+    readonly label: string;
+    /** The npm package holding the template's game module (src/) and browser client (client/). */
+    readonly pkg: string;
+    /** The export of src/manifest.ts that builds the room sim (a SimAdapter). */
+    readonly adapter: string;
+    /** The export of src/manifest.ts that gives the game manifest: `fn().manifest` or `fn()`. */
+    readonly manifest: {
+        readonly fn: string;
+        readonly field?: "manifest";
+    };
+    /** Most players one room seats. */
+    readonly seats: number;
+    readonly aoi: LocalAoi;
+}
+export declare const TEMPLATES: Readonly<Record<TemplateId, TemplateEntry>>;
+/** netnet.json's template field (the room template names are accepted too). */
+export declare function templateFor(name: unknown): TemplateEntry | null;

package/dist/templates.js

@@ -0,0 +1,34 @@
+// The Net Forge templates a downloaded game can name (netnet.json
+// "template"), and how local play runs each one: its package, the factory
+// its manifest exports for the room sim, its manifest accessor, the room's
+// seat count and what each player is sent.
+/** engine-sim entity kinds: player 1, enemy 2, projectile 3, pickup 4. */
+const K = { player: 1, enemy: 2, projectile: 3, pickup: 4 };
+const crowd = (radius, enemies) => ({
+    radius,
+    maxEntities: enemies + 140,
+    kindCaps: { [K.enemy]: enemies, [K.pickup]: 60, [K.projectile]: 80 },
+    alwaysKinds: [K.player],
+});
+const board = { radius: 60, maxEntities: 400, kindCaps: { [K.enemy]: 240 }, alwaysKinds: [K.player] };
+const race = (radius) => ({ radius, maxEntities: 16, alwaysKinds: [K.player] });
+export const TEMPLATES = {
+    survivor: { id: "survivor", label: "survivor-like co-op", pkg: "@netforge/template-survivor", adapter: "survivorAdapter", manifest: { fn: "survivorGame", field: "manifest" }, seats: 4, aoi: crowd(40, 250) },
+    arena: { id: "arena", label: "arena shooter", pkg: "@netforge/template-arena", adapter: "arenaAdapter", manifest: { fn: "arenaGame", field: "manifest" }, seats: 16, aoi: { radius: 34, maxEntities: 260, kindCaps: { [K.projectile]: 140, [K.pickup]: 40, [K.enemy]: 60 }, alwaysKinds: [K.player] } },
+    "tower-defense": { id: "tower-defense", label: "tower defense", pkg: "@netforge/template-tower", adapter: "towerAdapter", manifest: { fn: "towerManifest" }, seats: 4, aoi: board },
+    dungeon: { id: "dungeon", label: "co-op dungeon crawl", pkg: "@netforge/template-dungeon", adapter: "dungeonAdapter", manifest: { fn: "dungeonGame", field: "manifest" }, seats: 4, aoi: crowd(36, 140) },
+    idle: { id: "idle", label: "idle", pkg: "@netforge/template-idle", adapter: "idleAdapter", manifest: { fn: "idleManifest" }, seats: 8, aoi: board },
+    platformer: { id: "platformer", label: "platformer", pkg: "@netforge/template-platformer", adapter: "platformerAdapter", manifest: { fn: "platformerGame", field: "manifest" }, seats: 8, aoi: race(200) },
+    cards: { id: "cards", label: "card battler", pkg: "@netforge/template-cards", adapter: "cardsAdapter", manifest: { fn: "cardsManifest" }, seats: 2, aoi: board },
+    collector: { id: "collector", label: "monster collector", pkg: "@netforge/template-collector", adapter: "collectorAdapter", manifest: { fn: "collectorManifest" }, seats: 8, aoi: board },
+    racer: { id: "racer", label: "kart racer", pkg: "@netforge/template-racer", adapter: "racerAdapter", manifest: { fn: "racerGame", field: "manifest" }, seats: 8, aoi: race(400) },
+    party: { id: "party", label: "party co-op", pkg: "@netforge/template-party", adapter: "partyAdapter", manifest: { fn: "partyGame", field: "manifest" }, seats: 8, aoi: crowd(40, 200) },
+};
+/** netnet.json's template field (the room template names are accepted too). */
+export function templateFor(name) {
+    if (typeof name !== "string")
+        return null;
+    const alias = { shooter: "arena", tower: "tower-defense" };
+    const id = (alias[name] ?? name);
+    return Object.prototype.hasOwnProperty.call(TEMPLATES, id) ? TEMPLATES[id] : null;
+}

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,6 +1,90 @@
 {
   "name": "@netforge/kit-play",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./llms.txt": "./llms.txt"
+  },
+  "bin": {
+    "kit-play": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "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"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@colyseus/core": "0.18.18",
+    "@colyseus/ws-transport": "0.18.4",
+    "esbuild": "0.25.12",
+    "vite": "6.4.3",
+    "@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"
+  },
+  "scripts": {
+    "build": "node ../engine/scripts/fresh-dist.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }