---
game: madzi
name: Madzi — Guardians of the Flow
file: madzi_v1.html
subject: Science
grades: 3-7
languages: en, bem, nya, ton, loz
score-format: stars
content-version: 1.0.0
source-file: madzi_v1.html
source-hash: 1c29bf4ca96064a8
---

# Madzi — Guardians of the Flow · Curriculum Map

A physics-driven water conservation puzzle game. Learners carve channels through
terrain to guide simulated water past evaporation, leaks and contaminants into tanks,
collecting Drop Gems — then answer a conservation quiz after each level. Every level
teaches one Zambia-specific water fact.

## Learning Objectives

- Explain where clean water comes from and why springs and watersheds must be
  protected from deforestation and soil erosion.
- Describe rainwater harvesting and storage, including how evaporation causes loss.
- Identify how leaks, poor maintenance and inefficient irrigation waste water, and
  name ways to prevent it.
- Distinguish clean from contaminated water and describe natural filtration
  (sand/charcoal).
- Discuss fair sharing of river water between communities and the effects of drought
  and rationing on daily life (including water-collection distances).
- Predict water flow through terrain (gravity, blocking, channelling) — applied
  physical science reasoning.

## Curriculum Alignment

| Game content | Zambian learning area | Notes |
|---|---|---|
| Chapters 1-2 (sources, harvesting) | Integrated Science — water sources & the water cycle | [VERIFY: CDC syllabus topic codes] |
| Chapter 3 (leaks & efficiency) | Integrated Science / Home Economics — conservation practice | [VERIFY: CDC syllabus topic codes] |
| Chapter 4 (contamination & filtration) | Integrated Science — safe water & health | Links to hygiene/health topics |
| Chapters 5-6 (sharing, drought) | Social Studies — resources, community & environment | Cross-subject |
| Flow simulation gameplay | Science process skills — prediction & testing | Cellular-automaton water physics |

## Unit Map

| Unit | Title | Focus | Content | Assessment |
|---|---|---|---|---|
| Chapter 1 | The Source | Protecting springs and watersheds from deforestation and soil erosion | 5 levels with terrain-carving water puzzles + 5 Zambia-specific facts; generous sand budget teaches the digging/runoff basics | 6 quiz questions (levels 1.1-1.5); star ratings per level |
| Chapter 2 | Harvest & Store | Rainwater harvesting; preventing evaporation loss | 5 levels + 5 facts; exposed water visibly steams away (live Evap % stat) — covered tunnels and tank roofs (L3+) prevent loss | 5 quiz questions; star ratings |
| Chapter 3 | Every Drop Counts | Plugging leaks, tank maintenance, irrigation efficiency | 5 levels + 5 facts; leak-hole fields destroy water on contact (third field from L4) | 5 quiz questions; star ratings |
| Chapter 4 | Clean or Contaminated | Pollution avoidance; natural sand/charcoal filtration | 5 levels + 5 facts; buried ooze pockets + surface pools taint water on contact; the golden filter band purifies dirtied flow | 5 quiz questions; star ratings |
| Chapter 5 | Sharing the River | Equitable distribution of water downstream | 5 levels + 5 facts; the spring feeds both sides of a dividing ridge — BOTH villages' tanks must fill | 5 quiz questions; star ratings |
| Chapter 6 | The Long Walk | Drought, rationing and reducing water-collection distances | 5 levels + 5 facts; countdown timer (70-50s) + evaporation + leaks + contamination + the tightest sand budgets | 5 quiz questions; star ratings |

## Content Inventory

- **6 chapters × 5 levels = 30 levels** of grid-based liquid simulation puzzles —
  every level verified winnable by automated route solvers.
- **30 conservation facts** (one per level, Zambia-specific — e.g. Zambia shares major
  river basins with eight neighbouring countries).
- **31 multiple-choice quiz questions** (3 options + explanation each; level 1.1 has
  two, every other level one).
- **Real hazard physics per chapter:** exposed water evaporates under the sun
  (Chapters 2/6 — covered tunnels and tank roofs prevent it); leak holes destroy
  water on contact (Chapters 3/6); green contamination ooze TAINTS clean water on
  contact and lurks in buried soil pockets plus surface pools (Chapters 4/6 — the
  near-full-width golden filter band purifies dirtied flow); twin vessels with a
  dividing ridge force genuine flow-splitting (Chapter 5); a countdown drought
  timer (70-50s) stacks every hazard at once (Chapter 6).
- **Sand budget:** digging spends limited "sand credits" (scaled to route distance,
  tightening chapter by chapter) — route planning is the core strategic skill.
- **Deep runoff void:** water that misses the tanks drains away below them and
  counts as waste — careless pours are punished, and tank funnels with raised
  rims catch imperfect pours.
- Fail/retry flow with out-of-water detection, polluted-water fail, timer fail,
  vessel fill gauges, Drop Gem collectibles (gem spots are guaranteed reachable)
  and an out-of-sand warning.

## Assessment & Analytics

- Events emitted: `game_open`, `puzzle_start`, `puzzle_fail`, `level_complete`,
  `quiz_correct`, `quiz_wrong` — ALL self-declaring `subject: 'Science'` (Madzi's
  subject signal comes from the game itself). `level_complete` carries
  `wastePct` (ALL water that never reached the tank: leaks + runoff +
  evaporation), `evapPct`, `contamPct`, `sandLeft`, `gems` and `timeSec`.
- Score format: `stars` — 2★ requires total losses ≤35% and contamination ≤12%;
  3★ requires all gems, losses ≤20% and contamination ≤6%.
- Teacher dashboard: quiz accuracy tracks conservation knowledge; `puzzle_fail`
  counts show which physics puzzles frustrate learners (consider live demonstration
  for high-fail levels).

## AI & Accessibility Features

- No AI chat or AI level generation in this game — the "Gogo says" speech bubbles are
  scripted teaching text, fully offline.
- Full UI translation: English, Bemba, Nyanja, Tonga, Lozi (fail-to-English).
- Progress note: level progress is stored on the device (localStorage) — learners
  should use the same device across lessons.

## Lesson Planning Notes

- One chapter per lesson works well: ~5 minutes per level plus the quiz and a class
  talk about the chapter's facts (25-35 minutes of gameplay in a 40-minute period).
- Before play, demonstrate the chapter's hazard on the board (e.g. draw a leaking
  tank for Chapter 3) and ask learners to predict what the water will do.
- After play, re-read the five chapter facts aloud — they are the factual takeaway of
  the lesson and connect directly to the quiz questions.
- Practical extension: Chapter 4 pairs naturally with a real sand/charcoal filter
  demonstration; Chapter 6 with a discussion of learners' own water-collection
  routines.
- Differentiation: levels within a chapter escalate — struggling learners can master
  levels 1-3 while faster learners chase 3-star ratings on all five.

## Change Log

| Date | Game Version | Change | Curriculum Impact |
|---|---|---|---|
| 2026-08-10 | madzi_v1.html | Gameplay overhaul — the claimed hazards are REAL now: evaporation never actually removed water (two compounding bugs: the bedrock border row made the sky-exposure check never fire, and the evaporated amount was subtracted from a local copy but never written back to the grid) — fixed, tuned (~1.3%/s on the fully exposed lake), with visible steam, a live Evap % HUD stat and covered-route strategy; contamination is a real threat — ooze taints clean water on CONTACT (2%/tick transfer), spawns in buried soil pockets along the routing band (released when dug into) and surface pools beside the spring, with the filter band widened to catch every descent route; NEW sand budget (dig credits scaled to route distance, tightening per chapter, live HUD + out-of-sand warning + red brush) makes route planning the core skill; NEW deep-runoff void under the vessels (missed water drains away as waste, rendered as a darkening cavern); vessels gained funnel rims + partial lids (mouth-offset per seed, from C2); C5 rebuilt so the spring sits ON the dividing ridge (the lake pre-splits — both tanks genuinely need their own routes) with wider twin vessels; C6 timers rebalanced 45-33s → 70-50s; win requires the fill to HOLD ~0.75s (no splash flicker wins); stars judge TOTAL losses (leaks+runoff+evaporation ≤35%/20%) + contamination (≤12%/6%); per-chapter Gogo intros teach each hazard; gem spots are guaranteed reachable (previously a seeded leak row could land on a gem making 3★ silently impossible); all 30 levels re-verified winnable by automated solvers (28 by a greedy bot, 2 by scripted expert routes) | Unit Map content column updated per chapter (hazard descriptions now match real mechanics); Content Inventory documents the sand budget, runoff void, funnels and hazard physics; analytics gained evapPct/sandLeft and wastePct now means ALL losses; star thresholds changed — teachers comparing star data across versions should note the new bands |
| 2026-08-09 | madzi_v1.html | Stability tuning for fail/win logic: impossible-state detection now requires consecutive checks and accounts for recoverable ooze-through-filter potential; star bands now also gate on contamination quality thresholds | No chapter/level inventory change; reduces false fail states and aligns star awards more closely with clean-water outcomes |
| 2026-08-05 | (no game change) | Hash restamped: source-hash now computed over LF-normalized game HTML so stamps match on Windows and Linux/CI alike (v10.27.1 fix) | None - game content unchanged, documents remain valid |
| 2026-08-05 | madzi_v1.html | Initial curriculum map authored (platform standard adoption, v10.25.0) | Baseline — 6 chapters, 30 levels, 30 facts, 31 quiz questions documented |
