Lua Language Server - Definition files

[IIYAMA]

Lua Language Server - Definition files

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.

 

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.

 

Type validation

Having value type validation in your code editor is one of the main key features of the Lua Language Server. When working with variables, parameters, and arguments in Lua, you are not restricted to specific value types. This flexibility can make mistakes more likely to happen. However, being able to validate those mistakes instantly saves you a lot of time and frustration.

Spoiler

In the following example, we will be discussing type validation.

The code snippet below places a random player at the position (0, 0, 20).

local player = getRandomPlayer()

setElementPosition(player, 0, 0, 20)

However, an issue arises as I receive the following warning:

Cannot assign `userdata|false` to parameter `userdata`.

- `false` cannot match `userdata`

- Type `false` cannot match `userdata`

(param-type-mismatch)

In this example, `userdata` represents a MTA element. The `setElementPosition` function expects to receive a `userdata` (element) type, but it is receiving either `userdata` or `false` type.

Let's analyze the `getRandomPlayer` function:

When I place my cursor on the `getRandomPlayer` function, you can see that it returns `false` when there are no players on the server. Therefore, the `player` variable can contain either a player `userdata` or `false`, depending on the player count.

 userdata  false

 

To resolve this warning, we can add an `if` statement to check if the `player` variable has a value that is not `nil` and not `false`.

local player = getRandomPlayer()
if player then
    setElementPosition(player, 0, 0, 20)
end

Now, only the player `userdata` is accessible within the `if` statement.  userdata  false 

 

Type annotations for your own functions

Adding type annotations to your own functions can help improve validation and catch logic mistakes. It is particularly useful when calling functions from different parts of your code, as the annotations provide clarity on the expected input (arguments) and output (return values).

Additionally, comments that are placed above or adjacent to a variable or function are visible when hovering over them in another file or line. This can provide helpful information and context when working with the code.

How that looks like:

How can I quickly add annotations in less than a second? Open the spoiler:

Spoiler

Starting with a basic function.

Spoiler

function sum (a, b)
    return a + b
end

Typing --- lines before the function name, will show this option.

 

Press enter

Spoiler

---comment
---@param a any
---@param b any
---@return unknown
function sum (a, b)
    return a + b
end

Fill in the comment if you want. (optional)

Press tab to go to the next one.

Type number for a and b

And return a number as well.

 

Final result:

Spoiler

---@param a number
---@param b number
---@return number
function sum (a, b)
    return a + b
end

When you hover over the sum function, you can see that it takes in 2 numbers and returns 1.

Adding these annotations can take less than 1 second of your time (that is if you auto complete also the type's).

 

---

 

What did we gain from our previous work?

 

The first benefit is showing us a warning if you are missing any required arguments.

 

The second one is showing us a warning about a type mismatches.

For example if we have this code:

local inputA = 123
local inputB = "123"
sum(inputA, inputB)

The editor will warn us when we are using a string in our sum function.

 

Lets quickly fix that and return our result.

local inputA = 123
local inputB = 123
local result = sum(inputA, inputB)

 

Now lets make another mistake.

This time we want to enable birds when the result is higher than 10. Before we added the annotation, you wouldn't have noticed the mistake below.

local inputA = 123
local inputB = 123
local result = sum(inputA, inputB)

setBirdsEnabled(result)

This warning indicates that the setBirdsEnabled function expects a boolean on it's first argument. But we gave it a number, which resulted in an angry . I mean a warning... ughm.

Lets fix that as well:

local inputA = 123
local inputB = 123
local result = sum(inputA, inputB)

setBirdsEnabled(result > 10) -- Operators: https://www.lua.org/pil/3.2.html

 

 

AddEventHandler auto-complete

Most MTA addEventHandler functions have full eventName autocompletion. And the attached anonymous function is fully autocompleted and typed as well.

Spoiler

1. `eventName`
   
    
2. `attachedTo` element
   
    
3. Function
   
    
4. When clicking on fun(weapon: 0|1|10|11|12... (screenshot above), it will autocomplete an anonymous function with all parameters:
   
5. Hovering over the parameters:
   
   

 

 

 

 

Navigation features of Lua Language Server

It can be time consuming to find out where a (global) function or variable is located. Being able to jump right to it, saves you a lot of time.

Spoiler

1. Go to Definition: Developers can quickly jump to the definition of a function, variable, or class within their codebase, allowing for easy exploration and understanding of code structure. (vscode: right click > Go to Definitions)
   
2. Find References: The Lua language server enables developers to locate all the places where a specific function, variable, or class is referenced throughout their code. (vscode: right click > Go to References)
   
3. Symbol Search: With the Lua language server, developers can quickly search for specific symbols (such as functions or variables) within their codebase.  (vscode: ctrl + t)
   

 

 

Other information which you can find in the readme

• Installation for the Lua Language Server
• How to use the definition files?

 

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 certain cases, certain functions in the Lua server language definition files may return multiple types, even if you have selected a different syntax. To handle this situation, you can use the `cast` or `as` notation to explicitly specify the desired type or adjust the returned type. See `Casting and as` syntax below.

 

Casting and as

In certain situations, you may have a strong understanding of the type(s) that a variable or expression will have. This is where the keywords "cast" and "as" come into play. These keywords enable you to explicitly specify the intended type, ensuring proper type handling.

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

Spoiler

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

---

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

---

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

 

 

Download

The definition files can be downloaded here.

 

[sacr1ficez]

I assume both annotations and go to definition (particularly variable, because you can already go to function definition) works for Sublime Text 4 as well?

[IIYAMA]

23 minutes ago, srslyyyy said:

I assume both annotations and go to definition (particularly variable, because you can already go to function definition) works for Sublime Text 4 as well?

Yes, that is indeed the case.

(Sublime)

 

 

[sacr1ficez]

After some testing i could just say: wow. Just for the sole fact of updated syntax this is amazing (although there is mistakes to be found), and the latter is just spicy addition.

[IIYAMA]

For those that have already downloaded the definition files. In the last week, there have been some missing/incorrect types being discovered and fixed. See here the list of changes.

Thanks to @srslyyyy for helping me with that!

[FernandoMTA]

This is incredible. I use it with the VSCode Error Lens extension, it's so useful!
https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens

THANK YOU  

[FernandoMTA]

I opened a merge request to add two little client function defs that were missing

[IIYAMA]

5 hours ago, FernandoMTA said:

I opened a merge request to add two little client function defs that were missing

Merged!

[Ex_Asfh]

On 15/02/2024 at 22:09, IIYAMA said:

Yes, that is indeed the case.

(Sublime)

 

 

What Your IDE Name For Lua Code ?

Edited April 9, 2024 by Ex_Asfh

[IIYAMA]

On 09/04/2024 at 13:12, Ex_Asfh said:

What Your IDE Name For Lua Code ?

Visual Studio Code (for everything).

While I must say that I definitely love Sublime it's responsiveness, but it was (for me) not enough to change editors.

[IIYAMA]

There have been some updates for the new 1.6 functions, but it is still an ongoing process. Feel free to pull for newest version if you want to try out some of the new stuff with it's up to date syntax. Of course for the patches as well.

Special thanks to:

@srslyyyy @FernandoMTA

 

Known syntax to-do's in the near future:

• fxCreateParticle (wiki link) Done!
  by FileEX

• EngineSet/GetPoolCapacity
  by TheNormalnij

[FernandoMTA]

@IIYAMA I opened an issue on the repository so we can add the new funcs and events

[IIYAMA]

4 hours ago, FernandoMTA said:

@IIYAMA I opened an issue on the repository so we can add the new funcs and events

I have added the missing file/directory path functions.

For the rest of the missing functions events please check: issue

[Yeleha]

Opened an issue for a typo, waiting for merge

[IIYAMA]

2 hours ago, Yeleha said:

Opened an issue for a typo, waiting for merge

Thx, merged!

[IIYAMA]

Did you know that the definition file counts up to a whopping 1364 unique functions? While the actual value might be higher or lower (missing, unknown, class/OOP or deprecated functions). Having this amount of functions in MTA is an incredible accomplish by this community.

Some other statistics:

• 125 client unique events
• 88 server unique events