Definition files for the Lua-Language-Server extension

The Lua language server is a powerful tool that enhances the development experience for Lua programming. It provides a comprehensive set of code editing features, including suggestions, auto-completion, and error checking. With the Lua language server, developers can effortlessly navigate through their resource files, access documentation easily, and ensure code correctness by giving warnings. The files in this repository are used to set the syntax and types for Multi Theft Auto related Lua components.

Why should you care?

• The language server will inform you about all sorts of problems: type mismatches, missing function arguments, missing variables, etc.
• You have access to a lot of MTA syntax/autocomplete out of the box. The syntax information will remain while writing.
• You do not have to restart your resource so often in order to validate if everything is working.

Links and info

• Feature list of Lua-Language-Server
• More info about annotations
• Text editors support

Installation Lua-Language-Server extension

• Visual Studio Code

  • Go to extensions:

  

  • and search for Lua Language Server Coded by Lua by sumneko

  

  • And click on the install button

• Sublime

  • Open the command panel

    ctrl + shift + p
    

  • Run the following command

    Package Control: Install Package
    

  • Search for LSP (Language Server Protocol) and click on it.

  • Repeat the same command, search for LSP-lua and click on it. This is for Lua language support.

How to use the definition files?

The first step is to place the definition files at a location which you can find back.

Visual Studio Code

In the extension settings you can set a destination folder for the definition files.

1. Right click on extension > extension settings.

2. Search for workspace.library

3. Click on add item

4. Fill in the file path of the definition files.

For example:

C:\Program Files (x86)\MTA San Andreas 1.6\repos\mta-annotations-for-lua-language-server

If that doesn't work / can't find it. Just drop the definition folder right in your project.

Sublime

To make this work, you have to open the Lua settings file for defining the definition directory.

Command panel:

ctrl + shift + p

Search for:

Preferences: LSP-lua Settings

Or alternative:

Add a library file path override. You probably need to escape the following characters \ like this \\.

// Settings in here override those in "LSP-lua/LSP-lua.sublime-settings"
{
	"settings": {
		"Lua.workspace.library": ["DIRECTORY"]
	}
}

For example:

{
	"settings": {
		"Lua.workspace.library": ["C:\\Program Files (x86)\\MTA San Andreas 1.6\\repos\\mta-annotations-for-lua-language-server"],
		"Lua.runtime.version": "Lua 5.1"
	}
}

Also the runtime version (Lua 5.1) is set correctly (for MTA) in this example.

Find here info about definition files in general.

Other things to do

• Make sure to set the correct Lua runtime version in the extension config, for MTA it is: Lua 5.1

• Visual Studio Code Lua version

  • See previous step for showing up the settings menu.

  • Search with the text version.

  

  • Change the version to 5.1

  

  You might need to restart the editor!

• Sublime Lua version

  • See previous step for showing up the settings menu.

  Add the following line to the JSON file:

  "Lua.runtime.version": "Lua 5.1"
  

  like this:

  {
      "settings": {
          "Lua.workspace.library": ["C:\\Program Files (x86)\\MTA San Andreas 1.6\\repos\\mta-annotations-for-lua-language-server"],
          "Lua.runtime.version": "Lua 5.1"
      }
  }

  You might need to restart the editor!

• Disable the following diagnostic for your work files (you can also do it globaly in the workspace)

---@diagnostic disable: lowercase-global

• When creating your own definition files, disable the following diagnostics for those specific files

---@diagnostic disable: lowercase-global
---@diagnostic disable: missing-return

Known issues ⚠️

• Make sure to always have an empty new line at the end of your files, as recommended in this issue.

• Currently, the Lua server language definition files do not have a clear separation between serverside functions/events and clientside functions/events. However, it is possible to enforce this separation for specific functions if needed.

outputChatBox--[[@as outputChatBox_server]]("Serverside", player)

• In some cases, certain functions in the Lua server language definition files may return multiple types, even if you have selected a different syntax. To address this situation, you can use the cast or as notation to explicitly specify the desired type or adjust the return type.

Side note

• There are probably some mistakes in it. If you come across those, just go to the type definition files and fix it. You can also make a pull request!

Forcing types

cast keyword

Change the type of a variable to (a) different one(s). Wiki @cast

local varName = exampleFunc()
---@cast varName string

local varName = exampleFunc()
---@cast varName string | number

as keyword

Change the type of an expression to (a) different one(s). Wiki @as

local varName = exampleFunc() --[[@as string]]

local varName = exampleFunc() --[[@as string | number]]

Alias

Sometimes you want to use one or multiple types and re-use them at multiple places. Wiki @alias

Just a small example what you can do, visit the wiki for more info.

---@alias singleType integer
---@alias multiType string | integer
---@alias valueSpecific "verySpecific" | 555

---@param param1 singleType
---@param param2 multiType
---@param param3 valueSpecific
function example (param1, param2, param3)

end

example(123, "", "verySpecific") -- OK
example(123) -- Warning: This function requires 3 argument(s) but instead it is receiving 1.Lua Diagnostics.(missing-parameter)
example(123, 123, 555) -- OK
example(123, 123, 444) -- Warning: Cannot assign `integer` to parameter `"verySpecific"|555`.

Credits

Many thanks to Subtixx's dataset. These saved me a lot of time creating all those definitions.

Many thanks to the community for all the syntax and descriptions.

For the newest version?

MTA annotations for Lua-Language-Server

Current version 1.0.0