- Popular Addon Frameworks
- Common Addon Structures
- Configuration and Options
- Slash Commands
- LibStub and Library Management
- Localization Patterns
- Profile Systems
- Update and Notification Systems
- Performance Best Practices
- Distribution and Packaging
- Addon Categories and 12.0 Compatibility
- Library Updates for 12.0
Most popular addon development framework in the WoW community.
Core Libraries:
- AceAddon-3.0 - Addon management
- AceConsole-3.0 - Slash commands
- AceConfig-3.0 - Configuration GUI
- AceDB-3.0 - Database management with profiles
- AceEvent-3.0 - Event handling
- AceHook-3.0 - Function hooking
- AceGUI-3.0 - GUI widgets
- AceLocale-3.0 - Localization
Note: The following uses Ace3 libraries (AceAddon, AceEvent, AceConsole, AceDB). These are third-party community libraries, not part of the base WoW addon API. For base API equivalents, see the Single-File Addon pattern below or 04_Addon_Structure.md. For detailed Ace3 documentation, see 09a_Ace3_Library_Guide.md.
Basic Ace3 Addon Structure:
-- MyAddon.lua
local AddonName = "MyAddon"
local MyAddon = LibStub("AceAddon-3.0"):NewAddon(AddonName, "AceConsole-3.0", "AceEvent-3.0")
-- Defaults
local defaults = {
profile = {
enabled = true,
message = "Hello, World!",
},
}
function MyAddon:OnInitialize()
-- Database
self.db = LibStub("AceDB-3.0"):New("MyAddonDB", defaults, true)
-- Register slash command
self:RegisterChatCommand("myaddon", "ChatCommand")
end
function MyAddon:OnEnable()
-- Register events
self:RegisterEvent("PLAYER_LOGIN")
end
function MyAddon:OnDisable()
-- Cleanup
end
function MyAddon:PLAYER_LOGIN()
self:Print("MyAddon loaded!")
end
function MyAddon:ChatCommand(input)
if not input or input:trim() == "" then
self:Print("Usage: /myaddon <command>")
else
self:Print("You said:", input)
end
endPattern used by large addons like WeakAuras, DBM, BigWigs:
MyAddon/
├── MyAddon.toc
├── Core.lua # Main addon initialization
├── Config.lua # Configuration/defaults
├── Options.lua # Options GUI
├── Locales/
│ ├── enUS.lua
│ ├── deDE.lua
│ └── frFR.lua
├── Modules/
│ ├── Module1.lua # Feature module 1
│ ├── Module2.lua # Feature module 2
│ └── Module3.lua # Feature module 3
├── UI/
│ ├── MainFrame.xml
│ ├── MainFrame.lua
│ └── Templates.xml
└── Libs/
├── LibStub/
├── AceAddon-3.0/
└── AceDB-3.0/
Module Pattern (Base WoW API):
-- Core.lua
local ADDON_NAME, ns = ...
ns.modules = {}
function ns:RegisterModule(name, module)
self.modules[name] = module
end
function ns:InitModules()
for name, mod in pairs(self.modules) do
if mod.Init then mod:Init() end
end
end
-- Module1.lua
local ADDON_NAME, ns = ...
local Module1 = {}
ns:RegisterModule("Module1", Module1)
function Module1:Init()
print("Module1 initialized")
endLibrary Alternative: Ace3 provides a built-in module system via
AceAddon:NewModule(). See 09a_Ace3_Library_Guide.md.
Simple addons can be just one file:
MySimpleAddon/
├── MySimpleAddon.toc
└── MySimpleAddon.lua
MySimpleAddon.toc:
## Interface: 120005
## Title: My Simple Addon
## Author: Your Name
## Version: 1.0.0
## SavedVariables: MySimpleAddonDB
MySimpleAddon.lua
MySimpleAddon.lua:
local AddonName = "MySimpleAddon"
local DB
-- Initialize
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:RegisterEvent("PLAYER_LOGIN")
frame:SetScript("OnEvent", function(self, event, ...)
if event == "ADDON_LOADED" then
local addonName = ...
if addonName == AddonName then
DB = MySimpleAddonDB or {}
MySimpleAddonDB = DB
end
elseif event == "PLAYER_LOGIN" then
print(AddonName, "loaded!")
end
end)Modern WoW settings integration:
local category = Settings.RegisterVerticalLayoutCategory("MyAddon")
-- Boolean setting
local variable = "MyAddon_Enabled"
local name = "Enable MyAddon"
local tooltip = "Enable or disable the addon"
local defaultValue = true
local setting = Settings.RegisterAddOnSetting(category, variable, variable, Settings.VarType.Boolean, name, defaultValue)
Settings.CreateCheckbox(category, setting, tooltip)
-- Dropdown setting
local function GetOptions()
local container = Settings.CreateControlTextContainer()
container:Add("option1", "Option 1")
container:Add("option2", "Option 2")
container:Add("option3", "Option 3")
return container:GetData()
end
local variable = "MyAddon_DropdownValue"
local name = "Dropdown Setting"
local tooltip = "Select an option"
local defaultValue = "option1"
local setting = Settings.RegisterAddOnSetting(category, variable, variable, Settings.VarType.String, name, defaultValue)
Settings.CreateDropdown(category, setting, GetOptions, tooltip)
-- Register category
Settings.RegisterAddOnCategory(category)Library Alternative (requires Ace3): The following uses AceConfig-3.0 and AceConfigDialog-3.0. See 09a_Ace3_Library_Guide.md for details.
Many addons use Ace3 for configuration as a library convenience:
local options = {
name = "MyAddon",
handler = MyAddon,
type = "group",
args = {
enabled = {
type = "toggle",
name = "Enable",
desc = "Enable/disable the addon",
get = function(info) return MyAddon.db.profile.enabled; end,
set = function(info, value)
MyAddon.db.profile.enabled = value
end,
},
},
}
-- Register options
LibStub("AceConfig-3.0"):RegisterOptionsTable("MyAddon", options)
LibStub("AceConfigDialog-3.0"):AddToBlizOptions("MyAddon", "MyAddon")SLASH_MYADDON1 = "/myaddon"
SLASH_MYADDON2 = "/ma"
SlashCmdList["MYADDON"] = function(msg, editBox)
local command, rest = msg:match("^(%S*)%s*(.-)$")
if command == "show" then
MyAddon:ShowFrame()
elseif command == "hide" then
MyAddon:HideFrame()
elseif command == "config" then
MyAddon:OpenConfig()
else
print("MyAddon commands:")
print(" /myaddon show - Show main frame")
print(" /myaddon hide - Hide main frame")
print(" /myaddon config - Open configuration")
end
endlocal commands = {
["show"] = function()
MyAddon:ShowFrame()
end,
["hide"] = function()
MyAddon:HideFrame()
end,
["set"] = function(rest)
local key, value = rest:match("^(%S+)%s+(.+)$")
if key and value then
MyAddonDB.settings[key] = value
print("Set", key, "to", value)
else
print("Usage: /myaddon set <key> <value>")
end
end,
["get"] = function(rest)
local key = rest:match("^(%S+)")
if key then
print(key, "=", tostring(MyAddonDB.settings[key]))
else
print("Usage: /myaddon get <key>")
end
end,
}
SlashCmdList["MYADDON"] = function(msg)
local command, rest = msg:match("^(%S*)%s*(.-)$")
command = command:lower()
local handler = commands[command]
if handler then
handler(rest)
else
print("Unknown command:", command)
print("Available commands:")
for cmd in pairs(commands) do
print(" /myaddon", cmd)
end
end
endStandard library loader:
-- Check if library already loaded
local lib = LibStub:GetLibrary("MyLib-1.0", true)
if lib then
return lib -- Already loaded
end
-- Create new library
local lib = LibStub:NewLibrary("MyLib-1.0", 1) -- Name, version
if not lib then
return -- Older version already loaded
end
-- Library implementation
function lib:DoSomething()
print("Library function called!")
endPattern used by Ace3 and other community libraries:
The simplest way to use a library is to call it directly:
local MyLib = LibStub("MyLib-1.0"); MyLib:DoSomething(). The embed/mixin pattern below copies library methods onto your addon object for convenience, and is the approach Ace3 uses internally.
-- MyLib.lua
local MAJOR, MINOR = "MyLib-1.0", 1
local lib = LibStub:NewLibrary(MAJOR, MINOR)
if not lib then return; end
-- Embed mixin
lib.embeds = lib.embeds or {}
function lib:Embed(target)
for k, v in pairs(self) do
if type(v) == "function" and k ~= "Embed" then
target[k] = v
end
end
self.embeds[target] = true
end
-- Usage
MyAddon = {}
LibStub("MyLib-1.0"):Embed(MyAddon)
MyAddon:DoSomething() -- Library method now availablelocal L = {}
if GetLocale() == "deDE" then
L["WELCOME"] = "Willkommen!"
elseif GetLocale() == "frFR" then
L["WELCOME"] = "Bienvenue!"
else
L["WELCOME"] = "Welcome!"
end
print(L["WELCOME"])Library Alternative (requires Ace3): See 09_Addon_Libraries_Guide.md for detailed AceLocale documentation.
-- Locales/enUS.lua
local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "enUS", true)
if not L then return; end
L["WELCOME_MESSAGE"] = "Welcome to MyAddon!"
L["OPTION_ENABLED"] = "Enabled"
-- Locales/deDE.lua
local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "deDE")
if not L then return; end
L["WELCOME_MESSAGE"] = "Willkommen bei MyAddon!"
L["OPTION_ENABLED"] = "Aktiviert"
-- Usage in code
local L = LibStub("AceLocale-3.0"):GetLocale("MyAddon")
print(L["WELCOME_MESSAGE"])-- Manual profile system using raw SavedVariables
local ADDON_NAME, ns = ...
local defaultSettings = { fontSize = 12, showTooltips = true }
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:SetScript("OnEvent", function(self, event, addon)
if addon == ADDON_NAME then
MyAddonDB = MyAddonDB or { profiles = {}, currentProfile = "Default" }
local db = MyAddonDB
-- Ensure current profile exists with defaults
local profileName = db.currentProfile
if not db.profiles[profileName] then
db.profiles[profileName] = {}
end
-- Apply defaults to current profile
for k, v in pairs(defaultSettings) do
if db.profiles[profileName][k] == nil then
db.profiles[profileName][k] = v
end
end
ns.settings = db.profiles[profileName]
self:UnregisterEvent("ADDON_LOADED")
end
end)
-- Switch profile
function ns:SetProfile(name)
MyAddonDB.currentProfile = name
if not MyAddonDB.profiles[name] then
MyAddonDB.profiles[name] = {}
for k, v in pairs(defaultSettings) do
MyAddonDB.profiles[name][k] = v
end
end
ns.settings = MyAddonDB.profiles[name]
endLibrary Alternative (requires Ace3): See 09_Addon_Libraries_Guide.md for detailed AceDB documentation.
-- Database with profiles
local defaults = {
profile = {
setting1 = true,
setting2 = "value",
},
}
MyAddon.db = LibStub("AceDB-3.0"):New("MyAddonDB", defaults, true)
-- Access current profile
local profile = MyAddon.db.profile
print(profile.setting1)
-- Change profile
MyAddon.db:SetProfile("ProfileName")
-- Reset profile
MyAddon.db:ResetProfile()local CURRENT_VERSION = "1.2.3"
-- Parse version string
local function ParseVersion(versionString)
local major, minor, patch = versionString:match("(%d+)%.(%d+)%.(%d+)")
return tonumber(major), tonumber(minor), tonumber(patch)
end
-- Compare versions
local function IsNewerVersion(v1, v2)
local major1, minor1, patch1 = ParseVersion(v1)
local major2, minor2, patch2 = ParseVersion(v2)
if major1 > major2 then return true; end
if major1 < major2 then return false; end
if minor1 > minor2 then return true; end
if minor1 < minor2 then return false; end
return patch1 > patch2
end
-- Check for updates
function MyAddon:CheckVersion()
if not MyAddonDB.lastVersion then
-- First install
MyAddonDB.lastVersion = CURRENT_VERSION
self:ShowWelcomeMessage()
elseif IsNewerVersion(CURRENT_VERSION, MyAddonDB.lastVersion) then
-- Updated
self:ShowUpdateMessage(MyAddonDB.lastVersion, CURRENT_VERSION)
MyAddonDB.lastVersion = CURRENT_VERSION
end
endlocal CHANGELOG = {
["1.2.3"] = {
"Added new feature X",
"Fixed bug Y",
"Improved performance",
},
["1.2.2"] = {
"Fixed critical bug",
},
}
function MyAddon:ShowChangelog(fromVersion, toVersion)
print(format("|cff00ff00%s updated from %s to %s|r", AddonName, fromVersion, toVersion))
-- Collect and sort matching versions (pairs order is undefined)
local versions = {}
for version in pairs(CHANGELOG) do
if IsNewerVersion(version, fromVersion) and not IsNewerVersion(version, toVersion) then
versions[#versions + 1] = version
end
end
table.sort(versions, IsNewerVersion)
for _, version in ipairs(versions) do
print(format("|cffFFFF00Version %s:|r", version))
for _, change in ipairs(CHANGELOG[version]) do
print(format(" - %s", change))
end
end
end-- Throttle function calls
local function CreateThrottle(delay)
local lastUpdate = 0
return function(callback)
local now = GetTime()
if now - lastUpdate >= delay then
lastUpdate = now
callback()
end
end
end
-- Usage
local throttledUpdate = CreateThrottle(0.5) -- Max once per 0.5 seconds
frame:SetScript("OnUpdate", function()
throttledUpdate(function()
-- Expensive update code
MyAddon:RefreshDisplay()
end)
end)-- Debounce: Only call after activity stops
local function CreateDebounce(delay)
local timer
return function(callback)
if timer then
timer:Cancel()
end
timer = C_Timer.NewTimer(delay, callback)
end
end
-- Usage
local debouncedSave = CreateDebounce(1.0) -- Wait 1 second after last change
function MyAddon:OnSettingChanged()
debouncedSave(function()
MyAddon:SaveSettings()
end)
end-- Wrapper to identify performance bottlenecks using debugprofilestop()
local function ProfileFunction(funcName, func)
return function(...)
local startTime = debugprofilestop()
local results = SafePack(func(...))
local elapsed = debugprofilestop() - startTime
if elapsed > 1 then -- Log slow calls (>1ms)
print(format("%s took %.2fms", funcName, elapsed))
end
-- SafePack/SafeUnpack preserve trailing nil return values
return SafeUnpack(results)
end
end
-- Wrap expensive functions
MyAddon.ExpensiveFunction = ProfileFunction("ExpensiveFunction", MyAddon.ExpensiveFunction)## Interface: 120005
## Title: My Addon
## Notes: Short description of what the addon does
## Author: Your Name
## Version: @project-version@ # Auto-filled by packager
## X-Category: Interface Enhancements
## X-Website: https://github.com/yourname/myaddon
## X-Curse-Project-ID: 12345
## X-Wago-ID: yourwagoid
## SavedVariables: MyAddonDB
## SavedVariablesPerCharacter: MyAddonCharDB
# Libraries
Libs\LibStub\LibStub.lua
Libs\AceAddon-3.0\AceAddon-3.0.lua
# Localization
Locales\enUS.lua
Locales\deDE.lua
# Core
Core.lua
Config.lua
# Modules
Modules\Module1.lua
Modules\Module2.lua
# UI
UI\Templates.xml
UI\MainFrame.lua
UI\MainFrame.xml
package-as: MyAddon
enable-nolib-creation: no
externals:
Libs/LibStub:
url: https://repos.curseforge.com/wow/libstub/trunk
Libs/AceAddon-3.0:
url: https://repos.curseforge.com/wow/ace3/trunk/AceAddon-3.0
Libs/AceDB-3.0:
url: https://repos.curseforge.com/wow/ace3/trunk/AceDB-3.0
ignore:
- README.md
- .git
- .githubThe 12.0.0 (Midnight) expansion introduces significant API changes that affect most addon categories. This section documents the impact and migration strategies for each major category.
Updated March 2026: While combat log parsing is blocked and C_DamageMeter data is secret-protected during combat, proven workarounds exist that allow third-party damage meters to function. Recount has demonstrated a successful 12.0.1 update using these techniques.
12.0 Changes:
- Combat log events BLOCKED -
RegisterEvent("COMBAT_LOG_EVENT_UNFILTERED")throwsADDON_ACTION_FORBIDDEN - C_DamageMeter data is SECRET during combat - Key values (
name,totalAmount,amountPerSecond) are secret values - Workarounds exist - Secret values can be extracted for display and become fully readable after combat
Migration Strategy for Damage Meter Addons:
-- Use C_DamageMeter API with secret-value workarounds
local sessionData = C_DamageMeter.GetCombatSessionFromType(sessionType, meterType)
for i, source in ipairs(sessionData.combatSources) do
-- WORKAROUND 1: pcall(string.format) extracts secret values as text at C++ level
local ok, dpsText = pcall(string.format, "%.0f", source.amountPerSecond)
if ok then
myFontString:SetText(dpsText .. " DPS")
end
-- WORKAROUND 2: StatusBar accepts secret values at C++ level
pcall(myBar.SetMinMaxValues, myBar, 0, sessionData.maxAmount)
pcall(myBar.SetValue, myBar, source.totalAmount)
-- WORKAROUND 3: Array index = sort order (i=1 is highest)
local syntheticRank = 1000 - i
-- Always accessible (not secret):
local class = source.classFilename -- "DEATHKNIGHT"
local isMe = source.isLocalPlayer -- true/false
end
-- WORKAROUND 4: Post-combat, all values become fully readable
local reparseFrame = CreateFrame("Frame")
reparseFrame:RegisterEvent("PLAYER_REGEN_ENABLED")
reparseFrame:SetScript("OnEvent", function()
C_Timer.After(0.5, function()
-- Full arithmetic, comparisons, string ops now work
ReparseAllSessions()
end)
end)Key Techniques:
pcall(string.format, "%.0f", secretValue)-- formats secret numbers into normal displayable stringsStatusBar:SetValue(secretValue)/SetMinMaxValues()-- proportional bar display with secrets- Array index from
combatSourcespreserves sort order (index 1 = highest) isLocalPlayerandclassFilenameare always accessible for UI styling- After
PLAYER_REGEN_ENABLED+ delay, all values become non-secret for post-combat analysis - See 12a_Secret_Safe_APIs.md for complete documentation of workaround patterns
12.0 Changes:
- C_EncounterTimeline API - Official boss timeline system with phase tracking
- C_EncounterWarnings API - Native boss warnings that addons can supplement
- Secret values - Unit health in boss encounters may show approximated values
Migration Strategy:
-- Check for official encounter systems
local hasEncounterTimeline = C_EncounterTimeline ~= nil
local hasEncounterWarnings = C_EncounterWarnings ~= nil
-- Modern boss mod initialization
function BossMod:OnEncounterStart(encounterID, encounterName, difficultyID, groupSize)
-- Check if official timeline is available
if hasEncounterTimeline then
local phases = C_EncounterTimeline.GetEncounterPhases(encounterID)
if phases then
self:IntegrateOfficialPhases(phases)
end
end
-- Register for official warnings to avoid duplicates
if hasEncounterWarnings then
self:RegisterCallback(C_EncounterWarnings, "OnWarningDisplayed", "HandleOfficialWarning")
end
end
-- Handle secret values for boss health
function BossMod:GetBossHealth(unit)
-- In 12.0+, UnitHealthPercent(unit) returns a 0-1 float without a curve,
-- or 0-100 with CurveConstants.ScaleTo100. No issecretvalue guard needed
-- when called without a curve (SecretWhenCurveSecret only).
if UnitHealthPercent then
return UnitHealthPercent(unit, false, CurveConstants.ScaleTo100) -- Returns 0-100
end
-- Fallback for pre-12.0 (UnitHealth/UnitHealthMax are not secret in older clients)
local health = UnitHealth(unit)
local maxHealth = UnitHealthMax(unit)
if maxHealth > 0 then
return (health / maxHealth) * 100
end
return 0
end
-- Supplement rather than replace official warnings
function BossMod:DisplayWarning(warningType, spellID, text)
-- Check if official warning system will handle this
if hasEncounterWarnings and C_EncounterWarnings.HasWarningForSpell(spellID) then
-- Official system handles it - optionally add supplemental info
return
end
-- Display custom warning
self:ShowWarningFrame(warningType, text)
end12.0 Changes:
- Many global action bar functions moved to C_ActionBar namespace (e.g.,
GetActionTexture,HasAction,IsUsableAction,PickupAction) — the globalGetActionInfo(slot)remains available - Some addons may need updates for functions that were migrated
- New profiler metrics available for optimization
Migration Strategy:
-- 12.0: Prefer C_ActionBar namespace for migrated functions
-- Note: Global GetActionInfo(slot) is NOT removed — still works in 12.0.0
-- Modern action bar texture lookup
local function GetActionSlotTexture(slot)
-- 12.0: Use C_ActionBar namespace for migrated functions
if C_ActionBar.GetActionTexture then
return C_ActionBar.GetActionTexture(slot)
end
return nil
end
-- Action pickup (global PickupAction remains LIVE in 12.0.0 - no C_ActionBar equivalent)
local function PickupActionSlot(slot)
PickupAction(slot)
end
-- Action placement (global PlaceAction remains LIVE in 12.0.0 - no C_ActionBar equivalent)
local function PlaceActionInSlot(slot)
PlaceAction(slot)
end
-- Alternative: C_ActionBar.PutActionInSlot places whatever is on the cursor into slot
local function PutCursorActionInSlot(slot)
if C_ActionBar.PutActionInSlot then
C_ActionBar.PutActionInSlot(slot)
end
end
-- Modern action bar page management
local function GetCurrentActionBarPage()
if C_ActionBar.GetActionBarPage then
return C_ActionBar.GetActionBarPage()
end
return 1
end
-- Check if action has range
local function IsActionInRange(slot, unit)
if C_ActionBar.IsActionInRange then
return C_ActionBar.IsActionInRange(slot, unit)
end
return nil
end
-- Get action cooldown
local function GetActionCooldownInfo(slot)
if C_ActionBar.GetActionCooldown then
return C_ActionBar.GetActionCooldown(slot)
end
return 0, 0, 0
end
-- Full compatibility wrapper for action bar addons
local ActionBarCompat = {}
function ActionBarCompat:Initialize()
-- Verify required APIs exist
assert(C_ActionBar, "C_ActionBar namespace required for 12.0+")
assert(C_ActionBar.GetActionTexture, "C_ActionBar.GetActionTexture required")
assert(C_ActionBar.HasAction, "C_ActionBar.HasAction required")
end
function ActionBarCompat:HasAction(slot)
return C_ActionBar.HasAction(slot)
end
function ActionBarCompat:GetActionTexture(slot)
return C_ActionBar.GetActionTexture(slot)
end
function ActionBarCompat:GetActionText(slot)
return C_ActionBar.GetActionText(slot)
end
function ActionBarCompat:GetActionCharges(slot)
return C_ActionBar.GetActionCharges(slot)
end
function ActionBarCompat:IsUsableAction(slot)
local usable, noMana, noRange = C_ActionBar.IsUsableAction(slot)
return usable, noMana
end12.0 Changes:
- Secret values system - Health and power values may be approximated during combat
- New Unit functions - UnitHealthPercent(), UnitPowerPercent() provide reliable percentages
- Health prediction changes - Must handle secrets in prediction calculations
Migration Strategy:
-- Modern unit health display with secret handling
local function GetUnitHealthDisplay(unit)
-- 12.0: Use percentage functions for reliable display
local percent = UnitHealthPercent and UnitHealthPercent(unit)
if percent then
-- Reliable percentage even with secrets
local maxHealth = UnitHealthMax(unit)
local displayHealth = math.floor(maxHealth * percent / 100)
return displayHealth, maxHealth, percent
end
-- Fallback
local health = UnitHealth(unit)
local maxHealth = UnitHealthMax(unit)
local calcPercent = maxHealth > 0 and (health / maxHealth * 100) or 0
return health, maxHealth, calcPercent
end
-- Modern power display
local function GetUnitPowerDisplay(unit, powerType)
local percent = UnitPowerPercent and UnitPowerPercent(unit, powerType)
if percent then
local maxPower = UnitPowerMax(unit, powerType)
local displayPower = math.floor(maxPower * percent / 100)
return displayPower, maxPower, percent
end
local power = UnitPower(unit, powerType)
local maxPower = UnitPowerMax(unit, powerType)
local calcPercent = maxPower > 0 and (power / maxPower * 100) or 0
return power, maxPower, calcPercent
end
-- Health bar update with secrets awareness
function UnitFrameMixin:UpdateHealth()
local displayHealth, maxHealth, percent = GetUnitHealthDisplay(self.unit)
self.healthBar:SetMinMaxValues(0, maxHealth)
self.healthBar:SetValue(displayHealth)
-- Display percentage for accuracy during secrets
if self.healthText then
if self.showPercentage then
self.healthText:SetText(format("%.0f%%", percent))
else
self.healthText:SetText(AbbreviateNumber(displayHealth))
end
end
end
-- Incoming heal prediction with secrets handling
function UnitFrameMixin:UpdateHealPrediction()
local _, maxHealth, percent = GetUnitHealthDisplay(self.unit)
local incomingHeal = UnitGetIncomingHeals(self.unit) or 0
local absorb = UnitGetTotalAbsorbs(self.unit) or 0
-- Calculate based on percentages for consistency
local currentPercent = percent / 100
local healPercent = maxHealth > 0 and (incomingHeal / maxHealth) or 0
local absorbPercent = maxHealth > 0 and (absorb / maxHealth) or 0
self:SetHealPredictionBars(currentPercent, healPercent, absorbPercent)
endAffects: Any oUF-based addon (ElvUI, SUF, Pitbull via oUF, custom layouts) using the AdditionalPower element on retail.
As of the ElvUI_Libraries v15.13 oUF snapshot, oUF/elements/additionalpower.lua no longer carries its own fallback displayPairs table. Previously, if a consumer did not set element.displayPairs, oUF would populate it from _G.ALT_POWER_BAR_PAIR_DISPLAY_INFO or an internal Druid/Shaman/Priest fallback. That assignment was deleted; the visibility check now reads if element.displayPairs and (...) then, which short-circuits to "no secondary bar" when the consumer didn't supply the table.
Symptom: Druid Balance mana bar (and Shaman Maelstrom / Priest Insanity) silently stops rendering. No error. Just a missing secondary bar.
Fix — consumer must now explicitly supply displayPairs:
local CopyTable = CopyTable
local ManaType = { powerName = 'MANA', powerType = 0 }
-- Use Blizzard's global if available, else the classic per-class fallback:
local ALT_POWER_INFO = _G.ALT_POWER_BAR_PAIR_DISPLAY_INFO
and CopyTable(_G.ALT_POWER_BAR_PAIR_DISPLAY_INFO)
or {
DRUID = { [8] = CopyTable(ManaType) }, -- Balance: LunarPower -> show mana bar
SHAMAN = { [11] = CopyTable(ManaType) }, -- Maelstrom
PRIEST = { [13] = CopyTable(ManaType) }, -- Insanity
}
-- When creating the AdditionalPower element on your unit frame:
local bars = CreateFrame("StatusBar", nil, frame)
bars.displayPairs = ALT_POWER_INFO -- REQUIRED as of this oUF version
frame.AdditionalPower = bars -- oUF element wiringElvUI v15.13 mirrors this in Game/Shared/Modules/UnitFrames/Elements/ClassBars.lua by exposing UF.ALT_POWER_INFO at the module level and assigning bars.displayPairs = UF.ALT_POWER_INFO during frame construction. Third-party oUF layouts should follow the same pattern or they will regress.
12.0 Changes - MAJOR OVERHAUL:
- C_TransmogOutfitInfo namespace - Complete new API for outfit management
- Old outfit APIs removed - C_TransmogSets heavily restructured
- Custom sets system - New player-created outfit functionality
Migration Strategy:
-- Check for 12.0 transmog API
local hasNewTransmogAPI = C_TransmogOutfitInfo ~= nil
-- Modern outfit management
local TransmogCompat = {}
function TransmogCompat:GetOutfits()
if hasNewTransmogAPI and C_TransmogOutfitInfo.GetOutfits then
return C_TransmogOutfitInfo.GetOutfits()
end
-- Legacy fallback
return C_TransmogCollection and C_TransmogCollection.GetOutfits() or {}
end
function TransmogCompat:GetOutfitInfo(outfitID)
if hasNewTransmogAPI and C_TransmogOutfitInfo.GetOutfitInfo then
return C_TransmogOutfitInfo.GetOutfitInfo(outfitID)
end
return nil
end
function TransmogCompat:SaveOutfit(name, sources)
if hasNewTransmogAPI and C_TransmogOutfitInfo.SaveOutfit then
return C_TransmogOutfitInfo.SaveOutfit(name, sources)
end
-- Legacy
if C_TransmogCollection and C_TransmogCollection.SaveOutfit then
return C_TransmogCollection.SaveOutfit(name, sources)
end
return false
end
function TransmogCompat:DeleteOutfit(outfitID)
if hasNewTransmogAPI and C_TransmogOutfitInfo.DeleteOutfit then
return C_TransmogOutfitInfo.DeleteOutfit(outfitID)
end
if C_TransmogCollection and C_TransmogCollection.DeleteOutfit then
return C_TransmogCollection.DeleteOutfit(outfitID)
end
end
function TransmogCompat:GetSlotSources(slotID)
if hasNewTransmogAPI and C_TransmogOutfitInfo.GetSlotSources then
return C_TransmogOutfitInfo.GetSlotSources(slotID)
end
if C_TransmogCollection then
return C_TransmogCollection.GetAppearanceSources(slotID)
end
return {}
end
-- Apply outfit
function TransmogCompat:ApplyOutfit(outfitID)
if hasNewTransmogAPI and C_TransmogOutfitInfo.ApplyOutfit then
C_TransmogOutfitInfo.ApplyOutfit(outfitID)
return true
end
return false
end12.0 Changes:
- Void Storage REMOVED (11.2.0) - Must remove or gracefully handle missing API
- Socket APIs moved to C_ItemSocketInfo namespace (11.2.5+)
- Bank system restructured - New Warband bank integration
Migration Strategy:
-- Check for removed/moved APIs
local hasVoidStorage = C_VoidStorage ~= nil
local hasNewSocketAPI = C_ItemSocketInfo ~= nil
-- Socket API compatibility
local function GetItemSockets(itemLink)
if hasNewSocketAPI and C_ItemSocketInfo.GetItemSockets then
return C_ItemSocketInfo.GetItemSockets(itemLink)
end
-- Legacy fallback
if GetItemStats then
local stats = GetItemStats(itemLink)
return stats and stats["EMPTY_SOCKET_RED"] or 0
end
return 0
end
function GetSocketInfo(socketIndex)
if hasNewSocketAPI and C_ItemSocketInfo.GetSocketInfo then
return C_ItemSocketInfo.GetSocketInfo(socketIndex)
end
-- Legacy
return GetExistingSocketInfo and GetExistingSocketInfo(socketIndex)
end
-- Void Storage handling - gracefully removed
local function HasVoidStorageAccess()
if not hasVoidStorage then
return false -- Feature removed in 11.2.0
end
return CanUseVoidStorage and CanUseVoidStorage()
end
-- Bank compatibility with Warband bank
local function GetBankSlotInfo(bagIndex, slotIndex)
-- Check for Warband bank API
if C_Bank and C_Bank.GetBankSlotInfo then
return C_Bank.GetBankSlotInfo(bagIndex, slotIndex)
end
-- Legacy
return GetContainerItemInfo(bagIndex, slotIndex)
end
-- Modern container iteration
local function IterateBagSlots(bagID, callback)
local numSlots = C_Container.GetContainerNumSlots(bagID)
for slot = 1, numSlots do
local itemInfo = C_Container.GetContainerItemInfo(bagID, slot)
callback(slot, itemInfo)
end
end
-- Inventory addon initialization
function InventoryAddon:Initialize()
self.frame = CreateFrame("Frame")
self.frame:RegisterEvent("BAG_UPDATE")
self.frame:RegisterEvent("BANKFRAME_OPENED")
self.frame:RegisterEvent("BANKFRAME_CLOSED")
self.frame:SetScript("OnEvent", function(_, event, ...)
if InventoryAddon[event] then
InventoryAddon[event](InventoryAddon, ...)
end
end)
-- Remove Void Storage tab if feature is gone
if not hasVoidStorage then
self:RemoveVoidStorageTab()
end
-- Check for Warband bank
if C_Bank and C_Bank.HasWarbandBank then
self:SetupWarbandBankTab()
end
end12.0 introduces player housing with the C_Housing system. This enables an entirely new addon category.
Reference: See 11_Housing_System_Guide.md for complete API documentation.
-- Housing addon base structure (base WoW API)
local ADDON_NAME, ns = ...
local HousingAddon = {}
ns.HousingAddon = HousingAddon
-- Check for housing availability
local hasHousingSystem = C_Housing ~= nil
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:SetScript("OnEvent", function(self, event, ...)
if event == "ADDON_LOADED" and ... == ADDON_NAME then
if not hasHousingSystem then
print("Housing system not available - addon disabled")
return
end
-- Initialize saved variables
MyHousingAddonDB = MyHousingAddonDB or { layouts = {} }
HousingAddon.db = MyHousingAddonDB
-- Register housing events
self:RegisterEvent("HOUSING_ENTERED")
self:RegisterEvent("HOUSING_EXITED")
self:RegisterEvent("HOUSING_DECOR_PLACED")
self:RegisterEvent("HOUSING_DECOR_REMOVED")
self:RegisterEvent("HOUSING_DECOR_MOVED")
self:RegisterEvent("HOUSING_LAYOUT_CHANGED")
self:UnregisterEvent("ADDON_LOADED")
elseif HousingAddon[event] then
HousingAddon[event](HousingAddon, ...)
end
end)
-- Housing state management
function HousingAddon:HOUSING_ENTERED(houseID)
local houseInfo = C_Housing.GetHouseInfo(houseID)
self.currentHouse = houseInfo
self:RefreshDecorList()
end
function HousingAddon:HOUSING_EXITED()
self.currentHouse = nil
end
-- Decor management
function HousingAddon:GetPlacedDecor()
if not self.currentHouse then return {} end
return C_Housing.GetPlacedDecor(self.currentHouse.houseID)
end
function HousingAddon:PlaceDecor(decorID, position, rotation)
if not C_Housing.CanPlaceDecor(decorID) then
print("Cannot place this decor item")
return false
end
return C_Housing.PlaceDecor(decorID, position, rotation)
end
-- Layout save/load
function HousingAddon:SaveLayout(layoutName)
local decor = self:GetPlacedDecor()
local layout = {
name = layoutName,
houseID = self.currentHouse.houseID,
decor = {},
}
for _, item in ipairs(decor) do
table.insert(layout.decor, {
decorID = item.decorID,
position = item.position,
rotation = item.rotation,
})
end
self.db.layouts[layoutName] = layout
print("Layout saved:", layoutName)
end
function HousingAddon:LoadLayout(layoutName)
local layout = self.db.layouts[layoutName]
if not layout then
print("Layout not found:", layoutName)
return
end
-- Clear current decor first
C_Housing.ClearAllDecor()
-- Place saved decor
for _, item in ipairs(layout.decor) do
self:PlaceDecor(item.decorID, item.position, item.rotation)
end
print("Layout loaded:", layoutName)
end
-- Neighborhood features
function HousingAddon:GetNeighborhood()
if C_Housing.GetNeighborhoodInfo then
return C_Housing.GetNeighborhoodInfo()
end
return nil
end
function HousingAddon:VisitNeighbor(playerGUID)
if C_Housing.CanVisitHouse and C_Housing.CanVisitHouse(playerGUID) then
C_Housing.VisitHouse(playerGUID)
return true
end
return false
endSeveral community libraries may need updates or have native replacements in 12.0.
C_EncodingUtil (replaces some LibSerialize/LibCompress functionality):
-- 12.0 native encoding utilities
if C_EncodingUtil then
-- Serialize data to string
local encoded = C_EncodingUtil.EncodeTable(myTable)
-- Deserialize string to data
local decoded = C_EncodingUtil.DecodeTable(encoded)
-- Compress string
local compressed = C_EncodingUtil.CompressString(largeString)
-- Decompress string
local decompressed = C_EncodingUtil.DecompressString(compressed)
else
-- Fallback to libraries
local LibSerialize = LibStub("LibSerialize")
local LibDeflate = LibStub("LibDeflate")
endNative Table Functions (reduce utility library needs):
-- 12.0 native Lua extensions
-- table.create(narr, nrec) - Pre-allocate table memory
local t = table.create(100, 0) -- 100 array slots, 0 hash slots
-- table.count(t) - Count all entries (both array and hash)
local count = table.count(myTable)
-- These reduce need for custom implementations
local function CreatePooledTable(size)
return table.create(size, 0)
end
local function GetTableSize(t)
if table.count then
return table.count(t)
end
-- Fallback
local count = 0
for _ in pairs(t) do count = count + 1; end
return count
endLibraries that need 12.0 updates:
- LibDBIcon - May need updates for minimap changes
- LibDataBroker - Check for compatibility with new UI
- LibActionButton - CRITICAL: Must update for C_ActionBar changes
- LibCompress/LibSerialize - Consider C_EncodingUtil as alternative
- LibQTip - Verify tooltip system compatibility
- LibRangeCheck - May need updates for range API changes
Libraries likely still compatible:
- LibStub - Core loader, should work unchanged
- Ace3 suite - Community maintains compatibility
- CallbackHandler - Pure Lua, no API dependencies
- AceLocale - No API dependencies
- AceDB - SavedVariables system unchanged
Checking Library Compatibility:
-- Verify libraries load without error
local function CheckLibraryCompat(libName)
local success, lib = pcall(function()
return LibStub(libName)
end)
if success and lib then
print(format("%s loaded successfully", libName))
return true
else
print(format("%s FAILED to load: %s", libName, tostring(lib)))
return false
end
end
-- Check critical libraries
CheckLibraryCompat("AceAddon-3.0")
CheckLibraryCompat("AceDB-3.0")
CheckLibraryCompat("AceConfig-3.0")
CheckLibraryCompat("LibDBIcon-1.0")-- Helper module for detecting 12.0 API changes
local APICompat = {}
APICompat.features = {
hasHousing = C_Housing ~= nil,
hasEncodingUtil = C_EncodingUtil ~= nil,
hasNewActionBar = C_ActionBar ~= nil and C_ActionBar.GetActionTexture ~= nil,
hasNewTransmog = C_TransmogOutfitInfo ~= nil,
hasOfficialDamageMeter = C_DamageMeter ~= nil, -- NOTE: API exists but data is secret-protected!
hasEncounterTimeline = C_EncounterTimeline ~= nil,
hasEncounterWarnings = C_EncounterWarnings ~= nil,
hasVoidStorage = C_VoidStorage ~= nil,
hasNewSocketAPI = C_ItemSocketInfo ~= nil,
hasTableCreate = table.create ~= nil,
hasTableCount = table.count ~= nil,
}
function APICompat:PrintCompatReport()
print("=== 12.0 API Compatibility Report ===")
for feature, available in pairs(self.features) do
local status = available and "|cff00ff00YES|r" or "|cffff0000NO|r"
print(format(" %s: %s", feature, status))
end
end
function APICompat:RequiresFeature(featureName)
if not self.features[featureName] then
error(format("Required feature '%s' not available in this WoW version", featureName))
end
end
-- Export for other addons
_G.APICompat = APICompat- Use LibStub for library management
- Implement profile system for settings
- Provide localization support
- Use slash commands for user interaction
- Version your database for migrations
- Throttle/debounce expensive operations
- Follow community naming conventions
- Provide clear documentation
- Use semantic versioning (1.2.3)
- Test with different locales/UI scales
- Don't hardcode English strings
- Don't embed entire libraries if not needed
- Don't pollute global namespace
- Don't break on updates
- Don't ignore user feedback
- Don't use deprecated APIs without fallbacks
- Don't create UI every frame (pool!)
- Don't save temporary data
- Don't ignore memory usage
- Don't ship debug code in release