API UnitAura
From Wowpedia
Returns information about a buff or debuff on the specified unit.
name, rank, icon, count, debuffType, duration, expirationTime, unitCaster, canStealOrPurge, nameplateShowPersonal, spellId, canApplyAura, isBossDebuff, isCastByPlayer, nameplateShowAll, timeMod, ...
= UnitAura("unit", index[, "filter"])
or UnitAura("unit", "name", "rank"[, "filter"])
Arguments
- unit
- String (unitId) - unit whose auras to query.
- index or name
- Number or String - index (from 1 to 40) or name of the aura to query.
- rank
- String (optional) - rank of the aura to query; only available in combination with name.
- filter
- String (optional) - list of filters, separated by spaces or pipes. "HELPFUL" by default. The following filters are available:
- HELPFUL - buffs.
- HARMFUL - debuffs.
- PLAYER - auras that were applied by the player.
- RAID - auras that can be applied (if HELPFUL) or dispelled (if HARMFUL) by the player.
- CANCELABLE - buffs that can be removed (such as by right-clicking or using the /cancelaura command)
- NOT_CANCELABLE - buffs that cannot be removed
Returns
- name
- String - name of the aura
- rank
- String - rank of the spell or effect that caused the aura, or an empty string if there is no rank
- icon
- String - path to the texture file used for the aura's icon
- count
- Number - number of times the aura has been applied to the target, or 0 for auras that do not stack
- debuffType
- String - type of the aura ("Magic", "Disease", "Poison", "Curse", or an empty string for Enrage effects), or nil for auras that do not have a type
- duration
- Number - full duration of the aura in seconds
- expirationTime
- Number - time in seconds (comparable to GetTime()) when the aura will expire
- unitCaster
- String (unitId) - unit that applied the aura, or nil if no valid unit token currently represents the caster
- canStealOrPurge
- Boolean - true for buffs that can be stolen by mages with
[Spellsteal], or false for debuffs and for buffs that cannot be stolen, or for debuffs - nameplateShowPersonal
- Boolean - true for buffs that should be shown on player/pet/vehicle nameplates
- spellId
- Number - spell ID of the spell or effect that applied the aura
- canApplyAura
- Boolean - true for auras the player can apply (not necessarily if the player did apply the aura, just if the player can apply the aura)
- isBossDebuff
- Boolean - true for auras applied by a boss
- isCastByPlayer
- Boolean - true for auras applied by players
- nameplateShowAll
- Boolean - true for auras that should be shown on all nameplates
- timeMod
- Number - scaling factor for time left (appears to always be 1; Blizzard's display code would be incorrect otherwise).
- ...
- Additional values pertinent to specific aura (HoTs, traps, amounts etc. For example, the first value for Vengeance is its attack power bonus.)
Examples
- UnitAura("target", 1)
- the first buff on the target
- UnitAura("target", 1, "PLAYER HARMFUL")
- the first debuff cast by the player on the target
- UnitAura("player", "Renew")
- the first instance of Renew on the player
- UnitAura("player", "Renew", nil, "PLAYER")
- the first instance of Renew cast by the player on the player
The following macro prints the names of any stealable buffs on the current target, or a notice if nothing is stealable:
/run local y,n,s,_ for i=1,40 do n,_,_,_,_,_,_,_,s=UnitAura("target",i)if s then print(n.." on target, steal it!")y=1 end end if y~=1 then print("No stealable buffs.")end
Notes
- Spell ranks were removed in Patch 4.0 (Cataclysm), so the rank argument to this function is largely useless today.
- Some filters are mutually exclusive. Using "HELPFUL HARMFUL" together will return no results, since no aura can be both a buff and a debuff at the same time. Using "CANCELABLE NOT_CANCELABLE" will also return no results, since no buff can be both removable and unremovable.
- The debuffType return value is not localized.
- The UnitBuff function is an alias for using UnitAura with the "HELPFUL" filter. The UnitDebuff function is an alias for using UnitAura with the "HARMFUL" filter. Both aliases will ignore the "HELPFUL" and "HARMFUL" filters, but will accept other filters.
Patch changes
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 as a combination of UnitDebuff and UnitBuff.
