Foreword: how to read this

This is a guided read of one small, complete game: Terrapin Trail II, a comedic Oregon Trail-style RPG that follows the Grateful Dead on tour. It is about 3,800 lines of hand-written JavaScript in a single file, one serverless function, and no framework. That smallness is the point — it is big enough to be a real program with a real architecture, and small enough that you can hold all of it in your head by the end.

Two editions, same material

Use the switch in the top-right corner:

• Field Manual (this one) assumes you already write code. It moves fast, quotes the source directly, and points at exact lines.
• First Tour teaches the underlying ideas as they come up — what a function is, what "state" means, why an event loop exists. Same chapters, same code, gentler on-ramp.

Nothing stops you mixing them: read a concept in First Tour, then switch to Field Manual for the same chapter to see it stated tersely against the code.

How to read it

Every code excerpt is sliced live from the real source and labelled with its file and line numbers, like a tape on a shelf. The trace ↗ link on each excerpt opens the full file at that spot. The Q&A index (appendix B) is 238 searchable questions, each answer linked to the line it came from; the function map (appendix A) is the fast index into the source.

The one idea that unlocks everything

If you take away a single thing, take this: the same file runs in two worlds. In a browser it draws screens and plays sound; under Node — with no browser — it runs the pure game rules and hands out a test surface instead. One boolean decides which world it is in. Almost every design choice in the codebase falls out of keeping those two worlds sharing one body of logic.

9  // DOM, so rendering, animation, and network are skipped -- the pure game logic
10  // still runs, which is what the headless tests exercise.
11  var HAS_DOM = typeof document !== "undefined" && typeof window !== "undefined";
12
13  // ---------- tiny utils ----------
14  // rand is swappable so tests can install a seeded PRNG for deterministic runs.
15  var rand = Math.random;

The chapters build up from there: the shape of the file, the screen state machine, the data catalogs that hold all the content, then the subsystems — driving, crew, taping, economy, scoring, saving, the backend, and the tests.

The Infinity edition

The game you can play here grew up. The same single-file game now runs any tour by any band on the Internet Archive's Live Music Archive, with a small Python server around it: it lists the bands, builds tours from real shows, streams the recordings, keeps shared leaderboards per tour and rule set, and serves this guide. Chapters 0-12 read the game file; chapter 11 and chapters 13-18 cover everything around it. Every excerpt, in every chapter, is read from the code that is running right now, so what you read is what plays.