Bug Reporting for Games With Hitscan Weapons

Hitscan weapons resolve a shot instantly with a ray trace, which sounds simple and produces some of the most disputed bugs in shooters. A player lines up a shot, fires, the reticle is dead on the enemy, and the game says miss. Or a shot that clearly hit a wall registers as a hit on an enemy beyond it. These come down to the geometry of one ray trace and, in multiplayer, to lag compensation reconciling where the target was when the shot was fired. From a clip you cannot see the actual ray or what it hit. The fix is to capture the trace and the registration state. This post covers what to record and why hit registration disputes need data, not video.

A hitscan shot is one ray trace

When a hitscan weapon fires, the game casts a ray from an origin in a direction and asks the physics system what it hit first. That single trace determines everything. Bugs arise when the ray is not where the player thinks it is, or when what it hit is not what the player saw. The origin is often the camera or the weapon muzzle, and those differ, so a shot can be visually centered yet trace from a point that clips a nearby edge. Capturing the actual ray origin and direction, separate from where the reticle appeared, is the first step to understanding why a shot missed.

The trace result is equally important: what collider the ray hit, at what point, at what distance, or whether it hit nothing. A reported miss might actually be a hit on a thin piece of cover the player did not notice, or on a hitbox that does not match the visible character model. Capturing the hit collider and point lets you compare what the ray hit against what the player intended to hit. The mismatch between the visual and the actual trace is the entire bug in most hitscan disputes, and it is invisible without recording both.

Hitboxes that do not match the model

A frequent hitscan bug is a hitbox that does not match the character it represents. The animated model leans, crouches, or plays a hit reaction while the collision capsule stays upright or lags behind, so the ray passes through the visible head but misses the hitbox, or hits empty space the model has left. Capturing the hit collider and the target's animation state at fire time reveals these mismatches. When a player reports a clear headshot that missed, comparing the head bone position with the head hitbox position at that frame usually shows the hitbox was somewhere the model was not.

Per-bone hitboxes that follow animation are the fix, but they introduce their own bugs when the hitbox update lags a frame behind the render pose, which is exactly the case worth capturing. Record the positions of the relevant hitboxes at the moment of the trace, and ideally the render pose too, so you can see whether they agreed. This is also where capturing the target's velocity helps, because a fast-moving target with a one-frame hitbox lag can be visibly displaced from its collision. The data tells you whether to fix the hitbox interpolation or accept a small grace and widen the box.

Lag compensation in multiplayer

In a networked shooter, hit registration is dominated by lag compensation. The shooter sees targets where they were a moment ago, accounting for their own latency, so when they fire the server must rewind those targets to the position the shooter saw before testing the ray. Bugs proliferate here: the rewind uses the wrong timestamp, the interpolation between snapshots is off, or the rewind window is too short for high-latency players. The result is the classic I shot them dead on and it did not count. To debug it you must capture the shooter's latency, the timestamp used for the rewind, and the target positions both as the shooter saw them and as the server rewound them.

Capturing both client and server views of the same shot is what makes these bugs tractable. The client knows where it drew the target and where it aimed; the server knows where it rewound the target and what the authoritative trace hit. Logging both, keyed to the same shot, lets you line them up and find the discrepancy: the server rewound to a slightly different position, or the client extrapolated the target ahead and the server did not. Without both views you only have a player insisting the shot was good, which it was on their screen, while the server disagreed for a reason you cannot see.

Make traces deterministic and inspectable

Hit registration is hard to reproduce live but very inspectable if you capture the trace. Build a debug mode that records every shot: the ray origin and direction, the trace result, the hit collider and point, the target hitbox positions, and in multiplayer the rewind timestamp and both client and server target positions. Then you can replay a reported shot by drawing the exact ray and the hitboxes as they were, and the miss or the wrong hit becomes visually obvious. A debug draw of the ray persisting in the world for a second after each shot is one of the cheapest, most useful tools a shooter can have.

On the server side, log the lag compensation rewind so you can audit it after the fact. Store, for a short window, the timestamp each shot rewound to and the resulting target positions, so when a registration dispute arrives you can confirm whether the rewind was correct. Where you can, make the trace itself deterministic given its inputs so a captured shot replays identically. With the ray, the hitboxes, and the rewind all captured, a hit registration complaint stops being a he-said-she-said and becomes a specific, examinable trace that either reveals a bug or confirms the shot genuinely missed.

Setting it up with Bugnet

Bugnet's in-game report button captures device and platform context automatically, and for hitscan it captures the network context that hit registration depends on. You add custom fields for the ray origin and direction, the trace result and hit collider, the target hitbox positions at fire time, the shooter's latency, and the lag compensation rewind timestamp. Because the button snapshots state when a player reports a shot that should have hit, you receive the actual trace and the registration data from that shot, not a clip where the reticle looked centered. That snapshot turns a registration dispute into an examinable trace.

Occurrence grouping shows which hit registration problems are systemic. If shots on crouching enemies consistently miss, Bugnet folds those reports into one issue with a count, pointing at a crouch hitbox that lags the pose rather than a string of unrelated complaints. Filter by latency band using a custom field to find lag compensation failures concentrated among high-ping players, filter by weapon or by target action, and keep every trace snapshot in one dashboard. Hit registration is the most argued-about topic in any shooter community, and captured traces plus grouping turn that argument into prioritized, fixable bugs.

Earn trust with honest hit reg

Players forgive a lot, but they do not forgive a shooter where shots do not land, because it makes the game feel like it is lying to them. Use the captured traces and rewind logs to tune your lag compensation window against the latency distribution your players actually have, to fix hitboxes that drift from their poses, and to align the visual reticle with the real trace origin. When you fix a registration bug, save the captured shot as a regression test that replays the ray against the recorded hitboxes and asserts the expected hit, so a netcode or animation change cannot quietly break hit reg again.

Treat each shot as a deterministic trace whose outcome is a function of the ray, the hitboxes, and the lag compensation, all of which you can capture and replay. Once reports carry the trace and registration data, you build shot logging and rewind auditing, and you grow a test suite of corrected shots, the endless your hit reg is broken complaints become specific bugs in hitboxes, trace origins, or rewind logic. Players feel a shooter that registers honestly, you can prove when a shot truly missed, and you can evolve the netcode and animations with confidence that the data will catch any regression.

A hitscan shot is one ray trace plus lag comp. Capture the ray, the hitboxes, and the rewind and hit-reg disputes become examinable traces.