Konventionen und Qualität

Diese Regeln gelten für den Kern und für jedes Plugin. Sie sind die Messlatte, an der sich Beiträge orientieren.

Code

• TypeScript-first. Das Framework ist in TypeScript geschrieben; Lua kommt nur für dünne Brücken vor (etwa die ESX-/QBCore-Shims).
• Plattformneutral. Core und Fachpakete enthalten keine Natives und keine FiveM-Aufrufe. Was die Laufzeit braucht, wird injiziert.
• Validierung an der Grenze. Alles, was vom Client kommt, wird serverseitig gegen ein Schema geprüft, bevor es Logik oder Datenbank erreicht.
• Serverseitige Autorität. Geld, Inventar, Jobs und Rechte entscheidet der Server. Keine Geschäftslogik in der Oberfläche.
• Eigene Fehlerklassen je Domain (zum Beispiel VehicleError, ShopError) statt generischer Fehler, damit Meldungen im Klartext an den Spieler gehen können.
• Atomar ändern. Lesen, Rechnen und Schreiben, das Geld, Inventar oder Fahrzeuge betrifft, gehört in eine Transaktion mit Audit-Eintrag.
• Keine Secrets im Repository. Zugangsdaten und Schlüssel liegen in Vorlagen-Dateien als Platzhalter und in lokalen, nicht versionierten Dateien.
• Rückwärtskompatibel. Änderungen an Plugins oder Core bleiben kompatibel oder bringen Migrationshinweise mit.

Tests

• Es gibt Smoke-Tests statt eines Test-Frameworks: pro Paket ein Runner mit Szenarien der Form „Beschreibung plus Prüfung“. npm test läuft über alle Pakete.
• Die Tests laufen ohne FXServer. Dafür gibt es einen In-Memory-DataStore und eine Fake-FiveM-Runtime.
• Ein grüner Smoke-Lauf ist kein Nachweis für den Betrieb mit echter Datenbank oder echtem Spielclient: Nebenläufigkeit und Timing des SQL-Pfads bleiben im In-Memory-Test unsichtbar. Deshalb gibt es zusätzlich Lasttest, Backup-Probe und Missbrauchs-Probe sowie echte End-to-End-Läufe.
• Für Race-Bedingungen prüft ein Aufzeichnungs-Store, ob ein Lese-Rechne-Schreibe-Ablauf in einer einzigen Transaktion liegt.

Definition of Done

Ein Beitrag gilt als fertig, wenn:

1. relevante Tests oder reproduzierbare Smoke-Checks gelaufen sind,
2. keine ungeprüften API-Annahmen im Code stecken,
3. die Benutzerfreundlichkeit geprüft ist (siehe unten),
4. die Dokumentation aktualisiert ist,
5. Plugin- und Core-Änderungen rückwärtskompatibel sind oder Migrationshinweise enthalten.

Benutzerfreundlichkeit

Jede neue Funktion wird so gebaut, dass Spieler sie ohne Anleitung finden und verstehen:

• Der Einstieg ist auffindbar.
• Beschriftungen sind in Spielersprache, nicht in Entwicklersprache.
• Ein Leerzustand nennt den nächsten Schritt.
• Sperren und Fehler werden im Klartext begründet.
• Jede Aktion gibt Rückmeldung (Laden, Erfolg, Fehler).

Fallstricke in FiveM

Aus der Praxis dokumentiert, damit niemand sie ein zweites Mal findet:

• Kein backdrop-filter in der Oberfläche. FiveMs NUI zeigt den Filter über der transparenten Spielfläche als schwarzen Block. Im Browser sieht alles richtig aus, der Fehler fällt erst im Spiel auf. Transparenz kommt über die Deckkraft des Hintergrunds.
• Kein HTML5-Drag-and-Drop. Die Events feuern in NUI nicht zuverlässig; Ziehen läuft über Maus-Events.
• Source-ID und Typ. FXServer liefert die Source in Lua als Zahl, GTA5OS nutzt intern durchgängig den String. Während des Verbindens kann die Source-ID eine andere sein als bei späteren Befehlen; der Adapter verbindet fehlende Sessions deshalb bei Bedarf nach.
• Exports zwischen Lua und Node werden mit der Doppelpunkt-Syntax aufgerufen (exports['resource']:name(...)); eine herausgelöste Funktionsreferenz schlägt fehl.
• Client-Bundle. Ein Import über das Paket-Root der UI-Shell kann den Core transitiv ins Client-Bundle ziehen, das keine Node-Module laden kann. Deshalb zeigt der Client-Code gezielt auf Teilmodule.
• Gebaute Bundles. Der Server lädt gebauten Code aus dist/. Wer nach einer Codeänderung nicht neu baut, testet alten Code.