Workspace Settings - GLua Language Server

Overview

The workspace section tells the language server which files to analyze, which files to ignore, and where to find external libraries. It also controls module resolution and file encoding.

Options

Option	Type	Default	Description
`workspace.library`	`array`	`[]`	External library paths to include in analysis (strings or objects)
`workspace.workspaceRoots`	`string[]`	`[]`	Additional workspace root directories for multi-root setups
`workspace.ignoreDir`	`string[]`	`[]`	Directory names to exclude from analysis
`workspace.ignoreDirDefaults`	`(string \| object)[]`	built-in list	Built-in directories and globs to ignore. Accepts legacy strings or override objects; see below.
`workspace.useDefaultIgnores`	`boolean`	`true`	Whether to apply `workspace.ignoreDirDefaults`
`workspace.enableIsolation`	`boolean`	`false`	Keep multi-root main workspaces isolated. Set to `false` to merge workspace configs into one global baseline (first workspace config wins scalar conflicts, arrays are unioned) while still allowing per-workspace file-scoped overrides.
`workspace.ignoreGlobs`	`string[]`	`[]`	Glob patterns of files to exclude from analysis
`workspace.moduleMap`	`array`	`[]`	Module path rewrite rules (regex patterns)
`workspace.encoding`	`string`	`"utf-8"`	File encoding for all Lua files in the workspace
`workspace.enableReindex`	`boolean`	`false`	Trigger a full workspace reindex when files change
`workspace.reindexDuration`	`integer`	`5000`	Delay in ms before a reindex fires after a file change
`workspace.packageDirs`	`string[]`	`[]`	Partial library load; only load package declarations from these dirs, not full analysis

Library paths

workspace.library adds directories to analysis without treating them as project source. Use this for annotation files, dependencies, or other code you need to reference from your project.

This helps gamemodes such as Helix, where your schema needs to reference the “core” Helix gamemode. Add ../helix as a library path in your schema gamemode.

Each entry is either a path string or an object with per-library ignore options:

.gluarc.json

{
  "workspace": {
    "library": [
      "./types",
      {
        "path": "./vendor/stubs",
        "ignoreDir": ["test"],
        "ignoreGlobs": ["**/*.spec.lua"]
      }
    ]
  }
}

Ignore patterns

Exclude directories or files from analysis:

.gluarc.json

{
  "workspace": {
    "ignoreDir": ["node_modules", ".git", "tests"],
    "ignoreGlobs": [
      "**/*.min.lua",
      "legacy/**"
    ]
  }
}

Common directories to ignore for GMod projects:

garrysmod (Steam engine files)
addons (other addons’ source, if not relevant to your project)
.git
out, build, dist

Ignore default overrides

workspace.ignoreDirDefaults lets you override, disable, or extend the built-in ignore defaults without replacing the whole list. The list accepts two forms:

Legacy strings: when the list contains only plain strings, those strings replace all built-in defaults (original behavior, backward compatible).
Object entries: when any object entry is present, GLuaLS uses the built-in list as the starting point and applies each entry in turn.

Built-in default ids:

id	Default glob
`wire-expression2`	`/gmod_wire_expression2/`
`wire-expression-files`	`*/wire_expression.lua`
`tests`	`/tests/`
`test`	`/test/`

Object entry fields:

Field	Type	Description
`id`	`string`	Stable identifier matching a built-in or a custom id.
`label`	`string`	Optional human-readable label (informational only).
`glob`	`string`	Glob pattern to apply. Omit when only using `disabled`.
`disabled`	`boolean`	Set `true` to remove this built-in default from the workspace.

Disable a single built-in:

.gluarc.json

{
  "workspace": {
    "ignoreDirDefaults": [
      { "id": "tests", "disabled": true }
    ]
  }
}

Override a built-in pattern and add a custom entry:

.gluarc.json

{
  "workspace": {
    "ignoreDirDefaults": [
      { "id": "test", "glob": "**/my_tests/**" },
      { "id": "legacy-stuff", "glob": "**/legacy/**" }
    ]
  }
}

Disable all built-in defaults globally:

.gluarc.json

{
  "workspace": {
    "useDefaultIgnores": false
  }
}

moduleMap rewrites require paths to file paths using regex replacement. Use it when your project uses non-standard require patterns.

.gluarc.json

{
  "workspace": {
    "moduleMap": [
      {
        "pattern": "^libs/(.*)",
        "replace": "lua/libs/$1"
      }
    ]
  }
}

Workspace roots

If your Lua files are not at the repository root, specify the Lua root:

.gluarc.json

{
  "workspace": {
    "workspaceRoots": ["lua"]
  }
}

This affects require path resolution. GLuaLS resolves require("mymodule") relative to lua/mymodule.lua.

File encoding

Most Lua files use UTF-8, but older addons may use a legacy encoding:

.gluarc.json

{
  "workspace": {
    "encoding": "utf-8"
  }
}

Available values: "utf-8", "utf-16", "gbk", "latin1", "ascii".

VSCode extension settings

You can also configure these settings in VS Code settings with the gluals.* prefix:

VSCode Setting	.gluarc.json Key	Type	Default	Description
`gluals.workspace.enableReindex`	`workspace.enableReindex`	`boolean`	`false`	Enable reindex after file changes
`gluals.workspace.reindexDuration`	`workspace.reindexDuration`	`integer`	`5000`	Delay before reindex (ms)
`gluals.workspace.workspaceRoots`	`workspace.workspaceRoots`	`array`	`[]`	Additional workspace roots

​Overview

​Options

​Library paths

​Ignore patterns

​Ignore default overrides

​Workspace roots

​File encoding

​VSCode extension settings

Overview

Options

Library paths

Ignore patterns

Ignore default overrides

Workspace roots

File encoding

VSCode extension settings