Bug Tracking for Metroidvania Games with Sequence Breaks

Metroidvanias are built on an interconnected world gated by abilities, and their most interesting bugs come from players defeating that structure. A skilled player will reach an area before they were supposed to, skip an ability they needed, or trigger an event in an order you never anticipated, and your progression logic, which quietly assumed a particular order, breaks. These sequence-break bugs are the genre signature defect, and tracking them means capturing the exact ability and world state that let the player slip through your intended path.

Players will break your intended order

You design a metroidvania with an intended path: get the double jump, then reach the area that needs it, then get the next ability. Players, especially skilled ones, will not respect that path. They will find a way to reach the gated area early through clever movement, a missed collision, or an exploit, and your game will be in a state you never designed for, often with progression flags set in an impossible order.

This is not necessarily bad, sequence breaking is beloved by speedrunners and many developers embrace it, but it produces bugs. An event that assumed an ability the player skipped, a door that expected a flag that is not set, a soft lock where the player is trapped in an area they should not have been able to enter yet. Tracking these requires knowing exactly what state the player was in.

Capture abilities and items

The core context for a sequence-break bug is the set of abilities and items the player has. A bug that happens because the player reached an area without the expected ability is only diagnosable if you know which abilities they actually had. Capture the full ability and item state on every report so you can see the unexpected combination that produced the bug.

This ability state often immediately reveals the sequence break. When a report comes from a player who is in an area that requires the grapple but does not have the grapple, you know they broke sequence to get there, and that tells you both how the bug happened and that you need to either block that route or make the area robust to early entry. The ability state is the fingerprint of the sequence break.

Capture world and map flags

Beyond abilities, metroidvanias track a web of world flags: which bosses are defeated, which doors are open, which events have fired, which rooms are explored. Progression bugs and soft locks usually come from these flags being in a combination your logic did not expect. Capture the relevant world and map flag state so you can see the impossible combination directly.

A soft lock often comes down to a flag that should have been set but was not, because the player skipped the event that sets it, or a door whose open condition can never now be met. With the flag state captured, you can see exactly which condition is unsatisfiable from the player current position, which both explains the soft lock and points at the fix, usually making the relevant flag robust to being reached out of order.

Soft locks are the worst case

The most damaging metroidvania bug is the soft lock: the player is trapped with no way forward and no way back, their progress effectively dead. These are devastating because the player has invested hours and now cannot continue, and they are common precisely because the interconnected world has so many states. A soft lock report needs the full position and flag state to diagnose.

Capture the player current room and position along with the world flags so you can see how they got trapped and why they cannot escape. Sometimes the fix is a one-way passage that should have been two-way, sometimes it is a flag that should be set on entry rather than on an event, but in every case you need to see the exact trapped state to find the escape route you failed to provide. A reproducible soft lock is a fixable soft lock.

Setting it up with Bugnet

Add an in-game report option and attach the player abilities, items, world and map flags, current room, and position as a serialized state snapshot and custom fields. Bugnet stores them so any sequence-break or soft-lock bug arrives with the exact state that produced it, letting you load that state and stand where the player stood.

Group identical reports into occurrence counts so you can see which sequence breaks affect the most players, which tells you which routes to prioritize closing or hardening. Because the captured state reveals the unexpected ability and flag combinations, you can decide deliberately whether to embrace a given sequence break and make it robust, or block it, rather than discovering the consequences only through a wave of soft-lock complaints.

Decide your stance on sequence breaking

Metroidvania developers face a choice: fight sequence breaking or embrace it. Fighting it means blocking every unintended route, which is hard in an interconnected world and can feel restrictive to skilled players. Embracing it means making your progression robust to any order, so that no matter how the player reaches an area, the game continues to function and never soft locks.

Captured state data informs that decision with evidence. When you can see exactly which sequence breaks players find and what state they produce, you can choose to harden the popular ones into supported alternate routes, which speedrunners and explorers love, while blocking only the ones that genuinely break the game. That data-driven stance turns sequence breaking from a source of dread into a dimension of your design you actively shape, which is exactly how the best metroidvanias treat it.

Players will reach the gate before the key. Capture the state so out-of-order becomes reproducible.