Einführung in Lua-Scripting für FiveM

Lua ist die Skriptsprache, die FiveM-Ressourcenentwicklung antreibt. Ob du eigene Jobs erstellen, bestehende Skripte anpassen oder komplett neue Gameplay-Systeme bauen möchtest – Lua zu lernen ist dein Einstieg in die FiveM-Entwicklung. Dieser Guide bringt dich von null bis zum Schreiben deines ersten funktionierenden FiveM-Skripts und behandelt Lua-Grundlagen, FiveM-spezifische APIs und praktische Beispiele, die du sofort nutzen kannst.

Warum Lua für FiveM?

FiveM hat Lua aus gutem Grund als primäre Skriptsprache gewählt. Lua ist leichtgewichtig, schnell und einfach zu erlernen. Es wurde ursprünglich als eingebettete Skriptsprache für Spiele entwickelt, was es zu einer natürlichen Wahl für FiveM macht. Wenn du bereits Programmiererfahrung hast – selbst grundlegendes JavaScript oder Python – wirst du Lua schnell aufgreifen. Falls Lua deine erste Sprache ist, macht ihre einfache Syntax sie zu einem der freundlicheren Einstiege.

FiveM unterstützt auch C# und JavaScript für die Ressourcenentwicklung, aber der überwältigende Großteil der Community-Ressourcen ist in Lua geschrieben. Lua zu lernen gibt dir Zugang zum größten Ökosystem an Skripten, Beispielen und Community-Support.

Lua-Grundlagen: Variablen, Typen und Operatoren

Lua hat einen kleinen Satz von Datentypen und eine unkomplizierte Syntax. Hier sind die Grundlagen:

Variablen

Variablen in Lua sind standardmäßig global. Verwende das local-Schlüsselwort für lokale Variablen, was für Performance und zur Vermeidung von Namenskonflikten als Best Practice gilt:

local playerName = "John" local health = 100 local isAlive = true local nothing = nil

Lua ist dynamisch typisiert – du deklarierst keine Variablentypen. Eine Variable kann jeden Typ von Wert halten und den Typ während der Ausführung ändern.

Datentypen

• string — Textwerte in Anführungszeichen: "hello"
• number — sowohl Ganzzahlen als auch Dezimalzahlen: 42, 3.14
• boolean — true oder false
• nil — repräsentiert das Fehlen eines Wertes
• table — die einzige Datenstruktur in Lua, verwendet für Arrays, Dictionaries und Objekte
• function — Funktionen sind erstklassige Werte in Lua

Operatoren

Lua verwendet Standardoperatoren mit einigen besonderen:

• Arithmetik: +, -, *, /, % (Modulo), ^ (Potenz)
• Vergleich: ==, ~= (ungleich – beachte, dass dies in den meisten Sprachen anders ist)
• Logisch: and, or, not
• String-Verkettung: .. (zwei Punkte, kein +)

Funktionen

Funktionen werden mit dem function-Schlüsselwort definiert und sind zentral für FiveM-Scripting:

local function greetPlayer(name) print("Welcome, " .. name .. "!") end

Funktionen können Werte zurückgeben, mehrere Parameter akzeptieren und in Variablen oder Tabellen gespeichert werden. In der FiveM-Entwicklung wirst du ständig Funktionen definieren – für Event-Handler, Commands, NUI-Callbacks und Hilfslogik.

Tabellen: Das Schweizer Taschenmesser

Tabellen sind die einzige Datenstruktur in Lua, aber sie sind unglaublich vielseitig. Sie dienen als Arrays, Dictionaries, Objekte und mehr:

Als Array: local weapons = {"pistol", "smg", "rifle"} print(weapons[1]) -- "pistol" (Lua-Arrays beginnen bei 1, nicht 0!)

Als Dictionary: local player = { name = "John", job = "police", rank = 3 } print(player.name) -- "John"

Das Wichtigste zu merken: Lua-Arrays beginnen bei Index 1, nicht 0. Das erwischt jeden Entwickler, der von anderen Sprachen kommt.

Schleifen und Kontrollfluss

Lua bietet mehrere Schleifenkonstrukte:

For-Schleife (numerisch): for i = 1, 10 do print(i) end

For-Schleife (generisch – Tabellen iterieren): for key, value in pairs(myTable) do print(key, value) end

While-Schleife: while isRunning do -- etwas tun Wait(1000) end

If/elseif/else: if health > 50 then print("Gesund") elseif health > 0 then print("Verletzt") else print("Tot") end

FiveM-spezifische APIs

Jetzt, da du Lua-Grundlagen verstehst, schauen wir uns die FiveM-spezifischen Funktionen und Konzepte an, die du ständig verwenden wirst:

Events: Das Kommunikationssystem

Events sind die Art, wie verschiedene Teile deines Skripts (und verschiedene Skripte) kommunizieren. FiveM verwendet eine Client-Server-Architektur, bei der Events Daten zwischen beiden Seiten übertragen:

Event-Handler registrieren (Server-seitig): RegisterNetEvent("myScript:doSomething") AddEventHandler("myScript:doSomething", function(data) print("Received: " .. data) end)

Server-Event vom Client auslösen: TriggerServerEvent("myScript:doSomething", "hello server")

Client-Event vom Server auslösen: TriggerClientEvent("myScript:notify", source, "You received a message")

Verwende immer RegisterNetEvent vor AddEventHandler für Netzwerk-Events. Das registriert das Event als gültiges Netzwerk-Event und verhindert Exploits.

Commands

RegisterCommand("heal", function(source, args) local player = source -- Heilungslogik hier print("Player " .. player .. " healed") end, false) -- false = jeder kann es nutzen, true = nur Admins

Threads (Citizen.CreateThread)

Threads sind Schleifen, die kontinuierlich im Hintergrund laufen. Sie sind für client-seitige Gameplay-Logik unverzichtbar:

Citizen.CreateThread(function() while true do Wait(1000) -- 1 Sekunde pro Schleifendurchlauf warten -- Spielerstatus prüfen, HUD aktualisieren usw. end end)

Kritische Regel: Immer ein Wait() in deinen Threads einbauen. Ein Thread ohne Wait() friert das Spiel ein. Verwende Wait(0) für Frame-für-Frame-Updates (sparsam verwenden) und Wait(1000) oder höher für periodische Prüfungen.

Native-Funktionen

FiveM bietet Zugang zu tausenden von GTA V-Native-Funktionen. Diese steuern alles von Spielerbewegungen bis zu Wetter, Fahrzeugen, Waffen und UI:

local ped = PlayerPedId() -- Spielercharakter holen local coords = GetEntityCoords(ped) -- Position holen local health = GetEntityHealth(ped) -- Gesundheit holen SetEntityCoords(ped, 100.0, 200.0, 30.0) -- teleportieren

Die FiveM-Native-Referenz unter docs.fivem.net/natives ist dein bester Freund. Setze ein Lesezeichen – du wirst sie ständig brauchen.

Client- vs. Server-Skripte

Die Client-Server-Trennung zu verstehen ist fundamental für die FiveM-Entwicklung:

Aspekt

Client-Skript

Server-Skript

Läuft auf

Computer des Spielers

Server-Maschine

Zugang zu

GTA-Natives, Spieler-Ped, UI

Datenbank, alle Spieler, Server-Zustand

Vertrauensstufe

Nicht vertrauenswürdig (kann modifiziert werden)

Vertrauenswürdig (Server-autoritativ)

Verwendung für

UI, visuelle Effekte, Eingabe, lokales Gameplay

Datenspeicherung, Validierung, Wirtschaft, Berechtigungen

Datei-Suffix-Konvention

cl_*.lua oder client/*.lua

sv_*.lua oder server/*.lua

Goldene Regel: Vertraue dem Client nie. Alle wichtige Logik (Geld, Inventar, Berechtigungen) muss auf dem Server validiert werden. Der Client kümmert sich um Darstellung und Benutzerinteraktion; der Server verwaltet den Spielzustand und die Daten.

fxmanifest.lua erklärt

Jede FiveM-Ressource benötigt eine fxmanifest.lua-Datei, die dem Server mitteilt, was die Ressource enthält:

fx_version "cerulean" game "gta5"

name "my-first-script" description "A simple example resource" version "1.0.0"

client_scripts { "client/main.lua", }

server_scripts { "server/main.lua", }

shared_scripts { "config.lua", }

Wichtige Felder: fx_version sollte "cerulean" sein (die aktuelle Version). client_scripts laufen auf dem Spieler, server_scripts auf dem Server, und shared_scripts auf beiden. Du kannst auch dependencies definieren, um Ressourcen anzugeben, die vor deiner geladen werden müssen.

Dein erstes Skript: Ein Heilungs-Command

Lass uns ein vollständiges, funktionales Skript von Grund auf bauen. Dieses Skript fügt einen /heal-Command hinzu, der die Spielergesundheit wiederherstellt:

fxmanifest.lua: fx_version "cerulean" game "gta5" name "my-heal-script" server_scripts { "server.lua" } client_scripts { "client.lua" }

server.lua: RegisterCommand("heal", function(source) TriggerClientEvent("myHeal:doHeal", source) print("Healing player " .. source) end, false)

client.lua: RegisterNetEvent("myHeal:doHeal") AddEventHandler("myHeal:doHeal", function() local ped = PlayerPedId() SetEntityHealth(ped, GetEntityMaxHealth(ped)) end)

Lege dies in deinen Resources-Ordner, füge ensure my-heal-script zur server.cfg hinzu und starte neu. Tippe /heal im Chat und deine Gesundheit wird vollständig wiederhergestellt.

Debugging-Tipps

• Verwende print() großzügig — print() gibt in der Server-Konsole (Server-Skripte) oder F8-Konsole (Client-Skripte) aus. Es ist dein primäres Debugging-Werkzeug.
• Überprüfe die F8-Konsole — Drücke F8 im Spiel, um client-seitige Fehler und Print-Ausgaben zu sehen. Die meisten Skriptfehler erscheinen dort mit Zeilennummern.
• Server-Konsole — Server-seitige Fehler erscheinen in deinem Server-Terminal. Halte es während der Entwicklung immer sichtbar.
• Typenprüfung — Verwende type(variable), um zu überprüfen, welchen Typ eine Variable tatsächlich hat. Viele Bugs entstehen durch unerwartete nil-Werte.
• Lua-Fehlermeldungen — Lerne, Lua-Fehlermeldungen zu lesen. Sie sagen dir die Datei, Zeilennummer und Art des Fehlers. Die häufigsten sind "attempt to index a nil value" (Zugriff auf eine Eigenschaft von nil) und "attempt to call a nil value" (Aufruf einer nicht vorhandenen Funktion).

Nützliche Ressourcen zum Lernen

• FiveM-Dokumentation — docs.fivem.net — offizielle Native-Referenz und Guides
• Programming in Lua — Das offizielle Lua-Buch, kostenlos online unter lua.org/pil
• QBCore-Dokumentation — Falls du QBCore verwendest, erklären deren Docs framework-spezifische Funktionen
• Overextended-Dokumentation — Für ox_lib- und QBOX-Entwicklung
• FiveM-Foren und Discord — Aktive Community für Fragen und Skript-Sharing
• GitHub — Suche nach Open-Source-FiveM-Ressourcen, um realen Code zu studieren

Abschließende Gedanken

Lua für FiveM zu lernen ist eine lohnende Reise, die unbegrenzte Möglichkeiten für deinen Server eröffnet. Beginne mit einfachen Skripten wie Commands und Event-Handlern, studiere bestehende Open-Source-Ressourcen, um zu sehen, wie erfahrene Entwickler ihren Code strukturieren, und nimm schrittweise komplexere Projekte in Angriff. Die FiveM-Community ist neuen Entwicklern gegenüber aufgeschlossen, also zögere nicht, in Foren und Discord-Servern Fragen zu stellen. Jeder FiveM-Experte hat genau dort angefangen, wo du jetzt bist.

Fertig codierte FiveM-Skripte zum Lernen bei VertexMods

Sobald du Lua kennst, erkunde diese gut programmierten FiveM-Skripte bei VertexMods. Sie sind großartige Referenzen, um reale Skript-Architektur zu studieren:

• jobs-creator-7 — 60€ — Jobs Creator — erweiterbares Job-Framework
• drugs-creator — 50€ — Drugs Creator — fortgeschrittenes Drogensystem
• robbery-creator — 65€ — Robbery Creator — konfigurierbares Überfallsystem
• restaurant-system — 44€ — Restaurant System — Multi-Mechaniker-Job-Skript