Describe a game as JSON. Play it on a TV with a D-pad. Let robots make sure it's fair.
couch-engine is the dependency-free game engine behind Couch Game Studio, the Fire TV app where kids invent games out loud.
The idea is simple: a game is data, not code. A small, validated GameSpec describes the hero, the goodies, the hazards, the world and the rules. The engine turns any valid spec into a polished, playable game. That makes it a safe target for generative AI and for kids: a model or a child can design a game, but nobody writes code that could crash or misbehave.
It also ships a robot playtester. Bots with kid-level and grown-up-level reflexes play every game hundreds of simulated seconds in a few milliseconds, and an auto-balancer tunes the difficulty until a kid can win but a grown-up isn't bored.
- ๐ฎ Four genres:
catcher,runner,maze,shooter. - โจ Twelve stackable modifiers: night lighting, lava floor, giant or tiny hero, double points, reversed controls, wind, rainbow trail, slow motion, bouncy, boss fights, confetti.
- ๐จโ๐ฉโ๐ง Up to 4 co-op players (a TV remote plus phones, keyboards or gamepads).
- ๐บ Made for TVs: a 1280ร720 canvas, D-pad-only controls, a 3-2-1-GO countdown, large HUD, gold glow for "grab it" and red glow for "avoid it".
- ๐ต Procedural chiptune music and sound effects (WebAudio, nothing to download).
- ๐ค Headless mode, seeded simulation and auto-balancing: the same game logic runs in Node, deterministically.
- ๐งฉ Zero dependencies. Plain ES modules. Works in browsers, TV WebViews (Fire TV / Vega OS) and Node 20+.
npm install github:priteshvirat24/couch-engineimport { Game, normalizeSpec, sfx } from 'couch-engine';
const spec = normalizeSpec({
title: "Biscuit's Taco Rain",
genre: 'catcher',
hero: { name: 'Biscuit', emoji: '๐ถ' },
goodies: [{ name: 'Taco', emoji: '๐ฎ', points: 1 }],
hazards: [{ name: 'Broccoli', emoji: '๐ฅฆ' }],
rules: { speed: 4, spawnRate: 5, lives: 3, goalScore: 20 },
modifiers: ['confetti'],
});
const game = new Game(document.querySelector('canvas'), spec, {
onEvent: (e) => e.type === 'end' && console.log(e.won ? 'You won!' : 'Try again'),
});
await game.load(); // fetches emoji sprites
sfx.unlock(); // call from a user gesture to enable audio
game.start();
addEventListener('keydown', (e) => e.key === 'ArrowLeft' && game.input('tv', 'left', true));
addEventListener('keyup', (e) => e.key === 'ArrowLeft' && game.input('tv', 'left', false));There's also a no-build playground: serve the repo folder and open examples/index.html, for example with npx serve ..
import { balance, evaluate } from 'couch-engine/playtest';
const { spec, report } = balance(tooHardSpec);
// report โ {
// verdict: 'fair', kidWinRate: 0.75, grownupWinRate: 1, avgWinSeconds: 23, runs: 12,
// changes: ['made it a little easier']
// }
evaluate(spec, { skill: 'kid', runs: 8 }); // โ { winRate, avgWinSeconds, avgSeconds, runs }How it works
- Each genre has a bot "brain":
- Catcher bots predict where things land and dodge hazards.
- Runner bots time their jumps.
- Maze bots path-find with BFS and steer clear of ghosts.
- Shooter bots aim and dodge.
- Skill levels change reaction time, mistakes and precision. The kid bot is deliberately slow and makes mistakes.
balance()runs seeded games and adjustsspeed,spawnRate,livesandgoalScoretoward the targets: a 60โ95% kid win rate, with wins taking 25โ110 seconds.- As a last resort it removes the single hardest modifier.
- It never changes creative choices: hero, theme and items stay exactly as designed.
A full balance pass usually takes 20โ300 ms.
| Field | Type | Notes |
|---|---|---|
title, tagline |
string | โค 28 and โค 60 characters |
genre |
catcher | runner | maze | shooter |
|
hero |
{ name, emoji, image? } |
image (a URL) replaces the emoji, e.g. a kid's drawing |
goodies |
[{ name, emoji, points 1โ10 }] |
1โ4 |
hazards |
[{ name, emoji }] |
1โ4 |
projectile, goal |
emoji | shooter shot / maze exit |
theme |
{ skyTop, skyBottom, ground, scenery } |
hex colors, up to 3 scenery emojis |
rules |
{ speed 1โ10, spawnRate 1โ10, lives 1โ5, goalScore 5โ100 } |
|
modifiers |
up to 4 of the 12 listed above | |
narration |
{ intro, win, lose } |
short lines for the player |
normalizeSpec(anything) always returns a valid spec: it clamps, defaults and strips anything unknown. SPEC_JSON_SCHEMA is ready to use as an LLM tool or structured-output schema.
| Export | What it does |
|---|---|
new Game(canvas, spec, { onEvent }) |
A playable game. Methods: load(), start(), pause(), resume(), stop(), input(playerId, action, down), addPlayer(id), removePlayer(id) |
Game.headless(spec, { players }) + game.step(dt) |
Simulation without a canvas |
normalizeSpec, SPEC_JSON_SCHEMA, GENRES, MODIFIERS, GENRE_HELP |
The spec contract |
simulate, evaluate, balance(spec, { difficulty: 'easy' | 'normal' | 'hard' }), SKILLS, TARGETS |
Robot playtesting |
config.emojiBase |
Where emoji SVGs load from (default: the Twemoji CDN) |
setRandom, seededRandom |
Deterministic randomness |
sfx, music |
Audio |
Events passed to onEvent: score, lives, players, paused, end { won, score }.
npm testApache-2.0. Emoji graphics are Twemoji, licensed CC-BY 4.0.