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.

Compile-time hashes

Because you might often have to deal with ‘Jenkins one-at-a-time’ hashes in GTA/RAGE, the Lua runtime has been extended to have support for compile-time generation of hash keys, similar to GET_HASH_KEY, however with zero runtime overhead.

For example:

-- getting
RequestModel(`adder`)

-- comparing
if GetEntityModel(vehicle) == `buzzard` then
  print("Indeed, it's a Buzzard.")
end

-- printing
print(`a_m_y_skater_01`)

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:

Inside hello_explicit.lua:

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

Inside fxmanifest.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

Last modified January 6, 2021: Work on docs for the new doc FE (6433552)