Basics - LuaLS

What is LuaLS?

The lua-language-server allows for type checking with the use of comment annotations. This can be used on any editor that supports Language Server Protocol (most) however, this mini-guide shows how to install it for VisualStudio code. There are other guides here.

Type checking can be very useful for finding bugs before they happen due to type mismatches, often times providing early error detection. Ever had the expected ? got nil error before? Then this is for you!

Installation

Install the Lua (by sumneko) extension from the visual studio marketplace.
Install luttje/glua-api-snippets by following the guide on their README.

If you encounter an error popup when attempting to open the Lua Addon Manager, you more than likely are missing git. If you experience further issues with the Addon Manager, see troubleshooting.

Config / User Settings

Once everything is installed, open a text file in VS Code and switch to Lua language mode in the bottom right corner. Alternatively use the key shortcut ctrl + k m.

Next, open the command palette with ctrl + ⇧ shift + p. And search Open User Settings (JSON) and hit enter. This will open your settings as a JSON file to add the lua settings. You should then add these default settings.

"Lua.diagnostics.disable": [ "undefined-global" ], "Lua.runtime.special": { "include": "require", "IncludeCS": "require" }, "Lua.runtime.nonstandardSymbol": [ "continue", "&&", "||", "!=", "!", "//" ]

It can be tempting to disable more diagnostics, especially when you're getting started or integrating types into an existing codebase but this often leads to missing useful functionality when everything is properly typed.

If you have a gamemode / set of addons you want to always load types from you can add these to Lua.workspace.libary. This means you can use the type definitions in other addons without having to redefine / require them.

"Lua.workspace.library": [ "C:\Path\To\BaseDirectory" ]

Basic Usage Examples

Here are some short examples showcasing the different usecases of LuaLS.

Type Checking

Here we have an example where a function returns a key value table of two different types, we then iterate over the table and pass these values to another function. You may, or may not, have noticed that for PrintHealth the key and value arguments are switched. Since we've provided types for the table and function arguments, LuaLS warns us about the type mismatches! Obviously this example is a bit obvious, but in a case where the function returns are coming from some other file etc this can be a life saver.

Auto Completion

Here we define a new function GetOwnedEntities on Player that returns a table of Entities. (Entity[] is equivalent to table<integer, Entity>, where it's a sequential table of the type). Thanks to the type docs on this new function, we can see a full autocomplete of all functions within Entity when we iterate over the returned table.

Generic

Generics allow code to be reused and serve as a sort of "placeholder" for a type. They allow a type to be "captured" and reused, in this example we just return whatever the value was along with its type.

Troubleshooting

Sometimes the Lua Addon Manager will fail to install the Gmod Snippets. If this happens, instead:

Download the latest *.lua.zip from luttje/glua-api-snippets/releases.
Add the unzipped directory path to Lua.workspace.libary in your VS User Settings.