---

Trigger API Reference\DCEI Functions\Ability

bool IsUnitAbilityEnabled(unit unit, string abilityName)

bool IsUnitAbilityEnabled(unit unit, string abilityName)

Description

Returns true if the ability is enabled on a unit.

Parameters

• unit unit the unit to check for ability status.
• string abilityName the name of the ability to check.

Example Usage

function SetAbilityButtonStatus(unit, ability, button)
    local enabled = DCEI.IsUnitAbilityEnabled(unit, ability)
    DCEI.SetButtonFrameEnable(button, enabled)
end

float GetUnitAbilityCooldown(unit unit, string abilityName)

float GetUnitAbilityCooldown(unit unit, string abilityName)

Description

Returns the remaining cooldown of a unit's ability.

Parameters

• unit unit the unit to check for ability cooldown.
• string abilityName the name of the ability to check.

Example Usage

function CooldownBonusObtained(unit, ability, reduction)
    local cooldown = DCEI.GetUnitAbilityCooldown(unit, ability)
    local reduced_cooldown = cooldown - reduction
    if reduced_cooldown > 0.0 then
        DCEI.SetUnitAbilityCooldown(unit, ability, reduced_cooldown)
    else
        DCEI.SetUnitAbilityCooldown(unit, ability, 0.0)
    end
end

AbilityCost GetAbilityCost(string abilityName)

AbilityCost GetAbilityCost(string abilityName)

Description

Returns the cost of an ability as a table.

Parameters

• string abilityName the name of the ability to get the cost of.

Example Usage

function OnAbilityUse()
    local id = DCEI.TriggeringAbilityId
    local name = DCEI.TriggeringAbilityName
    DCEI.LogMessage(name .. " use")
    local cost = DCEI.GetAbilityCost(name)
    for key, value in pairs(cost) do
        DCEI.LogMessage(key .. " : " .. value)
    end
end

DCEI.TriggerAddUseAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityUse)

bool UnitHasAbility(unit unit, string abilityName)

bool UnitHasAbility(unit unit, string abilityName)

Description

Returns whether a unit has an ability or not.

Parameters

• unit unit the unit to check for the ability.
• string abilityName the name of the ability to check for.

Example Usage

function ShowAbilityButton(unit, ability, button)
    local has_ability = DCEI.UnitHasAbility(unit, ability)
    DCEI.SetFrameActive(button, has_ability)
end

bool UnitTypeHasAbility(string unitType, string abilityName)

bool UnitTypeHasAbility(string unitType, string abilityName)

Description

Returns true if a unit type has an ability.

Parameters

• string unitType the unit type to check for the ability.
• string abilityName the name of the ability to check for.

Example Usage

function ShowUpgradeButton(unit_type, ability, button)
    local has_ability = DCEI.UnitTypeHasAbility(unit_type, ability)
    DCEI.SetFrameActive(button, has_ability)
end

int GetUnitAbilityCurrentCharge(unit unit, string abilityName)

int GetUnitAbilityCurrentCharge(unit unit, string abilityName)

Description

Returns the number of charges a unit has left for an ability.

Parameters

• unit unit the unit to check for charge count.
• string abilityName the name of the ability to check.

Example Usage

function SetAbilityButtonStatus(unit, ability, button)
    local charges = DCEI.GetUnitAbilityCurrentCharge(unit, ability)
    DCEI.SetButtonFrameEnable(button, charges)
end

void SetUnitAbilityCooldown(unit unit, string abilityName, float seconds)

void SetUnitAbilityCooldown(unit unit, string abilityName, float seconds)

Description

Sets the current remaining cooldown of an ability on a unit to a specified time in seconds.

Parameters

• unit unit the unit to set the ability's cooldown.
• string abilityName the name of the ability to set the cooldown for.
• float seconds the time in seconds to set the cooldown of the ability to.

Example Usage

function CooldownBonusObtained(unit, ability, reduction)
    local cooldown = DCEI.GetUnitAbilityCooldown(unit, ability)
    local reduced_cooldown = cooldown - reduction
    if reduced_cooldown > 0.0 then
        DCEI.SetUnitAbilityCooldown(unit, ability, reduced_cooldown)
    else
        DCEI.SetUnitAbilityCooldown(unit, ability, 0.0)
    end
end

void SetUnitAbilityMaxCooldown(unit unit, string abilityName, float seconds)

void SetUnitAbilityMaxCooldown(unit unit, string abilityName, float seconds)

Description

Sets the maximum cooldown of an ability on a unit to a specified time in seconds.

Parameters

• unit unit the unit to set the ability's maximum cooldown.
• string abilityName the name of the ability to set the maximum cooldown for.
• float seconds the time in seconds to set the maximum cooldown of the ability to.

Example Usage

function PermanentCooldownBonusObtained(unit, ability, reduction)
    local cooldown = DCEI.GetUnitAbilityCooldown(unit, ability)
    local reduced_cooldown = cooldown - reduction
    if reduced_cooldown > 0.0 then
        DCEI.SetUnitAbilityMaxCooldown(unit, ability, reduced_cooldown)
    else
        DCEI.SetUnitAbilityMaxCooldown(unit, ability, 0.0)
    end
end

void CastAbilityAtUnit(string abilityName, unit caster, unit target, bool immediate = False)

void CastAbilityAtUnit(string abilityName, unit caster, unit target, bool immediate = False)

Description

Issues the order for a unit to cast an ability targeting another unit. For an instant ability, this will ignore the target parameter and simply cast the ability.

Parameters

• string abilityName the name of the ability to cast.
• unit caster the unit to cast the ability.
• unit target the unit to target with the ability.
• bool immediate if true, the unit will attempt to cast the ability in the same frame that it's ordered, rather than queuing the command.

Example Usage

function OnSwordAttackButtonPressed(unit)
    DCEI.CastAbilityAtUnit(DCEI.Ability("Sword Swing"), unit, unit, true)
end

void CastAbilityEffect(string abilityName, unit caster, unit target)

void CastAbilityEffect(string abilityName, unit caster, unit target)

Description

Immediately casts the given ability's linked effect with the context provided. Unlike CastAbilityAtUnit, the unit does not need to have the ability bound in order for the effect to fire.

Parameters

• string abilityName the name of the ability to cast the effect of.
• unit caster the unit to cast the ability.
• unit target the unit to target with the ability.

Example Usage

function OnDoNothing()
    local context = DCEI.TriggeringEffectContext
    local ability_name = DCEI.Ability("Ability_Name")

    DCEI.CastAbilityEffect(ability_name, context.caster, context.target)
end

DCEI.TriggerAddEffectEvent(DCEI.Effect("DoNothing"), OnDoNothing, true)

void CancelAbilities(unit unit)

void CancelAbilities(unit unit)

Description

Cancels all ability orders a unit has queued.

Parameters

• unit unit the unit to cancel abilities for.

Example Usage

function Stop(unit)
    local position = DCEI.GetUnitPosition2D(unit)
    DCEI.CancelAbilities(unit)
    DCEI.Move(unit, position.x, position.y)
end

void EnterTargetingMode(unit unit, string abilityName)

void EnterTargetingMode(unit unit, string abilityName)

Description

Enters targeting mode for a unit's ability. Only works for targeted abilities.

Parameters

• unit unit the unit to enter targeting mode for.
• string abilityName the name of the ability to enter the targeting mode for.

Example Usage

function AbilityButtonPressed(unit, ability)
    DCEI.EnterTargetingMode(unit, ability)
end

void ExitTargetingMode()

void ExitTargetingMode()

Description

Exits targeting mode for any abilities currently in targeting mode.

Example Usage

function CancelButtonPressed()
    DCEI.ExitTargetingMode()
    DCEI.SelectUnit(hero)
end

void AddUnitAbility(string unitType, string abilityName)

void AddUnitAbility(string unitType, string abilityName)

Description

Adds an ability to a unit type.

Parameters

• string unitType the unit type to add the ability to.
• string abilityName the name of the ability to add.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local ability = DCEI.Ability("MyAbility")
DCEI.AddUnitAbility(unit_type, ability)

void RemoveUnitAbility(string unitType, string abilityName)

void RemoveUnitAbility(string unitType, string abilityName)

Description

Removes an ability from a unit type.

Parameters

• string unitType the unit type to remove the ability from.
• string abilityName the name of the ability to remove.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local ability = DCEI.Ability("MyAbility")
DCEI.RemoveUnitAbility(unit_type, ability)

void CastAbilityAtPosition(string abilityName, unit caster, float x, float z, bool immediate = False)

void CastAbilityAtPosition(string abilityName, unit caster, float x, float z, bool immediate = False)

Description

Issues the order for a unit to cast an ability targeting another unit. For an instant ability, this will ignore the target parameter and simply cast the ability.

Parameters

• string abilityName the name of the ability to cast.
• unit caster the unit which will cast the ability.
• float x the x-axis coordinate to cast the ability at.
• float z the z-axis coordinate to cast the ability at.
• bool immediate if true, the unit will attempt to cast the ability in the same frame that it's ordered, rather than queuing the command.

Example Usage

function OnFireballButtonPressed(unit)
    local facing = DCEI.GetUnitFacing2D(unit)
    local position = DCEI.GetUnitPosition2D(unit)
    local angle = math.atan(facing.y/facing.x)
    local target = {
        x = position.x + 2.0*math.cos(angle),
        z = position.y + 2.0*math.sin(angle)
    }
    DCEI.CastAbilityAtPosition(DCEI.Ability("Fireball"), unit, target.x, target.z, true)
end

void CastAbilityEffectAtPosition(string abilityName, unit caster, float x, float z)

void CastAbilityEffectAtPosition(string abilityName, unit caster, float x, float z)

Description

Immediately casts the given ability's linked effect at a location with the context provided. Unlike CastAbilityAtPosition(), the unit does not need to have the ability bound in order for the effect to fire.

Parameters

• string abilityName the name of the ability to cast the effect of.
• unit caster the unit to cast the ability.
• float x the X coordinate.
• float z the Z coordinate.

Example Usage

--Whenever a unit casts an ability, they instantly 'cast' a duplicate targeting (16, 16)
function OnAbilityCast()
    local unit = DCEI.TriggeringUnit
    local ability_name = DCEI.TriggeringAbilityName
    DCEI.CastAbilityEffectAtPosition(ability_name, unit, 16, 16)
end

DCEI.TriggerAddCastAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityCast)

void SetAbilityCurrentCharge(unit unit, string abilityName, int chargeCount, bool clampChargeCount)

void SetAbilityCurrentCharge(unit unit, string abilityName, int chargeCount, bool clampChargeCount)

Description

Sets the current number of charges for an ability on a unit.

Parameters

• unit unit the unit to set ability charges for.
• string abilityName the name of the ability to set the charges for.
• int chargeCount the number of charges to set the ability to.
• bool clampChargeCount if true, the number of charges is clamped to the maximum charge count set for the ability.

Example Usage

function BonusChargeEarned(unit, ability)
    local current_charges = DCEI.GetUnitAbilityCurrentCharge(unit, ability)
    DCEI.SetAbilityCurrentCharge(unit, ability, current_charges + 1, false)
end