Rhythm Game — Learning Plan
The goal: a rhythm game you can hand to a friend — notes falling in perfect sync with the music, timing feedback that teaches, charts you made by playing, and a calibration screen so it works on their hardware too. Built in two acts, because this project starts somewhere unusual: with code you didn't write.
Act one is an audit. This prototype was built in early 2026 with AI writing most of it — it works, it's latency-compensated, it runs at 60fps, and nobody could fully explain it. Rather than delete it, the first three stages turn it into understood code: read it, explain it, hunt its real defects, and draw the boundaries it's missing. That skill — auditing code you inherited — is worth more than the game.
Act two builds everything the prototype lacks. By the end you'll have written the parts that make a rhythm game feel like one, and shipped it as an executable.
When you're done, all of this is true#
- You can explain the four-clock timing model from memory, and the song-time formula term by term
- Every inherited defect is found, explained, and fixed — and you can say which ones would have reached a player
- Notes move without visible stutter on a high-refresh monitor, and you have the before/after numbers to prove it
- You can chart a new song by playing it, and the chart feels right
- The game shows perfect/good/miss with early/late milliseconds, combo, and accuracy
- A stranger can calibrate their latency, pick a song, pause, finish, and see results
- A Windows build runs on a machine that has never seen Godot
What you'll learn#
New here: audio timing and latency compensation (the deep end of game programming — most developers never touch it) · reading and auditing unfamiliar code · building an authoring tool inside your own game · designing feedback that teaches a player · pause architecture · the export pipeline.
Practiced along the way: custom Resources, signals, enums over strings, typed GDScript,
scene flow, user:// vs res://, and git as a running commentary on your work.
Deliberately left out: multiplayer, leaderboards, and note types beyond taps. The point is a small game that is correct, not a big one that's approximately right — timing is unforgiving, and everything above depends on getting it exact.
Act one — make the inherited code yours#
| # | What you'll have (observable) | What you'll learn |
|---|---|---|
| 01 | You can narrate the timing pipeline aloud; the probe questions answered in writing | audio clocks & latency · reading unfamiliar code |
| 02 | Six defects found, explained, fixed; the game verified identical or better | systematic debugging · res:// vs user:// |
| 03 | Public APIs renamed; the stringly-typed judgment channel replaced with an enum | API discipline · enums & match |
Act two — build the real game#
| # | What you'll have (observable) | What you'll learn |
|---|---|---|
| 04 | Note motion measurably smooth at any refresh rate | clock blending · measuring before optimizing |
| 05 | Record a chart by tapping along; play it back | tool-building · runtime data hygiene |
| 06 | Combo, accuracy, early/late readout, a calibration screen | scoring math · designing feedback loops |
| 07 | Menu → song select → play → pause → results, all working | scene flow · pause architecture |
| 08 | A double-clickable Windows build | export pipeline · user:// for real |
Do act one before act two — every act-two stage leans on the understanding act one builds.
Three stages ask you to make a real design decision between two sound options: how to smooth the clock, where calibration applies, and where recorded charts live. The trade-offs are laid out where they appear; record what you chose and why in the architecture document. Those choices are what make the result yours.
House motto: aim for improvement every day. One stage is one sitting.