Game Boy Emulator — Curriculum Decision
File: GB_EMULATOR.md in llc-course root
Decision status: Option A recommended — PDF-exclusive ch12, not yet written
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 area | Emulator connection |
|---|---|
| Types + operators | 8-bit register file, flag bits (Z/N/H/C), masking, rotation opcodes |
| Pointers | Memory bus dispatch via function pointers or flat address array |
| Structs | CPU state (registers, PC, SP, IME) and PPU state as packed structs |
| File I/O | Loading a ROM file, validating the cartridge header |
| Going below C | Real ISA, cycle timing, reading disassembly, Godbolt analysis |
Options considered
Option A: PDF-exclusive ch12 ← Recommended
Add ch12 to the Companion PDF only. Roadmap callout gets a “Companion PDF” badge.
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); if written post-launch, early buyers may feel the PDF shipped incomplete
Option B: Full web module (Module 11) + PDF ch12
Add Module 11 to the free web app and the matching chapter to the PDF.
Pros: Maximum reach; “11 modules including a Game Boy emulator” is a stronger pitch
Cons: 3–4× more authoring work than Option A; weakens PDF’s exclusive-content angle; requires updating all “10 modules” references throughout; reopens a complete, shipped product
Option C: Both simultaneously
Option B but written at the same time. Worst of both — doubles effort, eliminates PDF’s exclusivity advantage.
Option D: Aspirational only
Leave it as a roadmap tag with no guided content. Wasted opportunity.
Recommendation: Option A
PDF-exclusive ch12 with transparent “Companion PDF” labeling on the roadmap callout. The label turns the callout from decorative to functional — a soft call to action. Critical implementation requirement: the label must be clear and prominent.
What ch12 would look like
Structure: Introduction → Key Concepts → Going Deeper → Real-World Connection (SameBoy/Gambatte source) → Exercises → Extended Project
Target length: 15–18 pages. Test files: tests/ch12/ex12_1–ex12_4
Exercises:
- ex12_1 — Register file: A/B/C/D/E/H/L/F/PC/SP as struct with flag bit getters/setters
- ex12_2 — Memory bus:
read8/write8dispatching ROM/WRAM/HRAM/I/O regions - ex12_3 — 25 core opcodes; pass Blargg cpu_instrs test 01
- ex12_4 — Scanline PPU: read tile data from VRAM, render one scanline to 160×1 framebuffer
Extended project: Get Tetris booting — full ROM loading, all cpu_instrs tests, complete PPU renderer, SDL2 display at 59.7 fps
Open questions
- Chapter 12 or “Capstone Project” — does numbering imply the 11-chapter structure is incomplete?
- SDL2 required, or provide a framebuffer-to-PPM fallback for headless environments?
- If successful, does it open the door to other post-course PDF chapters (compiler frontend, key-value store)?
- Buyer notification when ch12 ships — free update or price bump for new buyers only?