Garry's Mod LuaLS Addon + Plugin

Deprecated: This LuaLS plugin is no longer actively maintained. Please use my new Garry's Mod extension instead: https://github.com/Pollux12/vscode-gmod-glua-ls

This repository is a re-write of my personal LuaLS addon to instead use annotations from the upstream glua-api-snippets project (rather my my own scuffed system) and merge features from two other plugins. Alongside all the features in the original, it contains a plugin that allows for several new features and extended functionality over the original.

Features

• Everything in glua-api-snippets
• Include path resolution for gmod lua files, credit to CFC Servers
• Scripted class detection (ENT, SWEP, EFFECT, TOOL) with automated annotation and inheritance
• Derma (VGUI) class detection with automated annotation and inheritance
• NetworkVar, AccessorFunc and DEFINE_BASECLASS getter/setter annotation with type support, credit to TIMONz1535
• A config.lua file to configure some behaviour, useful for custom gamemodes
• Various annotation fixes

Manual installation (Visual Studio Code)

1. Install the Lua Language Server (LuaLS) extension

• Lua Language Server Extension: https://marketplace.visualstudio.com/items?itemName=sumneko.lua
• (OPTIONAL) You can also use my extension pack, it includes LuaLS and other useful things: https://marketplace.visualstudio.com/items?itemName=pollux.gmod-dev-pack-cityrp or just search for pollux.gmod-dev-pack-cityrp in VSCode Extensions View

2. Download the addon files

• Download the .plugin folder from a release ZIP, or clone the lua-language-server-addon branch into a folder you control.
• You can find the latest release here, download the one ending in .plugin.zip: https://github.com/Pollux12/gmod-luals-addon/releases/latest
• Extract it somewhere, you'll need the folder path in the next step.

3. Configure VSCode settings with the following. You can shove these values into either your workspace or profile VSCode settings

• Open VSCode JSON Settings via: File -> Preferences -> Settings -> Open Settings (JSON) (top right corner, file icon)

• Copy and paste the below code block into your settings

• Replace FOLDER-PATH with the absolute path of the folder containing the extracted plugin files. You may have to replace \ with /.

  Settings to copy (click to expand)

    "Lua.runtime.version": "LuaJIT",
    "Lua.runtime.special": {
      "include": "require",
      "IncludeCS": "require"
    },
    "Lua.runtime.nonstandardSymbol": [
      "!",
      "!=",
      "&&",
      "||",
      "//",
      "/**/",
      "continue"
    ],
    "Lua.runtime.plugin": [
      "FOLDER-PATH/plugin.lua"
    ],
    "Lua.workspace.library": [
      "FOLDER-PATH/library"
    ],
    "Lua.diagnostics.disable": [
      "lowercase-global",
      "inject-field",
      "duplicate-set-field"
    ],
    "Lua.completion.requireSeparator": "/",

The above is required since this isn't uploaded to the LuaLS addon repository, so it won't automatically load the config contained within the release. If you are not using a dedicated VSCode profile for GLua (you should be!), I'd recommend adding the above to workspace settings rather than profile settings, since profile settings are global (you may run into issues if you have the above config with non gmod lua).

4. (OPTIONAL) luarc.json configuration

• You may use a .luarc.json file in the root directory of the workspace to automatically set relevant settings for anyone editing that workspace.
• Here are the settings I use in my own project, feel free to adapt them.

5. (OPTIONAL) editorconfig configuration

• You may make use of a .editorconfig file to configure the formatter settings for anyone editing that workspace.
• Here are the settings I use in my own project, feel free to adapt them
• If you follow CFC-guidelines, you may find this more useful.

6. Once you're done setting it up, please close and re-open VSCode

Notes

• You may have to restart VSCode after installing and applying the relevant settings.
• There may be some minor bugs or performance issues, since this is not yet finished, although it should be good enough. I use this in a messy gamemode with thousands of files, and haven't noticed it any slower than the original.
• I will mark releases that I've used for a while as stable, with the rest being pre-release.
• I don't actively develop addons, and as such, there may be some bugs with addons due to limited testing. It should still work, but let me know if there are any issues.
• If you use this on a gamemode, check the config.lua file to add custom file paths and similar. It should be possible to add support for things such as plugins and items by adding custom scopes (Anything defined in scopes will automatically define a class annotation and adds a fake local <class> = {} (only the language server sees this variable) to the top of that file, the class will be automatically registered either based on the file name, or the folder name, depending on the config. It should be smart enough for most cases.
• I know that not everything makes use of the config yet; I'm slowly converting things over once confirming they're stable, since I didn't use a config system in my original version.
• After some more testing, I do plan on cleaning this up and creating a PR into the upstream repo.

Workspace Configuration

• The plugin now merges config.lua with an optional workspace override named .glua-api-snippets.json located at the workspace root. Values from the JSON document replace the defaults; table-like values are deep merged while array-like values replace the original array entirely.
• To point at a different JSON file (relative to the workspace or as a URI) add --config <path> to the plugin arguments. Use --no-workspace-config to disable overrides.
• Visual Studio Code example (.luarc.json):

{
  "runtime.plugin": ["FOLDER-PATH/plugin.lua"],
  "runtime.pluginArgs": ["--config", ".glua-api-snippets.json"]
}

• Sample .glua-api-snippets.json:

• Invalid or malformed workspace configuration files are ignored after a single warning (shown through LuaLS).

• Use the example.glua-api-snippets.json file in the repository root as a template. Copy it to the workspace as .glua-api-snippets.json (note the leading dot) so the plugin will find it automatically, or point the plugin at a different file with --config <path> when loading the plugin.

Some code is taken from the following: https://github.com/TIMONz1535/glua-api-snippets/tree/plugin-wip1 https://github.com/CFC-Servers/luals_gmod_include

Everything below is the original README and may be outdated

Garry's Mod Lua API Definitions

This repository scrapes the Garry's Mod Lua API and generates annotated code snippets that will help provide autocompletion for Lua in editors like VSCode, Neovim and more.

🔨 Usage

To get autocompletion for the Garry's Mod Lua API in your Garry's Mod projects, you need to install the Lua Language Server and our GLua API Definitions.

First install Lua Language Server (LuaLS): for your editor of choice:

• Visual Studio Code Extension

• Neovim Configuration

Then download/install our GLua API Definitions for the Lua Language Server. This process varies depending on your editor:

Visual Studio Code

Installing our GLua API Definitions for the Lua Language Server in Visual Studio Code is easy thanks to the Lua Language Server Addon Manager built into the VSCode extension.

1. In Visual Studio Code open the Command Palette with the key combination Ctrl+Shift+P (or Cmd+Shift+P on macOS)

2. Search for Addon, then select Lua: Open Addon Manager ...:

3. Search for the Garry's Mod addon and Enable it:

Neovim

1. Setup a folder for storing Lua Language Server addons (e.g. ~/.cache/luals/) and create addonManager/addons/garrysmod/module folders inside it

Note

If you switch between Neovim and VSCode regularly, you probably want to use VSCode's directory, which is ~/AppData/Roaming/Code/User/globalStorage/sumneko.lua on Windows and ~/.config/Code/User/globalStorage/sumneko.lua on Linux

2. Clone (or download and unzip) our lua-language-server-addon branch into the garrysmod/module folder

3. In your Neovim config where you call lspconfig.lua_ls.setup, add the following to the table

before_init = function(init_params, config)
    init_params.initializationOptions = init_params.initializationOptions or {}
    init_params.initializationOptions.storagePath = "~/.cache/luals"
end

Example .luarc.json for projects

{
    "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
    "runtime.version": "LuaJIT",
    "runtime.special": {
        "IncludeCS": "dofile",
        "include": "dofile"
    },
    "runtime.nonstandardSymbol": ["!", "!=", "&&", "||", "//", "/**/", "continue"],
    "workspace.library": ["${addons}/garrysmod/module/library"],
    "workspace.checkThirdParty": false
}

Warning

The VSCode extension currently does not automatically install addons. If a user that does not have this addon installed already opens a project that has this .luarc.json present, they will have to open the Addon Manager and click Disable and Enable on this addon for it to install the addon properly.

📅 Automatically up-to-date

Using GitHub Actions, this repository is automatically updated on the first day of every month at approximately 00:00 UTC.

A workflow will automatically scrape the latest Garry's Mod Lua API from the Garry's Mod Wiki and package them into 🔗 a release.

Note

The Lua Language Server addon might not be immediately updated to align with the definitions in this repository. This delay occurs because we must submit a pull request (PR) to the Lua Language Server Addons repository (LuaLS/LLS-Addons) to update the addon. Subsequently, a maintainer of the LuaLS/LLS-Addons repository needs to find time to review and merge the PR.

Our schedule for updating our addon with LuaLS/LLS-Addons is set for the first day of February, April, June, August, October, and December. This schedule is subject to change based on the availability of maintainers and the urgency of the update.

If you urgently require the most current definitions from the addon, you can expedite the process by submitting a PR to update it yourself. Instructions for doing so can be found in the CONTRIBUTING.md file.

🤖 Advanced Usage

Running the Scraper Locally

You can clone this repository and run the scraper yourself. This is useful if you want to use the latest version of the API, or if you want to make changes to the scraper.

1. Clone this repository

2. Install the dependencies with npm install

3. Run the scraper with npm run scrape-wiki

Testing the project

This project uses Jest to automate testing. You can run the tests with npm test.

API as JSON

The API is also available as JSON. You can find it with the Lua API package on 🔗 the releases page. It is named something like YYYY-MM-DD_HH-MM-SS.json.zip.

Manual Installation

If you cannot or do not want to use Lua Language Server:

1. Download and unzip the latest release from 🔗 the releases page, it's named something like YYYY-MM-DD_HH-MM-SS.lua.zip

2. Include or symlink the unzipped directory into your workspace

Contributors

luttje 💻	Aske 💻	Vurv 💻	jason 🤔	_AMD_ 🐛	[aka]bomb 🐛 💻	Rubat 💻
Techbot121 🐛	TIMON_Z1535 🤔 🐛	Cynthia Foxwell 📖