Bug Reporting for Games With Real-Time Shadows

Real-time shadows are where rendering quality goes to die a thousand small deaths. A player sends a screenshot of a wall covered in shimmering dark stripes, or a character whose shadow floats away from their feet, or a hard seam crawling across the ground as they walk. Each of these is a known shadow artifact with a known cause, but you cannot fix what you cannot reproduce, and shadow artifacts depend heavily on settings and hardware that differ from your dev machine. This post covers the rendering context you need to capture so shadow acne, peter-panning, flicker, and cascade seams become diagnosable bugs instead of vague visual complaints.

The shadow artifact zoo

Before you can triage shadow reports you need a shared vocabulary, because players describe the same artifact a dozen ways. Shadow acne is the self-shadowing stripe pattern on lit surfaces, caused by depth bias being too small for the surface angle. Peter-panning is the gap between an object and its shadow, the over-correction when bias is too large. Light leaking is shadow that fails to reach into a corner. Flicker and crawl appear when the shadow map updates as the camera moves. Cascade seams are visible bands where shadow map resolution steps down with distance.

Naming these precisely is not pedantry, it is the first triage step. Acne and peter-panning are two ends of one bias dial, so a report that mixes them tells you the bias is wrong in opposite directions on different geometry, which usually means a normal-offset or slope-scaled bias problem. Cascade seams point at split distances and resolution. Flicker points at update cadence or temporal stability. If your report form lets a player or your QA tag which artifact they saw, you have already narrowed the root cause before anyone opens the renderer.

Settings drive shadow behavior

A shadow artifact is rarely a pure bug; it is usually a setting that is wrong for a particular scene or hardware. Shadow map resolution, shadow distance, cascade count and split distances, depth bias and normal offset, and the filtering mode all combine to decide whether a surface shows acne or a shadow looks crisp. The same scene that looks perfect at your high preset can fall apart at the low preset a player picked to hit framerate. So the single most useful thing a shadow report can carry is the full set of shadow-related quality settings that were active.

Capture the quality preset by name and the individual overrides, because players love to mix presets with custom tweaks. Record shadow distance and cascade splits, since a seam that appears at twenty meters is a split-distance issue, not a bias issue. Note the bias values if they are exposed. With these fields attached, you can sort every acne report by preset and discover the artifact only appears below a certain shadow resolution, which immediately tells you whether to fix the bias formula or simply clamp the minimum resolution on that preset.

GPU, driver, and depth precision

Shadows are unusually sensitive to the GPU and driver because they lean on depth buffer precision and on how the hardware rasterizes and compares depth. Different vendors and drivers can produce subtly different depth values, so an acne pattern that never shows on your test card can be obvious on another. Depth buffer format and reversed-Z usage interact with precision in ways that change where bias needs to land. An integrated GPU may also silently reduce shadow resolution to keep up, producing seams that look like a bug but are really a thermal or performance fallback.

Because of this, every shadow report should stamp the GPU model, driver version, and the actual shadow resolution in use after any dynamic scaling. Without it you will test on your machine, see clean shadows, and close the report as not-reproducible while a quarter of your players keep hitting it. With it, you can filter the acne reports to one GPU family and confirm the precision theory, or notice the seams only appear when dynamic resolution has kicked the shadow map down. Hardware context turns an unreproducible shadow bug into a targeted one.

Camera angle and scene context

Shadow artifacts are viewpoint dependent, so the camera tells you a lot. Acne is worst on surfaces nearly parallel to the light, peter-panning is most visible when you look along a shadow, and cascade seams reveal themselves at the distances where splits occur. A report that captures the camera position, orientation, and field of view lets you stand exactly where the player stood and see exactly what they saw. Lacking that, you wander the level hoping to stumble onto the angle that triggers the stripe, which is a slow and demoralizing way to debug.

Scene context matters alongside the camera. The time of day or the dominant light direction decides the light-to-surface angle that drives acne. The objects in frame decide whether peter-panning shows. Whether other dynamic lights or a day-night cycle were active changes the picture too. Capturing the level, the light setup, and the camera transform with each shadow report gives you a deterministic recipe to reproduce, so the moment you load the same spot under the same light you are looking at the same broken shadow and can start tuning bias with confidence.

Setting it up with Bugnet

Bugnet captures the rendering context shadow bugs depend on without asking the player to know any of it. When someone hits the in-game report button next to a striped wall, the report automatically carries the quality preset, shadow distance, cascade configuration, GPU, driver, actual shadow resolution, and the camera transform. You add custom fields for bias values and a category tag for acne, peter-panning, leaking, flicker, or cascade seam. Instead of a lonely screenshot, you receive a full render config you can reproduce against, which is the entire battle with shadow artifacts.

Occurrence grouping then collapses the flood of look-alike shadow complaints into single counted issues. The fifty reports of crawling shadows on one GPU become one issue with a count of fifty, and you can immediately see it dwarfs the handful of peter-panning notes. You filter by GPU and preset to confirm a precision or dynamic-resolution cause, prioritize by occurrence, and after you ship a bias or resolution fix you watch the count flatten. One dashboard shows whether the seam tracked a setting or a hardware tier, which is the answer you actually needed.

A shadow regression checklist

Shadow tuning is fragile, so protect it with a deliberate test pass. For each supported quality preset, walk a few representative scenes at the angles that historically produced acne and peter-panning, and check the cascade transitions at their split distances. Test on at least one integrated GPU and one discrete card from each major vendor, because precision differences are real. Toggle dynamic resolution and confirm shadows degrade gracefully rather than seaming. Capture reference shots so you can diff future builds and catch a regression before it ships rather than after players report it.

Feed the player report stream back into that checklist so it grows where your real audience hits trouble. Every new acne cluster on a specific GPU becomes a permanent case in the pass, and every bias fix gets a regression shot so it cannot silently return when someone touches the lighting. Over a few releases you build a clear map of which presets and which hardware are fragile, and you tune shadows knowing where the edges are. That is how you ship crisp real-time shadows without each render change feeling like a roll of the dice.

Shadow artifacts come from settings and hardware, not pixels. Stamp the render config, GPU, and camera on every report and the stripes stop being mysterious.