C Systems Lab Wiki

Game Boy Emulator — Curriculum Decision

4 min read

Game Boy Emulator — Curriculum Decision

Decision status: Option A implemented — PDF-exclusive ch12, complete as of 2026-04-12

Background

In April 2026, while redesigning the roadmap page, a personal tag (“3DS RetroAchievements plugin”) was replaced with “Game Boy emulator (CPU + memory map)” as an aspirational destination. This prompted a structured analysis of whether to build it as guided content and where.

Why the DMG emulator fits this curriculum

The original Game Boy (DMG, 1989) is widely considered the best introductory emulation project. Scope is bounded (~2,000 lines of C to boot Tetris). Test infrastructure exists (Blargg’s test ROMs). Pan Docs are the definitive free reference. It touches every major skill taught in the course:

Course areaEmulator connection
Types + operators8-bit register file, flag bits (Z/N/H/C), masking, rotation opcodes
PointersMemory bus dispatch; register file as a pointer-indexed array
StructsCPU state (registers, PC, SP, IME) and PPU state as packed structs
File I/OLoading a ROM file, validating the cartridge header checksums
Function pointers256-entry opcode dispatch table — Module 4 applied directly
Going below CReal ISA, cycle timing, reading disassembly, Godbolt analysis

Options considered

Option A: PDF-exclusive ch12 ← Chosen

Add ch12 to the Companion PDF only. Roadmap callout gets a “Companion PDF” badge. No new web module.

Pros: Strongest upsell argument in the product family; no web authoring overhead (~3–4× less work than Option B); fits the PDF’s “goes deeper” positioning; paywall is visible and labeled (not a bait-and-switch).

Cons: No discoverability from free course unless roadmap callout works; mild break from the 11-chapter pattern (ch12 has no web counterpart).

Option B: Full web module (Module 11) + PDF ch12

Rejected. 3–4× more authoring work; weakens PDF’s exclusive-content angle; requires updating all “10 modules” references throughout the web app; reopens a complete, shipped product.

Option C: Both simultaneously

Rejected. Doubles effort, eliminates PDF’s exclusivity advantage.

Option D: Aspirational only

Rejected. Wasted opportunity — the emulator integrates the entire course.

Open questions resolved

ch12 vs “Capstone Project” label: → Use Chapter 12 — Game Boy Emulator with subtitle “A Systems Capstone”. Renaming to “Capstone” would break ToC consistency.

SDL2 vs PPM framebuffer: → Provide both. SDL2 for display; PPM fallback via -DNO_SDL for headless environments (Chromebook, CI, locked-down school machines).

Existing buyer notification: → Free update via Gumroad. ch12 is additive; no price bump for existing buyers. Update Gumroad description when ch12 ships.

Future beyond-course chapters: → Deferred. If ch12 lands well, the pattern is clear: each beyond-course chapter has its own ch{N}.typ, mirrored tests, and canonical content/ch{N}/ exercises.

Implementation status

PhaseItemStatus
Phase 1Web app: “COMPANION PDF” badge on roadmap callout✅ Already in IntroScreen.jsx
Phase 2PDF: src/chapters/ch12.typ written✅ Complete
Phase 3Exercise starters: ch12/ex12_1–ex12_4 in exercises repo✅ Complete
Phase 4Test solutions: tests/ch12/ex12_1–ex12_4 in PDF repo✅ Complete
Phase 5PDF metadata: STATUS.md, COMPANION.md, GUMROAD.md updated✅ Complete
Phase 6Wiki: this page updated✅ Complete

Shipped verification status (2026-04-15):

  • bash tests/run_all.sh: 48/48 pass
  • All 4 PDF outputs rebuilt successfully
  • Gumroad listing and project status pages updated to reflect ch12

What ch12 contains

Structure: Intro → Key Concepts → Going Deeper (4 sections) → Real-World Connection (SameBoy) → 4 Exercises → Solutions → Extended Project

Key Concepts: SM83 register file, memory map, cartridge header, PPU/scanline renderer, cycle accuracy vs. functional emulation.

Going Deeper sections:

  1. Cycle accuracy vs. functional emulation — when each matters
  2. Opcode dispatch: switch vs. function pointer table (connects to Module 4)
  3. Memory bank controllers — MBC1 and MBC3
  4. Pixel FIFO vs. scanline renderer — practical vs. hardware-accurate

Exercises:

  • ex12_1 — Register file: A/B/C/D/E/H/L/F/PC/SP as struct with flag getters/setters
  • ex12_2 — Memory bus: bus_read/bus_write dispatching all DMG regions
  • ex12_3 — Opcode subset: 256-entry function pointer dispatch table, 10 families
  • ex12_4 — ROM loader: header parse, logo check, checksum validation

Extended Project: Get Tetris booting — complete SM83 opcode set, scanline PPU, SDL2 display at 59.7 fps, Blargg cpu_instrs tests.

Graph View

Backlinks