# ROVER — guide for AI assistants

> A browser game where kids write their **first real Python** to drive a Mars rover through 8 missions / 32 levels. No install — Python runs in the browser. Aimed at roughly ages 9–14 (upper-primary to early-secondary), absolute beginners. Bilingual: English at rover.tobiasbuilds.com, Dutch at marsrover.tobiasbuilds.com.

## What this is

ROVER is a learn-to-code platform disguised as a space mission. The child is in
mission control, 225 million km from a rover on Mars. The story carries the
core idea: a radio signal takes **14 minutes** to reach the rover, so you can't
steer live with arrow keys — you must **write the whole plan in advance and send
it in one go**. That plan *is* a program. This justifies, from second one, why
we write code instead of pressing buttons.

The child types Python into a code editor, presses **SEND** (Dutch: VERSTUUR),
and watches the rover replay exactly what their program did on a grid. Real
Python runs via **Pyodide** (CPython compiled to WebAssembly) in a background
worker — so syntax errors, indentation rules, and infinite loops behave like
real Python, not a toy.

This is genuinely the child's first programming. Treat it that way: small wins,
lots of encouragement, and never assume prior knowledge of variables, loops, or
functions until the mission that introduces them.

## For the assistant: how to help

- **Mirror the game's own pedagogy: predict → send → see what happened.** Before
  giving any hint, ask the child what they *think* the rover will do, or what it
  *did* do versus what they wanted. The whole game is built on tracing a plan on
  paper before sending it. Lean into that.
- **Hints, not solutions.** Never write the finished program for a level. Give
  the smallest next nudge (see the graded ladder below). Finishing it for them
  steals the "aha" the level was designed to produce.
- **Point them at in-game help first.** Each level has a **lesson panel** (the
  story + the new command, with worked snippets), a **"Hint needed?"** expander,
  and a **command palette on the right** listing exactly which commands are
  available on this level. Most stuck kids haven't re-read the lesson or noticed
  a command isn't unlocked yet. Send them there before you explain.
- **Stay age-appropriate and warm.** Short sentences. One idea at a time. Errors
  are normal and even celebrated ("On Mars nobody dies from a bug — just send a
  new plan"). Never make a child feel slow.
- **Honor the "pain before the cure" design.** Early levels *deliberately* make
  the child type `move()` many times so the for-loop feels like relief later. If
  a child on Mission 1–3 asks "isn't there a shorter way?", don't hand them loops
  early — affirm the instinct ("great observation — that shortcut is coming very
  soon!") and let the curriculum deliver it.
- **Don't fight the anti-hardcoding design.** Many levels change the terrain
  every run, and the third star runs the child's code on **3 unseen layouts**.
  If a child hardcodes a fixed number of steps and it "sometimes works," that's
  the lesson landing — guide them toward a sensor/loop, not a bigger number.

## How it works

**Controls / loop**
- Type Python in the editor (CodeMirror, with Python syntax highlighting).
- **SEND ▸** runs the program (keyboard: **Ctrl/Cmd + Enter**). Button shows
  "SIGNAL ON ITS WAY…" while running.
- **RESET** restores the level's starter code.
- The world is simulated first (in Python), then the rover's actions are
  **animated as a replay** — so the child sees the run unfold step by step.

**Goal of a level:** collect any required samples and finish on a **base
platform** (when the level has one). A run is only "complete" if there's no
error, the required samples are collected, *and* the rover ends on the base.

**The rover commands** (each available only once its mission unlocks it; the
right-hand palette shows the current set):

| Command | What it does |
|---|---|
| `move()` | drive one square forward, in the facing direction |
| `turn_left()` / `turn_right()` | rotate 90° in place (does not move) |
| `collect()` | pick up a sample on the current square |
| `place()` | drop a carried sample; on a sensor pad this opens its airlock door |
| `say(...)` / `print(...)` | make the rover "speak" (print is aliased to say) |

**Sensors** (return `True`/`False`, used with `if` / `while` / `not`):

| Sensor | True when… |
|---|---|
| `front_is_clear()` | the square ahead is **not** a wall, rock, edge, or closed door |
| `cliff_ahead()` | the square ahead is a **crevasse** (a chasm) |
| `on_sample()` | a sample is on the current square |
| `at_base()` | the rover is standing on a base platform |
| `carrying()` | how many samples the rover holds (a number) |
| `facing_north()` / `_east()` / `_south()` / `_west()` | the rover faces that way |

**Important blind spot (this is intentional and is a whole lesson):**
`front_is_clear()` sees rocks, walls and edges but **NOT crevasses**. A rover
can roll straight into a chasm while `front_is_clear()` says `True`. Cliffs are
detected only by `cliff_ahead()`. Mission 6 teaches this the hard way.

**Stars (up to 3 per level):**
1. ★ **Completed** — solved the mission.
2. ★ **Compact** — solved in **at most `par` lines** of code. This rewards loops
   and functions; it cannot be earned by hardcoding many steps.
3. ★ **Robust** *or* **Flawless** — on levels with random/variant terrain, the
   code must also solve **3 unseen layouts** (auto-tested headlessly). On fixed
   levels there's nothing random to test, so this star is **Flawless**: cleared
   on the **first attempt** (rewards tracing on paper before sending).

Progress and stars are saved in `localStorage`. Levels unlock **linearly** — you
must finish a level to open the next.

**Infinite-loop safety:** a real infinite loop without rover commands (e.g.
`while True: pass`) is caught by a watchdog (~15 s) that restarts the engine and
explains what happened. A loop that *does* move is capped at **5000 steps**.

## The 8 missions (the learning arc)

The order is the whole point — each concept arrives only after the child has
*felt the problem it solves* ("pain before the cure"), and "counted before
tested" (`for range()` before `while`).

| # | Mission | New concept |
|---|---|---|
| M1 | Contact | **Sequence**; `move()`; a program is a plan sent ahead of time |
| M2 | Heading | `turn_left()` / `turn_right()`; tracing the rover's facing with your finger |
| M3 | Samples | `collect()`, `place()`; sensor pads & airlock doors |
| M4 | Patterns | **`for i in range(n)`**; indentation as meaning (after typing `move()` 12 times) |
| M5 | Sensors | **`while`**, `not`, `front_is_clear()`, `at_base()` (distance changes per run) |
| M6 | Decisions | **`if/else`**, `on_sample()`, `cliff_ahead()` (the crevasse blind-spot lesson) |
| M7 | Own commands | **`def`** — functions, then functions **with a parameter** `def name(n):` |
| M8 | Expedition | **Algorithms** — the right-hand rule on mazes regenerated every run |

The climax (M8-1) is five lines that solve *any* maze:

```python
while not at_base():
    turn_right()
    while not front_is_clear():
        turn_left()
    move()
```

The child can't memorize a route because the maze is rebuilt each run — so one
*general* algorithm beats any specific plan. That's the payoff of the whole game.

## What it teaches

The real computer-science concepts, embedded in the mechanics rather than
lectured:

- **A program is a plan.** Precise, ordered steps executed by a machine that
  does exactly what you said — not what you meant. The 14-minute signal delay
  makes "you can't fix it live" concrete.
- **Sequence & state.** `turn_left()` doesn't move; the rover has a *facing*
  that previous commands changed. Kids must track state in their head — the
  classic beginner hurdle of "the robot turned, so now 'forward' means a
  different direction."
- **Iteration, counted then conditional.** `for i in range(n)` = "do this n
  times" (you know the count). `while condition:` = "keep going until something
  is true" (you *don't* know the count — the storm moved the base). Introducing
  counted loops first is deliberate: it's conceptually simpler.
- **Indentation is syntax, not decoration.** Python decides what's *inside* a
  loop/if/function by 4-space indentation. The game makes this physical: an
  un-indented line happens *after* the loop.
- **Boolean logic & sensors.** `True`/`False`, and `not` to flip them. Sensing
  the world instead of assuming it.
- **Conditionals.** `if/else` to branch on what the rover senses *right now*
  ("if there's a sample here, collect it").
- **Abstraction with functions.** `def` to name a sequence, then **parameters**
  to make one function do a family of tasks (`def forward(n):`).
- **Algorithmic thinking.** A fixed procedure that solves *every* instance of a
  problem (right-hand maze rule) — and why generalizing beats memorizing.
- **Generalization vs. hardcoding** is rewarded directly by the star system:
  compact code and unseen-layout robustness both punish "just type the answer."

**Python the child actually meets, accurately:** function calls with `()`,
`range()`, the `:` that opens a block, indentation, `for`, `while`, `if`/`else`,
`not`, `def` with and without parameters, and friendly versions of real
exceptions (`NameError`, `SyntaxError`, `IndentationError`, `TypeError`,
`ZeroDivisionError`, `RecursionError`).

## Common stuck points → how to nudge

The engine already translates Python errors into friendly language with a tip;
your job is to coach *around* that message, Socratically. A graded ladder:

**"It says the rover doesn't know `<word>`" (NameError)**
- L1: "Python is fussy about spelling. Compare your word letter-by-letter with
  the command panel on the right." (The game even suggests "did you mean
  'move'?" via close-match.)
- L2: "Is that command unlocked on this level? Only the ones in the panel work."
- L3: Point to the exact typo (`mvoe` → `move`) without rewriting their line.

**"Python doesn't understand line N" (SyntaxError)**
- L1: "Lines that start a block — `for`, `while`, `if`, `else`, `def` — need
  something at the very end. What is it?" (the colon `:`)
- L2: "Count your brackets `(` and `)` on that line — do they match?"

**Indentation error**
- L1: "Everything that belongs *inside* the loop must line up — 4 spaces in.
  Which lines should run each time through the loop?"
- L2: "Look at your last line — should it happen *inside* the loop, or once
  *after* it? Its indentation decides."

**"BUMP! The rover hit a rock / the edge / a closed door"**
- L1: "Before each `move()`, which way is the rover facing? Trace it with your
  finger from the start." (Facing-tracking is *the* M2 skill.)
- L2: "After a `turn_left()`, 'forward' points a new way. Walk through it square
  by square."

**Rover fell into a crevasse**
- This is the M6 blind-spot lesson. "`front_is_clear()` can't see chasms — only
  rocks and walls. Which sensor finds a cliff?" (`cliff_ahead()`). Don't spoil
  the `if` structure; let them connect "check before stepping."

**"It worked once, then failed on the next run"**
- The terrain changed. "You used a fixed number of steps — but the distance
  changes every run. What could the rover *check* instead of counting?" Steer
  toward `while not at_base():` / sensors, never toward a bigger fixed number.

**"It says my function calls itself forever" / loop never stops**
- "A `while` only stops when its condition becomes `False`. In your loop, does
  anything ever make `not ...()` false? What has to happen each time round?"

**Can't get the 2nd/3rd star**
- Compact: "You solved it — now, what repeats? Could a loop or a function say it
  in fewer than `<par>` lines?" Robust/Flawless: explain *why* it exists (proves
  the code is a real general solution), not how to game it.

**"This is so much typing" (Missions 1–3)**
- Affirm it, don't shortcut it: "You found the exact reason loops exist — and
  Mission 4 hands you the magic word. You're going to love it." That frustration
  is the setup for the for-loop payoff.

## What NOT to do

- **Don't write the level's solution.** Especially not the M8 maze algorithm,
  the M5 `while` line, or any `for`/`if` structure — those are the payoffs.
- **Don't introduce concepts ahead of their mission.** No loops in M1–M3, no
  `while` before M5, no `def` before M7. Meeting a concept *after* feeling its
  absence is the entire design.
- **Don't hand out a fixed step count for random levels.** It defeats the lesson
  and won't earn the robust star.
- **Don't teach Python the game doesn't use yet** (lists, variables, f-strings,
  imports). Keep to the commands and structures actually unlocked.
- **Don't dismiss errors or rush.** Crashes are part of the fun here. Slow down,
  trace, predict, send again.
- **Don't replace the in-game lesson/hint.** Nudge the child back to the lesson
  panel and the "Hint needed?" expander; they learn more by re-reading than by
  being told.

## Links

- Play (English): https://rover.tobiasbuilds.com
- Play (Nederlands): https://marsrover.tobiasbuilds.com
- In-game help: every level has a **lesson panel** (story + new command + worked
  examples), a **"Hint needed?"** expander, and a **command palette** showing
  which commands are available right now. Friendly, translated error messages
  appear under the editor on every failed run.