Sep 26, 2026 · @Amin Uddin

ML Quest is a free, open-source browser game where players learn machine learning by training real models to beat levels. Every level is a puzzle: the player tweaks data, parameters or architecture, watches the model learn live, and passes only when the model hits a target.

• Core promise: you cannot pass a level by clicking through text. You pass by making a model work.
• Deployment: static site on GitHub Pages, no backend, no login, no cost to play.
• License: MIT for code, CC BY 4.0 for level content.
• Working name: ML Quest (placeholder, to be finalized).

The v1 goal is a player finishing World 1 who can explain loss, gradient descent and overfitting in their own words.

Goals

• Teach core ML intuition through hands-on play, not reading.
• Make every level passable only through correct interaction with a model.
• Run fully in the browser on a mid-range laptop or phone.
• Be easy for contributors to add new levels.

Non-goals (v1)

• No accounts, leaderboards server or paywall.
• No heavy math derivations or code-writing levels.
• No training of large models (no GPU requirement).

Success metrics

Metrics come from privacy-friendly analytics (e.g. Plausible or GoatCounter) with no personal data.

The primary player is a student or junior developer who knows basic programming but finds ML courses abstract.

Each level is a short loop: see the mission, interact with a live model, hit the target to pass, then get a debrief that names what you just learned.

Level loop

1. Mission card (10 sec read): a goal in game language, e.g. "Get the robot ball into the valley in under 30 steps."
2. Play: the player drags points, moves sliders, toggles layers or draws data. The model trains live and the visuals update every frame.
3. Check: the level evaluates a pass condition (accuracy, loss, steps, parameter count).
4. Result: pass → stars + debrief; fail → a hint and retry, with no penalty.
5. Debrief: 2–3 sentences mapping the game action to the real ML term, plus an optional "go deeper" card.

Pass and scoring rules

• 1 star: meet the pass condition.
• 2 stars: meet it efficiently (fewer steps, smaller model, less data).
• 3 stars: meet a bonus constraint, e.g. "also generalize to the hidden test set."
• Every level includes a hidden test set, so memorizing the training data never earns 3 stars. This teaches overfitting through the scoring itself.

Hints

• Three tiers: a nudge, a concept reminder, then a near-solution.
• Hints unlock after a failed attempt or 60 seconds of no progress.
• Using hints never blocks passing, only caps stars at 2.

Progression

• Worlds unlock in order; levels inside a world unlock one by one.
• Each world ends with a boss level that combines every concept in that world.
• Stars unlock cosmetic rewards (robot skins, map themes) and sandbox tools.
• Progress saves locally in the browser, with export/import as a JSON code so players can move devices.

Game feel

• A small robot mascot ("the Learner") that visibly improves as the model trains.
• Instant feedback: loss curve, decision boundary and predictions animate live.
• Sound and particle effects on pass, toggleable.

The game has 6 worlds; v1 ships World 1 and World 2 fully (16 levels), the rest follow in later releases.

World 1: Valley of Loss (v1)

World 2: Boundary Plains (v1)

The rule is play first, name it after: players feel a concept through the level, then the debrief gives it its real name.

• Field notes: every level has optional notes, closed by default, for players who want to understand before or while they play: the idea, what the controls do, and how to read the result. They never give the answer (that's what hints are for), so reading them never costs stars, and "play first" stays the default path.
• Concept cards: after each pass, a card unlocks in the player's "ML Codex" with the term, a one-line definition, the level's key visual and an optional formula.
• Debrief questions: one optional multiple-choice question per level ("Why did a high learning rate make the ball bounce?"). Correct answers give a bonus gem, never block progress.
• Misconception traps: some levels are designed so the obvious move fails (e.g. maximizing training accuracy in The Overfitter), and the debrief explains why.
• Sandbox mode: unlocked after World 1. Free play with any dataset and every tool the player has unlocked, no pass condition. Useful for teachers doing live demos.
• Accessibility of ideas: no formulas are required to pass any level; math appears only in "go deeper" cards.

Non-functional

• First load under 3 seconds on a 4G connection; each level's model trains at 30+ fps on a mid-range phone.
• Works offline after first visit (PWA).
• No personal data collected; no cookies.

Everything runs client-side as a static build deployed to GitHub Pages by GitHub Actions on every push to main.

Level config shape (sketch)

{
  "id": "w1-l4",
  "title": "Too Fast, Too Slow",
  "dataset": "linear-noisy-50",
  "model": "linear-regression",
  "widgets": ["learning-rate-slider", "train-button"],
  "pass": { "metric": "epochs_to_converge", "max": 50 },
  "stars": { "two": { "max_epochs": 25 }, "three": { "test_mse_max": 3 } },
  "hints": ["...", "...", "..."],
  "debrief": "concept:learning-rate"
}

The project is free forever to play, with growth driven by community-contributed levels.

• Repo contents: README with a GIF of gameplay, CONTRIBUTING.md, a "Create a level" guide, code of conduct, issue templates for bugs and level proposals.
• Level contribution flow: propose via issue → build the config → the CI pass-bot checks the level is winnable → review → merge. Contributors are credited on the level's debrief card.
• Good first issues: new datasets, hint text, translations, cosmetic skins.
• Funding (optional, no paywall): GitHub Sponsors and a "Buy me a coffee" link on the credits screen.

The first public release (v1, World 1 and 2) is planned about 10 weeks after starting, assuming one developer part-time.

Open questions

• Final name and visual style (pixel art vs clean flat illustration)?
• Should World 1 require any account or stay fully anonymous?
• Is Hindi UI a v1 or v2 priority?