Skip to content
This repository was archived by the owner on Jun 25, 2026. It is now read-only.

Latest commit

 

History

History
511 lines (393 loc) · 34.7 KB

README.md

File metadata and controls

511 lines (393 loc) · 34.7 KB

World of Warcraft Addon Development
Complete Knowledge Base

📚 Overview

This comprehensive knowledge base contains everything you need to create, debug, analyze, and maintain World of Warcraft addons. Originally created by analyzing the complete WoW 11.2.7 (The War Within) UI source code, now updated through 12.0.5 (Midnight) with documentation of the major API changes including the "Addon Apocalypse" Secret Values system, and the 12.0.5 refinements (numeric formatters, per-plate hit rect API, aura classification fields becoming non-secret, table.freeze, "outfit" secure action type).

Please note that this knowledge base was generated by Claude AI. Even with significant human oversight, guidance and quality control there may still be occasional mistakes. If you find a mistake, please feel free to open an issue or submit a pull request.

✨ What's Included

Complete Documentation (16 Guides + Quick Start)

Reference Data

  • API Documentation - 500+ API functions documented in 01_API_Reference.md
  • Event Lists - Complete event reference in 02_Event_System.md
  • 281 Blizzard addons analyzed for patterns and examples

Source Code Analysis

  • 3,417 Blizzard UI source files analyzed
  • 20,000+ community addon files referenced
  • Real-world patterns extracted from official Blizzard code

🤖 Using with Claude Code

This knowledge base ships with optional Claude Code integration (custom agent + slash command) for AI-assisted addon development:

🚀 Quick Start

For Complete Beginners

  1. Read 00_MASTER_GUIDE.md (overview + 5-minute tutorial)
  2. Follow the "Your First Addon" tutorial in that guide
  3. Start coding!

For Experienced Developers

  1. Check 00_MASTER_GUIDE.md for structure
  2. Jump to specific guides based on what you're building
  3. Reference 07_Blizzard_UI_Examples.md for code patterns
  4. Use 05_Patterns_And_Best_Practices.md for optimization

📖 Documentation Structure

Core Concepts (Read First)

File Topics When to Read
00_MASTER_GUIDE.md Overview, 5-minute tutorial, TOC basics, key components, navigation hub Start here
04_Addon_Structure.md TOC files, load order, dependencies Creating new addons
02_Event_System.md Events, event handlers, registration Event-driven programming

UI Development

File Topics When to Read
03_UI_Framework.md XML, frames, templates, mixins, layouts, nameplates Building UI
07_Blizzard_UI_Examples.md Action buttons, scrolling, tooltips Need working examples

Code & Data

File Topics When to Read
05_Patterns_And_Best_Practices.md Mixins, events, performance, patterns Writing good code
06_Data_Persistence.md Saved variables, databases, profiles Saving settings
08_Community_Addon_Patterns.md Ace3, LibStub, localization, profiles Using frameworks
09_Addon_Libraries_Guide.md LibStub, LibDataBroker, LibSharedMedia, etc. Using non-Ace3 libraries
09a_Ace3_Library_Guide.md AceAddon, AceDB, AceConfig, AceGUI, all Ace3 Using Ace3 framework
10_Advanced_Techniques.md Cross-client, event bucketing, profiling, multi-addon Production-level addons
11_Housing_System_Guide.md Housing APIs, furniture, decoration Building housing addons
12_API_Migration_Guide.md Version upgrades, API changes, compatibility Updating for new patches
13_Cooldown_Viewer_Guide.md Cooldown Viewer API, alerts, CooldownFrame widget Building cooldown tracking addons

API Reference

File Topics When to Read
01_API_Reference.md C_* APIs, function categories Looking up API calls
02_Event_System.md Event lists and payloads Need event details

🎯 Common Use Cases

I want to...

Create my first addon → Read: 00_MASTER_GUIDE.md (Your First Addon — 5-minute tutorial) → 04_Addon_Structure.md

Build action buttons → Read: 03_UI_Framework.md → 07_Blizzard_UI_Examples.md (Action Buttons section)

Build nameplate addons → Read: 03_UI_Framework.md (Nameplates section — unit tokens, click targeting, per-plate hit-rect API)

Save addon settings → Read: 06_Data_Persistence.md → 08_Community_Addon_Patterns.md (Profile Systems)

Create a scrolling list → Read: 03_UI_Framework.md (ScrollBox) → 07_Blizzard_UI_Examples.md (Scroll Frames)

Handle events → Read: 02_Event_System.md → 05_Patterns_And_Best_Practices.md (Event-Driven)

Show tooltips → Read: 07_Blizzard_UI_Examples.md (Tooltips section)

Use mixins → Read: 05_Patterns_And_Best_Practices.md (Mixin Patterns) → 03_UI_Framework.md

Optimize performance → Read: 05_Patterns_And_Best_Practices.md (Performance section)

Use Ace3 framework → Read: 09a_Ace3_Library_Guide.md (complete Ace3 reference) → 08_Community_Addon_Patterns.md

Add minimap icon → Read: 09_Addon_Libraries_Guide.md (LibDBIcon section)

Use libraries (LibStub, LibDataBroker, etc.) → Read: 09_Addon_Libraries_Guide.md (comprehensive library guide)

Support multiple WoW versions (Classic, Retail, etc.) → Read: 10_Advanced_Techniques.md (Cross-Client Compatibility)

Optimize for production/large-scale addons → Read: 10_Advanced_Techniques.md (Performance, Event Bucketing, Multi-Addon)

Build housing addons → Read: 11_Housing_System_Guide.md (Housing APIs, furniture placement, decoration)

Update addon for new WoW patch/expansion → Read: 12_API_Migration_Guide.md (API changes, migration patterns, compatibility)

Track quests → Read: 07_Blizzard_UI_Examples.md (Quest Tracking) → 01_API_Reference.md

🔍 Finding Information

By Topic

UI Framework & Layout:

Data Management:

Code Patterns:

API Usage:

Community Patterns:

By File Type

Looking at Blizzard source code?

Looking for API functions?

Looking for events?

📁 Directory Structure

WoW_Addon_Dev_Knowledge_Base/
│
├── README.md (this file)
├── 00_MASTER_GUIDE.md
├── 01_API_Reference.md
├── 02_Event_System.md
├── 03_UI_Framework.md
├── 04_Addon_Structure.md
├── 05_Patterns_And_Best_Practices.md
├── 06_Data_Persistence.md
├── 07_Blizzard_UI_Examples.md
├── 08_Community_Addon_Patterns.md
├── 09_Addon_Libraries_Guide.md
├── 09a_Ace3_Library_Guide.md
├── 10_Advanced_Techniques.md
├── 11_Housing_System_Guide.md
├── 12_API_Migration_Guide.md
├── 12a_Secret_Safe_APIs.md
└── 13_Cooldown_Viewer_Guide.md

💡 Tips for Success

Best Practices

  1. ✅ Start small - Begin with a simple addon
  2. ✅ Study examples - Read Blizzard's code in 07_Blizzard_UI_Examples.md
  3. ✅ Use patterns - Follow patterns in 05_Patterns_And_Best_Practices.md
  4. ✅ Save properly - Read 06_Data_Persistence.md before saving data
  5. ✅ Test frequently - Use /reload often during development

Common Mistakes to Avoid

  1. ❌ Don't pollute global namespace
  2. ❌ Don't use OnUpdate for everything (use events/timers)
  3. ❌ Don't forget to validate saved variables
  4. ❌ Don't create frames every time (use pools)
  5. ❌ Don't hardcode strings (use localization)

Debugging

-- Enable errors
/console scriptErrors 1

-- Print to chat
print("Debug:", value)

-- Dump table
/dump MyTable

-- Show frames
/fstack

-- Trace events
/eventtrace

🛠️ Development Tools

In-Game

  • /reload - Reload UI
  • /fstack - Show frame stack
  • /eventtrace - Monitor events
  • /dump - Print variables
  • /console scriptErrors 1 - Show Lua errors

Addons

  • BugSack - Error capture
  • DevTool - Variable inspector
  • Blizzard_DebugTools - Built-in debug tools

📍 File Paths

WoW UI Source (for reference)

https://github.com/Gethe/wow-ui-source

Your Addons

...\World of Warcraft\_retail_\Interface\AddOns\

Saved Variables

WTF\Account\[Account]\SavedVariables\
WTF\Account\[Account]\[Server]\[Character]\SavedVariables\

🎓 Learning Path

Week 1: Basics

Week 2: UI & Events

Week 3: Data & Patterns

Week 4: Advanced

Week 5+: Production-Level

Reference & Specialized Topics

📚 Additional Resources

Official Blizzard Code

All examples in this knowledge base reference:

  • WoW Version: 12.0.5 (Midnight, current) — see 12_API_Migration_Guide.md for the full 12.0.0 → 12.0.5 delta
  • Interface Version: 120005
  • Files Analyzed: 3,417+ Blizzard UI files (12.0.0 and 12.0.5 snapshots)
  • Addons Documented: 281 official addons

Critical 12.0.x Changes

"Addon Apocalypse" - Secret Values System:

  • Combat-sensitive values (damage, healing, resources) are now "secret values"
  • Addons cannot directly read these values; must use Blizzard's official damage meter
  • Affects: damage meters, combat logs, healing trackers, threat meters
  • C_DamageMeter namespace provides official encounter data

Major API Migrations:

  • Action bar APIs moved to C_ActionBar namespace
  • Combat log APIs moved to C_CombatLog namespace
  • Many global functions removed (use C_* equivalents)

New Systems:

New TOC Directives:

  • ## Category: - Addon category for organization
  • ## Group: - Group related addons together
  • ## LoadSavedVariablesFirst: - Ensure saved variables load before code

12.0.5 Additions (Current Patch)

Secret-Safe Rendering:

  • New numeric formatter types: AbbreviatedNumberFormatter, NumericRuleFormatter, SecondsFormatter — accept secret numbers natively via Format on duration objects
  • New Cooldown:SetCountdownFormatter(formatter) and Cooldown:SetCountdownMillisecondsThreshold(seconds) — reduces the need for pcall(string.format) workarounds

Nameplates:

  • Per-plate hit-rect override API: CanChangeHitTestPoints, SetHitTestPoints, SetAllHitTestPoints, ClearAllHitTestPoints, GetHitTestPoints — replaces the global C_NamePlate.SetNamePlateSize trick for per-plate sizing

Auras:

  • isHelpful, isHarmful, isRaid, isNameplateOnly, isFromPlayerOrPlayerPet are no longer secret — addons can classify auras via Lua during combat
  • auraInstanceID values re-randomize at encounter / M+ / PvP boundaries

Unit Identity Restrictions:

  • UnitName, UnitSpellTargetName, UnitTokenFromGUID, UnitIsUnit stricter about secret unit tokens — see 12_API_Migration_Guide.md for comparison rules

Miscellaneous:

  • table.freeze(t) / table.isfrozen(t) — read-only tables
  • New "outfit" action type for SecureActionButtonTemplate
  • GetRaidRosterInfo returns "Unknown" instead of nil for uncached names
  • UNIT_CONNECTION event reliability fixed
  • IsInInstance now correctly returns true inside delves
  • Throttles relaxed during PLAYER_LOGOUT / ADDONS_UNLOADING
  • New Predicates table in generated API docs describes per-API secret/taint restrictions

External Links

Documentation & Reference:

  • warcraft.wiki.gg — current community wiki (active since the 2023 Fandom migration). Covers API, events, widget methods, and patch changes.
  • Gethe/wow-ui-source (GitHub) — community mirror of Blizzard's UI source code. Branches track each client: live for retail, ptr/ptr2/beta for unreleased builds.

Community:

  • WoWUIDev Discord — addon development community; home of WowAce and WowInterface contributors.
  • WoWInterface — addon hosting and long-standing author forums.

Addon Hosting:

  • CurseForge — largest addon distribution platform; useful for downloading popular addons to study real-world patterns.
  • Wago.io — addon/WeakAuras hosting.

Version History

  • v3.3 (2026-04-22)

    • WoW 12.0.5 (Midnight patch 2) migration coverage propagated across the entire KB (TOC bumped to 120005)
    • 12_API_Migration_Guide.md gained a "Patch 12.0.5 (TOC 120005)" subsection, version-number table update, isMid_12_0_1/isMid_12_0_5 detection helpers, six new migration quick-reference rows, and forward cross-links from 12.0.0 cooldown-arithmetic notes to the 12.0.5 formatters
    • Documented 12.0.5 additions: numeric formatters that accept secret numbers natively (AbbreviatedNumberFormatter, NumericRuleFormatter, SecondsFormatter), Cooldown:SetCountdownFormatter / SetCountdownMillisecondsThreshold, per-plate nameplate hit-rect override API (SetHitTestPoints family replacing the global C_NamePlate.SetNamePlateSize trick), aura classification fields becoming non-secret (isHelpful, isHarmful, isRaid, isNameplateOnly, isFromPlayerOrPlayerPet), stricter unit-identity rules on UnitName / UnitSpellTargetName / UnitTokenFromGUID / UnitIsUnit, table.freeze / table.isfrozen read-only tables, the new "outfit" SecureActionButtonTemplate action type, and reliability fixes (UNIT_CONNECTION, IsInInstance inside delves, GetRaidRosterInfo "Unknown" sentinel)
    • Added a dedicated Nameplates chapter to 03_UI_Framework.md covering unit tokens, plate lookup, click-targeting rules (12.0.0+), per-plate hit-rect API (12.0.5+), and nameplate-specific secret-value caveats
    • Verified against warcraft.wiki.gg/wiki/Patch_12.0.5/API_changes and the +wow-ui-source+ (12.0.5) tree (FrameAPINamePlateDocumentation, AbbreviatedNumberFormatterAPIDocumentation, NumericRuleFormatterAPIDocumentation, SecondsFormatterAPIDocumentation, FrameAPICooldownDocumentation, and others)
  • v3.2 (2026-04-05)

    • Executed a 40-item audit against Blizzard_APIDocumentationGenerated/*.lua, the wow-ui-source tree, warcraft.wiki.gg, and real-world addons (Broker_WorldQuests, ArkInventory, HandyNotes/HereBeDragons-Pins-2.0)
    • Removed ~9 fabricated APIs: GetActionInfo() migration never happened (global still live); C_ActionBar.PickupAction / PlaceAction / GetCurrentPage don't exist; C_RestrictedActions namespace fabrications (IsActionRestricted, GetRestrictionReason, CanPerformAction, IsSecureContext, IsInCombatLockdown, IsRestricted, IsCombatRestricted); string.concat; child.Cooldown:GetDurationObject(); child:SetAlphaFromCurve(); GetActionCount/ActionHasRange renamed (not same-name) to GetActionUseCount/HasRangeRequirements
    • Corrected scrubsecretvalues as varargs-in/varargs-out, global GetSpellCooldown removed in 11.0.0, UnitHealth/UnitHealthMax %d format crashes in combat, C_RestrictedActions.IsAddOnRestrictionActive() requires the type argument, CooldownFrame_Set / CooldownFrame_SetDisplayAsPercentage inherit SetCooldown restrictions
    • Documentation accuracy fixes: Blizzard mixins use PascalCase universally (verified 123 PascalCase + 0 lowercase in ActionButton.lua); _Intrinsic is a method suffix not mixin suffix; tinsert/tremove/wipe are WoW global aliases; C_EventUtils.IsEventValid promoted as primary version-safe registration; SavedVariablesMachine storage path corrected to WTF/SavedVariables/AddonName.lua; 12.0.1 marked as current live patch
    • Reground GameTooltip taint workaround scope (plain tooltips don't need ItemTooltip:Hide(), only helpers that touch EmbeddedItemTooltip); repositioned private tooltips as scanning-primary not a "definitive taint fix"; corrected map canvas taint rules (standard pin pattern is NOT inherently tainting; real taint is from quest-tracking API calls in click handlers)
    • README External Links refreshed (warcraft.wiki.gg replaces stale Fandom mirror; added Gethe/wow-ui-source, verified WoWUIDev Discord, CurseForge, Wago, WoWInterface); Learning Path surfaces 12a_Secret_Safe_APIs.md in Week 1 and 09a_Ace3_Library_Guide.md in Week 4; end-to-end QUICK_START_GUIDE audit
  • v3.1 (2026-04-03)

    • Updated 13_Cooldown_Viewer_Guide.md with 10 additions from CooldownManagerCentered analysis: viewer frame accessible properties (isHorizontal, iconDirection, iconLimit, iconScale, childXPadding, childYPadding, visibleSetting, settingMap, IsInitialized()), child frame properties (cooldownID, layoutIndex, wasSetFromAura, cooldownChargesShown, cooldownShowSwipe, CooldownFlash, GetCooldownInfo(), GetBaseSpellID()), SetAlphaFromBoolean for secret boolean→alpha mapping, MENU_COOLDOWN_SETTINGS_ITEM context menu hook, CooldownViewerSettings:ShowUIPanel(false), EventRegistry argument column, C_AssistedCombat integration for rotation highlighting, C_CurveUtil-based dimming, charge-detection gap documentation, and nuanced child-hook taint warning (CDM hooks child methods successfully via hooksecurefunc with TaintLess)
  • v3.0 (2026-04-03)

    • Created 09a_Ace3_Library_Guide.md — a dedicated 3,994-line Ace3 framework reference covering all 14+ libraries (AceAddon, AceDB, AceDBOptions, AceEvent, AceConsole, AceTimer, AceHook, AceConfig, AceConfigDialog, AceGUI, AceComm, AceSerializer, AceBucket, AceLocale) with full API docs, a complete GoldTracker example addon, troubleshooting, and an Ace3-vs-base API comparison table
    • Audited all guides for Ace3 contamination and replaced 30+ Ace3-specific APIs (OnInitialize, self:RegisterEvent, AceDB, AceConfig, etc.) that had been incorrectly presented as base WoW API — replaced with native equivalents or clear Ace3 labeling with cross-references; most-touched files were 04_Addon_Structure.md, 08_Community_Addon_Patterns.md, 10_Advanced_Techniques.md
    • Removed ~320 lines of detailed Ace3 content from 09_Addon_Libraries_Guide.md (now in 09a) and replaced with a brief overview + cross-reference
    • Converted ~140 backtick code-span guide references to clickable markdown hyperlinks across every KB file
    • Fixed two filename typos: 11_API_Migration_Guide.md → 12_API_Migration_Guide.md, 12_Housing_System_Guide.md → 11_Housing_System_Guide.md
  • v2.9 (2026-04-03)

    • Added 13_Cooldown_Viewer_Guide.md — comprehensive 18-section reference for the Cooldown Viewer (Cooldown Manager) system introduced in 12.0.0: C_CooldownViewer API, enums (CooldownViewerAlertType, CooldownViewerCategoryType, CooldownViewerLayoutType), mixin hierarchy (CooldownViewerMixin, CooldownViewerSpellMixin, etc.), spell ID resolution pipeline, cooldown/aura tracking internals, alert system (sound / visual glow / TTS), layout serialization, settings UI, CooldownFrame widget API, and addon integration patterns
  • v2.8 (2026-03-25)

    • Corrected the previous "C_DamageMeter is unusable by addons / third-party damage meters CANNOT function in 12.0.0+" framing — Recount's successful 12.0.1 update demonstrated viable workarounds
    • Documented four techniques in 12a_Secret_Safe_APIs.md: pcall(string.format, "%.0f", secret) extracts secret numbers as displayable text at C++ level; StatusBar:SetValue(secret) and SetMinMaxValues() accept secrets at C++ level; array index from combatSources preserves sort order (index 1 = highest); after PLAYER_REGEN_ENABLED + delay all values become non-secret and fully readable
    • isLocalPlayer and classFilename always accessible even during combat
    • Supersedes the v2.2 "CANNOT function" conclusion across 00_MASTER_GUIDE.md, 08_Community_Addon_Patterns.md, 12a_Secret_Safe_APIs.md (and the legacy QUICK_START_GUIDE, since merged into 00_MASTER_GUIDE)
  • v2.7 (2026-03-08)

    • Documented map canvas taint propagation (12.0.0+): addon frames on WorldMapFrame:GetCanvas() with global names or EnableMouse(true) propagate taint through C++ hit-testing, causing "secret number value" errors in Blizzard tooltip code — use nil names, disable mouse on overlay frames, prefer Blizzard's pin system
    • Clarified that secret values appear in ANY tainted execution context, not just during InCombatLockdown() — map canvas taint is a concrete example of this occurring outside combat
    • Documented quest reward data loading: HaveQuestData() only guarantees basic quest info; GetNumQuestLogRewards() transiently returns 0 during QUEST_LOG_UPDATE; cache known-good reward data to prevent display regression
    • C_TaskQuest.GetQuestsOnMap() returns quests from parent AND child sub-zone maps with child quest mapIDs remapped to parent — use C_TaskQuest.GetQuestZoneID() for canonical zone
    • hooksecurefunc on FlightMapFrame methods taints the pin pipeline (SetPassThroughButtons ADDON_ACTION_BLOCKED errors); writing ANY property to GameTooltip from addon code taints that property permanently for the session
  • v2.6 (2026-02-05)

    • Documented that ALL aura data fields are SECRET during combat except auraInstanceID (name, spellId, icon, duration, expirationTime, sourceUnit, dispelName, isHarmful, isHelpful, isFromPlayerOrPlayerPet, applications, timeMod, points) — applies to ALL combat contexts including open world, dungeons, raids, M+, PvP
    • Every aura query method affected: C_UnitAuras.GetUnitAuras, GetAuraDataByAuraInstanceID, GetUnitAuraBySpellID, GetAuraDataBySpellName, AuraUtil.FindAuraByName, and UNIT_AURA event addedAuras payload
    • Pre-combat caching does NOT work — new auras get new auraInstanceIDs with secret spellId values, and there is no non-secret window during combat
    • C_Spell.GetSpellInfo("SpellName") returns nil in 12.0.0 — only numeric spell IDs accepted
    • API-level filter strings still work (HELPFUL|PLAYER, INCLUDE_NAME_PLATE_ONLY|HARMFUL) because filtering is done at the C++ level
    • Note: The isHelpful / isHarmful / isRaid / isNameplateOnly / isFromPlayerOrPlayerPet classification fields became non-secret in 12.0.5 — see v3.3
  • v2.5 (2026-01-28)

    • Created 12a_Secret_Safe_APIs.md — a 1000+ line comprehensive reference for 12.0.0's secret values system, the biggest API change in WoW addon history
    • Documented core detection functions (issecretvalue, canaccessvalue, canaccessallvalues, hasanysecretvalues, canaccesssecrets, canaccesstable, issecrettable), manipulation functions (scrubsecretvalues, scrub, mapvalues, secretwrap, secretunwrap, dropsecretaccess), secure execution functions (securecallfunction, secureexecuterange, forceinsecure), table security system (SetTableSecurityOption, TableSecurityOption.*), and SecureTypes containers (CreateSecureMap, CreateSecureArray, CreateSecureStack, CreateSecureValue, CreateSecureNumber, CreateSecureBoolean, CreateSecureFunction)
    • Researched against Platynator addon, 50+ Blizzard UI source files using secret-safe patterns (RestrictedInfrastructure.lua, SecureTypes.lua, Pools.lua, Dump.lua, AuraUtil.lua, CallbackRegistry.lua), and the official FrameScriptDocumentation.lua
    • Includes check-before-use / defer-to-out-of-combat / native StatusBar / percentage-based custom bar patterns, CVar-based testing helpers, and migration checklists
  • v2.4 (2026-01-24)

    • Documented the correct way to programmatically close the Blizzard Settings panel from addon code: if SettingsPanel and SettingsPanel:IsShown() then HideUIPanel(SettingsPanel) end
    • Settings.CloseUI() does not exist; SettingsPanel:Close() triggers ADDON_ACTION_BLOCKED (it calls Commit() → SaveBindings(), a protected function)
    • Common need for addons redirecting from the Blizzard Interface Options to standalone AceConfig-style dialogs
  • v2.3 (2026-01-24)

    • Documented 12.0.0's nameplate click-targeting change: click detection moved from Lua-level frame handling to C++ level via a HitTestFrame child of the nameplate's UnitFrame
    • UnitFrame:Hide() also hides the HitTestFrame child, breaking click targeting — use SetAlpha(0) instead to keep clicks alive while making the Blizzard plate invisible
    • New C_NamePlateManager.SetNamePlateHitTestFrame(frame) exists but may be restricted to Blizzard code
    • Affects TidyPlates, NeatPlates, Plater, KuiNameplates, and any addon replacing or modifying nameplates — discovered during real-world NeatPlates 12.0.0 testing
  • v2.2 (2026-01-22)

    • Discovered through Recount testing that C_DamageMeter API data is "secret value"-protected: source.name, source.totalAmount, source.amountPerSecond, source.sourceGUID all secret; only classFilename, isLocalPlayer, specIconID accessible during combat
    • Original conclusion ("third-party damage meters CANNOT function in 12.0.0+ / there is NO workaround") was superseded by v2.8 — multiple workarounds proven viable
  • v2.1 (2026-01-22)

    • Corrected a critical error in 12_API_Migration_Guide.md: combat log events are COMPLETELY BLOCKED for third-party addons in 12.0.0
    • Frame:RegisterEvent("COMBAT_LOG_EVENT_UNFILTERED") throws ADDON_ACTION_FORBIDDEN — event registration itself is blocked, not just the API calls
    • Applies to all registration methods: frame:RegisterEvent(), EventRegistry:RegisterFrameEventAndCallback(), RegisterEventCallback() — pcall() does NOT prevent the error
    • Traditional damage meters (Recount, Skada, Details!) require complete architectural rewrites to use C_DamageMeter with secret-value workarounds
  • v2.0 (2026-01-20)

    • Major update for WoW 12.0.0 (Midnight) — the largest API overhaul in WoW history: 432+ new APIs, 140+ removed APIs, and the introduction of the Secret Values security system
    • Added 11_Housing_System_Guide.md (~1,766 lines) covering the complete C_Housing player housing system (287+ new functions)
    • Updated all 13 existing guides for 12.0.0 compatibility — new namespaces (C_ActionBar, C_CombatLog, C_EncodingUtil), Secret Values warnings, callback-based event registration, Lua extensions (table.create, table.count), new TOC directives (Category, Group, LoadSavedVariablesFirst, AllowAddOnTableAccess)
    • Documented breaking changes: global action bar and combat log functions REMOVED; Transmog APIs redesigned; Void Storage and Reagent Bank REMOVED (11.2.0); Socket APIs moved (11.2.5); UnitAura finally removed in favor of C_UnitAuras
    • 11_API_Migration_Guide.md expanded from ~630 to ~1,950 lines covering patches 11.0.2 through 12.0.1
    • New systems: C_DamageMeter official damage meter, C_EncounterTimeline / C_EncounterWarnings boss timeline system, C_Housing player housing, C_EncodingUtil native compression/serialization
    • Cleanup: removed obsolete api_extracted/ (513 raw 11.x API files), events_extracted/ (1,645 events from 11.2.7), and file_lists/ directories — all content now lives in the curated guide files
  • v1.1 (2025-10-19)

    • Added 12_API_Migration_Guide.md — comprehensive guide for addon version migration covering where to find API changes (warcraft.wiki.gg, WoW Forums, GitHub UI source, CurseForge/Wago), major API changes by expansion (The War Within, Dragonflight, Shadowlands), common migration patterns (single function → namespace, multi-return → table, compatibility wrappers, version-specific blocks, safe wrappers), version/client detection, automated migration checklists, real-world case studies (ArchyShadowlands 10.0 → 11.0), and a quick-reference table of API changes
    • Expanded the KB to 12 guides and integrated the migration guide into the README learning path and "I want to..." section
  • v1.0 (2025-10-19)

    • Initial release — 11 core guides (00-10), QUICK_START_GUIDE, README
    • Guides: 00_MASTER_GUIDE, 01_API_Reference, 02_Event_System, 03_UI_Framework, 04_Addon_Structure, 05_Patterns_And_Best_Practices, 06_Data_Persistence, 07_Blizzard_UI_Examples, 08_Community_Addon_Patterns, 09_Addon_Libraries_Guide, 10_Advanced_Techniques
    • Built from analysis of the WoW 11.2.7 (The War Within) UI source tree and community addon patterns