LuckyParser

LuckyParser revives Luck as an indentation-based Warcraft III language and ships it with a VS Code development environment. Luck source compiles to clean, readable JASS. A project keeps all map source in src/ and may freely mix Luck, JASS, vJASS, Zinc and cJASS.

library Example:
    public nothing Hello(integer count = 3):
        local integer i = 0

        while i < count:
            print("Hello " + i)
            i++

    onInit:
        Hello(count = 2)

Generated JASS:

function Hello takes integer count returns nothing
    local integer i

    set i = 0
    loop
        exitwhen not (i < count)
        call BJDebugMsg("Hello " + I2S(i))
        set i = i + 1
    endloop
endfunction

Install

Install LuckyParser-0.3.0.vsix from Extensions → … → Install from VSIX, or open this repository as an extension-development workspace and press F5.

The extension has no npm runtime dependencies. Node.js is only needed for the standalone lucky CLI and repository tests.

Create a map project

Run Lucky: Create Warcraft III Project. The generator creates:

LuckyMap/
  src/
    main.luck
    interop.j
    examples/
      functions.luck
      control-flow.luck
      globals.luck
      variables.luck
      structs.luck
      namespaces.luck
      initialization.luck
      imports.luck
    showcase/
      ide-errors.luck
      reserved-syntax.luck
      README.md
  map/
    ExampleMap.w3x
  build/
  lucky.json

The starter project is now a comprehensive language/IDE tour. The files under src/examples/ cover every currently lowered Luck feature, src/interop.j demonstrates cross-language calls and language islands, and src/showcase/ contains deliberately broken/future syntax excluded from builds. A fresh untouched project still compiles successfully.

During project creation it downloads WurstScript's ExampleMap.w3x into map/. A compatible mpqcli build is installed once into VS Code's LuckyParser global extension storage, outside the workspace. Existing .lucky/tools/mpqcli installs from 0.1.0/0.1.1 are migrated automatically and removed from the project.

Automatic mpqcli installation targets platforms with matching upstream release assets. You can also set tools.mpqcli to an explicit executable.

The downloads are not embedded in the extension and remain governed by their respective licenses.

Imports

New projects use explicit imports:

import "examples/functions.luck"
from "examples/structs.luck" import Missile, CreateDemoMissile

Every supported source file under src/ is still compiled exactly once. Imports do not paste files or decide build inclusion; they define which public declarations are visible to a Luck file. Paths without ./ are relative to src/; ./ and ../ are relative to the importing source file. Imports can target Luck, JASS, vJASS, Zinc and cJASS files.

New projects set "imports": { "mode": "explicit" } in lucky.json. Existing projects remain in legacy project mode unless they opt in, preserving pre-0.3 project-wide visibility.

The IDE provides import-path completion, public-symbol completion after from ... import, clickable import paths, auto-import completion, import Quick Fixes, and Organize Imports.

Mixed languages

File extensions select the default language:

Any file can switch languages:

//! language jass
function ExistingJass takes nothing returns nothing
endfunction

//! language luck
nothing UseExistingJass():
    ExistingJass()

Public Luck functions retain their source names, so JASS-family code can call them. Luck can call foreign functions directly. The unified index provides cross-language completion, definition, reference and rename operations. Luck receives parser-backed semantic analysis; JASS-family analysis is a practical symbol index rather than a complete semantic compiler front end.

Build commands

• Lucky: Compile Sources — writes readable JASS to build/war3map.j.
• Lucky: Build and Compile Map — copies the input map and injects the compiled script.
• Lucky: Build and Run Map — builds, auto-detects Warcraft III, then launches the map.
• Lucky: Show Generated JASS — compiles and opens the output.
• Lucky: Install/Update MPQ Tool — installs mpqcli in global extension storage.
• Lucky: Detect Warcraft III — shows the automatically detected executable.
• Lucky: Reindex Workspace — rebuilds the cross-language symbol index.

Right-click any .w3x or .w3m in Explorer for Build and compile map and Build and run map. For arbitrary selected maps, the built copy is written to the configured build directory using the selected map's filename.

CLI equivalents:

node src/cli.js create MyMap
node src/cli.js compile --workspace MyMap
node src/cli.js build --workspace MyMap
node src/cli.js run --workspace MyMap
node src/cli.js doctor --workspace MyMap

Warcraft III detection and run

On Windows, LuckyParser follows WurstScript's run-map model. It checks Blizzard registry values and common Battle.net install roots, but deliberately prefers the actual Reforged game binary at _retail_/x86_64/Warcraft III.exe over a legacy root Warcraft III.exe launcher/stub. Cached paths from older LuckyParser releases are re-resolved automatically.

For a modern installation, the built map is copied to Documents/Warcraft III/Maps/Test/LuckyRunMap.w3x (using the Windows Documents known-folder registry value when available) and the game binary is launched directly with -launch -windowmode windowedfullscreen -loadfile <run-map>. LuckyParser no longer uses PowerShell or cmd.exe start fallbacks. If Windows rejects the actual game binary, the original spawn code/errno/syscall and resolved executable remain visible in the LuckyParser Output channel. Like Wurst, LuckyParser then offers to choose another Warcraft III installation folder, resolves the game binary inside it, and retries.

A detected executable is cached globally. If auto-detection fails, Build and Run Map can accept either the Warcraft III installation folder or a specific executable. You can override detection with the lucky.warcraft3.executable VS Code setting or tools.warcraft3 in lucky.json. Additional arguments can be supplied through tools.warcraft3Args.

External compiler interoperability

Pure Luck and JASS projects need no additional language compiler. Configure these tools in lucky.json when the corresponding source is present:

• vJASS/Zinc: JassHelper.
• cJASS: a cJASS compiler and argument template.
• Final validation: pjass, optional.

The pipeline is:

Luck -> readable JASS
cJASS -> configured cJASS compiler -> JASS
JASS + Luck JASS + vJASS + Zinc -> optional JassHelper -> plain JASS
plain JASS -> consolidate one globals block + dependency-order functions
normalized JASS + original map script -> copied map -> mpqcli injection
built map -> Warcraft Maps/Test run copy -> resolved game binary -> direct -launch -windowmode windowedfullscreen -loadfile

The final plain-JASS pass enforces Warcraft/JASS ordering rules: user-defined callees are emitted before their callers and all contributed global declarations are merged into one globals ... endglobals section.

IDE capabilities

Version 0.3 builds on the scoped semantic model rather than relying on global symbol-name matching. Luck receives parser-backed semantic analysis and the JASS-family languages receive structural scope/call indexing. The VS Code integration now provides:

• scope-aware completion for locals, parameters, globals, native functions and user types;
• explicit-import visibility, source-path completion, exported-symbol completion and auto-import edits;
• member completion/resolution from the qualifier type (missile.hit, unit.id);
• named-argument completion and signature help;
• hover with inferred/declared types, defaults, documentation and source location;
• go to declaration/definition/type-definition/implementation;
• scope-correct references, document highlights and rename;
• call hierarchy and type hierarchy;
• semantic diagnostics for duplicate locals, unresolved callables, argument counts, named arguments and basic type mismatches;
• inferred-type and parameter-name inlay hints;
• semantic tokens for declarations and references;
• hierarchical document outline, workspace symbols and breadcrumbs;
• formatting, range formatting, on-type indentation, folding and smart selection;
• quick fixes for unresolved functions/imports plus a positional-to-named-arguments refactor and Organize Imports;
• clickable import paths plus per-function reference CodeLens and language-tour/compile/build/run/generated-JASS CodeLens;
• external file watchers so the index updates when source changes outside VS Code;
• snippets and JSON schema completion/validation for lucky.json.

Configured common.j and Blizzard.j files are added to the workspace index, so standard/native APIs can be navigated from the user's own Warcraft script files.

Compiler status

Version 0.3 is a working compiler/IDE foundation, not a false claim that every idea from the 2011 LuckyParser discussion is already implemented. It lowers the core language, explicit imports, named/default arguments, structured control flow, initializers, and array-backed structs. Classes, closures, compile-time procedures, hooks, extensions and custom events are reserved and indexed, but currently produce explicit compiler warnings rather than incorrect generated code.

See:

• docs/LUCK_LANGUAGE.md
• docs/IDE_FEATURES.md
• docs/TOOLCHAIN.md
• docs/ARCHITECTURE.md

Verification

npm test
node src/cli.js doctor --self

License

LuckyParser is MIT licensed. Third-party integration details are in NOTICE.md.