wowlua.dev · install · quick start · bring your addon · docs · specification · roadmap · releases · discord
wowlua is a language, compiler, framework and package manager for World of Warcraft AddOns, shipped as one binary. It type-checks your code against the WoW API of every game flavor, builds a complete AddOn, and publishes it to CurseForge, Wago, WoWInterface and GitHub with one command. Every Lua file you have today is already valid wowlua.
Guides, the full reference and the changelog are at wowlua.dev.
| Language | .wowlua is a strict superset of Lua 5.1, the dialect WoW runs. It adds gradual types, classes, interfaces, enums, decorators, import/export modules, reflection, compile-time build information and syntax sugar (+=, continue, ?., ??, string interpolation, …). Everything compiles to plain Lua 5.1. |
| Compiler | Written in Rust. It type-checks your code and always emits a complete, installable AddOn: TOC files for every flavor, embedded libraries, assets and only the runtime pieces you use. Release builds are bundled and minified to the level you choose, to keep in-game load times low. |
| Framework | A typed standard library for what almost every addon needs: events, saved variables, slash commands, timers, localization, settings, a minimap button, addon comms, serialization and logging. |
| Package manager | A wowlua.json manifest describes the addon. Dependencies are resolved, locked and embedded. Finished addons are packaged and uploaded to every configured addon site. |
-- src/main.wowlua
import addon, build from "wowlua:meta"
import event from "wowlua:events"
import log from "wowlua:log"
export class Counter
private count: number = 0
@profile
function increment(by: number = 1): number
self.count += by
return self.count
end
end
local counter = Counter.new()
@event("PLAYER_LOGIN")
local function onLogin()
log.info(`{addon.title} {addon.version} loaded ({build.profile} build)`)
if build.debug then
counter:increment()
end
endMistakes show up before /reload, in the format your terminal already knows:
error[E2003]: `Ledger` has no field or method `balanse`
┌─ src/main.wowlua:88:10
│
88 │ print(l2.balanse)
│ ^^^^^^^ here
macOS and Linux:
curl -fsSL https://github.com/DomenikIrrgang/wowlua/releases/latest/download/install.sh | shWindows (PowerShell):
irm https://github.com/DomenikIrrgang/wowlua/releases/latest/download/install.ps1 | iexFrom source (Rust 1.96 or newer):
cargo install --path crates/wowlua-cliwowlua new MyAddon && cd MyAddon
wowlua dev # watch, build and sync into your WoW AddOns folders
wowlua build --release # bundled, optimized build
wowlua publish # package and upload to every configured addon sitewowlua dev syncs into every WoW client folder it finds (_retail_,
_classic_era_, …) and never overwrites a folder it did not install. In game,
type /wl to open the dev window.
cd MyExistingAddon
wowlua init --from-pkgmetainit turns your TOC files into wowlua.json, moves Lua and XML files into
src/ and updates the in-game paths to them. .pkgmeta externals become
dependencies, and the build matches the BigWigs packager's: the same loaded
code, the same shipped files, line endings and TOC versions. This is checked on
36 addons, including BigWigs, DBM, WeakAuras, ElvUI and Details. Your
packager workflows stay untouched; init prints how to switch them to
wowlua publish.
In plain Lua files the checker only warns, never errors. Rename files to
.wowlua one at a time when you want types, and convert LuaLS annotations with
wowlua types convert <path>.
Dev builds carry debugging tools without any change to your code, and release builds contain none of it.
- Profiler for every function: calls, total, self, max and average time.
- Monitor for events, scripts and timers, plus memory over time.
- Error capture that keeps BugSack and the default error frame working.
- Watches and a table inspector, live while the window is open.
wowlua tracemaps errors and stacks from the game back to your source lines, also through the source maps of bundled builds.
/wl opens the dev window; /wl prof|mon|errors|log|watch <addon> print to chat.
The specification lives in spec/; implementation follows the
roadmap.
| Milestone | Status | |
|---|---|---|
| M0 | Foundation | done · 2026-10-11 |
| M1 | Parser and emitter | done · 2026-10-11 |
| M2 | Lowering of syntax sugar and modules | done · 2026-10-11 |
| M3 | Classes, enums, decorators and stdlib infrastructure | done · 2026-10-11 |
| M4 | Type checker | done · 2026-10-12 |
| M5 | Debugging | done · 2026-10-12 |
| M6 | Package manager | done · 2026-10-12 |
| M7 | Optimization and publishing | done · 2026-10-13 |
| M8 | Standard library | done · 2026-10-15 |
| M9 | Test runner, language server, formatter | done · 2026-10-25 (0.10.0) |
| M10 | Registry | done · 2026-10-26 (0.13.0) |
| M11 | Performance optimization | in progress · built in 0.13.0, perf scenarios in 0.13.10, the in-game check pending |
| M12 | Debugger, profiler, screenshots, 3D models, MCP for AI agents | done · 2026-10-25 (0.10.0) |
| M13 | Game data and rendering | done · 2026-10-25 (0.11.0) |
| M14 | Browser | done · 2026-10-26 (0.12.0) |
| M15 | Studio (IDE) | in progress · its 3D world in 0.13.8, lit, shadowed and weathered in 0.13.9 · wowlua-studio |
What works today:
| Area | |
|---|---|
| Language | Type annotations (erased), +=, continue, ?., ??, string interpolation, bitwise operators, //, const, default parameters, destructuring, import/export, classes (abstract, generic, accessors), widget classes that extend native frame types, enums, core and user decorators, wowlua:meta with static conditions and @if. |
| Type checker | Basic and strict mode, generics, narrowing and flavor guards for shared multi-flavor builds, against the WoW API of every flavor, generated from Blizzard's documentation. |
| Builds | Per-flavor builds with generated TOC files; load order from imports and usage analysis of Lua, .wowlua and XML files; line numbers preserved in dev builds; bundling, minification levels, inlining, global caching and dead-code removal for release builds, within Lua's limits. |
| Debugging | The profiler, monitor, error capture, runtime type checks and the /wl dev window, with wowlua:debug, wowlua:log and wowlua:reflect. |
| Standard library | Written in wowlua, checked at compile time where it can be, and tested in game. The core: events (WoW events, unit events, messages, buckets), lifecycle, timer (@throttle, @debounce, @nextFrame), combat (@outOfCombat), hooks, slash (a typed subcommand router), saved (defaults, migrations, profiles), callbacks, errors, jobs, table, format. Interface: locale (JSON translations, a typed L), pool, settings (Blizzard's Settings API), launcher (minimap button, Addon Compartment, LDB launcher and data sources), frames (movable, resizable, Edit Mode), bindings (keybindings declared in code), menu, list, dialog, color, media, alert, links, widget themes. Game data, secret-value aware: secret, unit (with a roster), aura (with aura containers), spell, item, tooltip. Plus secure (state drivers with checked macro conditionals), serialize, comm and version. |
| Packages | git, SVN, path and archive dependencies in a global cache, locked in wowlua.lock; Lua libraries embedded (only the files the game loads), wowlua libraries compiled in; workspaces for addon suites. |
| Publishing | package and publish to CurseForge, Wago, WoWInterface and GitHub Releases, with API tokens kept in the OS credential store. |
Using a feature of a later milestone reports that milestone.
examples/typed-demo,
examples/widget-demo and
examples/core-demo are sample addons.
Every command
wowlua new <path>: create a package (--kind,--flavors,--ci github).wowlua init [--from-pkgmeta]: adopt an existing addon. Its TOC(s) becomewowlua.json, Lua/XML files move intosrc/and in-game paths to them are updated;.pkgmetaexternals become dependencies, and the build matches the BigWigs packager's (compatsettings, read from.pkgmetaand the project's CI workflows).wowlua add/remove/update/fetch/tree/outdated/cache clean: manage dependencies (git,svn,path,archive, and libraries of the wowlua registry by version requirement).-p <package>selects a workspace member.wowlua build [--release] [--flavor …] [--stats]: a complete AddOn indist/<profile>/<Name>/with generated TOC(s) for every flavor, Lua 5.1 syntax checks, XML reference checks and output validation..wowluafiles are compiled with their line numbers preserved (in-game errors point at the source line); source maps on request.wowlua check: type-check without writing a build (.luafiles too withcheck.lua;--!strictorcheck.modefor strict mode).wowlua lint [--fix]andwowlua fix: unused bindings, shadowing and unreachable code, with machine-applicable fixes.wowlua types convert <path>: turn LuaLS---@annotations into.d.wowluadeclarations.wowlua trace [file] [--clipboard]: map error messages and stacks from the game (error frame, BugSack) back to source lines and functions.wowlua package/publish [--dry-run]: build and package zips, and upload them to every configured publish target.wowlua login <site>/logout <site>: store or remove an API token in the OS credential store.- In game, dev builds:
/wlopens the dev window (profiler, monitor, log, errors, watches, inspector);/wl prof|mon|errors|log|watch <addon>print to chat. wowlua fmt [--check]: a StyLua-like, comment-preserving formatter (plain Lua syntax for now).wowlua dev [--link]/install/uninstall: sync builds into every WoW client folder (_retail_,_classic_era_, …), never overwriting folders that wowlua did not install.wowlua devkeeps compiled files between builds and compiles again only what changed.wowlua toc,wowlua clean,wowlua explain <code>.
cargo test --workspace
cargo xtask codes # regenerate diagnostic codes from spec/appendix/diagnostics.md
cargo xtask schema # regenerate schema/wowlua-<version>.json
cargo xtask check # verify generated files (CI)
cargo xtask corpus fetch && cargo run --release -p xtask -- corpus run
# conformance corpus: Lua 5.1 parity, bytecode round trip, every minification pass, formatter
cargo xtask corpus addons
# adopt, build and type-check the corpus addons, then build them bundled at every
# minification level (WOWLUA_CORPUS_FIX=1: also apply lint fixes)
cargo xtask types fetch && cargo xtask types gen
# regenerate the embedded wow-api declarations
(cd tests/ingame && wowlua install)
# the standard library's in-game tests: /stdtest in WoW runs them all
# (automatic, then guided: combat, a target change, a /reload);
# /stdtest auto runs the automatic ones onlyMIT. The logo and banner in .github/assets
and the VS Code extension's icon are set in Martian Mono and IBM Plex Mono
(SIL Open Font License 1.1) and converted to outlines.
Not affiliated with Blizzard Entertainment. World of Warcraft is a trademark of Blizzard Entertainment, Inc.