Bug Tracking for Co-op Puzzle Games

Co-op puzzle games are designed around dependency: one player holds a lever while the other crosses, two players push synchronized buttons, one builds a path the other walks. That interdependence is the joy of the genre and also the source of its hardest bugs. When something breaks, it almost always breaks asymmetrically, one player is stuck while the other sees no problem at all, which makes reports half-complete by nature. You need both players state to understand what went wrong. This post covers the three areas where co-op puzzle bugs concentrate, shared state, two-player dependencies, and desync, and how to capture the paired context that makes an interdependent bug reproducible.

Shared state in a two-player puzzle

A co-op puzzle has a shared world that both players read and write, but unlike a competitive puzzle the two players are cooperating, which changes the bug profile. The state is usually more structured, levers, doors, platforms, carried objects, with clear ownership, and the bugs come from that ownership going wrong. A door that opens on one client but stays shut on the other, an object one player is carrying that the other sees on the ground, or a switch whose state the two clients disagree about. The shared world quietly forks into two slightly different worlds.

Capture the shared world state from both clients at report time, not just one. The snapshot should include the state of every interactive object, who owns or is carrying what, and the authoritative version each client believes is current. Because co-op bugs are asymmetric, a single-client capture tells you only half the story, and the half you get is often the player who is not even experiencing the bug. Pairing the two snapshots and diffing them is what reveals which object desynced and which client holds the stale view, turning a confused report into a precise divergence.

Two-player dependencies are the core mechanic and the core risk

The defining mechanic of a co-op puzzle is the dependency where one player action only matters because of what the other player is doing. Player A stands on a pressure plate so Player B can pass, then a bug leaves the plate registered as pressed after A steps off, or fails to register it as pressed at all, and the puzzle becomes unsolvable or trivially broken. These dependency bugs are the heart of the genre precisely because they are where the two players game states must agree, and agreement across a network is hard.

Track each dependency as an explicit relationship with a state: which player is satisfying it, when it became satisfied, and when it was released, recorded on both clients and the server. When players report a puzzle that cannot be solved, attach the dependency state so you can see whether the plate, the lever, or the synchronized trigger registered correctly on both ends. A great many co-op bugs reduce to a dependency that one client thinks is satisfied and the other does not, and capturing the dependency relationship explicitly is what lets you pinpoint exactly which interdependent link broke.

Desync is uniquely confusing in co-op

Desync in a co-op puzzle is especially disorienting because the two players are sitting in voice chat describing different realities. One says the bridge is extended, the other says it is retracted, and both are telling the truth about their own client. The cooperative framing makes desync more visible than in any other genre, because the players actively compare notes in real time and will report the discrepancy in precise detail. The challenge is turning that vivid two-sided description into data you can act on.

Build end-of-puzzle or periodic state checksums so each client hashes the shared world and the server confirms agreement, flagging desync the moment it happens. Capture both hashes and the recent action timeline at report time, so a desync report carries evidence of which action was applied on one client and missed on the other. Frequently the divergence traces to a single missed dependency update or an action applied out of order, and the paired timeline points straight at it. Proactive desync detection also lets you resync quietly, sparing the players the experience of slowly realizing they are no longer in the same world.

Progression, checkpoints, and getting unstuck together

Co-op puzzles are usually linear and checkpoint-driven, so progression bugs strand both players at once. A checkpoint that saves one player progress but not the other, a level transition where only one client loads the next room, or a soft-lock where a consumed object is needed again and cannot be retrieved. Because both players are blocked together, these bugs are doubly frustrating and doubly reported, and they often have no in-game recovery, forcing a restart that loses shared progress. The social cost is high because two people lose time at once.

Capture the progression state for both players when a stuck report arrives: the current checkpoint, the room or level each client has loaded, and the state of any consumable or one-way objects. This reveals whether the two clients diverged at a transition or whether the level design itself permits an unrecoverable state. Grouping these reports by checkpoint quickly exposes a specific transition that consistently fails to sync both players, which is far more actionable than a scattering of we got stuck complaints that never name the same place twice.

Setting it up with Bugnet

Bugnet adds an in-game report button that, in a co-op puzzle, should capture both players context whenever either one flags a problem. Wire it to attach the paired shared-world snapshot, the dependency states, the action timeline, and each client checkpoint as custom fields and player attributes. Because co-op bugs are asymmetric, capturing both sides is what makes them reproducible, and the in-game button lets the player who is actually stuck file the report with the other player state attached. Crashes that drop one player from a session arrive with full stack traces and device context, so a desync caused by a reconnect is visible immediately.

Occurrence grouping is what separates a real interdependent bug from one duo with a bad connection. Many reports about a particular dependency failing fold into one counted issue, so you can see which shared mechanic is breaking the most co-op sessions. Filter by level, checkpoint, or dependency type using custom fields, and a sync bug confined to one synchronized-button puzzle becomes obvious in a single view. You prioritize by how many pairs of players each bug blocks, and the captured paired state gives engineers both halves of the picture from the start.

Testing two-player flows and respecting the duo

Co-op bugs are easy to miss because solo testing cannot exercise a two-player dependency, so structure your QA around real paired playthroughs and, crucially, around the captured states players send you. Replaying a paired snapshot and action timeline against your dependency logic reproduces an asymmetric bug that one tester alone would never trigger. Building a regression suite from these real two-player scenarios is the most effective guard the genre has, because it tests exactly the interdependent links that define your puzzles and that ordinary tests skip.

Remember the social stakes when you communicate fixes. A co-op bug that soft-locks a level wastes two people evening at once, often friends or partners who set aside time to play together, so acknowledgment and a quick fix matter even more than usual. When you ship a sync fix, say so, because the players who hit it remember the shared frustration vividly. Disciplined, paired-state bug tracking is what lets you build ever more ambitious interdependent mechanics while keeping the cooperative experience smooth for the two people relying on each other to solve it.

Co-op bugs break for one player and hide from the other. Capture both sides, model dependencies explicitly, and the asymmetric bug becomes reproducible.