- TOC File Overview
- TOC Directives Reference
- File Organization Best Practices
- Load Order
- C_AddOns API Reference
- Addon Profiling (11.0.7+)
- Security Changes in 12.0.0
- Dependencies Management
- LoadOnDemand Addons
- Addon Initialization Patterns
- Module Organization
- Library Integration
- Localization Structure
- Example Addon Structures
The TOC (Table of Contents) file is the manifest for your addon. It must:
- Have the same name as the addon folder with
.tocextension - Use UTF-8 encoding
- List all files to be loaded in order
- Define metadata and configuration through directives
File naming convention:
AddonName/
AddonName.toc
AddonName.lua
...
Basic TOC structure:
## Title: My Addon Name
## Interface: 120005
## Author: Your Name
## Version: 1.0.0
## Notes: Brief description of what the addon does
## SavedVariables: MyAddonDB
## Dependencies: SomeOtherAddon
## OptionalDeps: OptionalAddon
# Core files
Core.lua
Utils.lua
# Modules
Modules\Config.lua
Modules\UI.lua
# UI Files
UI.xml
Specifies which game version the addon is compatible with.
## Interface: 120005 # Version 12.0.5 (current Midnight patch)
## Interface: 120000 # Version 12.0.0 (Midnight launch)
## Interface: 0 # Works with any version (Blizzard addons only)
Format: XXYYZZ where XX=expansion, YY=major, ZZ=minor
- Example: 120005 = 12.00.05 (Midnight 12.0.5)
- Example: 120000 = 12.00.00 (Midnight 12.0.0)
- Example: 110207 = 11.02.07 (The War Within 11.2.7)
Since Patch 10.1.0 (May 2023), TOC files support comma-separated Interface versions. This allows a single TOC file to declare compatibility with multiple WoW versions:
## Interface: 120000, 110207, 50503, 40402, 11508
When to use comma-separated versions (single TOC file):
- Your addon code is identical across all WoW versions (Retail, Classic, etc.)
- You don't need to load different files for different game clients
- Simpler maintenance with one TOC file
When to use multiple TOC files:
- You need to load different files for different game versions
- Retail version needs different features than Classic version
- You have version-specific optimizations or code paths
Example - Single TOC with Multiple Versions:
## Interface: 120000, 110207, 50503, 40402, 11508
## Title: My Universal Addon
## Version: 1.0.0
# Same files load on all versions
Core.lua
Utils.lua
Example - Multiple TOC Files (when needed):
MyAddon/
MyAddon_Mainline.toc # ## Interface: 120005
MyAddon_Cata.toc # ## Interface: 40402
MyAddon_Vanilla.toc # ## Interface: 11508
Core.lua # Shared
Retail/Features.lua # Only in Mainline TOC
Classic/Features.lua # Only in Classic TOCs
Current Interface Versions Reference:
| Game Version | Interface Number | Notes |
|---|---|---|
| Retail 12.0.5 | 120005 | Current patch (Midnight) |
| Retail 12.0.1 | 120001 | Midnight launch hotfix |
| Retail 12.0.0 (Midnight) | 120000 | Expansion launch |
| TWW 11.2.7 | 110207 | Previous expansion |
| Classic Cata 4.4.2 | 40402 | Cataclysm Classic |
| Classic SoD/Era 1.15.8 | 11508 | Season of Discovery / Classic Era |
| Wrath Classic 3.4.3 | 30403 | WotLK Classic |
| TBC Classic 2.5.4 | 20504 | Burning Crusade Classic |
Note on Midnight patch numbering: There is no 12.0.2 / 12.0.3 / 12.0.4. Blizzard jumped from 12.0.1 directly to 12.0.5. Next is 12.0.7.
Best Practice Recommendation: For most addons, use comma-separated versions in a single TOC file unless you specifically need different file loading per version. This simplifies maintenance and ensures consistent behavior across clients.
Display name shown in the addon list.
## Title: My Awesome Addon
## Title: |cff00ff00Green|r Colored Title # With color codes
Addon author/creator.
## Author: YourName
## Author: Blizzard Entertainment
Version number for your addon.
## Version: 1.0.0
## Version: 2.3.1-beta
Short description shown in the addon list.
## Notes: Provides enhanced raid frames
## Notes: All aboard for da' island! (Island Queue Screen)
Global saved variables (account-wide, all characters).
## SavedVariables: MyAddonDB
## SavedVariables: GlobalSettings, GlobalCache
Variables are automatically saved/loaded to WTF/Account/<account>/SavedVariables/AddonName.lua
Per-character saved variables.
## SavedVariablesPerCharacter: MyAddonCharDB
## SavedVariablesPerCharacter: CharSettings, CharData
Variables are saved to WTF/Account/<account>/<realm>/<character>/SavedVariables/AddonName.lua
Per-computer saved variables (not synced between machines).
## SavedVariablesMachine: LocalCache
## SavedVariablesMachine: g_addonCategoriesCollapsed
Variables are saved to WTF/SavedVariables/AddonName.lua (at the WTF root, not under Account/) — each installation of the client has its own copy, so data does not sync across machines.
Example from Blizzard addons:
## SavedVariables: g_auctionHouseSortsBySearchContext
## SavedVariablesPerCharacter: g_activeBidAuctionIDs
Required addons that must load first. Addon fails to load if dependencies are missing.
## Dependencies: Blizzard_SharedXML, Blizzard_Colors
## Dependencies: MyOtherAddon
Also written as ## OptionalDep:
Optional addons that will load first if present, but not required.
## OptionalDeps: LibSharedMedia-3.0, LibDataBroker-1.1
## OptionalDep: Blizzard_UIParentPanelManager
Alternative syntax for Dependencies (used in some Blizzard addons).
## RequiredDep: Blizzard_MapCanvas, Blizzard_SharedMapDataProviders
Difference between Dependencies and OptionalDeps:
Dependencies: Hard requirement - addon won't load without themOptionalDeps: Soft requirement - loads if available, ensures load order- Use
OptionalDepsfor libraries you can detect and work without
Controls when the addon loads.
## LoadOnDemand: 0 # Load at startup (default)
## LoadOnDemand: 1 # Load only when requested
When LoadOnDemand: 1, the addon must be loaded via:
-- Check if loaded
if C_AddOns.IsAddOnLoaded("AddonName") then
-- Use addon
end
-- Load the addon
local loaded, reason = C_AddOns.LoadAddOn("AddonName")
if loaded then
-- Initialize
else
print("Failed to load:", reason)
endLoad this addon when specified addons load (only for LoadOnDemand addons).
## LoadOnDemand: 1
## LoadWith: Blizzard_UIParent
Ensures this addon loads before others (Blizzard addons only).
## LoadFirst: 1
Loads saved variables before the addon code executes (11.1.5+).
## LoadSavedVariablesFirst: 1
This is particularly useful when:
- Your addon needs saved data during the initial script execution
- You want to access settings before module initialization
- You need to configure the addon based on user preferences at load time
Without this directive, saved variables are available only after all addon files have loaded (at ADDON_LOADED event).
Controls where the addon can load.
## AllowLoad: Game # In-game only
## AllowLoad: Glue # Login screen only
## AllowLoad: Both # Both game and glue
Game: Normal in-game environment (most addons)Glue: Login/character select screenBoth: Works in both environments
Restricts loading to specific game variants. As of 11.1.5+, this directive is available to all addons (was previously secure-only).
## AllowLoadGameType: mainline # Retail only
## AllowLoadGameType: classic # Classic Era
## AllowLoadGameType: vanilla, tbc, wrath # Multiple versions
## AllowLoadGameType: plunderstorm # Special game modes
Available game types:
mainline- Retail WoWclassic- Classic Eravanilla- Classic Vanillatbc- Burning Crusade Classicwrath- Wrath of the Lich King Classiccata- Cataclysm Classicmists- Mists of Pandariaplunderstorm- Plunderstorm game modewowhack- Special development mode
Per-file loading restrictions (11.1.5+):
# In TOC file - inline AllowLoadGameType for specific files
MainlineFeature.lua [AllowLoadGameType mainline]
ClassicFeature.lua [AllowLoadGameType classic]
SharedFeature.lua
Groups addons under collapsible headers in the addon list (11.1.0+).
## Category: My Addon Category
## Category-deDE: Meine Addon-Kategorie
## Category-frFR: Ma Categorie d'Addon
Use localized variants with Category-<locale>: for different languages. This helps users organize related addons together in their addon management interface.
Links related addons together under a parent addon (11.1.0+).
## Group: MyMainAddon
This is useful for addon suites where multiple addons share functionality:
# MyAddon_Options.toc
## Title: MyAddon - Options
## Group: MyAddon
## LoadOnDemand: 1
# MyAddon_Debug.toc
## Title: MyAddon - Debug Tools
## Group: MyAddon
## LoadOnDemand: 1
Default state in addon list.
## DefaultState: enabled # Enabled by default
## DefaultState: disabled # Disabled by default
Marks addon as secure (can use secure functions in combat).
## Secure: 1
Only applies to Blizzard signed addons.
Controls visibility in addon list.
## ShowInAddOnList: 0 # Hidden from list
## ShowInAddOnList: 1 # Visible (default)
Controls visibility in debug addon list.
## ShowInDebugList: 1 # Show in debug list
Only loads on Beta/PTR realms.
## OnlyBetaAndPTR: 1
Treats any error during load as fatal.
## EscalateErrorDuringLoad: 1
Forces secure execution environment.
## UseSecureEnvironment: 1
Suppresses local table reference warnings.
## SuppressLocalTableRef: 1
Allows other addons to access this addon's namespace table via C_AddOns.GetAddOnLocalTable() (11.1.7+).
## AllowAddOnTableAccess: 1
When enabled, other addons can retrieve your addon's local table:
-- In another addon
local otherAddonTable = C_AddOns.GetAddOnLocalTable("MyAddon")
if otherAddonTable then
-- Access shared data/functions
otherAddonTable.SomeFunction()
endThis provides a cleaner alternative to exposing global tables for addon interoperability.
Icon shown in addon list.
## IconTexture: Interface\ICONS\inv_misc_note_06
Any directive starting with ## X- is custom and ignored by WoW:
## X-Website: https://example.com
## X-Email: author@example.com
## X-License: MIT
## X-Curse-Project-ID: 12345
## X-WoWI-ID: 67890
TOC files support inline variables that expand based on the game environment. This allows a single TOC to load different files for different game variants.
Expands based on game family (Mainline vs Classic):
[Family]\Init.lua
# Expands to:
# - Mainline\Init.lua (on Retail)
# - Classic\Init.lua (on Classic versions)
Expands based on specific game version:
[Game]\Features.lua
# Expands to:
# - Standard\Features.lua (Retail)
# - Mists\Features.lua (MoP Remix)
# - Vanilla\Features.lua (Classic Era)
# - Wrath\Features.lua (WotLK Classic)
# - Cata\Features.lua (Cata Classic)
Expands based on client locale:
Locales\[TextLocale].lua
# Expands to:
# - Locales\enUS.lua (English US)
# - Locales\deDE.lua (German)
# - Locales\frFR.lua (French)
# - Locales\esES.lua (Spanish Spain)
# - Locales\zhCN.lua (Chinese Simplified)
# etc.
Combine inline variables with AllowLoadGameType conditions:
# Load different files based on game type
MainlineFeatures.lua [AllowLoadGameType mainline]
ClassicFeatures.lua [AllowLoadGameType vanilla, tbc, wrath, cata]
# Using Family variable
[Family]\Core.lua
[Family]\UI.lua
# Conditional with variables
RetailUI.lua [AllowLoadGameType mainline]
ClassicUI.lua [AllowLoadGameType classic]
Complete example using inline variables:
## Interface: 120005
## Title: MultiPlatform Addon
## Version: 1.0.0
# Shared core
Core.lua
# Family-specific initialization
[Family]\Init.lua
# Locale-specific strings (loads only matching locale file)
Locales\[TextLocale].lua
# Conditional modules
RetailModule.lua [AllowLoadGameType mainline]
ClassicModule.lua [AllowLoadGameType vanilla, tbc, wrath]
MyAddon/
MyAddon.toc
MyAddon.lua
MyAddon/
MyAddon.toc # TOC file
Core.lua # Core initialization
Config.lua # Configuration
Utils.lua # Utility functions
UI.lua # UI code
Locales.lua # Localization
MyAddon/
MyAddon.toc
# Core
Core.lua # Addon initialization
Constants.lua # Constants and enums
# Libraries (embed if needed)
Libs/
LibStub.lua
CallbackHandler-1.0.lua
# Localization
Locales/
enUS.lua # English (default)
deDE.lua # German
frFR.lua # French
esES.lua # Spanish
zhCN.lua # Chinese Simplified
# Modules
Modules/
Database.lua
Events.lua
Commands.lua
Config.lua
# UI
UI/
MainFrame.lua
MainFrame.xml
OptionsPanel.lua
OptionsPanel.xml
# Data
Data/
Items.lua
Spells.lua
MyAddon/
MyAddon.toc
MyAddon_Mainline.toc # Retail-specific TOC
MyAddon_Classic.toc # Classic-specific TOC
Init.lua # Pre-initialization
Core.lua # Main initialization
Libs/ # Embedded libraries (optional)
LibStub/
CallbackHandler-1.0/
# Add community libraries as needed (see 09_Addon_Libraries_Guide.md)
Locales/
Locale.lua # Locale loader
enUS.lua
[other locales...]
Core/ # Core systems
Database.lua
Events.lua
Utilities.lua
API.lua
Modules/ # Feature modules
Module1/
Module1.lua
Module1.xml
Module2/
Module2.lua
Submodule.lua
UI/ # User interface
Templates/
Templates.xml
Frames/
MainFrame.lua
MainFrame.xml
Dialogs/
Dialogs.lua
Dialogs.xml
Config/ # Configuration
Defaults.lua
Options.lua
Profiles.lua
Data/ # Static data
Constants.lua
Tables.lua
-
Dependencies load first
Dependenciesaddons load before your addonOptionalDepsload before your addon (if present)LoadFirstensures priority loading
-
Files load in TOC order
- Files are loaded in the exact order listed in the TOC
- Lua files load before XML files at the same level
- XML files can reference Lua objects already loaded
-
Saved variables load timing
- Without
LoadSavedVariablesFirst: Variables available after all files load - With
LoadSavedVariablesFirst: Variables available before first file loads
- Without
Standard pattern:
# TOC file - typical loading pattern
Init.lua # Loads first
Core.lua # Then core
Utils.lua # Then utilities
Templates.xml # XML after Lua
MainFrame.lua # Frame logic
MainFrame.xml # Frame XML
Lua before XML rule:
- Always list
.luafiles before corresponding.xmlfiles - XML can reference Lua functions/tables, not vice versa
- Templates in XML must be defined before use
## MyAddon.toc
# Libraries (load first, if embedding any)
Libs\LibStub.lua
Libs\CallbackHandler-1.0.lua
# Core initialization (needs libraries)
Init.lua
Core.lua
# Localization (before modules need it)
Locales\enUS.lua
Locales\Locale.lua
# Data (before modules)
Data\Constants.lua
Data\Items.lua
# Modules (can use core, locales, data)
Modules\Database.lua
Modules\Events.lua
# UI (last - uses everything)
UI\Templates.xml # XML templates
UI\MainFrame.lua # Frame logic
UI\MainFrame.xml # Frame definition
-- File load time (when file is parsed)
local MyAddon = {}
-- Use ADDON_LOADED and PLAYER_LOGIN with a single event handler
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:RegisterEvent("PLAYER_LOGIN")
frame:SetScript("OnEvent", function(self, event, addonName)
if event == "ADDON_LOADED" and addonName == "MyAddon" then
-- This addon just loaded
-- Saved variables are definitely available
self:UnregisterEvent("ADDON_LOADED")
elseif event == "PLAYER_LOGIN" then
-- Player is fully loaded
-- All game data available
self:UnregisterEvent("PLAYER_LOGIN")
end
end)The C_AddOns namespace provides functions for querying and managing addon information programmatically.
-- Get number of addons
local count = C_AddOns.GetNumAddOns()
-- Get addon info by index or name
local name, title, notes, loadable, reason, security = C_AddOns.GetAddOnInfo(indexOrName)
-- Check if addon is loaded
local isLoaded = C_AddOns.IsAddOnLoaded(indexOrName)
-- Load an addon (LoadOnDemand addons)
local loaded, reason = C_AddOns.LoadAddOn(name)
-- Enable/disable addon for next session
C_AddOns.EnableAddOn(name, character)
C_AddOns.DisableAddOn(name, character)
-- Check enable state
local enabled = C_AddOns.GetAddOnEnableState(name, character)-- Get addon interface version (11.0.5+)
local interfaceVersion = C_AddOns.GetAddOnInterfaceVersion(name)
-- Access another addon's namespace table (11.1.7+)
-- Requires ## AllowAddOnTableAccess: 1 in target addon's TOC
local addonTable = C_AddOns.GetAddOnLocalTable("OtherAddonName")
-- Check for load errors (11.0.5+)
local hasError = C_AddOns.DoesAddOnHaveLoadError(name)
-- Check if addon is default enabled (11.1.0+)
local isDefaultEnabled = C_AddOns.IsAddOnDefaultEnabled(name)
-- Individual info functions (cleaner than GetAddOnInfo)
local name = C_AddOns.GetAddOnName(index)
local notes = C_AddOns.GetAddOnNotes(indexOrName)
local security = C_AddOns.GetAddOnSecurity(indexOrName)
local title = C_AddOns.GetAddOnTitle(indexOrName)-- List all loaded addons
local count = C_AddOns.GetNumAddOns()
for i = 1, count do
local name = C_AddOns.GetAddOnName(i)
if C_AddOns.IsAddOnLoaded(name) then
local title = C_AddOns.GetAddOnTitle(name)
local version = C_AddOns.GetAddOnInterfaceVersion(name)
print(format("%s (Interface: %d)", title, version))
end
end
-- Access another addon's API (requires AllowAddOnTableAccess)
local DBM = C_AddOns.GetAddOnLocalTable("DBM-Core")
if DBM and DBM.RegisterCallback then
DBM.RegisterCallback(myCallback)
endThe C_AddOnProfiler namespace provides performance metrics for addon debugging and optimization.
In 12.0.0+, C_AddOnProfiler is always enabled -- no CVar or UI toggle is needed. The functions below work out of the box.
In pre-12.0.0 clients, the legacy GetAddOnCPUUsage() / UpdateAddOnCPUUsage() functions required /console scriptProfile 1 (plus a UI reload) to activate. Those legacy functions were removed in 12.0.0; use C_AddOnProfiler.GetAddOnMetric() instead.
-- Check if profiling is enabled
local isEnabled = C_AddOnProfiler.IsEnabled()
-- Get specific metric for an addon
local value = C_AddOnProfiler.GetAddOnMetric(addonName, metric)
-- Get overall metric across all addons
local value = C_AddOnProfiler.GetOverallMetric(metric)
-- Measure a specific function call (11.1.7+)
local elapsed = C_AddOnProfiler.MeasureCall(func, ...)
-- Get profiler tick rate (11.1.7+)
local ticksPerSecond = C_AddOnProfiler.GetTicksPerSecond()| Metric | Description |
|---|---|
SessionAverageTime |
Average time per frame across session |
RecentAverageTime |
Average time per frame (recent samples) |
EncounterAverageTime |
Average time during boss encounters |
LastTime |
Time taken in last frame |
PeakTime |
Maximum time recorded |
CountTimeOver1Ms |
Frames exceeding 1ms |
CountTimeOver5Ms |
Frames exceeding 5ms |
CountTimeOver10Ms |
Frames exceeding 10ms |
CountTimeOver50Ms |
Frames exceeding 50ms |
-- Check addon performance
if C_AddOnProfiler.IsEnabled() then
local avgTime = C_AddOnProfiler.GetAddOnMetric("MyAddon", "RecentAverageTime")
local peakTime = C_AddOnProfiler.GetAddOnMetric("MyAddon", "PeakTime")
local slowFrames = C_AddOnProfiler.GetAddOnMetric("MyAddon", "CountTimeOver5Ms")
print(format("MyAddon - Avg: %.3fms, Peak: %.3fms, Slow frames: %d",
avgTime * 1000, peakTime * 1000, slowFrames))
end
-- Measure specific function performance (11.1.7+)
local function HeavyOperation()
-- Complex calculation
end
local elapsed = C_AddOnProfiler.MeasureCall(HeavyOperation)
print(format("Operation took %.3fms", elapsed * 1000))Based on profiler data:
RecentAverageTime > 1ms: Consider optimizing frequent operationsCountTimeOver5Ms > 0: Look for expensive operations causing hitchesPeakTimehigh: Investigate startup or event burst handlingEncounterAverageTimehigh: Optimize combat-related code
The 12.0.0 expansion introduces significant security changes affecting addon development:
12.0.0 expands the "secret values" system for combat security:
- Certain API return values become "tainted" during combat
- Tainted values cannot be used for secure operations
- Addons may need to cache values before combat or handle nil returns
- Action button addons: May need additional checks for tainted values
- Unit frame addons: Some unit information may be restricted during combat
- Macro/automation addons: Increased restrictions on programmatic actions
- Test addons thoroughly on PTR before 12.0.0 launch
- Cache important values during
PLAYER_REGEN_ENABLED - Check
InCombatLockdown()before secure operations - Reference 12_API_Migration_Guide.md for detailed migration steps
Use Dependencies when:
- Addon cannot function without it
- You use embedded libraries that must exist
- You extend another addon's functionality
Use OptionalDeps when:
- You can detect and work without the dependency
- You want to add features if a library is present
- You need load order but not requirement
Use RequiredDep when:
- Same as
Dependencies(Blizzard convention) - Seen in newer Blizzard addons
## Dependencies: Blizzard_MapCanvas
# In code - dependency is guaranteed loaded first
local mapFrame = WorldMapFrame
## OptionalDeps: LibSharedMedia-3.0
# In code - check before use
local LSM = LibStub:GetLibrary("LibSharedMedia-3.0", true)
if LSM then
-- Use LSM features
LSM:Register("font", "MyFont", [[Fonts\MyFont.ttf]])
else
-- Fallback without LSM
print("LibSharedMedia not available")
end
# TOC file - embed libraries directly
Libs\LibStub\LibStub.lua
Libs\CallbackHandler-1.0\CallbackHandler-1.0.lua
Libs\LibDataBroker-1.1\LibDataBroker-1.1.lua
# No Dependencies directive needed - libraries are embedded
## MyTooltipAddon.toc
## Title: My Tooltip Addon
## Dependencies: MyMainAddon
# Lua file
local MyMainAddon = _G.MyMainAddon
if MyMainAddon then
-- Extend main addon
MyMainAddon:RegisterTooltipProvider(MyTooltipAddon)
end
Problem:
AddonA: ## Dependencies: AddonB
AddonB: ## Dependencies: AddonA
Result: Neither loads!
Solution: Use OptionalDeps for one direction
AddonA: ## Dependencies: AddonB
AddonB: ## OptionalDeps: AddonA
Good uses:
- UI panels that aren't always needed (options, configuration)
- Feature modules users may not use
- Memory-intensive components
- Integration with other addons
Bad uses:
- Core functionality
- Event handlers needed at login
- Small addons (overhead not worth it)
## MyAddon_Options.toc
## Title: MyAddon Options
## LoadOnDemand: 1
## Dependencies: MyAddon
## OptionalDeps: MyAddon
Options.lua
OptionsUI.xml
-- In main addon - load when needed
local function ShowOptions()
local loaded, reason = C_AddOns.LoadAddOn("MyAddon_Options")
if loaded then
MyAddon_Options:Show()
else
print("Failed to load options:", reason)
end
end## MyAddon_GuildFeatures.toc
## Title: MyAddon Guild Features
## LoadOnDemand: 1
## LoadWith: Blizzard_GuildUI
## Dependencies: MyAddon
GuildFeatures.lua
Automatically loads when guild frame opens.
-- Check if already loaded
if not C_AddOns.IsAddOnLoaded("MyAddon_Options") then
-- Check if available
local name, title, notes, loadable, reason = C_AddOns.GetAddOnInfo("MyAddon_Options")
if loadable then
C_AddOns.LoadAddOn("MyAddon_Options")
else
print("Cannot load:", reason)
-- Reasons: "DISABLED", "MISSING", "INCOMPATIBLE", "CORRUPT"
end
end
-- Check if addon is loadable
local _, _, _, loadable, reason = C_AddOns.GetAddOnInfo("MyAddon_Options")
if loadable then
print("This addon can be loaded")
elseif reason then
print("Cannot load: " .. reason)
end-- Detect when LOD addon loads
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:SetScript("OnEvent", function(self, event, addonName)
if addonName == "MyAddon_Options" then
-- Options addon just loaded
MyAddon_Options:Initialize(MyAddon)
frame:UnregisterEvent("ADDON_LOADED")
end
end)Best for: Small addons, simple functionality
-- MyAddon.lua
MyAddon = {}
MyAddon.version = "1.0.0"
function MyAddon:Initialize()
print("MyAddon loaded!")
end
-- Create event frame
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:SetScript("OnEvent", function(self, event, addonName)
if addonName == "MyAddon" then
MyAddon:Initialize()
self:UnregisterEvent("ADDON_LOADED")
end
end)Best for: Medium to large addons
-- Core.lua
local ADDON_NAME, ns = ...
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:RegisterEvent("PLAYER_LOGIN")
frame:SetScript("OnEvent", function(self, event, ...)
if event == "ADDON_LOADED" and ... == ADDON_NAME then
-- Saved variables available
ns.db = MyAddonDB or {}
MyAddonDB = ns.db
self:UnregisterEvent("ADDON_LOADED")
elseif event == "PLAYER_LOGIN" then
-- All game data available, initialize UI
ns:Initialize()
end
end)
function ns:Initialize()
-- Register slash command
SLASH_MYADDON1 = "/myaddon"
SlashCmdList["MYADDON"] = function(msg)
ns:HandleSlashCommand(msg)
end
print("MyAddon loaded!")
endLibrary alternative: For Ace3-based initialization using
OnInitialize/OnEnablecallbacks, see 09a_Ace3_Library_Guide.md.
Best for: Large addons, avoiding global pollution
-- Init.lua - Create namespace
local ADDON_NAME, ns = ...
ns.version = "1.0.0"
-- Core.lua - Use namespace
local ADDON_NAME, ns = ...
ns.Core = {}
function ns.Core:Initialize()
print(ADDON_NAME .. " v" .. ns.version)
end
-- Events.lua - Add to namespace
local ADDON_NAME, ns = ...
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:SetScript("OnEvent", function(self, event, addonName)
if addonName == ADDON_NAME then
ns.Core:Initialize()
end
end)Best for: Very large addons, clean separation of concerns
-- Core.lua
local ADDON_NAME, ns = ...
local MyAddon = {}
ns.MyAddon = MyAddon
MyAddon.modules = {}
function MyAddon:RegisterModule(name, module)
self.modules[name] = module
if module.OnInitialize then
module:OnInitialize(self)
end
end
function MyAddon:GetModule(name)
return self.modules[name]
end
-- Module1.lua
local ADDON_NAME, ns = ...
local MyAddon = ns.MyAddon
local Module1 = {}
function Module1:OnInitialize(core)
self.core = core
print("Module1 initialized")
end
function Module1:DoSomething()
-- Module functionality
end
MyAddon:RegisterModule("Module1", Module1)
-- Usage
local module = MyAddon:GetModule("Module1")
module:DoSomething()Best for: Complex initialization sequences
local MyAddon = {}
local initialized = false
local loginComplete = false
-- Stage 1: Addon files loaded
local function OnAddonLoaded()
-- Saved variables available
MyAddon.db = MyAddonDB or {}
MyAddon:LoadModules()
end
-- Stage 2: Player enters world
local function OnPlayerLogin()
-- Game data available
MyAddon:InitializeUI()
loginComplete = true
end
-- Stage 3: Player entering world complete
local function OnPlayerEnteringWorld()
if not initialized then
MyAddon:CompleteInitialization()
initialized = true
end
end
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:RegisterEvent("PLAYER_LOGIN")
frame:RegisterEvent("PLAYER_ENTERING_WORLD")
frame:SetScript("OnEvent", function(self, event, ...)
if event == "ADDON_LOADED" and select(1, ...) == "MyAddon" then
OnAddonLoaded()
elseif event == "PLAYER_LOGIN" then
OnPlayerLogin()
elseif event == "PLAYER_ENTERING_WORLD" then
OnPlayerEnteringWorld()
end
end)-- Core.lua
local ADDON_NAME, ns = ...
ns.modules = {}
ns.moduleOrder = {}
function ns:RegisterModule(name, module)
if self.modules[name] then
error("Module already registered: " .. name)
end
self.modules[name] = module
table.insert(self.moduleOrder, name)
if module.Initialize then
module:Initialize()
end
end
function ns:GetModule(name)
return self.modules[name]
end
function ns:InitializeAllModules()
for _, name in ipairs(self.moduleOrder) do
local module = self.modules[name]
if module.OnEnable then
module:OnEnable()
end
end
end
-- Module template
local function CreateModule(name)
local module = {
name = name,
enabled = false
}
function module:Initialize()
-- Setup
end
function module:OnEnable()
self.enabled = true
-- Enable module
end
function module:OnDisable()
self.enabled = false
-- Cleanup
end
return module
end-- Modules/Database.lua
local ADDON_NAME, ns = ...
local Database = CreateModule("Database")
function Database:Initialize()
self.cache = {}
end
function Database:Set(key, value)
self.cache[key] = value
end
function Database:Get(key)
return self.cache[key]
end
ns:RegisterModule("Database", Database)-- Modules/Events.lua
local ADDON_NAME, ns = ...
local Events = CreateModule("Events")
function Events:Initialize()
self.frame = CreateFrame("Frame")
self.callbacks = {}
end
function Events:RegisterCallback(event, callback)
if not self.callbacks[event] then
self.callbacks[event] = {}
self.frame:RegisterEvent(event)
end
table.insert(self.callbacks[event], callback)
end
function Events:OnEnable()
self.frame:SetScript("OnEvent", function(frame, event, ...)
if self.callbacks[event] then
for _, callback in ipairs(self.callbacks[event]) do
callback(event, ...)
end
end
end)
end
ns:RegisterModule("Events", Events)LibStub is a widely-used community library loader for WoW addons (not part of the base WoW API — see 09_Addon_Libraries_Guide.md).
-- Embedding LibStub
## TOC file
Libs\LibStub\LibStub.lua
Libs\CallbackHandler-1.0\CallbackHandler-1.0.lua
Libs\LibDataBroker-1.1\LibDataBroker-1.1.lua
-- Using LibStub
local LibStub = LibStub
local LDB = LibStub("LibDataBroker-1.1")
-- Check if library exists (safe)
local LSM = LibStub("LibSharedMedia-3.0", true) -- true = silent fail
if LSM then
-- Use LibSharedMedia
endFor Ace3 library usage (AceAddon, AceDB, AceConfig, AceGUI, etc.), see 09a_Ace3_Library_Guide.md.
## OptionalDeps: LibSharedMedia-3.0
local LSM = LibStub("LibSharedMedia-3.0", true)
if LSM then
-- Register custom media
LSM:Register("font", "MyFont", [[Fonts\MyFont.ttf]])
LSM:Register("background", "MyTexture", [[Textures\Background.tga]])
LSM:Register("sound", "MySound", [[Sounds\Alert.ogg]])
-- Use registered media
local fontPath = LSM:Fetch("font", "MyFont")
fontString:SetFont(fontPath, 12, "OUTLINE")
endlocal LDB = LibStub("LibDataBroker-1.1", true)
if LDB then
local dataObject = LDB:NewDataObject("MyAddon", {
type = "data source",
icon = "Interface\\Icons\\inv_misc_note_01",
label = "MyAddon",
text = "0/100",
OnClick = function(self, button)
if button == "LeftButton" then
-- Handle click
end
end,
OnTooltipShow = function(tooltip)
tooltip:AddLine("MyAddon")
tooltip:AddLine("Click to toggle")
end
})
-- Update data
dataObject.text = "50/100"
end-- Locales/enUS.lua (default locale)
local L = {}
L["Hello"] = "Hello"
L["Goodbye"] = "Goodbye"
L["Welcome %s"] = "Welcome %s"
-- Store in addon namespace
local ADDON_NAME, ns = ...
ns.L = L-- Locales/deDE.lua (German)
local ADDON_NAME, ns = ...
local L = ns.L -- Get existing table from namespace
if GetLocale() == "deDE" then
L["Hello"] = "Hallo"
L["Goodbye"] = "Auf Wiedersehen"
L["Welcome %s"] = "Willkommen %s"
endFor AceLocale-3.0 based localization, see 09a_Ace3_Library_Guide.md.
## TOC file
Locales\Locale.xml # Load all locales
# Or load individually
Locales\enUS.lua
Locales\deDE.lua
Locales\frFR.lua
Locales\esES.lua
Locales\zhCN.lua
Locales\zhTW.lua
Locales\koKR.lua
Locales\ruRU.lua
<!-- Locales/Locale.xml -->
<Ui xmlns="http://www.blizzard.com/wow/ui/">
<Script file="enUS.lua"/>
<Script file="deDE.lua"/>
<Script file="frFR.lua"/>
<Script file="esES.lua"/>
<Script file="zhCN.lua"/>
<Script file="zhTW.lua"/>
<Script file="koKR.lua"/>
<Script file="ruRU.lua"/>
</Ui>Purpose: Display a message on login
SimpleAddon/
SimpleAddon.toc
SimpleAddon.lua
SimpleAddon.toc:
## Interface: 120005
## Title: Simple Addon
## Author: YourName
## Version: 1.0.0
## Notes: Shows a welcome message
SimpleAddon.lua
SimpleAddon.lua:
local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_LOGIN")
frame:SetScript("OnEvent", function(self, event)
print("Welcome to SimpleAddon!")
end)Purpose: Track player gold across characters
GoldTracker/
GoldTracker.toc
Core.lua
Database.lua
UI.lua
Locales.lua
GoldTracker.toc:
## Interface: 120005
## Title: Gold Tracker
## Author: YourName
## Version: 1.0.0
## SavedVariablesPerCharacter: GoldTrackerDB
## SavedVariables: GoldTrackerGlobal
Core.lua
Database.lua
Locales.lua
UI.lua
Core.lua:
local ADDON_NAME, ns = ...
GoldTracker = {}
ns.GoldTracker = GoldTracker
local function OnAddonLoaded()
GoldTracker.db = GoldTrackerDB or {}
GoldTracker.global = GoldTrackerGlobal or {}
end
local function OnPlayerMoney()
local money = GetMoney()
local playerName = UnitName("player")
local realmName = GetRealmName()
GoldTracker.global[realmName] = GoldTracker.global[realmName] or {}
GoldTracker.global[realmName][playerName] = money
end
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:RegisterEvent("PLAYER_MONEY")
frame:SetScript("OnEvent", function(self, event, ...)
if event == "ADDON_LOADED" and select(1, ...) == ADDON_NAME then
OnAddonLoaded()
elseif event == "PLAYER_MONEY" then
OnPlayerMoney()
end
end)For an example of a complex addon using Ace3 libraries (AceAddon, AceDB, AceConfig), see 09a_Ace3_Library_Guide.md.
The following shows a complex addon using only base WoW API:
Purpose: Full-featured raid frame addon
RaidFrames/
RaidFrames.toc
# Core
Core.lua
Defaults.lua
# Localization
Locales/
enUS.lua
deDE.lua
# Modules
Modules/
UnitFrames.lua
RaidFrames.lua
PartyFrames.lua
# UI
UI/
Templates.xml
Frames.lua
Frames.xml
# Config
Config/
Options.lua
RaidFrames.toc:
## Interface: 120005
## Title: Raid Frames
## Author: YourName
## Version: 2.0.0
## Notes: Advanced raid frame addon
## SavedVariables: RaidFramesDB
# Core
Defaults.lua
Core.lua
# Localization
Locales\enUS.lua
Locales\deDE.lua
# Modules
Modules\UnitFrames.lua
Modules\RaidFrames.lua
Modules\PartyFrames.lua
# UI
UI\Templates.xml
UI\Frames.lua
UI\Frames.xml
# Config
Config\Options.lua
Core.lua:
local ADDON_NAME, ns = ...
-- Event frame
local frame = CreateFrame("Frame")
frame:RegisterEvent("ADDON_LOADED")
frame:RegisterEvent("PLAYER_ENTERING_WORLD")
frame:RegisterEvent("GROUP_ROSTER_UPDATE")
frame:SetScript("OnEvent", function(self, event, ...)
if event == "ADDON_LOADED" and ... == ADDON_NAME then
-- Initialize saved variables with defaults
RaidFramesDB = RaidFramesDB or {}
for k, v in pairs(ns.defaults) do
if RaidFramesDB[k] == nil then
RaidFramesDB[k] = v
end
end
ns.db = RaidFramesDB
-- Register options panel
ns:RegisterOptions()
self:UnregisterEvent("ADDON_LOADED")
elseif event == "PLAYER_ENTERING_WORLD" then
ns:UpdateFrames()
elseif event == "GROUP_ROSTER_UPDATE" then
ns:UpdateRoster()
end
end)
function ns:RegisterOptions()
local category = Settings.RegisterCanvasLayoutCategory(
ns.optionsFrame, ADDON_NAME
)
Settings.RegisterAddOnCategory(category)
endPurpose: Support multiple WoW versions
Use this when: Your addon code is the same across all versions.
UniversalAddon/
UniversalAddon.toc
Core.lua
Utils.lua
UniversalAddon.toc:
## Interface: 120000, 110207, 50503, 40402, 11508
## Title: Universal Addon
## Author: YourName
## Version: 1.0.0
## Notes: Works on Retail, Cata Classic, and Classic Era
Core.lua
Utils.lua
Core.lua:
local isMainline = (WOW_PROJECT_ID == WOW_PROJECT_MAINLINE)
local isClassic = (WOW_PROJECT_ID == WOW_PROJECT_CLASSIC)
UniversalAddon = {
version = "1.0.0",
isMainline = isMainline,
isClassic = isClassic
}
-- Shared functionality with version detection for API differences
function UniversalAddon:Initialize()
print("UniversalAddon loaded for " .. (isMainline and "Mainline" or "Classic"))
-- Handle API differences in code
if isMainline then
-- Use C_ActionBar namespace (12.0.0+)
self.GetActionTexture = C_ActionBar and C_ActionBar.GetActionTexture or GetActionTexture
else
-- Use legacy globals on Classic
self.GetActionTexture = GetActionTexture
end
endUse this when: You need to load different files for different game versions.
MultiVersion/
MultiVersion_Mainline.toc # Retail
MultiVersion_Cata.toc # Cata Classic
MultiVersion_Vanilla.toc # Classic Era
# Shared core
Core.lua
# Version-specific files
Mainline\
Features.lua
Classic\
Features.lua
MultiVersion_Mainline.toc:
## Interface: 120005
## Title: MultiVersion
## Author: YourName
## Version: 1.0.0
Core.lua
Mainline\Features.lua
MultiVersion_Vanilla.toc:
## Interface: 11508
## Title: MultiVersion
## Author: YourName
## Version: 1.0.0
Core.lua
Classic\Features.lua
When Multiple TOCs Are Necessary:
- Loading different Lua/XML files per version
- Using version-specific libraries
- Significant code path differences that can't be handled with runtime detection
- Always specify
## Interfacematching your target version - Use descriptive
## Titleand## Notes - List files in logical load order
- Comment your TOC file for clarity
- Embed libraries when possible (reduces user hassle)
- Use
OptionalDepsfor soft dependencies - Avoid circular dependencies
- Document why dependencies exist
- Group related files in folders
- Load Lua before XML
- Load core before modules
- Load data before code that uses it
- Use proper initialization events (ADDON_LOADED, PLAYER_LOGIN)
- Don't do heavy work at load time
- Initialize saved variables safely
- Handle missing/corrupt saved variables
- Keep modules independent when possible
- Provide clear module APIs
- Use registration systems for discoverability
- Document module dependencies
- Always provide enUS as default
- Load locale files after core
- Use locale keys, not hardcoded strings
- Test with different locales
- Use LoadOnDemand for optional features
- Lazy-load heavy modules
- Cache frequently-used data
- Unregister events when not needed
- FrameXML Source:
Interface\FrameXML - Blizzard Addons:
Interface\AddOns\Blizzard_* - API Documentation: https://wowpedia.fandom.com/
- WoW Interface: https://www.wowinterface.com/
- CurseForge: https://www.curseforge.com/wow/addons
- Wago: https://addons.wago.io/