World of Warcraft Addon Development Complete Guide

Japanese Edition
https://daisuke.masuda.tokyo/article-2025-11-18-0805

This presentation is a comprehensive guide to World of Warcraft addon development, covering essential development practices. It demonstrates debugging techniques including conditional debug output with toggleable flags, stack trace capture for error tracking, and integration with tools like ViragDevTool. The guide emphasizes fast iteration development using the /reload command to test changes without restarting the game, while noting important considerations like SavedVariables and PLAYER_LOGOUT events. It also covers best practices for identifying global variable leaks by inspecting the _G table, helping developers maintain clean and efficient addon code.

Transcript

1. World of Warcraft World of Warcraft Addon Development Addon Development Complete Guide Complete Guide From Environment Setup to Debugging Lua 5.1 FrameXML API In-game tooling Created November 2025 Created November 2025
2. What is a WoW Addon? What is a WoW Addon? Popular examples WeakAuras DBM ElvUI Details! Plater ElvUI - The most popular UI customization addon Lua 5.1-based UI customization extensions • Uses Blizzard FrameXML API • Main uses: UI improvements, info display, combat assistance, QoL features •
3. Choose Your IDE: VS Code vs IntelliJ IDEA Choose Your IDE: VS Code vs IntelliJ IDEA Visual Studio Code wow-bundle WoW API for LuaLS Lightweight EmmyLua Annotations Supports type information and code completion via LuaLS (Lua Language Server) IntelliJ IDEA EmmyLua WoW API stubs Used by Total RP 3 developers EmmyLua Annotations Intuitive code completion and detailed API documentation display Both support EmmyLua annotations - choose what works for you! Lightweight & fast startup • Free & open-source • Rich extension ecosystem • Easy for beginners • Powerful refactoring tools • Advanced code navigation • Great for large projects • Professional IDE features •
4. VS Code Setup (Option 1) VS Code Setup (Option 1) Required Extensions Features WoW 8.0.1 API support Code snippets Syntax highlighting .toc file support // Quick Install (Ctrl+P) ext install Septh.wow-bundle ext install ketho.wow-api // Or search in Extensions panel // "wow-bundle" "WoW API" // Lua Language Server config (settings.json) { "Lua.workspace.library": [ "path/to/wow-api-library" ] } Tip: Enable Wow-bundle themes for optimized code display wow-bundle - WoW-aware Lua grammar, .toc colorization • WoW API for LuaLS - IntelliSense for WoW API • Fast & simple for small to medium addons •
5. IntelliJ IDEA Setup (Option 2) IntelliJ IDEA Setup (Option 2) Installation Steps 1 Open File > Settings > Plugins 2 Search for "EmmyLua" in the Marketplace tab 3 Select and install original EmmyLua (ID: 9768) 4 Restart the IDE Why Choose Original EmmyLua? Differences from EmmyLua2 Install EmmyLua plugin from JetBrains Marketplace • Original EmmyLua (Plugin ID: 9768) recommended • Fully compatible with Community Edition (free version) • Stability Over 6 years of development and mature codebase • WoW Compatible Proven implementation by Ellypse (Total RP 3 developer) • Lua 5.1 Full support for WoW Addon's foundation language • EmmyLua2 has a faster Rust-based engine but is still evolving • EmmyLua2 has limited proven integration with WoW API • Consider migrating to EmmyLua2 in the future •
6. IntelliJ: Create Lua SDK IntelliJ: Create Lua SDK 💡 Recommended SDK Names Lua 5.1 or WoW Lua SDK 💡 Important Tip No actual Lua runtime is required. The SDK configuration is just to help IntelliJ recognize Lua code - WoW provides the Lua environment. 💡 Assign SDK to Project In Project Structure's Project tab, select your SDK and click the Apply button to assign it to your project. Project Structure > Project > Project SDK From IntelliJ IDEA menu, select File 1 Click Project Structure File > Project Structure 2 Select SDKs in the left panel 3 Click the + button at the top and select Add Lua SDK from the dropdown 4 Select any folder (no actual Lua environment is needed) 5 In Project Structure's Project tab, select your created SDK and click Apply 6
7. Add WoW API Libraries Add WoW API Libraries Clone and add the following repositories to IntelliJ IDEA's Lua SDK: WoW API Definition Files Ellypse/IntelliJ-IDEA-Lua-IDE-WoW-API WoW API documentation and stub files for code completion WoW UI Source Code Ellypse/wow-ui-source or Gethe/wow-ui-source Blizzard's official UI source code and XML schema 1 API Function Auto-completion WoW function code completion, parameter hints, and documentation available 2 Widget Method Completion Type specification for Button also auto-completes inherited methods from Frame 3 XML Completion and Hints XML file editing support and error checking using UI.xsd 4 API Documentation Display Documentation popups when hovering over functions ⚠️ Important Tip After adding libraries, run File > Invalidate Caches / Restart to clear IntelliJ IDEA's cache and apply changes. 1 Clone repositories locally • 2 Project Structure > SDKs > Lua SDK • 3 Click + button in Classpath tab • 4 Select and add the cloned repositories •
8. Basic Addon Structure Basic Addon Structure Install Path _retail_/Interface/AddOns/MyAddon/ ├ MyAddon.toc ├ MyAddon.lua └ [other files] TOC File Key Fields Field Description ## Interface: 110002 WoW version number (required) ## Title: My Addon Addon title (required) ## Author: YourName Author name ## Version: 1.0 Version number ## SavedVariables: DB Variables to save (optional) Tip: Load Order Files are loaded in the order they are listed in the .toc file. If you have dependencies, make sure to list the required files first. Required files: • MyAddon.toc (manifest file) • MyAddon.lua (main code) • Optional files: • *.xml (UI layouts) • *.tga (textures) •
9. Hello World: Minimal Hello World: Minimal Working Example Working Example MyAddon.toc ## Interface: 110002 ## Title: My First Addon ## Author: YourName MyAddon.lua This code works when copied & pasted. Update the Interface number to match your current WoW patch. MyAddon.lua -- Create a frame and register for the PLAYER_LOGIN event local f = CreateFrame("Frame") f:RegisterEvent("PLAYER_LOGIN") f:SetScript("OnEvent", function(self, event) print("Hello WoW Addon World!") end) -- This is a minimal working addon -- This will print 'Hello WoW Addon World!' when you log in
10. In-Game Debug Tools In-Game Debug Tools Key /vdt Commands /vdt - Toggle UI /vdt help - Show help /vdt eventadd EVENT_NAME [unit] - Add event monitoring /vdt eventremove EVENT_NAME - Remove event monitoring Variable & table monitoring example: -- Monitor global variables if ViragDevTool_AddData then ViragDevTool_AddData(_G, "Globals") ViragDevTool_AddData(MyAddon, "MyAddon") end Debug function wrapper example: local DEBUG = true local function Debug(name, data) if DEBUG and ViragDevTool_AddData then ViragDevTool_AddData(data, name) end end -- Usage example Debug("PlayerFrame", PlayerFrame) Event monitoring example: -- Execute in chat /vdt eventadd UNIT_AURA player /vdt eventadd COMBAT_LOG_EVENT_UNFILTERED DevTool (ViragDevTool): Powerful debugger for addon developers • Visual inspection of tables/frames/variables (real-time) • Event monitoring and filtering • Function call logging with arguments and return values • Also available: DebugLog, DebugChatFrame •
11. In-Code Debugging In-Code Debugging Patterns Patterns Conditional Debug Function Usage Examples Stack Trace Capture Fast Iteration Development -- Conditional debug output (toggle ON/OFF as needed) local DEBUG = true local function Debug(...) if DEBUG then if ViragDevTool_AddData then ViragDevTool_AddData({...}, "MyAddon") else print("|cFF00FF00[MyAddon]|r", ...) end end end Define conditional debug functions at the top of your addon and simply set DEBUG = false before release to disable all debug messages. BEST PRACTICE Debug("Player name:", UnitName("player")) Debug("Status:", {health=100, mana=50}) -- Stack trace function function GetStackTrace() return debugstack(2) -- Skip current stack frame end -- Record detailed information when errors occur local success, err = pcall(function() -- Risky operation -- local n = nil + 1 -- Intentional error end) if not success then Debug("Error:", err) Debug("Stack trace:", GetStackTrace()) end Use chat command /reload or /rl to reload the entire UI • Test addon code changes without restarting the game • Be aware of PLAYER_LOGOUT event firing if you have SavedVariables • Inspect the _G table during debugging to identify unexpected global variable leaks: ViragDevTool_AddData(_G, "Global Variables") TIP
12. EmmyLua Annotations for EmmyLua Annotations for Better IntelliSense Better IntelliSense Type definitions & metadata for powerful code completion Class & Field Definition ---@class MyAddon ---@field db table database ---@field config table configuration table local MyAddon = {} Function Parameters and Return Values ---@param frame Button button widget ---@param text string display text ---@return boolean success function MyAddon:Setup(frame, text) frame:SetNormalTexture("Interface\\Buttons\\UI-Button") frame:SetText(text) return true end Widget Inheritance Completion Button ↓ Frame ↓ Region ↓ UIObject With annotations, all inherited methods appear in Button completion: Multiple IDE Support EmmyLua annotations work across major development environments: IntelliJ IDEA + EmmyLua VS Code + LuaLS Same annotation format provides code completion, documentation display, and type checking button:SetText() - Button-specific method • button:SetSize() - Inherited from Frame • button:SetAlpha() - Inherited from Region •
13. Summary & Next Steps Summary & Next Steps  Development Environment  Debug Tools  Learning Resources  Communities  Next Steps SavedVariables Events UI XML Widget Creation Library Usage Profiling Internationalization Security Option 1: VS Code + wow-bundle + WoW API for LuaLS • Option 2: IntelliJ IDEA + EmmyLua + WoW API stubs • Both environments support EmmyLua annotations • DevTool/ViragDevTool: Visual inspection of tables & variables • Conditional print: On/Off control with DEBUG variable • debugstack(): Get call stack when errors occur • /reload: Fast iteration with UI reload • warcraft.wiki.gg - WoW API official reference • Wowhead Lua Guide - Beginner tutorials • GitHub - Study existing addon code (ElvUI, WeakAuras, etc.) • r/wowaddons - Reddit developer community • WoWInterface Forums - Q&A and information exchange • CurseForge - Addon publishing platform •