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.
- ✅ 00_MASTER_GUIDE.md - Master overview and entry point
- ✅ 01_API_Reference.md - WoW API functions organized by category
- ✅ 02_Event_System.md - Complete event system documentation
- ✅ 03_UI_Framework.md - XML, frames, widgets, templates, mixins, nameplates
- ✅ 04_Addon_Structure.md - TOC files, file organization, load order
- ✅ 05_Patterns_And_Best_Practices.md - Coding patterns, performance, best practices
- ✅ 06_Data_Persistence.md - Saved variables, database management
- ✅ 07_Blizzard_UI_Examples.md - Real working code examples
- ✅ 08_Community_Addon_Patterns.md - Ace3, LibStub, community frameworks
- ✅ 09_Addon_Libraries_Guide.md - Library reference (LibStub, LibDataBroker, LibSharedMedia, etc.)
- ✅ 09a_Ace3_Library_Guide.md - Comprehensive Ace3 framework reference (all 14+ libraries, full examples)
- ✅ 10_Advanced_Techniques.md - Production-level patterns (cross-client, performance, multi-addon)
- ✅ 11_Housing_System_Guide.md - Housing system APIs and development patterns
- ✅ 12_API_Migration_Guide.md - API version migration, compatibility wrappers, update strategies
- ✅ 12a_Secret_Safe_APIs.md - Complete 12.0+ secret values API reference
- ✅ 13_Cooldown_Viewer_Guide.md - Cooldown Viewer system: C_CooldownViewer API, alerts, layout, CooldownFrame widget
- 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
- 3,417 Blizzard UI source files analyzed
- 20,000+ community addon files referenced
- Real-world patterns extracted from official Blizzard code
This knowledge base ships with optional Claude Code integration (custom agent + slash command) for AI-assisted addon development:
- +How To Use This Guide with Claude Code+.md — setup walkthrough
- Claude AI Commands (optional)/README.md — agent/command file reference and install helpers
- Read 00_MASTER_GUIDE.md (overview + 5-minute tutorial)
- Follow the "Your First Addon" tutorial in that guide
- Start coding!
- Check 00_MASTER_GUIDE.md for structure
- Jump to specific guides based on what you're building
- Reference 07_Blizzard_UI_Examples.md for code patterns
- Use 05_Patterns_And_Best_Practices.md for optimization
| 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 |
| 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 |
| 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 |
| 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 |
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
UI Framework & Layout:
- XML structure: 03_UI_Framework.md
- Templates: 03_UI_Framework.md
- Mixins: 05_Patterns_And_Best_Practices.md
- ScrollBoxes: 03_UI_Framework.md + 07_Blizzard_UI_Examples.md
- Layout frames: 03_UI_Framework.md
Data Management:
- Saved variables: 06_Data_Persistence.md
- Profiles: 08_Community_Addon_Patterns.md
- Database patterns: 06_Data_Persistence.md
- Migrations: 06_Data_Persistence.md
Code Patterns:
- Mixins: 05_Patterns_And_Best_Practices.md
- Events: 02_Event_System.md + 05_Patterns_And_Best_Practices.md
- State management: 05_Patterns_And_Best_Practices.md
- Performance: 05_Patterns_And_Best_Practices.md
API Usage:
- API categories: 01_API_Reference.md
- API wrappers: 05_Patterns_And_Best_Practices.md
- C_* namespaces: 01_API_Reference.md
Community Patterns:
- Ace3: 08_Community_Addon_Patterns.md
- LibStub: 08_Community_Addon_Patterns.md
- Localization: 08_Community_Addon_Patterns.md
- Slash commands: 08_Community_Addon_Patterns.md
Looking at Blizzard source code?
- Most important addon:
Blizzard_SharedXML(core templates and utilities) - Action buttons:
Blizzard_ActionBar(see 07_Blizzard_UI_Examples.md) - Buffs/debuffs:
Blizzard_BuffFrame(see 07_Blizzard_UI_Examples.md)
Looking for API functions?
- Complete API reference: 01_API_Reference.md
Looking for events?
- Complete event reference: 02_Event_System.md
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
- ✅ Start small - Begin with a simple addon
- ✅ Study examples - Read Blizzard's code in 07_Blizzard_UI_Examples.md
- ✅ Use patterns - Follow patterns in 05_Patterns_And_Best_Practices.md
- ✅ Save properly - Read 06_Data_Persistence.md before saving data
- ✅ Test frequently - Use
/reloadoften during development
- ❌ Don't pollute global namespace
- ❌ Don't use OnUpdate for everything (use events/timers)
- ❌ Don't forget to validate saved variables
- ❌ Don't create frames every time (use pools)
- ❌ Don't hardcode strings (use localization)
-- Enable errors
/console scriptErrors 1
-- Print to chat
print("Debug:", value)
-- Dump table
/dump MyTable
-- Show frames
/fstack
-- Trace events
/eventtrace/reload- Reload UI/fstack- Show frame stack/eventtrace- Monitor events/dump- Print variables/console scriptErrors 1- Show Lua errors
- BugSack - Error capture
- DevTool - Variable inspector
- Blizzard_DebugTools - Built-in debug tools
https://github.com/Gethe/wow-ui-source
...\World of Warcraft\_retail_\Interface\AddOns\
WTF\Account\[Account]\SavedVariables\
WTF\Account\[Account]\[Server]\[Character]\SavedVariables\
- Read 00_MASTER_GUIDE.md and do the 5-minute tutorial
- Read 04_Addon_Structure.md
- Read 12a_Secret_Safe_APIs.md — critical 12.0.0+ guards
- Experiment with slash commands
- Read 02_Event_System.md
- Read 03_UI_Framework.md
- Create a simple frame
- Handle PLAYER_LOGIN event
- Read 07_Blizzard_UI_Examples.md
- Read 06_Data_Persistence.md
- Implement saved variables
- Read 05_Patterns_And_Best_Practices.md
- Refactor code using mixins
- Optimize performance
- Read 08_Community_Addon_Patterns.md
- Read 09_Addon_Libraries_Guide.md and 09a_Ace3_Library_Guide.md
- Try Ace3 framework
- Create scrolling lists
- Implement profiles
- Study Blizzard source code
- Read 10_Advanced_Techniques.md
- Read 12_API_Migration_Guide.md
- Add performance profiling
- Optimize with event bucketing
- Build multi-addon architecture
- Learn to migrate addons for new patches
- (Optional) Implement cross-client compatibility
- 01_API_Reference.md — API lookup
- 11_Housing_System_Guide.md — player housing
- 13_Cooldown_Viewer_Guide.md — Cooldown Manager integration
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
"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_ActionBarnamespace - Combat log APIs moved to
C_CombatLognamespace - Many global functions removed (use C_* equivalents)
New Systems:
- Official damage meter and encounter timeline (
C_DamageMeter) - Housing system (
C_Housing) - see 11_Housing_System_Guide.md
New TOC Directives:
## Category:- Addon category for organization## Group:- Group related addons together## LoadSavedVariablesFirst:- Ensure saved variables load before code
Secret-Safe Rendering:
- New numeric formatter types:
AbbreviatedNumberFormatter,NumericRuleFormatter,SecondsFormatter— accept secret numbers natively viaFormaton duration objects - New
Cooldown:SetCountdownFormatter(formatter)andCooldown:SetCountdownMillisecondsThreshold(seconds)— reduces the need forpcall(string.format)workarounds
Nameplates:
- Per-plate hit-rect override API:
CanChangeHitTestPoints,SetHitTestPoints,SetAllHitTestPoints,ClearAllHitTestPoints,GetHitTestPoints— replaces the globalC_NamePlate.SetNamePlateSizetrick for per-plate sizing
Auras:
isHelpful,isHarmful,isRaid,isNameplateOnly,isFromPlayerOrPlayerPetare no longer secret — addons can classify auras via Lua during combatauraInstanceIDvalues re-randomize at encounter / M+ / PvP boundaries
Unit Identity Restrictions:
UnitName,UnitSpellTargetName,UnitTokenFromGUID,UnitIsUnitstricter 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 forSecureActionButtonTemplate GetRaidRosterInforeturns"Unknown"instead ofnilfor uncached namesUNIT_CONNECTIONevent reliability fixedIsInInstancenow correctly returnstrueinside delves- Throttles relaxed during
PLAYER_LOGOUT/ADDONS_UNLOADING - New
Predicatestable in generated API docs describes per-API secret/taint restrictions
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:
livefor retail,ptr/ptr2/betafor 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.
-
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_5detection 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 (SetHitTestPointsfamily replacing the globalC_NamePlate.SetNamePlateSizetrick), aura classification fields becoming non-secret (isHelpful,isHarmful,isRaid,isNameplateOnly,isFromPlayerOrPlayerPet), stricter unit-identity rules onUnitName/UnitSpellTargetName/UnitTokenFromGUID/UnitIsUnit,table.freeze/table.isfrozenread-only tables, the new"outfit"SecureActionButtonTemplateaction type, and reliability fixes (UNIT_CONNECTION,IsInInstanceinside 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_changesand 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/GetCurrentPagedon't exist;C_RestrictedActionsnamespace fabrications (IsActionRestricted, GetRestrictionReason, CanPerformAction, IsSecureContext, IsInCombatLockdown, IsRestricted, IsCombatRestricted);string.concat;child.Cooldown:GetDurationObject();child:SetAlphaFromCurve();GetActionCount/ActionHasRangerenamed (not same-name) toGetActionUseCount/HasRangeRequirements - Corrected
scrubsecretvaluesas varargs-in/varargs-out, globalGetSpellCooldownremoved in 11.0.0,UnitHealth/UnitHealthMax%dformat crashes in combat,C_RestrictedActions.IsAddOnRestrictionActive()requires thetypeargument,CooldownFrame_Set/CooldownFrame_SetDisplayAsPercentageinheritSetCooldownrestrictions - Documentation accuracy fixes: Blizzard mixins use PascalCase universally (verified 123 PascalCase + 0 lowercase in
ActionButton.lua);_Intrinsicis a method suffix not mixin suffix;tinsert/tremove/wipeare WoW global aliases;C_EventUtils.IsEventValidpromoted as primary version-safe registration;SavedVariablesMachinestorage path corrected toWTF/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 touchEmbeddedItemTooltip); 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.mdin Week 1 and09a_Ace3_Library_Guide.mdin Week 4; end-to-end QUICK_START_GUIDE audit
- Executed a 40-item audit against
-
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()),SetAlphaFromBooleanfor secret boolean→alpha mapping,MENU_COOLDOWN_SETTINGS_ITEMcontext menu hook,CooldownViewerSettings:ShowUIPanel(false), EventRegistry argument column,C_AssistedCombatintegration for rotation highlighting,C_CurveUtil-based dimming, charge-detection gap documentation, and nuanced child-hook taint warning (CDM hooks child methods successfully viahooksecurefuncwith TaintLess)
- Updated 13_Cooldown_Viewer_Guide.md with 10 additions from CooldownManagerCentered analysis: viewer frame accessible properties (
-
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)andSetMinMaxValues()accept secrets at C++ level; array index fromcombatSourcespreserves sort order (index 1 = highest); afterPLAYER_REGEN_ENABLED+ delay all values become non-secret and fully readable isLocalPlayerandclassFilenamealways 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 orEnableMouse(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 duringQUEST_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 — useC_TaskQuest.GetQuestZoneID()for canonical zonehooksecurefuncon 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
- Documented map canvas taint propagation (12.0.0+): addon frames on
-
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, andUNIT_AURAeventaddedAuraspayload - 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/isFromPlayerOrPlayerPetclassification fields became non-secret in 12.0.5 — see v3.3
- Documented that ALL aura data fields are SECRET during combat except
-
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()triggersADDON_ACTION_BLOCKED(it callsCommit()→SaveBindings(), a protected function)- Common need for addons redirecting from the Blizzard Interface Options to standalone AceConfig-style dialogs
- Documented the correct way to programmatically close the Blizzard Settings panel from addon code:
-
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
HitTestFramechild of the nameplate's UnitFrame UnitFrame:Hide()also hides the HitTestFrame child, breaking click targeting — useSetAlpha(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
- Documented 12.0.0's nameplate click-targeting change: click detection moved from Lua-level frame handling to C++ level via a
-
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.sourceGUIDall secret; onlyclassFilename,isLocalPlayer,specIconIDaccessible 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
- Discovered through Recount testing that C_DamageMeter API data is "secret value"-protected:
-
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")throwsADDON_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_DamageMeterwith 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_Housingplayer 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);
UnitAurafinally removed in favor ofC_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_DamageMeterofficial damage meter,C_EncounterTimeline/C_EncounterWarningsboss timeline system,C_Housingplayer housing,C_EncodingUtilnative compression/serialization - Cleanup: removed obsolete
api_extracted/(513 raw 11.x API files),events_extracted/(1,645 events from 11.2.7), andfile_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