HasHeightAdvantageOverride

Tracking Issue: #851

This feature allows mods to override whether a unit has height advantage over another unit, gaining various tactical benefits.

Normally this override would have been implemented as an event, but events in To Hit Chance Calculation logic can cause issues, see GetHitChanceEvents, so the delegates system is used instead.

How to use

Implement the following code in your mod's X2DownloadableContentInfo class:

static event OnPostTemplatesCreated()
{
    local CHHelpers CHHelpersObj;

    CHHelpersObj = class'CHHelpers'.static.GetCDO();
    if (CHHelpersObj != none)
    {
        CHHelpersObj.AddOverrideHasHeightAdvantageCallback(OverrideHasHeightAdvantage);
    }
}

// To avoid crashes associated with garbage collection failure when transitioning between Tactical and Strategy,
// this function must be bound to the ClassDefaultObject of your class. Having this function in a class that
// `extends X2DownloadableContentInfo` is the easiest way to ensure that.
static private function EHLDelegateReturn OverrideHasHeightAdvantage(XComGameState_Unit Attacker, XComGameState_Unit TargetUnit, out int bHasHeightAdvantage)
{
    // Optionally modify bHasHeightAdvantage here.
    // `bHasHeightAdvantage` is `0` if the `Attacker` does not have height advantage over the `TargetUnit`,
    // and `1` if height advantage is present.

    // Return EHLDR_NoInterrupt or EHLDR_InterruptDelegates depending on
    // if you want to allow other delegates to run after yours
    // and potentially modify bHasHeightAdvantage further.
    return EHLDR_NoInterrupt;
}

Delegate Priority

You can optionally specify callback Priority.

CHHelpersObj.AddOverrideHasHeightAdvantageCallback(OverrideHasHeightAdvantage, 45);

Delegates with higher Priority value are executed first. Delegates with the same Priority are executed in the order they were added to CHHelpers, which would normally be the same as DLCRunOrder. This function will return true if the delegate was successfully registered.

Removing Delegates

If necessary, it's possible to remove a delegate.

CHHelpersObj.RemoveOverrideHasHeightAdvantageCallback(OverrideHasHeightAdvantage);

The function will return true if the Callback was successfully deleted, return false otherwise.

Source code references