Introduction au scripting Lua pour FiveM

Les ressources FiveM peuvent utiliser CfxLua, un runtime Lua 5.4 modifié, pour les scripts client et serveur. Une ressource actuelle commence par fxmanifest.lua, liste les fichiers que chaque contexte charge, et conserve les décisions faisant autorité telles que les permissions, l'argent et l'inventaire sur le serveur.

Les exemples de configuration et de code ici ciblent FiveM pour GTA V Legacy. Enhanced a des règles d'exécution et de compatibilité différentes ; vérifiez les changements Legacy-to-Enhanced de Cfx.re avant de les appliquer à un serveur Enhanced.

L'ancien __resource.lua manifest et le lua54 'yes' switch sont dépréciés pour les nouveaux travaux. Cfx.re indique que le support de Lua 5.3 a pris fin en juin 2025 et que les scripts actuels utilisent Lua 5.4.

Créez une ressource minimale

Dans votre répertoire de ressources resources server-data, créez [local]/hello_fivem. Les crochets regroupent les ressources ; la ressource elle-même est le répertoire. hello_fivem répertoire.

fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'

author 'Your name'
description 'Small CfxLua learning resource'
version '1.0.0'

client_script 'client.lua'
server_script 'server.lua'

client.lua:

RegisterCommand('mycoords', function()
    local coords = GetEntityCoords(PlayerPedId())
    print(('x=%.2f y=%.2f z=%.2f'):format(coords.x, coords.y, coords.z))
end, false)

server.lua:

AddEventHandler('onResourceStart', function(resourceName)
    if resourceName ~= GetCurrentResourceName() then
        return
    end

    print(('[%s] started'):format(resourceName))
end)

Le comportement du manifeste et du runtime est documenté dans le référence du manifeste de ressource et guide CfxLua.

Comprendre les contextes client et serveur

Un script client s'exécute séparément pour chaque joueur connecté et peut appeler des fonctions natives orientées jeu telles que PlayerPedId et GetEntityCoords. Un script serveur coordonne l'état partagé, la persistance et l'autorisation. Les valeurs fournies par un client sont des entrées, pas des preuves.

Utilisez AddEventHandler pour les événements qui doivent rester dans un seul contexte. Utilisez RegisterNetEvent uniquement lorsqu'un événement doit franchir la frontière client/serveur. Le guide officiel Sécurisez vos événements explique pourquoi chaque action réseau doit valider la permission et l'état actuels du joueur côté serveur.

Évitez de bloquer le planificateur

Les scripts CfxLua utilisent un ordonnancement coopératif. Une boucle qui ne rend jamais la main peut bloquer son contexte d’exécution. Lorsqu’une boucle doit attendre, utilisez Wait avec un délai approprié à la tâche, et ne sondez pas une base de données ou un point de terminaison HTTP à chaque image. Préférez les événements et les changements d'état au sondage permanent.

Utilisez des exports pour une limite de ressource claire

Un export expose une fonction nommée à une autre ressource. Définissez-la explicitement et documentez ses arguments et sa valeur de retour :

exports('formatPlayerLabel', function(serverId, playerName)
    return ('[%d] %s'):format(serverId, playerName)
end)

Une autre ressource Lua peut l'appeler comme exports.hello_fivem:formatPlayerLabel(id, name). N'utilisez pas d'export pour contourner les vérifications d'autorisation ou de propriété.

Exécutez et testez la ressource

1. Sauvegardez la ressource que vous remplacez, le cas échéant.
2. Dans la console du serveur, exécutez refresh puis ensure hello_fivem.
3. Vérifiez le message de démarrage dans la console du serveur.
4. Connectez-vous au serveur de développement, ouvrez F8 et exécutez mycoords.
5. Ajoutez ensure hello_fivem à server.cfg après toutes les dépendances, puis redémarrez le serveur pour confirmer le démarrage normal.

Les commandes de ressources prises en charge sont listées dans la référence des commandes de serveur. Continuez avec le premier tutoriel de script Lua avant d'ajouter des dépendances de framework ou de base de données.