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.

Créez une ressource minimale

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

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 manifeste et le comportement de l’environnement d’exécution sont documentés dans la référence officielle des manifestes de ressources et le 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 même contexte. Utilisez RegisterNetEvent uniquement lorsqu’un événement doit franchir la frontière entre client et serveur. Le guide officiel de sécurisation des événements explique pourquoi chaque action réseau doit vérifier les permissions 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 figurent dans la référence officielle des commandes de serveur. Poursuivez avec le tutoriel officiel du premier script Lua avant d’ajouter des dépendances à un framework ou à une base de données.