Einführung in Lua-Scripting für FiveM

FiveM-Ressourcen können CfxLua, eine modifizierte Lua 5.4-Laufzeitumgebung, für Client- und Server-Skripte verwenden. Eine aktuelle Ressource beginnt mit fxmanifest.lua, listet die Dateien auf, die jeder Kontext lädt, und behält autoritative Entscheidungen wie Berechtigungen, Geld und Inventar auf dem Server.

Die hier gezeigten Konfigurations- und Codebeispiele beziehen sich auf FiveM für GTA V Legacy. Enhanced hat andere Laufzeit- und Kompatibilitätsregeln; überprüfe die Legacy-zu-Enhanced-Änderungen von Cfx.re bevor du sie auf einen Enhanced-Server anwendest.

Erstelle eine minimale Ressource

Erstelle im Verzeichnis resources deiner server-data-Struktur den Ordner [local]/hello_fivem. Die eckigen Klammern gruppieren Ressourcen; die eigentliche Ressource ist das Verzeichnis 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)

Die offizielle Dokumentation zum Manifest und zum Laufzeitverhalten findest du hier: Ressourcenmanifestreferenz und CfxLua-Leitfaden.

Verstehe Client- und Serverkontexte

Ein Client-Skript läuft für jeden verbundenen Spieler separat und kann spielbezogene Natives aufrufen, etwa PlayerPedId und GetEntityCoords. Ein Server-Skript koordiniert den gemeinsamen Zustand, die Persistenz und die Autorisierung. Werte, die von einem Client geliefert werden, sind Eingaben, kein Beweis.

Verwende AddEventHandler für Events, die in einem Kontext verbleiben sollen. Verwende RegisterNetEvent nur, wenn ein Event die Client/Server-Grenze überschreiten muss. Der offizielle Leitfaden zur Sicherung deiner Events erklärt, warum jede vernetzte Aktion die aktuelle serverseitige Berechtigung und den Status des Spielers validieren muss.

Vermeide es, den Scheduler zu blockieren

CfxLua-Skripte teilen sich die Ausführungszeit kooperativ. Eine Schleife, die die Ausführung nie abgibt, kann ihren Skriptkontext blockieren. Wenn eine Schleife warten muss, verwende Wait mit einer zur Aufgabe passenden Verzögerung und frage Datenbanken oder HTTP-Endpunkte nicht in jedem Frame ab. Bevorzuge Events und Zustandsänderungen gegenüber dauerhaftem Polling.

Verwende Exporte für eine klare Ressourcengrenze

Ein Export macht eine benannte Funktion für eine andere Ressource verfügbar. Definiere sie explizit und dokumentiere ihre Argumente und Rückgabewerte:

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

Eine andere Lua-Ressource kann sie so aufrufen: exports.hello_fivem:formatPlayerLabel(id, name). Verwende keinen Export, um Berechtigungs- oder Eigentumsprüfungen zu umgehen.

Führe die Ressource aus und teste sie

1. Sichere die Ressource, die du ersetzt, falls vorhanden.
2. Führe in der Serverkonsole folgende Befehle aus: refresh und dann ensure hello_fivem.
3. Überprüfe die Serverkonsole auf die Startmeldung.
4. Verbinde dich mit dem Entwicklungsserver, öffne F8 und führe folgenden Befehl aus: mycoords.
5. Füge ensure hello_fivem nach allen Abhängigkeiten zu server.cfg hinzu und starte dann den Server neu, um den normalen Start zu bestätigen.

Die offizielle Liste unterstützter Ressourcenbefehle findest du hier: Server-Befehlsreferenz. Fahre mit dem offiziellen ersten Lua-Skript-Tutorial fort , bevor du Framework- oder Datenbankabhängigkeiten ergänzt.