Addons

Addons can be used to add additional content for the Lua Language Server by doing the following:

• Providing definitions for a framework/library/API.
• Including a plugin.
• Modifying a user's settings.

They can then be published to the addon manager using the LLS-Addons repository .

There are a number of addons that come with the language server that can be found in meta/3rd .

Addons can be installed from anywhere, however, many popular addons can be found in the LLS-Addons repository, an official collection of community addons used by the addon manager. The intention with the repository is that each addon is its own sub-repository (submodule) so that they can be forked and downloaded easily.

While addons can be installed from anywhere, we are going to go through installing from LLS-Addons . Take a look through the addons/ directory and open up your desired addon. Clicking module will bring you to the repository where that addon lives. You can then download the zip for that addon and unzip it to some directory, any directory, on your computer (e.g. C:\Users\me\Documents\LuaAddons). You can place any future addons in this directory as well, just make sure they are contained within their own directory (see below). Then add the path to this parent directory to workspace.userThirdParty.

📂 LuaAddons/
    ├── 📂 Addon1/
    │    ├── 📁 library/
    │    ├── 📜 config.json
    │    └── 📜 plugin.lua
    └── 📂 Addon2/
         ├── 📁 library/
         └── 📜 config.json

So in this case, your setting could look like this in your configuration file:

{
  "Lua.workspace.userThirdParty": ["C:\Users\me\Documents\LuaAddons"]
}

Addons often define some configuration values in their config.json file that are meant to be automatically applied, however, they can still be applied manually.

If the addon in question has been configured to allow automatic enabling and it has been placed in a directory specified in workspace.userThirdParty, you will be prompted to enable it once certain critera is met. The critera is defined by the addon in its config.json file - this could be, for example, using require on the library or naming a file a certain way.

If the addon contains a library/ directory, you will want to paste the full path to that directory in your workspace.library setting. This will enable the provided definition files.

If the config.json contains settings, you will have to manually copy them to your configuration file.

The addon manager, which is currently only available in Visual Studio Code, allows you to browse and install addons from LLS-Addons . It manages downloading addons and applying modifications to your configuration file.

The addon manager can be opened from the command palette Ctrl + P by running the "Open Addon Manager" command (lua.addon_manager.open).

The addon manager is a webview (basically an iframe) that contains a Vue.js webapp .

If you have feedback on the addon manager, please leave it in the vscode-lua repository .

To create an addon, you will want to first create a directory where all your files will live. If you intend to publish your addon to LLS-Addons , you will also want a remote repository where people can access it. Both GitHub and GitLab have been confirmed to work, although any service that provides Git cloning over HTTP should work.

An addon that contains definitions should place them in a library/ directory. You can use the LuaLS/addon-template to get up and running a little bit quicker.

📂 myAddon/
    ├── 📁 library/
    │    ├── 📜 http.lua
    │    └── 📜 error.lua
    ├── 📜 plugin.lua
    └── 📜 config.json

The definition files should live in the library/ directory and should start with a @meta annotation. They can use LuaCATS annotations just like any Lua code.

A plugin can be included simply by placing it in the addon folder and naming it plugin.lua.

The config.json file is very important for addons and must be included. A schema for it can be found at LLS-Addons/schemas/addon.schema.json . You can also browse some of the addons in that repository to see how the config.json file can be used. The settings array can contain any settings for the language server, as well as any VS Code settings, if applicable.

{
    // Name of the addon
    "name": "My Awesome Addon",

    // Lua string patterns to look for in a workspace.
    // If detected, this addon will be recommended to enable
    "words": [ "require[%s%(\"']+MAA[%)\"']" ],

    // Lua string patterns to look for in filenames.
    // If detected, this addon will be recommended to enable
    "files": ["my-awesome-file.lua"],

    // List of settings to apply when this addon is enabled
    "settings": {
        "Lua.diagnostics.globals" : [
            "awesome"
        ]
    }
}