API UnitBuff

From Wowpedia
Jump to: navigation, search

Retrieve info about a certain buff on a certain unit.

name, icon, count, debuffType, duration, expirationTime, unitCaster, isStealable, 
  nameplateShowPersonal, spellId, canApplyAura, isBossDebuff, nameplateShowAll, timeMod, value1, value2, value3
= UnitBuff("unit", index[, "filter"])

Arguments

unit 
String (unitId) - unit whose buffs to query.
index 
Number or String - index (from 1 to 40)
filter 
String (optional) - list of filters, separated by spaces or pipes ("|"). "HELPFUL" by default. The following filters are available:
HELPFUL - buffs.
HARMFUL - debuffs.
PLAYER - buffs that were applied by the player.
RAID - buffs that can be applied 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

1. name 
String - The name of the spell or effect of the buff, or nil if no buff was found with the specified name or at the specified index. This is the name shown in yellow when you mouse over the buff's icon.
2. icon 
Number (fileID) - identifier of the texture used for the buff's icon.
3. count 
Number - The number of times the buff has been applied to the target.
4. debuffType 
String - The magic type of the buff
5. duration 
Number - The full duration of the buff in seconds
6. expirationTime 
Number - Time the buff expires (compare to GetTime())
7. source 
String - The unit that cast the buff
8. isStealable 
Boolean - true if it is stealable
9. nameplateShowPersonal 
Boolean - true if the buff should be shown on the player/pet/vehicle nameplate
10. spellId 
Number - spell ID of the aura.
11. canApplyAura 
Boolean - true if the player can apply the aura (not necessarily if the player did apply the aura, just if the player can apply the aura).
12. isBossDebuff 
Boolean - true if the aura was cast by a boss.
13. nameplateShowAll 
Boolean - true if the buff should be shown on nameplates
14. timeMod 
Number - scaling factor used for displaying time left
15. value1
Number - Value of variable effect 1 of the aura. (HoTs, resource-capturing trinkets, etc.)
16. value2
Number - Value of variable effect 2 of the aura. (HoTs, resource-capturing trinkets, etc.)
17. value3
Number - Value of variable effect 3 of the aura. (HoTs, resource-capturing trinkets, etc.)

Example

The following snippet prints the name, icon, and time left for each buff on the player:

for i=1,40 do
  local name, icon, _, _, _, etime = UnitBuff("player",i)
  if name then
    print(("%d=%s, %s, %.2f minutes left."):format(i,name,icon,(etime-GetTime())/60))
  end
end

Details

  • This essentially an alias of UnitAura with the "HELPFUL" filter.

Patch changes

  • Battle for Azeroth Patch 8.0.1 (2018-07-17): Removed Rank and querying by name option, Moved all returns down by 1.
  • Legion Patch 7.0.3 (2016-07-19): Added return values "nameplateShowAll" and "timeMod"; change "shouldConsolidate" to "nameplateShowPersonal".
  • 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 of the Lich King Patch 3.3.0 (2009-12-08): Added shouldConsolidate and spellId.
  • Wrath of the Lich King 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 of the Lich King Patch 3.0.2 (2008-10-14): Updated the return values.
  • The Burning Crusade Patch 2.4.0 (2008-03-25): Corrected the bug introduced in 2.3.2. The castable parameter correctly filters non-castable buffs once again.
  • The Burning Crusade Patch 2.3.2 (2008-01-08): Changed behavior of castable parameter - spells cast by other players are no longer shown at all when castable is used. This is a bug.
  • The Burning Crusade Patch 2.1.0 (2007-05-22): Added duration and timeLeft return values.
  • The Burning Crusade Patch 2.0.1 (2006-12-05): Added name and rank return values.
  • WoW Icon update.png Patch 1.9.0 (2006-01-03): Added castable to the list of parameters.

See also