Configuration overview - GLua Language Server

Overview

Configure language server behavior in a .gluarc.json file at your workspace root. The file has full JSON schema support, so your editor validates settings and provides completions. GLuaLS provides two ways to manage configuration:

Settings panel (recommended): an interactive VS Code UI that edits .gluarc.json for you
Manual editing: edit .gluarc.json with full IDE validation

Both methods write to the same file and stay in sync.

Settings panel (recommended)

The GLua Settings panel lets you configure GLuaLS without touching JSON. Changes write directly to .gluarc.json.

Opening the panel

You can open the settings panel in three ways:

Command Palette (Ctrl+Shift+P) → GLua: Open Settings
Click the GLuaLS item in the status bar
Right-click any .gluarc.json file in the Explorer → Open GLua Settings

The panel opens as a tab in your editor. In a multi-root workspace, you’ll be prompted to choose which workspace folder to configure.

Panel layout

The settings panel uses collapsible sections that match the .gluarc.json structure:

Section	What it configures
GMod	Realm detection, scripted classes, network analysis, VGUI hints
Diagnostics	Enable/disable individual diagnostic codes, set severity levels
Completion	Autocomplete behavior, call snippets, postfix triggers
Formatting	Formatter preset, style overrides
Hints	Inlay hint types and thresholds
Workspace	Library paths, ignore patterns, module maps
Runtime	Non-standard Lua symbols, require-like functions

Editing settings

Every control maps directly to a .gluarc.json property:

Toggles: boolean options
Dropdowns: enum options (e.g., severity levels)
Text fields: string and number options
Tables: array and map options (e.g., file param defaults, scripted class definitions)

Changes are saved to .gluarc.json after a short debounce (5 seconds by default). You can also click Save now at any time.

If you want to inspect the generated JSON, open .gluarc.json directly. You can edit both the settings panel and the JSON file, and they stay in sync.

Auto-save behavior

Auto-save is off by default. Click Save after editing. To change auto-save behavior, toggle Auto-save settings in the panel header or set gluals.gmod.settingsAutoSave in your VS Code settings.

Manual configuration (.gluarc.json)

Creating your config

Create a .gluarc.json file at the root of your workspace:

Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.

.gluarc.json

{
  "$schema": "https://raw.githubusercontent.com/Pollux12/gmod-glua-ls/main/crates/glua_code_analysis/resources/schema.json"
}

The $schema property enables IDE validation and autocomplete for the file itself. The settings panel can also generate a starter configuration. Open GLua: Open Settings, then click Edit in JSON at the bottom of the panel.

Recommended starter config

This configuration is suitable for most GMod addon projects:

.gluarc.json

{
  "$schema": "https://raw.githubusercontent.com/Pollux12/gmod-glua-ls/main/crates/glua_code_analysis/resources/schema.json",
  "diagnostics": {
    "enable": true,
    "diagnosticInterval": 500,
    "severity": {
      "unused": "hint",
      "undefined-field": "information",
      "redundant-return": "hint",
      "redundant-return-value": "hint",
      "param-type-mismatch": "information",
      "missing-fields": "information",
      "assign-type-mismatch": "information",
      "return-type-mismatch": "information",
      "missing-parameter": "information",
      "cast-type-mismatch": "information",
      "need-check-nil": "hint"
    }
  }
}

Config file priority

When a workspace has multiple config files, GLuaLS uses this priority order (highest first):

.gluarc.json
.luarc.json
.emmyrc.json
.emmyrc.lua

.gluarc.json is exclusive. If it exists, GLuaLS ignores all other config files.

Configuration reference

The config file is split into top-level sections. Refer to each section’s page for the full option reference, including both VSCode and .gluarc.json equivalents:

GMod settings

GMod-specific analysis: realms, network, scripted classes, hooks, VGUI

Diagnostics

Enable, disable, and tune severity of all diagnostic codes

Completion

Autocomplete behavior, call snippets, postfix trigger, auto-require

Formatting

Built-in presets, style overrides, external formatter configuration

Workspace

Library paths, ignore patterns, module map, encoding

Hints & Hover

Inlay hints, inline values, hover, semantic tokens, signature help

Runtime & Strict

Non-standard symbols, strict type checking, special functions

Annotations management

Auto-download GMod wiki annotations, custom annotation paths

VSCode extension settings

Some settings are specific to the VSCode extension and are not part of .gluarc.json. These control extension-level behavior like the debugger, MCP server, UI preferences, and annotation downloads.

Setting	Type	Default	Description
`gluals.gmod.autoLoadAnnotations`	`boolean`	`true`	Auto-download and load GMod wiki annotations (workspace default is `null` to use this setting)
`gluals.gmod.settingsAutoSave`	`boolean`	`false`	Auto-save settings panel changes to `.gluarc.json`
`gluals.gmod.debugRealm`	`string`	`"server"`	Default realm for debug execution (`server`, `client`, `shared`)
`gluals.gmod.debugger.autoUpdateRdb`	`boolean`	`true`	Prompt to update `gm_rdb` on version mismatch
`gluals.gmod.debugger.autoUpdateClientRdb`	`boolean`	`true`	Prompt to update client debug module on mismatch
`gluals.gmod.mcp.enabled`	`boolean`	`true`	Enable MCP server for AI integration
`gluals.gmod.mcp.authToken`	`string`	`""`	MCP auth token (empty = auto-generate local token)
`gluals.gmod.mcp.port`	`integer`	`0`	MCP server port (0 = random ephemeral)
`gluals.gmod.mcp.rateLimitPerMinute`	`integer`	`60`	Max MCP requests per minute per client
`gluals.gmod.templatePath`	`string`	`null`	Path to custom scaffolding templates
`gluals.gmod.network.codeLensEnabled`	`boolean`	`true`	Network code lens
`gluals.gmod.vgui.codeLensEnabled`	`boolean`	`true`	VGUI panel code lens
`gluals.gmod.vgui.inlayHintEnabled`	`boolean`	`false`	VGUI panel inlay hints
`gluals.ls.executablePath`	`string`	`""`	Override language server binary path
`gluals.ls.debugPort`	`integer`	`null`	Connect to existing language server on this port
`gluals.ls.startParameters`	`array`	`[]`	Additional language server arguments
`gluals.ls.globalConfigPath`	`string`	`""`	Path to global `.emmyrc.json`
`gluals.language.completeAnnotation`	`boolean`	`true`	Auto-insert `---` on line break after comment
`gluals.decorations.globals`	`boolean`	`false`	Underline global variables
`gluals.decorations.mutableLocals`	`boolean`	`false`	Underline mutable local variables
`gluals.decorations.mutableParams`	`boolean`	`false`	Underline mutable function parameters
`gluals.decorations.readonlyLocals`	`boolean`	`false`	Underline readonly local variables
`gluals.decorations.readonlyParams`	`boolean`	`false`	Underline readonly function parameters
`gluals.workspace.workspaceRoots`	`array`	`[]`	Additional workspace roots for file resolution
`gluals.inlineValues.enable`	`boolean`	`null`	Show inline values during debug
`gluals.semanticTokens.enable`	`boolean`	`null`	Enable semantic tokens

Settings in .gluarc.json always take precedence over VS Code workspace settings for analysis behavior.

​Overview

​Settings panel (recommended)

​Opening the panel

​Panel layout

​Editing settings

​Auto-save behavior

​Manual configuration (.gluarc.json)

​Creating your config

​Recommended starter config

​Config file priority

​Configuration reference

GMod settings

Diagnostics

Completion

Formatting

Workspace

Hints & Hover

Runtime & Strict

Annotations management

​VSCode extension settings

Overview

Settings panel (recommended)

Opening the panel

Panel layout

Editing settings

Auto-save behavior

Manual configuration (.gluarc.json)

Creating your config

Recommended starter config

Config file priority

Configuration reference

VSCode extension settings