Warcraft Lua Toolkit

Warcraft Lua Toolkit is a standalone Visual Studio Code extension for Warcraft III Lua map development. It combines a Warcraft-aware Lua language server, map compilation, compile-time object editing, MPQ/CASC tooling, editable object data, and Warcraft asset and map-file viewers in one package.

You do not need the WurstScript extension or a separate LuaLS/Sumneko extension. The Warcraft-specific tooling and Lua language services described below are integrated directly into Warcraft Lua Toolkit.

Credits and integrated upstream work

Warcraft Lua Toolkit builds on two major open-source projects:

WurstScript VS Code extension

The Warcraft development tools are adapted from the Apache-2.0-licensed WurstScript VS Code extension 0.12.8 (wurstscript/wurst4vscode). Its Warcraft-focused features are integrated under the warcraftLua namespace, including:

• MPQ and folder-map browsing and extraction
• Editable Warcraft object data
• CASC access and Warcraft asset extraction
• BLP, DDS, TGA, MDX, MDL, and audio previews
• Editable map information and binary map-data inspectors
• Experimental terrain preview
• Asset links, hovers, inline icons, and Warcraft file grammars

The Wurst language, compiler, Java tooling, package manager, tests, language server, and Wurst project commands are not included or started. Warcraft Lua Toolkit uses the Warcraft-development portions independently for Lua map workflows.

Lua Language Server

Lua editing support is powered by the MIT-licensed Lua Language Server 3.7.4 (LuaLS/lua-language-server), embedded with native launchers for Windows x64, Linux x64/ARM64, and macOS x64/ARM64. Its completion, diagnostics, navigation, refactoring, semantic highlighting, and EmmyLua analysis are integrated directly into the extension.

The embedded server is adapted for Warcraft III development by automatically loading generated Warcraft APIs and object-editing declarations, recognizing ---@compiletime, treating compile-time functions as build entry points, and supporting Lua files both inside and outside a workspace through one multi-root client.

Warcraft Lua Toolkit is an independent project. These upstream projects retain their respective copyrights and licenses. Full attribution, modification details, and included license locations are in THIRD_PARTY_NOTICES.md.

Features

Lua development

• Embedded LuaLS 3.7.4 with completion, diagnostics, hover, signature help, definitions, references, rename, symbols, folding, semantic highlighting, code actions, auto-require, hints, and EmmyLua annotations
• Automatic Lua 5.3 configuration for new Warcraft projects
• Automatic loading of common.lua, blizzard.lua, HiddenNatives.lua, luaStdlib, and generated object IDs
• First-class ---@compiletime annotation support
• Warcraft API declarations refreshed from CASC, loose JASS files, or classic MPQ archives

Map development

• Compile Lua sources into war3map.lua
• Extract an existing war3map.lua or convert war3map.j into Lua
• Build to a copied .w3x or .w3m; the source map is never modified
• Insert generated object data and files from imports/
• Automatically expand full MPQ hash tables for large import sets
• Compile and launch Warcraft III

Warcraft tooling

• MPQ and folder-map browser
• Editable .w3u, .w3t, .w3a, .w3b, .w3d, .w3h, and .w3q files
• BLP, DDS, TGA, MDX, MDL, MP3, WAV, OGG, and FLAC previews
• Editable .w3i map information
• Viewers for .doo, .wpm, .wtg, .wct, .w3e, .w3r, .w3c, .w3s, .w3l, .w3o, .imp, .mmp, and .shd
• Experimental terrain preview with terrain, cliffs, water, doodads, units, and start locations
• WTS, FDF, TOC, and MDL syntax highlighting

Create a project

Run Warcraft Lua: Create New Project from the Command Palette. A workspace does not need to be open first.

A new project uses this layout:

.vscode/settings.json
ExampleMap.w3x
imports/
src/
  custom.lua
  war3map.lua       # extracted Lua or converted JASS, when enabled
  war3map.j         # extracted only when JASS conversion is disabled
_build/
  common.lua
  blizzard.lua
  HiddenNatives.lua
  compiledwar3map.lua
  dependencies/
    luaStdlib/
      objediting/
        objediting.d.lua
  cache/
    ExampleMap.compiled.w3x
    objectdata/
      object_ids.lua
      war3map.w3u   # only generated object-data types are written
      ...

The object-editing declaration library is packaged with the extension and is created or repaired automatically at:

_build/dependencies/luaStdlib/objediting/objediting.d.lua

common.lua, blizzard.lua, and HiddenNatives.lua remain directly under _build; they are not placed in dependencies.

Compile-time object editing

A compile-time function may live in any configured source file. Mark it with ---@compiletime:

local FOOTMAN = "hfoo"

---@compiletime
local function configureObjects()
    local elite = UnitDefinition("h000", FOOTMAN)
    elite:setName("Elite Footman")
         :setHitPoints(900)
         :setAttackDamage(24, 2, 6)

    ObjectEditor.export("ELITE_FOOTMAN", elite)
end

function SpawnEliteFootman(player, x, y)
    return CreateUnit(player, OBJECT_IDS.ELITE_FOOTMAN, x, y, 270.0)
end

During a build, every annotated function is executed in the compile-time environment. Generated object binaries are written under _build/cache/objectdata, while the annotated functions are removed from the runtime script. Runtime code in the same source file remains intact.

LuaLS treats annotated local functions and compile-time-only helpers as used, so they do not produce unused-local or unused-function warnings. Runtime calls to functions that will be removed are diagnosed by the Toolkit.

Build process

Run Warcraft Lua: Compile and Build Map. The Toolkit:

1. Extracts or refreshes the selected map script in src when enabled.
2. Executes all ---@compiletime functions.
3. Generates _build/compiledwar3map.lua.
4. Copies the source map to _build/cache/<map-name>.compiled.w3x or .w3m.
5. Inserts the compiled script as war3map.lua.
6. Inserts generated object data and files from imports/.
7. Selects Lua in war3map.w3i and verifies the written archive entries.

The built-in MPQ writer enlarges the copied map's hash table when necessary, so projects with large import sets remain in normal .w3x or .w3m mode.

Warcraft API definitions

New projects immediately receive bundled editor declarations:

_build/common.lua
_build/blizzard.lua
_build/HiddenNatives.lua

When a Warcraft III installation is available, common.lua and blizzard.lua are refreshed from the installed game:

• Modern installations use the integrated CASC reader.
• Classic installations use loose JASS files or matching MPQ archives.

The JASS-to-Lua declaration converter defines the root handle class before derived handle types and rejects reserved declaration keywords such as local as type names.

Embedded LuaLS behavior

The embedded server automatically loads these project libraries when present:

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

One window-wide client handles multiple workspace folders and standalone Lua files. To avoid duplicate diagnostics and command collisions, the embedded server defers when an external Sumneko/LuaLS extension or another active Lua server already owns LuaLS commands. Disable the external Lua extension to use the embedded server, or set warcraftLua.languageServer.disableWhenExternalLuaServerDetected to false to override detection.

Main commands

Default new-project settings

New projects include the recommended Warcraft III Lua and editor settings:

{
  "json.maxItemsComputed": 30000,
  "Lua.runtime.version": "Lua 5.3",
  "Lua.workspace.preloadFileSize": 2000,
  "Lua.workspace.maxPreload": 1000,
  "Lua.hint.enable": true,
  "Lua.type.weakUnionCheck": true,
  "Lua.type.weakNilCheck": true,
  "Lua.diagnostics.disable": [
    "lowercase-global",
    "inject-field"
  ],
  "editor.parameterHints.enabled": true,
  "workbench.editor.enablePreview": false,
  "editor.semanticHighlighting.enabled": true,
  "warcraftLua.warcraftPath": "",
  "warcraftLua.sources": ["src/**/*.lua"],
  "warcraftLua.build.output": "_build/compiledwar3map.lua",
  "warcraftLua.build.cacheDirectory": "_build/cache",
  "warcraftLua.objectEditing.outputDirectory": "_build/cache/objectdata",
  "warcraftLua.objectEditing.generatedIds": "_build/cache/objectdata/object_ids.lua",
  "warcraftLua.build.extractMapScript": true,
  "warcraftLua.build.convertJassToLua": true,
  "warcraftLua.cascTextures": false,
  "warcraftLua.languageServer.enabled": true,
  "warcraftLua.languageServer.autoLibrary": true
}

Older project settings are migrated when possible. Compile-time source selection is annotation-based, and extracted map scripts use fixed names in the root of src.

Licenses and trademarks

Warcraft Lua Toolkit's own license is in LICENSE.md. Third-party licenses and attribution are documented in THIRD_PARTY_NOTICES.md.

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