v0.9

v0.9 · a strict superset of Lua 5.1 · macOS, Linux, Windows · MIT licence

Typed Lua for World of Warcraft AddOns

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.

start a new addonbring your addonor read the language reference

Install wowlua

a single binary, no runtime to install

curl -fsSL https://github.com/DomenikIrrgang/wowlua/releases/latest/download/install.sh | sh

Then run wowlua new MyAddon, or wowlua init --from-pkgmeta in your addon's folder.

~/TypedDemozsh
$ wowlua new TypedDemo --flavors standard,camelot,vanilla  # wowlua.json, src/, tests/
     Created addon package in TypedDemo
$ cd TypedDemo && wowlua check
error[E2003]: `Ledger` has no field or method `balanse`
   ┌─ src/main.wowlua:88:10
   │
88 │ print(l2.balanse)
   │          ^^^^^^^ here

error: aborting due to 1 previous error
$ wowlua test                             # in the emulated client, per flavor
 PASS tests/main.test.wowlua (standard, 0.04s)
   ✓ greets at login
 PASS tests/main.test.wowlua (camelot, 0.05s)
   ✓ greets at login
 PASS tests/main.test.wowlua (vanilla, 0.03s)
   ✓ greets at login
      Tested 3 passed, 0 failed, 0 skipped (3 files) in 0.32s
$ wowlua build --release                  # bundled and minified
    Finished TypedDemo 0.1.0-alpha (release: standard, camelot, vanilla) in 0.09s → dist/release/TypedDemo
$ wowlua publish                          # CurseForge, Wago, WoWInterface, GitHub Releases

Two ways in

Start from an empty folder, or point wowlua at the addon you already ship. Both end in the same place: a checked, complete AddOn.

[ start new ]

Your first AddOn in a minute

Typed access to the WoW API of every flavor, generated from Blizzard's documentation. wowlua dev recompiles only what changed when you save and syncs into your AddOns folders.

wowlua new MyAddon --flavors standard,mists,vanilla
follow the getting started guide →
[ bring your addon ]

Adopt it without rewriting it

init 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.

wowlua init --from-pkgmeta
read the adoption guide →

It compiles to the Lua you would write

Types are erased, sugar is lowered, and the output stays readable Lua 5.1 with your line numbers, so in-game errors point at your source.

src/util.wowluawowlua
local function clamp(v: number, lo: number = 0, hi: number = 1): number    return math.max(lo, math.min(hi, v))end
emittedlua 5.1
local function clamp(v, lo, hi) if lo == nil then lo = 0 end if hi == nil then hi = 1 end    return math.max(lo, math.min(hi, v))end

One tool from first file to release

The language, compiler, framework and package manager ship as one binary.

  • language

    Types, classes, modules

    .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.

    export class Counter
    private count: number = 0
  • compiler

    Catch bugs before /reload

    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.

    error[E2001]: `"now"` is not
assignable to `number`
  • framework

    The parts every addon needs

    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.

    @event("PLAYER_LOGIN")
  • package manager

    Publish everywhere at once

    A wowlua.json manifest describes the addon. Dependencies are resolved, locked and embedded. Finished addons are packaged and uploaded to every configured addon site.

    wowlua publish --dry-run
[ in game ]

A dev window inside the game

Dev builds carry debugging tools without any change to your code, and release builds contain none of it. Type /wl.

  • → 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 trace maps errors and stacks from the game back to your source lines, also through the source maps of bundled builds.
[wl] wowlua dev TypedDemo ×
overview profiler monitor log errors 2 watch inspector
functioncallstotal ↓selfmaxavg warbandGold1,28458.36.2021.40.05 Ledger:update1,28441.229.80.410.03 Ledger:summary1218.73.101.201.56 Ring:push1,28411.411.40.090.01

Built in the open

github ↗Source, issues and releases. MIT licence.roadmap →M0 to M8 done, M9 (test runner, language server, formatter) in progress, next: registry.changelog →Every release, latest v0.9.0, and what is on main but not released yet.