GMP Classic Lua Tools

A VS Code extension for writing GMP Classic Lua resources with API completions, hover docs, side-aware diagnostics, TOML config help, and LuaLS stub generation.

What it does

GMP Classic Lua Tools is focused on editing support for Gothic Multiplayer Classic resources. It does not start servers, manage GothicStarter entries, or try to replace a full Lua language server.

The extension currently provides:

• GMP Classic API completions, hover documentation, signature help, document links, and optional inlay hints for Lua files.
• Side-aware checks for server/client/shared API usage.
• A few GMP-specific diagnostics for common mistakes.
• TOML assistance for GMP Classic server configuration files.
• Optional Lua Language Server stub generation.
• Workspace scanning for basic GMP resource layout information.

API data is fetched from:

https://gothic-multiplayer-classic.github.io/docs/api.json

If the remote API cannot be loaded, the extension falls back to bundled API data.

Lua API support

Lua support is built around the GMP Classic API index. The extension uses that API data for:

• global function and constant completions;
• member completions for known classes/owners;
• hover cards with declaration headers, type, side, category, documentation descriptions, parameters, returns, notes, examples, deprecation info, and a documentation link;
• signature help for known calls;
• links from known symbols to the online GMP Classic documentation;
• generated LuaLS annotation stubs.

Documentation links follow the current GMP Classic docs layout, such as:

• client-functions/<category>/<name>/
• server-functions/<category>/<name>/
• shared-functions/<category>/<name>/
• client-events/<category>/<name>/
• server-events/<category>/<name>/
• <side>-classes/<category>/<ClassName>/
• <side>-globals/<category>/<name>/
• <side>-constants/<category-or-constant-group>/

Side detection

The extension detects whether a Lua file is server, client, shared, or unknown mainly from its path. Paths containing folders like server, client, or shared are used as hints.

You can also set or clear a side override for the active file from the command palette:

• GMP: Set File Side
• GMP: Clear File Side Override

Side detection is intentionally simple. If your project uses unusual folder names, you may need an override.

Diagnostics

GMP diagnostics can report:

• server/client side mismatches;
• unknown GMP event names in addEventHandler(...) calls;
• deprecated API usage;
• potentially unsupported nested resource script layouts;
• argument-count mismatches, if you enable that check manually.

Argument-count diagnostics are disabled by default because simple argument counting is noisy for Lua calls that use tables, nested calls, strings with commas, optional arguments, or overload-like GMP API patterns.

Useful settings:

{
  "gmpClassic.diagnostics.sideMismatch": "warning",
  "gmpClassic.diagnostics.unknownEvents": "warning",
  "gmpClassic.diagnostics.deprecatedApi": "warning",
  "gmpClassic.diagnostics.resourceLayout": "information",
  "gmpClassic.diagnostics.argumentCount": "disabled"
}

Each severity setting accepts error, warning, information, or disabled.

TOML configuration help

TOML support follows the official GMP Classic server configuration documentation:

https://gothic-multiplayer-classic.github.io/docs/server-manual/Configuration/

The docs state that the server config uses TOML and that all settings are optional unless stated otherwise. The extension provides completions, hovers, duplicate-key diagnostics, basic type checks, log_level enum validation, and lightweight .ZEN path help for the documented server config keys.

Known keys include:

• basic server information: name, port, public, slots, admin_passwd, auth_key, seconds_per_game_minute;
• server identity: server_identity_seed;
• gameplay: map, map_md5, allow_modification, hide_map, respawn_time_seconds;
• logging: log_file, log_to_stdout, log_level;
• performance: tick_rate_ms;
• process management: daemon.

Unknown TOML keys are not treated as errors. This keeps the extension usable with local comments, custom tooling, or future server config additions.

Lua Language Server integration

LuaLS is separate from this extension. GMP Classic Lua Tools provides GMP-aware completions, hovers, links, and diagnostics, but LuaLS may still warn about GMP globals or call shapes unless it is configured.

If LuaLS diagnostics are noisy, add something like this to .vscode/settings.json:

{
  "Lua.diagnostics.disable": [
    "undefined-global",
    "missing-parameter",
    "redundant-parameter"
  ],
  "gmpClassic.diagnostics.argumentCount": "disabled"
}

Another option is to run GMP: Generate LuaLS Stub and add the generated stub to your LuaLS workspace/library setup.

Inline parameter-name hints are available but disabled by default. Enable them with:

{
  "gmpClassic.inlayHints.parameters": true
}

Commands

• GMP: Refresh API Docs — fetch the API JSON again and rebuild the local index.
• GMP: Show API Cache Status — show the current API source and cache timestamp.
• GMP: Open Documentation for Symbol — open docs for the symbol under the cursor.
• GMP: Set File Side — override the active file as server, client, shared, or unknown.
• GMP: Clear File Side Override — remove the active file's side override.
• GMP: Scan Workspace — scan Lua files and report basic resource layout information.
• GMP: Generate LuaLS Stub — generate Lua annotations from the GMP API index.
• GMP: Configure API Source — set a custom API JSON URL for the workspace.
• GMP: Show Resource Report — open the workspace scan report as JSON.

Settings

All extension settings live under gmpClassic.*.

Common settings:

• gmpClassic.api.url
• gmpClassic.api.autoRefresh
• gmpClassic.api.cacheTtlHours
• gmpClassic.diagnostics.enabled
• gmpClassic.diagnostics.sideMismatch
• gmpClassic.diagnostics.argumentCount
• gmpClassic.diagnostics.unknownEvents
• gmpClassic.diagnostics.deprecatedApi
• gmpClassic.diagnostics.resourceLayout
• gmpClassic.inlayHints.enabled
• gmpClassic.inlayHints.parameters
• gmpClassic.inlayHints.returns
• gmpClassic.luaLs.generateStub
• gmpClassic.luaLs.autoConfigureWorkspace
• gmpClassic.toml.enabled

Known limitations

• Some diagnostics are heuristic and intentionally conservative.
• Lua syntax and type analysis are not a full Lua parser.
• Argument-count diagnostics are available but disabled by default because they can be noisy.
• LuaLS may still produce its own diagnostics unless configured separately.
• Side detection is mainly path-based.
• TOML checks focus on the documented GMP Classic server configuration keys and avoid flagging unknown keys.