So, how does firearm aiming work internally?

While looking into #27321, I got really confused by the relationship between steadiness, dispersion, recoil and aim. Notably, static int print_aim(...) in ranged.cpp

There is a recoil player variable that has a magic maximum of 3000, gets reset to this maximum when player moves / etc. and slowly decreases when skipping turns in aiming UI. That doesn’t really make any sense, since recoil is how hard your gun kicks you when you fire. There is also a fun fact that aiming somewhere far away, skipping turns, then aiming closer and skipping turns again gives you lower recoil value then aiming closer from the start.

Then there is dispersion value that comes from weapon & the player (perception, eye/arm encumbrance, bonuses from bionics, weapon stats) - seems straightforward. It comes and… renames into recoil… then transforms to steadiness…?

There are also ‘aim types’, provided by the character. There may be 1, 2 or 3 of them and they are, as I understand, just a fancy names for ‘precision thresholds’ with the latest being the most accurate. They are used for accuracy prediction & aiming automation in aiming UI. But you sort-of cannot reach these thresholds, with them always saying ‘15 moves to fire’… Does this mean, like, ‘15 moves to pull the trigger’?

You also cannot reach precise aim when aiming at a tile without a creature, which is, apparently, intended behavior (#38502)… I get how shooting, say, a nail gun at a zombie hulk has better success chance than shooting the floor tile beneath it, and trying to shoot a floor tile is more likely than shooting a rat. And ‘steadiness’, i.e. how good is your grip on the gun, does not equal how precise you aim it - only how your aim will decrease from shooting… But why can’t you reach ‘precise’ aim when aiming at a floor? Or at a refrigerator?

I didn’t found any docs on this, and the discourse threads are talking about general UI/balance stuff, not the mechanics… Plz help