@netforge/kit-play 0.0.0-stage → 0.1.0

package/dist/names.d.ts

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

package/dist/names.js

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

package/dist/play.d.ts

@@ -0,0 +1,38 @@
+import { type Names } from "./names.js";
+import { type TemplateEntry } from "./templates.js";
+/** The only import a game module may make (the studio's rule, kept here so a game that plays locally plays in the studio). */
+export declare const ALLOWED_IMPORT = "@netforge/engine";
+export interface PlayOptions {
+    readonly dir: string;
+    readonly port: number;
+    readonly host: string;
+    readonly open: boolean;
+    /** Browser tabs to open, one per local player. */
+    readonly players: number;
+    /** A base URL the page loads the asset library from instead of this host (any mirror of the published library). */
+    readonly libraryUrl: string | null;
+    readonly log: (s: string) => void;
+}
+export interface GameFolder {
+    readonly dir: string;
+    readonly template: TemplateEntry;
+    readonly gameFile: string;
+    readonly names: Names | null;
+}
+export declare class PlayError extends Error {
+}
+/** Reads and checks the game folder. */
+export declare function readGameFolder(dir: string): GameFolder;
+/** The template package's root (its "." export is src/manifest.ts). */
+export declare function templateDir(t: TemplateEntry, from: string): string;
+/** The built asset library shipped in @netforge/asset-library-files, or null when it is not installed. */
+export declare function libraryDir(from: string): string | null;
+/** 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>;
+/** 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;
+    close(): Promise<void>;
+}
+export declare function play(o: PlayOptions): Promise<Playing>;

package/dist/play.js

@@ -0,0 +1,209 @@
+// `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 { 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;
+    }
+}
+/** 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 },
+    });
+}
+/** 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 = {
+        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}"` }] };
+            });
+        },
+    };
+    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 params = new URLSearchParams({ server: running.url });
+    if (o.libraryUrl)
+        params.set("library", o.libraryUrl);
+    const url = `${running.url}/?${params.toString()}`;
+    o.log(`Playing locally with play money at ${url}`);
+    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 };
+}

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/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@netforge/kit-play",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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.",
+  "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"
+  },
+  "bin": {
+    "kit-play": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+  },
+  "dependencies": {
+    "@colyseus/core": "0.18.18",
+    "@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"
+  },
+  "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",
+    "test": "vitest run"
+  }
 }