How to Fix Game Physics Bugs Fast: A Diagnostic Method

Fixing a physics bug is a diagnosis, not a guess. The method is the same every time: turn on debug draw, reproduce the bug in the smallest possible scene, read the symptom, and apply the fix that symptom points to. Almost every 2D physics bug falls into one of six patterns, and each pattern has a known cause and a specific fix. This article is that map.

A physics engine is a deterministic simulator: the same inputs produce the same outputs. When something "random" happens — a crate launches across the room, the player falls through the floor, a stack explodes — it is not random. It is the engine correctly executing a setup or a piece of code that asks for exactly that behaviour. Your job is to find what you are asking for.

Step 0 — Turn on debug draw first#

Before changing anything, make the physics visible. Every engine has a debug draw mode that renders the actual collider shapes, contact points, normals and velocities on top of your sprites. Turn it on.

This single step solves a surprising fraction of bugs, because the rendered sprite rarely matches the collider. The player's sprite is a person; the collider is an oversized box that extends past the feet. The "wall the player got stuck on" is invisible because there is no art for it — it is a leftover trigger volume from a prototype. You cannot fix what you cannot see, and in physics, what you see in the sprites is almost never what the engine sees.

Step 1 — Isolate the bug#

Reproduce the problem in the smallest scene that still shows it: one body, one surface, one movement. A bug that happens "sometimes, in level 4" is hard to read. The same bug with one box on one floor is usually obvious.

Physics bugs compound. Three wrong settings can mask each other; removing two reveals the third. Strip the scene down until only the bug remains, then fix that.

The six bug patterns#

Bug 1 — Tunneling (fast objects pass through walls)#

Symptom: a bullet, a falling character at terminal velocity, or a fast-moving enemy passes cleanly through a thin wall or floor.

Cause: discrete collision detection checks for overlap at the start and end of each simulation step. If the object moved further in one step than the wall is thick, neither check sees contact.

Fix: turn on continuous collision detection (CCD) — "bullet" mode in Box2D — for the fast body, which sweeps the shape across the whole step. Raise the simulation rate so each step covers less distance. For very fast, thin projectiles, skip the body entirely and use a raycast from the old position to the new one.

Bug 2 — Jitter and settling vibration#

Symptom: objects vibrate, hover slightly, or slowly sink into the ground when they should be at rest. Stacked boxes tremble.

Cause: the solver cannot fully separate overlapping bodies within its iteration budget, or resting contacts have non-zero restitution that produces perpetual micro-bounces.

Fix: raise the solver's velocity and position iterations (Box2D defaults to 8 and 3). Set restitution to zero for objects that should rest. Confirm the simulation runs on a fixed timestep — a variable step makes the solver's job different every frame. Also check that the timestep is not so large that bodies penetrate deeply each step.

Bug 3 — Glued or stuck objects#

Symptom: the character sticks to walls, hitches on flat seams between floor tiles, or cannot be pushed off a resting object.

Cause: friction. The same friction that lets a character stand lets it grip a wall it slides along. Tile-seam hitching comes from the collider catching on the corner of an adjacent tile.

Fix: lower the friction on wall and ceiling colliders. For tile seams, either use a single composite collider per surface instead of many tile-shaped ones, or bevel the player's collider so it slides over corners. The cleanest pattern is a raycast-based ground check: only apply grip when the character is actually on the ground, and let walls be frictionless.

Bug 4 — Floaty, unpredictable jumps#

Symptom: jump height varies, the character slides on landing, or the controls feel like walking on ice.

Cause: the character is a dynamic rigidbody driven by forces or velocity, so momentum, friction and restitution all interfere with deliberate control.

Fix: take the player out of the simulation. Use a kinematic or raycast-based character controller that you move deliberately, with an explicit grounded check and your own jump impulse. Reserve dynamic rigidbodies for objects the player interacts with — crates, barrels, ragdolls — not the player itself.

Bug 5 — Frame drops as the scene grows#

Symptom: the game runs fine early and degrades as more objects appear.

Cause: the engine's broad phase cannot prune the collision pairs, or bodies that should sleep are being kept awake.

Fix: keep colliders tight to the visual shape and avoid enormous invisible colliders. Prefer a few composite colliders over dozens of tiny ones for complex shapes. Let bodies sleep — and audit your code for anything that pokes body velocity or position every frame, which keeps them awake. Profile to confirm the cost is actually in physics before over-tuning.

Bug 6 — Non-deterministic replay or desync#

Symptom: the same input produces different results, replays drift, or netcode desyncs.

Cause: physics runs on a variable timestep, or gameplay code reads input on the render thread while physics steps independently.

Fix: use a fixed timestep so each simulation step is identical, process gameplay input inside the fixed step (not the render step), and avoid floating-point operations whose result depends on platform or optimisation level where determinism matters. Determinism is the foundation of rollback netcode and reliable replay.

Symptom → cause → fix#

Symptom	Cause	Fix
Fast object passes through a wall	Step wider than the collider	CCD / bullet mode, higher rate, raycast
Objects vibrate or sink at rest	Too few solver iterations, restitution non-zero	Raise iterations, zero restitution, fixed step
Character sticks to walls	Friction on wall colliders	Lower friction, raycast ground check, beveled collider
Jump height varies, controls feel floaty	Player is a dynamic rigidbody	Kinematic / raycast character controller
Frame drops as scene grows	Broad phase overloaded, bodies not sleeping	Tight composite colliders, let bodies sleep
Replay or netcode desyncs	Variable timestep, input off the fixed step	Fixed timestep, process input in step

A diagnostic checklist you can run in minutes#

1. Debug draw on. Are the colliders what you think they are?
2. Isolate. Does the bug reproduce with one body on one surface?
3. Timestep. Is the simulation fixed, or tied to the frame rate?
4. Units. Are colliders in the 0.1–10 m range the engine expects?
5. Body type. Is each body static, kinematic or dynamic as its role demands?
6. Fast bodies. Do they have CCD on?
7. Resting contacts. Is restitution zero where things should rest?
8. Player. Is the player a rigidbody, or a controller?
9. Stale state. On restart, are bodies recreated or teleported?

Run this list against any physics bug and most are resolved before you reach the end of it.

How Egmatic fits#

Physics debugging lives or dies on the speed of the observe-change-observe loop. With a live preview, the scene keeps running while you change solver iterations, toggle a collider, or zero out restitution — so the moment you turn on debug draw and change a value, you see whether the bug is gone, without a build step. Physics events (collisions, contacts, triggers) are exposed as nodes, which makes it easy to add a temporary debug node that logs a contact or draws a velocity arrow without writing boilerplate. The engine underneath is cross-platform, so the physics you debug on desktop is the physics that ships on mobile and console. For the setup mistakes that cause these bugs in the first place, see 2D Physics Setup: 8 Common Mistakes That Break Your Game.

The bottom line#

There is no such thing as a random physics bug — only a symptom whose cause you have not yet read. Turn on debug draw, reproduce the bug in isolation, match the symptom to one of the six patterns, and apply the fix. Almost every case of tunneling, jitter, stuck objects, floaty control, frame drops and desync traces back to one of the setup mistakes covered here, and is fixable in minutes once you can see what the engine actually sees.