Skip to main content

​
What Are Triggers?

Triggers are the core detection system in WeakAuras. They monitor game events and states to determine when your displays should appear, update, or hide.
Every display needs at least one trigger to function. Triggers define when and why a display becomes active.

​
Trigger Architecture

WeakAuras implements two main trigger systems:

Aura Triggers

Specialized system for buffs, debuffs, and auras using BuffTrigger2.lua

Generic Triggers

Event-based system for everything else using GenericTrigger.lua

​
Trigger Types

​
Status Triggers

Monitor ongoing conditions that have duration: 
-- Buff/Debuff status trigger
{
  type = "aura2",
  auranames = {"Power Word: Shield"},
  unit = "player",
  debuffType = "HELPFUL"
}
Examples: Buffs, debuffs, health percentage, power levels

​
Event Triggers

Respond to instantaneous game events: 
-- Combat log event trigger
{
  type = "event",
  event = "COMBAT_LOG_EVENT_UNFILTERED",
  subeventPrefix = "SPELL_CAST_SUCCESS",
  spellIds = {"12345"}
}
Examples: Spell casts, damage events, chat messages

​
Custom Triggers

Use Lua code for complete control: 
-- Custom trigger function
function()
  local health = UnitHealth("player")
  local maxHealth = UnitHealthMax("player")
  return health < maxHealth * 0.3
end

​
Trigger States

Triggers generate states that contain information about what activated: 
state = {
  show = true,           -- Whether to show display
  changed = true,        -- State has changed
  name = "Spell Name",   -- Spell/aura name
  icon = "path/to/icon",
  stacks = 5,            -- Stack count
  duration = 30,         -- Total duration
  expirationTime = time, -- When expires
  progressType = "timed",
  -- Custom properties based on trigger type
}

​
Trigger Loading

WeakAuras loads triggers in phases:
1

Add Phase

Trigger configuration is parsed and validated
2

Compile Phase

Trigger functions are compiled from configuration
3

Load Phase

Events are registered and trigger becomes active
4

Scan Phase

Initial state is established by scanning current conditions

​
Event Registration

Triggers automatically register for relevant game events: 
-- Event registration in GenericTrigger.lua
if data.events then
  for index, event in pairs(data.events) do
    loaded_events[event] = loaded_events[event] or {}
    loaded_events[event][id] = loaded_events[event][id] or {}
    loaded_events[event][id][triggernum] = data
  end
end
Each active trigger registers for game events. Too many complex triggers can impact performance.

​
Trigger Evaluation

When events fire, triggers evaluate conditions: 
-- Event fires -> Test condition -> Update state
function(event, unit)
  if unit == "player" then
    return UnitHealth("player") < 1000
  end
end

​
Multi-Trigger Logic

Combine multiple triggers with boolean logic: 
-- All triggers must be active
{
  disjunctive = "all",  -- AND
  triggers = {
    {1} = trigger1,
    {2} = trigger2
  }
}

​
Trigger Duration

Control how long displays stay visible: 
{
  duration = 10,              -- Fixed duration
  automaticAutoHide = true    -- Auto-hide when duration ends
}

​
Duration Sources

Timed

Fixed or variable duration with expiration time

Static

Progress bar showing value/total

​
Untriggers

Define when displays should hide: 
{
  trigger = function() 
    return UnitAffectingCombat("player")
  end,
  untrigger = function()
    return not UnitAffectingCombat("player")
  end
}
If no untrigger is specified, the display hides when the trigger condition becomes false.

​
Overlays and Additional Progress

Triggers can provide multiple progress sources: 
{
  overlays = {
    {
      type = "progressbar",
      min = 0,
      max = 100,
      value = 50
    }
  }
}

​
Performance Optimization

High-frequency events are automatically throttled:
{
  event = "FRAME_UPDATE",
  onUpdateThrottle = 0.1  -- Update every 0.1 seconds
}
Delay trigger evaluation to reduce CPU usage:
{
  triggerDelay = 0.5  -- Wait 0.5s before evaluating
}
Use specific events instead of polling:
-- Good: Event-based
{ event = "UNIT_HEALTH", unit = "player" }

-- Bad: Polling
{ event = "FRAME_UPDATE" }

​
Trigger API

​
Core Functions

-- Add a new trigger
GenericTrigger.Add(data)

-- Load triggers for display
GenericTrigger.LoadDisplay(id)

-- Unload all triggers
GenericTrigger.UnloadAll()

-- Scan for trigger matches
WeakAuras.ScanEvents(event, ...)

​
Trigger State Access

-- Get current trigger state
local states = WeakAuras.GetTriggerStateForTrigger(id, triggernum)

-- Check if trigger is active
local active = states[""] and states[""].show

​
Common Patterns

​
Health Threshold

{
  type = "status",
  event = "UNIT_HEALTH",
  unit = "player",
  use_percenthealth = true,
  percenthealth = "30",
  percenthealth_operator = "<"
}

​
Cooldown Tracking

{
  type = "spell",
  event = "Cooldown Progress (Spell)",
  use_spellName = true,
  spellName = 12345,
  use_track = true,
  track = "cooldown"
}

​
Proc Detection

{
  type = "event",
  event = "COMBAT_LOG_EVENT_UNFILTERED",
  subeventPrefix = "SPELL_AURA_APPLIED",
  sourceUnit = "player",
  spellIds = {"12345"}
}

​
Best Practices

Buff/Debuff Triggers

Track auras on units

Combat Events

Monitor combat log events

Custom Lua

Write custom trigger code

Build docs developers (and LLMs) love

Get started for freeTalk to us