Learn by taking the machine apart
Curious Hacker's Guide
A practical path through the codebase for people who want to port Johnny, learn C, or build their own weird little platform target.
This section is for the reader who looks at a 1992 Windows screensaver running on a 1994 console and thinks: I want to understand how that trick works. Maybe you want to learn C by reading a real codebase. Maybe you want to port Johnny to another strange machine. Maybe you just want to know which tools actually moved the project forward when the elegant plan failed.
The answer is not one heroic abstraction. The answer is a stack of practical loops: build the thing, see the thing, freeze the thing, compare the thing, and then make one small change that survives the loop.
The Path
-
Start here
The first day: clone, build, run, read the scene ledger, and learn what the repository is trying to prove.
-
Learn C from Johnny
A guided tour through plain-C modules that show resource loading, state machines, renderer contracts, and PS1 hardware boundaries.
-
Port to a new platform
How to decide whether a target should run the interpreter, replay packs, or do something stranger.
-
Visual debugging
The screenshot scripts, overlays, frame diffs, and image ledgers that made progress possible when printf was not safe.
-
Memory wars
The 2 MB RAM problem, VRAM pressure, SPU budget, CD layout, and why generated packs beat live bytecode on this machine.
-
The performance loop
Printf, telemetry, headless DuckStation, and the long-running experiments that turned hunches into numbers.
The Four Maps
If you are learning the project, keep these open:
- Build docs for the Docker and PSn00bSDK setup.
- Scene ledger for visual-signoff status per scene; the headless-perf battle card is the second ledger, sortable.
- Source library for the complete Markdown archive, including old failed plans.
- Resource catalog for the bitmaps, ADS scripts, TTM animations, sounds, sprite banks, and generated packs.
The magazine version of this story lives in the Lab. The reference-manual version lives in Docs. This section is the shop notebook: what to read, what to run, what to inspect, and what not to trust until a frame diff agrees.