Warcraft Lua Toolkit

A Visual Studio Code extension for Warcraft III Lua and JASS-family development. It combines language intelligence, mixed-source map builds, compile-time object editing, archive tools, and Warcraft asset previews in one package.

No separate LuaLS or WurstScript installation is required for the integrated features described below.

Highlights

Language support

• Embedded Lua language server configured for Warcraft III and Lua 5.3
• Native editor intelligence for JASS, vJASS, Zinc, and cJASS
• Workspace diagnostics, completion, hover, signature help, navigation, references, rename, symbols, semantic highlighting, hierarchy views, CodeLens, inlay hints, formatting, and quick fixes
• Automatic loading of Warcraft APIs, generated object IDs, luaStdlib, and object-editing declarations
• Asset-string previews and Ctrl+Click navigation for Warcraft paths

Map development

• Compile mixed Lua and JASS-family sources into war3map.lua
• Convert JASS, vJASS, Zinc, and cJASS to native Lua
• Extract an existing map script and use it as project source
• Build into a copied .w3x or .w3m; the source map is never modified
• Insert generated object data and files from imports/
• Build and launch Warcraft III from VS Code

Warcraft tooling

• Browse MPQ archives and folder maps
• Inspect and edit Warcraft object data and map information
• Preview BLP, DDS, TGA, MDX, MDL, and common audio formats
• Inspect Warcraft map files such as .doo, .w3e, .wtg, .wct, and .wpm
• Preview map terrain, cliffs, water, doodads, units, and start locations
• Syntax highlighting for WTS, FDF, TOC, MDL, and related formats

Getting started

1. Open the Command Palette.
2. Run Warcraft Lua: Create New Project.
3. Select a source map and, when needed, your Warcraft III installation.
4. Add source files under src/ and imported assets under imports/.
5. Run Warcraft Lua: Compile and Build Map or Warcraft Lua: Compile and Run Map.

A generated project uses this structure:

.vscode/settings.json
YourMap.w3x
imports/
src/
  war3map.lua
  custom.lua
_build/
  compiledwar3map.lua
  common.lua
  blizzard.lua
  HiddenNatives.lua
  dependencies/
    assets/
      AbilityIds.lua
    luaStdlib/
      objediting/
        ObjEditingCommons.lua
        objediting.d.lua
  cache/
    YourMap.compiled.w3x
    objectdata/

The exact generated files depend on the selected map and project settings.

Lua development

The embedded Lua language server provides standard Lua editing features plus Warcraft-aware libraries and generated declarations. New projects are configured for Lua 5.3 automatically.

The toolkit loads these libraries when available:

_build/common.lua
_build/blizzard.lua
_build/HiddenNatives.lua
_build/dependencies/assets
_build/dependencies/luaStdlib
_build/cache/objectdata/object_ids.lua

Support code under _build is project-owned after it is installed. The extension preserves edits to common.lua, blizzard.lua, HiddenNatives.lua, objediting.d.lua, asset libraries, and legacy dependency files instead of refreshing or deleting them.

Place common.j or blizzard.j directly under _build to use a custom JASS API. The matching common.lua or blizzard.lua declaration is generated immediately and regenerated whenever the .j file is saved. While a matching .j file exists, edit that source rather than its generated .lua output.

Runtime .lua files under _build/dependencies/assets and _build/dependencies/luaStdlib/objediting are automatically compiled before the configured project sources, except for AbilityIds.lua. Declaration files ending in .d.lua are excluded. The bundled AbilityIds.lua is an editable compile-time constant catalog: references such as AbilityIds.blizzard are replaced with integer rawcodes during the build, and the table itself is omitted from the final map script. _build/dependencies/luaStdlib/objediting/ObjEditingCommons.lua adds commaList(...), which joins values with commas and converts rawcode integers back to four-character strings.

hero:setHeroAbilities(commaList(
    AbilityIds.blizzard,
    AbilityIds.summonWaterElemental,
    AbilityIds.brillianceAura,
    AbilityIds.massTeleport
))

Generated build outputs remain managed: _build/compiledwar3map.lua and files under _build/cache are recreated by builds.

JASS-family library, scope, struct, and module initializers are normally inserted into global main. When warcraftLua.build.extractMapScript is disabled and no global main exists, the toolkit schedules __WLT_ProjectInit() through a zero-second Warcraft timer instead. This supports UjAPI-style Lua scripts that intentionally omit main and config.

To prevent duplicate diagnostics and completions, the embedded server does not start when another Lua language-server extension is detected by default.

JASS-family development

.j, .jass, .vjass, .zinc, and .cjass files are analyzed directly rather than through generated Lua shadow files. The workspace index follows recursive imports and understands common JassHelper constructs, including libraries, scopes, structs, interfaces, modules, textmacros, visibility, inheritance, and initializers.

Use Warcraft Lua: Convert JASS Family to Native Lua to convert a complete source file, selected editor text, or tagged JASS-family blocks embedded in Lua.

--[[!vjass
library LegacyDamage
    function CalculateDamage takes integer base returns integer
        return base + 25
    endfunction
endlibrary
]]

Supported embedded tags are !jass, !vjass, !zinc, and !cjass.

Unsupported syntax fails with a source-aware diagnostic instead of being silently removed.

Compile-time object editing

Mark Lua functions with ---@compiletime to generate Warcraft object data during a build:

---@compiletime
local function configureObjects()
    local unit = UnitDefinition("h000", "hfoo")
    unit:setName("Elite Footman")
        :setHitPoints(900)

    ObjectEditor.export("ELITE_FOOTMAN", unit)
end

Generated object files are written under _build/cache/objectdata, and exported rawcodes are available to runtime code through generated declarations.

Build behavior

A normal build:

1. Extracts or refreshes the configured map script when enabled.
2. Loads runtime libraries from _build/dependencies/assets and _build/dependencies/luaStdlib/objediting.
3. Processes configured Lua and JASS-family sources plus embedded blocks.
4. Executes ---@compiletime functions.
5. Generates _build/compiledwar3map.lua.
6. Copies the source map into _build/cache.
7. Inserts the compiled Lua script, generated object data, and imported files.
8. Verifies the resulting map archive.

Main commands

Important settings

Additional settings are available under Extensions → Warcraft Lua Toolkit in VS Code.

Contributions

Contributions, bug reports, compatibility examples, and focused test cases are welcome.

Warcraft Lua Toolkit incorporates or adapts work from these open-source projects:

• WurstScript VS Code extension — Warcraft archive, asset, object-data, and map tooling
• Lua Language Server — Lua editing and semantic analysis
• JassHelper — vJASS-compatible preprocessing behavior
• pJASS — base-JASS validation behavior

Warcraft Lua Toolkit is an independent project. Upstream projects retain their respective copyrights and licenses. Full attribution and modification details are documented in THIRD_PARTY_NOTICES.md.

License

The toolkit license is available in LICENSE.md. Third-party notices are available in THIRD_PARTY_NOTICES.md.

Warcraft III and related names are trademarks or property of Blizzard Entertainment, Inc. No endorsement by Blizzard Entertainment or the upstream projects is implied.