Bug Reporting for Games With Physics Vehicles

Everyone who has shipped a physics vehicle knows the report: the car touched a tiny bump and rocketed into orbit. Vehicle physics is a delicate negotiation between a chassis rigidbody, a set of wheels probing the ground with raycasts, suspension springs pushing back, and a contact solver resolving collisions, all running every fixed timestep. When it goes wrong it usually goes wrong in a single frame, an impulse spike that flips, launches, or buries the vehicle before anyone can react. This post is about capturing the chassis, wheel, suspension, and contact state around that frame so the launch becomes reproducible instead of a legendary clip with no cause.

Vehicle physics is a multi-body negotiation

A typical arcade or sim vehicle is not one object but a system: a central rigidbody for the chassis, wheels that cast rays or sweep shapes to find the ground, suspension that applies spring and damper forces based on compression, and friction models that turn wheel slip into traction. Each frame the solver gathers contacts, computes forces, and integrates motion. The vehicle feels stable only because all these pieces agree. A bug is usually one piece disagreeing for a frame, producing a force the others did not expect.

The launch-to-the-moon classic is the signature of this disagreement. A wheel raycast misses the ground for one frame, the suspension reads maximum extension, then the next frame the wheel finds geometry deep inside a surface, the suspension reads huge compression, and it answers with an enormous corrective impulse. The chassis takes off. None of this is visible at human timescales, so the player only sees the result. To debug it you must capture the per-wheel and per-body state across the few frames where the disagreement happened.

The physics state worth capturing

For each report, capture the chassis state first: position, orientation, linear and angular velocity, and any external forces queued that frame. Then capture per-wheel state: raycast hit or miss, hit distance and surface, suspension compression and the spring and damper forces it produced, contact normal, and slip values for friction. Finally capture the collision context: which colliders touched, penetration depth, and the impulses the solver applied. Together these explain any sudden motion, because a launch is always a large impulse, and the snapshot shows exactly which body and which contact produced it.

The key is timing. The frame where the car is already airborne tells you nothing useful, because the cause was one or two frames earlier when a raycast flickered or a contact resolved deep. Keep a small ring buffer of physics snapshots, a dozen fixed frames or so, and dump the whole buffer when a report fires or when an automatic guard detects an implausible velocity. The buffer captures the run-up to the event, which is where the actual bug lives, rather than just the spectacular aftermath.

Reproducing a launch or flip

With the buffered state you can reconstruct the incident. Reset the chassis and wheels to the state from the first buffered frame, including velocities, then step the physics with the same fixed timestep and watch the same impulse spike develop. Determinism matters here: if your physics is not deterministic, set a fixed timestep, pin the solver iteration count, and avoid frame-rate-dependent forces, otherwise the replay drifts and you chase a different bug. A deterministic replay turns a once-in-a-thousand launch into something you can step through frame by frame.

Often the replay reveals a geometry problem rather than a physics-engine problem: a collider with a sliver of overlap, a seam between two surfaces where the raycast falls through, or a mesh with a flipped normal that the wheel reads as a wall. Other times it is a tuning issue, suspension that is too stiff to absorb the correction, or a missing clamp on suspension force. Either way, seeing the impulse build in a stepped replay points you straight at the wheel, the contact, or the surface responsible, instead of guessing from a wobbly video.

Common vehicle physics failure modes

The recurring offenders are raycast flicker at surface seams and edges, where the ground detection toggles between hit and miss; suspension force spikes when compression jumps in a single frame; and friction blowups where slip goes to extremes and the friction model produces NaN or a giant lateral force. Add tunneling at high speed, where the chassis passes through thin geometry because the solver only checks discrete positions, and stacking instabilities when a vehicle rests on another physics body. Each has a clear signature in the per-wheel and contact logs.

NaN propagation deserves its own mention because it is so destructive. One bad division, often from a zero-length vector in the friction or suspension math, poisons a velocity, and within a frame the entire vehicle state is NaN and the car vanishes or teleports. A snapshot that includes the per-component values lets you find the exact quantity that went non-finite and trace back to the operation that produced it. Guarding against NaN and clamping suspension and friction forces prevents the most spectacular and most reported failures outright.

Setting it up with Bugnet

Bugnet's in-game report button is perfect for the moon-launch moment, because the player will absolutely press it after their car flies off the map. The SDK attaches the physics context you buffer: the chassis velocity history, per-wheel raycast and suspension state, and the contact impulses from the frames around the event. Better still, you can fire a report automatically when a velocity guard detects an implausible spike, so you capture the incident even when the player is laughing too hard to file it. The buffer arrives in your dashboard ready to replay.

Physics launches at a specific track location tend to repeat for everyone who drives there, so the same seam or bad collider generates a flood of similar reports. Bugnet groups these by occurrence, and with the location or surface id as a custom field you can see that two hundred launches all happened at one corner. That count makes prioritization obvious and points your level artist at the exact geometry to fix. One grouped issue with a replayable buffer beats sifting through two hundred hilarious but unactionable clips in a community channel.

Testing and hardening vehicle physics

Build a deterministic physics test bench that drives vehicles over a battery of nasty geometry: seams, steep edges, thin walls at speed, ramps, and rest-on-body scenarios. Assert that velocity never exceeds a plausible cap, that no state goes non-finite, and that suspension and friction forces stay within clamps. Run it headless in CI so a change to your collision meshes or physics tuning that reintroduces launches fails the build instead of shipping. The captured buffers from real reports become fixtures that replay the exact failures players found.

Beyond automated tests, add runtime guards in the shipping build: clamp suspension and friction force magnitudes, reject NaN by resetting the affected body to its last good state, and cap velocity so a glitch produces a bump instead of an orbital launch. These guards both protect players and generate clean automatic reports when they trigger. The pairing of deterministic replay, geometry-stress tests, and runtime clamps keeps physics vehicles fun and predictable, while turning the rare remaining glitch into a captured, reproducible, fixable event.

A car going to the moon is a one-frame impulse spike. Buffer the per-wheel and contact state and you can replay the launch instead of just admiring the clip.