- Trigger API Reference\DCEI Functions\Ability
- IsUnitAbilityEnabled
- GetUnitAbilityCooldown
- GetAbilityCost
- UnitHasAbility
- UnitTypeHasAbility
- GetUnitAbilityCurrentCharge
- SetUnitAbilityCooldown
- SetUnitAbilityMaxCooldown
- CastAbilityAtUnit
- CastAbilityEffect
- CancelAbilities
- EnterTargetingMode
- ExitTargetingMode
- AddUnitAbility
- RemoveUnitAbility
- CastAbilityAtPosition
- CastAbilityEffectAtPosition
- SetAbilityCurrentCharge
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