[script]DisarmUtils

//! zinc
library DisarmUtils requires TimerUtils, AutoIndex {
/**
 *      This is just a simple snippet that is meant to make disarming easier,
 *   and does so by taking advantage of the Cargo Hold ability.
 *   It also provides responses that are evaluated when a unit is effectively
 *   disarmed or rearmed. It should be noted that the responses will only be
 *   evaluated through the use of this snippet's functions. Achieving the same
 *   effects by other means will not result in the evaluation of any response.
 *
 *   It requires the latest version of JassHelper and the AutoIndex and TimerUtils libraries. 
 *   
 *   Credits go to:
 *      1. BBQ for writing the DisarmUtils snippet.
 *      2. grim001 for his AutoIndex library.
 *      3. Vexorian for his TimerUtils library, Zinc and JassHelper.
 *      4. PitzerMike for his WarCraft III Ability Guide.
 *      5. All of the contributors to the Jass NewGen Pack.
 *
 *   The functions provided by this snippet are as follows:
 *
 *      - function Disarm takes unit whichUnit returns nothing
 *           This function disarms a unit, which means that the unit will no longer
 *           be able to perform normal attacks. It is fully multi-instanceable as long 
 *           as the unit has been indexed by AutoIndex.
 *
 *      - function Rearm takes unit whichUnit returns nothing
 *           This function rearms a unit, which means that it will be able to perform
 *           normal attacks again. It is fully multi-instanceable as long as the unit 
 *           has been indexed by AutoIndex.
 *      
 *      - function TimedDisarm takes unit whichUnit, real duration returns nothing
 *           This function is used to disarm a unit for a specified duration.
 *
 *      - function IsUnitDisarmed takes unit whichUnit returns boolean
 *           Checks if a unit is disarmed. In order for this function to work as it
 *           should, it is advised that you perform all the disarming in your map
 *           by using this snippet's functions.
 *
 *      - function OnUnitDisarmed takes response whichResponse returns nothing
 *           The "response" function or static method will be evaluated when a unit is 
 *           effectively disarmed. Note that it needs to take unit and return nothing. 
 *           The unit it takes is the unit that was disarmed.
 *      
 *      - function OnUnitRearmed takes response whichResponse returns nothing
 *           The "response" function or static method will be evaluated when a unit is 
 *           effectively rearmed. Again, it needs to take unit and return nothing. 
 *           The unit it takes is the unit that was rearmed.
 *
 *       Disarming units via Cargo Hold is much better than using Drunken Haze or other similar
 *   abilities. The only downside is that you cannot disable melee or ranged attacks separately.
 *
 *       If for some reason you do not wish to use the default Cargo Hold ability,
 *   then feel free to edit the constant below.
 */
    type response extends function(unit);
    
    constant integer CARGO_HOLD = 'Abun';

    integer disarmResponses_n = 0, rearmResponses_n = 0, disarmCounter[];
    response disarmResponses[], rearmResponses[];
    
    //! textmacro DisarmUtils__runEvents takes which
        for (n = 1; n <= $which$Responses_n; n += 1) {   
            $which$Responses[n].evaluate(whichUnit);
        }
    //! endtextmacro
    
    public function OnUnitDisarmed(response whichResponse) {
        disarmResponses_n += 1;
        disarmResponses[disarmResponses_n] = whichResponse;
    }

    public function OnUnitRearmed(response whichResponse) {
        rearmResponses_n += 1;
        rearmResponses[rearmResponses_n] = whichResponse;
    }

    public function Disarm(unit whichUnit) {
        integer index, n;
        if (IsUnitIndexed(whichUnit)) {
            index = GetUnitId(whichUnit);
            if (disarmCounter[index] == 0) {
                UnitAddAbility(whichUnit, CARGO_HOLD);
                UnitMakeAbilityPermanent(whichUnit, true, CARGO_HOLD);
                //! runtextmacro DisarmUtils__runEvents("disarm")
            }
            disarmCounter[index] += 1;
        }
        else {
            UnitAddAbility(whichUnit, CARGO_HOLD);
            UnitMakeAbilityPermanent(whichUnit, true, CARGO_HOLD);
        }
    }

    public function Rearm(unit whichUnit) {
        integer index, n;
        if (IsUnitIndexed(whichUnit) && GetUnitAbilityLevel(whichUnit, CARGO_HOLD) > 0) {
            index = GetUnitId(whichUnit);
            disarmCounter[index] -= 1;
            if (disarmCounter[index] <= 0) {
                UnitRemoveAbility(whichUnit, CARGO_HOLD);
                disarmCounter[index] = 0;
                //! runtextmacro DisarmUtils__runEvents("rearm")
            }
        }
        else UnitRemoveAbility(whichUnit, CARGO_HOLD);
    }

    struct disarmData {
        unit disarmedUnit;
    }

    public function TimedDisarm(unit whichUnit, real duration) {
        disarmData data;
        timer durationTimer;
        if (duration <= 0.0) {
            Disarm(whichUnit);
            Rearm(whichUnit);
        }
        else {
            Disarm(whichUnit);
            durationTimer = NewTimer();
            data = disarmData.create();
            data.disarmedUnit = whichUnit;
            SetTimerData(durationTimer, integer(data));
            TimerStart(durationTimer, duration, false, function() {
                disarmData data = disarmData(GetTimerData(GetExpiredTimer()));
                Rearm(data.disarmedUnit);
                data.disarmedUnit = null;
                data.destroy();
                ReleaseTimer(GetExpiredTimer());
            });
            durationTimer = null;
        }
    }
    
    public function IsUnitDisarmed(unit whichUnit) -> boolean {
        return (GetUnitAbilityLevel(whichUnit, CARGO_HOLD) > 0);
    }

    function onInit() {
        OnUnitDeindexed(function(unit leavingUnit) {
            disarmCounter[GetUnitId(leavingUnit)] = 0;
            /* Since AutoIndex recycles its indices, we need to reset the counter as well. */
        });
    }
}
//! endzinc