UnitAura

From Warcraft Wiki
Jump to navigation Jump to search

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" Auras Debuffs applied by the 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. shouldConsolidate (WoW Icon update.pngWrath-Logo-Small.png)
boolean - Whether to consolidate auras, only exists in Classic Era/Wrath.
...
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.
  • WoW Icon update.png The debuff limit is at 16 for Classic Era and 40 for BCC.
Related Events UNIT_AURA

World Buffs

WoW Icon update.png 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
17. Fengus' Ferocity number Duration
18. Mol'dar's Moxie number Duration
19. Slip'kik's Savvy number Duration
20. Rallying Cry of the Dragonslayer number Duration
21. Warchief's Blessing number Duration
22. Spirit of Zandalar number Duration
23. Songflower Serenade number Duration
24. Sayge's Fortune number Duration of the chosen buff
25. Sayge's Fortune number spellID of the chosen buff
26. Boon of Blackfathom number Duration
27. [Spark of Inspiration] number Duration
28. Fervor of the Temple Explorer number Duration

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")
/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

Dragonflight Patch 10.2.5 (2024-01-16): Deprecated. Replaced by C_UnitAuras.GetAuraDataByIndex.
WoW Icon update.png Patch 1.14.4 (2023-08-22): Added shouldConsolidate return value.
Shadowlands Patch 9.0.1 (2020-10-13): Added MAW filter.[1]
Battle for Azeroth Patch 8.0.1 (2018-07-17): Removed querying by name, and removed rank return value.
Legion Patch 7.0.3 (2016-07-19): Added nameplateShowAll and timeMod; shouldConsolidate changed to nameplateShowPersonal.
Mists of Pandaria 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.
Cataclysm Patch 4.2.0 (2011-06-28): Re-added the return values canApplyAura and isBossDebuff, and added return values value[1-3].
Cataclysm Patch 4.0.1 (2010-10-12): Removed the return values canApplyAura and isBossDebuff.
Wrath-Logo-Small.png Patch 3.3.0 (2009-12-08): Added shouldConsolidate and spellId.
Wrath-Logo-Small.png 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.
Wrath-Logo-Small.png Patch 3.0.2 (2008-10-14): Added UnitDebuff() and UnitBuff()

References

 
  1. ^ 2020-10-13, Blizzard_MawBuffs.lua, version 9.0.1.36230, near line 26, archived at Townlong-Yak