A beginner's library for writing World of Warcraft addons on WoW Forever and Midnight.
Tutorials, references, notes from real addons, and a starter addon that runs on both clients.

---

Contents

• Who this is for
• Quick start
• Learning path
• What's inside
• Using with AI coding tools
• External sources
• Learning Lua
• Which source to trust
• Repository layout
• Tips for first timers
• Credits and licenses

Who this is for

You play WoW, you've used addons, and you want to make your own. You don't need to know Lua yet. Everything here targets the two modern clients:

Client	Interface	Notes
WoW Forever	16001	Classic-style content on a modern client (C_Spell, C_Item, Settings API, secret values). Not the same as Classic Era.
Midnight (retail)	120105 / 120107	Patch 12.x. Secret values and no combat log for addons.

Quick start

git clone https://github.com/Terynas/First-Timers.git
cd First-Timers
bash sync.sh        # downloads the external sources listed below (about 220 MB)

Then try the starter addon:

1. Copy 07-starter/HelloAzeroth/ into your client's Interface/AddOns/ folder.
2. Fully restart the game. /reload isn't enough after adding a new addon.
3. Type /hello in chat.

Run bash sync.sh again whenever you want the latest docs (bash sync.sh docs refreshes only the guide pages, which is quick).

Learning path

1. Lua (language). Addons are Lua 5.1. You can start HelloAzeroth with almost no Lua — when you want books and manuals, see Learning Lua and 06-notes/addon-dev/lua-learning-resources.md.
2. Your first addon. Read 01-guides/wiki/01-getting-started.md (Hello World in 15 minutes), then open 07-starter/HelloAzeroth/ and read its two files line by line.
3. The building blocks. Work through the numbered wiki tutorials in 01-guides/wiki/: TOC files, the loading process, events, saved settings, slash commands, localization, taint, XML.
4. What's different on modern clients. Read the Midnight 12.0.0 API changes and 06-notes/addon-dev/midnight-12.md. Forever inherits most of these changes.
5. Forever specifics. Read 06-notes/forever-rules.md, 06-notes/forever-quirks.md and the Forever 1.60.1 API changes, then the Forever developer series (downloaded into 01-guides/forever/ by sync.sh).
6. Going further. Topic notes in 06-notes/addon-dev/ cover secure templates and combat lockdown, debugging, Ace3, and packaging for CurseForge. Bigger examples are in 07-starter/more-examples/.
7. Building with AI. Start at AGENTS.md (works with Claude, Copilot, Cursor, and other agents), then set up agent memory (Hindsight + optional Obsidian) so sessions do not re-teach Forever every time. Read ai-assisted-best-practices.md, the mandatory luacheck gate, and the security / performance checklists. See Using with AI coding tools.

What's inside

Folder	What you'll find
01-guides/wiki/	17 Warcraft Wiki pages as Markdown. Numbered files are tutorials in reading order; ref-* files list every API function, event, widget method, script handler and CVar.
06-notes/	Notes written while building and shipping real addons: Forever rules, quirks, Lua learning, agent memory (Hindsight/Obsidian), topic guides, AI security/performance gates.
AGENTS.md	Tool-agnostic instructions for any coding agent (Claude, Copilot, Cursor, Codex, Gemini, …).
07-starter/HelloAzeroth/	A minimal addon for both clients: event handling, a slash command, saved settings and Forever detection.
07-starter/more-examples/	Ace3 addon, options panel, addon-to-addon messages, boss encounter handling, multi-version TOCs. Their TOCs say 120005; update ## Interface: before loading them.
07-starter/more-examples/StandardUI/	The standard addon UI (same look as SnapPost Forever and ProfessionMaster): a reusable UIKit.lua plus an example window with sidebar, list rows, minimap button and options page. Loads on Forever, Classic Era and Midnight; type /sui.
sync.sh	Downloads and updates everything in External sources.

Using with AI coding tools

AGENTS.md is the single source of truth for agents. Tool-specific files only point at it (and at the deep-dive notes) so Claude, Copilot, Cursor, and others all get the same security and performance gates.

Tool	What to open / what loads automatically
Any agent	Tell it: “Follow AGENTS.md.” Or @AGENTS.md / attach that file in chat.
Claude Code	CLAUDE.md (auto-read) → AGENTS.md
GitHub Copilot	.github/copilot-instructions.md (repo instructions)
Cursor	AGENTS.md + .cursor/rules/ (Lua/TOC gates)
Gemini CLI	GEMINI.md → AGENTS.md
Windsurf	.windsurfrules → AGENTS.md
Codex / other	Prefer AGENTS.md; attach the three 06-notes/addon-dev/ai-*.md / checklist files for deep work

Human-readable playbooks (same content the agents should follow):

• 06-notes/addon-dev/ai-assisted-best-practices.md
• 06-notes/addon-dev/agent-memory-setup.md — Hindsight (primary) + optional Obsidian; token discipline
• 06-notes/addon-dev/luacheck-and-code-quality.md — run before finish / publish / r/wowaddons (install luacheck separately; not bundled here); also lists optional GUI scanners (Mechanic, Globe, wowlua, AddonSentry)
• 06-notes/addon-dev/security-and-trust.md
• 06-notes/addon-dev/performance-and-resources.md

Cursor skills (auto-picked by task):

• .cursor/skills/wow-luacheck/ for lint and publish work.
• .cursor/skills/wow-addon-ui/ for any window, panel, list, minimap button or options page, so every addon shares the standard look.

Optional broader skill (retail-focused, separate repo): wow-addon-dev for Claude/Codex/Gemini skill folders — still use this repo’s Forever notes when targeting Forever.

External sources

These aren't stored in this repo. They belong to their authors and change with every patch, so sync.sh downloads them straight from the source into the folder shown.

Source	What it is	Local folder	License
Gethe/wow-ui-source (live, forever)	Blizzard's own UI code (FrameXML) and the generated API documentation for each client	03-blizzard-source/	Blizzard's code; mirror, no license
Ketho/BlizzardInterfaceResources (live, forever)	Plain lists of every global function, event, frame, template, texture atlas and string	04-interface-resources/	none declared
Atraeau/WoW-Addons	Forever API definitions generated from the Forever client (browse online)	02-api-docs/forever-api-dump/	none declared
BigWigsMods/packager	The release packager CurseForge, Wago and WoWInterface projects use to build zips	05-libraries/packager/	none declared
wowforeverguides.com addon series	Forever developer guide: guide, patterns, API cheat sheet, pitfalls, code templates	01-guides/forever/	site content, all rights reserved
Ketho/vscode-wow-api	Type annotations for the whole API. Install the VS Code extension for autocomplete and inline docs	02-api-docs/vscode-wow-api/	MIT
WoWUIDev/Ace3	The most widely used addon framework (addon objects, events, profiles, config UI), includes LibStub	05-libraries/Ace3/	BSD-style

Also worth bookmarking: Warcraft Wiki: World of Warcraft API and the in-game /api command.

Learning Lua

Addons are Lua 5.1 inside a WoW sandbox (no general file/OS I/O). Full list of books and links:

06-notes/addon-dev/lua-learning-resources.md

Highlights:

Resource	Why
Programming in Lua (PiL) — 1st ed. free online	The standard language book
Lua 5.1 Reference Manual	Authoritative syntax and standard library
Learn X in Y minutes: Lua	Quick syntax tour
lua-users wiki	Community patterns
01-guides/wiki/10-lua-functions.md	Which Lua builtins exist in WoW

Which source to trust

When two sources disagree:

• Forever: the client's generated docs win: 03-blizzard-source/forever/Interface/AddOns/Blizzard_APIDocumentationGenerated/, or /api in game. The Atraeau dump is easier to search but can lag a build behind. Then check 06-notes/forever-quirks.md for behaviour that only shows up at runtime.
• Midnight: 03-blizzard-source/midnight-live/Interface/AddOns/Blizzard_APIDocumentationGenerated/, then the wiki.
• Forever is not Classic. Code copied from Classic Era addons usually needs rewriting for the modern APIs.

Handy searches once sync.sh has run:

rg -n "GetItemInfo" 03-blizzard-source/forever/Interface/AddOns/Blizzard_APIDocumentationGenerated/
rg -n "MAIL_SHOW" 04-interface-resources/*/Resources/Events.lua
rg -n "^## " 01-guides/wiki/ref-events.md | rg -i trade

Repository layout

First-Timers/
├── 01-guides/
│   ├── wiki/                  Warcraft Wiki tutorials + references (in repo)
│   └── forever/               wowforeverguides.com series (sync.sh)
├── 02-api-docs/               Forever API dump, vscode-wow-api (sync.sh)
├── 03-blizzard-source/        Blizzard UI source per client (sync.sh)
├── 04-interface-resources/    Globals, events, frames, atlases per client (sync.sh)
├── 05-libraries/              Ace3, packager (sync.sh)
├── 06-notes/                  Notes from shipping real addons (in repo)
│   └── addon-dev/             Topic guides + AI security/performance playbooks
├── 07-starter/                HelloAzeroth + more examples (in repo)
├── AGENTS.md                  Canonical instructions for every AI coding tool
├── CLAUDE.md / GEMINI.md      Thin pointers for Claude Code / Gemini CLI
├── .github/copilot-instructions.md
├── .cursor/rules/             Cursor-specific mirrors of the same gates
├── .windsurfrules             Windsurf pointer → AGENTS.md
└── sync.sh                    Download / update script

Tips for first timers

• Restart the game after editing a .toc file. /reload reloads Lua but not the addon list.
• Turn on error messages with /console scriptErrors 1, or install BugSack, so mistakes don't fail silently.
• Use /dump to inspect anything: /dump C_Item.GetItemInfo(2318).
• Set your event handler before registering events, and read saved settings in ADDON_LOADED, not at file load.
• Don't modify protected frames in combat. Check InCombatLockdown() first.
• Start small. One file, one event, one slash command. HelloAzeroth is all three.
• Learn Lua 5.1 when you need it. Books and manuals: Learning Lua / lua-learning-resources.md. Prefer 5.1 docs over newer Lua editions.
• If an AI wrote the code, point it at AGENTS.md, then verify every API against Forever/Midnight docs and run the security and performance checklists before you trust it in-game.
• Install luacheck separately before the publish gate — it is not included in First Timers or WoW. See luacheck-and-code-quality.md (Install section).
• Give AI agents memory. Prefer Hindsight; optional Obsidian for short human notes. Setup: agent-memory-setup.md.

Credits and licenses

• Warcraft Wiki pages in 01-guides/wiki/ are from warcraft.wiki.gg under CC BY-SA 4.0. Each file names its source page at the top.
• External sources keep their own licenses (see External sources) and are downloaded from their authors; they aren't redistributed here.
• Notes in 06-notes/ and the starter addon were written by Terynas while building the SnapPost and ProfessionMaster addons.
• World of Warcraft is a trademark of Blizzard Entertainment. This project isn't affiliated with or endorsed by Blizzard.