Ludea — Game Engine
Version française
A template repository for building small top-down 2D games (Phaser 3, 100% static,
no build). The engine is generic: you don't code a game, you describe it in one
config file (game.config.js) + assets — or just run the /new-game skill and
answer a few questions.
It ships with a small starter game that already runs — a mini space nursery where a
keeper robot looks after three glowing critters (three needs, a close-up "polish" scene, a
rest pod, surprises that appear as you play), in English and French. It is the seed that
/new-game turns into your game (.claude/skills/new-game/references/minimal-seed.config.js).
Want to see everything the engine can do? The showcase Nebula Nursery switches on every
system — riding and jumps, shop and decorations, deliveries chased by drones, a pseudo-3D race…
▶ Play the showcase (source) ·
ludea.ai — the games made with the engine
🆕 Create a new game
This repo is a GitHub template — each game lives in its own repository, so the
engine stays clean and you can make as many games as you like.
- Use this template → Create a new repository. Click the green “Use this
template” button on the repo home, name your game (e.g.
my-space-game) and choose
Public (GitHub Pages publishes public repositories for free). You get a fresh,
independent repo containing the whole engine + a game that already runs.
- Open it in Claude Code, on the
main branch (see the warning below).
- Run
/new-game. It interviews you — theme, target age/audience, art style,
language, core loop — then writes your game.config.js, creates/sources the assets,
themes the look, tests it, and can deploy. It only touches the engine for a generic,
switchable feature your game truly needs — and then reports it to Ludea.
- Turn on GitHub Pages: in your repo, Settings → Pages → Source → “GitHub
Actions”. Your game goes live at
https://<you>.github.io/<repo>/ (or under your own
domain if your account's Pages site has one), and every later push to main redeploys
automatically.
That's it — you now have your own game. Keep shaping it by iterating.
⚠️ Run the Claude Code session on main. When you open your game repo in Claude
Code (web), make sure it develops on main — a session can otherwise spin up a
separate branch. If the game is pushed to another branch, GitHub Pages won't publish it
(Pages deploys the default branch) and the first deploy fails. Working on main
keeps every push a one-click deploy.
Start small. A new game should be tiny: one place, one creature, 1–2 needs, two
actions, maybe a small goal. You grow it by iterating — that's the whole workflow, so
don't pile on features up front.
(Prefer a hands-on start? You can skip /new-game and edit game.config.js yourself —
the full field-by-field schema is in ENGINE.md.)
✏️ Make it yours by iterating
Most changes are a small config edit, each with a dedicated skill — just ask in plain
language (e.g. “add a pink critter”, “let me ride them”, “add a shop”):
| Want to add… | Where it lives | Skill |
|---|
| A new colour/skin for the creature | creature.variants (a tint, or a sheet drawn in tools/art/) | add-creature-variant |
| Rename / restyle creatures | creature.customize | — |
| A shop & coins | economy + shop (and meta.showCoins) | — |
| Buyable, placeable decorations | GAME.decor | add-decor-item |
| Riding + obstacles to hop | creature.ride (+ environment.arena) | add-collision |
| Babies / growing up | creature.breeding, creature.aging | — |
| A scattered forest / trail loop | GAME.environment | place-scatter |
| More goals / levels | GAME.objectives.levels | — |
| Another playable character | GAME.characters | add-character |
| Brand-new art | tools/art/<game>.cjs → assets/ (SVG → PNG) | asset-add (or asset-search for external art) |
| New UI icons | GAME.icons (_shared/icon-kit.cjs) | — |
| Theme-specific effects (e.g. stars when playing) | action.anim particles | — |
Nothing here ships in the starter on purpose — you switch features on as you need them.
For non-technical feedback (the players, even children), the feedback-session
skill lets them drive changes in plain words while the technical work happens silently.
📣 Tell Ludea, and get your game in the catalogue
Your game and the engine improve each other:
- Automatically: when your game hits a bug in the engine or its skills, or when your game
needs a new engine capability (added as a generic, switchable feature), the report-upstream
skill sends it to Ludea as an issue on ludea-ai/game-engine,
with the exact change attached. Ludea reviews it, adds it to the engine, and every game gets it
at the next update (
sync-engine from https://github.com/ludea-ai/game-engine.git).
/update: when Ludea releases a newer engine, your session tells you what it brings (fixes, and new capabilities your game could use); say yes and your game is updated, tested and put back online./idea: your own ideas for the engine ("it would be great if the engine could…")./publish: ask for your game to appear on ludea.ai — or send an update of a game already published there. It checks your
game is ready (age, description, French + English, icon, no errors) and safe for children (no
tracker, ad, external link or data collection), then sends a request. Ludea reviews it — child
safety first — and, once accepted, publishes a copy of the reviewed version at https://ludea.ai/<your-game>/.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
