GLuaLS Annotation Generator

Automatically generates GLuaLS annotations for Garry's Mod API by scraping the GMod Wiki. These annotations are consumed by gmod-glua-ls.

Plugins are currently WIP and are not used.

Note: This repository is part of the GMod language server infrastructure. Annotations are automatically downloaded by the VSCode extension from the gluals-annotations branch - manual setup is not required.

Workflow

1. npm run wiki-check-changed checks whether upstream wiki content changed since the latest scrape tag.
2. npm run scrape-wiki scrapes and normalizes wiki pages, then writes Lua annotations into output/.
3. npm test validates scraper and writer behavior.
4. CI formats generated output and publishes annotations to the gluals-annotations branch for extension consumption.

Development Setup

Requirements:

• Node.js >= 21

Install dependencies:

npm ci

Generate annotations locally:

npm run scrape-wiki

Run tests:

npm test

Build release artifact locally (legacy, not required for branch-based consumption):

npm run pack-release

Local Development Testing

For local language server testing, generate annotations and point your workspace library to ./output/:

{
  "workspace": {
    "library": [
      "./output"
    ]
  }
}

Note: The VSCode extension automatically downloads production annotations from the gluals-annotations branch. The above configuration is only needed for testing local changes during development.

Repository Layout

• src/scrapers/ - GMod wiki scraping and normalization
• src/api-writer/ - EmmyLua/LuaCATS annotation generation
• plugin/ - framework plugin metadata + gluarc fragments consumed by the VSCode extension
• custom/ - manual overrides merged during generation
• output/ - generated annotation files (published to gluals-annotations branch)

Plugin Metadata Notes

The VSCode extension loads plugin metadata from the annotation bundle (plugin/index.json + plugin/<id>/plugin.json).

Credits

Forked from luttje/glua-api-snippets