Changes: API UnitDebuff

Revision as of 04:22, 18 January 2010

Retrieve info about a certain debuff on a certain unit. This is essentially an alias of UnitAura with the "HARMFUL" filter applied.

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

Arguments

unitId: String - The unit you want debuff information for.
index or name: Number or string - The index or name of the debuff to retrieve information for. Indices range from 1 to 40.
removable: Boolean - (optional) - If 1, only debuffs removable by player will be returned; debuffIndex still begins at 1.

Returns

name: String - The name of the spell or effect of the debuff, or nil if no debuff was found with the specified name or at the specified index. 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 identifier of (path and filename to) the indicated debuff, or nil if no debuff
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; nil if the debuff was not cast by the player.
expirationTime: Number - Time at which the debuff expires (GetTime() as a reference frame).
unitCaster: String - unitId reference to the unit that cast the buff/debuff.
isStealable: Boolean - 1 if it is stealable otherwise nil
shouldConsolidate: Boolean - 1 if the buff should be placed in a buff consolidation box (usually long-term effects).
spellId: Number - spell ID of the aura.

Example

Retrieves the name, rank and icon texture of the first debuff on the player's pet:

name, rank, texture = UnitDebuff("pet", 1);

Macros

Macro to print a list of the target's debuffs:

/run for i=1,40 do local D= UnitDebuff("target",i); if D then print(i.."="..D) end end

Notes

UnitDebuff and other UnitAura-based queries may not be accurate immediately after casting a spells that applies an aura to its target.

History

Patch 1.9 introduced the removable argument.
Patch 2.0 extended the maximum number of debuffs to 40 (from 16).
Patch 2.0 introduced name and rank return values.
Patch 2.1 introduced duration and timeLeft return values.
Patch 3.0 changes this into an alias of UnitAura; durations are now available for all debuffs.
Patch 3.1 changed "isMine" to "unitCaster". It is now possible for addons to retrieve the unitId that cast the buff/debuff.

@@ Line 1: / Line 1: @@
+{{wowapi}} __NOTOC__
- <center>'''UnitDebuff''' ''-Documentation by Sarf-''</center>
+Retrieve info about a certain debuff on a certain unit. This is essentially an alias of [[API_UnitAura|UnitAura]] with the "HARMFUL" filter applied.
+ name, rank, icon, count, debuffType, duration, expirationTime, unitCaster, isStealable, shouldConsolidate, spellId
+  = UnitDebuff("unit", index or ["name", "rank"][, "filter"])
+== Arguments ==
-Retrieve info about a certain debuff on a certain unit.
+;unitId : String - The [[API TYPE UnitId|unit]] you want debuff information for.
+;index or name : Number or string - The index or name of the debuff to retrieve information for. Indices range from 1 to 40.
+;removable : Boolean - <small>''(optional)''</small> - If 1, only debuffs removable by player will be returned; debuffIndex still begins at 1.
+== Returns ==
- debuffTexture, debuffApplications = UnitDebuff(unitName, debuffIndex, showDisepllable);
+;name : String - The name of the spell or effect of the debuff, or nil if no debuff was found with the specified name or at the specified index. 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 identifier of (path and filename to) the indicated debuff, or nil if no debuff
+;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; nil if the debuff was not cast by the player.
+; expirationTime : Number - Time at which the debuff expires (GetTime() as a reference frame).
+; unitCaster : String - [[unitId]] reference to the unit that cast the buff/debuff.
+;isStealable : Boolean - 1 if it is stealable otherwise nil
+;shouldConsolidate : Boolean - 1 if the buff should be placed in a buff consolidation box (usually long-term effects).
+;spellId : Number - spell ID of the aura.
+== Example ==
-----
+Retrieves the name, rank and icon texture of the first debuff on the player's pet:
-;''Arguments''
+ name, rank, texture = UnitDebuff("pet", 1);
+== Macros ==
-:(String unitName)
+Macro to print a list of the target's debuffs:
+ /run for i=1,40 do local D= UnitDebuff("target",i); if D then print(i.."="..D) end end
+== Notes ==
-:;unitName : The name of the unit you wish to retrieve info on
+* UnitDebuff and other UnitAura-based queries may not be accurate immediately after casting a spells that applies an aura to its target.
+== History ==
-: Viable names known:
+* Patch 1.9 introduced the removable argument.
-:* player
+* Patch 2.0 extended the maximum number of debuffs to 40 (from 16).
-:* party1-4
+* Patch 2.0 introduced name and rank return values.
-:* raid1-40
+* Patch 2.1 introduced duration and timeLeft return values.
-:* pet
+* Patch 3.0 changes this into an alias of UnitAura; durations are now available for all debuffs.
-:* partypet1-4
+* Patch 3.1 changed "isMine" to "unitCaster". It is now possible for addons to retrieve the unitId that cast the buff/debuff.
-:* target
+== See Also ==
-:(Number debuffIndex)
+: [[API_UnitAura|UnitAura]], [[API UnitBuff|UnitBuff]].
+: [[HOWTO: Identify Buffs Using Textures]]
-:;debuffIndex : The index num of the debuff to retrieve info on. Starts at 1 and goes up to (and possibly beyond) a certain number.
-: The maximum numbers used by the Blizzard code are 16 for party/pet/target debuffs.
-:(Boolean showDispellable)
-:;showDispellable : Flag <small><i>(optional)</i></small> - Can be 0, 1, or nil. If present and 1, then only buffs will be returned which are dispellable by the player. Index is still starting with 1 and counting up. (new in 1.9, works in 1.9.3)
-----
-;''Returns''
-:(String debuffTexture)
-:;debuffTexture : The identifier of (path and filename to) the indicated debuff, or nil if no debuff
-:(String debuffApplications)
-:;debuffApplications : The number of times the debuff has been applied to the target.
-----
-;''Example''
- debuff = UnitDebuff("pet", i);
-;''Result''
-Retrieves the debuff texture of the pets debuff with the index of "i".
-----
-;''Description''
-: Retrieve info (texture name) about a certain debuff of the specified unit.
-;''See Also''
-: [[API UnitBuff|UnitBuff]]
-: [[UI Questions#Lua_Questions|Why doesn't UnitDebuff accurately report the spell I just cast?]]
-: [[Check Hunter Mark|Sample Code Check Hunter's Mark Aspect]]
 : [[Queriable Buff effects|List of known buff and debuff effects that can be queried]]
-----
-{{WoW API}}