Skip to main content

​
Overview

GLuaLS ships without bundled GMod API definitions. The VS Code extension downloads the latest annotations generated from the Garry’s Mod wiki, so your API definitions stay current without extension updates.

​
How it works

On first launch and on later checks, the extension:
  1. Checks the remote metadata for the gluals-annotations branch
  2. If the annotations are outdated or missing, downloads and extracts the latest ZIP
  3. Points the language server at the annotations path
VS Code stores annotations in global extension storage, separate from your project. All workspaces share them.

​
Annotation source

By default, the extension downloads annotations from Pollux12/annotations-gmod-glua-ls on the gluals-annotations branch. You can point downloads at another compatible GitHub repository or branch from VS Code settings:
VSCode SettingDefaultDescription
gluals.gmod.annotationsRepositoryPollux12/annotations-gmod-glua-lsGitHub repository in owner/repository format, or a GitHub repository URL
gluals.gmod.annotationsBranchgluals-annotationsBranch containing generated annotations and __metadata.json; plugin artifact branches are not supported
VS Code settings
{
  "gluals.gmod.annotationsRepository": "Pollux12/annotations-gmod-glua-ls",
  "gluals.gmod.annotationsBranch": "gluals-annotations"
}

​
Manual update

To force an annotations update:
  1. Open the Command Palette (Ctrl+Shift+P)
  2. Run GLua: Update Annotations

​
Disabling auto-download

If you need to use a custom annotations build or are in an environment without internet access:
VSCode Setting.gluarc.json KeyDefaultDescription
gluals.gmod.autoLoadAnnotationsgmod.autoLoadAnnotationstrue (null in workspace)Auto-download and load GMod wiki annotations

​
Via VSCode settings

VS Code settings
{
  "gluals.gmod.autoLoadAnnotations": false
}

​
Via .gluarc.json (per-workspace)

Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.
.gluarc.json
{
  "gmod": {
    "autoLoadAnnotations": false
  }
}

​
Using a custom annotations path

Point GLuaLS at your own annotations folder instead of the auto-downloaded ones:
.gluarc.json KeyTypeDefaultDescription
gmod.annotationsPathstring | nullnullPath to custom annotations folder
.gluarc.json
{
  "gmod": {
    "annotationsPath": "./my-custom-annotations"
  }
}
The path can be absolute or relative to the workspace root. When you set annotationsPath, GLuaLS does not use the downloaded annotations for that workspace.
gmod.annotationsPath takes precedence over the extension’s auto-download setting for that workspace. Set gmod.autoLoadAnnotations: false in .gluarc.json to disable auto-loading for that workspace, including extension settings and CLI-provided annotation paths.

​
What the annotations contain

The annotations are generated from the official Garry’s Mod wiki and include:
  • All GMod global functions with parameter types, return types, and descriptions
  • All class methods (Entity, Player, Weapon, etc.)
  • All enumerations
  • All hooks with parameter types
  • Realm badges indicating where each function is available