# Moonspell

> Moonspell is a React Native setup for games: one TypeScript codebase that plays in the browser, on iOS and on Android, drawn with WebGPU everywhere, and made so a coding agent can build a whole game with it.

Every page below is Markdown. The whole site in one file: https://docs.moonspell.app/llms-full.txt. Any page's HTML URL plus `.md` gives its Markdown.

## Overview

- [Moonspell](https://docs.moonspell.app/index.md): The Moonspell engine is a React Native (Expo) project set up as a game runtime, one TypeScript codebase that plays in the browser, on iOS and on Android, with a WebGPU 3D renderer on every platform.

## Get started

- [Quickstart](https://docs.moonspell.app/start/quickstart.md): Clone the repository, install the game template, run the starter game Sunset Sprint in a browser with npm run web, make a static web build, run an example, and find the steps for iOS and Android.
- [Your first game](https://docs.moonspell.app/start/first-game.md): Build Orb Hunt, a small 3D game, from scratch in src/game/index.tsx, step by step, with EngineCanvas, a joystick that also answers to the keyboard, a game loop in useFrame, a HUD and a finish screen, then run it in the browser.
- [Publish to the Moonspell app](https://docs.moonspell.app/start/publish-to-moonspell.md): Local developer mode, step by step - build a Moonspell game on your own computer with your own coding agent, then publish it to the Moonspell app on iPhone and Android and to the web with the built crescent CLI.
- [How it works](https://docs.moonspell.app/start/how-it-works.md): React Native as a game runtime, concretely, from the entry points and the Metro bundle to how EngineCanvas, three.js's WebGPU renderer and React Three Fiber produce a frame, how the HUD and input sit over the canvas, where platform differences live, and what the optional shell is.
- [Project structure](https://docs.moonspell.app/start/project-structure.md): What is in a Moonspell game repo, as an annotated tree of the game template, which files you edit, which you leave alone, the placeholders a copied template must replace, and where the docs and skills for coding agents live.
- [The game contract](https://docs.moonspell.app/start/game-contract.md): The rules every Moonspell game follows so the same source plays in a browser, on iOS, on Android and inside the Moonspell app, covering the entry export, exit and cleanup, pausing, orientation, input, assets, drawing, the pinned dependency set, performance budgets and the labels playtests rely on.
- [What is open and what is private](https://docs.moonspell.app/start/open-source.md): Which parts of Moonspell are open source under the MIT License, whose source stays private (the Moonspell phone app and the crescent CLI, which is still handed out in built form), and the two ways to build a game, engine only or published to the Moonspell app.

## Engine

- [Engine overview](https://docs.moonspell.app/engine/overview.md): The map of src/engine, what each folder and file does, how a game imports from the engine, and what belongs in src/game versus src/engine.
- [Canvas and rendering](https://docs.moonspell.app/engine/canvas-and-rendering.md): EngineCanvas, the three.js WebGPU renderer it drives, how react-three-fiber runs inside it, the frame loop, Environment for sky and light, PostFX, glow and the error boundary.
- [Input](https://docs.moonspell.app/engine/input.md): The engine's multi-touch controls, TouchControls for racing, the floating Joystick and CharacterControls for character games, the input objects they write, and the keyboard they answer to in a desktop browser.
- [HUD and UI](https://docs.moonspell.app/engine/hud-and-ui.md): The HUD pieces in @/engine (TopBar, RoundButton, FinishCard, Banner, DebugRow, the Skia Gauge) and the game UI kit in @/engine/ui (SF Symbol icons, bundled fonts, rolling counters, press and pop motion, sprite-sheet images).
- [Audio](https://docs.moonspell.app/engine/audio.md): The audio mixer (useAudioMixer, AudioMixer, AudioListener) with buses, positional sounds, random pitch, voice limits, ducking and music crossfades, plus the mixing maths and RaceAudio.
- [Physics](https://docs.moonspell.app/engine/physics.md): Rigid bodies on cannon-es behind a typed API (Physics, RigidBody, StaticBody, LevelBodies, TriggerVolume, Joint, PhysicsWorld), the player's capsule, collisions and rays, the drivable Vehicle, and GPU Debris for thousands of small pieces.
- [Models and scenery](https://docs.moonspell.app/engine/models-and-scenery.md): Bundled .glb models through Model (sized, anchored, animated, with a fallback until the file is real), Scenery for one model placed many times with instancing, Billboard sprites in the 3D scene, SheetImage in the HUD, and the loaders behind them.
- [GPU effects](https://docs.moonspell.app/engine/gpu-effects.md): TypeGPU effects on three's own GPU device, Particles, Trail, Grass, LivelyGround, Water and GpuStrip, and how to write your own compute shader that fills buffers three draws.
- [Game feel](https://docs.moonspell.app/engine/game-feel.md): Camera shake, hit-stop, slow motion, a screen flash, squash and stretch, pops and tweens on any three object, and the juice presets that combine them, from GameFeel and FeelOverlay.
- [The 2D layer](https://docs.moonspell.app/engine/2d.md): GameCanvas2D and the pieces a flat game uses, from stage units, pointer events and the fixed-step loop to drawing, tweens, particles, sprite sheets, tile maps, platformer and top-down bodies, and a 2D camera.
- [Character and cameras](https://docs.moonspell.app/engine/character-and-cameras.md): A body that walks, runs, jumps, hangs from ledges and looks around in a level of boxes, four camera rigs and the multi-touch controls that drive it.
- [Combat](https://docs.moonspell.app/engine/combat.md): Health, armour, weapons as data, hitscan and projectile shots, explosions, aim assist, status effects, kill credit, respawns, bots that shoot back, and the effects and HUD that draw it all.
- [Bots](https://docs.moonspell.app/engine/bots.md): Computer opponents that patrol, hear, see, chase, keep their distance or flee on the same character controller as the player, with a nav grid, steering, senses and a roster that fills empty seats.
- [Saves and progression](https://docs.moonspell.app/engine/saves.md): Typed, versioned saves kept on the device and synced to the game's backend when it has one, plus currencies, a shop, unlocks, XP, daily streaks, offline earnings, player settings and a shareable score card.
- [Networking](https://docs.moonspell.app/engine/net.md): Leaderboards, "N playing now" presence, multiplayer rooms and room links, with one API that works on the device alone and goes online when the game has a backend.
- [Story](https://docs.moonspell.app/engine/story.md): Dialogue with cut-out portraits, choices on cards, reward sheets, objectives and chapters, written as data and run by a small saveable state machine.
- [Turns](https://docs.moonspell.app/engine/turns.md): Turn-based games described once as TurnRules, with full chess, a look-ahead search, a computer opponent at three levels that can talk through the game's backend, and online turns over a room.
- [Utilities](https://docs.moonspell.app/engine/utilities.md): The small shared pieces of the engine, math helpers, paths and the things that follow them (followers, moving platforms, camera dollies, path meshes), trigger zones and typed signals, and the development debug overlay.
- [Platform layer](https://docs.moonspell.app/engine/platform-layer.md): How one game source runs in a browser, on iOS and on Android, the shell contract (shell.ts, shellModule.ts, shellModule.web.ts), the web boot in src/engine/web, the engine's other platform branches, what happens with no Moonspell app around the game, and why platform differences never go in a game.

## Game modules

- [Game modules](https://docs.moonspell.app/modules/overview.md): A game module is a whole genre packaged as one defineXGame call; this page explains how modules differ from engine pieces, lists the four modules and helps you pick one.
- [Racing module](https://docs.moonspell.app/modules/racing.md): defineRaceGame builds a complete 3D arcade car race from one config, with a track, the player's car, AI rivals, a chase camera, a HUD, touch and keyboard controls, and a countdown and finish screen.
- [Puzzle module](https://docs.moonspell.app/modules/puzzle.md): definePuzzleGame builds a complete 2D grid puzzle from one config, with four rule packs (block, merge, match, sort), endless or level play, a daily puzzle, every screen, sounds, haptics and a leaderboard.
- [Shooter module](https://docs.moonspell.app/modules/shooter.md): defineShooterGame builds a complete 3D arena shooter from one config, with five modes, rounds, three mirrored maps, items, bots in every empty seat, and multiplayer where one host phone runs the match.
- [Kingdom module](https://docs.moonspell.app/modules/kingdom.md): defineKingdomGame builds a story-led town builder with joystick sorties from one config, with buildings on timers, producers, crops, debris, a hero class, a squad, enemy camps, rewards and chapters of dialogue.
- [Writing a module](https://docs.moonspell.app/modules/writing-a-module.md): How to add a new game module to the engine, following the file layout, define function, config types, tests, docs, skill and example that the four existing modules share.

## Examples

- [Example games](https://docs.moonspell.app/examples.md): The eleven example games in templates/crescent-game/examples, what each one shows, which engine pieces or module it uses, which files to read first, and how to run one.

## Backend

- [Game backend](https://docs.moonspell.app/backend/overview.md): Each game's shared and lasting data lives on its own Cloudflare Worker, made from the template's backend scaffold (Durable Objects, D1, Workers AI), while the device keeps an offline copy; what the scaffold contains, which engine piece uses which route, and how to deploy it to your own Cloudflare account with Wrangler.
- [Realtime](https://docs.moonspell.app/backend/realtime.md): The backend side of leaderboards (and the rule that every board name must be in BOARDS), "N playing now" presence, and multiplayer rooms players join from a link, as the scaffold's Durable Objects implement them.
- [Saves sync](https://docs.moonspell.app/backend/saves-sync.md): How engine saves (src/engine/save) sync to the player's own PlayerSaves Durable Object, with revisions, conflicts and merges, live updates to the player's other copies, the server clock, and the limits the backend enforces.
- [Computer opponent](https://docs.moonspell.app/backend/ai-opponent.md): POST /ai/turn, the backend route where a Workers AI model plays one turn of a turn-based game in character, choosing among the moves the game's own search offers, and how useOpponent in the turns kit calls it and falls back when it cannot.

## Build with AI

- [Build with AI](https://docs.moonspell.app/ai/overview.md): What a coding agent gets from a Moonspell game repo (CLAUDE.md, AGENTS.md, 24 skills, agent docs, examples, GDD.md and playtest.json) and why the engine is shaped for agents.
- [Claude Code and other agents](https://docs.moonspell.app/ai/claude-code.md): Step by step, open a Moonspell game repo in Claude Code or another coding agent, ask for a game, let the agent check its own work, and know which skills assume the hosted Moonspell app.
- [Skills](https://docs.moonspell.app/ai/skills.md): Every skill in the game template's .claude/skills folder, grouped by job, with what it is for, when an agent should load it, what it produces, and which ones assume the hosted Moonspell pipeline.
- [Game router](https://docs.moonspell.app/ai/game-router.md): How the game-router skill turns a player's idea into a genre and a route (a module config, an example to copy, or from scratch), with its classify and route tables.
- [GDD.md and playtest.json](https://docs.moonspell.app/ai/game-design-doc.md): The two files every game repo keeps for its agent, GDD.md (the game's design document and memory between sessions) and playtest.json (a script of real touches that proves the game plays), with their formats and what runs them.
- [llms.txt and Markdown pages](https://docs.moonspell.app/ai/llms-txt.md): Feed these docs to a model with /llms.txt (an index), /llms-full.txt (every page in one file) or the Markdown copy of any page, with examples for curl, a chat and an agent's project file.
- [MCP servers](https://docs.moonspell.app/ai/mcp.md): The two Moonspell MCP servers side by side - the public docs server at https://docs.moonspell.app/mcp that searches and reads these docs, and the Moonspell server at https://mcp.moonspell.app/mcp that gives a signed-in developer's agent the engine's skills and their account - with setup for Claude Code, Claude Desktop, Cursor, VS Code and Codex.

## Platforms

- [Web](https://docs.moonspell.app/platforms/web.md): How a Moonspell engine game runs in a browser, from the web entry and Skia's CanvasKit to npm run web, a static export in dist/, hosting it, keyboard input, embedding it in a page with an iframe, and the known issues.
- [iOS](https://docs.moonspell.app/platforms/ios.md): How to run a Moonspell engine game as a normal Expo development build on an iOS simulator or iPhone, what app.json needs, release builds, and what differs from playing inside the Moonspell app.
- [Android](https://docs.moonspell.app/platforms/android.md): How to run a Moonspell engine game as a normal Expo development build on an Android emulator or phone, why the react-native-webgpu plugin and minSdk 26 are required, the package name, release builds, and what differs from the Moonspell app.
- [Platform differences](https://docs.moonspell.app/platforms/differences.md): What differs between web, iOS and Android for a Moonspell engine game (rendering, input, audio, haptics, storage, fonts, safe areas, orientation, links, performance), where the engine handles each difference, and what the Moonspell app's shell adds when it is there.

## How Moonspell works

- [Architecture](https://docs.moonspell.app/moonspell/architecture.md): The whole hosted Moonspell system on one page, from the app and the server to the sandbox, storage, the edge Worker and each game's own backend.
- [Nova and the worker](https://docs.moonspell.app/moonspell/nova-and-the-worker.md): How Nova, the chat agent in agent/, hands a brief to the worker run, how the worker builds in checkpoints so a run always lands a version, and how left-out extras come back as suggestions.
- [Builds and versions](https://docs.moonspell.app/moonspell/builds.md): What a Moonspell version is, how a run exports it once per platform, where the files are stored, and how each app gets its own export.
- [Live progress](https://docs.moonspell.app/moonspell/realtime.md): How the edge Worker in edge/ streams a build's progress to the apps through one Durable Object per run, and what else the Worker does.
- [Community builds](https://docs.moonspell.app/moonspell/community-builds.md): How any Moonspell player can keep improving someone else's game through a private draft, a merge, a judge, and the author's review.
- [Credits](https://docs.moonspell.app/moonspell/credits.md): How the Moonspell app prices and meters building, from the credit ledger and monthly refill to the edge's meter for the builder's Claude calls and the confirm box for generated assets.
- [Sharing](https://docs.moonspell.app/moonspell/sharing.md): How every Moonspell version gets its own share link, what the shared-game page shows, and how the apps and the App Clip open it.
- [Three apps, one product](https://docs.moonspell.app/moonspell/three-apps.md): How the iOS, Android and web apps stay one Moonspell product with no shared UI code, through generated contracts, one server API and per-feature specs checked by the parity script.
- [Deploy](https://docs.moonspell.app/moonspell/deploy.md): The order in which the hosted Moonspell server, database, storage, game repos, sandbox snapshot, edge Worker and optional services are set up, and which environment variables each needs.
- [Development setup](https://docs.moonspell.app/moonspell/dev-setup.md): How to run the Moonspell server, the web app, Nova and the edge Worker locally from a public clone, and what does and does not work without the private app and CLI.
- [Testing](https://docs.moonspell.app/moonspell/testing.md): The checks for the Moonspell server, the edge Worker, the engine and template, game backends, the contracts and these docs, and how playtests decide which games get a feed video.
- [Game channels](https://docs.moonspell.app/moonspell/channels.md): A channel per game for its author and everyone with an accepted change, with moderation and announcements.
- [Notifications and categories](https://docs.moonspell.app/moonspell/notifications.md): The inbox every app shows, push to phones and browsers, the daily digests, and the category each game is sorted into.
- [Game repos](https://docs.moonspell.app/moonspell/game-repos.md): Where each Moonspell game's git repo lives, the one interface in front of the two hosts (GitHub and Cloudflare Artifacts), and how a deployment moves games between them.
- [Local developer mode](https://docs.moonspell.app/moonspell/local-dev-mode.md): The server side of local developer mode - how the Moonspell server signs a developer's CLI in, gives it the game's repo, takes a published version and handles invites, under /api/dev.
- [The Moonspell MCP server](https://docs.moonspell.app/moonspell/mcp-server.md): How the remote MCP server at mcp.moonspell.app works - what it serves a developer's agent, how signing in with Google turns into a dev token, and how to run and test it locally from mcp/.

## Contributing

- [Contributing](https://docs.moonspell.app/contributing.md): How to contribute to Moonspell, what is in the public repo, which checks to run before a pull request, where plans and issues live, and the rules that keep every game playing everywhere.
- [Roadmap](https://docs.moonspell.app/contributing/roadmap.md): Which engine foundations and genre modules are built, which come next, and the phone-first principles that set the order.