In some circumstances, it may be benefecial to use spell textures, rather than names, to identify buff and debuff effects - textures require no additional localization, while buff names will require to be localized for every language your addon should support. This HOWTO describes an easy mechanism to find out if a certain unit is affected by a specific buff or debuff.
Iterating buff / debuffsEdit
While we could write separate functions for buffs and debuffs, it's easier to write a single iterator function and pass the desired spell effect type as an argument - effectively cutting down the amount of code required for the whole routine. We can get the buff's texture from UnitBuff and debuffs from UnitDebuff:
name, rank, iconTexture, count, duration, timeLeft = UnitBuff(unit, buffIndex [, castable]); name, rank, texture, count, debuffType, duration, timeLeft = UnitDebuff(unitID, debuffIndex [, removable]);
The effect's texture is the third return value of both functions, but UnitDebuff has one more return value - which means that we'll need to store all seven return values in order to return them. Castable and removable arguments allow us to save iterations of the loop if we're only interested in buffs/debuffs the player can cast/remove, so we should allow access to those from the iterator function. For both functions, index starts at 1 and goes up until the function returns nil -- while a while loop is ideal, we can use an infinite loop, and call break; when nil is encountered to save iterator calls. So far, our inner iterator loop would look something like:
qFunc, unit, castable, id, match = UnitBuff, "player", 1, nil, "SomeEffectTexture"; -- while true do local name, rank, texture, count, type, duration, timeleft = qFunc(unit, id, castable); -- note UnitDebuff returns; we simply don't care about the names at this point, but we need all seven. if not name then break; -- There are no more buffs / debuffs, exit infinite loop end if string.match(texture, match) then return name, rank, texture, count, type, duration, timeleft; -- We've found a match end i = i + 1; -- Go for the next index end
This would tell return the proper UnitBuff/UnitDebuff returns if the target is affected by a matching buff/debuff, or nil if it's not. Stopping here is good enough; we can, however, make things even better by allowing you to detect multiple textures with the same texture by using another index argument, and then decrementing it on matching effects until we hit zero, returning the found buff entry. Everything combined, the iterator function is:
function iterateQueriableEffect(qFunc, unit, matchTexture, id, castable) id = id or 1; -- default value, making id optional; while true do local name, rank, texture, count, type, duration, timeleft = qFunc(unit, id, castable); if not name then break; end if string.match(texture, matchTexture) then id = id - 1; if id == 0 then return name, rank, texture, count, type, duration, timeleft; end end end end
Using the iterator function to query effectsEdit
With the background code written, we can now use it to query actual effects. WoWWiki has a list of buff and debuff textures with associated names; suppose we wanted to know whether the player is buffed with Mark of the Wild: motw is a buff (so we need UnitBuff), player's unitid is "player":
name, rank, texture, count, duration, timeLeft = iterateQueriableEffect(UnitBuff, "player", "Spell_Nature_Regeneration"); if name then message("Player is buffed with " .. name .. " (" .. rank .. ")"); else message("Player is not buffed with Mark of the Wild."); end
Or if we wanted to know whether the target is sapped(UnitDebuff, "target"):
name, rank, texture, count, debuffType, duration, timeLeft = iterateQueriableEffect(UnitDebuff, "target", "Ability_Sap"); message(name and "Target is sapped!" or "Target is not sapped"); -- shorthand if syntax -- if name is non-false and non-nil, the first message appears, otherwise, the second.
Other interesting usesEdit
You can find out whether the unit is affected by a debuff you can remove (by using the castable argument, which doubles up as removable for debuffs):
name, rank, texture, count, debuffType, duration, timeLeft = iterateQueriableEffect(UnitDebuff, unit, ".", 1, true); -- "." matches all textures, so we only have to get a return from UnitDebuff(unit, id, true) for this to return something.
You can also use the id argument to find all buffs/debuffs with the same texture on target; for example, "Spell_Fire_FireArmor" is used for almost all fire-shield effects - Fire Ward, greater protection potions, warlock imps' fire thorns spell... suppose you wanted to iterate through them:
local i, out = 1, ""; while true do local name, rank = iterateQueriableEffect(UnitBuff, unit, "Spell_Fire_FireArmor", i); if not name then break; end out = out .. (out == "" and "" or ", ") .. name; end message("Following debuffs on unit share Spell_Fire_FireArmor texture: " .. out);
Note that the last example is somewhat inefficient - you would be better off acquiring all the buff names in a single local loop rather than iterating through buffs multiple times to find all occurrences of a certain texture.