Skip to content

WoW Addon Development Guide

The complete reference for building World of Warcraft addons for Patch 12.0+ (Midnight)

Interface version: 120001 · Lua 5.1 · Updated for Midnight launch

🚀 Quick Start

Your first addon in 60 seconds

Every addon needs just two files in your Interface/AddOns/ folder:

MyAddon/
├── MyAddon.toc
└── MyAddon.lua

MyAddon.toc — tells WoW about your addon:

## Interface: 120001
## Title: My Addon
## Notes: My first addon for Midnight!
MyAddon.lua

MyAddon.lua — your addon code:

local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_LOGIN")
frame:SetScript("OnEvent", function(self, event)
    print("|cff00ff00MyAddon|r loaded! Welcome to Midnight.")
end)

Type /reload in-game to load your addon. That's it!

📚 Documentation

  • TOC Format

    Define your addon's metadata, dependencies, saved variables, and load conditions using the .toc file format.

    TOC Reference

  • Lua API

    Core functions, C_ namespaces, and the Lua 5.1 environment available to addons — over 260 API namespaces.

    API Reference

  • Events

    Event-driven architecture — register, handle, and respond to game events like PLAYER_LOGIN and UNIT_AURA.

    Events Guide

  • Frames & Widgets

    Build UI with Frame, Button, Texture, FontString, and other widget types. XML and Lua creation patterns.

    Widget Guide

  • Security

    Protected functions, secure templates, taint system, and combat lockdown — what you can and can't do.

    Security Guide

  • Midnight Changes

    What's new in 12.0 — Secret Values, CLEU removal, the secure UI model, and how to migrate your addons.

    Midnight Guide

💡 Key Facts

Things every addon developer should know

Fact Detail
Language WoW uses Lua 5.1 — not 5.2+. No goto, no bitwise operators, no _ENV.
Official docs Blizzard does not publish addon API docs. The in-game /api command is the only official source. warcraft.wiki.gg is the community authority.
Midnight's secure model Patch 12.0 introduced Secret Values — opaque black boxes that replace raw combat numbers. COMBAT_LOG_EVENT_UNFILTERED no longer fires for addons.
API scope 260+ C_ namespace APIs available (C_Item, C_Spell, C_Timer, etc.) plus hundreds of global functions.
Interface number 120001 for Patch 12.0.1 (Midnight launch). Set this in your .toc file.
Blizzard UI source Blizzard's own UI code is mirrored at Gethe/wow-ui-source — the best way to learn real patterns.

🎓 Learn from the Best

These widely-used addons have open-source codebases — study them to learn real-world patterns:

  • Deadly Boss Mods (DBM)

    The most downloaded addon in WoW history. Boss encounter alerts and timers.

    595M downloads · Source

  • Details! Damage Meter

    Combat analysis and damage/healing meters. Complex data visualization patterns.

    330M downloads · Source

  • WeakAuras 2

    The ultimate custom UI framework. Deep use of the event system and secure templates.

    1.4k stars · Source

  • BigWigs Bossmods

    Alternative boss mod framework. Clean architecture and plugin-based design.

    183M downloads · Source

  • Plater Nameplates

    Nameplate customization. Great examples of frame manipulation and visual scripting.

    90M downloads · Source

🔗 Essential Resources

Resource URL Description
WoW API Reference warcraft.wiki.gg/wiki/World_of_Warcraft_API The primary community API reference
Events List warcraft.wiki.gg/wiki/Events Complete categorized events reference
API Changes (12.0) warcraft.wiki.gg/wiki/Patch_12.0.0/API_changes What changed in Midnight
Blizzard UI Source github.com/Gethe/wow-ui-source Official UI code mirror
VS Code Extension WoW API IntelliSense Autocomplete for WoW API
WoWUIDev Discord discord.gg/txUg39Vhc6 Addon developer community chat

Development Setup

Install these VS Code extensions for the best experience:

Debugging

Install these addons for in-game error reporting: