Skip to content

About

๐Ÿ•น๏ธ Describe a game as JSON, play it on a TV with a D-pad, and let robots make sure it's fair. Zero-dependency engine with a headless playtester and auto-balancer.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿ•น๏ธ couch-engine

Describe a game as JSON. Play it on a TV with a D-pad. Let robots make sure it's fair.

License Dependencies Runs on

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.

Features

  • ๐ŸŽฎ 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+.

Quick start

npm install github:priteshvirat24/couch-engine
import { 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 ..

Robot playtesting

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 adjusts speed, spawnRate, lives and goalScore toward 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.

GameSpec

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.

API

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 }.

Tests

npm test

License

Apache-2.0. Emoji graphics are Twemoji, licensed CC-BY 4.0.

About

๐Ÿ•น๏ธ Describe a game as JSON, play it on a TV with a D-pad, and let robots make sure it's fair. Zero-dependency engine with a headless playtester and auto-balancer.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages