---

Trigger API Reference\DCEI Events\Ability

Ability Events Overview

The order of phases for abilities and their corresponding events are as follows:

1. Ability Starts (via trigger or button)
2. Enter Target Mode (TriggerAddActivateAbilityEvent())
3. Exit Target Mode (TriggerAddDeactivateAbilityEvent())
4. Queued
5. Prep Time Start
6. Prep Time End
7. Cast (TriggerAddCastAbilityEvent())
8. Finish Time Start
9. Finish Time End (TriggerAddUseAbilityEvent())
10. Cooldown Start (TriggerAddUnitAbilityOnOffEvent())
11. Cooldown End (TriggerAddUnitAbilityOnOffEvent())
    

TriggerHandle TriggerAddCastAbilityEvent(unit unit, TypedCallback<unit, Float2> trigger, bool simple = False, AbilityFilter filter = default)

TriggerHandle TriggerAddCastAbilityEvent(unit unit, TypedCallback<unit, Float2> trigger, bool simple = False, AbilityFilter filter = default)

Description

This event triggers when an ability has completed its cast. This function can also pass the target unit and target location as parameters to the callback function (if target is only a location, target unit will return nil). You can also set up an Ability Filter to make this only trigger for certain ability.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<unit, Float2> trigger the callback function that is run when the event is triggered.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not use DCEI.Wait().
• AbilityFilter filter this filter allows you to only trigger this event on certain abilities

Callback Parameters

• Unit target_unit
• Float2 target_position

Example Usage

function OnAbilityCast(target_unit, target_pos)
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local ability_name = DCEI.TriggeringAbilityName
    DCEI.LogMessage(unit_name .. " casts " .. ability_name)

    local target_name = DCEI.GetUnitType(target_unit)
    DCEI.LogMessage("Target: " .. target_name .. " at (" .. target_pos.x .. ", " .. target_pos.y .. ")")
end
DCEI.TriggerAddCastAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityCast, true)

TriggerHandle TriggerAddUseAbilityEvent(unit unit, TypedCallback<unit, Float2> trigger, bool simple = False, AbilityFilter filter = default)

TriggerHandle TriggerAddUseAbilityEvent(unit unit, TypedCallback<unit, Float2> trigger, bool simple = False, AbilityFilter filter = default)

Description

This event triggers when an ability exits the finish phase. This function can also pass the target unit and target location as parameters to the callback function (if target is only a location, target unit will return nil). You can also set up an Ability Filter to make this only trigger for certain ability.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<unit, Float2> trigger the callback function that is run when the event is triggered.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not use DCEI.Wait().
• AbilityFilter filter this filter allows you to only trigger this event on certain abilities

Callback Parameters

• Unit target_unit
• Float2 target_position

Example Usage

function OnAbilityCast(target_unit, target_pos)
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local ability_name = DCEI.TriggeringAbilityName
    DCEI.LogMessage(unit_name .. " casts " .. ability_name)

    local target_name = DCEI.GetUnitType(target_unit)
    DCEI.LogMessage("Target: " .. target_name .. " at (" .. target_pos.x .. ", " .. target_pos.y .. ")")
end
DCEI.TriggerAddUseAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityCast, true)

TriggerHandle TriggerAddActivateAbilityEvent(unit unit, TypedCallback trigger, bool simple = False, AbilityFilter filter = default)

TriggerHandle TriggerAddActivateAbilityEvent(unit unit, TypedCallback trigger, bool simple = False, AbilityFilter filter = default)

Description

This event triggers when an ability activates. You can also set up an Ability Filter to make this only trigger for certain ability.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback trigger the callback function that is run when the event is triggered.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not use DCEI.Wait().
• AbilityFilter filter this filter allows you to only trigger this event on certain abilities

Example Usage

function OnAbilityActivate()
    local ability_name = DCEI.TriggeringAbilityName
    DCEI.LogMessage("Ability " .. ability_name .. "activated!")
end
DCEI.TriggerAddActivateAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityActivate, true)

TriggerHandle TriggerAddUnitAbilityOnOffEvent(unit unit, TypedCallback<bool> trigger, bool simple = False, AbilityFilter filter = default)

TriggerHandle TriggerAddUnitAbilityOnOffEvent(unit unit, TypedCallback<bool> trigger, bool simple = False, AbilityFilter filter = default)

Description

This event triggers when an ability goes on or off cooldown. For abilities with charges, the event will only trigger when the charge count decreases to 0 or increases to at least 1.

The first parameter of the callback function is a boolean that indicates whether the ability has become available (true) or unavailable (false).

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<bool> trigger the callback function that is run when the event is triggered. This first parameter of this function will return true when the ability goes off cooldown and false when the ability enters cooldown.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not use DCEI.Wait().
• AbilityFilter filter this filter allows you to only trigger this event on certain abilities

Callback Parameters

• Boolean is_on

Example Usage

function OnAbilityOnOff(is_ready)
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local ability_name = DCEI.TriggeringAbilityName
    local state = is_ready and "on" or "off"

    DCEI.LogMessage(ability_name .. " is now ".. state .. " for " .. unit_name)
end

DCEI.TriggerAddUnitAbilityOnOffEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityOnOff, true)

Related

• TriggeringAbilityID
• TriggeringAbilityName
• TriggeringUnit
• UnitAny
  

TriggerHandle TriggerAddUnitAbilityOnEvent(unit unit, TypedCallback<bool> trigger, bool simple = False, AbilityFilter filter = default)

TriggerHandle TriggerAddUnitAbilityOnEvent(unit unit, TypedCallback<bool> trigger, bool simple = False, AbilityFilter filter = default)

Description

This event triggers when an ability goes on cooldown.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<bool> trigger the callback function that is run when the event is triggered. This first parameter of this function will return true when the ability goes off cooldown and false when the ability enters cooldown.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not use DCEI.Wait().
• AbilityFilter filter this filter allows you to only trigger this event on certain abilities

Callback Parameters

• Boolean is_on

Example Usage

function OnAbilityOn()
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local ability_name = DCEI.TriggeringAbilityName

    DCEI.LogMessage(ability_name .. " is now on for " .. unit_name)
end

DCEI.TriggerAddUnitAbilityOnEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityOn, true)

TriggerHandle TriggerAddUnitAbilityOffEvent(unit unit, TypedCallback<bool> trigger, bool simple = False, AbilityFilter filter = default)

TriggerHandle TriggerAddUnitAbilityOffEvent(unit unit, TypedCallback<bool> trigger, bool simple = False, AbilityFilter filter = default)

Description

This event triggers when an ability goes off cooldown.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<bool> trigger the callback function that is run when the event is triggered. This first parameter of this function will return true when the ability goes off cooldown and false when the ability enters cooldown.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not use DCEI.Wait().
• AbilityFilter filter this filter allows you to only trigger this event on certain abilities

Callback Parameters

• Boolean is_on

Example Usage

function OnAbilityOnOff()
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local ability_name = DCEI.TriggeringAbilityName

    DCEI.LogMessage(ability_name .. " is now off for " .. unit_name)
end

DCEI.TriggerAddUnitAbilityOffEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityOnOff, true)

TriggerHandle TriggerAddDeactivateAbilityEvent(unit unit, TypedCallback trigger, bool simple = False, AbilityFilter filter = default)

TriggerHandle TriggerAddDeactivateAbilityEvent(unit unit, TypedCallback trigger, bool simple = False, AbilityFilter filter = default)

Description

This event triggers when an ability exits targeting mode for the unit.

Note: This is event is triggered regardless of method by which the targeting mode was exited, whether it was canceled or a target was set.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback trigger the callback function that is run when the event is triggered.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not use DCEI.Wait().
• AbilityFilter filter this filter allows you to only trigger this event on certain abilities

Example Usage

function OnAbilityDeactivate()
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local ability_name = DCEI.TriggeringAbilityName
    DCEI.LogMessage(unit_name .. " has exited the targeting mode for " .. ability_name)
end

DCEI.TriggerAddDeactivateAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityDeactivate, true)

Related

• TriggeringAbilityID
• TriggeringAbilityName
• TriggeringUnit
• UnitAny
  

void TriggerRemoveDeactivateAbilityEvent(TriggerHandle handle)

void TriggerRemoveDeactivateAbilityEvent(TriggerHandle handle)

Description

Removes a trigger created from TriggerAddDeactivateAbilityEvent.

Parameters

• TriggerHandle handle a reference to the trigger to be removed.

Example Usage

local trigger = nil

function OnAbilityDeactivate()
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local ability_name = DCEI.TriggeringAbilityName
    DCEI.LogMessage(unit_name .. " has exited the targeting mode for " .. ability_name)

    -- Execute once, then remove.
    DCEI.TriggerRemoveDeactivateAbilityEvent(trigger)
end

trigger = DCEI.TriggerAddDeactivateAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityDeactivate, true)