netforge 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/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# netforge
 
-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.
+The Net Forge command line for coding agents: one command makes a project
+ready for Claude Code, Cursor, VS Code, Codex and Gemini CLI, and the
+package ships Agent Skills for building Net Forge games.
+
+## Set up a project for your agent
+
+```sh
+npx netforge setup agent
+```
+
+It writes, without replacing anything you already have:
+
+| File | For |
+|---|---|
+| `AGENTS.md` | Every agent: where the game lives, the rules, how to validate and playtest. Added as a section when the file exists. |
+| `CLAUDE.md` | Claude Code: imports `AGENTS.md`. |
+| `.cursor/rules/netforge.mdc` | Cursor rules. |
+| `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json` | The `@netforge/mcp` server, merged next to your other servers. |
+
+Then it prints the install lines for agents that keep MCP config outside
+the project, such as `claude mcp add netforge -- npx -y @netforge/mcp`.
+
+## Agent Skills
+
+Four skills, each a folder with a `SKILL.md`:
+
+| Skill | When the agent uses it |
+|---|---|
+| `netforge-create-game` | Start a game from one of ten genre templates. |
+| `netforge-add-content` | Add an enemy, weapon, upgrade, earn rule or store item. |
+| `netforge-playtest` | Validate and run bot playtests after every change. |
+| `netforge-play-locally` | Play the game in the browser with play money. |
+
+Install them in one line with `npx skills add netnetdev/net-forge`, or copy
+them yourself:
+
+```sh
+npx netforge skills list
+npx netforge skills copy <your agent's skills folder>
+```
+
+## Start a new game
+
+```sh
+npm create netforge@latest
+```
+
+## Docs
+
+https://forge.netnet.capital/docs/agents
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+export declare const HELP = "netforge: set up a project for coding agents that build Net Forge games.\n\nUsage:\n  netforge setup agent [dir]   Write AGENTS.md, CLAUDE.md, .cursor/rules/netforge.mdc,\n                               .mcp.json, .cursor/mcp.json and .vscode/mcp.json (merged,\n                               never replacing other servers) and print the install lines.\n  netforge skills list         List the bundled Agent Skills.\n  netforge skills path         Print the folder that holds them.\n  netforge skills copy <dir>   Copy every skill folder into <dir> (your agent's skills folder).\n\nStart a new game: npm create netforge@latest\nDocs: https://forge.netnet.capital/docs";
+export declare function run(argv: readonly string[], io: {
+    out(s: string): void;
+    err(s: string): void;
+    cwd: string;
+}): number;

package/dist/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// netforge: the Net Forge command line for coding agents.
+//
+//   netforge setup agent [dir]   write AGENTS.md, CLAUDE.md, Cursor rules and MCP configs
+//   netforge skills path         print where the bundled Agent Skills are
+//   netforge skills list         list the bundled skills
+//   netforge skills copy <dir>   copy the skills into a skills folder
+//   netforge help
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { INSTALL_LINES, setupAgent } from "./setup.js";
+import { copySkills, listSkills, skillsDir } from "./skills.js";
+export const HELP = `netforge: set up a project for coding agents that build Net Forge games.
+
+Usage:
+  netforge setup agent [dir]   Write AGENTS.md, CLAUDE.md, .cursor/rules/netforge.mdc,
+                               .mcp.json, .cursor/mcp.json and .vscode/mcp.json (merged,
+                               never replacing other servers) and print the install lines.
+  netforge skills list         List the bundled Agent Skills.
+  netforge skills path         Print the folder that holds them.
+  netforge skills copy <dir>   Copy every skill folder into <dir> (your agent's skills folder).
+
+Start a new game: npm create netforge@latest
+Docs: https://forge.netnet.capital/docs`;
+export function run(argv, io) {
+    const [cmd, sub, arg] = argv;
+    if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+        io.out(HELP);
+        return 0;
+    }
+    if (cmd === "setup" && (sub === "agent" || sub === undefined)) {
+        const dir = resolve(io.cwd, arg ?? ".");
+        const r = setupAgent(dir);
+        for (const f of r.written)
+            io.out(`wrote    ${f}`);
+        for (const f of r.skipped)
+            io.out(`skipped  ${f}`);
+        io.out("");
+        io.out(INSTALL_LINES);
+        return 0;
+    }
+    if (cmd === "skills") {
+        if (sub === "path") {
+            io.out(skillsDir());
+            return 0;
+        }
+        if (sub === "list" || sub === undefined) {
+            for (const s of listSkills())
+                io.out(`${s.name.padEnd(26)} ${s.description}`);
+            return 0;
+        }
+        if (sub === "copy" && arg) {
+            for (const f of copySkills(resolve(io.cwd, arg)))
+                io.out(`copied   ${f}`);
+            return 0;
+        }
+    }
+    io.err(`Unknown command: ${argv.join(" ")}\n\n${HELP}`);
+    return 2;
+}
+const isMain = (() => {
+    try {
+        return process.argv[1] !== undefined && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain)
+    process.exitCode = run(process.argv.slice(2), { out: (s) => console.log(s), err: (s) => console.error(s), cwd: process.cwd() });

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** netforge: project setup and Agent Skills for coding agents that build Net Forge games. */
+export { setupAgent, AGENTS_SECTION, CLAUDE_MD, CURSOR_RULE, INSTALL_LINES, MCP_PACKAGE, type SetupResult } from "./setup.js";
+export { copySkills, listSkills, skillsDir, type SkillInfo } from "./skills.js";
+export { run, HELP } from "./cli.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+/** netforge: project setup and Agent Skills for coding agents that build Net Forge games. */
+export { setupAgent, AGENTS_SECTION, CLAUDE_MD, CURSOR_RULE, INSTALL_LINES, MCP_PACKAGE } from "./setup.js";
+export { copySkills, listSkills, skillsDir } from "./skills.js";
+export { run, HELP } from "./cli.js";

package/dist/setup.d.ts

@@ -0,0 +1,12 @@
+export declare const MCP_PACKAGE = "@netforge/mcp";
+export declare const SKILLS_SOURCE = "netnetdev/net-forge";
+export declare const DOCS_URL = "https://forge.netnet.capital/docs";
+export declare const AGENTS_SECTION = "<!-- netforge:agents -->\n## Net Forge\n\nThis project builds a game on Net Forge, an MIT TypeScript engine for\nmultiplayer browser games. One simulation (ECS, Rapier physics, fixed tick,\nsnapshots) runs in the browser and on the room server, and a template draws,\nnetworks and simulates the game.\n\n- The whole game is `src/game.ts`: declarations (game, prefab, weapon,\n  upgrade, director, system, earn.rule, earn.stake, store.sku and the genre's\n  own). It may import only `@netforge/engine`.\n- Ids are lower_snake_case. Every game declares at least one `earn.rule`\n  and one `earn.stake`.\n- Never write renderers, netcode or physics. Models are asset library ids\n  such as `\"style.lowpoly.ghost\"`, never URLs or paths.\n- After each change: `netforge_validate_game`, then `netforge_run_playtest`\n  (MCP server `@netforge/mcp`). To try it in a browser:\n  `netforge_play_locally` or `npx kit-play`.\n- Look things up with `netforge_search_docs` and `netforge_explain_api`\n  before guessing. Docs: https://forge.netnet.capital/docs\n";
+export declare const CLAUDE_MD = "@AGENTS.md\n";
+export declare const CURSOR_RULE = "---\ndescription: Net Forge game rules (src/game.ts, validation, playtests)\nalwaysApply: true\n---\n\nRead AGENTS.md. The game is src/game.ts and it may import only @netforge/engine.\nValidate every change with netforge_validate_game and playtest with\nnetforge_run_playtest before calling it done.\n";
+export interface SetupResult {
+    readonly written: string[];
+    readonly skipped: string[];
+}
+export declare function setupAgent(dir: string): SetupResult;
+export declare const INSTALL_LINES = "MCP server (@netforge/mcp, runs locally, no keys):\n  Claude Code   claude mcp add netforge -- npx -y @netforge/mcp\n  Cursor        written to .cursor/mcp.json (project); or add the same entry to ~/.cursor/mcp.json\n  VS Code       code --add-mcp '{\"name\":\"netforge\",\"command\":\"npx\",\"args\":[\"-y\",\"@netforge/mcp\"]}'\n  Codex         codex mcp add netforge -- npx -y @netforge/mcp\n  Gemini CLI    gemini mcp add netforge npx -y @netforge/mcp\n\nAgent Skills (create a game, add content, playtest, play locally):\n  npx skills add netnetdev/net-forge\n  or copy them from: npx netforge skills path\n\nDocs: https://forge.netnet.capital/docs";

package/dist/setup.js

@@ -0,0 +1,118 @@
+// `netforge setup agent`: makes a project ready for a coding agent. Writes
+// AGENTS.md (or adds a Net Forge section to an existing one), a CLAUDE.md
+// that imports it, Cursor rules, and the MCP server entry in .mcp.json,
+// .cursor/mcp.json and .vscode/mcp.json (merged into existing files, never replacing other
+// servers). Prints the install lines for the agents that configure MCP
+// outside the project.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const MCP_PACKAGE = "@netforge/mcp";
+export const SKILLS_SOURCE = "netnetdev/net-forge";
+export const DOCS_URL = "https://forge.netnet.capital/docs";
+const MARK = "<!-- netforge:agents -->";
+export const AGENTS_SECTION = `${MARK}
+## Net Forge
+
+This project builds a game on Net Forge, an MIT TypeScript engine for
+multiplayer browser games. One simulation (ECS, Rapier physics, fixed tick,
+snapshots) runs in the browser and on the room server, and a template draws,
+networks and simulates the game.
+
+- The whole game is \`src/game.ts\`: declarations (game, prefab, weapon,
+  upgrade, director, system, earn.rule, earn.stake, store.sku and the genre's
+  own). It may import only \`@netforge/engine\`.
+- Ids are lower_snake_case. Every game declares at least one \`earn.rule\`
+  and one \`earn.stake\`.
+- Never write renderers, netcode or physics. Models are asset library ids
+  such as \`"style.lowpoly.ghost"\`, never URLs or paths.
+- After each change: \`netforge_validate_game\`, then \`netforge_run_playtest\`
+  (MCP server \`${MCP_PACKAGE}\`). To try it in a browser:
+  \`netforge_play_locally\` or \`npx kit-play\`.
+- Look things up with \`netforge_search_docs\` and \`netforge_explain_api\`
+  before guessing. Docs: ${DOCS_URL}
+`;
+export const CLAUDE_MD = "@AGENTS.md\n";
+export const CURSOR_RULE = `---
+description: Net Forge game rules (src/game.ts, validation, playtests)
+alwaysApply: true
+---
+
+Read AGENTS.md. The game is src/game.ts and it may import only @netforge/engine.
+Validate every change with netforge_validate_game and playtest with
+netforge_run_playtest before calling it done.
+`;
+const server = { command: "npx", args: ["-y", MCP_PACKAGE] };
+function readJson(file) {
+    if (!existsSync(file))
+        return {};
+    try {
+        const v = JSON.parse(readFileSync(file, "utf8"));
+        return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+function write(dir, rel, text, r) {
+    mkdirSync(dirname(join(dir, rel)), { recursive: true });
+    writeFileSync(join(dir, rel), text);
+    r.written.push(rel);
+}
+/** Adds the netforge server under `key` in a JSON config, keeping everything else. */
+function mergeMcp(dir, rel, key, entry, r) {
+    const file = join(dir, rel);
+    const cfg = readJson(file);
+    if (cfg === null) {
+        r.skipped.push(`${rel} (not plain JSON, perhaps comments; left as it is: add the netforge entry by hand)`);
+        return;
+    }
+    const current = cfg[key];
+    if (current !== undefined && (current === null || typeof current !== "object" || Array.isArray(current))) {
+        r.skipped.push(`${rel} ("${key}" is not an object, left as it is)`);
+        return;
+    }
+    const servers = (current ?? {});
+    if (servers.netforge) {
+        r.skipped.push(`${rel} (already has netforge)`);
+        return;
+    }
+    cfg[key] = { ...servers, netforge: entry };
+    write(dir, rel, JSON.stringify(cfg, null, 2) + "\n", r);
+}
+export function setupAgent(dir) {
+    const r = { written: [], skipped: [] };
+    const agents = join(dir, "AGENTS.md");
+    if (!existsSync(agents))
+        write(dir, "AGENTS.md", `# Notes for coding agents\n\n${AGENTS_SECTION}`, r);
+    else if (readFileSync(agents, "utf8").includes(MARK))
+        r.skipped.push("AGENTS.md (already has the Net Forge section)");
+    else
+        write(dir, "AGENTS.md", `${readFileSync(agents, "utf8").trimEnd()}\n\n${AGENTS_SECTION}`, r);
+    const claude = join(dir, "CLAUDE.md");
+    if (!existsSync(claude))
+        write(dir, "CLAUDE.md", CLAUDE_MD, r);
+    else if (/@AGENTS\.md/.test(readFileSync(claude, "utf8")))
+        r.skipped.push("CLAUDE.md (already imports AGENTS.md)");
+    else
+        write(dir, "CLAUDE.md", `${readFileSync(claude, "utf8").trimEnd()}\n\n${CLAUDE_MD}`, r);
+    if (existsSync(join(dir, ".cursor", "rules", "netforge.mdc")))
+        r.skipped.push(".cursor/rules/netforge.mdc (exists)");
+    else
+        write(dir, ".cursor/rules/netforge.mdc", CURSOR_RULE, r);
+    mergeMcp(dir, ".mcp.json", "mcpServers", server, r);
+    mergeMcp(dir, ".cursor/mcp.json", "mcpServers", server, r);
+    mergeMcp(dir, ".vscode/mcp.json", "servers", { type: "stdio", ...server }, r);
+    return r;
+}
+export const INSTALL_LINES = `MCP server (${MCP_PACKAGE}, runs locally, no keys):
+  Claude Code   claude mcp add netforge -- npx -y ${MCP_PACKAGE}
+  Cursor        written to .cursor/mcp.json (project); or add the same entry to ~/.cursor/mcp.json
+  VS Code       code --add-mcp '{"name":"netforge","command":"npx","args":["-y","${MCP_PACKAGE}"]}'
+  Codex         codex mcp add netforge -- npx -y ${MCP_PACKAGE}
+  Gemini CLI    gemini mcp add netforge npx -y ${MCP_PACKAGE}
+
+Agent Skills (create a game, add content, playtest, play locally):
+  npx skills add ${SKILLS_SOURCE}
+  or copy them from: npx netforge skills path
+
+Docs: ${DOCS_URL}`;

package/dist/skills.d.ts

@@ -0,0 +1,9 @@
+/** The package's skills folder (next to dist/ and src/). */
+export declare function skillsDir(): string;
+export interface SkillInfo {
+    readonly name: string;
+    readonly description: string;
+}
+export declare function listSkills(): SkillInfo[];
+/** Copies every skill folder into `to`; returns the folders copied. */
+export declare function copySkills(to: string): string[];

package/dist/skills.js

@@ -0,0 +1,33 @@
+// The Agent Skills shipped in this package (skills/<name>/SKILL.md).
+import { cpSync, existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The package's skills folder (next to dist/ and src/). */
+export function skillsDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+}
+export function listSkills() {
+    const root = skillsDir();
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((d) => existsSync(join(root, d, "SKILL.md")))
+        .sort()
+        .map((d) => {
+        const text = readFileSync(join(root, d, "SKILL.md"), "utf8");
+        const field = (k) => new RegExp(`^${k}:\\s*(.+)$`, "m").exec(text)?.[1]?.trim() ?? "";
+        return { name: field("name") || d, description: field("description") };
+    });
+}
+/** Copies every skill folder into `to`; returns the folders copied. */
+export function copySkills(to) {
+    const root = skillsDir();
+    const out = [];
+    for (const s of readdirSync(root)) {
+        if (!existsSync(join(root, s, "SKILL.md")))
+            continue;
+        cpSync(join(root, s), join(to, s), { recursive: true });
+        out.push(join(to, s));
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "netforge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Net Forge command line for coding agents: `npx netforge setup agent` writes AGENTS.md, CLAUDE.md, Cursor rules and MCP configs into a game project, and ships Agent Skills for building Net Forge games.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "netforge": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netnetdev/net-forge.git",
+    "directory": "packages/netforge"
+  },
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
+  "homepage": "https://forge.netnet.capital/docs/agents",
+  "keywords": [
+    "net-forge",
+    "game-engine",
+    "ai-agents",
+    "agent-skills",
+    "agents-md",
+    "mcp",
+    "cli",
+    "vibe-coding",
+    "browser-game",
+    "multiplayer",
+    "gamedev"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "typescript": "5.8.3",
+    "vitest": "3.2.7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }

package/skills/netforge-add-content/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: netforge-add-content
+description: Add or change content in a Net Forge game's src/game.ts, such as a new enemy, weapon, upgrade, earn rule, store item or spawn pacing. Use when the user asks to add an enemy, a boss, a weapon, a power-up, a reward or to rebalance a Net Forge game.
+---
+
+# Add content to a Net Forge game
+
+All content is declared in `src/game.ts` with functions imported from
+`@netforge/engine`. Look up any declaration before using it:
+`netforge_explain_api { "name": "weapon" }` or
+`netforge_search_docs { "query": "spawn director curves" }`.
+
+## Common declarations (action templates)
+
+```ts
+import { earn, prefab, weapon } from "@netforge/engine";
+
+// An enemy. model is an asset library id, never a URL.
+prefab("brute", { model: "style.lowpoly.orc_brute", health: 160, speed: 2.2, radius: 0.8, damage: 18, ai: "tank", mass: 6, drops: ["ember_mid"] });
+
+// A weapon that fires by itself, with level-up steps.
+weapon("spark_bolt", { kind: "bolt", damage: 14, cooldown: 0.6, range: 14, speed: 24, pierce: 1, knockback: 2,
+  levels: [{ count: 1 }, { damage: "+40%" }, { cooldown: "-20%" }] });
+
+// A reward: pays when the event happens n times in a run.
+earn.rule("first_light", { when: "wave.cleared", n: 2, pay: 5, oncePer: "run" });
+```
+
+Board templates (tower defense, idle, cards, collector) use their own
+declarations, such as `tower(...)`, `waves(...)`, `plant(...)`, `card(...)`,
+`creature(...)` and `move(...)`. Read the template's own `src/game.ts` for
+the pattern and copy it.
+
+## Checklist
+
+1. New ids are lower_snake_case and unique per kind.
+2. Anything an enemy drops is a declared pickup prefab.
+3. A new enemy appears only when the spawn `director({ pool })` (or the
+   template's own spawner) names it.
+4. Run `netforge_validate_game` and fix every error it returns; each error
+   has the likely line and a hint.
+5. Run `netforge_run_playtest` and act on its findings.
+
+Docs: https://forge.netnet.capital/docs

package/skills/netforge-create-game/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: netforge-create-game
+description: Start a new multiplayer browser game with Net Forge from one of ten finished genre templates (survivor-like, arena shooter, tower defense, dungeon crawl, idle, platformer, card battler, monster collector, kart racer, party). Use when the user asks to make, scaffold or start a browser game, a multiplayer game, a co-op game or an .io-style game.
+---
+
+# Create a Net Forge game
+
+Net Forge games are one declarative file, `src/game.ts`, on top of a
+template that already has rendering (three.js, WebGPU with a WebGL2
+fallback), multiplayer netcode, physics, input, HUD and bots.
+
+## Steps
+
+1. Pick the template that matches the request. With the MCP server, call
+   `netforge_list_templates`; without it, use one of these ids: `survivor`,
+   `arena`, `tower-defense`, `dungeon`, `idle`, `platformer`, `cards`,
+   `collector`, `racer`, `party`.
+2. Create the folder:
+   - MCP: `netforge_create_game { "template": "survivor", "directory": "/abs/path/my-game" }`
+   - CLI: `npm create netforge@latest my-game -- --template survivor --yes`
+3. `cd my-game && npm install`
+4. Read `AGENTS.md` in the new folder, then make the user's changes in
+   `src/game.ts` (see the netforge-add-content skill).
+5. Validate and playtest (see the netforge-playtest skill), then let the
+   user play it (see the netforge-play-locally skill).
+
+## Rules
+
+- `src/game.ts` may import only `@netforge/engine`.
+- Ids are lower_snake_case.
+- Every game keeps at least one `earn.rule(...)` and one `earn.stake(...)`.
+- Keep `game({ style })`: the art style the template draws in.
+- Do not write renderers, netcode or physics, and never use asset URLs.
+
+Docs: https://forge.netnet.capital/docs

package/skills/netforge-play-locally/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: netforge-play-locally
+description: Run a Net Forge game on this computer in the browser with play money, for one or more players, with no wallet, chain or servers. Use when the user wants to try, see or play their Net Forge game, or test multiplayer with several browser tabs.
+---
+
+# Play a Net Forge game locally
+
+1. In the game folder (it has `netnet.json` and `src/game.ts`), run
+   `npm install` once.
+2. Start it:
+   - MCP: `netforge_play_locally { "projectDir": "/abs/path/my-game" }` returns the URL.
+   - CLI: `npm run play` or `npx kit-play` in the folder, which opens
+     `http://127.0.0.1:4663`.
+3. Open the URL in more tabs or windows for more players. `--host 0.0.0.0`
+   lets phones on the same network join.
+4. Stop it with `netforge_play_locally { "projectDir": "...", "stop": true }`
+   or Ctrl+C.
+
+kit play builds the template's browser client with `src/game.ts` and runs a
+local room host. Coins are play money and nothing pays out. It runs the
+game's code with your permissions, so play only code you trust.
+
+Docs: https://forge.netnet.capital/docs

package/skills/netforge-playtest/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: netforge-playtest
+description: Validate a Net Forge game and run headless bot playtests that report kills, waves, deaths, softlocks, earn awards and server milliseconds per tick. Use after every change to a Net Forge game's src/game.ts, or when the user asks whether the game works, is fun or is balanced.
+---
+
+# Validate and playtest a Net Forge game
+
+## With the MCP server (@netforge/mcp)
+
+1. `netforge_validate_game { "projectDir": "/abs/path/my-game" }`
+   returns `ok` and, for each problem, the stage, the engine's message, the
+   likely line in `src/game.ts` and a hint. Fix and repeat until `ok` is true.
+2. `netforge_run_playtest { "projectDir": "/abs/path/my-game", "bots": 4, "seconds": 120 }`
+   runs bots on the same simulation the room server uses and returns the
+   report plus plain findings. Pass `"bot": "human"` for players who react
+   like people (the fun metrics), and `"response_format": "detailed"` for
+   every metric.
+3. Read `findings` first. Fix softlocks, failed checks, missing earn and a
+   high p99 tick cost before anything else.
+
+## Without MCP
+
+The playtest is `engine.test.run` from `@netforge/engine`:
+
+```ts
+import { engine } from "@netforge/engine";
+const r = await engine.test.run({ ticks: 30 * 120, bots: 4, seed: 1 });
+console.log(r.kills, r.wave, r.softlock, r.msPerTick, r.failed);
+```
+
+Run it from a test file in the template package after importing the
+template's `src/manifest.ts`, the way each template's `test/harness.test.ts`
+does.
+
+Docs: https://forge.netnet.capital/docs