Bug Reporting for Games With Sanity Meters

Sanity meters are the heartbeat of psychological horror. As a player's sanity drops, the world should warp: hallucinations appear, audio distorts, the camera drifts, enemies behave strangely. Done right it is unforgettable; done wrong it is comedy. A jump scare fires while the player is perfectly calm, the screen stays warped after sanity recovers, or the meter never moves no matter what horrors the player walks through. Underneath is a value drained by fear and restored by safety, with thresholds that gate effects on and off. The bugs hide in those triggers and in cleaning up effects. This post is about capturing sanity state so a broken horror moment names its cause.

Sanity drives effects, and effects are stateful

A sanity meter is only interesting because it drives effects, and those effects are pieces of state that get turned on and must later be turned off. A hallucination spawns an entity, an audio filter is applied, a post processing effect is enabled. Each of these is an on switch that needs a matching off switch tied to the sanity value rising back above a threshold. The most common sanity bug is an effect that turns on correctly but never turns off, because the recovery path forgot to undo what the descent path did, leaving the player permanently haunted.

Because the effects are dramatic and the meter is hidden, players report the effect, not the value. They say the screen stayed distorted or a monster appeared that was not real, and they have no idea what their sanity reading was. This is exactly why the value must be captured automatically. The difference between a hallucination that fired correctly at low sanity and one that fired erroneously at high sanity is entirely in the sanity value at the trigger moment, which is the one number the player cannot see and you most need.

The sanity state to capture

Capture the current sanity value, the maximum, the active drain sources and their rates, the active restore sources, the threshold values for each tier of effect, and crucially the list of currently active sanity effects with the threshold each was triggered at. With that list you can immediately tell whether a running effect is consistent with the current value. An audio distortion active in the report while the sanity value sits near maximum is a smoking gun: either the effect failed to clear on recovery, or it triggered against the wrong value in the first place.

Capture a short event log of sanity transitions: effect triggered, effect cleared, threshold crossed downward, threshold crossed upward. Sanity bugs are largely about the matching of these transitions, so seeing them in order reveals an unmatched pair. A downward crossing that triggered an effect with no corresponding upward crossing clearing it explains the lingering distortion exactly. The event log converts the static snapshot into a narrative of how sanity moved and what each movement turned on or off, which is precisely the story needed to fix horror effect bugs.

Triggers firing at the wrong sanity

The first class of sanity bug is a trigger firing against the wrong value. Hallucination spawns are often gated on a threshold, but if the check reads a cached sanity value, or reads it before a restore is applied, an effect can fire when the player has actually recovered. Players find this jarring because the horror loses meaning when it is random. Capturing the sanity value the trigger actually evaluated, next to the threshold it required, makes the mismatch undeniable: the value is above the threshold yet the effect fired, so the trigger read stale or pre restore state.

Randomized triggers complicate this. Many sanity systems add a chance roll on top of the threshold so effects feel unpredictable, and a bug in the gating can let the roll happen regardless of sanity. Capturing both the sanity value and whether the threshold gate passed before the roll separates a tuning complaint from a logic bug. If the gate is recorded as passed while sanity was high, the gate compared wrong; if the gate failed but the effect fired anyway, the roll is running outside the gate. Either way the captured trigger context names which it is.

Effects that never clear

The second and more frustrating class is effects that never clear. When sanity recovers above the threshold that spawned an effect, every effect from that tier should be undone: hallucination entities despawned, filters removed, camera restored. If the recovery path only handles some effects, or runs once and misses effects added later, the player is left permanently impaired in a game that is supposed to reward finding safety. Capturing the active effect list with each effect's trigger threshold lets you compare against the current value and spot every effect that should have cleared but did not.

These cleanup bugs are especially common when effects are added from multiple code paths but removed from only one. A hallucination spawned by a scripted event and one spawned by the ambient sanity system might both need clearing, but only the ambient one is on the recovery path. The captured list shows both effects active with their sources, so you can see the scripted one has no cleanup owner. Centralizing effect cleanup so that crossing a threshold upward tears down everything triggered below it is the fix, and the captured list tells you what was being missed.

Setting it up with Bugnet

Bugnet's in-game report button captures game state automatically, so a horror report arrives with the sanity value and active effects attached rather than a player describing a scary screen. Serialize sanity into custom fields: current value, maximum, active drain and restore sources, the effect thresholds, and the list of currently active sanity effects with the threshold and source each was triggered at, plus a recent transition log. When a report says the screen stayed warped, you open it and an audio or visual effect is active while the sanity value reads near full, proving the recovery cleanup failed.

Occurrence grouping folds matching sanity reports into one issue with a count, so a cleanup bug that strands many players in permanent madness surfaces as a single prioritized entry instead of scattered horror complaints. You can filter by the effect type custom field to find every report involving a specific hallucination, and sort by occurrence to fix the most common stuck effect first. With the sanity value, the active effects, and the transition log in one dashboard, the bugs in your most atmospheric system become a precise read rather than a player trying to describe a feeling of dread.

Testing the descent and the recovery

The durable defense is testing both directions of the sanity curve against the captured state. Write tests that drive sanity down across each threshold and assert the correct effects trigger and read the live value, then drive it back up and assert every effect from each tier is fully cleared. Test effects that can be added from multiple sources and assert the upward crossing tears all of them down, since the asymmetry between many spawn paths and one cleanup path is the heart of these bugs. Because your reports serialize the effect list, any stuck effect replays into a test directly.

Add a test that holds sanity just above a threshold and asserts no effect fires, then just below and asserts it does, with the value read fresh at the moment of the check so stale reads cannot slip through. The teams that ship horror that actually lands are the ones who can observe the sanity value and the full set of active effects at any moment and replay them. When descent and recovery are both observable and tested, the jump scare at full sanity and the madness that never lifts both stop recurring, and your sanity meter keeps its menace intact.

Sanity effects are on switches that need off switches. Capture the value and the active effects and the haunting that never lifts names its missing cleanup.