Build with AI
The Moonspell engine was built so that a coding agent can make a whole game with it, from an idea to a version you can play. Every game repo starts from the game template in templates/crescent-game/, and that template carries everything an agent needs to work in it: standing instructions, skills that hold the know-how for each genre and engine piece, reference docs next to the code, complete example games, and checks the agent can run itself.
This section is for two readers: you, setting up Claude Code or another agent on a game, and the agent, reading these pages as Markdown to learn how to work with the engine.
What an agent gets from a game repo
| File or folder | What it is for |
|---|---|
CLAUDE.md | The repo's standing instructions: what can be built and with which engine piece, the rules every game keeps (one game for web, iOS and Android, input through the engine's controls, assets through require(), no emoji on screen, clean up on unmount), and how to finish a task. Claude Code reads it at the start of every session. |
AGENTS.md | The same instructions under the name other coding agents look for. It is an exact copy of CLAUDE.md. |
.claude/skills/ | 24 skills, one folder each with a SKILL.md: routing an idea to a genre, one per genre module, one per engine piece, art and audio, the backend, the playtest. See Skills. |
.claude/settings.json | A permission allowlist for Claude Code: npx tsc, npm run typecheck, the crescent CLI and agent-device. |
docs/ | Agent-facing references for the engine, one file per piece: engine-api.md, games-contract.md, racing-module.md, shooter-module.md, puzzle-module.md, kingdom-module.md, character-controller.md, bots.md, combat.md, 2d-layer.md, saves.md, turns.md, cloudflare.md. Skills point to them for every field and range. |
examples/ | Eleven complete games, each one file (examples/<name>/index.tsx) to copy over src/game/index.tsx and change. examples/README.md says what each shows. See Examples. |
src/game/index.tsx | The game itself: a GameDefinition as its default export. The starter is Sunset Sprint, a racing module config. |
src/engine/ | The game's own copy of the engine. An agent may change or extend it; the change affects only this game. |
GDD.md | The game's design document and its memory between sessions. Not in the template: the agent creates it on the first task. See GDD.md and playtest.json. |
playtest.json | A short script that plays the game with real touches. The template ships one for Sunset Sprint. |
.claude/skills/realtime-backend/scaffold/backend/ | The game's Cloudflare Worker, copied to backend/ when the game goes online. See Backend. |
Why the engine is shaped this way
- Small pieces that compose. Input, cameras, physics, audio, particles, saves and the network are separate engine pieces with typed props. An agent can read one piece's doc and use it without reading the rest. See the engine overview.
- Genre modules for the common shapes. A racer, an arena shooter, a puzzle game and a kingdom builder are each one config object (
defineRaceGame,defineShooterGame,definePuzzleGame,defineKingdomGame). Turning a request into a config is far more reliable than writing a game loop from scratch. See Game modules. - Skills carry the know-how. Each skill maps a player's words to the engine's fields ("night, neon" to
timeOfDay: 'night'and a palette), lists the limits, and says what to do instead. The agent loads only the skill its task needs. - Docs next to the code. The template's
docs/travel with every game repo, so the reference an agent reads matches the engine copy it is editing. - Checks an agent can run.
npm run typecheck,npm test(the engine's unit tests) andnpm run export:web(a full static build) tell the agent whether its change works, without a person in the loop. See Claude Code and other agents. - Small playable steps. The skills ask for the smallest playable version first, then one change at a time, each one checked and committed.
Inside and outside the Moonspell app
The template is also what the hosted Moonspell app uses: a player chats with Nova, and a Claude Code worker edits the game's repo in a sandbox. Some instructions and skills are written for that worker and mention the crescent CLI, the Moonspell app, or art, sound and models generated after the worker's pass. Outside the app you have two choices:
- Engine only, plain Expo. None of those tools exist. Claude Code and other agents lists which parts assume the hosted pipeline and what to do instead.
- Local developer mode. You publish to the Moonspell app from your own computer. The starter from moonspell.app rewords the skills for your machine and adds the built
crescentCLI, amoonspell-devskill and the Moonspell MCP server. See Publish to the Moonspell app.
What is open and what is private is on Open source.
In this section
- Claude Code and other agents: set up an agent on a game repo, prompts that work, how the agent checks its work.
- Skills: every skill, what it is for and when to load it.
- Game router: how an idea becomes a genre route.
- GDD.md and playtest.json: the design document and the playtest script.
- llms.txt and Markdown pages: feed these docs to a model.
- MCP servers: let an agent search these docs, or reach your Moonspell account in local developer mode.