The game-development layer for coding agents.
Build better browser-native 2D games with Codex, Claude Code, and other coding agents—from a focused game contract to deterministic playtests.
Quick start · Skills · MCP tools · Game Bridge · Roadmap
Coding agents already write code, run terminals, and inspect screenshots. A screenshot, however, cannot prove that a collision removed the right health, a puzzle reached a valid state, or a restart cleared every timer.
Web2DKit adds the missing game-development feedback loop:
| Agent alone | Agent + Web2DKit |
|---|---|
| Generates mechanics from a prompt | Starts from a scoped player loop and quality contract |
| Guesses hidden state from pixels | Reads structured scenes, entities, objectives, and lifecycle state |
| Clicks coordinates and waits | Uses bounded native input and semantic game actions |
| Stops when the page runs | Proves rules with fixed seeds and explicit assertions |
| Re-discovers the workflow next session | Replays short regression scenarios through reusable Skills |
game idea → design Skill → coding agent edits the game
↓
visual review ← Game Bridge ← MCP actions, observations, and assertions
└──────────────────── iterate ────────────────────┘
Web2DKit does not replace the coding agent, browser, terminal, or renderer. It gives them a shared, testable language for 2D game rules.
- Five game-development Skills for design, implementation, playtesting, debugging, and polish.
- Eight bounded MCP tools for project inspection, browser sessions, observation, actions, assertions, scenarios, and runtime quality checks.
- A framework-neutral Game Bridge that exposes authoritative JSON state without leaking renderer objects or arbitrary JavaScript execution.
- Versioned Acceptance Scenarios and a bounded CLI for repeatable local and CI rule verification.
- Codex and Claude Code plugin manifests backed by the same local Node.js server.
| Skill | When it helps | MCP evidence |
|---|---|---|
design-web2d-game |
Turn an idea into a player loop, vertical slice, state contract, and acceptance scenarios | project inspection and an evidence-ready design |
build-web2d-game |
Implement or extend Canvas, DOM/SVG, Phaser, PixiJS, or similar Web 2D games | observe the initial state and assert a complete loop |
playtest-web2d-game |
Verify controls, rules, lifecycle, responsive UI, and regressions | deterministic scenarios plus separate visual review |
debug-web2d-game |
Find the first incorrect transition instead of patching the visible symptom | fixed-seed reproduction and regression assertion |
polish-web2d-game |
Improve feel, UI, assets, accessibility, or performance without breaking rules | before/after visual evidence plus scenario guards |
The Skills deliberately keep gameplay truth and visual quality as two evidence lanes. Web2DKit handles structured game semantics; the host Agent keeps using its own browser and screenshot capabilities.
Requires Node.js 22+.
git clone https://github.com/44-99/Web2DKit.git
cd Web2DKit
npm ci
npx playwright install chromium
npm run validateThen follow Getting started to load the local plugin in Codex or Claude Code and point it at a running Web 2D game.
For a complete proof instead of a minimal demo, run the official Signal Relay end-to-end example:
npm run example:signal-relay:e2eIt starts the game automatically and uses the real MCP server to verify native input, seed propagation, deterministic replay, pause behavior, the winning route, and runtime quality.
Try prompts such as:
Use $design-web2d-game to turn this puzzle idea into a small testable game contract.
Use $build-web2d-game to implement the first complete player loop and verify it.
Use $playtest-web2d-game to prove restart clears the board and score.
Expose the serializable state already owned by the game:
window.__WEB2D_GAME__ = {
describe: () => ({ protocolVersion: "1", name: "my-game" }),
getState: () => structuredClone(gameState),
reset: ({ seed } = {}) => resetGame(seed ?? 1),
dispatch: ({ name, payload }) => dispatchGameAction(name, payload)
};An Agent can then run web2d_session_start → web2d_observe → web2d_scenario_run and prove a gameplay claim instead of inferring it from pixels. See the Bridge protocol and MCP tool reference.
Web2DKit targets browser-native 2D games built with DOM/CSS, Canvas 2D, SVG, Web Audio, or WebGL-based 2D renderers. It is designed for vanilla JavaScript/TypeScript and frameworks such as Phaser, PixiJS, Excalibur, and Kaboom.
Unity, Unreal, Godot, Three.js 3D scenes, and editor-dependent pipelines are outside the current scope. Framework detection exists today; deep Phaser and PixiJS adapters remain roadmap work and are not presented as complete.
- Getting started
- Signal Relay end-to-end example
- Architecture
- Game Bridge protocol
- Acceptance scenarios and CLI
- MCP tool reference
- Domain language
- Why Web2DKit augments the host agent
- Why scenarios are game-owned assets
- Latest Windows host verification
- Security boundaries
- Roadmap
- Contributing
Web2DKit is an early working foundation. Its real Chromium integration tests and Signal Relay puzzle example prove the state → action → assertion loop against an executable game. Action and simulation examples remain credibility gates before a stable release.
MIT licensed. Built for developers who want coding agents to create games they can also understand, play, and verify.