<cat>Dev.Lua</cat> <title>Basics - LuaLS</title> ## 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](https://luals.github.io/#install). 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](https://marketplace.visualstudio.com/items?itemName=sumneko.lua). + Install [luttje/glua-api-snippets](https://github.com/luttje/glua-api-snippets) by following the guide on their README. <note>If you encounter an error popup when attempting to open the Lua Addon Manager, you more than likely are missing [git](https://git-scm.com/). If you experience further issues with the Addon Manager, see troubleshooting.</note> ## 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 <key>Ctrl</key> + <key>K</key> <key>M</key>. Next, open the command palette with <key>Ctrl</key> + <key>Shift</key> + <key>P</key>. 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. ```markdown "Lua.diagnostics.disable": [ "undefined-global" ], "Lua.runtime.special": { "include": "require", "IncludeCS": "require" }, "Lua.runtime.nonstandardSymbol": [ "continue", "&&", "||", "!=", "!",⤶ "//" ] ``` <note>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.</note> 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. ```markdown "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. <upload src="b52b3/8dccf682b315945.png" size="46349" name="type-checking.png" /> ### 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. <upload src="b52b3/8dccf68ff0806f0.png" size="59750" name="auto-completion.png" /> ### 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. <upload src="b52b3/8dccf6a62254ffe.png" size="45602" name="image.png" /> ## 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](https://github.com/luttje/glua-api-snippets/releases). + Add the unzipped directory path to `Lua.workspace.libary` in your VS User Settings. ## Links + [LuaLS Github](https://github.com/LuaLS/lua-language-server). + [LuaLS Wiki](https://github.com/LuaLS/lua-language-server/wiki).