WoW:API UnitAura: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
(expirationTime is always returned regardless of who cast the buff/debuff)
m (Move page script moved page API UnitAura to API UnitAura without leaving a redirect)
 
(5 intermediate revisions by 4 users not shown)
Line 2: Line 2:


This function was introduced in Patch 3.0. It will serve as an all-in-one solution for querying unit buffs and debuffs. [[API UnitBuff|UnitBuff]] and [[API UnitDebuff|UnitDebuff]] will serve as aliases with built-in harmful/helpful filters.
This function was introduced in Patch 3.0. It will serve as an all-in-one solution for querying unit buffs and debuffs. [[API UnitBuff|UnitBuff]] and [[API UnitDebuff|UnitDebuff]] will serve as aliases with built-in harmful/helpful filters.
Usage:
 
  name, rank, icon, count, debuffType, duration, expirationTime, unitCaster, isStealable  
'''''Usage''''':
   = UnitAura("unit", index or ["name", "rank"][, "filter"])  
  name, rank, icon, count, debuffType, duration, expirationTime, unitCaster, isStealable, shouldConsolidate, spellId
   = UnitAura("unit", index or "name"[, "rank"[, "filter"]])
 
If the second parameter is a string, then the third parameter is the rank (which can be nil)
<dl>
<dt>Either use:
<dd>'''unit''', '''index''', '''filter'''
<dt>or
<dd>'''unit''', '''name''', '''rank''', '''filter'''</dl>
 
'''Examples''':<ul>
<li>UnitAura("target", 1) -- First buff on target
<li>UnitAura("target", 1, "PLAYER|HARMFUL") -- First debuff, cast by the player, on the target
<li>UnitAura("player", "Lightning Shield") -- first instance of "Lightning Shield" on the player
<li>UnitAura("player", "Lightning Shield", nil, "PLAYER|HELPFUL") -- first instance of "Lightning Shield" on the player, cast by the player
<li>UnitAura("player", "Lightning Shield", "Rank 2") -- first instance of "Lightning Shield", rank 2, on the player</ul>


== Arguments ==
== Arguments ==
Line 14: Line 29:
;name : String - The name of the spell or effect of the debuff. This is the name shown in yellow when you mouse over the icon.
;name : String - The name of the spell or effect of the debuff. This is the name shown in yellow when you mouse over the icon.
;rank : String - The rank of the spell or effect that caused the debuff. Returns "" if there is no rank.
;rank : String - The rank of the spell or effect that caused the debuff. Returns "" if there is no rank.
;icon  
;icon : String - The path to the icon file.
;count : Number - The number of times the debuff has been applied to the target.  Returns 0 for any debuff which doesn't stack. ( Changed in 1.11 ).
;count : Number - The number of times the debuff has been applied to the target.  Returns 0 for any debuff which doesn't stack. ( Changed in 1.11 ).
;debuffType : String - The type of the debuff: Magic, Disease, Poison, Curse, or nothing for those with out a type.
;debuffType : String - The type of the debuff: Magic, Disease, Poison, Curse, or nothing for those with out a type.
Line 21: Line 36:
; unitCaster : String - [[unitId]] reference to the unit that casted the buff/debuff.
; unitCaster : String - [[unitId]] reference to the unit that casted the buff/debuff.
; isStealable : Boolean - 1 or nil depending on if the aura can be spellstolen.
; isStealable : Boolean - 1 or nil depending on if the aura can be spellstolen.
 
; shouldConsolidate : Boolean - 1 or nil depending on if the default Blizzard UI should put the aura into the "consolidated" box of buffs.
; spellId : Number - the spellId of the aura.


==Macro Options:==
==Macro Options:==
Line 31: Line 47:
* Patch 3.0 combined UnitDebuff and UnitBuff into this command.
* Patch 3.0 combined UnitDebuff and UnitBuff into this command.
* Patch 3.1 changed "isMine" to "unitCaster". It is now possible for addons to retrieve the unitId that cast the buff/debuff.
* Patch 3.1 changed "isMine" to "unitCaster". It is now possible for addons to retrieve the unitId that cast the buff/debuff.
* Patch 3.3 added shouldConsolidate and spellId


== See Also ==
== See Also ==

Latest revision as of 04:47, 15 August 2023

WoW API < UnitAura

This function was introduced in Patch 3.0. It will serve as an all-in-one solution for querying unit buffs and debuffs. UnitBuff and UnitDebuff will serve as aliases with built-in harmful/helpful filters.

Usage:

name, rank, icon, count, debuffType, duration, expirationTime, unitCaster, isStealable, shouldConsolidate, spellId 
 = UnitAura("unit", index or "name"[, "rank"[, "filter"]])

If the second parameter is a string, then the third parameter is the rank (which can be nil)

Either use:
unit, index, filter
or
unit, name, rank, filter

Examples:

  • UnitAura("target", 1) -- First buff on target
  • UnitAura("target", 1, "PLAYER|HARMFUL") -- First debuff, cast by the player, on the target
  • UnitAura("player", "Lightning Shield") -- first instance of "Lightning Shield" on the player
  • UnitAura("player", "Lightning Shield", nil, "PLAYER|HELPFUL") -- first instance of "Lightning Shield" on the player, cast by the player
  • UnitAura("player", "Lightning Shield", "Rank 2") -- first instance of "Lightning Shield", rank 2, on the player

Arguments[edit]

unit
String - The unit you want debuff information for.
index
Number - The index of the debuff to retrieve info for. Starts at 1, maximum 40.
filter
This parameter can be any of "HELPFUL", "HARMFUL", "PLAYER", "RAID", "CANCELABLE", "NOT_CANCELABLE". You can also specify several filters separated by a | or space character to chain multiple filters together (e.g. "HELPFUL|RAID" or "HELPFUL RAID" == helpful buffs that you can cast on your raid). By default UnitAura has "HELPFUL" as an implicit filter - you cannot get back BOTH helpful and harmful at the same time. Neither "HELPFUL" or "HARMFUL" have meaning for UnitBuff/UnitDebuff, and will be ignored.

Returns[edit]

name
String - The name of the spell or effect of the debuff. This is the name shown in yellow when you mouse over the icon.
rank
String - The rank of the spell or effect that caused the debuff. Returns "" if there is no rank.
icon
String - The path to the icon file.
count
Number - The number of times the debuff has been applied to the target. Returns 0 for any debuff which doesn't stack. ( Changed in 1.11 ).
debuffType
String - The type of the debuff: Magic, Disease, Poison, Curse, or nothing for those with out a type.
duration
Number - The full duration of the debuff in seconds;
expirationTime
Number - The time in seconds (like what returns GetTime()) when the aura will expire.
unitCaster
String - unitId reference to the unit that casted the buff/debuff.
isStealable
Boolean - 1 or nil depending on if the aura can be spellstolen.
shouldConsolidate
Boolean - 1 or nil depending on if the default Blizzard UI should put the aura into the "consolidated" box of buffs.
spellId
Number - the spellId of the aura.

Macro Options:[edit]

1. Prints the name of any stealable buffs on the current target, or a notice if nothing is stealable:

/run local y=0;for i=1,40 do local n,_,_,_,_,_,_,_,isStealable=UnitAura("target",i);if isStealable==1 then print(n.." on target, steal it!")y=1;end end if y~=1 then print("No stealable buffs.")end


History[edit]

  • Patch 3.0 combined UnitDebuff and UnitBuff into this command.
  • Patch 3.1 changed "isMine" to "unitCaster". It is now possible for addons to retrieve the unitId that cast the buff/debuff.
  • Patch 3.3 added shouldConsolidate and spellId

See Also[edit]

UnitBuff
UnitDebuff
List of known buff and debuff effects that can be queried
Upcoming 3.0 Changes - Concise List