Talk:API UnitAura


 * added macro code Belleboom (talk) 16:55, 10 April 2009 (UTC)

UnitAura arguments
Nexiuz Asks: It seems that this function doesn't have the rank anymore. Or at least the first 3 arguments are now Unit, Index, Filter (3th is filter, not the 4th). Can someone check this also and maybe check if the 4th argument is rank.

Kitjan Answers The reference is a little confusing, but UnitAura works in two ways: "unit", index, "filter" "unit", "name", "rank", "filter"

Examples:    

I just verified that all three of those work (wow 3.3.5.12340) I have seen a couple addons try to hook UnitAura and only support the first form, which ended up breaking my addon.

Does not return array!
In the returns section, the final returns listed as `...` say "array of values pertinent to specific aura", which is certainly not correct. Is a list of values, not an array. This may seem like nitpicking, but may be confusing for some people. Nefftd (talk) 16:38, 17 August 2014 (UTC)

expirationTime may be 0
The expirationTime is set to 0 if the aura doesn't have an expiration. Ex. Warlock's Corruption with the Absolute Corruption debug. The duration is also set to 0 in that case.

--LaoTseu (talk) 20:02, 3 December 2016 (UTC)

Examples of Return Values
Misdirection:
 * name = Misdirection
 * icon = 132180
 * count = 0
 * debuffType = nil
 * durSecs = 8
 * expTime = 13740.819 (typical)
 * caster = player
 * stealOrPurge = false
 * personalNameplateShow = false
 * spellID = 35079
 * canApplyAura = false
 * bossDebuff = false
 * castByPlayer = true
 * nameplateShowAll = false
 * timeMod = 1

Significant here is that the canApplyAura value is false. I'm not certain about the why of that as this was cast by my Hunter with his pet as the target. Obviously the player (in this case) can apply this aura.

Flask of the Currents:
 * name = Flask of the Currents
 * icon = 2057568
 * count = 0
 * debuffType = nil
 * durSecs = 7200
 * expTime = 16150.766 (typical)
 * caster = player
 * stealOrPurge = false
 * personalNameplateShow = false
 * spellID = 251836
 * canApplyAura = false
 * bossDebuff = false
 * castByPlayer = true
 * nameplateShowAll = false
 * timeMod = 1
 * extra1 = 238

Significant here is the use of the first of the unspecified fields (which I have named "extra1") - the value shown is the amount that my Hunter's Agility is increased (as it appears in the Aura tooltip).

Enlisted:
 * name = Enlisted
 * icon = 1455894
 * count = 0
 * debuffType = nil
 * durSecs = 0
 * expTime = 0
 * caster = player
 * stealOrPurge = false
 * personalNameplateShow = false
 * spellID = 269083
 * canApplyAura = false
 * bossDebuff = false
 * castByPlayer = true
 * nameplateShowAll = false
 * timeMod = 1
 * extra1 = 10
 * extra2 = 10
 * extra3 = 0
 * extra4 = 10
 * extra5 = 10
 * extra6 = 10
 * extra7 = 10
 * extra8 = 10
 * extra9 = 10
 * extra10 = 10
 * extra11 = 10

Significant here is the depth of the extra return values (eleven elements in this case). This is the deepest that I found in my limited testing. I tested to a depth that would have taken me to extra15 but never found anything higher than I did with this aura.

It appears that the depth of the extra return values is relatively open-ended. Certainly it is completely undocumented.

I know there is a ton of stuff that need documentation that is likely higher priority than this, but discovery and documentation of how those extra values are used with different auras could be useful.

Significant about all of these, nowhere in any of my testing did I find a true value in canApplyAura. Admittedly I was only testing on a BM Hunter, but there were any number of spells cast (or abilities used) that were directly responsible for, shared spellIDs with, shared icons with, shared names with, and were cast by that hunter that appeared in my captured list of aura information and none of them showed a true value in canApplyAura.

Since the return values aren't named (officially) and FrameXML is notorious for broken naming patterns, I'm wondering if either that return value has been deprecated and will always be false or if it means something other than what the description of that return value implies. Some research on that might also be in order.

My apologies for essentially broadening the scope here rather than narrowing it, but those how delve into dealing with UnitAura data directly would probably benefit from a more thorough understanding of exactly what is being returned by that API function call.Mltco78dhs (talk) 04:58, 17 May 2019 (UTC)

Bestial Wrath:
 * name = Bestial Wrath/*
 * icon = 132127/*
 * spellID = 19574/186254
 * count = 0/*
 * expTime = 4123.037/4123.038
 * durSecs = 15/*
 * caster = player/*
 * castByPlayer = true/*
 * canApplyAura = true/false
 * nameplateShowAll = false/*
 * personalNameplateShow = false/*
 * stealOrPurge = false/*
 * bossDebuff = false/*
 * timeMod = 1/*
 * extra1 = 25/*
 * extra2 = 0/40
 * extra3 = 0/*
 * extra4 = 25/0

The "/" notation indicates player/pet values for the same buff on the same cast. An asterisk indicates identical pet values (simpler to indicate "identical" than to list the value and require the reader to determine that).

Significant here are two things.

First: This DOES show a true value for canApplyAura which leads me to believe that the given name for this return value is incorrect (not that it doesn't occur in FrameXML - that FrameXML misnames it). I believe this is not an indicator of whether or not this aura can be applied through the actions of the player but whether this aura can be applied DIRECTLY (not as an adjunct of another ability) by the player to the player. Note that canApplyAura value for the PLAYER for this is true but for the PET it is false.

Second: There is a misconception, particularly in the Weak Auras community that all buffs from the same cast have the same timestamp. Granted they're usually very close, but I happened to catch this one at just the right moment to demonstrate that the PLAYER versus PET start times (as computed by expiration time minus duration) differ by about 1/1000 of a second. Likely, given the frame rates I enjoy on my PC, these occurred one frame apart from one another. It's something to keep in mind when coding rotational or monitoring code based on aura timings and sources.Mltco78dhs (talk) 15:01, 17 May 2019 (UTC)

Barbed Shot/Frenzy:
 * name = Barbed Shot/Frenzy
 * icon = 2058007/*
 * spellID = 246851/272790
 * count = 0/2
 * expTime = 3402.98/3403.98
 * durSecs = 8/9
 * caster = player/*
 * castByPlayer = true/*
 * canApplyAura = false/*
 * nameplateShowAll = false/*
 * personalNameplateShow = false/*
 * stealOrPurge = false/*
 * bossDebuff = false/*
 * timeMod = 1/*
 * extra1 = 5/nil

I captured this during combat and the Frenzy count is 2 rather than 1 because of that. Duration of Frenzy is non-standard because of Azerite traits on my gear. Expiration times show a one second difference because of that but the start times compute to the same time.

Significant here is that this is also (like with Bestial Wrath) an aura that applied to both Hunter and Pet but in this case it obtains from use of Barbed Shot rather than a direct Buff ability. Notice that canApplyAura is false for both auras.Mltco78dhs (talk) 15:15, 17 May 2019 (UTC)

Using version 8.1.5.29981 of FrameXML, I found that canApplyAura is never captured in any call to UnitAura. It is captured by UnitDebuff (a closely-related API function) three times (lines 1296, 1312, and 1318 of CompactUnitFrame.lua) but the variables it is captured into are local and never referenced. It is captured by UnitBuff three times (lines 1252, 1272, and 1310 of CompactUnitFrame.lua) but in only one of those is it used and I have doubts about the code it's used in being correct.

function CompactUnitFrame_UtilShouldDisplayBuff(unit, index, filter) local name, icon, count, debuffType, duration, expirationTime, unitCaster, canStealOrPurge, _, spellId, canApplyAura = UnitBuff(unit, index, filter); local hasCustom, alwaysShowMine, showForMySpec = SpellGetVisibilityInfo(spellId, UnitAffectingCombat("player") and "RAID_INCOMBAT" or "RAID_OUTOFCOMBAT"); if ( hasCustom ) then return showForMySpec or (alwaysShowMine and (unitCaster == "player" or unitCaster == "pet" or unitCaster == "vehicle")); else return (unitCaster == "player" or unitCaster == "pet" or unitCaster == "vehicle") and canApplyAura and not SpellIsSelfBuff(spellId); end end

This function is only called by one other... function CompactUnitFrame_UpdateBuffs(frame) if ( not frame.buffFrames or not frame.optionTable.displayBuffs ) then CompactUnitFrame_HideAllBuffs(frame); return; end local index = 1; local frameNum = 1; local filter = nil; while ( frameNum <= frame.maxBuffs ) do   local buffName = UnitBuff(frame.displayedUnit, index, filter); if ( buffName ) then if ( CompactUnitFrame_UtilShouldDisplayBuff(frame.displayedUnit, index, filter) and not CompactUnitFrame_UtilIsBossAura(frame.displayedUnit, index, filter, true) ) then local buffFrame = frame.buffFrames[frameNum]; CompactUnitFrame_UtilSetBuff(buffFrame, frame.displayedUnit, index, filter); frameNum = frameNum + 1; end else break; end index = index + 1; end for i=frameNum, frame.maxBuffs do   local buffFrame = frame.buffFrames[i]; buffFrame:Hide; end end

...which is itself only called from one place...

function CompactUnitFrame_UpdateAuras(frame) CompactUnitFrame_UpdateBuffs(frame); CompactUnitFrame_UpdateDebuffs(frame); CompactUnitFrame_UpdateDispellableDebuffs(frame); CompactUnitFrame_UpdateClassificationIndicator(frame); end

I've seen enough commentary on problems with auras showing up correctly on CUF that I don't think even Blizzard fully understands what canApplyAura really means (or at least the author of the one function that makes use of the value in all of FrameXML doesn't).

It CANNOT be true in the one place it needs to be because from all the research I've seen in will only be true if the aura is a directly applied aura capable of being applied by the player (not the result of an ability that applies an aura as a secondary effect) but in context it's only used in a situation where it's NAND with SpellIsSelfBuff but AND with having been cast by the PLAYER, the PLAYERPET, or the vehicle the PLAYER is in. I do not believe that situation can ever happen. I believe that use, or potential misuse, of canApplyAura is responsible for some or all of the aura display issues currently happening with CUF.

My suggestion would be to disregard Blizzards misnaming of this return variable and use playerDirectAura instead of canApplyAura. It's more descriptive of what the value seems to reflect and far less confusing than the existing name.Mltco78dhs (talk) 15:53, 17 May 2019 (UTC)


 * Interesting discovery, Mltco78dhs. It's clear that this page is based on documentation that doesn't tell the complete story.  Is it possible the discrepency over canApplyAura is because of some spells having a certain spellID, and the aura applied is in fact a different spellID?  DDC (talk)