Roadmap
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, and how to add one in Writing a module.
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 |
| F2 Combat kit | Health, armour, teams, hitscan, projectiles, explosions and melee, aim assist, statuses, kill credit and respawns, armed bots | Combat |
| F3 Bots | A nav grid with A*, steering, sight and hearing, roles and difficulties, bots that fill empty multiplayer seats | Bots |
| 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 |
| 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 |
| 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 |
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).
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).
Next
In order:
- 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.
- 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.
- 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.
- 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.
- 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).