Bug Reporting for Games With Physics Puzzles

A physics puzzle asks the player to manipulate a simulated world: stack crates, swing weights, route a ball through contraptions, exploit momentum and gravity to reach a goal. The simulation is the puzzle, which means the simulation is also where the bugs live. A box tunnels through a wall, a stack that should be stable jitters apart, a contraption solves itself differently every time the player tries it. These are among the hardest bugs to reproduce, because physics engines are sensitive to tiny differences and may not be deterministic at all. This post covers reporting physics bugs by capturing the full object state and the input sequence, so a glitch you saw once becomes replayable.

Why physics bugs are so slippery

Physics simulation is iterative and numerically sensitive. Each step integrates positions and velocities, resolves collisions, and satisfies constraints, and tiny differences in starting conditions or in floating point results can compound into wildly different outcomes a few seconds later. This sensitivity is what makes physics bugs so slippery: a player drops a box and it clips through the floor, but when you set up what looks like the same situation, the box behaves perfectly. The starting conditions were not actually identical, and in a chaotic system that is enough to change everything.

On top of sensitivity sits the question of determinism. Many physics engines are not deterministic by default, frame rate, thread scheduling, and platform floating point behavior can all change results, so the same inputs do not even guarantee the same output on the same machine. When the simulation itself is not repeatable, reproducing a bug by recreating the scenario is fundamentally unreliable. You have to capture the actual state that produced the glitch rather than trying to recreate the conditions and hoping the simulation lands in the same place, which it may never do.

Object state is the ground truth

The most reliable way to reproduce a physics bug is to capture the complete state of the simulation at, or just before, the moment it broke. That means the position, rotation, linear velocity, and angular velocity of every relevant rigid body, plus which bodies are asleep, what constraints and joints are active, and any forces being applied. This full state is the ground truth of where the simulation actually was, as opposed to where you think it was when you try to set it up by hand. With it, you can load the bodies into exactly that configuration.

Capturing state just before the failure is especially powerful because it lets you step the simulation forward and watch the glitch unfold. If a box is about to tunnel through a wall, loading the frame before, with the box's high velocity and position, and stepping forward shows you the exact moment the collision is missed. That is far more useful than the after state, which only shows the box already on the wrong side. The pre failure snapshot turns an instantaneous, unrepeatable event into something you can replay frame by frame and study.

Input sequences and timing

Object state alone sometimes is not enough, because physics bugs frequently depend on the exact sequence and timing of player inputs. Tunneling through a thin wall, for instance, often requires a body moving fast enough that it crosses the wall within a single simulation step, and reaching that speed depends on precisely how the player pushed or threw it. A stacking exploit might require placing objects in a specific order with specific timing. The bug is a product of the input history, not just a static configuration.

So capture the input sequence leading up to the failure, the ordered player actions with their timing relative to the simulation steps, alongside the object state. Replaying those inputs against the captured starting state, at a fixed time step, recreates the exact motion that produced the glitch. This combination, a known starting state plus a recorded input sequence played back deterministically, is the closest thing to a physics replay you can get, and it is what makes an otherwise one in a thousand glitch reliably reproducible on a developer machine.

Common physics puzzle failures

Physics puzzle bugs fall into recognizable families. Tunneling, where a fast object passes through a collider in a single step, breaks puzzles by letting objects escape their bounds or reach goals unintendedly. Instability, where stacks or jointed structures jitter and explode, comes from the constraint solver failing to converge, often when too many contacts pile up. Sleeping bugs leave a body frozen because the engine put it to sleep prematurely, so it ignores a force that should have woken it. Each family has a characteristic signature in the captured state.

There are also exploit shaped bugs, where the physics behaves correctly by its own rules but lets the player bypass the intended solution, launching themselves with a glitchy bounce, or wedging an object to clip past a barrier. These are valid simulation outputs that are wrong for the puzzle, so you cannot fix them by fixing the physics; you have to add constraints to the puzzle, a kill volume, a velocity clamp, a continuous collision setting on the critical body. Knowing which family a report belongs to, which the captured state reveals, tells you whether to fix the solver or the level.

Setting it up with Bugnet

Bugnet gives players an in game report button, and for a physics game you configure it to capture the full object state, positions, rotations, and velocities of the relevant bodies, the active constraints, and the recent input sequence, attaching them as custom fields. Ideally you snapshot a short ring buffer of recent frames so the report includes the state just before the glitch, not only after. If the physics step throws, an assertion in the solver, for example, the report carries a full stack trace and platform context, locating the failure precisely.

Because a particular geometry or solver weakness produces the same class of glitch for many players, Bugnet folds the duplicate reports into one issue with an occurrence count, so a tunneling spot in one puzzle that hundreds of players hit is clearly a level you need to fix rather than a fluke. You can filter the dashboard by puzzle, by object, or by any field you captured, and the captured velocities and states let you spot patterns, such as tunneling always occurring above a certain speed. That points you at a continuous collision fix instead of leaving you guessing.

Toward deterministic, testable physics

The teams that ship solid physics puzzles invest in making the simulation as deterministic as they can: a fixed time step decoupled from frame rate, controlled iteration order, and care around platform floating point, so that the same inputs reliably produce the same result. A deterministic simulation transforms bug tracking, because a captured state plus an input sequence becomes a perfect replay that reproduces the glitch every time, and a fix can be verified by replaying the same sequence and confirming the glitch is gone.

With determinism in place, every reported physics bug becomes a regression test: store the starting state and inputs, replay them on each build, and assert the object ends where it should rather than tunneling or exploding. Fuzzing the puzzles with randomized inputs at a fixed step flushes out tunneling and instability before players find them. When your reports always carry the object state and input sequence, and your simulation is deterministic, physics stops being a source of unreproducible ghosts and becomes a system you can replay, test, and trust, glitch by glitch.

Physics bugs are chaos until you pin them down. Capture the object state and input sequence, make the step deterministic, and the glitch replays on demand.