Why Lua for FiveM?
Lua is the primary scripting language used in FiveM development, and for good reason. It is lightweight, fast to execute, and deeply integrated into the CitizenFX framework that powers FiveM. Whether you are building a simple command script or a complex roleplay system, understanding Lua fundamentals is the first step toward becoming a proficient FiveM developer. Unlike heavier languages, Lua gives you the performance overhead needed for real-time game server scripting where every millisecond counts.
Variables, Types, and Functions
Lua uses dynamic typing, meaning you do not need to declare variable types explicitly. Local variables are declared with the local keyword and are scoped to their block, while global variables are accessible everywhere but should be avoided in FiveM scripts for performance and security reasons. Functions in Lua are first-class values, meaning you can store them in variables, pass them as arguments, and return them from other functions. This flexibility is central to how FiveM event handlers and callbacks work.
Working with Tables
Tables are the most powerful data structure in Lua and serve as arrays, dictionaries, and objects all at once. In FiveM, you will use tables constantly to store player data, configuration options, and inventory items. A table can hold mixed key types and nested structures, making it extremely versatile. Understanding how to iterate tables with pairs() and ipairs() is essential for processing collections of data efficiently on both client and server sides.
Citizen.CreateThread and Game Loops
One of the most important FiveM-specific Lua functions is Citizen.CreateThread, which allows you to run asynchronous code without blocking the main game thread. Inside these threads, you typically use Citizen.Wait(ms) to control execution timing. A common pattern is creating a loop with while true do inside a thread, using wait intervals to check conditions or update game state. Getting the wait interval right is critical for performance, as a thread with Wait(0) runs every frame and should be reserved for tasks that genuinely need per-frame updates.
Events and Communication
FiveM scripts communicate through events, which are the backbone of client-server interaction. You register event handlers with RegisterNetEvent and AddEventHandler, then trigger them with TriggerEvent, TriggerServerEvent, or TriggerClientEvent. Understanding the distinction between client-side and server-side events is crucial for building secure scripts. Never trust data sent from the client without server-side validation, as malicious players can trigger any client-registered event with arbitrary data.
Getting Started with Your First Script
To create your first FiveM script, make a new folder in your resources directory, create a fxmanifest.lua with the resource metadata, and add a client or server Lua file. Start with something simple like a command that displays a notification or teleports the player. Test your changes by restarting the resource with the ensure command in the server console. As you grow more comfortable, explore native functions through the FiveM documentation and begin building more complex systems that combine client rendering with server-side logic.