tlua-gmod

Garry's Mod type declarations for the tlua type checker, scraped from the GMod Wiki.

npm run scrape-wiki normalizes wiki pages into a cached wiki-data/ directory, then generates .d.tlua declarations into dist/. The scrape is skipped when wiki-data/ is already up to date.

Using the typings

npm install @tlua/gmod

Then list the package under types in your tluaconfig.json. Unlike TypeScript, tlua does not auto-include installed type packages, only those named in types (or "*" for all of them):

{
  "compilerOptions": {
    "types": ["@tlua/gmod"]
  }
}

The Garry's Mod globals (Entity, Vector, hook, _G entries, ...) are then available ambiently, with no require.

Publishing (maintainers)

The release workflow (push to main, monthly cron, or manual dispatch) scrapes, regenerates, and publishes to npm under latest. It regenerates only when a generator input (src/, custom/, config) changed or on the schedule, and skips the publish when the output matches what is already published.

Auth is npm trusted publishing over OIDC, so there is no NPM_TOKEN and npm attaches a provenance attestation. The repository and .github/workflows/release.yml must be registered as a trusted publisher on npm; renaming that file breaks the link until it is re-registered.

Each run bumps the patch of the published version, read from the registry so the counter cannot reset. Bump the major or minor by publishing that version by hand once.

Development Setup

Requires Node.js >= 21; tests and the CLI run on bun.

npm ci               # install dependencies
npm run scrape-wiki  # scrape and generate into dist/
bun test             # run tests

Repository Layout

• src/scrapers/ - GMod wiki scraping and normalization
• src/api-writer/ - tlua declaration (.d.tlua) generation (tlua-api-writer.ts)
• custom/ - manual tlua overrides (.d.tlua) merged during generation, plus the _gmod-std.d.tlua prelude of std.* utility types
• wiki-data/ - cached raw wiki markup (git-ignored); the scraper's output and the generator's input
• dist/ - the generated typings package before it is published (git-ignored)

Credits

A hard fork of luttje/glua-api-snippets by Luttje, which generates LuaLS/EmmyLua annotations, by way of Pollux12/annotations-gmod-glua-ls. The retarget here is to emit .d.tlua declarations instead. MIT licensed; all three copyrights are retained in LICENSE.