Automated updating of API pages at this location, to reflect patch changes, has ceased from 10.1.7 onwards. |
Returns the buffs/debuffs for the unit.
name, icon, count, dispelType, duration, expirationTime, source, isStealable, nameplateShowPersonal, spellId, canApplyAura, isBossDebuff, castByPlayer, nameplateShowAll, timeMod, ... = UnitAura (unit, index [, filter]) = UnitBuff (unit, index [, filter]) = UnitDebuff(unit, index [, filter])
Arguments[]
- unit
- string : UnitId
- index
- number - Index of an aura to query.
- filter
- string? - A list of filters, separated by pipe chars or spaces. Otherwise defaults to "HELPFUL".
Filters[]
- UnitBuff() is an alias for
UnitAura(unit, index, "HELPFUL")
, returning only buffs. - UnitDebuff() is an alias for
UnitAura(unit, index, "HARMFUL")
, returning only debuffs.
Filter | Description |
---|---|
"HELPFUL" | Buffs |
"HARMFUL" | Debuffs |
"PLAYER" | |
"RAID" | Buffs the player can apply and debuffs the player can dispell |
"CANCELABLE" | Buffs that can be cancelled with /cancelaura or CancelUnitBuff() |
"NOT_CANCELABLE" | Buffs that cannot be cancelled |
"INCLUDE_NAME_PLATE_ONLY" | Auras that should be shown on nameplates |
"MAW" | Torghast Anima Powers |
Returns[]
- Returns
nil
when there is no aura for that index or when the aura doesn't pass the filter.
- 1. name
- string - The localized name of the aura, otherwise nil if there is no aura for the index.
- 2. icon
- number : FileID - The icon texture.
- 3. count
- number - The amount of stacks, otherwise 0.
- 4. dispelType
- string? - The locale-independent magic type of the aura:
Curse, Disease, Magic, Poison
, otherwise nil. - 5. duration
- number - The full duration of the aura in seconds.
- 6. expirationTime
- number - Time the aura expires compared to GetTime(), e.g. to get the remaining duration:
expirationtime - GetTime()
- 7. source
- string : UnitId - The unit that applied the aura.
- 8. isStealable
- boolean - If the aura may be stolen.
- 9. nameplateShowPersonal
- boolean - If the aura should be shown on the player/pet/vehicle nameplate.
- 10. spellId
- number - The spell ID for e.g. GetSpellInfo()
- 11. canApplyAura
- boolean - If the player can apply the aura.
- 12. isBossDebuff
- boolean - If the aura was cast by a boss.
- 13. castByPlayer
- boolean - If the aura was applied by a player.
- 14. nameplateShowAll
- boolean - If the aura should be shown on nameplates.
- 15. timeMod
- number - The scaling factor used for displaying time left.
- 16+ ...
- Variable returns - Some auras return additional values that typically correspond to something shown in the tooltip, such as the remaining strength of an absorption effect.
Details[]
- UnitBuff() will ignore any HARMFUL filter, and vice versa UnitDebuff() will ignore any HELPFUL filter.
- Filters can be mutually exclusive, e.g.
"HELPFUL|HARMFUL"
will always return nothing. - On retail a unit can have an unlimited amount of buffs/debuffs.
- The debuff limit is at 16 for Classic Era and 40 for BCC.
Related Events | UNIT_AURA |
World Buffs[]
If the unit has the [Supercharged Chronoboon Displacer] buff, then the world buffs can be selected from the return values. For example for [Warchief's Blessing]:
select(20, UnitBuff("player", index))
Buff | Type | Description |
---|---|---|
16. Fengus' Ferocity | number | Duration |
17. Mol'dar's Moxie | number | Duration |
18. Slip'kik's Savvy | number | Duration |
19. Rallying Cry of the Dragonslayer | number | Duration |
20. Warchief's Blessing | number | Duration |
21. Spirit of Zandalar | number | Duration |
22. Songflower Serenade | number | Duration |
23. Sayge's Fortune | number | spellID of the chosen buff |
24. Sayge's Fortune | number | Duration of the chosen buff |
Example[]
- Prints the third aura on the target.
/dump UnitAura("target", 3)
[1] = "Power Word: Fortitude", -- name
[2] = 135987, -- icon
[3] = 0, -- count
[4] = "Magic", -- dispelType
[5] = 3600, -- duration
[6] = 112994.871, -- expirationTime
[7] = "player", -- source
[8] = false, -- isStealable
[9] = false, -- nameplateShowPersonal
[10] = 21562, -- spellID
[11] = true, -- canApplyAura
[12] = false, -- isBossDebuff
[13] = true, -- castByPlayer
[14] = false, -- nameplateShowAll
[15] = 1, -- timeMod
[16] = 5, -- attribute1: Stamina increased by 5%
[17] = 0 -- attribute2: Magic damage taken reduced by 0% (Thorghast Enchanted Shroud power)
- The following are equivalent. Prints the first debuff applied by the player on the target.
/dump UnitAura("target", 1, "PLAYER|HARMFUL") /dump UnitDebuff("target", 1, "PLAYER")
- GetPlayerAuraBySpellID() is useful for checking only a specific aura on the player character.
/dump GetPlayerAuraBySpellID(21562)
Aura Util[]
ForEachAura[]
AuraUtil.ForEachAura(unit, filter, [maxCount], func, [usePackedAura])
This is recommended for iterating over auras. For example to print all buffs:
AuraUtil.ForEachAura("player", "HELPFUL", nil, function(name, icon, ...)
print(name, icon, ...)
end)
The callback function should return true
once it's fine to stop processing further auras.
local function foo(name, icon, _, _, _, _, _, _, _, spellId, ...)
if spellId == 21562 then -- Power Word: Fortitude
-- do stuff
return true
end
end
AuraUtil.ForEachAura("player", "HELPFUL", nil, foo)
FindAuraByName[]
AuraUtil.FindAuraByName(name, unit [, filter])
Finds the first aura that matches the name, but note that:
- Aura names are not unique, this will only find the first match.
- Aura names are localized, what works in one locale might not work in another.
/dump AuraUtil.FindAuraByName("Power Word: Fortitude", "player")
- Remember to specify the "HARMFUL" filter for debuffs.
/dump AuraUtil.FindAuraByName("Weakened Soul", "player", "HARMFUL")
Patch changes[]
Patch 9.0.1 (2020-10-13): Added MAW
filter.[1]
Patch 8.0.1 (2018-07-17): Removed querying by name, and removed rank
return value.
Patch 7.0.3 (2016-07-19): Added nameplateShowAll
and timeMod
; shouldConsolidate
changed to nameplateShowPersonal
.
Patch 5.1.0 (2012-11-27): isCastByPlayer
moved from #17 to #14 after isBossDebuff
so that the value[1-n]
are at the end and can expand beyond 3 returns.
Patch 4.2.0 (2011-06-28): Re-added the return values canApplyAura
and isBossDebuff
, and added return values value[1-3]
.
Patch 4.0.1 (2010-10-12): Removed the return values canApplyAura
and isBossDebuff
.
Patch 3.3.0 (2009-12-08): Added shouldConsolidate
and spellId
.
Patch 3.1.0 (2009-04-14): Changed isMine
to unitCaster
. It is now possible for addons to retrieve the unitId that cast the buff/debuff.
Patch 3.0.2 (2008-10-14): Added UnitDebuff()
and UnitBuff()
References[]
- ^ 2020-10-13, Blizzard_MawBuffs.lua, version 9.0.1.36230, near line 26, archived at Townlong-Yak
|