# Roadmap

> Which engine foundations and genre modules are built, which come next, and the phone-first principles that set the order.

The engine grows in two layers. **Foundations** are shared pieces every genre stands on (a character controller, bots, combat, saves, a 2D layer). **Genre modules** are complete game kits on top of them, each with a `defineXGame(config)` entry point. This page lists what is built, what comes next, and why in that order. The modules themselves are documented in [Game modules](https://docs.moonspell.app/modules/overview.md), and how to add one in [Writing a module](https://docs.moonspell.app/modules/writing-a-module.md).

## Principles

Moonspell games are played on a phone, mostly in portrait, in short sessions, and spread by a share link. That sets the order:

- **One thumb by default.** Unless a genre needs two thumbs (character games, racing), the first version uses one finger: tap, hold, swipe or drag.
- **Portrait by default.** Landscape needs a two-handed grip.
- **2D where the shape is 2D.** Many of the most played phone games are flat (block, merge and sort puzzles, cards, word games). They should not cost what a 3D game costs.
- **Progression where it holds players.** Puzzles, idle games and runners with shops need coins, upgrades, streaks and saves; one-tap arcade games do not.
- **Touch-first controls.** No dual-stick defaults and no free 3D camera; forgiving jumps (coyote time, jump buffer); large sticks with forgiving turn rates; a fixed camera for tap puzzles; an arc preview for flick and drag-to-aim games.
- **Live by default.** Every game gets a live leaderboard and presence when it has a backend, and rooms where the genre fits.

## Built

### Foundations

| Piece | What it gives a game | Docs |
|---|---|---|
| **F1** Character controller and cameras | A capsule character that collides with box levels, coyote time and jump buffer, third-person, first-person, top-down and side-view cameras, a stick plus look pad plus buttons in one gesture | [Character and cameras](https://docs.moonspell.app/engine/character-and-cameras.md) |
| **F2** Combat kit | Health, armour, teams, hitscan, projectiles, explosions and melee, aim assist, statuses, kill credit and respawns, armed bots | [Combat](https://docs.moonspell.app/engine/combat.md) |
| **F3** Bots | A nav grid with A*, steering, sight and hearing, roles and difficulties, bots that fill empty multiplayer seats | [Bots](https://docs.moonspell.app/engine/bots.md) |
| **F4** Saves and progression | Typed, versioned save slots with migrations; currencies, a shop, unlocks, items, loot, XP, daily streaks, offline earnings, bests; synced to a per-player Durable Object on the game's backend | [Saves](https://docs.moonspell.app/engine/saves.md) |
| **F5** Models and props, in part | Generated `.glb` models with fallbacks, animation clips, and `<Scenery>` for one model placed many times with instancing | [Engine overview](https://docs.moonspell.app/engine/overview.md) |
| **F6** 2D layer | A Skia game canvas with stage units, pointer events, a fixed-step loop, tweens, a grid, collision, particles, a 2D camera, sprite sheets and tile maps, plus a 2D platformer controller | [2D](https://docs.moonspell.app/engine/2d.md) |

Also built: the floating joystick, a story kit (dialogue, portraits, objectives), GPU grass, and the **game-router** skill, which turns a player's words into a genre and the route that builds it (see [Build with AI](https://docs.moonspell.app/ai/overview.md)).

### Genre modules and kits

| Module | Shape |
|---|---|
| **Racing** | 3D arcade racing: track shape and length, cars, laps, AI rivals, time of day, music |
| **Puzzle** | 2D puzzles on the 2D layer: block (place pieces, clear lines), merge, match (swap or tap to pop) and sort; endless or levels, a daily puzzle, every screen |
| **Arena shooter** | Free-for-all, team deathmatch, gun game, capture the flag and king of the hill; rounds, maps, pickups, bots that play the objective, one phone hosting the match for friends who join from the link |
| **Turns kit** | Turn-based board games: rules, a search, chess built in, a computer opponent that talks through the game backend's AI model, live online turns |
| **Kingdom** | A story-led town builder: buildings on timers, crops, land to clear, a hero class, squads, joystick sorties against enemy camps, chapters of dialogue |

Each has an example game in `templates/crescent-game/examples/` (see [Examples](https://docs.moonspell.app/examples.md)).

## Next

In order:

1. **Runner module**, 3D on F1 and the level system: streamed track chunks, lane swipes, jump and slide, obstacles, coins, multiplier gates, a distance leaderboard and a ghost of the top run. Presets for lane runners, gate runners and obstacle courses.
2. **One-tap arcade kit**, 2D first: a fixed-step loop with simple physics (gravity, bounce, swing), a scrolling camera, and presets for stacking, flapping, rising, swerving and swinging games, so "a game where you tap to..." becomes a config.
3. **Idle and tycoon module** on F4: resources, producers, timers, offline earnings, upgrade tables, a daily streak. A 2D interface by default, with an optional top-down scene.
4. **Survivors and horde**: automatic attacks, waves, XP pickups, pick one of three on level-up. Needs the rest of F5: instanced crowds, so a hundred or more enemies stay cheap.
5. **Cards, and turns across days**: card games on the 2D layer and the turns kit, and asynchronous turns kept on the game's backend.

## Later

Shapes that fit a phone and reuse what exists, not yet ordered:

| Shape | Builds on |
|---|---|
| Eat-and-grow arena (.io style) with short rounds and bot fill | F3 bots, instanced crowds, rooms |
| Flick sports (throw, shoot, bowl) with swipe-to-velocity and an arc preview | A small flick kit |
| Round-based party games: lobby, roles, a round timer, votes, results; a draw-and-guess game | A rounds kit on rooms |
| Tower defense | Bots on paths, the idle economy |
| Daily word and trivia games with a shared seed and a share card | The 2D layer, F4 |
| Obstacle courses with moving, crumbling and kill blocks | F1, the level kit |
| Co-op escape and horror | F1, F3, light combat |
| Drift and obstacle-course modes for racing | The racing module |

## Every module has the same shape

- a `defineXGame(config)` entry point with presets;
- a skill in `templates/crescent-game/.claude/skills/` that maps a player's words to the config, and a row in the **game-router** skill;
- an example in `templates/crescent-game/examples/`;
- a development-only debug line and an autopilot button, so a game can be checked without a human playing it;
- the realtime default: a leaderboard and presence, and rooms where they fit.

Plans for each piece of work live in `.scratch/<feature>/` ([Contributing](https://docs.moonspell.app/contributing.md#plans-and-issues)).