wowlua for VS Code

wowlua is a typed language, compiler, test runner and emulated client for World of Warcraft addons. This extension needs the wowlua command on your PATH (or its path in the wowlua.path setting). Install it, then reload VS Code:

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

# Windows (PowerShell)
irm https://github.com/DomenikIrrgang/wowlua/releases/latest/download/install.ps1 | iex

Colors .wowlua files (keywords, strings and their {…} expressions, decorators, declared names, type annotations as types), toggles -- comments with Cmd+/, closes brackets and indents blocks.

Check, format and outline wowlua addons as you type. The extension starts wowlua lsp: errors and warnings show in the Problems view a moment after you stop typing (and at once when you save), for the edits you haven't saved too; Format Document formats as wowlua fmt does with your package's fmt settings; the outline and breadcrumbs list a file's functions, classes with their methods, locals, enums and types; Go to Definition (F12, or Ctrl or Cmd + click) leads from a name to where it is defined, in your files or in the game's API; Find All References (Shift+F12) lists every place in your workspace that uses a name, and Rename Symbol (F2) renames it everywhere, or says why it can't; hovering a name shows its type and doc comment; completion lists the names in scope, the game's API, and after . and : a value's fields and methods. A package wowlua can't load (a broken wowlua.json, a package.wowlua this wowlua doesn't satisfy) is an error message saying why, as nothing in it is checked. The Testing view lists your tests (*.test.wowlua) and runs or debugs a file or a single test, each result shown at its test; "Run test" and "Debug" above each test do the same (wowlua.testCodeLens hides them). Run with Coverage shows which lines, branches and functions of the addon the tests ran (VS Code 1.88 or newer), and wowlua: Show Coverage Report opens the HTML coverage report in a tab, where a line's number opens that line. wowlua.languageServer turns it off; wowlua: Restart Language Server restarts it (its log is in the wowlua Language Server output).

Debug wowlua addons and their tests in wowlua's emulated World of Warcraft client: breakpoints in .wowlua and .lua files, stepping, the call stack with the events and scripts that ran your code, variables with their taint, watches. The extension starts wowlua debug (it needs wowlua 0.10 or newer on your PATH, or its path in the wowlua.path setting).

A launch configuration (.vscode/launch.json):

{
  "type": "wowlua",
  "request": "launch",
  "name": "wowlua: debug a test",
  "test": "tests/options.test.wowlua",
  "filter": "options window"
}

A session runs one flavor: "flavor": "camelot" chooses it; without one, the extension takes the package's only flavor or asks which of its flavors to debug, and the Debug Console names the flavor that runs.

Also "addon": true to run the addon itself, "clock": "manual", "stopOnEntry": true, "debugBlizzardUI": true. See Debugging in the emulator.

Debugging the addon itself

"addon": true runs the addon in the emulated client, logged in, without a test: set breakpoints, then use it. In the Debug Console a line starting with / is a slash command, as typed in chat (/wdemo); any other line is Lua, run in the game (or in the stopped frame while paused). Clicks in the UI panel (below) click in the game.

{ "type": "wowlua", "request": "launch", "name": "wowlua: run the addon", "addon": true, "flavor": "camelot", "profile": "camelot" }

"profile" starts the session in a world profile (tests/profiles/<name>.json: the character with its name, gear and bags, the world around it) instead of the default character; the widget demo has camelot, a recorded WoW Forever character, "Player Lastname", with eight other players online to /invite (/invite Gorak Stonefist), enough for a party and, after C_PartyInfo.ConvertToRaid(), a raid.

The game's screen

While a session runs, the wowlua: UI panel beside the editor shows the game's screen as the client draws it (with your installation's textures and fonts). It redraws at every stop and step, and once a second while the game runs (wowlua.ui.refreshInterval, 0 for stops only). Click in it to click in the game (right-click for the right button): the frame under the pointer gets the click, so its breakpoints stop. Zoom with Ctrl or Cmd and the wheel (or a pinch), or the buttons; pan with the scrollbars, the wheel, or by dragging with the middle button or Space held. Zoom to frame… lists the frames on screen (type to filter, arrows and Enter to pick) and zooms to the one you pick; zoomed in, the screen is drawn sharper. wowlua: Show UI opens it; wowlua.ui.autoOpen opens it as a session starts.

The wowlua Frames view in the debug sidebar lists the frames on screen with their type, size and text; select one to outline it in the panel, or its zoom button to zoom to it.

Trying it from the repository

ln -s "$(pwd)/editors/vscode" ~/.vscode/extensions/wowlua

then reload VS Code. To package it: npx @vscode/vsce package in this folder.

Its tests drive a VS Code of their own on examples/widget-demo (they need a WoW installation and cargo build --release -p wowlua-cli): editors/vscode/test/run.sh (WOWLUA_SCENARIO=lsp for the language client alone). node --test editors/vscode/test/connection.test.js checks the client's connection to wowlua lsp without VS Code, and node --test editors/vscode/test/grammar.test.js the grammar with VS Code's own tokenizer.