IE Lua Language Server

Professional language support for Enhanced Edition Infinity Engine Lua and .menu files.

This repository ships:

• A Visual Studio Code extension.
• A stdio-capable Language Server Protocol server for editors such as Kate.

This extension targets:

• Lua 5.2 with the base globals and the bit32, debug, math, string, and table libraries.
• LuaJIT compatibility mode.
• Infinity Engine .lua files.
• Infinity Engine .menu files with embedded Lua regions.

Features

• Completion, hover, signature help, go to definition, find references, same-file rename, diagnostics, formatting, document symbols, workspace symbols, semantic tokens, and folding.
• Scope-aware Lua analysis backed by a parser plus tolerant fallback scanning for incomplete buffers.
• Embedded Lua analysis in .menu files for backtick chunks, lua "..." expressions, action/open/close/escape blocks, and enabled/clickable expressions.
• Source-driven API data from official sources only, with immutable upstream provenance.
• Full EE Game Lua and EEex function completion, hover, signature help, and source definitions, including namespace members, colon methods, typed instance aliases, parameter defaults, return values, warnings, notes, examples, and tables.
• Full EE Game Structures (x64) layout metadata: structure and field completion, annotation-aware member resolution, chained field hover, exact source definitions, types, offsets, and byte sizes.

Screenshots

The screenshots below were captured at 1440x900 from a real Visual Studio Code Extension Development Host using non-proprietary fixture snippets and Visual Studio Code's built-in Monokai theme. The reproducible capture steps are documented in docs/screenshots/README.md.

View Visual Studio Code screenshots

EEex Function Completion

EEex Hover Documentation

Signature Help

EE Game Structures (x64) Member Completion

Embedded .menu Diagnostics

Document Symbols

Runtime Dependencies

Visual Studio Code users do not need to install luaparse, Node.js, npm, or any other npm package to use validation. The published Marketplace extension and generated VSIX bundle the language server runtime dependencies.

Kate users do not need luaparse or npm packages, but they do need Node.js 24 LTS available on PATH because Kate starts the bundled server as an external stdio process.

Using with Visual Studio Code

For Windows, macOS, and Linux:

1. Install IE Lua Language Server from the Visual Studio Code Marketplace, or install the generated .vsix.
2. Reload Visual Studio Code if prompted.
3. Open an Infinity Engine .lua or .menu file.

Settings can be changed from the Visual Studio Code Settings UI or settings.json:

{
  "ieLua.dialect": "lua52",
  "ieLua.validation.mode": "save",
  "ieLua.validation.debounceMs": 300,
  "ieLua.diagnostics.unknownGlobals": "off"
}

The extension activates automatically for .lua and .menu files and exposes the commands listed below.

Using with Kate

Kate integration uses the same bundled LSP server over stdin/stdout. This is useful when you want completion, hover, diagnostics, definitions, references, symbols, and formatting outside Visual Studio Code.

Requirements:

• Kate with the LSP Client plugin enabled.
• Node.js 24 LTS on PATH.
• A built checkout or unpacked VSIX containing dist/server/server.js and resources/api/api-index.json.

Download and unpack a verified VSIX from the CI workflow artifacts or GitHub Releases. Source builds run exclusively in GitHub Actions.

Install the optional .menu syntax definition so Kate can map *.menu files to the ie-menu LSP language id:

install -D editors/kate/syntax/ie-menu.xml ~/.local/share/org.kde.syntax-highlighting/syntax/ie-menu.xml

For Flatpak, Snap, Windows, or custom KDE paths, use the syntax-definition directory reported by Kate/KDE. KDE documents the generic user location as org.kde.syntax-highlighting/syntax/ under a qtpaths --paths GenericDataLocation directory, and the Windows user location as %USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax.

Then open Settings -> Configure Kate -> Plugins, enable LSP Client, and add this to LSP Client -> User Server Settings. Replace /absolute/path/to/ie-lua-language-server with this checkout or unpacked VSIX extension directory:

{
  "servers": {
    "ie-lua": {
      "command": [
        "node",
        "/absolute/path/to/ie-lua-language-server/dist/server/server.js",
        "--stdio"
      ],
      "rootIndicationFileNames": [".git"],
      "url": "https://github.com/4Luke4/ie-lua-language-server",
      "highlightingModeRegex": "^Lua$",
      "settings": {
        "ieLua": {
          "validation": {
            "mode": "save",
            "debounceMs": 300
          }
        }
      }
    },
    "ie-menu": {
      "command": [
        "node",
        "/absolute/path/to/ie-lua-language-server/dist/server/server.js",
        "--stdio"
      ],
      "rootIndicationFileNames": [".git"],
      "url": "https://github.com/4Luke4/ie-lua-language-server",
      "highlightingModeRegex": "^IE Menu$",
      "settings": {
        "ieLua": {
          "validation": {
            "mode": "save",
            "debounceMs": 300
          }
        }
      }
    }
  }
}

The same JSON is available as editors/kate/lsp-client.example.json.

Kate's LSP Client plugin communicates with configured servers over stdin/stdout and uses highlightingModeRegex to map Kate highlighting modes to server entries. See the official Kate LSP Client documentation: https://docs.kde.org/stable5/en/kate/kate/kate-application-plugin-lspclient.html.

Node.js and npm are only required when building/testing this repository or when launching the stdio server from a non-VS Code editor.

Validation Modes

ieLua.validation.mode controls when diagnostics run:

• manual: only through IE Lua: Validate Document or IE Lua: Validate Workspace.
• save: on save. This is the default.
• type: while editing, using the configured debounce delay.
• saveAndType: on save and while editing, using the configured debounce delay for edits.

ieLua.validation.debounceMs controls the type-validation delay in milliseconds and defaults to 300. Lower values make diagnostics appear sooner but may increase CPU usage during rapid edits. Higher values coalesce more edits and reduce repeated validation work, but diagnostics take longer to appear.

Commands

• IE Lua: Validate Document
• IE Lua: Validate Workspace
• IE Lua: Reload API Data
• IE Lua: Show API Source
• IE Lua: Open Server Log

Development

Node.js 24 LTS and npm are required. This repository is structured as a TypeScript npm workspace.

Open a draft PR to run CI. Compilation, formatting, tests, packaging, and API generation run exclusively in GitHub Actions. Download verified VSIX files and maintenance patches from the run. The language server runs as a separate process over IPC from the VS Code extension client.

The docs-ingestion step fetches official Lua 5.2, LuaJIT, EE Game Lua Function, and EEex Function documentation at build time and stores the source wording as Markdown for hover, completion, and signature-help previews. RST presentation is converted to equivalent VS Code Markdown while paragraphs, emphasis, lists, tables, admonitions, links, code blocks, and visible punctuation are retained.

Generated API data uses a schema-v3 manifest for auditability. resources/api/api-index.json retains the six logical source sections and lists every data file with its symbol count and, for EE/EEex data, its exact upstream category path. The three EEex-backed sources mirror the top-level categories in the pinned upstream toctrees, including explicit empty shards:

• resources/api/sections/ee-game-lua-functions/
• resources/api/sections/eeex-functions/
• resources/api/sections/ee-game-structures-x64/

Lua 5.2, LuaJIT, and optional local utility metadata remain single-file sections under resources/api/sections/. Category filenames are derived deterministically from upstream names rather than maintained as a hardcoded list.

The Actions ingestion job sets IE_LUA_FETCH_EEEX=1 to refresh EEex metadata. The generator resolves the latest dev revision by default; set IE_LUA_EEEX_COMMIT to a full commit SHA for a reproducible run. Function ingestion discovers every standalone EE Game function page, every game function defined directly in a category index, and every EEex_* function anchor from the pinned tree. It rejects incomplete or malformed input and records exact commit-and-line provenance. Structure help includes names, fields, types, offsets, byte sizes, upstream narrative, and pinned source lines.

The scheduled Update EEex API data workflow checks the upstream repository daily. When its revision changes, the workflow regenerates and verifies the API data on a dedicated branch and opens a pull request for review; it never executes upstream code.

Local game files under samples/ are ignored because they may contain proprietary official content. Set IE_LUA_SCAN_LOCAL_UTIL=1 only when you intentionally want an ingestion run in an approved Actions environment to derive EE Utility Function metadata from an untracked samples/util.lua file.

Release Process

Stable and prerelease publishing instructions are maintained in docs/release.md.

CI audits both stable and prerelease VSIX files; select the intended channel in the Release workflow. The prerelease path uses VS Code's --pre-release flag; do not put a SemVer prerelease suffix in package.json.version.

Documentation Provenance

The shipped API index is generated from these official sources:

• EE Game Lua Functions: https://github.com/Bubb13/EEex-Docs/tree/b4d0acd776f5d3b8337afbd038d6128efce51cfd/source/EE%20Game%20Lua%20Functions
• EEex Functions: https://github.com/Bubb13/EEex-Docs/tree/b4d0acd776f5d3b8337afbd038d6128efce51cfd/source/EEex%20Functions
• EE Game Structures (x64): https://github.com/Bubb13/EEex-Docs/tree/b4d0acd776f5d3b8337afbd038d6128efce51cfd/source/EE%20Game%20Structures%20(x64)
• Lua 5.2: https://www.lua.org/manual/5.2/
• LuaJIT: https://luajit.org/
• EE Utility Functions: local, untracked samples/util.lua only when explicitly enabled for docs ingestion.

Bundled third-party documentation attribution is recorded in THIRD_PARTY_NOTICES.md.

License

This project is proprietary software. See LICENSE.md.