NET FORGE DOCS

How to let an AI agent build your game (Claude Code, Cursor, MCP)

Last updated Checked against @netforge/engine 0.2.0View as Markdown

Net Forge, the open-source multiplayer browser game engine built for AI coding agents, is published on npm under @netforge with source at github.com/netnetdev/net-forge.

Create the game with npm create netforge@latest, open the folder in your coding agent and ask for changes in plain words. The project already tells the agent what to do: AGENTS.md explains that the whole game is src/game.ts, and npm run check lets the agent verify each edit with a headless bot playtest before you look at it.

npm create netforge@latest my-game -- --template survivor --yes
cd my-game
claude

Swap claude for Cursor, VS Code with Copilot, Codex or Gemini CLI; the project carries instructions and MCP configs for each.

Why this works with an agent

What the agent needsWhat Net Forge gives it
A small surface to changeOne declarative file, src/game.ts, that may import only @netforge/engine. The renderer, netcode and physics are out of reach, so an edit cannot break multiplayer.
Instructions in the repoAGENTS.md, CLAUDE.md, .cursor/rules/netforge.mdc and .github/copilot-instructions.md, written for this template. Each template also ships an llms.txt with its common changes.
Types and clear errorsEvery declaration is typed, and a mistake fails with one line naming the field and the fix.
A way to check its own worknpm run check plays the game headless with bots and prints JSON: kills, waves, levels, softlocks, earn rules fired and ms per tick.
Tools, if it speaks MCP.mcp.json connects the @netforge/mcp server: templates, docs search, API lookup, validation, playtests and local play.

1. Create the project

npm create netforge@latest my-game -- --template arena --yes

With no terminal attached (as when an agent runs it), the command never asks a question. --agent claude, --agent cursor or --agent copilot limits the agent files it writes; by default it writes all of them.

2. Connect the MCP server (optional)

Claude Code reads .mcp.json in the project. To add the server for every project instead:

claude mcp add netforge -- npx -y @netforge/mcp

For Cursor, VS Code, Codex and Gemini CLI, see Set up your coding agent.

3. Ask for a change in plain words

Good first requests are about the game, not the code:

  • "Add a fast enemy that appears after two minutes."
  • "Make the first minute easier, then harder after five minutes."
  • "Add a boss at ten minutes with a telegraphed slam."
  • "Sell a cosmetic skin for 300 coins."

The template's llms.txt maps requests like these to declarations, and the engine's design rules (quiet opening, off-screen spawns, telegraphed hits) are part of what the agent reads.

4. Have the agent check every edit

npm run check
npm test

Ask the agent to run npm run check after each change and fix what it reports before you play. A good instruction is: "After every change to src/game.ts, run npm run check and keep going until it passes."

5. Play the result

npm run play

Open the link in a second tab to play together. Everything runs on your computer with play money.

A typical session

you:   Add a ranged enemy that keeps its distance, from minute three.
agent: (reads AGENTS.md and llms.txt, edits src/game.ts)
       prefab("spitter", { model: "style.lowpoly.frog", health: 20, speed: 2.8,
         ai: "ranged", attack: { damage: 8, range: 10, speed: 7 }, drops: ["ember_small"] });
       director pool: { prefab: "spitter", from: 180, weight: 3 }
agent: (runs npm run check) pass: 1,350 kills, level 9, no softlock
you:   npm run play

Alternatives

  • Phaser publishes an official Game Agent MCP and a large examples index for agents, and is a strong choice for 2D games. See Net Forge and Phaser.
  • Godot is a full desktop editor and engine with web export, a good fit when you want an editor and native builds as well as the web. See Net Forge and Godot web export.
  • Plain three.js gives your agent the most freedom and the most to build: networking, physics and game rules are yours to write. See Net Forge and three.js.

Pick Net Forge when you want the agent to change a finished multiplayer game rather than write the engine around it.

FAQ

Can Claude Code build a multiplayer game?

Yes. Start from a Net Forge template with npm create netforge@latest, open the folder in Claude Code and ask for changes. The multiplayer netcode is already in the template, so the agent works on the rules in src/game.ts and verifies them with npm run check.

What is the best game engine for AI coding agents?

It depends on the game. For multiplayer browser games, an engine where the game is a small typed file with validated declarations and a headless test the agent can run gives the agent the shortest loop from request to verified change. That is the shape Net Forge is built around.

Does the agent need an API key or account for Net Forge?

No. The packages, the MCP server and local play need no key, account or wallet.

Can the agent break the netcode or rendering?

Not from src/game.ts. The play build rejects any import other than @netforge/engine, and the renderer, netcode and physics live in the template packages.

How does the agent know the change is fun and not just valid?

npm run check includes design metrics measured by the playtest bots: time to the first threat and the first reward, deaths in the first minute, spawns on screen and the share of telegraphed deaths. See Testing with playtest bots.