Scripting in Lua

FiveM supports the general purpose programming language Lua as one of its scripting languages. Lua is a very easy language to learn, simple to use and fast to write. To use Lua, just use .lua in your scripts file extensions.

A modified version of Lua 5.3 is used in FiveM, called CfxLua. This version includes some of the modifications the Grit game engine introduced:

To learn more about Lua, read their official documentation.

Using Lua

To use Lua in your scripts, simply use the .lua file extension. No additional configuration is required.

Relative path literals

As is the case in Grit, CfxLua provides support for relative path literals using backticks. This allows you to express a relative file path in your code, which can sometimes be more convenient than absolute file paths. Relative path literals will be resolved from their current file and cannot descend below the root of your resource.

print(`foo`)
print(`/dir/foo`)
print(`../foo`)
print(`.`)

Strings within backticks are assumed to be a path. If the path starts with a /, it will behave as an absolute path, not any different from a normal string. Any other path is assumed to be relative, and will be resolved using the directory of the currently executing Lua file. Descending below the root of your resource will raise an error.

assert(`foo/../bar` == `bar`)
assert(`foo/../bar/.` == `bar`)
assert(`./foo/../bar` == `bar`)
assert(`/.` == `/`)

Vectors & quaternions

FiveM supports first-class vectors and quaternions in Lua. Vectors and quaternions are incredibly useful to represent things like positions, rotations or even colors. For performance reasons, vectors and quaternions are real data types in CfxLua, just like booleans, numbers and strings are.

Many native functions return and accept vectors too. They’re commonly used for world positions and standard euler rotations, so use them whenever you can. More about there here.

For usage and examples see their respective docs:

Using exports

You can define exports by calling the global exports object:

hello.lua:

exports('SayHello', function(str)
  print('Hello, ' .. tostring(str) .. '!')
end)

You can also define an export or server_export entry in your resource manifest. Functions need to be global to be ‘explicitly’ exported. Note that these exports will only be available after the first scheduler tick.

For example:

hello_explicit.lua:

function SayHello(str)
  print('Hello, ' .. tostring(str) .. '!')
end

__resource.lua:

-- Client:
client_script 'hello.lua'
export 'SayHello'

-- Or server:
server_script 'hello.lua'
server_export 'SayHello'

In another resource:

-- Prints 'Hello, world!'
exports.myresource:SayHello('world')

External libraries

The Lua runtime exposes some libraries on the global scope which you can use.

Lua specific functions