Skip to content

language-server.md

Latest commit

 

History

History
172 lines (140 loc) · 7.25 KB

language-server.md

File metadata and controls

172 lines (140 loc) · 7.25 KB
Raw

Standalone language server

Use zerosyntax-lsp with any editor that supports the Language Server Protocol over stdio.

Install

  1. Download the Windows x64 or Linux x64 server archive from the latest release.
  2. Verify the archive against SHA256SUMS.txt from the same release.
  3. Extract the archive and put zerosyntax-lsp (or zerosyntax-lsp.exe) on your PATH, or configure its absolute path in your editor.
  4. Register the server for the Generals/Zero Hour .ini files in your project.

The server writes protocol messages to stdout, so clients must launch it using stdio rather than a TCP port.

Command-line diagnostics

Use the check subcommand to run the same parser, schema, workspace index, and diagnostics without an LSP client:

zerosyntax-lsp check Data/INI
zerosyntax-lsp check map.ini --base-root "C:/Games/Zero Hour"
zerosyntax-lsp check --fail-on warning Data/INI
zerosyntax-lsp check --json --stdin-filename map.ini - < generated.ini

The positional targets are .ini files, recursively scanned directories, or one - for stdin. At least one target is required. All selected targets are indexed together before diagnostics run, so references between them resolve. Overlapping targets are checked once.

--base-root is repeatable and accepts directories or .big archives containing base/mod INIs and game assets. Base roots participate in reference, model, bone, audio, and texture checks but do not emit diagnostics themselves. For stdin, --stdin-filename supplies the displayed/indexed name and enables map.ini or solo.ini override semantics; it defaults to <stdin>.

Human output uses compiler-style records followed by a summary:

Data/INI/Weapon.ini:12:14: error[bad-number]: expected an integer, found `lots`
1 error(s), 0 warning(s), 0 hint(s)

--json writes a stable array to stdout. Each record has file, range, severity, code, and message. Range lines and Unicode-scalar columns are 1-based; the end position is exclusive.

[{"file":"map.ini","range":{"start":{"line":2,"column":14},"end":{"line":2,"column":18}},"severity":"error","code":"bad-number","message":"expected an integer, found `lots`"}]

Exit codes are:

  • 0: no diagnostic meets the failure threshold.
  • 1: at least one diagnostic meets it.
  • 2: invalid arguments, inaccessible/unsupported inputs, or an internal failure.

The default threshold is error. Select --fail-on warning or --fail-on hint for stricter CI. Diagnostics are still written to stdout when the command exits 1; operational errors go to stderr.

Client configuration

Configure your LSP client with:

Option Value
Command zerosyntax-lsp
Transport stdio
Files Zero Hour .ini files
Workspace root Your map or mod directory

The server indexes INI files under each workspace folder. Open the whole project to enable cross-file completion, definitions, references, rename, and workspace symbols.

Initialization options

{
  "format": { "enable": false },
  "preview": { "imageWidth": 160, "zoomPercent": 100 },
  "schemaPath": "C:/Mods/MyMod/schema.json",
  "analysis": {
    "modelMemberStrictness": "compatible",
    "allowPercentagesWithoutSign": false,
    "mapOrderingDiagnostics": true,
    "debounceMs": 250
  },
  "baseIniRoots": [
    "C:/Games/Zero Hour",
    "C:/Mods/MyMod/Data/INI",
    "C:/Mods/MyMod.big"
  ]
}
  • format.enable controls document formatting. It defaults to false and is dynamically registered when the client supports it.
  • preview.imageWidth controls the displayed W3D thumbnail width in pixels (80–640, default 160). The client still owns the outer details-pane bounds.
  • preview.zoomPercent controls the default W3D camera zoom (25–400, default 100). Both preview settings apply to newly resolved completions without restarting the server.
  • schemaPath points to a custom schema JSON file. Unreadable or invalid files produce a warning and fall back to the built-in schema.
  • analysis.modelMemberStrictness is off, compatible (member exists in any applicable model), or strict (member exists in every applicable model). It defaults to compatible.
  • analysis.allowPercentagesWithoutSign accepts engine-compatible bare numbers in percentage fields. It defaults to false, requiring the trailing %.
  • analysis.mapOrderingDiagnostics controls source-backed forward-order warnings in map.ini and solo.ini. It defaults to true.
  • analysis.debounceMs waits this many milliseconds after the latest edit before refreshing whole-document indexes and diagnostics. Parsing and completions remain immediate. It defaults to 250; valid values are 0–5000, where 0 refreshes as soon as possible.
  • baseIniRoots accepts directories and .big archives containing base game or mod INI files and game assets. WAV/MP3 filenames and TGA/DDS textures power asset completion and warnings; DDS-only textures complete as the canonical INI spelling stem.tga. Audio and texture warnings activate independently only after that asset kind is indexed. Supply every loaded game/mod root to avoid warnings caused by a partial asset index. INI definitions are treated as loaded before map.ini and solo.ini. Definitions in loose files open through native file: URIs. Definitions inside .big archives open as read-only virtual INIs with navigation and inspection support when the client selects the big URI scheme.

The same settings can be sent at runtime through workspace/didChangeConfiguration, either directly or nested under {"zerosyntax": ...}. Analysis, debounce, and formatting changes apply immediately. Schema and base-root changes rebuild the complete index, keep filesystem scanning on a blocking worker, and report indexing progress. Identical settings are ignored.

Clients without dynamic formatting registration keep their startup formatting capability. If such a client starts with formatting disabled, it must restart to expose formatting; all other settings still hot-reload. Only selecting a different server executable inherently requires a new process.

Supported LSP features

ZeroSyntax supports incremental document sync, diagnostics, completion, hover, go to definition, references, rename, semantic tokens, document and workspace symbols, folding ranges, quick fixes, and optional document formatting.

W3D model completion items support completionItem/resolve. Clients that render Markdown completion documentation can show a lazy textured thumbnail for the active Model = suggestion. The initial completion list contains no image data. Previews use indexed loose or BIG-contained W3D/TGA/DDS assets and cover mesh geometry, base materials, HLOD composition, and hierarchy bind pose. preview.imageWidth changes its displayed size and preview.zoomPercent changes the model framing. Malformed or unsupported assets leave completion functional and show a short preview-unavailable message. Rebuild the asset index or reload the server after changing binary assets.

Build from source

Install Rust 1.75 or newer, clone the repository, and run:

cargo build --locked --release -p zerosyntax-server

The binary is written to target/release/zerosyntax-lsp (.exe on Windows).