Add Heavy Stun uptime and Crushing Blows

[515k4]

Fixes #834.

Description of the problem being solved:

"Is the enemy Heavy Stunned?" was a checkbox, so a modifier that only applies against Heavy Stunned enemies counted either on every hit or never. PoB already calculated the Heavy Stun buildup per hit, but only displayed it. "Your Hits are Crushing Blows" (Titan's Crushing Impacts) was unparsed. It adds no damage by itself: it makes the Heavy Stun come sooner, which the checkbox could not show.

What this PR changes

• Configuration: the checkbox becomes "Enemy Heavy Stun uptime" with None, 25%, 50%, 75%, 100% and Calculated. 100% does what the checkbox did: the enemy is Heavy Stunned, Stunned and Immobilised. Builds saved with the checkbox ticked load as 100%.
• Averaging: with 25% to 75% and Calculated, the offence calculations run once against a Heavy Stunned enemy and once against an enemy that is not, and every numeric output, including the per-weapon ones, is averaged by the uptime. This covers any modifier that depends on the Heavy Stun (more damage, always crit, lucky hits, cannot be evaded, gain as extra damage) without special cases. The calculation state (mod lists, skill data and flags, outputs, breakdowns) is saved before the first run and restored before the second, so mods that the offence code adds while it runs are not applied twice.
• Calculated uptime: D / (D + t), from the main skill's hits against an enemy that is not Heavy Stunned yet:
  • hits needed = ⌈100% / Heavy Stun buildup per hit⌉
  • t = hits needed / hits per second, where hits per second = attack or cast rate × DPS multiplier × quantity multiplier × hit chance
  • D = 2s (monster base_heavy_stun_duration_ms) × increased and more Stun Duration × (1 + chance to double Stun Duration) / (1 + enemy Stun Recovery)
• Crushing Blows: "Your Hits are Crushing Blows" and Syzygy's crushing_blow_vs_ignited_and_fully_armour_broken (only against Ignited and Fully Armour Broken enemies) are now parsed. A Crushing Blow Heavy Stuns an enemy that is Primed for Stun, at 40% buildup for normal, 60% for rare and 70% for unique enemies (poe2wiki: Primed for Stun). The hit after the one that Primes the enemy causes the Heavy Stun, so hits needed = min(⌈100% / buildup⌉, ⌈Primed threshold / buildup⌉ + 1).
• Calcs tab: new Hits to Heavy Stun, Heavy Stun Duration and Heavy Stun Uptime rows under Stun Buildup, with breakdowns. With 25% to 75% or Calculated, the uptime breakdown also lists the DPS against a Heavy Stunned and a normal enemy. The estimate is shown with None too, so it can be checked before switching. It is not shown at 100%, where the hits already include the bonuses against Heavy Stunned enemies.

Not in this PR

• Only the first Heavy Stun is modelled: the bar fills from zero and resets after the stun. The higher Stun threshold an enemy has for a while after being Heavy Stunned (HeavyStunThresholdModifier and HeavyStunModifierDuration in the game constants) is ignored, and so is buildup decay.
• The estimate uses only the selected skill's own hits. Buildup from other skills, or from another stat set of the same skill (such as Earthquake's Aftershocks), is not added.
• PoB has no setting for magic enemies, so they use the normal threshold (40%).
• Whether the hit that Primes the enemy can itself be the Crushing Blow is not documented. This PR assumes it cannot.
• With 25% to 75% and Calculated, the offence calculations run twice, so they take about twice as long. None and 100% run them once, as before.

Steps taken to verify a working solution:

• New spec/System/TestHeavyStun_spec.lua with 21 tests. They cover:
  • parsing of both Crushing Blow sources
  • loading the old checkbox, the dropdown's options, and 100% matching the old checkbox
  • averaging at 25%, 50% and 75%
  • no mods applied twice for an attack with Ruthless, a spell and a minion
  • the enemy left not Heavy Stunned after averaging
  • the calculated uptime: hits needed from the buildup, fewer hits with more buildup, less time with more attack speed, longer duration with increased and doubled Stun Duration, Crushing Blows against normal, rare and unique enemies, and the breakdowns
• With the state restore between the two runs disabled, 4 of them fail, including the Ruthless one: its Heavy Stun buildup mod is applied twice.
• Full suite passes (924 tests).
• ModCache regenerated. The only change is "Your Hits are Crushing Blows", which now parses.
• Headless comparison: a level 97 Titan Earthquake build against a Guardian/Pinnacle boss, with Crushing Impacts' two lines added as custom mods. 14.2% Heavy Stun buildup per hit, about 4 hits per second, 2s Heavy Stun. DPS of the Earthquake slam:

Enemy Heavy Stun uptime	Without Crushing Impacts	With Crushing Impacts
None	969,726	969,726
50%	969,726	1,090,301
100%	969,726	1,210,876
Calculated	969,726 (8 hits, 1.99s, 50.1% uptime)	1,107,803 (6 hits, 1.49s, 57.3% uptime)

Without Crushing Impacts nothing in this build depends on the Heavy Stun, so every option gives the same DPS.

Link to a build that showcases this PR:

N/A

Before screenshot:

After screenshot:

🤖 Generated with Claude Code