Buff and Debuff Triggers

Overview

The Aura trigger system (aura2) is a specialized, high-performance trigger type for tracking buffs, debuffs, and other auras. It uses BuffTrigger2.lua for optimized scanning and state management.

Aura triggers are significantly more efficient than combat log triggers for tracking buffs and debuffs.

Basic Aura Trigger

{
  type = "aura2",
  auranames = {"Power Word: Shield"},
  unit = "player",
  debuffType = "HELPFUL",
  matchesShowOn = "showOnActive"
}

Required Fields

Field	Description	Values
`unit`	Target unit to scan	`player`, `target`, `focus`, `group`, etc.
`debuffType`	Aura type filter	`HELPFUL`, `HARMFUL`, `BOTH`
`auranames`	Spell names to match	Array of strings

Unit Selection

Single Units
Multi-Unit
Multi-Target

{
  unit = "player"   -- Player
  unit = "target"   -- Current target
  unit = "focus"    -- Focus target
  unit = "pet"      -- Player's pet
  unit = "boss1"    -- Boss frame 1
}

{
  unit = "group",      -- All party/raid members
  unit = "party",      -- Party members only
  unit = "raid",       -- Raid members only
  unit = "nameplate"   -- All nameplates
}

{
  unit = "multi",      -- Track on multiple enemies
  useMatch_count = true,
  match_count = 3,
  match_count_operator = ">="
}

Aura Matching

By Spell Name

{
  auranames = {
    "Renew",
    "Power Word: Shield",
    "Prayer of Mending"
  },
  useNamePattern = false  -- Exact match
}

By Spell ID

{
  auraspellids = {
    "48068",  -- Renew (Rank 12)
    "48066"   -- Power Word: Shield (Rank 12)
  },
  use_exact_spellId = true
}

Using spell IDs is more reliable than names, especially for multi-rank spells or localization.

Pattern Matching

{
  auranames = {"^Renew"},  -- Starts with "Renew"
  useNamePattern = true     -- Enable regex patterns
}

Aura Filters

Caster Filter

{
  ownOnly = true  -- Only show if player cast it
}

Debuff Type

{
  debuffType = "HARMFUL",     -- Debuffs only
  debuffClass = {
    magic = true,              -- Magic debuffs
    disease = true             -- Disease debuffs
  }
}

Debuff Classes:

magic - Magic effects
disease - Diseases
poison - Poisons
curse - Curses
none - Physical/other
enrage - Enrage effects (empty string in API)

Stack Count

{
  use_stacks = true,
  stacks = 5,
  stacks_operator = ">="
}

Remaining Time

{
  use_remaining = true,
  remaining = "10",
  remaining_operator = "<"
}

Remaining time checks create scheduled updates, which may impact performance with many active triggers.

Group Aura Tracking

Track auras across multiple units:

{
  unit = "group",
  auranames = {"Renew"},
  useMatch_count = true,
  match_count = 3,
  match_count_operator = ">=",
  useAffected = true  -- Track who has it
}

Group Filters

Role Filters

{
  groupRole = {
    TANK = true,
    HEALER = true
  }
}

Class Filters

{
  class = {
    PRIEST = true,
    PALADIN = true,
    DRUID = true
  }
}

Include Pets

{
  includePets = "PlayersAndPets",  -- Include pets
  includePets = "PetsOnly"         -- Only pets
}

Dead/Disconnected

{
  ignoreDead = true,
  ignoreDisconnected = true,
  ignoreInvisible = true
}

Display Modes

Show on Active

{
  matchesShowOn = "showOnActive"  -- Show when any aura matches
}

Show on Missing

{
  matchesShowOn = "showOnMissing"  -- Show when NO aura matches
}

Show on Matches

{
  matchesShowOn = "showOnMatches",  -- Show based on match count
  useMatch_count = true,
  match_count = 5,
  match_count_operator = ">="
}

Show Clones

{
  showClones = true,  -- Create clone for each aura instance
  combinedMode = "showClones"
}

Clones create separate display instances for each matching aura, useful for DoT trackers.

Combine Modes

Control how multiple aura matches are displayed:

Show One
Show Clones
Show Per Unit

{
  combineMode = "showOne",
  compareFunc = function(a, b)
    return a.expirationTime < b.expirationTime
  end
}

Shows single “best” match based on comparison function.

{
  combineMode = "showClones"
}

Shows separate display for each match.

{
  combineMode = "showPerUnit",
  perUnitMode = "affected"  -- or "all"
}

Shows one display per unit with the aura.

State Properties

Aura triggers provide rich state information:

state = {
  -- Identity
  name = "Renew",
  spellId = 48068,
  icon = "Interface\\Icons\\Spell_Holy_Renew",
  
  -- Unit information  
  unit = "raid5",
  unitName = "Playername",
  GUID = "Player-123-456789",
  
  -- Aura properties
  stacks = 1,
  duration = 15,
  expirationTime = GetTime() + 10,
  progressType = "timed",
  
  -- Caster information
  unitCaster = "player",
  casterName = "Yourname",
  
  -- Classification
  debuffClass = "magic",
  isStealable = false,
  isBossDebuff = false,
  
  -- Group tracking (if applicable)
  matchCount = 5,
  unitCount = 3,
  maxUnitCount = 25,
  affected = "Player1, Player2, Player3",
  affectedUnits = {"raid1", "raid5", "raid12"},
  totalStacks = 15,
  
  -- Tooltip (if enabled)
  tooltip = "Tooltip text",
  tooltip1 = "Line 1",
  tooltip2 = "Line 2"
}

{
  fetchTooltip = true,  -- Enable tooltip scanning
  tooltip_operator = "find('%s')",
  tooltip = "Increases damage"
}

Tooltip scanning adds overhead. Only enable when necessary for trigger logic.

Advanced Matching

Composite Checks

{
  auranames = {"Renew"},
  use_stacks = true,
  stacks = 1,
  use_remaining = true,
  remaining = "5",
  remaining_operator = "<",
  ownOnly = true
}

Custom Scan Function

Implemented in C for performance:

-- Internal scan function checks all conditions
local function scanFunc(time, auraData)
  if triggerInfo.remainingFunc and auraData.expirationTime then
    local remaining = auraData.expirationTime - time
    if not triggerInfo.remainingFunc(remaining) then
      return false
    end
  end
  -- Additional checks...
  return true
end

Performance Optimization

Specific Filters

Use spell IDs and specific unit filters to reduce scanning

Avoid Polling

Remaining time checks are scheduled, not polled

Limit Clones

Use match count limits for clone displays

Disable Tooltips

Only enable tooltip scanning when needed

Common Patterns

Track Specific Buff

{
  type = "aura2",
  unit = "player",
  auranames = {"Bloodlust"},
  debuffType = "HELPFUL",
  matchesShowOn = "showOnActive"
}

Missing Raid Buff

{
  type = "aura2",
  unit = "player",
  auraspellids = {"48470"},  -- Gift of the Wild
  debuffType = "HELPFUL",
  matchesShowOn = "showOnMissing"
}

Multi-DoT Tracker

{
  type = "aura2",
  unit = "multi",
  auranames = {"Shadow Word: Pain", "Vampiric Touch"},
  debuffType = "HARMFUL",
  ownOnly = true,
  showClones = true,
  use_remaining = true,
  remaining = "3",
  remaining_operator = "<"
}

Tank Debuff Monitor

{
  type = "aura2",
  unit = "group",
  debuffType = "HARMFUL",
  debuffClass = {magic = true, curse = true},
  groupRole = {TANK = true},
  useMatch_count = true,
  match_count = 1,
  match_count_operator = ">="
}

Raid Cooldown Tracker

{
  type = "aura2",
  unit = "group",
  auranames = {"Power Infusion", "Bloodlust", "Heroism"},
  debuffType = "HELPFUL",
  combineMode = "showPerUnit",
  perUnitMode = "affected"
}

Troubleshooting

Aura Not Detected

Verify spell name matches exactly (case-sensitive)
Check debuffType matches (HELPFUL vs HARMFUL)
Ensure unit filter is correct
Try using spell ID instead of name

Wrong Unit Shown

Check combine mode settings:

showOne - uses comparison function
showPerUnit - one per affected unit
showClones - one per aura instance

Performance Issues

Reduce tooltip scanning
Use specific spell IDs instead of patterns
Limit multi-target tracking
Avoid unnecessary remaining time checks

Best Practices

Trigger Overview

Learn trigger fundamentals

Custom Lua

Advanced trigger scripting

Conditions

Conditional display modifications

Architecture

Triggers

Display Types

Customization

​Overview

​Basic Aura Trigger

​Required Fields

​Unit Selection

​Aura Matching

​By Spell Name

​By Spell ID

​Pattern Matching

​Aura Filters

​Caster Filter

​Debuff Type

​Stack Count

​Remaining Time

​Group Aura Tracking

​Group Filters

​Display Modes

​Show on Active

​Show on Missing

​Show on Matches

​Show Clones

​Combine Modes

​State Properties

​Tooltip Integration

​Advanced Matching

​Composite Checks

​Custom Scan Function

​Performance Optimization

Specific Filters

Avoid Polling

Limit Clones

Disable Tooltips

​Common Patterns

​Track Specific Buff

​Missing Raid Buff

​Multi-DoT Tracker

​Tank Debuff Monitor

​Raid Cooldown Tracker

​Troubleshooting

​Best Practices

​Related Topics

Trigger Overview

Custom Lua

Conditions

Build docs developers (and LLMs) love

Overview

Basic Aura Trigger

Required Fields

Unit Selection

Aura Matching

By Spell Name

By Spell ID

Pattern Matching

Aura Filters

Caster Filter

Debuff Type

Stack Count

Remaining Time

Group Aura Tracking

Group Filters

Display Modes

Show on Active

Show on Missing

Show on Matches

Show Clones

Combine Modes

State Properties

Tooltip Integration

Advanced Matching

Composite Checks

Custom Scan Function

Performance Optimization

Common Patterns

Track Specific Buff

Missing Raid Buff

Multi-DoT Tracker

Tank Debuff Monitor

Raid Cooldown Tracker

Troubleshooting

Best Practices

Related Topics