# Turtle Workshop: Guide the Turtle! 🐢

A two-part kids' coding workshop using Python's built-in `turtle` module.
No extra installs are strictly required except **Pillow** (`pip install pillow`),
which is only needed for Lesson 2's collision detection.

**Files included:**
| File | Purpose |
|---|---|
| `path_background.png` | Background image for Lesson 1 |
| `maze_background.png` | Background image for Lesson 2 |
| `lesson1_starter.py` | Fill-in-the-blank movement exercise (hand to kids) |
| `lesson1_solution.py` | Full solution + bonus arrow-key mode (for you) |
| `lesson2_race_game.py` | Full two-player race game (hand to kids, or live-code it together) |
| `gen_path_bg.py` / `gen_maze_bg.py` | Scripts that generated the two images (re-run to remix a new maze — see "Remixing" below) |

**Setup note:** all `.py` files assume the matching `.png` is in the *same folder*.
Keep them together when you hand out files.

---

## Lesson 1 — Movement (≈30–40 min)

**Concept goals:** `forward()`, `left()`, `right()`, coordinates, headings.

1. **Show the image first, no code.** Open `path_background.png`. Ask: "If you
   were the turtle standing on the green flag, which way would you have to
   walk, and when would you need to turn?" Get kids describing the path in
   plain language (up, right, up, right...) before touching Python.
2. **Introduce the turtle's "home" facing.** A turtle always starts facing
   **east** (heading 0°). `left(90)` and `right(90)` rotate it a quarter turn.
   A good physical warm-up: have kids stand up and physically turn
   left/right 90° themselves before coding it.
3. **Hand out `lesson1_starter.py`.** It already has segment 1 filled in as
   an example. Kids fill in the `???` blanks with the right `forward()`
   distances. Encourage guessing + running + adjusting — that trial-and-error
   loop *is* the lesson.
4. **Success check is built in:** the script prints how far the turtle
   ended up from the finish flag, so kids get instant feedback without you
   checking every screen.
5. **Early finishers:** open `lesson1_solution.py` and uncomment the "Part B"
   bonus block to let them drive the turtle freely with the arrow keys —
   this is a natural teaser for Lesson 2.

**Common bugs to watch for:**
- Forgetting that `right(90)`/`left(90)` must come *before* the next
  `forward()`, not after.
- Off-by-a-bit distances — remind them the goal is "close enough" (the
  checker allows 20px of slack), not pixel-perfect.
- Typos like `t.forward(200` (missing parenthesis) — a great moment to
  teach reading Python error messages.

**Discussion prompt to close:** "What would happen if we turned `right(90)`
twice instead of once?" (Great segue into experimentation.)

---

## Lesson 2 — Keyboard Input & Collision (≈40–50 min)

**Concept goals:** `screen.listen()` + `onkeypress()` for input, and a simple,
very visual technique for collision detection (checking pixel color).

1. **Reframe the image as a game board.** Show `maze_background.png`. Point
   out the **blue dot** (Player 1 start, bottom-left), **red dot** (Player 2
   start, bottom-right) and **gold checkered square** (finish, top-center).
   Ask: "How many different routes can you see from blue to gold?" — this
   sets up the idea that a maze can have *multiple valid paths*, not just one.
2. **Teach keyboard input first, in isolation.** Before running the full
   game, live-code a 5-line mini demo: a single turtle that moves with just
   the arrow keys, no walls, no maze. This isolates the new concept
   (`screen.listen()`, `screen.onkeypress(function, "Up")`) from everything
   else.
   ```python
   import turtle
   screen = turtle.Screen()
   t = turtle.Turtle()
   screen.listen()
   screen.onkeypress(lambda: t.forward(15), "Up")
   screen.onkeypress(lambda: t.right(15), "Right")
   screen.mainloop()
   ```
3. **Now introduce collision.** Ask kids: "How would the computer *know* it
   hit a wall?" Let them guess (a great discussion) before revealing the
   trick used in `lesson2_race_game.py`: we load the *same background image*
   with the Pillow library and check the color of the pixel exactly where
   the turtle is about to move. Dark pixel = wall = crash.
4. **Run `lesson2_race_game.py` as a class.** Pair kids up: one on arrow
   keys, one on WASD, same keyboard. First to the gold square wins; touching
   a wall crashes you out.
5. **Extend it (great group challenge):** once the base game works, have
   kids suggest and add features, e.g.:
   - A countdown ("3, 2, 1, GO!") before movement is allowed.
   - A move counter or timer shown on screen.
   - Detecting if the two players' turtles touch each other (tie-breaker
     rule of your choice).
   - Changing `STEP` to make the race faster/slower.

**Common bugs to watch for:**
- Forgetting `screen.listen()` — keys won't register at all without it.
- `FileNotFoundError` on `maze_background.png` — the script must run from
  the folder containing the image (or you must give it a full path).
- `ModuleNotFoundError: No module named 'PIL'` — install with
  `pip install pillow` (mention this once at the start of the session so
  no one gets stuck mid-lesson).
- Two turtles moving at exactly the same key press can look like the game
  froze — reassure them it's just Python processing input quickly, not a
  crash.

**Discussion prompt to close:** "Why did we check the *pixel color* instead
of, say, writing down the coordinates of every wall by hand?" (Leads nicely
into talking about how games generally need reusable, general-purpose rules
rather than one-off special cases.)

---

## Remixing the maze for a repeat workshop

Re-run `gen_maze_bg.py` with a different `random.seed(...)` value near the
top of the file to generate a brand-new maze layout in seconds — handy if
you're running this workshop multiple times and want each group to have a
fresh challenge. The game code doesn't need to change at all, since it
reads wall positions straight from the image.

## Suggested full session timing (≈90 min total)
| Time | Activity |
|---|---|
| 0:00–0:10 | Intro: what is `turtle`, show finished race game as a demo/hook |
| 0:10–0:45 | Lesson 1: movement exercise |
| 0:45–0:55 | Break / early-finisher bonus mode |
| 0:55–1:05 | Mini keyboard-input demo (live-coded) |
| 1:05–1:30 | Lesson 2: full race game + play-testing in pairs |
| 1:30–1:40 | Wrap-up: brainstorm extensions, show remixed maze idea |