Comment créer votre premier script FiveM en Lua : tutoriel pas à pas

Apprendre comment créer un script FiveM en Lua constitue la première étape pour personnaliser votre serveur et offrir une expérience unique à vos joueurs en 2025. Que vous souhaitiez développer des systèmes de jobs, des interactions immersives ou des mécaniques de jeu innovantes, la maîtrise du langage Lua et de l’API FiveM vous ouvre des possibilités infinies. Ce guide complet vous accompagne pas à pas, de la configuration de votre environnement de développement jusqu’à la publication de votre première ressource fonctionnelle.

Pourquoi choisir Lua pour développer sur FiveM ?

Le langage Lua s’impose comme le standard du développement FiveM pour plusieurs raisons techniques et pratiques. Sa syntaxe simple et épurée permet aux débutants de produire rapidement des scripts fonctionnels, tout en offrant aux développeurs expérimentés une flexibilité remarquable pour des projets complexes.

Les avantages du Lua dans l’écosystème FiveM

Lua présente un temps d’exécution ultra-rapide, essentiel pour maintenir des performances optimales sur des serveurs accueillant jusqu’à 128 joueurs simultanés. Ce langage léger consomme peu de ressources mémoire, contrairement à d’autres langages de script. La communauté FiveM a développé une documentation exhaustive et des milliers d’exemples open-source qui facilitent l’apprentissage.

L’intégration native de Lua avec l’API FiveM permet d’accéder directement aux fonctions du jeu GTA V, de manipuler les entités, de créer des événements réseau et de gérer les interactions joueur-serveur. Cette synergie technique explique pourquoi plus de 95% des ressources FiveM sont développées en Lua plutôt qu’en C# ou JavaScript.

Structure d’un projet FiveM moderne

Un script FiveM se compose de plusieurs éléments obligatoires et optionnels. Le fichier fxmanifest.lua constitue le point d’entrée de toute ressource, définissant les métadonnées, les fichiers client et serveur, ainsi que les dépendances. Voici un exemple de structure de base :

mon-script/
├── fxmanifest.lua
├── client/
│   └── main.lua
├── server/
│   └── main.lua
├── config.lua
└── README.md

Cette organisation modulaire facilite la maintenance et le débogage. Les fichiers client s’exécutent sur l’ordinateur de chaque joueur, tandis que les fichiers serveur tournent sur votre machine hébergeant FiveM. La séparation stricte entre ces deux environnements constitue un principe fondamental de la sécurité et des performances.

Configuration de votre environnement de développement Lua

Avant de créer votre premier script FiveM en Lua, vous devez préparer un environnement de travail professionnel. Cette étape initiale vous fera gagner des dizaines d’heures de débogage et facilitera grandement votre progression.

Choix et configuration de l’éditeur de code

Visual Studio Code s’impose comme l’éditeur de référence pour le développement FiveM en 2025. Gratuit et extensible, il offre la coloration syntaxique, l’auto-completion et le débogage intégré. Installez les extensions suivantes pour optimiser votre productivité :

• Lua Language Server : fournit l’auto-completion intelligente et la détection d’erreurs en temps réel
• FiveM Natives : intègre la documentation complète des fonctions natives de FiveM
• Better Comments : améliore la lisibilité de vos annotations de code
• Bracket Pair Colorizer : visualise les blocs de code imbriqués

Configurez ensuite votre workspace en créant un fichier .vscode/settings.json qui définit les chemins Lua et active les suggestions contextuelles. Cette configuration reconnaît automatiquement les natives FiveM et vous propose des extraits de code prêts à l’emploi.

Installation d’un serveur de test local

Pour tester vos scripts en conditions réelles, installez un serveur FiveM local sur votre machine. Téléchargez les fichiers serveur depuis le dépôt officiel FiveM, extrayez-les dans un dossier dédié, puis créez un fichier server.cfg minimal :

endpoint_add_tcp "0.0.0.0:30120"
endpoint_add_udp "0.0.0.0:30120"
sv_maxclients 8
set sv_licenseKey "votre_clé_ici"
start mon-script

Lancez le serveur via la commande FXServer.exe +exec server.cfg et connectez-vous depuis votre client GTA V en utilisant F8 puis connect localhost:30120. Vous disposez maintenant d’un environnement de développement complet et isolé.

Ressources essentielles pour héberger professionnellement

Si le serveur local convient pour le développement, un hébergement professionnel devient indispensable pour accueillir vos joueurs. Les solutions d’hébergement FiveM spécialisées garantissent des performances stables, une protection anti-DDoS et un support technique réactif, éléments cruciaux pour maintenir une communauté active et satisfaite.

Créer votre premier script FiveM fonctionnel

Maintenant que votre environnement est configuré, passons à la pratique en créant un script complet qui illustre les concepts fondamentaux du développement FiveM en Lua. Nous allons développer un système de téléportation entre points d’intérêt.

Le fichier manifest : déclarer votre ressource

Créez un dossier teleport-system dans votre répertoire resources, puis ajoutez-y un fichier fxmanifest.lua :

fx_version 'cerulean'
game 'gta5'

author 'Votre Nom'
description 'Système de téléportation entre points'
version '1.0.0'

client_scripts {
    'config.lua',
    'client/main.lua'
}

server_scripts {
    'server/main.lua'
}

Cette déclaration indique à FiveM la version du framework (cerulean étant la plus récente en 2025), le jeu ciblé, et les fichiers à charger. L’ordre de chargement des scripts est crucial : config.lua doit être chargé avant main.lua pour que les variables de configuration soient disponibles.

Configuration centralisée des paramètres

Créez un fichier config.lua pour centraliser les paramètres modifiables sans toucher au code principal :

Config = {}

Config.TeleportPoints = {
    {
        name = "Commissariat LSPD",
        coords = vector3(425.1, -979.5, 30.7),
        marker = {r = 0, g = 100, b = 255, a = 100}
    },
    {
        name = "Hôpital Central",
        coords = vector3(298.7, -584.5, 43.3),
        marker = {r = 255, g = 0, b = 0, a = 100}
    },
    {
        name = "Garage Mécanique",
        coords = vector3(-356.8, -133.7, 39.0),
        marker = {r = 255, g = 165, b = 0, a = 100}
    }
}

Config.MarkerType = 1
Config.MarkerSize = {x = 1.5, y = 1.5, z = 0.5}
Config.TeleportKey = 38 -- Touche E

Cette approche modulaire permet aux administrateurs de serveur de personnaliser les points de téléportation sans connaissances en programmation.

Développement du script client

Dans client/main.lua, implémentez la logique d’affichage des marqueurs et de détection de proximité :

local playerInZone = false
local currentZone = nil

Citizen.CreateThread(function()
    while true do
        Citizen.Wait(0)
        local playerPed = PlayerPedId()
        local playerCoords = GetEntityCoords(playerPed)
        local isInZone = false
        
        for k, point in pairs(Config.TeleportPoints) do
            local distance = #(playerCoords - point.coords)
            
            if distance < 10.0 then
                DrawMarker(
                    Config.MarkerType,
                    point.coords.x, point.coords.y, point.coords.z,
                    0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
                    Config.MarkerSize.x, Config.MarkerSize.y, Config.MarkerSize.z,
                    point.marker.r, point.marker.g, point.marker.b, point.marker.a,
                    false, true, 2, false, nil, nil, false
                )
                
                if distance < 1.5 then
                    isInZone = true
                    currentZone = k
                    DrawText3D(point.coords.x, point.coords.y, point.coords.z + 1.0, 
                        "Appuyez sur ~g~E~w~ pour vous téléporter")
                end
            end
        end
        
        if isInZone and not playerInZone then
            playerInZone = true
        elseif not isInZone and playerInZone then
            playerInZone = false
            currentZone = nil
        end
        
        if not isInZone then
            Citizen.Wait(500)
        end
    end
end)

Citizen.CreateThread(function()
    while true do
        Citizen.Wait(0)
        if playerInZone and IsControlJustReleased(0, Config.TeleportKey) then
            TeleportToNextPoint()
        end
    end
end)

function TeleportToNextPoint()
    local nextIndex = currentZone % #Config.TeleportPoints + 1
    local nextPoint = Config.TeleportPoints[nextIndex]
    local playerPed = PlayerPedId()
    
    DoScreenFadeOut(500)
    Citizen.Wait(500)
    
    SetEntityCoords(playerPed, nextPoint.coords.x, nextPoint.coords.y, nextPoint.coords.z, false, false, false, true)
    
    Citizen.Wait(500)
    DoScreenFadeIn(500)
    
    ShowNotification("Téléporté vers : ~b~" .. nextPoint.name)
end

function DrawText3D(x, y, z, text)
    local onScreen, _x, _y = World3dToScreen2d(x, y, z)
    local px, py, pz = table.unpack(GetGameplayCamCoords())
    
    SetTextScale(0.35, 0.35)
    SetTextFont(4)
    SetTextProportional(1)
    SetTextColour(255, 255, 255, 215)
    SetTextEntry("STRING")
    SetTextCentre(1)
    AddTextComponentString(text)
    DrawText(_x, _y)
end

function ShowNotification(text)
    SetNotificationTextEntry("STRING")
    AddTextComponentString(text)
    DrawNotification(false, false)
end

Gestion côté serveur et événements réseau

Dans server/main.lua, ajoutez la logique serveur pour valider et journaliser les téléportations :

RegisterNetEvent('teleport:log')
AddEventHandler('teleport:log', function(destination)
    local source = source
    local playerName = GetPlayerName(source)
    local identifier = GetPlayerIdentifiers(source)[1]
    
    print(string.format("[TELEPORT] %s (%s) s'est téléporté vers : %s", 
        playerName, identifier, destination))
end)

Cette architecture client-serveur garantit que les actions importantes sont tracées côté serveur, où les joueurs ne peuvent pas les manipuler. Pour un système de téléportation complet, vous pourriez ajouter des vérifications de permissions, des cooldowns, ou des coûts en monnaie virtuelle.

Optimisation et bonnes pratiques du développement Lua

Un script fonctionnel ne suffit pas : il doit également être performant, sécurisé et maintenable. Ces bonnes pratiques professionnelles distinguent un développeur amateur d’un expert reconnu dans la communauté FiveM.

Gestion efficace des threads et performances

Le plus grand piège des débutants consiste à utiliser Citizen.Wait(0) dans des boucles inutiles. Chaque thread actif consomme des ressources processeur. Optimisez systématiquement vos intervalles de vérification :

Utilisez la commande resmon dans la console F8 pour surveiller en temps réel la consommation de vos ressources. Un script bien optimisé ne devrait jamais dépasser 0.5 ms de temps d’exécution avec 32 joueurs connectés.

Sécurisation contre les exploits

Ne faites jamais confiance au client. Toute action sensible (ajout d’argent, modification d’inventaire, téléportation, etc.) doit être validée côté serveur. Implémentez des vérifications de distance, de permissions et de cooldowns :

-- ❌ MAUVAIS : validation côté client uniquement
RegisterCommand('givemoney', function()
    TriggerEvent('esx:addMoney', 50000)
end)

-- ✅ BON : validation serveur stricte
RegisterCommand('givemoney', function()
    TriggerServerEvent('admin:requestMoney', 50000)
end)

-- server/main.lua
RegisterNetEvent('admin:requestMoney')
AddEventHandler('admin:requestMoney', function(amount)
    local source = source
    if IsPlayerAdmin(source) and amount <= 100000 then
        -- Ajouter l'argent après vérifications
    else
        BanPlayer(source, "Tentative d'exploitation")
    end
end)

Documentation et maintenance du code

Commentez vos fonctions complexes en utilisant le format LuaDoc pour générer automatiquement une documentation :

--- Téléporte un joueur vers des coordonnées spécifiques avec effet de fondu
-- @param playerPed number L'entité du joueur à téléporter
-- @param coords vector3 Les coordonnées de destination
-- @param fadeDuration number Durée du fondu en millisecondes
-- @return boolean Succès de l'opération
function TeleportPlayer(playerPed, coords, fadeDuration)
    -- Implémentation
end

Cette discipline documentaire facilite la collaboration avec d’autres développeurs et la reprise de vos projets après plusieurs mois d’inactivité.

Débogage avancé et résolution d’erreurs

Utilisez les natives de débogage FiveM pour tracer l’exécution de votre code :

-- Affichage de variables dans la console F8
print(string.format("Position du joueur : %s", json.encode(playerCoords)))

-- Vérification de type pour éviter les erreurs nil
assert(Config.TeleportPoints, "Configuration des points de téléportation manquante")

-- Gestion d'erreurs avec pcall
local success, result = pcall(function()
    return PerformDangerousOperation()
end)

if not success then
    print("Erreur interceptée : " .. tostring(result))
end

La console serveur affiche également les erreurs Lua avec numéros de ligne. Activez le mode développeur dans votre server.cfg avec set developer 1 pour obtenir des messages d’erreur détaillés.

Publier et distribuer votre script FiveM

Une fois votre script testé et optimisé, vous pouvez le partager avec la communauté ou le commercialiser. Cette étape finale demande autant de rigueur que le développement lui-même.

Préparation du package de distribution

Créez un fichier README.md complet incluant les prérequis, instructions d’installation, configuration, captures d’écran et changelog. Ajoutez une licence open-source (MIT, GPL) ou commerciale selon vos intentions. Nettoyez votre code des commentaires de débogage et variables de test.

Plateformes de partage et monétisation

Les développeurs FiveM publient généralement leurs créations sur GitHub pour les projets open-source, ou sur des marketplaces spécialisées comme Tebex et FiveM Store pour les scripts premium. La qualité du support après-vente différencie les développeurs professionnels qui génèrent des revenus réguliers de ceux qui abandonnent leurs projets.

Avant de commercialiser un script, assurez-vous qu’il fonctionne sur diverses configurations de serveur, est compatible avec les frameworks populaires (ESX, QBCore, VRP), et propose une documentation professionnelle. Les scripts vendus entre 15€ et 150€ selon leur complexité et leur unicité sur le marché.

Créer un script FiveM en Lua représente un parcours d’apprentissage gratifiant qui ouvre des opportunités créatives et professionnelles. En maîtrisant les fondamentaux présentés dans ce guide, vous disposez désormais des connaissances pour développer vos propres ressources personnalisées. La pratique régulière, l’étude de scripts open-source existants et l’implication dans la communauté accéléreront votre progression vers l’expertise technique.

FAQ

Hébergez votre serveur FiveM maintenant