Adding a new game

Every game on this site is a configuration object passed to the shared engine in assets/js/engine.js. You do not write game code to add a game - you describe one.

1. Add an entry to _src/games_data.py

{
  "slug": "my-new-game",
  "title": "My New Game",
  "h1": "My New Game - Play Free Online",
  "meta_title": "My New Game - Play Free Online | Brick Breaker Games",
  "meta_desc": "150 characters describing what makes this game different.",
  "short": "One line for the game card.",
  "description": "Two lines for JSON-LD and the data file.",
  "category": "Classic",                       # display label
  "categories": ["classic", "skill"],          # filter chips, lowercase
  "difficulty": "Medium",                      # Easy | Medium | Hard | Expert
  "controls": "Keyboard, mouse and touch",
  "control_keys": ["keyboard", "mouse", "touch"],
  "hook": "Short badge line",
  "objective": "What the player is trying to do.",
  "what_makes_it_different": "A paragraph. Be specific - this is the anti-clone section.",
  "tips": [ ... 5 tips ... ],
  "faq": [ (question, answer), ... 4 items ... ],
  "related_games": ["slug", "slug", "slug"],
  "related_articles": ["slug", "slug", "slug"],
  "primary_category": "brick-breaker-games",   # one of the six category slugs
  "engine": { ... see below ... }
}

2. Engine configuration reference

3. Level objects

{
  "name": "The Tunnel",
  "pattern": "tunnel",     # rows pyramid diamond checker fortress tunnel
                           # zigzag waves columns scatter arch
  "rows": 6, "cols": 11,
  "mix": "nnnnsp",         # weighted string: one character per weight unit
  "brickHeight": 22,       # optional
  "top": 26,               # optional offset below the top wall
  "moving": true,          # optional: slide selected rows horizontally
  "movingEvery": 2, "movingAmp": 30, "movingSpeed": 0.7
}

Brick type characters:

mix can also be an object: {"rows": ["s","n","u"], "edge": "u", "core": "x", "fallback": "n"}. edge and core only apply to the fortress pattern.

4. Make it genuinely different

Levers that produce real differences: failure system (lives / ball budget / timer / descent), scoring rule (flat / combo / time bonus), power-up pool including harmful capsules, brick mix (unbreakable and explosive change level shape most), acceleration, and aim-based launching.

5. Rebuild

py _src/build.py

This creates games/<slug>/index.html, generates the featured image, adds the game to data/games.json and the search index, adds it to the directory, the XML sitemap and the HTML sitemap.

6. Test before publishing

• Every level is completable, and no breakable brick is unreachable.
• Keyboard, mouse and touch all work; the touch buttons appear on a phone.
• Pause, restart and sound toggle work; the score saves and reloads.
• No console errors; the ball never escapes through a wall or the floor.
• Difficulty label matches reality - play it and be honest.

7. The automated smoke test

Several of those checks are automated. py _src/build.py --smoke writes _smoke.html to the project root with every game's real configuration injected. Opening it drives each game headlessly for five minutes of simulated time with a tracking paddle, then reports per game whether the engine constructed, whether bricks were destroyed, how many levels cleared, whether the ball ever left the playfield, and whether any JavaScript error was thrown.

# terminal 1
py _m http.server 8000

# terminal 2 - any Chromium browser works
chrome --headless=new --virtual-time-budget=40000 --dump-dom http://localhost:8000/_smoke.html

Or simply open http://localhost:8000/_smoke.html in a normal browser and read the output. A healthy line looks like:

arcade-breakout: PASS frames=18000 state=running score=1780 levelClears=0
                 bricksStart=65 bricksLeft=2 escaped=0

_smoke.html is disallowed in robots.txt and does not need to be uploaded. It is regenerated whenever you pass --smoke, so it always tests the current configurations rather than a stale copy.