Bug Tracking for Rhythm Games

Rhythm games live and die on timing. The entire experience is the player hitting notes in sync with music, and the game judging that timing down to a few milliseconds. That makes the genre uniquely vulnerable to a whole class of bugs other games never have to think about: audio that drifts from the visuals, input that arrives later than the player pressed, and calibration that fails to account for the latency stacked across a player's audio and display hardware. When timing is wrong, the game feels broken even if every note renders perfectly. This post covers the bugs specific to rhythm games and the context needed to reproduce timing failures.

The song clock and where timing comes from

Everything in a rhythm game is judged against a clock, and the most reliable clock is the audio playback position itself. A common architectural bug is judging input against the frame clock or wall time instead of the audio position, which lets the visuals and judgment drift away from the music as small timing errors accumulate over a long song. By the final chorus, notes that looked aligned at the start are judged early or late, and the player's perfect run is ruined by accumulated drift the game never corrected.

Debugging drift requires knowing what clock the game judged against and the audio playback position at the moment of the report. A player reporting that a song gets harder to time toward the end is describing accumulating drift between the audio and the judgment clock. Capturing the audio position and the song time the game believed it was at lets you measure the divergence directly. The fix is almost always to drive everything from the audio clock, but you can only confirm the bug once you can see the two clocks separate over the course of a track.

Calibration and offset handling

Every player's hardware adds latency: audio output has buffer delay, displays add their own lag, and Bluetooth audio can add a great deal. Rhythm games handle this with calibration, letting the player set an audio offset and a visual offset so notes and music align for their setup. Bugs in offset handling are devastating because they make the game unplayable for affected players while feeling fine for the developer. An offset applied with the wrong sign, applied to the wrong path, or reset on each song silently throws off everyone who calibrated.

These bugs need the player's configured offsets, both audio and visual, and confirmation of how the game applied them. A player whose timing is consistently early by a fixed amount, matching their offset, has an offset applied with the wrong sign or not applied at all. Capturing the configured offsets alongside the judged timing errors reveals a constant bias that points straight at the calibration path. Because the symptom is a systematic offset rather than random error, the configured values are exactly the context that turns it from confusing to obvious.

Audio buffers, latency, and Bluetooth

The audio pipeline itself is a source of timing bugs. A large audio buffer reduces stutter but adds latency, and if the game does not account for the buffer size in its timing, every judgment is biased by that delay. Wireless audio is worse: Bluetooth can add a hundred milliseconds or more, and that latency varies by device and can change mid-session. A player on wireless headphones who calibrated once may drift out of sync as the codec renegotiates, and the game judges them harshly for latency it introduced.

Capturing the audio buffer size, the output device type, and whether the route is wired or wireless is essential for these. A player whose timing is badly off and who is on Bluetooth is almost certainly fighting audio latency the game is not compensating for. Recording the buffer size lets you check whether the game accounts for it in its timing math, and recording the device tells you whether the problem is a class of hardware rather than a single bug. These details separate a genuine timing defect from the unavoidable latency of a player's audio setup.

Judgment windows and beatmap timing

The judgment windows, the millisecond ranges that map a hit to perfect, good, or miss, encode the game's difficulty and fairness. Bugs here make the game feel arbitrary. A window defined asymmetrically by accident so early hits are punished more than late ones, a window that scales wrong at high note density, or a beatmap whose notes are placed against a slightly wrong tempo so the chart itself is off-beat. The last is especially common, since a beatmap authored with the wrong BPM or offset will feel wrong no matter how good the engine timing is.

To debug these you need the per-note judged timing errors and the beatmap identifier. A consistent bias on one specific chart but not others points at the beatmap's tempo or offset rather than the engine. Capturing the timing error distribution across a song reveals whether early and late hits are judged symmetrically and whether a section drifts. The beatmap ID lets you reauthor or re-time the specific chart at fault. Without per-note timing data you cannot tell an engine bug from a charting error, which are fixed in completely different places.

Setting it up with Bugnet

Bugnet's in-game report button captures game state automatically, and for a rhythm game the decisive captures are the timing values: the audio and visual offsets, the buffer size, the output device, the per-note judged errors, and the beatmap and song position. When a player reports that timing feels off, the report can carry all of it, so instead of a subjective complaint you get a timing error distribution and the calibration that produced it. That lets you tell an engine drift from a wrong offset from a mischarted beatmap without ever touching the player's setup.

Occurrence grouping plus device context is what makes hardware-specific timing bugs visible. Grouping folds many reports of off timing into one issue with a climbing count, and the captured device and route reveal the pattern: a cluster on Bluetooth points at audio latency, a cluster on one beatmap points at the chart. Custom fields let you filter by output device, by offset, or by beatmap, so a systematic timing bias surfaces as a clean cluster instead of a pile of disputed scores. That clarity is essential in a genre where timing complaints are otherwise impossible to adjudicate.

Testing timing objectively

The most effective practice for a rhythm game is to make timing measurable and automated. Build tests that feed synthetic inputs at known offsets from the audio clock and assert the engine judges them to the expected windows, across different buffer sizes and simulated output latencies. This catches asymmetric windows, offset sign errors, and failure to account for buffer latency deterministically, removing the subjectivity from a genre where everything is subjective until you measure it.

Pair that with a feedback loop and a culture of trusting the data. When a captured timing distribution reveals a mischarted beatmap or a calibration bug, turn that exact scenario into a regression, and re-time the chart or fix the offset path. Test on the hardware your players actually use, including wireless audio, because the worst timing bugs hide in latency the developer's wired setup never sees. Treat a measured timing bias as a real defect, not player error, and your players will trust that a missed note is their hand, not your engine.

Rhythm bugs are timing data. Capture offsets, buffer, device, and per-note errors, and a subjective off-beat complaint becomes a measurable, fixable bias.