Skip to content

Add the daily games: System Design Runner, Linux Command Explorer, Docker Commands - #246

Open
AQIB-NAWAB wants to merge 2 commits into
mainfrom
feat/daily-games
Open

AQIB-NAWAB wants to merge 2 commits into
mainfrom
feat/daily-games

Conversation

@AQIB-NAWAB

Copy link
Copy Markdown
Collaborator

Three playable browser games in /puzzles, three rounds each (easy, medium, hard), new every day and the same for everyone. A round solved for the first time that day earns 3 XP, and finishing all three rounds of one game earns 2 more. The most the games give is 33 XP a day. A visitor can play without an account and is asked to sign in to save stars and earn XP.

The games

  • System Design Runner (12 scenarios). A production incident on a small AWS-style system: a tripled bill, an oversized fleet, a database crushed by a flash sale, a lost zone, a NAT gateway line that explodes, a hot key. Pick a limited number of changes (each shows its cost), press Run, and watch a 24-hour traffic simulation with animated packets, cost and latency meters against goals. Each scenario has a trap. Prices are illustrative and labelled so.
  • Linux Command Explorer (14 missions). A terminal quest on a made-up server with a shell of about 45 commands, pipes, redirects, globs, permissions and realistic errors: find a hidden file, count failed logins, kill a runaway process, fix permissions, find what fills the disk, chain grep | sort | uniq -c, find a leaked key, restore a file from backup. Live objective checklist, par, hints.
  • Docker Commands (16 scenarios, two modes). Fix mode: a terminal plus a live dock view of containers, ports, networks and volumes (missing env var, wrong port, port clash, lost data without a volume, no network, OOM restart loop, free disk, compose). Build mode: assemble a Dockerfile from pieces (drag, tap or keyboard) or fill a compose file, then watch layers stack, cache hits and the container start. Every day has at least one of each mode.

Sound effects (made with Web Audio, no files), stars, confetti, shake on a miss, an XP chip, and a mute switch. Sound is off and decorative motion is reduced when the system asks for reduced motion.

How it is built

  • A game is a pure, deterministic engine in server/src/shared/games/<game>/ implementing GameEngine (roundsFor(dayKey), parseSubmission, verify). The browser plays with it for instant feedback, and the server replays the submission with the same engine before it records the round or pays XP, so a client cannot claim a win. Details and how to add a game: docs/17-daily-games.mdx.
  • New GamePlay table (migration 20261118120000_game_plays), XP sources game_round and game_set, and /api/v1/games: GET /daily (open to visitors) and POST /:game/rounds/:index/submit (signed in, rate limited, size limited).
  • XP is awarded with the existing awardXp once per key (game_round:<day>:<game>:<round>, game_set:<day>:<game>), with a daily cap as a backstop. The day is the learner's local day. Replays are free practice.
  • /puzzles shows today's three games with progress, XP earned and a countdown. It replaces the coming soon page.

Tests and checks

  • Server: 623 tests pass, including 240 in tests/unit/shared/games (every scenario's stated solution passes, wrong or empty submissions fail, a trap is real, parsing rejects junk, verify never throws, rotation is deterministic and varies by day) and tests/api/games.test.ts (visitor view, auth, bad game or round, unsolved pays nothing, XP paid once, best stars kept, set bonus once).
  • Frontend: 4,872 tests pass. Type checks clean in both. sync-shared:check clean. Lint: 0 errors in the new code (5 warnings in the Docker build component).
  • Played end to end in Chrome as a learner (rounds solved, stars and XP saved, hub updated). Desktop and 390 px looked at for all three games.

Not done, and things to decide

  • Not heard or tested: the sound effects were wired and checked in code but not listened to. Reduced motion, Tab completion and arrow-key history in the terminal, touch drag in the Docker builder, and the compose build round were only partly checked in a browser. Only some missions were played by hand; every scenario is solved by its stated solution in the unit tests.
  • Streak: solving a game does not count as an active day for the streak (the streak reads study time). Decide if it should.
  • Hints: in System Design Runner hints are free. The Linux and Docker games count hints toward stars.
  • XP numbers are in server/src/shared/gamification/xp.ts (3 and 2). No leaderboard yet.
  • Mascot XP toast: the games show their own "+3 XP" chip. They do not use the mascot reaction (that needs a new engagement event type).
  • Deploy: runs prisma migrate deploy for the new table. GAMIFICATION_XP must be on for XP to be paid.

…cker Commands

Three browser games in /puzzles, three rounds each (easy, medium, hard), new
every day and the same for everyone. Each round a learner solves for the
first time that day earns 3 XP, and finishing all three rounds of one game
earns 2 more (33 XP a day at most). A visitor can play without an account.

Framework:
- shared/games: the GameEngine contract, deterministic daily rotation, and
  one pure engine per game. The browser plays with the engine for instant
  feedback, and the server replays the submission with the same engine
  before it records the round or pays XP.
- GamePlay table (migration), game_round and game_set XP sources, a
  /api/v1/games API (daily set, submit a round), unit and API tests.
- Shell: round tabs, result with stars, XP chip and confetti, a mute switch,
  synthesized sound effects, and a terminal component for the command games.

Games:
- System Design Runner: 12 AWS incident scenarios (cost, right-sizing,
  latency, outages, hot keys). Pick a limited set of changes and run a
  24-hour traffic simulation against latency, availability and cost goals.
- Linux Command Explorer: 14 terminal missions on a made-up server with a
  shell of about 45 commands, pipes, redirects and permissions.
- Docker Commands: 16 scenarios in two modes, a fix-the-container terminal
  with a live dock view and a visual Dockerfile and compose builder.

/puzzles now lists the games instead of the coming soon page.
…the lab board

The three daily games now share GameFrame, which copies the lab board's
look: a dark header bar with the level and actions, three plain steps, the
brief, and a checks list with Wait and Pass badges. The /puzzles hub has a
how-it-works strip and flat cards with one Start button each.

System Design Runner is now six real incident labs (two per difficulty, with
a broken starting board, checks and a reference solution) played on the
platform's own HldBoard. The lab model (catalog, types, tiered model,
challenge) moved to server/src/shared/lab/engine so the server replays a
submitted board with runChallenge before it records the round or pays XP.
The old paths in packages/learning-ui re-export it, so existing labs are
unchanged. HldBoard gets an optional onRunComplete callback.

Linux Command Explorer and Docker Commands are redesigned around GameFrame:
a dark terminal, a clear first command, a checks list, one primary action,
and a mobile layout. Decorative stars, glow and ship art are removed.
@AQIB-NAWAB

Copy link
Copy Markdown
Collaborator Author

Update after review: the games looked generic and hard to use, and the System Design Runner was a custom board instead of the platform lab. This push changes that.

  • System Design Runner now plays on the real lab board (HldBoard, Run tests, results, reference solution) with 6 incident specs, two per difficulty. The lab model moved to server/src/shared/lab/engine/ so the server replays a submitted board with runChallenge; the old paths in packages/learning-ui/src/labs re-export it. HldBoard gets an optional onRunComplete. Existing labs are unchanged (all 4,872 frontend tests pass).
  • Shared GameFrame copies the lab look: dark header bar with level and actions, three plain steps, the brief, and a Wait and Pass checks list. Linux and Docker are redesigned around it, with a clear first command, a dark terminal, one primary action and a mobile layout. The hub has a how-it-works strip and one Start button per game.
  • Checks: server 560 tests, frontend 4,872, type checks and lint clean.
  • Known: the round data sent to the browser includes the lab's reference solution (the lab already offers it after the first run). The desktop app was not built or tested.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant