wow-addon-structure
WoW AddOn Structure (Retail)
Scope
- Retail only, current as of Patch 12.0.0.
- Focuses on folder layout, .toc metadata, loading order, and SavedVariables.
- Avoid deprecated or removed APIs and call out restricted directives.
When to use this skill
Use this skill when you need to:
- Design or review an AddOn folder layout.
- Author or audit a .toc file.
- Reason about file load order and login events.
- Wire SavedVariables or troubleshoot persistence.
- Query or load AddOns via
C_AddOnsAPIs.
How to use this skill
- Start with layout and naming rules in references/ADDON_STRUCTURE.md.
- Build the .toc file using references/TOC_FORMAT.md.
- Plan initialization order with references/LOADING_LIFECYCLE.md.
- Wire persistence with references/SAVED_VARIABLES.md.
- Use
C_AddOnsmetadata APIs from references/C_ADDONS_API.md. - Cross-check patterns in Blizzard UI source from references/VIEWING_BLIZZARD_UI.md.
Reference files
- references/ADDON_STRUCTURE.md - Folder layout rules, naming, and common patterns.
- references/TOC_FORMAT.md - .toc syntax, directives, and file order rules.
- references/LOADING_LIFECYCLE.md - Load order, events, and login timeline.
- references/SAVED_VARIABLES.md - Persistence rules and file locations.
- references/C_ADDONS_API.md - Key
C_AddOnsmetadata and load APIs. - references/VIEWING_BLIZZARD_UI.md - How to inspect Blizzard UI source.
Key rules and reminders
- The AddOn folder name and .toc filename must match.
- The .toc file is required and defines file load order.
- Files load top to bottom in the .toc list.
- SavedVariables are available after
ADDON_LOADEDunlessLoadSavedVariablesFirstis used. - Use
LoadOnDemandandC_AddOns.LoadAddOnfor heavy modules. - Some .toc directives are restricted to Blizzard AddOns and are not available to third-party AddOns.
Sources
- https://warcraft.wiki.gg/wiki/TOC_format
- https://warcraft.wiki.gg/wiki/AddOn
- https://warcraft.wiki.gg/wiki/AddOn_loading_process
- https://warcraft.wiki.gg/wiki/SavedVariables
- https://warcraft.wiki.gg/wiki/Viewing_Blizzard%27s_interface_code
- https://warcraft.wiki.gg/wiki/World_of_Warcraft_API
- https://github.com/Gethe/wow-ui-source/tree/live/Interface/AddOns/Blizzard_APIDocumentationGenerated
More from jburlison/wowaddonapiagents
wow-lua-api
Verbose guide to Lua 5.1 functions available in WoW, including Blizzard-specific differences and WoW-only additions. Use for core Lua behavior in the WoW addon environment.
33wow-api-currency-economy
Complete reference for WoW Retail Currency, Auction House, Token, Store, Trading Post, Black Market, Mail, and Player Trading APIs. Covers C_CurrencyInfo (currency data, tracking, backpack), Auction House (full listing/bidding/buying/selling/search/commodity), C_WowTokenPublic (WoW Token market), AccountStore (in-game shop), CatalogShop, C_PerksProgram (Trading Post — Trader's Tender), BlackMarket (BMAH), TradeInfo (player trading), MailInfo (mailbox), and related events. Use when working with currencies, auction house UI, WoW Tokens, the in-game store, Trading Post, black market, mail, or player-to-player trading.
15wow-api-map-navigation
Complete reference for WoW Retail Map, Navigation, Area POI, Taxi, Vignette, Minimap, Nameplate, Waypoint, Zone Ability, Fog of War, and Exploration APIs. Covers C_Map (50+ functions for map data, coordinates, map IDs, area info), C_MapExplorationInfo, C_AreaPoiInfo, C_TaxiMap (flight paths), C_Vignette, C_SuperTrackManager, C_Navigation (in-game navigation), C_ZoneAbility, C_FogOfWar, Minimap functions, C_NamePlateManager, and coordinate conversion. Use when working with maps, coordinates, waypoints, flight paths, minimap, nameplates, vignettes, exploration, zone abilities, or in-game navigation.
11wow-api-encounters
Complete reference for WoW Retail Encounter Journal, Mythic+/Challenge Mode, Instance, Scenario, Raid Lock, and Season APIs. Covers EncounterJournal (dungeon/raid boss database, loot tables, section navigation), C_ChallengeMode (M+ keystones, affixes, timers, best times), C_MythicPlus (weekly runs, seasonal data, rating), ScenarioInfo (delves/scenarios objectives and stages), InstanceLeaverInfo (deserter), RaidLocks (saved instances), C_SeasonInfo (seasonal info), and related events. Use when working with dungeon/raid encounter data, M+ keystones, mythic plus scores, scenario stages, raid lockouts, or seasonal content.
11wow-api-reputation
Complete reference for WoW Retail Reputation, Faction, Major Factions, Paragon, and Neighborhood Initiative APIs. Covers C_Reputation (faction info, standings, watched faction, headers, friendship reps, paragon), C_MajorFactions (Dragonflight+ renown factions, renown levels, rewards), C_NeighborhoodInitiative (12.0.0 housing neighborhood reputation), faction expansion data, and reputation-related events. Use when working with reputation tracking, faction standings, renown systems, paragon rewards, friendship reputations, or neighborhood initiatives.
11wow-api-combat
Complete reference for WoW Retail Combat, Damage Meter, Threat, Loss of Control, Combat Text, Combat Audio Alert, Secret Values, and Spectator APIs. Covers the 12.0.0 combat log removal (CLEU no longer available to addons), C_DamageMeter built-in damage meter, C_Secrets secret predicates, C_CurveUtil/C_DurationUtil for secret value visualization, C_LossOfControl, C_CombatText, C_CombatAudioAlert, ENCOUNTER_STATE_CHANGED, threat functions, and the new COMBAT_LOG_MESSAGE event. Use when working with combat data, damage meters, threat, loss of control, combat text, encounter events, or any combat-related addon functionality.
10