FiveM VS Code-Setup: Lua Language Server, Natives, keine falschen Warnungen

Du öffnest ein perfekt gutes Skript in VS Code und es sieht so aus:

Undefined global `PlayerPedId`.

Jedes Native, exports, ESX und QBCore bekommt eine gelbe Unterlinie, und echte Fehler ertrinken in dem Lärm. Diese Anleitung richtet VS Code so ein, dass es FiveM Lua versteht und dich nur vor Dingen warnt, die tatsächlich falsch sind.

#Installiere einen Lua Language Server

Im Erweiterungsfeld installiere einen Lua Language Server-Erweiterung. Der weit verbreitete ist die "Lua"-Erweiterung von sumneko, die auf Lua Language Server (LuaLS) aufgebaut ist. Es gibt dir Fertigstellung, Gehe zur Definition, Umbenennung und Diagnostik.

Öffne deinen Ressourcenordner als Workspace (nicht eine einzelne Datei), damit der Server jedes Skript und die Einstellungen, die du gleich hinzufügst, sehen kann.

#Füge FiveM-Native-Definitionen hinzu

Plain LuaLS hat keine Ahnung, was GetEntityCoords nimmt. Die Community verwaltet Typings für FiveM / CfxLua: ein Satz von Anmerkungsdateien, die die Natives, die Cfx.re-Globals und die zusätzliche Lua-Syntax, die FiveM ermöglicht, beschreiben. Suche im Erweiterungsfeld nach "CfxLua" oder "FiveM natives", oder suche nach einer "FiveM"-Erweiterung im LuaLS-Erweiterungs-Manager und wähle die, die aktiv gewartet wird.

Mit ihnen installiert, bekommst du Signaturen, wenn du tippst:

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

Hover über ein Native und die Parameter und Rückgabetypen zeigen sich. Die meisten Typings enthalten auch exports, lib-Anmerkungen, wenn du die ox_lib-Definitionen hinzufügst, und die cache-Tabelle.

Tipp: Erweiterungsnamen und Einstellungen ändern sich im Laufe der Zeit. Wenn eine Einstellung unten nicht in deiner Version existiert, überprüfe die eigene README der Erweiterung, die immer aktueller ist als ein Tutorial.

#Workspace-Einstellungen

Erstelle .vscode/settings.json am Root deines Ressourcenordners. Dies behält die Einstellungen mit dem Projekt, damit jeder, der es öffnet, das gleiche Verhalten bekommt:

{
  "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"]
}

Was jeder Teil macht:

• Lua.runtime.version passt lua54 'yes' in deinem fxmanifest.lua an.
• nonstandardSymbol teilt dem Parser mit, dass FiveMs Compound-Assignment (x += 1) und Backtick-Hashes gültig sind. Ohne es wird perfekt guter Code als Syntaxfehler gekennzeichnet.
• Lua.diagnostics.globals listet Namen auf, die das Skript irgendwo definiert, das der Server nicht verfolgen kann. Füge deine eigenen hinzu: ESX, QBCore, eine Config-Tabelle von config.lua. Wenn eine Typings-Erweiterung bereits lib und exports deklariert, kannst du sie aus der Liste fallen lassen.

Füge nur echte Globals hinzu. Wenn du alles zum Schweigen bringst, verlierst du die Warnung, die eine falsch geschriebene Variable fängt, was eines der besten Dinge ist, die der Editor für dich tut.

#Behebe die Warnungen, die real sind

Einige Warnungen sind der Editor, der seinen Job macht:

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

Verwandle Lua.diagnostics.globals in eine kurze, absichtliche Liste und jedes verbleibende Undefined global ist ein Tippfehler oder ein fehlendes local. Das ist auch die schnellste Weise, versehentliche Globals zu finden, die die resmon-Anleitung als eine Leistungs- und Fehlerquelle auflistet.

Für einmalige Fälle ist ein Inline-Kommentar besser als eine globale Einstellung:

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

#Annotiere deinen eigenen Code

LuaLS liest ---@-Kommentare. Ein paar Zeilen machen deine eigenen Funktionen selbsterklärend und geben Anrufern Autovervollständigung:

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

Wenn du eine Bibliothek baust, die andere Skripte durch exports aufrufen, zahlt sich das Setzen dieser Anmerkungen auf den exportierten Funktionen am meisten aus.

#Format beim Speichern

Installiere StyLua (die Erweiterung für den StyLua Formatter) oder verwende den eigenen Formatter des Language Servers. Für StyLua füge ein stylua.toml neben deinen Ressourcen hinzu:

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

Dann in den VS Code-Einstellungen:

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

Überprüfe die Formatter-ID im Erweiterungsfeld, wenn es nicht auslöst. StyLua mag möglicherweise keine FiveM-nur-Syntax wie Backtick-Hashes nicht, daher führe sie zuerst auf einer Kopie aus, wenn deine Skripte sie stark verwenden.

#Suche die Natives

Der Editor sagt dir die Signatur; die offizielle Natives-Referenz sagt dir, was das Native wirklich tut, mit Notizen von anderen Entwicklern. Die Natives-Seiten sind bei docs.fivem.net/natives, und das Suchfeld findet ein Native nach Name oder Beschreibung. Zwei Gewohnheiten helfen:

• Suche nach dem, was du willst, nicht dem genauen Namen: "get closest vehicle", "ped bone".
• Lese das Cfx.re native zuerst, dann den GTA V-Referenztext, da sich einige Natives im FiveM-Build anders verhalten.

Für Client/Server-Details siehe Client- und Server-Events und Wait und Threads.

#Checkliste