- Overview
- Event System Basics
- Event Registration Patterns
- Callback-Based Event Registration (12.0.0+)
- Common Events by Category
- New Events (11.x - 12.0.0)
- Removed and Changed Events
- Event Best Practices
- Event Reference
The WoW event system is the backbone of addon development. Events notify addons when something happens in the game world.
Statistics:
- Total Events: 1,800+ events (12.0.0)
- Event Systems: 200+ different systems
Version Note: This document covers WoW 12.0.0 (Midnight expansion). Events may differ in Classic versions.
- Something happens in game (player logs in, item acquired, combat starts, etc.)
- WoW fires an event with that event's name
- All frames registered for that event have their OnEvent handler called
- The handler receives the event name and any payload data
Basic Pattern:
local frame = CreateFrame("Frame")
-- Register for events
frame:RegisterEvent("PLAYER_LOGIN")
frame:RegisterEvent("PLAYER_ENTERING_WORLD")
frame:RegisterEvent("COMBAT_LOG_EVENT_UNFILTERED")
-- Set event handler
frame:SetScript("OnEvent", function(self, event, ...)
if event == "PLAYER_LOGIN" then
print("Player logged in!")
elseif event == "PLAYER_ENTERING_WORLD" then
local isInitialLogin, isReloadingUi = ...
if isInitialLogin then
print("First login on this character")
elseif isReloadingUi then
print("UI was reloaded")
end
elseif event == "COMBAT_LOG_EVENT_UNFILTERED" then
-- NOTE: CombatLogGetCurrentEventInfo() is deprecated in 12.0.0.
-- Combat log data is now restricted. Use C_DamageMeter for damage/healing data.
-- The deprecated global only works if loadDeprecationFallbacks CVar is enabled.
local timestamp, subevent, _, sourceGUID, sourceName = CombatLogGetCurrentEventInfo()
-- Process combat log event
end
end)local MyAddon = {}
function MyAddon:OnEvent(event, ...)
if self[event] then
self[event](self, ...)
end
end
function MyAddon:PLAYER_LOGIN()
print("Logged in!")
end
function MyAddon:BAG_UPDATE(bagID)
print("Bag " .. bagID .. " updated")
end
local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_LOGIN")
frame:RegisterEvent("BAG_UPDATE")
frame:SetScript("OnEvent", function(self, event, ...)
MyAddon:OnEvent(event, ...)
end)-- NOTE: Do not name this "EventRegistry" — that shadows Blizzard's global EventRegistry.
local MyEventDispatcher = {}
function MyEventDispatcher:RegisterEvent(event, callback)
if not self.events then
self.events = {}
end
if not self.events[event] then
self.events[event] = {}
self.frame:RegisterEvent(event)
end
table.insert(self.events[event], callback)
end
function MyEventDispatcher:OnEvent(event, ...)
if self.events and self.events[event] then
for _, callback in ipairs(self.events[event]) do
callback(...)
end
end
end
MyEventDispatcher.frame = CreateFrame("Frame")
MyEventDispatcher.frame:SetScript("OnEvent", function(self, event, ...)
MyEventDispatcher:OnEvent(event, ...)
end)
-- Usage
MyEventDispatcher:RegisterEvent("PLAYER_LOGIN", function()
print("Login callback 1")
end)
MyEventDispatcher:RegisterEvent("PLAYER_LOGIN", function()
print("Login callback 2")
end)local MyFrame = CreateFrame("Frame")
MyFrame:RegisterEvent("PLAYER_LOGIN")
MyFrame:RegisterEvent("PLAYER_LOGOUT")
MyFrame.events = {}
-- Define with . (not :) because the dispatch below passes the frame as self
function MyFrame.events.PLAYER_LOGIN(self)
print("Logged in!")
end
function MyFrame.events.PLAYER_LOGOUT(self)
print("Logging out!")
end
MyFrame:SetScript("OnEvent", function(self, event, ...)
if self.events[event] then
self.events[event](self, ...)
end
end)New in 12.0.0: WoW now provides a native callback-based event registration system that does not require creating frames. This is the recommended approach for new addons.
-- Register a callback for an event
local function OnPlayerLogin(...)
print("Player logged in!")
end
RegisterEventCallback("PLAYER_LOGIN", OnPlayerLogin)
-- Unregister when no longer needed
UnregisterEventCallback("PLAYER_LOGIN", OnPlayerLogin)For unit-specific events, use the unit event callbacks to filter by unit:
-- Register for a specific unit's events
local function OnPlayerHealthChanged(unit, ...)
local health = UnitHealth(unit)
local maxHealth = UnitHealthMax(unit)
-- 12.0.0+: UnitHealth/UnitHealthMax may return secret values during combat
-- or any tainted execution context. Passing a secret through string.format
-- with a %d specifier throws a Lua error, so guard with issecretvalue().
if issecretvalue(health) or issecretvalue(maxHealth) then
print(format("%s health: ???/???", unit))
else
print(format("%s health: %d/%d", unit, health, maxHealth))
end
end
-- Only fires for "player" unit
RegisterUnitEventCallback("UNIT_HEALTH", OnPlayerHealthChanged, "player")
-- Unregister when done
UnregisterUnitEventCallback("UNIT_HEALTH", OnPlayerHealthChanged, "player")You can register multiple callbacks for the same event:
local function Callback1(...)
print("Callback 1 fired")
end
local function Callback2(...)
print("Callback 2 fired")
end
RegisterEventCallback("PLAYER_ENTERING_WORLD", Callback1)
RegisterEventCallback("PLAYER_ENTERING_WORLD", Callback2)
-- Both callbacks will fire when the event occurs| Feature | Frame-Based | Callback-Based (12.0.0+) |
|---|---|---|
| Requires frame creation | Yes | No |
| Memory overhead | Higher | Lower |
| Unregistration | Frame method | Function reference |
| Multiple handlers | Manual dispatch | Native support |
| Unit filtering | RegisterUnitEvent | RegisterUnitEventCallback |
| Backwards compatible | All versions | 12.0.0+ only |
If your addon needs to support both pre-12.0 and 12.0+ clients:
local MyAddon = {}
-- Check if callback system exists
if RegisterEventCallback then
-- Use new callback system
local function OnLogin(...)
MyAddon:OnPlayerLogin(...)
end
RegisterEventCallback("PLAYER_LOGIN", OnLogin)
else
-- Fall back to frame-based
local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_LOGIN")
frame:SetScript("OnEvent", function(self, event, ...)
if event == "PLAYER_LOGIN" then
MyAddon:OnPlayerLogin(...)
end
end)
end
function MyAddon:OnPlayerLogin(...)
print("Logged in!")
endLogin/Logout:
PLAYER_LOGIN- Fired when player logs in (once per session)PLAYER_ENTERING_WORLD- Fired when entering world (login, zoning, reload)- Payload:
isInitialLogin, isReloadingUi
- Payload:
PLAYER_LEAVING_WORLD- Fired when leaving worldPLAYER_LOGOUT- Fired when logging out
Player State:
PLAYER_ALIVE- Player is alivePLAYER_DEAD- Player diedPLAYER_UNGHOST- Player released from deathPLAYER_LEVEL_UP- Player leveled up- Payload:
newLevel, healthGained, powerGained, numNewTalents, numNewPvpTalentSlots, strengthGained, agilityGained, staminaGained, intellectGained
- Payload:
PLAYER_MONEY- Player's money changedPLAYER_XP_UPDATE- XP changedPLAYER_REGEN_DISABLED- Entered combatPLAYER_REGEN_ENABLED- Left combatPLAYER_FLAGS_CHANGED- Player flags changed (AFK, DND, etc.)- Payload:
unit
- Payload:
UNIT_HEALTH- Unit health changed- Payload:
unitTarget
- Payload:
UNIT_POWER_UPDATE- Unit power changed (mana, energy, etc.)- Payload:
unitTarget, powerType
- Payload:
UNIT_AURA- Unit buffs/debuffs changed- Payload:
unitTarget, updateInfo
- Payload:
UNIT_TARGET- Unit's target changed- Payload:
unitTarget
- Payload:
UNIT_SPELLCAST_START- Unit started casting- Payload:
unitTarget, castGUID, spellID
- Payload:
UNIT_SPELLCAST_SUCCEEDED- Unit finished casting- Payload:
unitTarget, castGUID, spellID
- Payload:
UNIT_SPELLCAST_FAILED- Cast failed- Payload:
unitTarget, castGUID, spellID
- Payload:
UNIT_SPELLCAST_INTERRUPTED- Cast interrupted- Payload:
unitTarget, castGUID, spellID
- Payload:
UNIT_DIED- Unit died (12.0.0+)- Payload:
unitTarget
- Payload:
UNIT_LOOT- Unit looted (12.0.0+)- Payload:
unitTarget
- Payload:
UNIT_SPELL_DIMINISH_CATEGORY_STATE_UPDATED- Diminishing returns state changed (12.0.0+)- Payload:
unitTarget, category, state
- Payload:
PLAYER_REGEN_DISABLED- Entered combatPLAYER_REGEN_ENABLED- Left combatCOMBAT_LOG_EVENT_UNFILTERED- Combat log event (deprecated in 12.0.0 — useC_DamageMeterinstead)PLAYER_DAMAGE_DONE_MODS- Damage modifiers changed- Payload:
unit
- Payload:
PARTY_KILL- Party killed a unit (12.0.0+)- Payload:
unitTarget
- Payload:
PLAYER_TARGET_DIED- Player's target died (12.0.0+)CHAT_MSG_ENCOUNTER_EVENT- Encounter event message (12.0.0+)- Payload:
text, ...
- Payload:
Combat Log Processing (DEPRECATED in 12.0.0):
Warning:
CombatLogGetCurrentEventInfo()is deprecated in 12.0.0 and only works when theloadDeprecationFallbacksCVar is enabled. The publicC_CombatLognamespace does not exposeGetCurrentEventInfoto addons. For damage/healing data, use theC_DamageMeterAPI instead. The example below is provided for legacy/Classic compatibility only.
frame:RegisterEvent("COMBAT_LOG_EVENT_UNFILTERED")
frame:SetScript("OnEvent", function(self, event)
if event == "COMBAT_LOG_EVENT_UNFILTERED" then
local timestamp, subevent, _, sourceGUID, sourceName, sourceFlags, sourceRaidFlags,
destGUID, destName, destFlags, destRaidFlags = CombatLogGetCurrentEventInfo()
if subevent == "SPELL_DAMAGE" then
local spellId, spellName, spellSchool, amount, overkill, school, resisted,
blocked, absorbed, critical, glancing, crushing = select(12, CombatLogGetCurrentEventInfo())
-- Process damage
elseif subevent == "SPELL_HEAL" then
local spellId, spellName, spellSchool, amount, overhealing, absorbed,
critical = select(12, CombatLogGetCurrentEventInfo())
-- Process healing
end
end
end)BAG_UPDATE- Bag contents changed- Payload:
bagID
- Payload:
BAG_UPDATE_DELAYED- Bag update finished (throttled version of BAG_UPDATE)ITEM_LOCKED- Item locked (being moved)- Payload:
bagID, slotID
- Payload:
ITEM_UNLOCKED- Item unlocked- Payload:
bagID, slotID
- Payload:
PLAYERBANKSLOTS_CHANGED- Bank slot changed- Payload:
slotID
- Payload:
Note: PLAYERREAGENTBANKSLOTS_CHANGED was removed in 11.2.0 when the Reagent Bank was consolidated into the main bank.
QUEST_ACCEPTED- Quest accepted- Payload:
questID
- Payload:
QUEST_REMOVED- Quest removed- Payload:
questID
- Payload:
QUEST_TURNED_IN- Quest turned in- Payload:
questID, xpReward, moneyReward
- Payload:
QUEST_LOG_UPDATE- Quest log changedQUEST_WATCH_UPDATE- Tracked quest changed- Payload:
questID
- Payload:
QUEST_POI_UPDATE- Quest POI updatedQUEST_AUTOCOMPLETE- Quest auto-completed- Payload:
questID
- Payload:
CHAT_MSG_SAY- Say message- Payload:
text, playerName, languageName, channelName, playerName2, specialFlags, zoneChannelID, channelIndex, channelBaseName, languageID, lineID, guid, bnSenderID, isMobile, isSubtitle, hideSenderInLetterbox, supressRaidIcons
- Payload:
CHAT_MSG_YELL- Yell message (same payload as SAY)CHAT_MSG_WHISPER- Whisper received (same payload)CHAT_MSG_PARTY- Party message (same payload)CHAT_MSG_RAID- Raid message (same payload)CHAT_MSG_GUILD- Guild message (same payload)CHAT_MSG_OFFICER- Officer message (same payload)CHAT_MSG_CHANNEL- Custom channel message (same payload)CHAT_MSG_SYSTEM- System message- Payload:
text
- Payload:
CHAT_MSG_EMOTE- Emote messageCHAT_MSG_ENCOUNTER_EVENT- Encounter/boss event message (12.0.0+)- Payload:
text, ...
- Payload:
ADDON_LOADED- Addon finished loading- Payload:
addOnName
- Payload:
VARIABLES_LOADED- Saved variables loadedPLAYER_LOGIN- Player logged in (UI is ready)UPDATE_MOUSEOVER_UNIT- Mouse is over new unitUI_ERROR_MESSAGE- UI error occurred- Payload:
messageType, message
- Payload:
UI_INFO_MESSAGE- UI info message- Payload:
messageType, message
- Payload:
SETTINGS_LOADED- Settings system loaded (11.0.0+)SETTINGS_PANEL_OPEN- Settings panel opened (12.0.0+)ADDON_RESTRICTION_STATE_CHANGED- Addon restriction state changed (12.0.0+)- Payload:
addonName, state
- Payload:
LOOT_READY- Loot window ready- Payload:
autoloot
- Payload:
LOOT_OPENED- Loot window openedLOOT_CLOSED- Loot window closedLOOT_SLOT_CLEARED- Loot slot cleared- Payload:
slot
- Payload:
LOOT_SLOT_CHANGED- Loot slot changed- Payload:
slot
- Payload:
GROUP_FORMED- Group formedGROUP_JOINED- Joined groupGROUP_LEFT- Left groupGROUP_ROSTER_UPDATE- Group roster changedRAID_ROSTER_UPDATE- Raid roster changedPARTY_LEADER_CHANGED- Party leader changedPARTY_MEMBER_ENABLE- Party member came onlinePARTY_MEMBER_DISABLE- Party member went offline
AUCTION_HOUSE_SHOW- AH openedAUCTION_HOUSE_CLOSED- AH closedAUCTION_OWNED_LIST_UPDATE- Owned auctions updatedAUCTION_BIDDER_LIST_UPDATE- Bid auctions updatedAUCTION_MULTISELL_START- Multi-sell startedAUCTION_MULTISELL_UPDATE- Multi-sell progress- Payload:
numPosted, numTotal
- Payload:
AUCTION_MULTISELL_FAILURE- Multi-sell failed
TRADE_SKILL_SHOW- Profession window openedTRADE_SKILL_CLOSE- Profession window closedTRADE_SKILL_LIST_UPDATE- Recipe list updatedTRADE_SKILL_DATA_SOURCE_CHANGED- Data source changedCRAFT_SHOW- Crafting UI shownCRAFT_CLOSE- Crafting UI closed
ZONE_CHANGED- Zone changedZONE_CHANGED_INDOORS- Indoor/outdoor changedZONE_CHANGED_NEW_AREA- New area enteredPLAYER_STARTED_MOVING- Player started movingPLAYER_STOPPED_MOVING- Player stopped movingMIRROR_TIMER_START- Breath/fatigue timer started- Payload:
timerName, value, maxValue, scale, paused, label
- Payload:
The new Encounter Timeline system provides detailed boss fight information:
ENCOUNTER_TIMELINE_EVENT_ADDED- Timeline event added- Payload:
encounterID, eventID, eventData
- Payload:
ENCOUNTER_TIMELINE_EVENT_REMOVED- Timeline event removed- Payload:
encounterID, eventID
- Payload:
ENCOUNTER_TIMELINE_EVENT_STATE_CHANGED- Event state changed- Payload:
encounterID, eventID, newState
- Payload:
ENCOUNTER_TIMELINE_LAYOUT_UPDATED- Timeline layout refreshed- Payload:
encounterID
- Payload:
ENCOUNTER_WARNING- Boss ability warning- Payload:
text, warningType
- Payload:
ENCOUNTER_STATE_CHANGED- Encounter state changed- Payload:
encounterID, state
- Payload:
Built-in damage meter support:
DAMAGE_METER_COMBAT_SESSION_UPDATED- Combat session data updated- Payload:
type(DamageMeterType),sessionID(number)
- Payload:
DAMAGE_METER_CURRENT_SESSION_UPDATED- Current session data updatedDAMAGE_METER_RESET- Damage meter reset
Combat log system has been refactored with new events:
COMBAT_LOG_APPLY_FILTER_SETTINGS- Filter settings appliedCOMBAT_LOG_ENTRIES_CLEARED- Log entries clearedCOMBAT_LOG_MESSAGE_LIMIT_CHANGED- Message limit changed- Payload:
newLimit
- Payload:
COMBAT_LOG_REFILTER_ENTRIES- Entries being refilteredCOMBAT_LOG_MESSAGE- New combat log message (alternative to CLEU)- Payload:
messageInfo
- Payload:
Over 100 new events for the Housing system. Key events include:
HOUSE_INFO_UPDATED- House information updatedHOUSING_DECOR_PLACE_SUCCESS- Decor item placed successfully- Payload:
decorID, position
- Payload:
HOUSING_DECOR_REMOVE_SUCCESS- Decor item removed- Payload:
decorID
- Payload:
HOUSING_DECOR_INVENTORY_UPDATED- Decor inventory changedHOUSING_MODE_ENTERED- Entered housing edit modeHOUSING_MODE_EXITED- Exited housing edit modeNEIGHBORHOOD_INFO_UPDATED- Neighborhood info changedHOUSING_VISITOR_ENTERED- Visitor entered your house- Payload:
visitorName, visitorGUID
- Payload:
HOUSING_VISITOR_LEFT- Visitor left your house- Payload:
visitorName, visitorGUID
- Payload:
See 12_Housing_System_Guide.md for the complete Housing event reference.
Enhanced transmogrification events:
TRANSMOG_CUSTOM_SETS_CHANGED- Custom transmog sets changedTRANSMOG_DISPLAYED_OUTFIT_CHANGED- Displayed outfit changed- Payload:
outfitID
- Payload:
TRANSMOG_OUTFITS_CHANGED- Outfits list changedVIEWED_TRANSMOG_OUTFIT_STARTED- Started viewing transmog outfit- Payload:
outfitID
- Payload:
VIEWED_TRANSMOG_OUTFIT_ENDED- Stopped viewing transmog outfitVIEWED_TRANSMOG_SOURCE_STARTED- Started viewing transmog source- Payload:
sourceID
- Payload:
VIEWED_TRANSMOG_SOURCE_ENDED- Stopped viewing transmog source
The C_EventScheduler API provides scheduled event support:
EVENT_SCHEDULER_UPDATE- Scheduled event tick- Payload:
schedulerID, elapsed
- Payload:
-- Using the event scheduler
local schedulerID = C_EventScheduler.CreateScheduler(interval, callback)
C_EventScheduler.DestroyScheduler(schedulerID)
-- Listen for updates
RegisterEventCallback("EVENT_SCHEDULER_UPDATE", function(schedulerID, elapsed)
-- Handle scheduled tick
end)SETTINGS_LOADED- Settings system initializedSETTINGS_PANEL_OPEN- Settings panel opened (12.0.0+)SETTINGS_PANEL_CLOSE- Settings panel closed (12.0.0+)
ADDON_RESTRICTION_STATE_CHANGED- Addon restriction state changed- Payload:
addonName, restrictionState - States:
NONE,RESTRICTED,BLOCKED
- Payload:
UNIT_SPELL_DIMINISH_CATEGORY_STATE_UPDATED- DR state updated- Payload:
unitTarget, category, state, timeRemaining
- Payload:
LEARNED_SPELL_IN_TAB- Removed; useLEARNED_SPELLinsteadRETURNING_PLAYER_PROMPT- Behavior changed, event signature modified
With the consolidation of Void Storage and Reagent Bank into the unified Bank system:
Void Storage Events (Removed):
VOID_STORAGE_OPENVOID_STORAGE_CLOSEVOID_STORAGE_UPDATEVOID_STORAGE_CONTENTS_UPDATEVOID_STORAGE_DEPOSIT_UPDATEVOID_TRANSFER_DONE
Reagent Bank Events (Removed):
PLAYERREAGENTBANKSLOTS_CHANGEDREAGENTBANK_PURCHASEDREAGENTBANK_UPDATE
LUA_WARNING (12.0.0):
-- Old (pre-12.0.0):
-- Payload: warnType, message
-- New (12.0.0+):
-- Payload: message
-- warnType parameter removed
-- Compatibility wrapper:
frame:SetScript("OnEvent", function(self, event, arg1, arg2)
local message
if arg2 then
-- Pre-12.0.0 format
message = arg2
else
-- 12.0.0+ format
message = arg1
end
end)VOICE_CHAT_TTS_ Events* (12.0.0): Several voice chat text-to-speech events have had parameters removed:
VOICE_CHAT_TTS_PLAYBACK_STARTED- RemovedvoiceIDparameterVOICE_CHAT_TTS_PLAYBACK_FINISHED- RemovedvoiceIDparameter
Login Sequence:
ADDON_LOADED- Fires once for each addon as it loadsVARIABLES_LOADED- SavedVariables are availablePLAYER_LOGIN- Player is fully loaded, UI is readyPLAYER_ENTERING_WORLD- Player in world (also fires on zone/reload)
Important Notes:
- Saved variables ARE available in
ADDON_LOADED— this is the standard place to initialize them (checkaddonNamematches yours first) VARIABLES_LOADEDfires after all addons have loaded — useful if you depend on another addon's saved dataPLAYER_LOGINfires exactly once per sessionPLAYER_ENTERING_WORLDfires on login, zone, and/reload
-- After you're done with an event (frame-based)
frame:UnregisterEvent("SOME_EVENT")
-- Unregister all events
frame:UnregisterAllEvents()
-- Callback-based (12.0.0+)
UnregisterEventCallback("SOME_EVENT", myCallback)local throttle = 0
frame:SetScript("OnEvent", function(self, event, ...)
if event == "UNIT_HEALTH" then
-- This fires VERY frequently, throttle it
local now = GetTime()
if now - throttle < 0.1 then -- Max 10 times per second
return
end
throttle = now
-- Process event
end
end)-- Bad: Fires too often
frame:RegisterEvent("BAG_UPDATE")
-- Better: Only fires when done updating
frame:RegisterEvent("BAG_UPDATE_DELAYED")-- Bad: Receives all unit health changes
RegisterEventCallback("UNIT_HEALTH", function(unit, ...)
if unit == "player" then
-- Process
end
end)
-- Good: Only receives player health changes
RegisterUnitEventCallback("UNIT_HEALTH", function(unit, ...)
-- Process (always "player")
end, "player")-- Print all events (use sparingly - very spammy!)
local f = CreateFrame("Frame")
f:RegisterAllEvents()
f:SetScript("OnEvent", function(self, event, ...)
print("Event:", event, ...)
end)/eventtrace
Opens a window showing all fired events in real-time.
/fstack
Shows frame names under mouse cursor (useful for finding what handles events).
-- Monitor specific events only
local watchEvents = {
["PLAYER_LOGIN"] = true,
["PLAYER_ENTERING_WORLD"] = true,
["ADDON_LOADED"] = true,
}
local f = CreateFrame("Frame")
for event in pairs(watchEvents) do
f:RegisterEvent(event)
end
f:SetScript("OnEvent", function(self, event, ...)
print(format("[%s] %s: %s", date("%H:%M:%S"), event, strjoin(", ", tostringall(...))))
end)local MyAddon = {}
function MyAddon:EnableCombatTracking()
if not self.combatTrackingEnabled then
self.frame:RegisterEvent("PLAYER_REGEN_DISABLED")
self.frame:RegisterEvent("PLAYER_REGEN_ENABLED")
self.combatTrackingEnabled = true
end
end
function MyAddon:DisableCombatTracking()
if self.combatTrackingEnabled then
self.frame:UnregisterEvent("PLAYER_REGEN_DISABLED")
self.frame:UnregisterEvent("PLAYER_REGEN_ENABLED")
self.combatTrackingEnabled = false
end
endlocal eventQueue = {}
local isReady = false
local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_LOGIN")
frame:RegisterEvent("SOME_OTHER_EVENT")
frame:SetScript("OnEvent", function(self, event, ...)
if not isReady and event ~= "PLAYER_LOGIN" then
-- Queue events until ready
table.insert(eventQueue, {event = event, args = {...}})
return
end
if event == "PLAYER_LOGIN" then
isReady = true
-- Process queued events
for _, queued in ipairs(eventQueue) do
-- Process queued.event with queued.args
end
eventQueue = nil
end
end)For events that may not exist in all client versions, prefer
C_EventUtils.IsEventValid(eventName) (added in Dragonflight, present in
12.0.0+). It returns a boolean, so typos and missing events are visible at
the call site rather than silently swallowed.
-- Preferred: explicit validity check. Typos surface as "event invalid"
-- rather than being silently discarded.
local function SafeRegisterEvent(frame, event)
if C_EventUtils and C_EventUtils.IsEventValid and C_EventUtils.IsEventValid(event) then
frame:RegisterEvent(event)
return true
end
return false
endLegacy fallback (pre-Dragonflight clients only). Older clients without
C_EventUtils wrapped RegisterEvent in pcall so an unknown event name
would be swallowed rather than erroring out. This pattern silently masks
typos, so only use it when targeting clients older than Dragonflight:
-- Legacy: silently no-ops if event doesn't exist. DO NOT USE on 10.x+ —
-- typos will never surface. Kept for cross-version compat only.
local function LegacySafeRegisterEvent(frame, event)
pcall(frame.RegisterEvent, frame, event)
endFor a complete event reference, consult the Blizzard API documentation files located in:
Interface\AddOns\Blizzard_APIDocumentationGenerated\
These files contain all 1,800+ events organized by system, including event payloads and documentation.