Add events required for cover DR and point-blank bonuses

[DaloLorn]

Problem Overview

This used to be a very different issue before I realized I could just add a few event hooks instead of baking the intended feature directly into the Highlander. Several events will be needed, but for now, I'll write it as a single issue and break it up later if needed.

I want to change the ArmorMitigation value of an X2Effect_ApplyWeaponDamage on the fly, with access to at least the following information:

• Original mitigation value
• Unmitigated damage
• Armor piercing
• Source and target units
• Ability template
• Ability input context

I also want to change a unit's cover level against another unit, as seen by X2AbilityToHitCalc_StandardAim, with access to at least the following information:

• Original cover level
• Source and target units

Finally, I probably want to add extra flyovers to X2Action_ApplyWeaponDamageToUnit (or at least create the illusion of doing so). This might not require any Highlander changes, but I might need some advice to pull it off without using MCOs. Either way, the flyover must have ways to access:

• Cover level before the attack was executed. (My current, heavyweight draft doesn't know how to label the DR flyover if the cover was damaged/destroyed by the attack's environmental damage.)
• The results of the abovementioned ArmorMitigation event handler. (Its inputs are fine too, since they can be used to recalculate!)

Original Issue

Lately, I've been playing around with Anisotropic's Cover Damage Reduction mod, configuring it to something resembling Long War Rebalance's cover ruleset. However, where LWR's cover DR is (seemingly?) cleanly integrated into the game, Anisotropic's mod is... noticeably less so. Bluntly put, it's a heavy-handed mess with a tendency to reduce damage where it shouldn't, and neglects to factor the DR into damage previews in any way.

Proposed Solution

Events seem to be a valid approach to at least two of the three functions I require. I'm open to suggestions as to what the payloads should look like, though.

Original Solution

The core principle seems sound, but needs to properly integrate with Highlander's damage calculations. I will quickly summarize the intended behavior:

• All features are controllable by configs, and disabled by default.

• For most intents and purposes, cover DR is a dynamic source of extra armor. Armor-ignoring effects ignore cover, armor-piercing effects reduce its effects after the DR has first been calculated. (Something to consider, however: In my experience, damage previews don't account for armor when calculating the final value. Should there be another feature to make them do that? 🤔)

  • A config option could be provided to prevent cover DR from being subject to piercing.

• Cover is immune to shredding; cover DR prevents as much shred as it prevents damage.

• Cover DR is expressed using a set of three config values, provided separately for low and high cover:

  • Flat reduction, simply adding X DR when in cover.
  • Percentile reduction, expressed as a float typically in the 0-1 range, adds DR proportional to the incoming damage (e.g. LWR adds 50% DR when in high cover).
  • Maximum reduction, a total cap on how much DR can be received from a given cover level (to quote Anisotropic, "for those who don't want to see a cactus absorb an entire Sectopod cannon blast").

• If the abovementioned configs ever result in fractional DR, the fraction represents the probability of adding 1 DR. For instance, 2.5 DR would always reduce damage by 2 points, and have a 50% chance of reducing damage by another 1 point.

• A separate config flag controls whether cover DR affects AoE attacks, subject to the above rules.

  • By default, cover against AoEs will be evaluated as if the attacker were at the epicenter of the AoE. However, a config option can be provided to evaluate DR using the attacker's location. (If Anisotropic's comments are to be believed, this is how it worked in LW1.)

• Melee attacks are not subject to cover DR. A config option could be provided to disable this rule.

• At close range (exact distance in tiles configurable as a non-negative integer defaulting to 1), cover DR is disabled.

  • This is configurable separately for each cover type.
  • An extra config or pair of configs could be provided to disable cover defense, too. (Totally not adding hooks for LWR-esque behavior throughout the whole combat system while I'm here... 😂)

• By default, unflankable units are treated as not being in cover. However, as cover types are just an enum, a config could easily be provided to allow them to receive cover DR as if they were in either low or high cover. (Gross. Go just give extra armor or percentile DR to unflankable units like a civilized person.)

Can Self-Serve?

Mostly, I think, but some advice and review will be needed.

Original Estimate

I think so, but rigorous review may be advisable whenever I get around to opening a PR.

[DaloLorn]

... Okay, the proposal's actually fully written now.

[DaloLorn]

Rewrote the proposal as a set of event handlers, instead. The original proposal text is still available, but collapsed for readability.