Status: Draft 0.1 · Last updated 2026-10-11
wowlua is a language, compiler, framework and package manager for World of Warcraft AddOns. This directory is the normative specification. The compiler (written in Rust) is implemented against it.
Documents
| # | Document | Contents |
|---|---|---|
| 0 | Overview | Goals, principles, the superset guarantee, project anatomy, terminology |
| Language | ||
| 1 | Syntax | Lexical structure, statement and expression extensions, syntax sugar |
| 2 | Types | Type syntax, gradual checking, inference, narrowing, declaration files |
| 3 | Classes, interfaces, enums | Classes, inheritance, widget classes, interfaces, enums |
| 4 | Decorators | Decorator syntax and semantics, built-in decorators, user decorators |
| 5 | Modules | import / export, resolution, load order, interop with plain Lua |
| 6 | Build metadata & conditional compilation | wowlua:meta, flavors, profiles, compile-time folding |
| 7 | Debugging & reflection | wowlua:debug, profiling, tracing, runtime checks, reflection |
| Standard library | ||
| 8 | Standard library | WoW-specific framework modules (wowlua:*) |
| Toolchain | ||
| 9 | Manifest | wowlua.json reference |
| 10 | Package manager | Packages, sources, resolution, lockfile, embedding |
| 11 | Publishing | Packaging and upload to CurseForge, Wago, WoWInterface, GitHub |
| 12 | CLI | wowlua command reference |
| 13 | Compiler architecture | Rust implementation: crates, pipeline, data structures |
| 14 | Code generation & output | Lowering, runtime library, output layout, TOC generation |
| 15 | Optimization | Bundling, minification levels, folding, tree-shaking |
| 16 | Developer tooling | Test runner, language server, formatter, trace decoder |
| 17 | WoW client emulation | The test VM and engine: WoW's Lua, taint, secret values, the generated API, FrameXML (planned, M9) |
| Appendices | ||
| A | Grammar | Complete grammar (EBNF) |
| B | Diagnostics | Error and warning codes |
| C | Decision log | Design decisions and their rationale |
| — | Roadmap | Implementation milestones |
Conventions
- MUST, MUST NOT, SHOULD, MAY are used as in RFC 2119.
wowluacode blocks are wowlua source.luacode blocks show the Lua 5.1 the compiler emits. Emitted code in this spec is shown pretty-printed for readability. Real output follows the layout rules in Code generation.- Names starting with
__wlin emitted code are compiler-generated. The compiler makes them hygienic (see Code generation). - "Lua" without a version always means Lua 5.1 as embedded in World of Warcraft.