gamecodex

GameCodex

A game designer AI lens for programmers. One MCP tool.

Your AI assistant writes competent game code and gives you zero design judgment. It will implement a jump, a shop, or an entire crafting system without ever asking whether it should exist, what it should feel like, or which proven design thinking applies. GameCodex gives your AI that judgment: a single tool — lens — that answers as the game designer looking over your shoulder.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, Cline, and any MCP-compatible tool.

Quick start

claude mcp add gamecodex -- npx -y gamecodex

Or add to your MCP config file (claude_desktop_config.json, .cursor/mcp.json, ~/.windsurf/mcp.json, …):

{
  "mcpServers": {
    "gamecodex": { "command": "npx", "args": ["-y", "gamecodex"] }
  }
}

The one tool

lens { situation: "my jump feels floaty" }

returns the Game Feel lens (Steve Swink, 2008): the questions a designer would ask right now ("how many frames between input and first visible response — have you measured?"), red flags phrased in code terms ("input handled in a fixed tick without interpolation", "jump is a single impulse with default gravity"), and concrete prescriptions ("derive gravity from jump height and time-to-apex: g = 2h/t², v0 = 2h/t; split rising/falling gravity; add coyote time and input buffering").

Call	Returns
lens { situation: "..." }	Top matching lenses for what you're building, deciding, or struggling with — plus the matching knowledge-base docs
lens { lens: "scope" }	A specific lens by id
lens { doc: "G106" }	A knowledge-base doc — oversized docs return a table of contents
lens { doc: "G106", section: "Jitter" }	Just that section of the doc
lens { }	The catalog

No action routing. Four optional strings. That's the entire API.

The 15 lenses

Every lens distills an industry-proven philosophy — real, checkable provenance, original distillations:

Lens	Source	Reach for it when
find-the-fun	Mark Cerny — Method (D.I.C.E. 2002)	Starting anything; building systems before fun is proven
mda	Hunicke/LeBlanc/Zubek (2004)	A feature works as coded but the game feels wrong
interesting-decisions	Sid Meier (GDC 2012)	Everyone picks the same option; choices feel hollow
game-feel	Steve Swink (2008)	Floaty, sluggish, unresponsive, slippery
juice	Jonasson & Purho (2012); Nijman (2013)	Combat "lacks impact"; actions go unacknowledged
flow-difficulty	Csikszentmihalyi (1990); Celeste Assist Mode (2018)	Players quit; too hard/too easy arguments
onboarding	George Fan (GDC 2012); Nintendo	New players are confused; tutorial walls of text
kishotenketsu	Koichi Hayashida (GDC 2012)	Levels feel like filler; no per-level identity
core-loop	Dormans (2012); session-design craft	"What do players actually do?"; retention questions
scope	Derek Yu — Finishing a Game (2010)	"Should I add X?"; the project keeps growing
playtesting	Valve culture; RITE (2002)	Months of dev, zero external eyes
player-motivation	SDT (Ryan/Rigby 2006); Bartle; Quantic Foundry	"Who is this for?"; retention mechanics debates
balance	Sirlin; Schreiber	Overpowered options; economies that inflate
theory-of-fun	Raph Koster (2004)	"It gets old fast"; depth vs. complexity
emergence	BotW (GDC 2017); immersive sims	Special-cased interactions; content treadmill

The knowledge base works within the lens

The 957-doc engine library (29 engines — deepest on MonoGame 131, Godot 116, Unity 81, Unreal 81; every doc purpose-written for AI consumption, drafted with AI assistance under human editorial direction) is reachable through the same one tool:

• every situation reply ends with From the knowledge base — the top matching docs with ids
• doc: "<id>" reads one; docs over 25KB return their table of contents so you fetch just the section you need instead of flooding context

The docs also ship as passive MCP resources at gamedev://docs/{module}/{id} for clients that browse resources.

Scope which modules load:

{ "env": { "GAMEDEV_MODULES": "core,godot-arch" } }

Without GAMEDEV_MODULES, all modules load.

What makes this different

• Judgment, not integration. Godot-MCP and Unity-MCP give your AI buttons to press in the editor; Context7 gives it API docs. GameCodex gives it design thinking — the layer none of them touch. They compose well.
• One tool. No 50K-token schema dump. The entire tool surface is four optional strings.
• Real provenance. Every lens cites its source — the talks, books, and papers the industry actually runs on. No invented frameworks.
• Secure by design. stdio-only transport — no network, no open ports. Analytics are local JSON files (~/.gamecodex/analytics/), never uploaded.

Development

git clone https://github.com/sbenson2/GameCodex.git
cd GameCodex
npm install
npm run build
npm test

Runtime dependencies: @modelcontextprotocol/sdk and zod. Nothing else.

See SPEC.md for the v2 architecture and lens content rules, and SECURITY.md for the security policy.

Upgrading from 1.x: v2.0.0 removed the project/design/docs/build/meta tools — the lens is the product now. gamecodex@1.0.1 is the final release of the old five-tool surface if you depend on it.

Contributing

Found a bug, a provenance error, or a doc correction? Open an issue. New lenses are welcome if they meet the content rules in SPEC.md: real, checkable provenance; original distillation; red flags in programmer terms.

License

MIT — see LICENSE.

---

Built for programmers who want their AI to think like a designer.