Bug Tracking for Puzzle RPGs

A puzzle RPG asks you to debug two games glued together. On top there is a match-three or merge board, a combinatorial space where one move can trigger a cascade of chains, multipliers and special tiles. Underneath there is a role-playing game with levels, gear, status effects and a save file that has to survive for dozens of hours. The hard bugs are the ones that cross the seam: a board cascade that resolves damage in the wrong order, a status effect that should expire but does not, a reward that writes a malformed item into the save. This post is about tracking failures across both layers at once.

The board is a combinatorial minefield

The match layer is where the most reproducible-looking bugs hide, because the board is a finite state you can actually serialize. A single move can set off a chain: tiles clear, others fall, new matches form, special tiles detonate, and each step feeds the next. The order in which the engine resolves simultaneous matches matters enormously, and an off-by-one in cascade ordering can double a multiplier or skip a trigger. When a player reports that a combo did not pay out, the only reliable evidence is the full board state before the move plus the move itself, because everything else flows deterministically from there.

Special tiles and adjacency rules multiply the edge cases. A bomb next to a line-clear, two specials swapped together, a board with no legal moves that should reshuffle but locks instead, all live in the gaps of your resolution logic. These are exactly the cases your unit tests miss because no human sets them up on purpose. Capturing the serialized board at the moment of the report lets you replay the move in isolation, step the cascade, and see precisely which resolution step diverged from what the player expected to happen.

Where the board poisons progression

The dangerous bugs are the ones that leak from the transient board into the persistent RPG layer. Combat damage is usually computed from board events, so if a cascade reports the wrong number of matched tiles, the damage calculation downstream is wrong, and the player either steamrolls or stalls a fight that should be balanced. Worse, if a reward is granted based on a miscounted combo, the loot written to the save is wrong, and now the bug is permanent. A board glitch you could have shrugged off becomes a corrupted character that no patch can retroactively fix.

Status effects and turn order are the other seam. A poison that ticks based on board fills, a shield that should consume on the next hit, a buff that must clear at end of turn, all depend on the board and combat layers agreeing about when a turn actually ended. Capture both the combat state and the board state together, because a bug report that only shows the board cannot prove the status effect math was wrong, and a report that only shows combat cannot prove the board fed it bad input. You need the handoff between them in a single packet.

Save integrity over long sessions

Progression means a save file that accumulates state for a very long time, and that file is the thing players cannot afford to lose. The subtle bugs are not crashes but slow corruption: an item with a stat field that overflows, a quest flag that gets set twice, a currency that goes negative because a refund path ran an extra time. None of these announce themselves. They surface hours later as a character that will not load or a shop that gives infinite gold. By the time the player reports it, the originating action is long gone unless you logged it.

Defend the save the way you would defend a database. Validate the save on write and on load, and when a check fails, capture the offending structure and the recent progression events rather than silently clamping. A report that includes the malformed item and the last several rewards granted points you straight at the loot or combat path that wrote it. Treat save corruption reports as the highest priority class in a puzzle RPG, because a board bug ruins a match but a save bug ruins someone's entire run, and that is the player you lose for good.

Reproducing across both layers

Reproduction in a puzzle RPG means recreating a specific board on top of a specific character state, which is more than a screenshot can carry. The reliable approach is to serialize a compact snapshot at the moment of the report: the board grid, the pending cascade, the combat actors with their stats and active effects, and the relevant progression flags. With that you can load the exact situation in a test harness and step it. A textual description like my combo did not work is unworkable, but a loadable snapshot turns it into a deterministic test case you can keep as a regression check.

Categorize incoming reports by which layer the divergence appears in, because players cannot tell you that. Tag them as cascade resolution, damage calculation, status or turn order, reward grant, or save integrity. Once sorted, the patterns become obvious: cascade bugs cluster around specific special-tile combinations, save bugs cluster around a particular loot type. That mapping is what lets a small team triage a genre that, taken as a flat list, looks like an unrelated jumble of board complaints and RPG complaints that actually share a common root at the seam.

Setting it up with Bugnet

Bugnet's in-game report button can serialize the whole cross-layer snapshot for you. Bind it so a report attaches the board grid, the move that was made, the combat actors and effects, and the relevant progression flags as custom fields. Arm a guard around save validation so that a malformed item or an out-of-range stat flushes a report automatically with the offending structure and recent reward events. If the resolution code panics on an impossible board, the crash arrives with a stack trace and full device context. Vague combat complaints become loadable, replayable test cases.

Occurrence grouping then turns the flood into priorities. Forty reports of the same special-tile combo paying out wrong fold into one issue with a count, and you can filter by your layer tags to see whether save-integrity reports are spiking after a recent loot change. Custom fields let you ask whether a damage bug correlates with a specific status effect, all from one dashboard. Instead of reading the board layer and the RPG layer as two separate inboxes, you triage the seam between them by how many real saves each failure actually threatens.

Testing the hybrid as a whole

Test the seam, not just the halves. It is tempting to unit test the board solver and the combat math separately and call it covered, but the bugs that hurt live in the handoff. Build fuzz tests that play random legal moves for thousands of turns while asserting invariants across both layers: damage never exceeds what the matched tiles justify, currency never goes negative, every saved item validates. Run them long enough to expose the slow save corruption that only appears after hours, because a short test will never reach the state that breaks a real player's file.

Make save integrity a release gate. Before shipping, load a library of real long-session saves through the new build and confirm they all still parse and play. Keep every captured board-plus-combat snapshot as a permanent regression case so a fixed cascade bug never silently returns. Done consistently, this gives players a game where the puzzle stays clever and the progression stays trustworthy, and where the rare bug that does cross the seam leaves a clean, replayable trail back to the exact move that caused it.

In a puzzle RPG the board is transient but the save is forever. Capture both layers together and guard the save like a database.