Configuration FiveM VS Code : serveur de langage Lua, natives, pas de faux avertissements

Vous ouvrez un script parfaitement bon dans VS Code et cela ressemble à ceci :

Undefined global `PlayerPedId`.

Chaque native, exports, ESX et QBCore reçoit un trait jaune, et les véritables erreurs se noient dans le bruit. Ce guide configure VS Code pour qu'il comprenne Lua FiveM, et vous avertit uniquement des choses qui sont réellement fausses.

#Installer un serveur de langage Lua

Dans le panneau Extensions, installez une extension serveur de langage Lua. Celle largement utilisée est l'extension "Lua" par sumneko, qui est construite sur Lua Language Server (LuaLS). Elle vous donne la complétion, aller à la définition, renommer et les diagnostiques.

Ouvrez votre dossier de resources comme l'espace de travail (pas un seul fichier), pour que le serveur puisse voir chaque script et les paramètres que vous allez ajouter.

#Ajouter les définitions FiveM natives

LuaLS simple n'a aucune idée de ce que GetEntityCoords prend. La communauté entretient des typages pour FiveM / CfxLua : un ensemble de fichiers d'annotation qui décrivent les natives, les globals Cfx.re et la syntaxe Lua supplémentaire que FiveM permet. Recherchez dans le panneau Extensions "CfxLua" ou "FiveM natives", ou recherchez un add-on "FiveM" dans le gestionnaire d'add-ons LuaLS, et choisissez celui qui est activement maintenu.

Avec eux installés, vous obtenez des signatures quand vous tapez :

local ped = PlayerPedId()
local coords = GetEntityCoords(ped)

Passez la souris sur un native et les paramètres et les types de retour s'affichent. La plupart des typages incluent également exports, les annotations lib si vous ajoutez les définitions ox_lib, et la table cache.

Conseil : Les noms d'extensions et les paramètres changent au fil du temps. Si un paramètre ci-dessous n'existe pas dans votre version, vérifiez le README de l'extension lui-même, qui est toujours plus actuel qu'un tutoriel.

#Paramètres de l'espace de travail

Créez .vscode/settings.json à la racine de votre dossier de resources. Cela garde les paramètres avec le projet, donc tout le monde qui l'ouvre obtient le même comportement :

{
  "Lua.runtime.version": "Lua 5.4",
  "Lua.runtime.nonstandardSymbol": [
    "/**/", "`", "+=", "-=", "*=", "/=", "<<=", ">>=", "&=", "|=", "^="
  ],
  "Lua.diagnostics.globals": [
    "ESX", "QBCore", "Config", "Locales", "PlayerData",
    "lib", "cache", "exports"
  ],
  "Lua.workspace.checkThirdParty": false,
  "Lua.workspace.ignoreDir": [".vscode", "node_modules", "dist"]
}

Ce que chaque partie fait :

• Lua.runtime.version correspond à lua54 'yes' dans votre fxmanifest.lua.
• nonstandardSymbol dit à l'analyseur que l'affectation composée de FiveM (x += 1) et les hashes à backtick sont valides. Sans cela, le code parfaitement bon est signalé comme une erreur de syntaxe.
• Lua.diagnostics.globals liste les noms que le script définit quelque part que le serveur ne peut pas tracer. Ajoutez le vôtre : ESX, QBCore, une table Config de config.lua. Si une extension de typages déclare déjà lib et exports, vous pouvez les supprimer de la liste.

N'ajoutez que de vrais globals. Si vous silencez tout, vous perdez l'avertissement qui attrape une variable mal orthographiée, ce qui est l'une des meilleures choses que l'éditeur fait pour vous.

#Corrigez les avertissements qui sont réels

Certains avertissements sont l'éditeur qui fait son travail :

local players = ESX.GetPlayers()
for i = 1, #player do   -- 'player' is not defined: should be 'players'
end

Convertissez Lua.diagnostics.globals en une courte liste délibérée et chaque Undefined global restant est une faute de frappe ou un local manquant. C'est aussi le moyen le plus rapide de trouver les globals accidentelles, que le guide resmon liste comme source de performance et de bug.

Pour les cas ponctuels, un commentaire inline est meilleur qu'un paramètre global :

---@diagnostic disable-next-line: undefined-global
local x = SomeOtherResourceGlobal

#Annotez votre propre code

LuaLS lit les commentaires ---@. Quelques lignes rendent vos propres fonctions auto-documentées et donnent aux appelants l'autocomplétion :

---@param plate string
---@param coords vector3
---@return boolean
local function isPlateNear(plate, coords)
    -- ...
end

Si vous construisez une bibliothèque que d'autres scripts appellent via exports, mettre ces annotations sur les fonctions exportées est très rentable.

#Format on save

Installez StyLua (l'extension pour le formateur StyLua) ou utilisez le formateur propre du serveur de langage. Pour StyLua, ajoutez un stylua.toml à côté de vos resources :

column_width = 120
indent_type = "Spaces"
indent_width = 4
quote_style = "AutoPreferSingle"

Puis dans les paramètres VS Code :

{
  "[lua]": {
    "editor.defaultFormatter": "JohnnyMorganz.stylua",
    "editor.formatOnSave": true
  }
}

Vérifiez l'ID du formateur dans le panneau Extensions s'il ne se déclenche pas. StyLua peut ne pas aimer la syntaxe FiveM uniquement comme les hashes à backtick, donc exécutez-la sur une copie d'abord si vos scripts les utilisent beaucoup.

#Rechercher les natives

L'éditeur vous dit la signature ; la référence natives officielle vous dit ce que le native fait vraiment, avec des notes d'autres développeurs. Les pages natives sont à docs.fivem.net/natives, et la boîte de recherche trouve un native par nom ou description. Deux habitudes aident :

• Recherchez par ce que vous voulez, pas le nom exact : "obtenir le véhicule le plus proche", "os ped".
• Lisez d'abord le native Cfx.re, puis le texte de référence GTA V, car certains natives se comportent différemment sur la compilation FiveM.

Pour les détails client/serveur, voir événements client et serveur et Wait et threads.

#Liste de contrôle