Skip to content

About

WoW: Forever addon dev environment — multi-addon workspace with deploy/scaffold tooling and a generated API reference for the modern (12.0) client.

Topics

Resources

Stars

17 stars

Watchers

0 watching

Forks

Repository files navigation

WoW-Addons

A development environment for building multiple World of Warcraft addons against WoW: Forever (codename Camelot, product wow_classic_beta, Interface 16001 — a modern 12.0-based engine), plus a generated reference for that client's whole API.

Each addon lives under src/. One build turns each into exactly the files the game loads, and one deploy script junction-links those builds into the live game, so a rebuild (or -Watch) is all it takes after an edit.

📖 Live API reference: https://atraeau.github.io/WoW-Addons/ — searchable, browsable, and machine-readable (tools can fetch api.json).

Repository map

Path What's there
src/ Your addons — one folder each, holding everything about that addon: game code, tests, simulators, docs (source of truth)
AddOns/ Build output (gitignored): src/<Addon> built into exactly the files the client loads, mirroring the game's Interface/AddOns folder. See Building and releases
vendor/ Tracked third-party addons (patched for this client)
docs/api/ Generated API reference — 405 namespaces in 19 category folders
docs/README.md How the API docs + LSP definitions are generated
scripts/ Build, deploy, scaffold, and doc/definition generators
types/ Lua Language Server definitions (client-accurate autocomplete)
wow-dev.config.json Game path, flavor, interface version (shared config)
.vscode/ Recommended extensions + Lua LSP settings

Addons

Addon Location What it is
HelloForever src/HelloForever Example addon produced by the scaffolder (/hf)
WowBagSorter src/WowBagSorter Bag/bank sorter (originally Classic 1.13; may need 12.0 fixes)
KingsGambit src/KingsGambit King's Gambit raid loot ledger (inspired by Suicide Kings: keeps what works, fixes what does not); the addon itself is in its src/
WowApiExport src/WowApiExport Dev tool — dumps the client's own API docs (/apiexport)
BTPCompatCheck src/BTPCompatCheck Dev tool — probes which APIs exist on the client (/btpcheck)
BlizzThreatPlates vendor/BlizzThreatPlates Patched third-party addon (MIT) — see PATCHES.md

King's Gambit

A full-featured raid loot system, inspired by Suicide Kings, that keeps what works and fixes what does not (gifting), with a tamper-evident shared ledger. The engine is plain Lua with no game dependency, so it is fully tested outside WoW.

Everything about it lives in src/KingsGambit/: the addon (its src/, with the training and simulation code the game uses too), plus its docs, tests, simulator, tools and data scripts. The build ships only what its TOC loads.

Building and releases

src/<Addon>/ is the whole project for an addon. scripts/build-addons.lua turns it into AddOns/<Addon>/: the TOC files, every file they list (following XML includes), assets the code names by their Interface\AddOns\<Addon>\ path, and a license file; nothing else. An addon can add a build.lua (root = "src" if its TOC is in a subfolder; extra = {...}).

lua scripts/build-addons.lua --check          # build everything into AddOns/ and verify what ships
lua scripts/test-build-addons.lua             # the build tool's own tests
.\scripts\deploy.ps1 [-Name X] [-Watch]       # build, then junction AddOns/<Addon> into the game (-Watch rebuilds on save)

Releases come from CI. Every push to main that changes what an addon ships publishes a GitHub pre-release <Addon>-v<version> with <Addon>-<version>.zip (the addon folder at the top, ready to upload to CurseForge). The version is the TOC's ## Version: plus the run number as SemVer build metadata (0.1.0+57); change the TOC version for a bigger step. King's Gambit uses Semantic Versioning to decide who may play together: the same MAJOR (or the same MAJOR.MINOR while it is 0.x), not the same exact version. A change to the ledger's entries, rules or messages must start a new line, and a test enforces that (see the ledger format doc). Pushes that only touch tests, docs or the simulator publish nothing. The newest 30 per addon are kept.

API reference

The client documents its own API (the /api system). docs/api/ is that surface turned into browsable Markdown — 6,577 functions, 1,802 events, 792 types across 405 namespaces, grouped into 19 folders (Units & Combat, Items & Inventory, Spells/Auras/Talents, UI Widgets & Frames, Core & Shared Libraries, …). Each function page has its signature, typed argument/return tables, description, and an example.

Regenerate it (and the LSP definitions) any time — see docs/README.md:

# In game: /apiexport  then  /reload   (writes the dump to SavedVariables)
.\scripts\generate-api-docs.ps1          # -> docs/api/
.\scripts\generate-lua-definitions.ps1   # -> types/WowForeverAPI.lua
.\scripts\generate-console-docs.ps1      # -> docs/console-commands.md (every console command and CVar the client lists, sorted by topic; the topic rules are in scripts/console-groups.json)

Quick start

# 1. Link every addon in src/ into the game's AddOns folder (junctions, no admin needed)
.\scripts\deploy.ps1

# 2. Launch WoW: Forever. On character select, enable "Load out of date AddOns"
#    if anything is grayed out. In game, type:  /hf

# 3. Create a new addon
.\scripts\new-addon.ps1 -Name MyAddon -Title "My Addon" -Notes "What it does"
.\scripts\deploy.ps1 -Name MyAddon

After editing a .lua, rebuild (.\scripts\deploy.ps1 -Name X, or leave -Watch running) and /reload in game. The game folders are junctions to the build, so nothing needs copying.

On macOS or Linux, scripts/deploy.sh does the same job with symlinks and takes the same options (--name X, --copy, --clean). Point it at the game with a local override, which is gitignored:

echo '{ "gamePath": "/Applications/World of Warcraft" }' > wow-dev.config.local.json
scripts/deploy.sh

Scripts

Command What it does
deploy.ps1 Junction-link every addon under src/ (and <project>/src/) into the game
deploy.ps1 -Name X Link only addon X
deploy.ps1 -Copy Hard-copy instead of link (packaging / other drives)
deploy.ps1 -Clean Remove the deployed links (source untouched)
deploy.sh macOS/Linux counterpart: symlinks, same options as deploy.ps1
new-addon.ps1 -Name X Scaffold src/X/ with TOCs + Core.lua
generate-api-docs.ps1 Build the Markdown API reference from a dump
generate-lua-definitions.ps1 Build types/ LSP definitions from a dump
generate-luacheck-globals.ps1 Build types/luacheck-globals.lua (every client global, for luacheck) from docs/api.json

Grouping rules for the docs live in scripts/api-categories.psd1; curated examples in scripts/api-examples.psd1.

Editor setup

Open the folder in VS Code and install the recommended extensions (.vscode/extensions.json: sumneko Lua + WoW API). The Lua Language Server is pointed at types/WowForeverAPI.lua via .vscode/settings.json, so completion and hover match this client's actual API.

Key Value Meaning
gamePath C:\Program Files (x86)\World of Warcraft WoW install root
flavorDir _classic_beta_ Flavor folder that holds Interface\AddOns
interface 16001 TOC interface version (patch 1.60.1 → 16001)
tocSuffix Camelot Flavor TOC suffix the client prefers (<Addon>_Camelot.toc)

Create wow-dev.config.local.json (gitignored) to override any of these locally.

When the client updates: bump interface in the config, then edit .toc files (or re-scaffold) and re-run the export + generators. Confirm the live number in game with /dump select(4, GetBuildInfo()).

Linting

Install luacheck and run luacheck src from the repo root. Config: .luacheckrc. It merges types/luacheck-globals.lua, generated from this client's docs/api.json, into read_globals, so an "undefined variable" warning means either a typo or a function this client no longer has (GetContainerItemInfo, UnitAura, ...), which is the signal a port needs. Regenerate it with generate-luacheck-globals.ps1 after a client update; CI does the same on push.

About

WoW: Forever addon dev environment — multi-addon workspace with deploy/scaffold tooling and a generated API reference for the modern (12.0) client.

Topics

Resources

Stars

17 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages