StarfallEx Lua

Syntax highlighting, contextual autocompletion, hover documentation and snippets for StarfallEx (Garry's Mod).

All function/hook/directive data is generated directly from StarfallEx's own auto-generated docs (sf_doc.json), the same data that powers https://thegrb93.github.io/StarfallEx/ — so it stays accurate to the real API, including parameter names, types, descriptions, realms (server/client/shared) and source links.

What it does

• Language: starfall. Auto-detected for any file whose first line matches --@name ... (so plain .lua chips get it automatically), plus explicit .sf / .sf.lua extensions. You can also force it via the command palette: Starfall: Set Language Mode for Current File.
• Syntax highlighting: comments, strings (incl. long [[ ]] strings), numbers, keywords, --@directive lines, and known library/type names (render, hook, Vector, Entity, ...).
• Autocomplete:
  • render. / hook. / etc. → library functions & fields
  • ent: / something: → union of all known type methods (best effort; plain-text tooling can't know the real static type, same tradeoff other Lua extensions make)
  • hook.add(" → hook name list
  • --@ → directive list
  • bare word → globals (print, chip, timer, ...), library names, type names
• Hover docs: full signature, parameter table, return values, realm badge, and a link to the source line on GitHub.
• Snippets: hand-written boilerplate (chip header, hook.add, timer.simple, timer.create, net.receive, ...) plus one auto-generated snippet per hook (hookPlayerEnteredVehicle, ...) and per directive (@server, ...).

Try it locally

npm install
npm run compile

Then open this folder in VS Code and press F5 to launch an Extension Development Host. Open examples/sample.sf.lua there to try highlighting, completion (Ctrl+Space after render. or ent:) and hover.

Refreshing the data

The dataset in src/data/starfallData.json is a snapshot. To pull the latest docs straight from StarfallEx's master branch:

npm run generate-data
npm run compile

This re-downloads sf_doc.json from raw.githubusercontent.com/thegrb93/StarfallEx/gh-pages/sf_doc.json and regenerates the bundled dataset. Consider wiring this into a scheduled CI job if you want the extension to auto-track upstream changes.

Packaging & publishing

npm install -g @vscode/vsce
vsce package     # produces a .vsix you can install locally or share
vsce publish     # publishes to the Marketplace (needs a publisher account)

Before publishing, update publisher in package.json to your own Marketplace publisher id, and consider adding a proper icon (images/icon.png, referenced via "icon" in package.json).

Known limitations / ideas for next steps

• : completion doesn't do static type inference — it shows all known methods across all types (same approach glua and most untyped-Lua extensions use). A more advanced version could track local ply = owner() assignments to narrow suggestions to Player methods.
• No SignatureHelpProvider yet (parameter hints while typing inside (...)) — the data model already has everything needed (params[]) to add this.
• No diagnostics/linting. Could integrate a Lua linter (e.g. via luacheck) scoped to the StarfallEx sandboxed globals.
• Grammar highlights library/type names generically; it doesn't verify that render.pushMatrix is a real function vs. a typo — that could be a diagnostics pass built on the same dataset.