Docs

A labor of love by Hunter Davis. The pages below are reference manuals for the PlayStation 1 build of Johnny Castaway. They describe how the executable is compiled, what each subsystem does, and what the author types when bringing up a scene. They are not tutorials. They are not a community forum. There is no contributor onboarding here — see the FAQ for the project’s stance on contributions.

If you paid for this, you were cheated. Open source and free.

What’s in /docs/

• Build & toolchain

  PSn00bSDK 0.24, the Docker dev image, the cmake invocation, and the mkpsxiso step that produces jcreborn.bin + jcreborn.cue. Includes the exact docker commands the author uses.

• Closed captions

  How the caption corpus, the ADS-tag map, and the on-screen text band fit together. Includes the 30 HIGH / 21 MED / 12 LOW confidence breakdown from the 2026-04-26 audit and the v0.8.4-ps1 runtime corrections section noting which audit ratings the on-PS1 chapter-select walk overturned.

• Holidays

  From four shipped holidays to thirty-six. Movable feasts via Meeus / Zeller, no expiring tables. Codegen pipeline from holidays.yml to a C struct array.

• Pause menu

  State machine, twelve sub-screens (Scene Set, Scene Explorer, Freeplay Options, Controls, World Options, Holidays, Set Island Position, Accessibility, Sound Test, System, Set Time/Date, Set RNG Seed), Freeplay entry/exit, and the shared font atlas used by captions.

• Freeplay mode

  The runtime-driven scene where the player drives Johnny instead of watching him: controls, gag/visitor debug catalogs, world toggles, frog loading transitions, and long-run memory rules.

• Story-loop walks

  How Johnny stops teleporting between scenes — the walk_pilot/walk_render split, Sierra's six-spot route table, the persistent clean buffer, and the runtime invariants (waves, palm-tree occlusion, holiday overlay re-stamping).

• Regression testing

  Headless DuckStation in Docker. Frame PNGs every N frames, SHA256 state hashes, telemetry overlay decode, and the per-scene wrapper.

• Scripted input harness

  Pad scripts embedded into the PS1 build: deterministic menu routes, Freeplay repros, marker-aligned screenshots, and the generated menu help guide.

• API mapping (SDL2 → PSn00bSDK)

  Every SDL2 symbol the upstream engine called, mapped to the PSn00bSDK call that replaced it. The bridge between the host-capture build and the PS1 build.

• Development workflow

  The author's per-scene runbook: capture on host, encode to .FG2, replay on PS1, take a screenshot, validate. Honest about how long it takes and how often it breaks.

• Performance

  Reference manual for the headless-perf battle card: how loop_vb / target_vb are measured, what each column means, the column-by-column glossary, and the experiment-log discipline.

• Hardware

  The PS1 envelope this port runs inside — 33.8688 MHz MIPS, 2 MB RAM, 1 MB VRAM, 512 KB SPU, no FPU, 2× CD drive at 300 KB/s. Why every constraint shows up in the build.

• Devices — what it runs on

  The emulator and hardware combinations actually tested: DuckStation as the every-commit reference, SCPH-7501 via TonyHax as the smoke-tested real PS1 path, PCSX-Redux + PS2/PS3 backwards-compat as should-work-unverified, plus the BIOS requirement and the paths the project has never tried.

• Audio

  SPU layout, VAG sample bank, the round-robin voice allocator, the captured 0xC051 PLAY_SAMPLE events, and the ocean-ambience loop on its dedicated voice.

• File formats

  The five spec pages behind the build chain: the FG2 / FGP3 pack payload, the pack-manifest sidecar, the dirty-region template, the transition-prefetch schema, and the SDL-compat-lite shim spec.

• Infrastructure

  The Docker dev image, the regtest container, the release script, the build-farm pattern, and what's still done by hand on every release.

• AI sub-agents

  The honest accounting of where LLM sub-agents helped on this project — caption corpus drafts, holiday-emblem sprite primitives, long-form prose drafting — and what they explicitly didn't do.

• Vision-classifier

  The pixel-vs-reference comparison layer that runs on top of the regtest harness: per-frame diffs, scene-state classification, and how it feeds the visual signoff bar.

• Glossary

  The specific technical terms the rest of the docs use without scaffolding — FG2 packs, ADS, TTM, dirty-rect bookkeeping, FntFlush, the FISHING 1 bar, drawCredits. Grouped by area, not alphabetical.

• Feeds & well-known endpoints

  Every machine-readable URL on the site: the Atom + JSON feeds for the devlog and lab, the hand-rolled sitemap, the RFC 9116 security.txt, robots.txt, humans.txt, the W3C web manifest, and the Schema.org JSON-LD records emitted in every page's head.

The Other Maps

The reference manuals are not the whole archive. The site now has four neighboring maps that make the rest of the work findable:

• Source library

  Every Markdown file outside the website tree gets a public page: active manuals, generated research, old plans, status notes, and archaeology.

• Resource catalog

  The asset shelf: BMP, ADS, TTM, SCR, VAG, PSB, and FG2 files indexed by type with source links.

• Regtest case shelf

  Sixty-three host baselines, one page per captured reference, with boot string, frame count, state hash, and source artifacts.

• Curious hacker guide

  A learning path for reading the C, porting to another machine, using visual debugging, and understanding the memory budget.

Where this content comes from

These pages are derived from the source documents under docs/ps1/ in the repository. Each sub-page links directly to the file or files it was built from. If you want to view-source any reference manual, the GitHub tree is the canonical copy; /docs/ is just a re-organized read of it.

For the high-level “what this project is” narrative see About. For per-scene status see the scene ledger. For day-by-day worklog see the devlog. For methodology essays see the Lab.