Roblox LSP is Lua Language Server for Roblox forked from sumneko’s Lua language server.
Everything you will see in this topic and more was made by me, but this would not be possible without the language server created by sumneko.
This project was made with Roblox developers in mind.
Roblox LSP provides a lot of features, like advanced IntelliSense, Signature Help, Goto Definition, Symbols, Diagnostics, etc, and many focused on programming in Roblox and Luau.
When you are a Roblox programmer, you may not be satisfied with Roblox Studio and the Script Editor it has for various reasons, so you decide to use an external editor (like Visual Studio Code) to improve your workflow.
This comes with many advantages like:
- Have your project in your filesystem.
- Use Git for version control (Especially useful when working with teams)
- Use your favorite code editor.
And this comes with more advantages like Snippets, Multiple Editors, Multiple Cursors, Code Preview, and a huge amount of Plugins that give you even more!
Now you can add to that list: A Better IntelliSense!
I am going to show you its features and explain you how to use it, so this topic can become a little long.
sumneko’s Lua Features
- Goto Definition
- Find All References
- Auto Completion
- Signature Help
- Document Symbols
- Workspace Symbols
- Syntax Check
- Code Action
- EmmyLua Annotation
- Multi Workspace
- Semantic Tokens
You will feel that you are programming in Roblox Studio (but better), it has an environment exactly same as Roblox, you have the same globals, same functions, same everything!
And you can also expect certain behaviors, such as that global variables can only be used in the script in which you define them, and that
shared are shared across all scripts.
Classes and Datatypes
As you can expect, you will have full intellisense and auto-completion for each Class and Datatype, but not only that.
You will get documentation and details of the API of almost every member of every class.
And also className autocompletion for functions like
IsA, etc, and Enums autocompletion!
FindFirstChildOfClass, etc, will return a type with the arguments you give them, for example:
local basePart = game.Workspace:FindFirstChildWhichIsA("BasePart")
But get ready because there is still more!
When giving a function as an argument to Connect of a RBXScriptSignal, the parameters of the function will get types!
You will also have a snippet that autocompletes the function and the parameters.
When doing math operations with certain types, you will receive the expected type!
You also have some table types, like Dictionary, Array, Map and Objects, which will give types to the parameters of a for loop.
Dictionary will give you
string as key and
any as value.
Array will give you
integer as key and
any as value.
Objects will give you
integer as key and
Instance as value.
But that’s not all, because some functions will give you more specific types, for example,
Players.GetPlayers will give you
Full Luau Syntax
It supports full Luau Syntax! and has IntelliSense for Compound Assignments, Continue Statement and types for parameters, variables and returns.
However, there is not type checking, but i’m planning to implement it in a future update.
Using Selene (Optional)
In order to use it, Roblox LSP has an option to disable Syntax Error warnings, all Roblox LSP features works correctly with syntax errors in the code, these are simply ignored.
You just have to install Selene for VSCode, and you will also have to disable some duplicated lints.
Add this to your selene.toml:
std = "roblox" [rules] undefined_variable = "allow" unused_variable = "allow" shadowing = "allow" empty_if = "allow" incorrect_standard_library_use = "warn"
Alternatively, you can disable the same diagnostics in Roblox LSP if you prefer Selene.
Make sure you have the latest version of Selene.
This is extremely important and useful, with Rojo support you can do a lot of things!
If you have a project file in your workspace, it will read it and create an Instance Tree, with it, you will get IntelliSense for modules, it will know the location of the scripts in the Instance Tree, and you will get Autocompletion for children in DataModel that you created in your filesystem.
It has support for .txt, .lua and .model.json files, and recognizes init files too.
If you have multiple projects in your workspace, you can set
Lua > Workspace: Load Mode to
Rojo Project, and Roblox LSP will only load the scripts that can be found in your Rojo Project, unless you open them manually.
You also have to specify the name of the .project.json file you are working with in
Workspace: Rojo Project File, by default it is “default”.
But if you want to work on several projects at the same time that are in the same workspace, and you have several .project.json files, then you can set
Lua > Workspace: Rojo Project File to blank, this will make Roblox LSP read all the .project.json files it finds, convert them into Instance Trees, and then combine the Instance Trees into one.
You may also have noticed that the require function has an optional parameter called path, it’s optional, and you can use it to get IntelliSense for files that Roblox LSP can’t found.
Another thing to notice is that the functions
WaitForChild, will return you the child of the Instance if it finds it, otherwise, they will return you a value of type
Autocompletion for datamodel descendants
Roblox LSP can receive information from Roblox Studio using a plugin, if you install it, a list of every descendant in your game will be send to Roblox LSP every time you create, remove, move or rename an Instance.
To use this feature, install the plugin here, and two buttons will appear in the Toolbar called Connect to start sending data to this extension, and Settings to configure the plugin.
Roblox LSP will be ready to receive data when you initialize the extension, it creates a port in localhost (your machine), you can configure the port changing the setting “Lua.completion.serverPort”. You can also configure the plugin to make it start automatically when you open the place, exclude instances and their descendants, or change the port, both ports must match. It is recommended to use a different port for every project.
You can check the data sent to localhost in http://127.0.0.1:PORT/last.
Children of StarterPack, StarterGui, StarterPlayerScripts and StarterCharacter will also be children of Backpack, PlayerGui, PlayerScripts and Character respectively.
sumneko’s Lua includes a lot of diagnostics, and Roblox LSP includes a few more focused in Roblox, they only work with Roblox Instances, Datatypes, and Lua libraries.
You will get a warning if you try to access an undefined member of an Instance or DataType.
When indexing a value of type
Instance specifically, it will give you a warning if the member is undefined in all Instance classes.
When indexing a deprecated member of an Instance or DataType, you will get an info warning.
There is a quick fix to fix it, or you can add the name in the ignore list.
When calling a function with incorrect arguments types, you will get a warning.
And when calling
Instance.new, etc, you will get a warning if className is invalid.
You can disable the diagnostics you don’t want.
You can also add “–ignore” at the end of the line and the diagnostics will not show up.
Support for some Third-Party Libraries!
To use it, set the type (Not necessary anymore).
Roact to your Roact module.
It adds the following types:
It adds the following types:
It adds the following types:
It has something very special, AeroService and AeroController comes with members called Modules, Shared, Services and Controlllers, when you set the type of a variable to AeroService or AeroController, it will appear in Services or Controllers.
For Modules and Shared, your project has to be structured this way:
root: - scr - Server - Modules - Client - Modules - Shared
Adds the following types:
Like AeroGameFramework, it provides intellisense for Services and Controllers, but it doesn’t need you to have your project structured in a specific way.
Adds TestTz functions to scripts that ends with “.spec.lua”.
Using it with other Code Editors
If you prefer Sublime Text, Atom, Vim, Notepad, etc, luckily, as Roblox LSP is a Language Server, it can be used in almost any code editor.
To do it, all you need is the server that you can found in the GitHub repository, and a Language Client for your Code Editor, the process is completely different for each code editor, so I can’t explain it here.
Keep in mind that depending on the code editor and the language client you use, some features of Roblox LSP will not work correctly or will not be available, the most recommended is to use Visual Studio Code, which already comes with an extension to install it easily.
Make sure you don’t have both Lua by sumneko and Roblox LSP installed.
If you have used sumneko’s lua before, you may have noticed that it had some weird bugs, many of them have been fixed in Roblox LSP.
If it doesn’t work correctly, make sure
Lua › Runtime: Versionis set to
Roblox LSP consumes a lot of RAM, but nothing worrisome.
The Language Server can only run on 64-bits computers.
If you have a Low-End computer, you will start to notice it slow from 700 lines of code, the performance depends only on the file you are editing, and there are other factors such as the complexity of the code. You can enable
Lua › Completion: Fast Autocompletion, although it is experimental and may not work correctly sometimes.
When the Language Server starts, it will load all the scripts one by one in your workspace (depending on how
Workspace: Load Modeis configured), this process may be slow, but the first script that will load will be the one you are editing and from there you can start coding.
The Roblox API updates automatically.
This topic may have many grammatical errors.