The bug you can't screenshot

Most bugs you can point at. A button in the wrong place, a number that should be 5 and says 4, a page that won't load. You take a screenshot, you attach it, and the person fixing it sees what you saw. Sound doesn't work like that. When someone tells me a sound in Resonance is wrong, there's nothing to attach. They heard something, it didn't match what they expected, and by the time they've typed the message the moment is gone.

Resonance is a sound mod for RimWorld. It works out where every sound is coming from and what it has to pass through to reach you, walls, doors, distance, and then plays it quieter and duller to match. That's a lot of small decisions per sound, made several times a second, and any one of them can be off. "Footsteps go quiet indoors" could be the room geometry, the distance math, the wall it's routing through, or the game handing back a different number than the mod asked for. From the outside they all sound the same: quieter than it should be.

"It sounds wrong" is close to impossible to fix from a description. For a while I tried anyway, going back and forth with people, guessing, asking them to stand in the same spot and listen again. It mostly didn't work, and it wasn't because they were bad at describing it. The information I needed wasn't something a person can hear. I needed the numbers the mod was working with, and those only exist for a few milliseconds inside the program.

So I made the mod write them down. Press a key and Resonance dumps everything it knows at that instant into a text file: a small map of the rooms around you, drawn in characters, with walls and doors marked; a table of every room and how much sound leaks out of it, in decibels; and a line for every sound currently playing, showing its volume before and after the walls, the distance, and the corners it bent around. Under each one is a plain verdict, either "audible" or the exact reason it went silent.

The map is the part that surprised me most. It's how the mod sees your surroundings, which is not always how you see them. More than once someone reported a sound coming from the wrong place, I looked at the snapshot, and there was a wall in the grid that wasn't there in the game, or a door the mod thought was shut. The bug wasn't in the sound at all. It was in the geometry, two steps earlier, and I'd never have found it by listening.

There's a line in the snapshot for reverb now. There wasn't at first. For a long time it reported volume and muffling in detail and said nothing about reverb, so when someone told me the reverb had stopped working I had no way to check and could only guess. Adding the line took two minutes. It should have been there from the start, and the only reason it wasn't is that I hadn't yet been burned by its absence.

The lesson I keep relearning is that software should be able to explain itself. Not log everything all the time, which is just noise you have to dig through later. One command that makes the program say, in plain terms, what it currently believes and why. It turns "it sounds wrong" into "the mod thinks there's a wall here and there isn't," and those are completely different problems. The first one costs a week of back and forth. The second one you fix before lunch.