Aura (API Type)

From Warcraft Wiki
Jump to navigation Jump to search

Auras are buffs and debuffs that may exist on any unit.

Returns

1. name
string - The localized name of the aura, otherwise nil if there is no aura for the index.
2. icon
number : FileID - The icon texture.
3. count
number - The amount of stacks, otherwise 0.
4. dispelType
string? - The locale-independent magic type of the aura: Curse, Disease, Magic, Poison, otherwise nil.
5. duration
number - The full duration of the aura in seconds.
6. expirationTime
number - Time the aura expires compared to GetTime(), e.g. to get the remaining duration: expirationtime - GetTime()
7. source
string : UnitId - The unit that applied the aura.
8. isStealable
boolean - If the aura may be stolen.
9. nameplateShowPersonal
boolean - If the aura should be shown on the player/pet/vehicle nameplate.
10. spellId
number - The spell ID for e.g. GetSpellInfo()
11. canApplyAura
boolean - If the player can apply the aura.
12. isBossDebuff
boolean - If the aura was cast by a boss.
13. castByPlayer
boolean - If the aura was applied by a player.
14. nameplateShowAll
boolean - If the aura should be shown on nameplates.
15. timeMod
number - The scaling factor used for displaying time left.
16. shouldConsolidate (WoW Icon update.pngWrath-Logo-Small.png)
boolean - Whether to consolidate auras, only exists in Classic Era/Wrath.
...
Variable returns - Some auras return additional values that typically correspond to something shown in the tooltip, such as the remaining strength of an absorption effect.

Examples

UnitAura

UnitAura provides several return values describing up to 40 auras on a unit matching an optional filter (such as "HELPFUL" or "HARMFUL"). 

for i=1, 40 do
  local name, __, count = UnitAura("player", i, "HARMFUL");    -- debuffs only
  if (not name) then
    break;    --end the loop
  end
  if (count > 1) then
    print("Yikes!  You have " .. count .. " stacks of " .. name);
  else
    print("Look out!  You have " .. name);
  end
end

UnitAura may be used in conjunction with event handlers to display an insecure icon of an aura 

-- create a frame to hold the texture and handle events
local myFrame = CreateFrame("Frame", nil, UIParent)
myFrame:SetSize(64, 64)
myFrame:SetPoint("CENTER")

-- create the texture
local myTexture = frame:CreateTexture(nil, "ARTWORK")
myTexture:SetAllPoints();

-- create the handler that updates the texture
myFrame:SetScript("OnEvent", function()
  if (UnitExists("target")) the
    local name, icon = UnitAura("target", 1)
    if (name) then
      -- the target has at least one buff or debuff
      myTexture:SetTexture(icon);
      myTexture:Show();
    else
      -- the target has no buffs or debuffs
      myTexture:Hide();
    end
  else
    -- there is no currently selected target
    myTexture:Hide();
  end
end);  --end of the OnUpdate handler

-- register the handler so it triggers on useful events
myFrame:RegisterUnitEvent("UNIT_AURA", "target"); -- the player's current target recently gained or lost an aura
myFrame:RegisterUnitEvent("UNIT_TARGET, "player");  -- the player recently has a new target, or no longer has a target

SecureAuraHeaderTemplate

SecureAuraHeaderTemplate automatically creates, filters and sorts secure frames that allow players to perform protected functions like removing buffs during combat (normally via right clicking). By comparison, the insecure method shown earlier is more appropriate for party or target frames because you only see their buffs but cannot interact with them.

This secure approach requires the creation of a custom xml template describing the appearance of each buff button, and then a secure header frame that will use the custom temlplate to produce buttons as new buffs appear. 

-- create a template in XML
<Ui ...>
<Button name="myAuraButtonTemplate" inherits="SecureActionButtonTemplate" virtual="true">
<Size x="10 y="10" />
<Attributes>
  <Attribute name="type2" value="cancelaura" />  
</Attributes>
<Scripts>
  <OnLoad>
    self:RegisterForClicks("RightButtonUp")
  </OnLoad>
</Button>
</Ui>


-- create the SecureAuraHeader in lua
assert(not InCombatLockdown());
local mySecureHeader = CreateFrame("Frame", "mySecureHeader", UIParent, "SecureAuraHeaderTemplate");
mysecureHeader:SetAttribute("template", "myAuraButtonTemplate"); -- it will use
mySecureHeader:SetAttribute("unit", "player"); -- to show auras on the player
mySecureHeader:SetAttribute("minWidth", 1);
mySecureHeader:SetAttribute("minHeight", 1);
mySecureHeader:Show();

-- customize via these attributes
mySecureHeader:SetAttribute("filter", "HELPFUL"); -- see UnitAura() for a list of possible filters
mySecureHeader:SetAttribute("sortMethod", "TIME"); -- also could be "INDEX" or "NAME"
mySecureHeader:SetAttribute("sortDirection", "+"); -- also could be "-" for reverse sorting
mySecureHeader:SetAttribute("point", "CENTER"); -- start creating buff icons in the middle of the screen
mySecureHeader:SetAttribute("xOffset", 15); -- position each buff relative to the previous one
mySecureHeader:SetAttribute("yOffset", 0);
mySecureHeader:SetAttribute("wrapAfter", 5); -- create a new row if there are 6 or more buffs
mySecureHeader:SetAttribute("wrapXOffset", 0);
mySecureHeader:SetAttribute("wrapYOffset", -15);

-- create a function to update the appearance of each button (see UnitAura earlier)
mySecureHeader:SetScript("OnEvent", function()
  for i=1, 40 do
    local child = header:GetAttribute("child" .. i);  -- gets the i'th automatically created button
    if (not child or not child:IsShown()) then
      return;  -- the player has fewer than 40 buffs
    end
    child.texture = child.texture or child:CreateTexture(nil, "ARTWORK")  -- create a texture if one doesn't exist already
    child.texture:SetAllPoints();
    
    -- the 2nd parameter should accomodate the secure header's sortMethod and sortDirection attributes, by using GetID()
    -- the 3rd parameter should match the secure header's filter attribute, by using the same string
    local name, icon = UnitAura("player", i, "HELPFUL");
    if (name) then
      child.texture:SetTexture(icon);
      child.texture:Show();
    else
      child.texture:Hide();
    end
  end
end); -- end of the OnEvent handler

-- register the handler to a useful event so it triggers
mySecureHeader:RegisterUnitEvent("UNIT_AURA", "player"); -- triggers when buffs/debuffs on the player change

Patch changes

Retrieved from "https://warcraft.wiki.gg/index.php?title=Aura_(API_Type)&oldid=921568"