Architektur

GTA5OS besteht aus fünf Schichten. Die Abhängigkeiten zeigen immer nach innen: Plugins kennen den Core, der Core kennt keine Plugins; der Core kennt die Plattform nicht, der Adapter kennt den Core.

Die Schichten

Platform-Adapter

Der Adapter (gta5os-platform-fivem) ist die einzige Stelle, an der FiveM-Events, Exports, Commands, Natives und der NUI-Transport vorkommen. Er bindet die Core-Dienste an Verbindungsaufbau, Charakterfluss und Spieler-Aktionen an und führt Wirkungen wie Nachrichten, Positionswechsel oder Trennen eines Spielers über eine injizierbare Runtime aus. Dadurch lässt sich die Adapter-Logik ohne echten Server mit einer Fake-Runtime testen.

Core-Kernel

Der Kern (gta5os-core) enthält die Systemdienste:

• Lebenszyklus, Konfiguration (mit Schema-Prüfung) und Logger mit Namensräumen
• Service-Registry mit typisierten Tokens
• typisierter Event-Bus und RPC-Schicht mit Runtime-Validierung und Ratenbegrenzung
• Rechte (Permissions)
• Spieler- und Session-Laufzeit
• Beobachtbarkeit: Messwerte und Leistungsbudgets je Plugin und Operation

Darauf liegen die Domain-Module: Identität und Charaktere, Inventar, Wirtschaft, Jobs, Fahrzeuge, Shops, Rechnungen sowie Tod und Respawn.

Wichtigste Regel: Im Core gibt es keine FiveM-Natives, keine Source-IDs und keine Aufrufe wie RegisterCommand. Alles, was die Laufzeit braucht, wird injiziert. So bleibt der Core auch im reinen Node-Test lauffähig.

Datenschicht (DataStore)

Alle Domain-Daten laufen über einen adapterneutralen DataStore-Vertrag:

• Transaktionen mit Commit und Rollback ohne Teilzustand
• Repositories (KeyValueRepository) statt direktem Datenbankzugriff im Spielcode
• ein Migrations-Runner, der idempotent arbeitet
• ein In-Memory-Adapter für Tests und ein SQL-Adapter für PostgreSQL und MySQL/MariaDB
• ein Backup-/Restore-Vertrag mit Prüfsumme

Jede Mengen- oder Geldänderung läuft zusammen mit ihrem Audit-Eintrag in einer Transaktion. Schlägt ein Schritt fehl, bleibt kein halber Zustand zurück.

Plugin-Runtime

Die Plugin-Runtime lädt das Manifest eines Plugins, prüft Abhängigkeiten und führt den Lebenszyklus aus. Commands, Berechtigungen und UI-Routen dürfen nur registriert werden, wenn sie im Manifest stehen. Details: Plugin-System.

UI-Shell

Die UI-Shell (gta5os-ui-shell) ist eine einzige, framework-freie NUI-App mit mehreren Plugin-Routen. Sie liefert Design Tokens und gemeinsame Bausteine wie Button, Eingabefeld, Modal, Toast, Menü, Tabelle, Leer- und Fehlerzustand. Jede Aktion zeigt Lade-, Erfolgs- und Fehlerzustand, Tastatur- und Controller-Bedienung wird mitgedacht.

Die ausgelieferte Resource

Die Pakete werden zur FiveM-Resource gta5os_core zusammengesetzt (Client, Server und NUI-Web). Sie verdrahtet Core und Adapter gegen den FXServer, registriert Commands und Tastenbelegungen und baut die Oberfläche mit einem eigenen UI-Build. Ein Node-Smoke-Test prüft die Verdrahtung mit einer Fake-FiveM-Runtime.

Wie eine Spieleraktion läuft

1. Der Spieler löst in der Oberfläche eine Aktion aus (zum Beispiel „Kaufen“).
2. Die UI-Shell schickt eine validierte Nachricht an den Client, der Client einen Event an den Server.
3. Die Netzwerkgrenze prüft Schema und Ratenlimit und verwirft kaputte oder zu häufige Nachrichten.
4. Der zuständige Dienst im Core prüft Rechte und Zustand und führt die Änderung in einer Transaktion samt Audit-Eintrag aus.
5. Der Server meldet Ergebnis oder verständlichen Fehler zurück; die Oberfläche zeigt Erfolg oder Klartext-Meldung.

Es gibt keine Geschäftslogik in der Oberfläche und keinen Datenbank-Schreibzugriff ohne serverseitige Prüfung.

Leitplanken

• TypeScript-first, strikte Runtime-Validierung an Netzwerkgrenzen
• Plugin-APIs werden versioniert
• Der Core darf Plugins nicht kennen; Plugins kennen nur die öffentliche Core-API
• Rechte sind namespaced (plugin.aktion); FiveM-ACE kann angebunden werden, bleibt aber ein Adapter-Detail