API UnitBuff

Main Menu
WoW API Lua API FrameXML util Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

Retrieve info about a certain buff on a certain unit.

name, rank, iconTexture, count, duration, timeLeft =  UnitBuff(unit, buffIndex[, castable]);

In 3.0, the returns will change:

name, rank, icon, count, debuffType, duration, expirationTime, isMine, isStealable = UnitBuff(unit, buffIndex[, castable])

Parameters

Arguments

(unit, buffIndex, showCastable)

unit

String - The unit to query information for

buffIndex

Integer - The index of the buff to retrieve information for. Starts at 1 and goes up indefinitely until there are no more buffs on target.

castable

Boolean - If present and true (1), then only player-castable buffs will be returned; buffIndex still starts at 1.

Returns

name

String - The name of the spell or effect of the buff. 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 buff. Returns "" if there is no rank.

iconTexture

String - The identifier of (path and filename to) the indicated buff.

count

String - The number of times the buff has been applied to the target.

duration

Number - Full duration of a buff you cast, in seconds; nil if you did not cast this buff.

timeLeft

Number - Time left before a buff expires, in seconds; nil if you did not cast this buff.

Example

local buffs, i = { }, 1;
local buff = UnitBuff("player", i);
while buff do
  buffs[#buffs + 1] = buff;
  i = i + 1;
  buff = UnitBuff("player", i);
end;
if #buffs < 1 then
  buffs = "You have no buffs";
else
  buffs[1] = "You're buffed with: "..buffs[1];
  buffs = table.concat(buffs, ", ");
end;
DEFAULT_CHAT_FRAME:AddMessage(buffs);

Macro Options:

1. Prints the names of all buffs on the current target:

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

2. Prints the name, icon texture, and time left for all buffs on the player.

/run for i=1,40 do local n,_,icon,_,_,dur,x,_,_=UnitBuff("player",i);if n then print(i.."="..n..", "..icon..", "..format("%.2f",-1*(GetTime()-x)/60).." minutes left.")end end

History

• Patch 1.9 added castable to the list of parameters.
• Patch 2.0 added name and rank return values.
• Patch 2.1 added duration and timeLeft return values.
• Patch 2.3.2 changed behaviour of castable parameter - spells cast by other players are no longer shown at all when castable is used. Bug or intented change?
• Patch 2.4 (PTR 8089-enGB) changed (again) behaviour of castable parameter - spells cast by other classes are no longer shown at all when castable is used. Tested with druid and priest spells, MacOSX client. Needs to be confirmed.
• Patch 2.4 (Live) has corrected the bug introduced in 2.3.2. The castable parameter correctly filters non-castable buffs once again.
• Patch 3.0 updated the return values.

See also

UnitDebuff

HOWTO: Identify Buffs Using Textures

List of known buff and debuff effects that can be queried