PiTyUs.Hire me

Engineering

Typing your FiveM Lua with annotations

Use Lua Language Server annotations in FiveM scripts: ---@param, ---@return, ---@class and ---@field for player and config tables, ---@alias for string unions, ---@type, typing exports and events, and how annotations catch bugs before the server starts.

Updated 9 min readBy PiTyUs · FiveM developer

Overview

Lua is dynamically typed, which is great for quick scripts and painful in a 5,000-line resource. Lua Language Server annotations — special ---@ comments — give you types without changing how the code runs: autocompletion for your own tables, warnings for wrong arguments and documentation on hover.

Functions

server.lualua
---@alias MoneyAccount 'cash' | 'bank'

---Pays a player and logs the reason.
---@param src number Server ID of the player
---@param account MoneyAccount
---@param amount integer Must be positive
---@param reason? string Optional log reason
---@return boolean ok
local function pay(src, account, amount, reason)
    if amount <= 0 then return false end
    return Bridge.addMoney(src, account, amount, reason)
end

pay(1, 'cahs', 100) -- warning: 'cahs' is not a MoneyAccount

Table shapes with @class

config.lualua
---@class GarageConfig
---@field label string
---@field coords vector3
---@field spawn vector4
---@field jobs? string[] Only these jobs may use it

---@type table<string, GarageConfig>
Config.Garages = {
    legion = {
        label = 'Legion Square',
        coords = vec3(215.8, -810.1, 30.7),
        spawn = vec4(229.7, -800.1, 30.5, 157.8),
    },
}

Now Config.Garages.legion. autocompletes its fields, and a missing spawn or a typo like cords shows a warning. Config design is covered in config.lua best practices.

The annotations you will use most

AnnotationUse
---@param name typeFunction parameter (name? for optional)
---@return type nameReturn value
---@class NameDeclare a table type
---@field name typeA field of the class above
---@type TType of the next variable
---@alias Name 'a' | 'b'Named union type
---@deprecatedWarn when something old is used
---@metaA definitions-only file (for exports other resources call)

Typing exports for other resources

Put ---@meta definition files in your resource (for example types/exports.lua) describing its exports; other developers can add the resource to their workspace.library and get completion for exports.yourres:.... ox_lib does exactly this, which is why its functions autocomplete — see VS Code setup.

Frequently asked questions

Do Lua annotations slow down FiveM?

No. They are comments and are ignored when the script runs.

What tool reads the annotations?

The Lua Language Server (the “Lua” extension in VS Code).

How do I mark an optional parameter?

Add a question mark: ---@param reason? string.

Can I type a table of configs?

Yes: declare a ---@class with ---@fields and use ---@type table<string, YourClass>.

Need this built, not just explained?

Ten years of FiveM work, from Lua to NUI

Custom resources, React NUI, ESX / QBCore / Qbox integration, OneSync performance audits and security reviews — plus the websites and SEO around your server brand.

Talk on DiscordSee services

Related guides

All FiveM guides