Curious hacker path

Start Here

The first day with the Johnny Castaway PS1 codebase.

The fastest way into this project is to stop trying to understand every file up front. Build it, run it, then use the running program as the index.

Start with the build guide. It explains the Docker image, PSn00bSDK 0.24, the cmake invocation, and the mkpsxiso step that creates the disc image. Then open the play page, the scene ledger, and the performance battle card. Those four pages tell you what the project does today, what it claims to do, which claims are actually validated, and which are actually fast.

The First Loop

  1. Build the PS1 disc image.
  2. Boot it in DuckStation.
  3. Pick FISHING 1, because it is the reference bar.
  4. Toggle night, tide, holiday, raft, and captions from the pause menu.
  5. Run the scripted input harness once so the menu route becomes screenshots instead of memory.
  6. Read the per-scene page for FISHING 1.
  7. Read the regtest docs and understand why “it looked fine once” does not count.

That loop is small enough to finish and rich enough to teach the whole shape of the project. You will touch the renderer, the input path, foreground pack replay, audio cues, overlays, captions, and the runtime options surface.

The project’s polished explanation is About / Method. The raw archive is the source library, which wraps every Markdown file outside the website. The files worth reading early:

Read the old research too, but read it as archaeology. The project has several false summits preserved on purpose, including the 63/63 host-harness moment that did not mean what it first seemed to mean.

What Not to Do First

Do not begin by changing scene routing. Do not begin by rewriting the pack format. Do not begin by cleaning up style. The first useful contribution to your own understanding is a local run that you can compare against a known state. Once you can reproduce FISHING 1, the rest of the codebase has a scale.

  • Hack: learn C from Johnny — guided tour through plain-C modules in this codebase, the natural next stop once the build runs.
  • Hack: visual debugging — the screenshot-and-overlay loop the rest of the project’s bug-fixing loop runs on top of.
  • Hack: memory wars — the 2 MB / 1 MB / 512 KB hardware envelope this codebase was shaped by.
  • Hack: performance loop — the headless-perf iteration that now drives most ongoing work.
  • Hack: port to a new platform — what changes if you take what’s here and target some other weird machine.
  • Build & toolchain — the canonical reference for the cmake + Docker + mkpsxiso pipeline mentioned above.
  • Glossary — vocabulary anchor for the terms (FG2 pack, FISHING 1 bar, host build, regtest, scene picker) the loop above leans on without scaffolding.