WoW:API UnitBuff: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
(3.0 note)
m (Move page script moved page API UnitBuff to API UnitBuff without leaving a redirect)
 
(13 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{wowapi}} __NOTOC__
{{wowapi}} __NOTOC__
Retrieve info about a certain buff on a certain unit.
Retrieves info about a certain buff on a certain unit. This is essentially an alias of [[API_UnitAura|UnitAura]] with the "HELPFUL" filter.
  name, rank, iconTexture, count, duration, timeLeft = UnitBuff(unit, buffIndex[, castable]);
  name, rank, icon, count, debuffType, duration, expirationTime, unitCaster, isStealable,
shouldConsolidate, spellId = UnitBuff("unit", [index] or ["name", "rank"][, "filter"])  


In 3.0, the returns will change:
== Arguments ==
name, rank, icon, count, debuffType, duration, expirationTime, isMine, isStealable = UnitBuff(unit, buffIndex[, castable])
;unitId : String - The [[unitId|unit]] to query information for
;index or name : Number or string - The index or name of the buff to retrieve information for. Indices start at 1 and go up indefinitely until there are no more buffs on target.
;filter : String - zero or more of "PLAYER", "RAID", "CANCELABLE", "NOT_CANCELABLE", separated by pipe ("|") or space characters.


== Parameters ==
== Returns ==
=== Arguments ===
;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 icon.
 
;rank : String - The rank line from the tooltip of the spell or effect that caused the buff, e.g. "Rank 2". Returns "" if there is no rank.
:(unit, buffIndex, showCastable)
;iconTexture : String - The identifier of (path and filename to) the indicated buff.
 
;count : Number - The number of times the buff has been applied to the target.
:;unit : String - The [[unitId|unit]] to query information for
;debuffType : String - The magic type of the buff
 
;duration : Number - The full duration of the buff in seconds
:;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.
;expirationTime : Number - Time the buff will expire in seconds
 
;source : String - The [[unitId|unit]] that cast the buff
:;castable : Boolean - If present and true (1), then only player-castable buffs will be returned; buffIndex still starts at 1.
;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).
=== Returns ===
;spellId : Number - spell ID of the aura.
:;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 ==
== Example ==
Line 42: Line 39:


=====Macro Options:=====
=====Macro Options:=====
1. Prints the names of all buffs on the current target.
1. Prints the names of all buffs on the current target:
<pre>/run for i=1,40 do local B=UnitBuff("target",i); if B then DEFAULT_CHAT_FRAME:AddMessage(i.."="..B) end end</pre>
<pre>/run for i=1,40 do local B=UnitBuff("target",i); if B then print(i.."="..B) end end</pre>
2. Prints the name, texture, and time left for all buffs on the player.
2. Prints the name, icon texture, and time left for all buffs on the player.
<pre>/run for i=1,40 do local n,_,tex,_,_,t=UnitBuff("player",i);if n then DEFAULT_CHAT_FRAME:AddMessage(i.."="..n..", "..tex..", "..format("%.2f",t/60).." minutes left.")end end</pre>
<pre>/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
</pre>


== History ==
== History ==
Line 55: Line 53:
* Patch 2.4 (Live) has corrected the bug introduced in 2.3.2. The castable parameter correctly filters non-castable buffs once again.
* 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.
* Patch 3.0 updated the return values.
* Patch 3.1 changed the boolean return value isMine to the string value source.


== See also ==
== See also ==

Latest revision as of 04:47, 15 August 2023

WoW API < UnitBuff

Retrieves info about a certain buff on a certain unit. This is essentially an alias of UnitAura with the "HELPFUL" filter.

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

Arguments[edit]

unitId
String - The unit to query information for
index or name
Number or string - The index or name of the buff to retrieve information for. Indices start at 1 and go up indefinitely until there are no more buffs on target.
filter
String - zero or more of "PLAYER", "RAID", "CANCELABLE", "NOT_CANCELABLE", separated by pipe ("|") or space characters.

Returns[edit]

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 icon.
rank
String - The rank line from the tooltip of the spell or effect that caused the buff, e.g. "Rank 2". Returns "" if there is no rank.
iconTexture
String - The identifier of (path and filename to) the indicated buff.
count
Number - The number of times the buff has been applied to the target.
debuffType
String - The magic type of the buff
duration
Number - The full duration of the buff in seconds
expirationTime
Number - Time the buff will expire in seconds
source
String - The unit that cast the buff
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[edit]

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:[edit]

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[edit]

  • 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.
  • Patch 3.1 changed the boolean return value isMine to the string value source.

See also[edit]

UnitDebuff
Identify Buffs Using Textures
List of known buff and debuff effects that can be queried