EmergencyOS — Dokumentation

Willkommen in der offiziellen Entwickler- und Betreiber-Dokumentation des EmergencyOS-Ökosystems. Hier findest du zu jedem FiveM-Script die vollständige Anleitung: Installation, Voraussetzungen, Datenbank- und Panel-Sync, jede Config-Option und jeden Export mit Code-Beispiel.

Das Ökosystem

EmergencyOS besteht aus zwei Hälften, die über eine sichere HTTP-Bridge zusammenspielen:

• Web-Panel (emergencyos.de) — die Fach-Anwendung (Akten, Fahndungen, Tickets, LiveMap, Statistiken). Läuft im Browser und als Tablet-Oberfläche im Spiel.
• FiveM-Ressourcen — die Ingame-Scripts auf deinem GTA-V-Server, die sich mit dem Panel synchronisieren.

Produkte im Überblick

Wähle links in der Sidebar ein Produkt — jede Seite ist gleich aufgebaut: Überblick → Voraussetzungen → Installation → Datenbank & Sync → Konfiguration → Exports → Events & Commands → Troubleshooting.

Allgemeine Voraussetzungen

• Aktueller FiveM-Server (Artifacts)
• oxmysql als Datenbank-Layer
• Framework: ESX, QBCore / Qbox oder Standalone (je nach Script frei wählbar)
• Ein EmergencyOS-Panel-Konto mit API-Key (für die panel-gebundenen Scripts EmergencyOS & LicenseOS)

So funktioniert die Panel-Anbindung

Jedes panel-gebundene Script verbindet sich beim Start automatisch mit dem Web-Panel — Server-IP und Port müssen nirgendwo eingetragen werden:

1. Im Panel unter Einstellungen → Datenbank Sync (bzw. FiveM-Bridge) einen API-Key erzeugen.
2. Den Key in die jeweilige config.lua / api_config.lua eintragen (SVConfig.API.key bzw. Config.ApiKey).
3. Ressource neu starten — der Server registriert sich selbst am Panel (IP/Port automatisch). Fertig.

Tipp: Die genauen Schritte, Endpunkte und Fehlerbilder stehen bei jedem Produkt in den Abschnitten „Installation" und „Datenbank & Panel-Sync".

Konventionen in dieser Doku

• Code in dieser Schrift = exakte Datei-, Config- oder Exportnamen aus dem Quellcode.
• Tabellen listen Key · Standard · Beschreibung — die Standardwerte sind die echten Defaults aus dem ausgelieferten Code.

Support

Bei Fragen: Discord (discord.gg/2pKru3N) oder per E-Mail an info@ancomox.com.

EmergencyOS — Entwickler-Dokumentation

Überblick

EmergencyOS ist die Ingame-Extension (Tablet/MDT) zum EmergencyOS-Web-Panel (emergencyos.de). Das Tablet ist die Bedienoberfläche im Spiel; die eigentliche Fach-App (Akten, Fahndungen, Tickets, LiveMap, Statistiken) läuft als Web-Panel, mit dem sich der Spielserver über eine HTTP-Bridge synchronisiert.

Zielgruppe / Fraktionen: Polizei/Behörden (LSPD, FIB, LSSD/Sheriff), Justiz (DOJ), Rettungsdienst (LSMD/Medic) und Feuerwehr (LSFD). Die Abteilungs-Sichtbarkeit ist strikt getrennt. Standard-Whitelist im Code: police, ambulance, fib, justiz, admin.

Kernfeatures (aus CHANGELOG/README): - MDT/Tablet mit Multi-Window, freiem Resizing, Dark-Design, Rich-Text-Editor (Quill, Auto-Save), Aktenvorlagen. - Personen- & Fahrzeugakten, Fahndungssystem (Wanted/BOLO) — intern & öffentlich; öffentliche Fahndungen laufen als DUI-Carousel auf Welt-Bildschirmen (Config.WantedBillboards). - Digital Citation / Ticketsystem — inszeniertes Strafzettel-Ausstellen mit Beweisfoto (Evidence Cam → Discord), animiertem Beleg, Bürgerportal /strafzettel zum Einsehen & Bezahlen. - Bußgeldrechner mit dynamischen Modifikatoren (Geständig −20 %, Wiederholungstäter +50 %). - Sofort-Halterabfrage (F9 / /runplate) mit HUD und BOLO-Treffer. - App „Dienst & Statistik" — automatische Dienstzeit-Erfassung nach Job, Live-Dienststand, Leaderboard, Team-Übersicht, Dienstpflicht/Wochen-Soll, AFK-Schutz, optionaler Discord-Wochenbericht. - Verhaftungs-Anbindung für eigene Jail-Scripts (RecordArrest), Dispatch-Anbindung (Vanguard Dispatch Gateway). - Panic Button (10-13), interner Monitor (Atlas-Feed auf Wachen-Screens), KI-gestützte Tatberichte, Beweismittel-Verwaltung, FIB „Nexus Netzwerk". - Framework-agnostisch: ESX, QBCore oder STANDALONE (Custom) über die Data-Provider-API.

Voraussetzungen

Aus fxmanifest.lua (fx_version 'bodacious', game 'gta5', lua54 'yes'):

Es gibt keine expliziten dependency-Zeilen im Manifest außer @oxmysql.

Installation

1. Ordnername: Die Resource muss exakt EmergencyOS heißen (Groß-/Kleinschreibung beachten — der Code nutzt durchgängig exports['EmergencyOS'] und GetCurrentResourceName()).
2. Panel-Konto/Instanz: Auf emergencyos.de anmelden, Instanz anlegen. Im Panel unter Einstellungen → Datenbank Sync einen API-Key erzeugen (nur der Besitzer-Account sieht diesen Button). Panel-DB-Migrationen/-Dateien laut Keymaster/Panel einspielen.
3. API-Key eintragen: In config/api_config.lua den Key in SVConfig.API.key setzen (siehe nächster Abschnitt).
4. Framework wählen: In config/config.lua Config.Framework auf "ESX", "QBCORE" oder "STANDALONE" setzen; bei STANDALONE zusätzlich Data Provider registrieren (siehe README_CUSTOM_FRAMEWORK).
5. server.cfg — Startreihenfolge (oxmysql zuerst, Framework davor): cfg ensure oxmysql ensure es_extended # oder qb-core (bei STANDALONE entfällt das) ensure EmergencyOS
6. SQL-Migrationen einmalig ausführen (Dienstzeit-Spalten, Dienstpflicht, Ticket-Zuordnung, optional Patrol-Index; Duty-Tabelle emos_duty_stats).
7. Server starten. Beim Start meldet sich der Server automatisch am Panel an (Handshake). Erfolg: [EmergencyOS] v… bereit | Panel verbunden (Instanz <id>) — Sync aktiv.

Datenbank & Panel-Sync

Die Synchronisation läuft über eine bidirektionale HTTP-Bridge (server/api_endpoint.lua, server/sync_bridge.lua). Der Spielserver ruft das Panel unter https://emergencyos.de/api/… auf; das Panel ruft umgekehrt den FiveM-HTTP-Endpoint des Servers auf (SetHttpHandler, Autorisierung per Api-Key).

Einrichtung (neuer Weg, ab v3-Handshake)

1. Key erstellen: Panel → Einstellungen → Datenbank Sync → API-Key (nur Besitzer-Account). Neue Keys tragen das Präfix eos_.
2. Key eintragen in config/api_config.lua → SVConfig.API.key.
3. Resource neu starten — fertig. Server-IP/Port müssen nirgendwo eingetragen werden: der Server registriert sich beim Start selbst am Panel und schickt beim Handshake Resource-Name und Server-Port (GetConvar('netPort', '30120')) mit; das Panel registriert IP/Port/Resource-Name automatisch als Push-Rückkanal.

Handshake-Logik (api_endpoint.lua)

• Self-Service-Key (eos_…): Anmeldung nur mit dem Key. Header: Api-Key, Resource-Name, Server-Port, optional Server-Ip (nur wenn SVConfig.API.serverIp gesetzt). Ziel: GET https://emergencyos.de/api/getInstance → liefert die numerische Instance-ID (GlobalInstanceId).
• Legacy-Key (ohne eos_, Ancomox-Bestandskunden): zusätzlich Instance-Username + Instance-Password (aus SVConfig.API.username/password) erforderlich. Fehlen sie, bricht der Handshake mit klarer Konsolenmeldung ab (kein weiterer Versuch bis Neustart).
• Retry/Backoff: Bei nicht erreichbarem Panel automatische Wiederholung 10s → 30s → 60s → 2min → 5min. HTTP 400 (unvollständige Daten) stoppt dauerhaft mit Anleitung; 401/403 (Key falsch/abgelaufen) zeigt einmal einen Hinweis und versucht danach leise alle 10 min erneut.
• Re-Handshake: Nach Erst-Erfolg meldet sich der Server stündlich erneut an (registriert IP/Port bei Server-Umzug automatisch neu).
• Nach Verbindung wird nach 5 s die animierte Fahndungs-Rotation gestartet (api/wantedCarousel.php?instance=<id>).

Sicherheit des eingehenden Endpoints

• Nur POST mit gültigem Key (Header Authorization: Bearer <key> oder Api-Key), Vergleich in konstanter Zeit (SecureCompare).
• Rate-Limit SVConfig.ApiRateLimit (Default 120/10 s) → HTTP 429; Body-Limit SVConfig.ApiMaxBodyBytes (Default 524288 = 512 KB) → HTTP 413; Watchdog-Timeout SVConfig.ApiTimeoutMs (Default 15000 ms) → {"error":"timeout"}.
• Jede Action läuft in eigenem Citizen-Thread; Actions können execute(data)->string (sync) oder executeAsync(data, done) definieren.

Genutzte Panel-Endpoints (ausgehend)

api/getInstance (Handshake), api/getWanteds.php (BOLO-Pull), api/mdtLookup.php (MDT), api/wantedCarousel.php, api/billPaid (via sendAPIReqest), api/getOpenTickets.php, api/setTicketPaid.php (Bürgerportal), version.json (Update-Check).

Eingehende Actions (Panel → Server)

U. a. syncWanteds (BOLO-Push), getDispatchState, dispatchCreateCall, dispatchAssign, dispatchClose, createBill, liveConsoleLog sowie die Data-Provider-Actions (getVehicle, searchPlayers, getPlayer, searchVehicles, trackPhone, getJobPlayerPositions).

BOLO/Fahndungs-Cache (sync_bridge.lua)

RAM-Cache mit 3 Quellen (Priorität absteigend): 1) Push (Actions['syncWanteds']), 2) Pull (api/getWanteds.php, Intervall SVConfig.BoloPullInterval, Default 300000 ms), 3) DEV-Fallback (direkte DB app_wanteds/app_vehicleRegister, nur wenn SVConfig.BoloDevFallback == true). MDT-Lookups werden SVConfig.MdtCacheTTL ms (Default 90000) gecacht, mit Live-Fallback auf die Data-Provider-Actions.

Konfiguration

config/config.lua (Client & Shared)

Weitere Config.DutyStats-Optionen (im Code unterstützt, in der Default-Config nicht ausgeschrieben — bei Bedarf ergänzen):

config/api_config.lua (Server)

config/cl_integrations.lua (Client, Framework-Bridge-Stubs)

Diese Datei enthält Stub-Funktionen, die bei Custom-Frameworks überschrieben werden können. Standardwerte:

Exports

exports['EmergencyOS']:<Name>(...). Insgesamt 19 registrierte Exports (5 Client, 14 Server).

Client-Exports (client/client.lua)

LockEmergencyOS() — Client. Schließt das Tablet und sperrt das Öffnen (IsPadLocked = true). Keine Rückgabe.

exports['EmergencyOS']:LockEmergencyOS()

UnlockEmergencyOS() — Client. Hebt die Sperre auf. Keine Rückgabe.

exports['EmergencyOS']:UnlockEmergencyOS()

CloseEmergencyOS() — Client. Schließt das Tablet (ohne Sperre).

exports['EmergencyOS']:CloseEmergencyOS()

OpenTablet([fullscreen]) — Client. Öffnet das Tablet; fullscreen (bool) erzwingt Vollbild.

exports['EmergencyOS']:OpenTablet(true)

SetPlayerJob(jobName) — Client. Setzt den lokal bekannten Job (Bridge.PlayerJob) für Whitelist/UI. Bei STANDALONE/Custom bei Charwahl, Spawn und Jobwechsel aufrufen.

exports['EmergencyOS']:SetPlayerJob("police")

Server-Exports

SetPlayerJob(source, jobName) — Server (server.lua). Setzt global den Job eines Online-Spielers (Bridge.PlayerJobs[src]) für Whitelist-Prüfung, LiveMap-Gruppen und Panic-Broadcast.

exports['EmergencyOS']:SetPlayerJob(source, "police")

GetInstanceId() — Server (api_endpoint.lua). Gibt die vom Panel zugewiesene Instance-ID zurück (oder nil, solange nicht verbunden).

local iid = exports['EmergencyOS']:GetInstanceId()

billPaid(billId) — Server (server_actions.lua). Meldet dem Panel, dass eine Rechnung bezahlt wurde (ruft api/billPaid). Aus eigenem Banking aufrufen.

exports['EmergencyOS']:billPaid(billId)

RegisterDataProvider(tbl) — Server (sv_data_provider.lua). Registriert die Custom-Framework-Hooks. Gültige Hooks: getIdentifier, resolveSource, getPlayer, searchPlayers, getVehicle, searchVehicles, findByPhone, getJob, removeMoney. Rückgabe: true/false. Alle Hooks müssen synchron liefern (oxmysql:executeSync).

exports['EmergencyOS']:RegisterDataProvider({
    getIdentifier = function(src) return "char:"..MyCore.GetCharId(src) end,
    getPlayer     = function(id) return { firstname="Max", lastname="Muster", dob="1990-05-14" } end,
})

HasDataProvider() — Server. true, wenn ein Provider registriert ist.

if exports['EmergencyOS']:HasDataProvider() then ... end

GetPlayerIdentifierEOS(src) — Server. Persistenter Panel-Identifier eines Spielers (Provider → ESX license → QB citizenid → FiveM license).

local ident = exports['EmergencyOS']:GetPlayerIdentifierEOS(src)

ResolveIdentifierToSource(identifier) — Server. Umkehrung: Identifier → Server-ID (oder nil).

local src = exports['EmergencyOS']:ResolveIdentifierToSource(ident)

RecordArrest(officerSrc) — Server (sv_duty.lua). Schreibt dem Beamten eine Verhaftung gut (erscheint in Team-Übersicht/Detailansicht/Settings). Rückgabe: true/false (false bei ungültiger/offline Source).

exports['EmergencyOS']:RecordArrest(officerSource)   -- aus dem eigenen Jail-Script

AddOfficerActivity(officerSrc, column, amount) — Server (sv_duty.lua). Erhöht einen beliebigen Aktivitäts-Zähler (z. B. 'arrests', 'scans', 'plate_checks', 'panics').

exports['EmergencyOS']:AddOfficerActivity(src, 'arrests', 1)

IsOnDuty(src) — Server (sv_duty.lua). true, wenn der Spieler aktuell als im Dienst geführt wird.

if exports['EmergencyOS']:IsOnDuty(src) then ... end

PlayTicketCeremony(officerSrc, targetSrc, amount, reason, fraction) — Server (sv_ticket_fx.lua). Spielt die Digital-Citation-Zeremonie ab (ohne echte Rechnung). officerSrc darf nil sein → Zustellung „per Post" (mode='mail'), sonst Vor-Ort-Modus (mode='handover'). Rückgabe: true/false.

exports['EmergencyOS']:PlayTicketCeremony(officerSrc, targetSrc, 250, "Falschparken", "LSPD")

IsPlateWanted(plate) — Server (sync_bridge.lua). true, wenn das (normalisierte) Kennzeichen im BOLO-RAM-Cache steht. Nicht-blockierend.

if exports['EmergencyOS']:IsPlateWanted("LS12345") then ... end

GetWanteds() — Server (sync_bridge.lua). Gibt wanteds (Tabelle) und version (Zahl) des aktuellen BOLO-Cache zurück.

local wanteds, version = exports['EmergencyOS']:GetWanteds()

MdtLookup(payload, cb) — Server (sync_bridge.lua). Asynchrone MDT-Abfrage ans Panel (mit Live-Fallback + Cache). payload z. B. { action="personDetail", id="emergencyos__LIVE:..." } bzw. { action=..., query=... }. Ergebnis kommt über cb(result).

exports['EmergencyOS']:MdtLookup({ action = "plate", query = "LS12345" }, function(res) ... end)

Öffentliche API-Events ans Panel (Payloads)

Für die Anbindung eigener Scripts (Verhaftungen/Scan/Dispatch/Tickets). Server-authoritativ, alle serverseitig auf WhitelistedJobs geprüft:

EmergencyOS:PanicButton — TriggerServerEvent. Payload: coords (vector3/Table mit x,y), streetName (string). Broadcastet 10-13 an alle Whitelist-Einheiten (bzw. übergibt an Vanguard, falls aktiv).

TriggerServerEvent("EmergencyOS:PanicButton", vec3(443.46,-982.45,30.68), "Mission Row")

EmergencyOS:ScanClosestPlayer — TriggerServerEvent. Payload: targetServerId (number). Serverseitige Distanzprüfung (≤ 6 m), öffnet die Personenakte des Ziels beim scannenden Beamten (ForceOpenRecord). Zählt als Aktivität scans.

TriggerServerEvent("EmergencyOS:ScanClosestPlayer", targetSource)

EmergencyOS:CheckALPR — TriggerServerEvent. Payload: plate (string, ≤ 12 Zeichen). Prüft BOLO-Status, Cooldown 10 s pro Spieler/Kennzeichen; bei Treffer ALPRResult an den Absender.

TriggerServerEvent("EmergencyOS:CheckALPR", "LS12345")

Verhaftungen ans Panel: über den Export RecordArrest(officerSrc) (siehe oben) — der empfohlene Weg aus dem CHANGELOG/examples/.

Dispatch ans Panel (Vanguard Gateway): Actions getDispatchState, dispatchCreateCall, dispatchAssign, dispatchClose; Live-Push über AddEventHandler('vanguard:dispatch:broadcast', …) → TriggerClientEvent('EmergencyOS:ReceiveLiveLog', -1, { dispatch = payload }).

Events & Commands

Commands (für Betreiber/Spieler relevant)

Wichtige Netz-Events (Auszug)

• Bürgerportal: Client→Server EmergencyOS:Citizen:GetTickets, EmergencyOS:Citizen:PayTicket(ticketId), EmergencyOS:Citizen:PayAll; Server→Client EmergencyOS:Citizen:Tickets, EmergencyOS:Citizen:PaidResult, EmergencyOS:Citizen:PaidAll. Zahlung holt frischen Preis (getOpenTickets.php), bucht ab, markiert atomar (setTicketPaid.php), zahlt an Society aus, mit Refund bei Fehler.
• Dienst & Statistik: EmergencyOS:Duty:Idle, EmergencyOS:Duty:GetMine, EmergencyOS:Duty:GetBoard(period); Antworten EmergencyOS:Duty:State/Mine/Board.
• Sonstige: EmergencyOS:openTablet, EmergencyOS:ForceOpenRecord, EmergencyOS:ALPRResult, EmergencyOS:PanicButtonAlert, EmergencyOS:RunPlate, EmergencyOS:TicketFx, EmergencyOS:TicketEvidence, EmergencyOS:SyncPosition (Live-Tracking), EmergencyOS:ReceiveLiveLog (Atlas/Dispatch), EmergencyOS:UpdateWantedBillboard, EmergencyOS:UpdateInternalMonitor.
• Billing: RegisterNetEvent(SVConfig.BillingTrigger) ("EmergencyOS:billPayed") → meldet billId als bezahlt ans Panel.

Hinweise / Troubleshooting

• Ordnername: Resource muss EmergencyOS heißen — alle exports['EmergencyOS'] und der Handshake (GetCurrentResourceName()) hängen daran.
• Sync erreicht Panel nicht / Konsolenmeldungen:
• „Kein API-Key hinterlegt" → SVConfig.API.key in api_config.lua fehlt/ist Platzhalter (eos_HIER_DEN_KEY_EINFUEGEN, selberapikeywieimancomoxdashboard).
• HTTP 400 → Anmeldedaten unvollständig: bei eos_…-Key darf nur der Key gesetzt sein; bei Legacy-Key müssen username+password gesetzt sein. Danach Resource neu starten.
• HTTP 401/403 → Key falsch/abgelaufen. Nach „Key neu generieren" im Panel den neuen Key eintragen. Weitere Versuche laufen leise alle 10 min.
• „Panel nicht erreichbar" → Netzwerk/Firewall; Retry-Backoff greift automatisch.
• Multi-IP-Server: Schlägt der Verbindungstest im Panel trotz laufendem Server fehl, die erreichbare FiveM-IP in SVConfig.API.serverIp eintragen (überschreibt die Auto-Erkennung).
• BOLO-Pull-Warnung (api/getWanteds.php HTTP ≠ 200) → Panel-Dateien nicht/veraltet deployed. Für Dev ohne deployte PHP: SVConfig.BoloDevFallback = true (nur bei geteilter DB).
• Framework-Bridge / Custom Framework: Bei Config.Framework="STANDALONE" liefern nur registrierte Data-Provider-Hooks Daten; ein Hook, der nil liefert, gilt als „nicht gefunden" (kein Fallback auf ESX/QB). Hooks müssen synchron sein (oxmysql:executeSync). Jobs zusätzlich über SetPlayerJob (Server und Client) setzen. getIdentifier muss Reconnects überleben (Server-IDs ungeeignet); ohne Provider wird die FiveM-License genutzt.
• Dienstzeiten falscher/kein Job erkannt: /emos_dutydebug zeigt den exakt erkannten Jobnamen → in Config.DutyStats.onDutyJobs bzw. jobFaction eintragen; Off-Duty-Jobs nicht auflisten.
• Ticket-Zeremonie ohne Beweisfoto: screenshot-basic fehlt oder Config.ScreenshotWebhook ist leer/Platzhalter → Evidence Cam deaktiviert.
• Tickets vor dem Update lassen sich nicht nachträglich Beamten zuordnen (Zählung ab Einspielen).
• Update-Check meldet dauerhaft „neue Version": version.json auf dem Webserver an die tatsächliche Resource-Version 3.9.6 anpassen.

DispatchOS — Dokumentations-Spec

Leitstellen-, Dispatch- und MDT-System für FiveM. Quelle: [ANCOMOX]/dispatchos · Version 2.22.0.

Überblick

Zweck: DispatchOS ist das zentrale Notruf-, Einsatz- und Leitstellensystem. Es nimmt Alarme (automatisch erkannt oder per API) entgegen, legt Einsätze („Calls") mit Priorität, Blip, Zone und Timeline an, verteilt sie an die zuständigen Fraktionsgruppen und stellt eine Vollbild-Leitstelle mit Taktikkarte bereit. Architektur laut Manifest: „RAM-first, Push statt Polling, serverseitig validiert".

Kernfeatures (aus README.md und Code verifiziert): - Automatische Einsätze (Detektoren): Schüsse, Drive-by, Fahrzeugraub, Schlägerei, Unfall, Raser, Person am Boden, ALPR-Treffer, Panik, Zivil-Notrufe — mit Merge naher Mehrfachmeldungen (MergeRadius/MergeTime). - Leitstelle / Dispatch Center (F6): Taktikkarte mit Live-Einheiten, Icon-Marker je Code, Einsatzliste + Filter, Detail-Dock mit Timeline & Notizen, Zuweisung, Fahndungs-Ticker (BOLO), Ø-Reaktionszeit-KPI, 7-Tage-Statistik-Cockpit, Panic-Auto-Fokus. - MDT (F7): Kennzeichen-/Personenabfrage aus der Spieldatenbank (DirectDB) oder über EmergencyOS-Gateway; Fahndungsabgleich, Live-Online-Status. - ALPR (F10/F11): Kennzeichenscanner im Einsatzfahrzeug per Raycast mit 3D-Holo-Marker und Fahndungstreffer. - Schnellfunk (F5): konfigurierbare 10-Codes + Freitext + Position. - Panic Button, Smart-3D-Ping, Eskalation (P3→P2→P1), Zonen-Routing, Rechte-System, Auto-Zuweisung bei Panik/Backup. - Notruf-Integration: lb-phone (Nachricht + Anruf + Handy-Alerts) und generische Export-API für andere Telefon-Scripts. - Optionale Web-Leitstelle (dispatchos.de) und EmergencyOS-Panel-Anbindung über FiveM-Events. - Zweisprachig (de/en), Discord-Webhook-Feed integriert.

Voraussetzungen

Das fxmanifest.lua deklariert keine dependencies — alle Abhängigkeiten werden zur Laufzeit per GetResourceState(...) weich erkannt. Manifest-Eckdaten:

Abhängigkeiten (alle laufzeit-erkannt, keine harte Pflicht):

Installation

1. Ordner dispatchos nach resources/ kopieren.
2. In server.cfg nach oxmysql, Framework und (optional) EmergencyOS starten: cfg ensure oxmysql ensure es_extended # bzw. qb-core / qbx_core ensure EmergencyOS # optional ensure dispatchos
3. Tabelle dispatchos_calls wird beim ersten Start automatisch angelegt bzw. migriert (fehlende Spalten werden ergänzt; einmalige Übernahme einer alten vanguard_calls-Tabelle).
4. config.lua anpassen — v. a. VConfig.JobGroups an die eigenen Fraktions-Jobs.

Panel-Bezug: Zwei optionale Anbindungen (beide ohne Ingame-Paywall): die gehostete Web-Leitstelle (VConfig.WebLink, Modul web_link) und das EmergencyOS-Panel (rein über FiveM-Events, siehe nächster Abschnitt).

Datenbank

Nur bei VConfig.PersistCalls = true und gestartetem oxmysql. Eine Tabelle:

dispatchos_calls — angelegt via CREATE TABLE IF NOT EXISTS, danach Auto-Migration der Spalten (SHOW COLUMNS → fehlende per ALTER TABLE ADD COLUMN).

Engine InnoDB, Charset utf8mb4. Retention: Zeilen älter als VConfig.DBRetentionDays werden periodisch gelöscht (Batch LIMIT 5000; 0 = nie). Einmal-Rename beim Start: falls vanguard_calls existiert und dispatchos_calls nicht, wird umbenannt (Bestandsdaten-Übernahme).

Die MDT-DirectDB liest zusätzlich fremde Tabellen (nur SELECT, keine eigene Anlage): ESX users/owned_vehicles, QBCore players/player_vehicles sowie optional eine lb-phone-Tabelle (Default phone_phones). Tabellennamen über VConfig.MDT.DirectDB überschreibbar.

Sync / Panel-Anbindung

A) EmergencyOS-Panel (Event-basiert, keine Webserver-Last)

Wird automatisch aktiv, sobald GetResourceState('EmergencyOS') == 'started': - BOLO/Fahndung: DispatchOS ruft per pcall einen der Exports exports.EmergencyOS:GetWanteds/GetBolos/GetWantedPlates/GetWantedList ab (erster funktionierender wird gemerkt) und exports.EmergencyOS:IsPlateWanted(plate). Push-Refresh über Listener EmergencyOS:WantedsUpdated. - Panic: Kompatibilitäts-Listener RegisterNetEvent('EmergencyOS:PanicButton', ...) — Tablet-Panik landet direkt als Einsatz (Dedupe über Cooldown). - Atlas-Feed: internes Event dispatchos:dispatch:broadcast transportiert alle Dispatch-/Funk-/Status-Ereignisse (auch Discord/Phone/WebLink hängen hier dran). - MDT-Gateway: exports.EmergencyOS:MdtLookup(payload, cb) (Panel-Akten + Live-Fallback), genutzt wenn DirectDB aus ist bzw. für Panel-Anreicherung (PanelEnrich/PanelFileLookup). - Akte öffnen: NUI-Callback mdtOpenRecord → TriggerEvent('EmergencyOS:ForceOpenRecord', id). - Externer Fokus: AddEventHandler('dispatchos:client:FocusCall', callId) öffnet die Leitstelle und fliegt per Kamera auf den Einsatz (für Atlas-Terminal-Klick). - Statistik/Heatmap: gemeinsame Tabelle dispatchos_calls.

Für vollen Umfang liegen dem EmergencyOS-Paket 3 aktualisierte Dateien bei (html/app.js, Panel-Terminal.php, kleine client.lua-Ergänzungen). MDT.PanelFileLookup erst nach verbundener Panel-API (gültiger API-Key) aktivieren.

B) Web-Leitstelle (modules/web_link/server.lua, optional)

Nur aktiv, wenn VConfig.WebLink.Token gesetzt und kein Platzhalter ist (Platzhalter-Liste im Code: '', HIER_DEN_TOKEN_EINFUEGEN, los_HIER_DEN_KEY_EINFUEGEN). Ohne gültigen Token: Modul kehrt sofort zurück → reines Standalone.

• Nur ausgehendes HTTPS (PerformHttpRequest), kein offener Port. Auth per Authorization: Bearer <Token> und Api-Key: <Token> (Apache/PHP-FPM-Kompatibilität).
• Handshake: GET {BridgeUrl}/v1/hello → prüft Token; Klartext-Feedback in der Konsole (gültig / abgelaufen / unerreichbar / ungültig).
• Push-Loop: Snapshot + Events an POST {BridgeUrl}/v1/ingest (Intervall PushIntervalMs, Queue max. 400). HTTP 403 = Abo abgelaufen → pausiert, Standalone läuft weiter.
• Command-Long-Poll: GET {BridgeUrl}/v1/commands?wait=<PollWaitSec>; führt Web-Kommandos aus (Executors: call.assign/unassign/close/note/create, unit.status/callsign, radio.send, gps.send, bolo.add/remove, sys.presence/resync/idle, config.set).
• Status-Global DispatchOSWebLink = { configured, linked } fürs Leitstellen-Settings-Panel.

Konfiguration

Alle Optionen aus config.lua (VConfig = {}). Zusätzlich am Ende die hartcodierten Blöcke aus server/main.lua (Discord/Auto-Panik) und Config-Keys, die der Code liest, aber die shipped config.lua nicht enthält (mit „(nicht in config.lua)").

Basis

JobGroups-Default: police = {leo, leo_city, leo_county}, lssd = {leo, leo_county}, fib = {leo, leo_city, leo_county}, justiz = {leo, leo_city, leo_county}, ambulance = {ems}.

MDT

DispatchCenter

Statuscodes, Eskalation, Funk

Radio.Codes-Default: 10-4 Verstanden, 10-8 Einsatzbereit, 10-6 Beschäftigt, 10-97 Am Einsatzort, 10-20 Standort durchgeben (pos), 10-13 Benötige Unterstützung (priority,pos), Code 2, Code 3.

Zones

Permissions

Jeder Wert: "unit" (jede Einheit) oder { jobs = { <job> = <Mindest-Grade> } }.

Zeiten, Merge, Blips, Melder

Keybinds & Panik

SmartPing (3D-Ping)

ALPR & Detektoren

Sounds

Je Ereignis { name, set } (Frontend-Sound) oder false (stumm). Keys mit Defaults: panic (Laster_10A/GTAO_Biker_FM_Soundset), p1/p2 (Beep_Red/DLC_HEIST_HACKING_SNAKE_SOUNDS), p3 (Text_Arrive_Tone/Phone_SoundSet_Default), alprHit, radio, radioPrio, ping (WAYPOINT_SET/HUD_FRONTEND_DEFAULT_SOUNDSET).

AutoCalls

Je Auslöser: enabled, code, labelKey, priority (1–3), groups, meist cooldown (s), ignoreUnits (Einsatzkräfte lösen nicht selbst aus), teils minSpeed, plus blip = { sprite, color, scale }.

Locales

VConfig.Locales.de / .en — vollständige Text-Tabellen (HUD, Leitstelle, MDT, Funk, BOLO, Meldungen). Labels der AutoCalls kommen über labelKey (z. B. lbl_shots, lbl_panic).

WebLink

Phone

Config-Keys, die der Code liest, aber die config.lua NICHT enthält (Defaults im Code)

Hartcodierte Blöcke in server/main.lua (nicht in config.lua)

Discord-Feed (local DISCORD): enabled=true, webhook="https://discord.com/api/webhooks/DEINE/URL_HIER" (eintragen), username="Leitstelle", avatar="", postNew=true, postClosed=true, postRadio=false, pingRoleOnPanic="". Postet neue/geschlossene Einsätze (optional Funk/Panik-Ping) über dispatchos:dispatch:broadcast.

Auto-Panik-Zuweisung (local AUTO_PANIC): enabled=true, onlyIfUnassigned=true, notifyUnit=true. Weist bei neuem Panik-Einsatz automatisch die nächste freie On-Duty-Einheit derselben Abteilung zu.

Exports

Insgesamt 23 Exports (README nennt „~21"): 18 Server in server/main.lua, 1 Server in modules/phone/server.lua, 4 Client in client/main.lua. Namen SetPlayerJob und CreateCall existieren doppelt (client- und serverseitig, unterschiedliche Signatur/Wirkung — Kontext beachten).

Aufruf serverseitig: exports.dispatchos:Name(...) bzw. exports['dispatchos']:Name(...). Ressourcenname = Ordnername (dispatchos).

Server-Exports (server/main.lua)

1. CreateCall(data) — Seite: server - Signatur: exports.dispatchos:CreateCall(data) — data muss data.coords = {x,y,z} enthalten. - Felder (alle optional außer coords): code (≤16, Default "CALL"), label (≤120, Default "Einsatz"), priority (1–3, Default 3), groups (Default {"leo"}, danach Zonen-Routing), street (≤96), plate (≤12), vehName (≤40), details (≤200), sender (≤40), panic (bool), mergeKey, blip = {sprite,color,scale}. - Rückgabe: Call-id (number) — oder bei Merge die bestehende id; nil bei ungültigen Daten. - Beschreibung: Kern-Funktion zum Anlegen eines Einsatzes; führt Merge (gleicher mergeKey im Radius/Zeitfenster), Zonen-Routing, Broadcast an passende Gruppen und DB-Insert aus.

local id = exports.dispatchos:CreateCall({
    code='10-90', label='Fahrzeugraub', priority=2,
    groups={'leo'}, coords={x=215.3,y=-810.1,z=30.0},
    street='Legion Square', mergeKey='mycustom'
})

2. CloseCall(id, closedBy) — server · Signatur (id, closedBy) → bool. Schließt Einsatz, schreibt closed_at/reports/units, informiert Gruppen. closedBy = Anzeigename im Feed.

exports.dispatchos:CloseCall(42, 'ADMIN')

3. AttachUnit(id, src) — server · (callId, playerSrc) → bool. Weist Einheit zu (setzt Waypoint, Status active, responded_at). Nur wenn Einheit die Gruppe teilt.

4. DetachUnit(id, src) — server · (callId, playerSrc) → bool. Entfernt Einheit; ohne verbleibende Einheiten → Status pending.

5. AddDispatchCall(code, label, details, coords, priority, groups, blip, mergeKey, plate, vehName, sender) — server · Positionsargumente-Wrapper um CreateCall → gibt id zurück. priority Default 3, groups Default {"leo"}, sender Default "System".

local id = exports.dispatchos:AddDispatchCall(
  '10-31','Alarm',nil,{x=1.0,y=2.0,z=3.0},1,{'leo'},60)

6. Alarm(a) — server · Öffentliche Alarm-API → id oder nil. a.type: 'ladenraub' (10-90, P2), 'bankraub' (10-90, P1), 'gefaengnisausbruch' (10-98, P1) oder 'custom'. Weitere Felder: coords, code, label, details, priority, groups (Default {'leo'}), blip, mergeKey, sender. Auch via Event TriggerEvent('dispatchos:alarm', a).

local id = exports.dispatchos:Alarm({
  type='custom', code='10-31', label='Juwelier-Alarm',
  coords=coords, priority=1, groups={'leo'}, blip=617 })

7. GetCall(id) — server · → öffentliche Call-Tabelle (id, code, label, priority, coords, street, units, history, …) oder nil.

8. GetActiveCalls() — server · → Array aller aktiven Einsätze (öffentliche Form), nach id absteigend sortiert.

9. GetUnits() — server · → Array aller On-Duty-Einheiten {src, name, callsign, status, job}.

10. AddWantedPlate(p, reason) — server · Setzt lokale Fahndung (BOLO) für Kennzeichen; reason ≤90. Pusht an Leitstellen-Viewer. Keine Rückgabe.

exports.dispatchos:AddWantedPlate('ABC123', 'Fahrerflucht')

11. RemoveWantedPlate(p) — server · Entfernt lokale Fahndung. Keine Rückgabe.

12. SetPlayerJob(src, job) — server · Setzt Job im STANDALONE-Tracker (StandaloneJobs[src]). Für Server ohne ESX/QBCore.

exports.dispatchos:SetPlayerJob(source, 'police')

13. SetPlayerDuty(src, state) — server · Setzt Duty-Flag (DutyStates[src]). Wirkt mit UseDuty=true.

14. LstSetStatus(src, st) — server · Web-Leitstand-Wrapper → bool. Setzt Unit-Status (validiert gegen Statuses).

15. LstSetCallsign(src, cs) — server · → true. Setzt Funkrufname.

16. LstGps(src, x, y) — server · → bool. Sendet Waypoint an Einheit.

17. LstAddNote(id, who, text) — server · → bool. Fügt Notiz (≤140) an Einsatz-Timeline.

18. LstRadio(who, code, text) — server · → bool. Sendet Funkspruch an alle Einheiten.

14–18 („Lst…") sind bewusst schlanke Wrapper für das Web-Link-Modul, funktionieren aber auch direkt.

Server-Export (modules/phone/server.lua)

19. PhoneEmergencyCall(data) — server · Generische Notruf-API für beliebige Telefon-Scripts → callId oder nil. - Felder: x, y (Pflicht), z, code, label, details (≤140), priority (1–3), group ('leo'|'ems'|'both') oder groups, sender (≤24) oder anonymous=true. Eingebauter Cooldown pro Sender (VConfig.Phone.Cooldown), automatischer mergeKey='phone:<sender>'.

local id = exports.dispatchos:PhoneEmergencyCall({
  x=215.3, y=-810.1, details='Bewaffneter Überfall',
  sender='555-0123', group='leo', priority=2, code='911', label='Notruf' })

Client-Exports (client/main.lua)

20. CreateCall(data) — client · Third-Party-Integration. Ergänzt fehlende data.coords mit der Spielerposition und feuert TriggerServerEvent('dispatchos:server:CreateExternalCall', data). Keine Rückgabe (asynchron). Serverseitig gilt für echte Spieler: On-Duty-Pflicht, Rate-Limit, panic wird verworfen.

exports.dispatchos:CreateCall({ code='911', label='Notruf', priority=2 })

21. SetPlayerJob(job) — client · Setzt DispatchOSJob lokal (für Standalone/eigene Job-Logik). Keine Rückgabe.

22. SetDuty(state) — client · Setzt DispatchOSOnDuty lokal. Keine Rückgabe. (Beachte: Export heißt client SetDuty, server SetPlayerDuty.)

23. TriggerPanic() — client · Löst den Panic-Button aus (ExecuteCommand('dispatchpanic')). Keine Rückgabe.

exports.dispatchos:TriggerPanic()

Events & Commands

Öffentliche/Integrations-Events (für eigene Scripts relevant)

• TriggerEvent('dispatchos:alarm', { type=..., coords=..., details=... }) — serverseitig, Alarm auslösen (Pendant zu Export Alarm).
• TriggerEvent('dispatchos:server:CreateExternalCall', data) — serverseitig (source 0 erlaubt) Einsatz anlegen; von Spieler-Clients gesendet gilt On-Duty + Rate-Limit, panic entfernt.
• dispatchos:dispatch:broadcast — internes Feed-Event ({action='new'|'closed'|'update'|'unit'|'radio', …}); Anknüpfpunkt für Discord, lb-phone-Push, Web-Link, EmergencyOS-Atlas und Auto-Panik. Nicht von Clients auslösbar.
• dispatchos:client:FocusCall(callId) — clientlokal, öffnet Leitstelle mit Kamera-Flug (Atlas-Integration).
• Gehörte Fremd-Events: EmergencyOS:PanicButton, EmergencyOS:WantedsUpdated, lb-phone:newCompanyMessage, lb-phone:callEnded. Ausgelöst: EmergencyOS:ForceOpenRecord.

Client-seitige Server-Events (Auszug, spielergebunden, mit IsUnit/Cooldown/Permission-Guards)

dispatchos:server:WhoAmI, RespondCall, MarkArrived, RequestDispatchState, GetStatsFull, DcViewer, CloseCallReq, LeaveCallReq, SetStatus, SetCallsign, SendRoute (Perm AssignUnits), RadioSend, AddNote (Perm AddNotes), ManualCall (Perm CreateCall), AssignUnit/UnassignUnit (Perm AssignUnits), AutoCall, PanicButton, AlprScan, ReportPos, RequestBackup, SmartPing, SyncDraw/ClearBoard (Whiteboard). MDT: dispatchos:mdt:LookupPlate, SearchPerson, PersonDetail.

Commands & Standard-Keybinds

* Alle Tasten in config.lua und pro Spieler unter GTA-Einstellungen → Tastenbelegung → FiveM änderbar.

Hinweise / Troubleshooting

• Einsatzkräfte lösen keine Auto-Alarme aus → Absicht: ignoreUnits = true (Produktions-Default). Zum Testen im jeweiligen AutoCalls-Eintrag auf false.
• fight ist standardmäßig aus (enabled=false) — bei Bedarf aktivieren.
• Kein Blip/keine Karte für einen Job → Job in JobGroups eintragen und Zonengruppen (leo_city/leo_county) prüfen.
• F6 öffnet nicht → anderes NUI hält den Focus (FocusGuard). /dcdiag zeigt Job/Unit/Focus-Status; notfalls DispatchCenter.FocusGuard = false.
• „Panel nicht erreichbar" im MDT → MDT.PanelFileLookup erst nach eingerichteter EmergencyOS-Panel-API aktivieren; ohne DirectDB und ohne EmergencyOS liefert das MDT nur BOLO-Fahndung.
• Diagnose-Schalter → VConfig.DetectorDebug = true (Detektoren) bzw. VConfig.MDT.Debug = true (MDT-Kette; Default bereits „an", da Debug ~= false).
• Ohne oxmysql → Konsolenhinweis „Calls werden nicht persistiert (Heatmap bleibt leer)"; Statistik fällt auf In-Memory (seit Serverstart) zurück, Kern bleibt voll funktionsfähig.
• Standalone-Job setzen → ohne ESX/QBCore Job/Duty über die Exports SetPlayerJob/SetPlayerDuty (Server) bzw. SetPlayerJob/SetDuty (Client) pflegen, sonst zählt niemand als Einheit.
• Discord-Feed ist im Code aktiviert (enabled=true), postet aber nur mit gültiger webhook-URL (sonst still verworfen).
• Sounds reminder/arrived werden clientseitig abgespielt, sind aber in VConfig.Sounds nicht definiert → bleiben stumm, bis ergänzt.

LicenseOS — Entwickler-Dokumentation

Ressourcen-Ordner: licenseos · fxmanifest-Version 1.0.0 · Frameworks: ESX · QBCore · Qbox · ox_core · Standalone

Überblick

LicenseOS ist ein Führerschein- und Fahrschulsystem für FiveM. Die eigentliche Fach-Logik (Lizenzkatalog, Prüfungsbögen, Preise, Fahrstunden-Vorgaben) läuft in einem externen Web-Panel (https://licenseos.app). Die hier dokumentierte FiveM-Ressource ist die Server-Bridge + NUI-Anbindung zu diesem Panel — sie enthält selbst keine Prüfungsinhalte, sondern verbindet Spielserver und Panel.

Die Ressource leistet vier Dinge:

1. Panel ingame öffnen — das Web-Panel wird als NUI-iframe geladen (Muster: EmergencyOS-Tablet). Fahrlehrer arbeiten ingame mit demselben Panel wie im Browser, per Web-Login. Die Berechtigung wird serverseitig geprüft.
2. Server-Bridge — Handshake ans Panel, plus ein eingehender Push-Endpunkt, über den das Panel Lizenz-Änderungen live an den Spielserver meldet.
3. Exports — Lizenz-Checks (HasLicense, GetLicenses, …) für eigene Scripts, mit RAM-Cache und optionalem lokalem DB-Cache.
4. Framework-Sync — Lizenz-Änderungen aus dem Panel werden live ins Framework gespiegelt (ESX user_licenses, QB/Qbox metadata.licences, ox_core Charakter-Metadaten).

Lizenzarten (aus Config.LicenseMapping)

Die Klassen-Namen (A1, B, FLUG …) stammen aus dem Panel; die Mapping-Tabelle ist frei erweiterbar (siehe Konfiguration).

Prüfungen & Vorgänge

• Theorieprüfung — Fahrlehrer starten per /theorie <klasse> eine Gruppenprüfung; alle Spieler im Umkreis (Config.TheoryRadius) bekommen den Prüfungsbogen automatisch als Panel-Overlay eingeblendet.
• Fahrstunde — Fahrlehrer tragen per /fahrstunde <id> <minuten> [notiz] Fahrstunden ein; das Panel zählt Richtung eines Soll-Werts (totalMinutes/required).
• Praktische Prüfung / Lizenzvergabe / Gebühren — werden im Web-Panel abgewickelt.
• Bürger-Abfrage — Spieler rufen per /lizenzen ihre Lizenzen, Punkte, Gültigkeit und offenen Gebühren im Chat ab.

Lizenz-Status

aktiv · gesperrt · entzogen · abgelaufen (werden in Benachrichtigungen und im licenseos:licenseUpdate-Event verwendet).

Voraussetzungen

fxmanifest.lua:

• Harte Abhängigkeit: nur /assetpacks.
• Framework: ESX (es_extended), QBCore (qb-core), Qbox (qbx_core) oder ox_core (ox_core) — automatisch erkannt, keine Anpassung nötig. Auch Standalone (ohne Framework) läuft; dann Identifier license:….
• Datenbank / oxmysql: optional, aber empfohlen. Wird per GetResourceState('oxmysql') erkannt. Ohne oxmysql schaltet sich der lokale Lizenz-Cache automatisch ab (dann nur RAM-Cache + Live-API); die Offline-Spielersuche entfällt ebenfalls.
• Web-Panel-Account mit erzeugtem API-Key (Panel → Einstellungen → FiveM-Bridge).
• Netzwerk: Der Spielserver-HTTP-Port (Convar netPort, Standard 30120) muss vom Webserver aus per HTTP erreichbar sein, damit Panel-Pushes ankommen. Exports & Befehle (Richtung Spiel → Panel) funktionieren auch ohne eingehende Erreichbarkeit.
• Optionale Notify-Ressourcen: okokNotify oder ox_lib (sonst Chat-Fallback).

Installation

1. Ordner als licenseos in resources/ ablegen.
2. Im Web-Panel einen API-Key erzeugen (Einstellungen → FiveM-Bridge, als Inhaber/Admin) und in config.lua eintragen: lua Config.PanelURL = 'https://licenseos.app' -- OHNE abschließenden / Config.ApiKey = 'los_...'
3. In die server.cfg eintragen: cfg ensure licenseos
4. Server starten. Beim Start meldet sich der Server am Panel an (/bridge/getInstance.php) und registriert automatisch den Push-Rückkanal (IP/Port/Resource) — es muss keine Server-IP im Panel eingetragen werden.

Reihenfolge: oxmysql und das genutzte Framework sollten vor licenseos gestartet sein. Die Ressource wartet aber nach: bei Config.Framework = 'auto' bis zu 10 s auf ein Framework, bei erzwungenem Framework bis zu 30 s (und weicht dann nie still auf ein anderes aus, sondern auf Standalone).

Berechtigungen setzen (server.cfg):

# Panel ingame öffnen (zusätzlich zu Config.AllowedJobs):
add_ace group.admin licenseos.open allow

# Fahrlehrer-Befehle /fahrstunde und /theorie:
add_ace group.fahrlehrer licenseos.instructor allow
add_principal identifier.license:DEINE_LICENSE group.fahrlehrer

Panel-Bezug: Das Panel wird ingame über /licenseos bzw. Taste F7 geöffnet und als iframe von Config.PanelURL geladen. Login-Daten werden nur lokal auf dem PC des Spielers gecacht (SetResourceKvp), nie auf dem Server.

Datenbank

Die Ressource legt eine eigene Tabelle an, sofern Config.LocalLicenseCache = true und oxmysql läuft. Die Tabelle wird automatisch beim ersten erfolgreichen Handshake erstellt (kein manuelles SQL-Import nötig):

CREATE TABLE IF NOT EXISTS licenseos_licenses (
    license_no VARCHAR(32) PRIMARY KEY,
    identifier VARCHAR(80) NOT NULL,
    owner_name VARCHAR(60) NOT NULL DEFAULT '',
    class      VARCHAR(6)  NOT NULL,
    status     VARCHAR(12) NOT NULL,
    points     INT NOT NULL DEFAULT 0,
    expires_at DATE DEFAULT NULL,
    INDEX idx_lic_ident (identifier, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

• Master bleibt das Panel. Diese Tabelle ist nur ein lokaler Spiegel: Voll-Sync beim Start (DELETE + Neu-Einfügen), Delta-Sync alle 15 Min (?since=…), plus Live-Pushes. Datenquelle: PanelURL/bridge/export.php.
• Vorteil: HasLicense/GetLicenses laufen ohne Internet-Roundtrip; der Server bleibt bei Panel-Wartung spielbar.
• Zusätzlich genutzte (Framework-)Tabellen — nur lesend für die Spielersuche bzw. schreibend für den Sync, werden nicht von dieser Ressource angelegt:
• ESX: users (Suche), user_licenses (Lizenz-Spiegel)
• QBCore/Qbox: players (Suche), metadata.licences (Spiegel, über Player-API)
• ox_core: characters (Suche), Charakter-Metadaten licenseos:<fwLicense> (Spiegel)

Sync / Panel-Anbindung

Die Bridge kommuniziert in beide Richtungen über HTTP-Endpunkte unterhalb von Config.PanelURL. Authentifizierung durchgehend per Api-Key-Header (bzw. Authorization beim eingehenden Endpunkt), zeitkonstant verglichen.

Ausgehend (Spiel → Panel)

Eingehend (Panel → Spiel, SetHttpHandler auf Port netPort)

Abgesichert durch: zeitkonstanten Key-Vergleich (SecureCompare), Rate-Limit (Config.ApiRateLimit/10 s), Body-Limit (Config.ApiMaxBodyBytes), 15-s-Watchdog-Timeout (504).

Datenschutz by Design: Es gibt keinen automatischen Bürger-Sync beim Joinen. Spieler werden nie pauschal ans Panel übertragen; die Suche läuft live, gespeichert wird ein Spieler erst bei einem echten Vorgang (Lizenz, Prüfung, Fahrstunde).

Lizenz vergeben/entziehen erfolgt im Panel (bzw. wird per licenseUpdate an den Server gepusht) — dafür gibt es bewusst keinen Export. Die Ressourcen-Exports sind lesend (siehe unten).

Konfiguration

Vollständige config.lua. Alle Werte sind die echten Defaults.

Config.AllowedJobs — Job → Mindest-Grade

Erweitern: einfach weitere ['jobname'] = mindestGrade ergänzen. Bei ox_core werden die Keys als Gruppennamen gegen player.getGroup(name) geprüft.

Config.LicenseMapping — Panel-Klasse → Framework-Lizenz

Mehrere Panel-Klassen dürfen auf dieselbe Framework-Lizenz zeigen (z. B. B und BE → drive). Beim Entzug entfernt die Bridge die Framework-Lizenz nur, wenn keine andere aktive Panel-Klasse dasselbe Mapping benötigt.

Was wo konfiguriert wird — wichtig

• Lizenzarten (Katalog), Prüfungsinhalte, Preise/Gebühren werden im Web-Panel gepflegt, nicht in config.lua. In der Ressource legt man nur fest, wie diese ins Spiel wirken:
• Lizenzen: über Config.LicenseMapping (welche Panel-Klasse welche Framework-Lizenz setzt) und Config.SyncFramework.
• Prüfungen: über Config.TheoryCommand und Config.TheoryRadius (Start & Einladungsradius der Theorieprüfung); Bögen/Bestehensgrenzen/praktische Prüfung liegen im Panel.
• Preise/Gebühren: rein im Panel; die Ressource zeigt nur die vom Panel gelieferten openFees (/lizenzen) an.

Exports

Alle vier Exports sind serverseitig (in server/main.lua). Aufruf aus Server-Scripts über exports.licenseos:…. Als identifier ist der Framework-Identifier zu übergeben: ESX identifier, QBCore/Qbox citizenid, ox_core stateId, Standalone license:….

1. GetCommunityId

• Seite: Server
• Signatur: exports.licenseos:GetCommunityId()
• Parameter: keine
• Rückgabe: number | nil — die Community-ID nach erfolgreichem Handshake, sonst nil (noch nicht verbunden).
• Beschreibung: Liefert die vom Panel vergebene Community-ID. Nützlich für Support-Anfragen und zur Prüfung, ob die Bridge verbunden ist.

local id = exports.licenseos:GetCommunityId()
print(id and ('Verbunden, Community ' .. id) or 'Bridge noch nicht verbunden')

2. GetLicenses

• Seite: Server
• Signatur: exports.licenseos:GetLicenses(identifier, cb)
• Parameter: identifier (string), cb (function) — wird mit dem Ergebnis aufgerufen.
• Rückgabe (via Callback): Array aktiver Lizenzen; jeder Eintrag: { class, license_no, status, points, expires_at }.
• Beschreibung: Holt die aktiven Lizenzen eines Spielers. Reihenfolge der Quellen: lokale Tabelle (falls Cache aktiv & bereit) → RAM-Cache (< CacheTTL) → Live-API (/bridge/licenses.php). Kein Callback-Typ = No-Op.

exports.licenseos:GetLicenses(identifier, function(licenses)
    for _, l in ipairs(licenses) do
        print(l.class, l.license_no, l.points, l.expires_at)
    end
end)

3. HasLicense

• Seite: Server
• Signatur: exports.licenseos:HasLicense(identifier, class, cb)
• Parameter: identifier (string), class (string, z. B. 'B'), cb (function(has)).
• Rückgabe (via Callback): boolean — ob eine aktive Lizenz der Klasse existiert.
• Beschreibung: Async-Check (empfohlen für normale Wege). Nutzt intern GetLicenses und damit denselben Cache.

-- Beispiel: Fahrzeug nur bei gültiger PKW-Lizenz freigeben
exports.licenseos:HasLicense(identifier, 'B', function(has)
    if not has then
        -- z. B. Motor sperren, Strafe, Hinweis ...
        TriggerClientEvent('ox_lib:notify', src, { description = 'Kein Führerschein Klasse B!' })
    end
end)

4. HasLicenseCached

• Seite: Server
• Signatur: local has = exports.licenseos:HasLicenseCached(identifier, class)
• Parameter: identifier (string), class (string).
• Rückgabe: boolean — synchron, nur aus dem RAM-Cache. false, wenn für den Spieler noch kein HasLicense/GetLicenses lief (Cache leer).
• Beschreibung: Kein HTTP, für Hot-Paths (z. B. jeden Frame / beim Einsteigen). Voraussetzung: der Spieler wurde vorher einmal geladen.

-- Hot-Path: vorher einmal HasLicense/GetLicenses aufrufen, um den Cache zu füllen
if not exports.licenseos:HasLicenseCached(identifier, 'C') then
    -- LKW-Lizenz fehlt (nach Cache-Stand)
end

Lizenz geben/entziehen: dafür existiert kein Export. Das geschieht im Panel und wird per licenseUpdate-Push an den Server übernommen — koppelbar über das Event licenseos:licenseUpdate (siehe unten).

Events & Commands

Events

-- Eigene Systeme an Lizenz-Änderungen koppeln:
AddEventHandler('licenseos:licenseUpdate', function(identifier, class, status, data)
    if status == 'entzogen' and class == 'B' then
        -- z. B. Fahrzeugschlüssel sperren
    end
end)

NUI-Callbacks (Client, intern): close, saveLogin, getLogin, clearLogin — verwalten den lokalen Login-Cache (KVP) und das Schließen.

Commands

Hinweise / Troubleshooting

• „Kein API-Key in config.lua hinterlegt — Bridge inaktiv." → Config.ApiKey ist leer oder noch der Platzhalter los_HIER_DEN_KEY_EINFUEGEN. Echten Key aus Panel → Einstellungen → FiveM-Bridge eintragen.
• HTTP 401 beim Handshake → falscher/abgelaufener API-Key. Panel-Key prüfen bzw. neu erzeugen.
• Panel-Pushes kommen nicht an (Lizenzänderungen erscheinen ingame nicht sofort) → der Spielserver-Port (netPort, Standard 30120) ist vom Webserver aus nicht erreichbar. Firewall/Portfreigabe prüfen. Exports/Befehle (Spiel → Panel) laufen davon unabhängig.
• Lokaler Cache bleibt aus („oxmysql nicht gestartet") → oxmysql wird nicht vor licenseos gestartet. ensure oxmysql vor ensure licenseos setzen. Ohne oxmysql läuft die Ressource mit RAM-Cache + Live-API weiter, aber ohne Offline-Suche.
• Falsches Framework erkannt → Config.Framework explizit setzen. Erzwungenes Framework wartet bis zu 30 s auf die Ressource und weicht nie still auf ein anderes aus (fällt sonst auf Standalone). Bei 'auto' wird qbx_core vor qb-core geprüft (Qbox liefert eine qb-core-Bridge mit).
• HasLicenseCached liefert false, obwohl Lizenz vorhanden → RAM-Cache für den Spieler noch leer. Vorher einmal HasLicense/GetLicenses aufrufen (oder lokalen Cache aktiv lassen).
• Panel öffnet nicht / „keine Berechtigung" → weder passender Job-Grade in AllowedJobs noch Ace licenseos.open. Berechtigung wird ausschließlich serverseitig geprüft.
• Fahrlehrer-Befehle reagieren nicht → Ace licenseos.instructor fehlt (add_ace + add_principal in server.cfg).
• Datenschutz: Kein automatischer Bürger-Sync beim Join — gewollt. Spieler werden erst bei einem echten Vorgang im Panel gespeichert.

Ancomox Garage — Entwickler-Dokumentation

Überblick

ancomox_garage (Handelsname „Zenith Glass Edition Garage") ist ein premium Multi-Framework-Garagensystem für FiveM. Es verwaltet das Ein- und Ausparken von Fahrzeugen über ein modernes Glass-NUI mit 3D-Fahrzeugvorschau und deckt weit mehr als eine klassische Garage ab.

Kernfunktionen - Öffentliche & Job-Garagen (statisch aus Config oder dynamisch per In-Game-Creator in der DB) - Fahrzeug einparken/ausparken, umbenennen, Schlüssel teilen (2 Stufen: Drive / Drive & Park) - Impound (job-basiert, Gebühr, Sperrzeit) + Verwahrstelle/Impound-Lot (Auslösung) + Schrottplatz für „verlorene" Fahrzeuge - Private, kaufbare Garagen in 3 Vanilla-GTA-Interiors (2/6/10 Stellplätze, kein MLO nötig, eigene Routing-Bucket-Instanz) - Vehicle Transfer (Besitzübertragung zwischen Spielern, optional gegen Bezahlung) - Valet (eingelagertes Fahrzeug liefern lassen), Admin-Fahrzeug-Panel, Housing-Bridge - Fahrzeug-Lock (Keymapping), GPS-Tracking, Fuel-Bridges, optionale ox_target/qb-target-Integration - Discord-Webhook-Logs für alle relevanten Aktionen

Autor: Ancomox | Emergency OS

Voraussetzungen

Installation

1. Ordner ancomox_garage nach resources/ (bzw. [ANCOMOX]/) kopieren.
2. In der server.cfg ensure oxmysql VOR ensure ancomox_garage setzen (Reihenfolge ist wichtig).
3. In config/config.lua Config.Framework auf "auto" lassen (erkennt ESX/QBCore/QBox) oder fest auf "esx", "qb" bzw. "custom" setzen.
4. Server starten — es muss KEINE SQL-Datei importiert werden, das Script legt seine Tabellen beim ersten Start selbst an und ergänzt fehlende Fahrzeug-Spalten automatisch.

Empfohlene server.cfg-Reihenfolge:

ensure oxmysql
# ggf. Framework, ox_lib, target, fuel ...
ensure ancomox_garage

Datenbank

Es ist kein manueller SQL-Import nötig. Bei MySQL.ready werden folgende Tabellen per CREATE TABLE IF NOT EXISTS angelegt und bestehende Fahrzeugtabellen migriert (EnsureColumnExists):

Automatisch ergänzte Spalten in deiner Fahrzeugtabelle (Config.CustomFramework.VehiclesTable, Default owned_vehicles): fuel (INT 100), name (VARCHAR 100), pound_time (INT 0), impound_reason (VARCHAR 120), impound_by (VARCHAR 64), last_x/last_y/last_z (FLOAT), garage_id (VARCHAR 64) sowie bei DBStyle = "esx" zusätzlich pound (TINYINT).

Konfiguration

config/config.lua — Core-Einstellungen

Config.CustomFramework (nur bei Framework "custom" / wenn auto nichts findet)

Custom-Anbindung: Pflichtfunktion Custom_GetPlayer in server/open.lua implementieren (muss identifier, name, job, group, getMoney, removeMoney, addMoney, jobGrade, source zurückgeben). addMoney ist Pflicht für Transfer-/Garagenverkäufe. Client-seitig bei Jobwechsel TriggerEvent('ancomox_garage:setJob', jobName) feuern.

Config.PrivateGarages (Premium — kaufbare private Garagen)

Interiors-Eintrag (je small/medium/large): label, capacity (2/6/10), playerEnter (vector4), exitPoint (vector3), menuPoint (vector3), slots (Liste von vector4-Stellplätzen). Z-Höhe der drei Vanilla-Garagen ist bewusst -99.60 (knapp über dem Interior-Boden).

Locations-Eintrag (Table-Key = eindeutige DB-ID):

Default-Standorte: legion_small ($65.000), grove_medium ($145.000), sandy_large ($295.000).

Config.PrivateGarageUpgrades

Config.VehicleTransfer (Premium — Besitzübertragung)

Config.Valet (Premium — Fahrzeug liefern lassen)

Config.Keys (Premium — Fahrzeugschlüssel-Bridge)

Config.AdminPanel

Config.HousingBridge

Config.PreviewCustomization

Config.Target & Config.TextUI

Config.ServerSpawn (Anti-Dupe, opt-in)

Config.Performance

Fahrzeug-Lock & System-Settings

UI, Kamera, Distanzen, Fuel

Config.NotifyClient / Config.NotifyServer (Funktionen)

Standard-Benachrichtigungen. NotifyClient(msg, type) und NotifyServer(source, msg, type) verzweigen intern nach ESX (ShowNotification / esx:showNotification) bzw. QB (Functions.Notify / QBCore:Notify). Für Custom-Frameworks hier anpassen.

Impound, Schrottplatz & Verwahrstelle

Config.Impound (Beschlagnahmungs-/Impound-Interaktionspunkt):

Config.ScrapYard (Schrottplatz für „verlorene" Fahrzeuge):

Config.ImpoundLot (physische Verwahrstelle/Depot zum Auslösen):

Config.Garages — statische Garagen (nur bei UseDatabaseGarages = false)

Enthält rund zwei Dutzend vordefinierte Standard-Garagen (öffentliche + Job-Garagen für police, ambulance, mechanic, merryweather, admin sowie Boots-/Air-Garagen). Struktur eines Garagen-Eintrags:

Neue Garage anlegen — Variante A (statisch, in Config.Garages)

Neuen Eintrag in die Config.Garages-Liste ergänzen. Beispiel öffentliche PKW-Garage:

{
    location = vector4(-1985.00, 3065.13, 32.81, 102.20),  -- Garage öffnen
    spawnPos = vector4(-1993.00, 3067.41, 32.81, 57.95),   -- Fahrzeug-Ausgabe
    job = nil,                                             -- nil = für alle
    spawnNPC = true,
    npcHash = 'a_m_y_business_02',
    blip = { sprite = 357, color = 3, scale = 0.75, name = "Garage" },
    markerSettings = { id = 25, size = {x = 5.0, y = 5.0, z = 1.0}, color = {r = 0, g = 255, b = 0, a = 100} },
    vehicleTypes = {"car"},
    vehicleClasses = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 19, 20}
}

Beispiel Job-Garage (Polizei):

{
    location = vector4(451.94, -973.12, 25.70, 176.38),
    spawnPos = vector4(450.43, -977.88, 25.70, 102.37),
    job = 'police',
    spawnNPC = true,
    npcHash = 'a_m_y_business_02',
    blip = { sprite = 60, color = 29, scale = 0.8, name = "Police Garage" },
    vehicleClasses = {18, 20, 0, 1, 2}
}

Neue Garage anlegen — Variante B (dynamisch, empfohlen bei UseDatabaseGarages = true)

Im Spiel als Admin /creategarage → Platzierung per Raycast, Job-Bindung, Fahrzeugtyp-/Klassenfilter, Blip-Einstellungen, optional Company fleet (society) + Mindest-Job-Rang. Speicherung in ancomox_garages, sofortiger Sync an alle Clients. Private Standorte im selben Creator unter Tab „Private Garages" (Name, Interior small/medium/large, Preis, Entrance + Vehicle Exit Point) → Speicherung in ancomox_private_locations.

config/locales.lua — Sprachdatei

Locales enthält vollständige en- und de-Blöcke. Sprache über Config.Locale wählen; eigene Sprache = Block kopieren, Kürzel ändern, übersetzen. Strings mit %s/%d sind Format-Platzhalter (nicht entfernen). Übersicht der Schlüsselgruppen:

(Beide Sprachblöcke enthalten jeweils dieselbe Schlüsselmenge; Standardwerte sind die englischen bzw. deutschen Klartexte oben in config.lua-Nähe zitiert.)

config_logs.lua — Discord-Webhook-Konfiguration

Config_Logs = {
    Webhooks = {
        Store    = "",   -- Fahrzeug eingeparkt
        ParkOut  = "",   -- Fahrzeug ausgeparkt / verschoben / Valet
        Impound  = "",   -- Beschlagnahmung / Auslösung
        Scrap    = "",   -- Schrottplatz / kostenlose Wiederherstellung / Löschung
        Admin    = "",   -- Admin- & Creator-Aktionen
        Transfer = "",   -- Fahrzeug-Übertragungen zwischen Spielern
        Property = ""    -- Kauf/Verkauf privater Garagen, Mitglieder, Upgrades
    },
    LogSettings = {
        Store = true, ParkOut = true, Impound = true, Scrap = true,
        Admin = true, Transfer = true, Property = true
    }
}

Ein Log wird nur gesendet, wenn LogSettings[typ] = true und die passende Webhook-URL gesetzt ist. Ein leerer String oder eine Demo-Webhook (interner Guard api/webhooks/119887…) unterdrückt den Versand.

Exports

Beide Exports liegen client-seitig in client/client.lua und dienen der Housing-Bridge. Sie sind nur aktiv, wenn Config.HousingBridge.Enabled = true. Beide geben keinen Wert zurück (kein Rückgabewert / nil).

1. OpenHouseGarage(houseId, data)

• Seite: Client
• Definition: exports('OpenHouseGarage', function(houseId, data) ... end)
• Signatur:
• houseId (string|number) — eindeutige Haus-ID (wird zu string konvertiert; intern retrievalKey = "house:<hausId>")
• data (table, optional):
  • label (string) — Anzeigename der Garage (Default "House Garage")
  • spawn (vector4/{x,y,z,w}) — wo ausgeparkte Fahrzeuge erscheinen (Default: aktuelle Ped-Position)
  • vehicleTypes (table, optional) — Typ-Filter
  • vehicleClasses (table, optional) — Klassen-Filter
• Rückgabe: keine
• Beschreibung: Öffnet das volle Garagen-Menü für eine an ein Haus gebundene Garage. Fahrzeuge, die hier eingelagert werden, erscheinen nur in dieser Haus-Garage. Auch als Event ancomox_garage:openHouseGarage verfügbar.
• Beispiel:

exports.ancomox_garage:OpenHouseGarage(houseId, {
    label = "Mein Haus",
    spawn = vector4(x, y, z, w),      -- wo Autos rauskommen
    vehicleTypes = {"car"},
    vehicleClasses = nil
})
-- alternativ per Event:
TriggerEvent('ancomox_garage:openHouseGarage', houseId, data)

2. StoreVehicleAtHouse(houseId, vehicle)

• Seite: Client
• Definition: exports('StoreVehicleAtHouse', function(houseId, vehicle) ... end)
• Signatur:
• houseId (string|number) — Haus-ID (Zuordnung über garage_id = "house:<hausId>")
• vehicle (entity handle, optional) — zu lagerndes Fahrzeug. Wird nichts/0 übergeben, nutzt der Export das Fahrzeug, in dem der Spieler sitzt, sonst das nächste Fahrzeug im Umkreis < 5.0 m.
• Rückgabe: keine
• Beschreibung: Lagert das angegebene (oder automatisch ermittelte) Fahrzeug in die Haus-Garage ein (ruft intern AttemptToStoreVehicle). Ist kein Fahrzeug in Reichweite, erscheint die Notify no_vehicle_nearby.
• Beispiel:

-- aktuelles/nächstes Fahrzeug einlagern:
exports.ancomox_garage:StoreVehicleAtHouse(houseId)
-- bestimmtes Fahrzeug einlagern:
exports.ancomox_garage:StoreVehicleAtHouse(houseId, vehicleEntity)

Events & Commands

Befehle (RegisterCommand)

Wichtige Events (Auswahl)

Server-Callbacks laufen über eine eigene Bridge (ancomox_garage:cbRequest / cbResponse, Custom_RegisterServerCallback), z. B. garage:getVehicles, garage:fetchDBGarages, garage:saveCreatorGarage, garage:getPrivateGarageStates.

Discord-Logs

Zentrale Funktion: SendWebhookLog(type, title, message, color) (server/server.lua, Zeile ~8583). Sie prüft Config_Logs.LogSettings[type], holt Config_Logs.Webhooks[type], überspringt leere/Demo-Webhooks und postet dann per PerformHttpRequest ein Discord-Embed:

• Benutzername: "Garage Logs"
• Embed: title, description (Markdown mit Spielername, Identifier, Kennzeichen [PLATE], Beträgen), footer = "Garage System | <YYYY-MM-DD HH:MM:SS>", color = dezimaler Farbwert (z. B. grün 5763719 Store/Kauf, blau 3447003 ParkOut/Info, rot 15548997 Impound/Löschung, gelb 16776960 Update/Verkauf)

Welche Aktionen loggen in welchen Typ:

Webhook-Setup: 1. In Discord: Servereinstellungen → Integrationen → Webhooks → Neuer Webhook, Kanal wählen, URL kopieren. 2. URL in config_logs.lua beim gewünschten Typ eintragen, z. B. Store = "https://discord.com/api/webhooks/…". Für mehrere Kategorien im selben Kanal dieselbe URL mehrfach eintragen. 3. Einzelne Kategorien über LogSettings.<Typ> = false deaktivieren (spart HTTP-Requests).

Hinweise / Troubleshooting

• Reihenfolge in server.cfg: oxmysql muss vor ancomox_garage starten, sonst schlagen die MySQL.ready-Migrationen fehl.
• Kein SQL-Import nötig: Alle Tabellen und fehlende Fahrzeug-Spalten werden beim ersten Start automatisch angelegt/ergänzt.
• „Garage server did not respond" (dbg_no_response): /garagedebug ausführen und die Ressource neu starten; meist ein DB-/Callback-Timing-Problem.
• Falscher identifier: Bei Custom-Frameworks muss der von Custom_GetPlayer gelieferte identifier exakt zur Owner-Spalte (Config.CustomFramework.Columns.Owner) passen, sonst tauchen keine Fahrzeuge auf. addMoney ist Pflicht für Transfer-/Garagenverkauf, jobGrade für Fleet-Garagen.
• DBStyle korrekt wählen: "esx" (getrennte stored/pound-Spalten) vs. "qb" (eine state-Spalte). Falsche Wahl → Fahrzeuge gelten als draußen/beschlagnahmt.
• Private Garagen — Routing Buckets: RoutingBucketBase (Default 5000) darf nicht mit anderen Instanz-Systemen kollidieren; bei Bedarf erhöhen. Slot-Positionen bei „Auto klebt in der Wand" einfach als vector4 in Config.PrivateGarages.Interiors verschieben — Z wird per SetVehicleOnGroundProperly abgesichert (Z = -99.60 nicht unter -100.0 setzen, sonst fällt man durchs Interior).
• Logout in privater Garage: Wird über ancomox_private_garage_presence abgefangen (v2.11-Fix) — Tabelle nicht manuell leeren, während Spieler online sind.
• ServerSpawn (Anti-Dupe): Config.ServerSpawn.Enabled = true benötigt OneSync (Infinity) und ändert die Spawn-Architektur — vorher auf einem Testserver prüfen. Passt zu Config.OnRestart = "return".
• AdvancedParking: fixDeleteVehicle.lua ist ein Kompatibilitäts-Shim; die Datei nicht in AdvancedParking selbst starten (sie bricht dort bewusst ab).
• Discord-Logs kommen nicht an: Prüfen, ob (a) LogSettings[typ] = true, (b) die Webhook-URL gesetzt und gültig ist und (c) keine Demo-Webhook (…api/webhooks/119887…) verwendet wird — diese wird bewusst blockiert.
• Fahrzeugbilder: Eigene PNGs (Modellname, klein) nach html/images/vehicles/ legen; fehlt ein Bild, lädt das UI das offizielle FiveM-Docs-Bild und danach default.png.

ancomox_vehicleshop — Entwickler-Dokumentation

Ancomox Premium Vehicle Shop — Fahrzeug-Shop/Autohaus-Script für FiveM mit NUI-Oberfläche, permanenten Vorschaufahrzeugen, Probefahrt, kinematischer Kamera, Job-beschränkten Shops und Discord-Logging.

Überblick

ancomox_vehicleshop stellt beliebig viele Autohäuser (Standard: 14 Shops) an frei konfigurierbaren Orten bereit. Der Spieler interagiert über einen Verkäufer-Ped (via ox_target/qb-target) oder über einen klassischen 3D-Marker und öffnet eine NUI, in der Fahrzeuge nach Kategorien durchgeblättert, in einer Live-3D-Vorschau betrachtet (Farbe/Türen/Licht/Motor umschaltbar), probegefahren und gekauft werden können.

Kernmerkmale (aus dem Code bestätigt): - Multi-Framework: esx, qbcore oder custom (Config.Framework). - Wiederverwendbare Fahrzeug-Pools (Config.GlobalVehicles), pro Shop über useGlobal referenziert, oder Inline-Fahrzeuglisten pro Kategorie (vehicles). - Job-beschränkte Shops (restrictedJob), z. B. Police/Ambulance/Mechanic. - Permanente Zufalls-Vorschaufahrzeuge vor dem Shop (Config.UseRandomPreview, pro Shop via DisablePermanentPreview abschaltbar). - Ghost-Car-Schutz (Preview-Fahrzeuge tragen das Kennzeichen SHOPPREV* und werden aggressiv aufgeräumt). - Discord-Logs für Kauf und Probefahrt (config_logs.lua).

Wichtig: Die Ressource besitzt keine exports() und keine RegisterCommand. Der Shop wird ausschließlich über Ped-Target oder Marker geöffnet. Integriert wird ausschließlich über Config, Events und die entkapselten Dateien client/open.lua / server/open.lua.

Voraussetzungen

Framework-Runtime (aus dem Code): - ESX: exports["es_extended"]:getSharedObject() - QBCore: exports["qb-core"]:GetCoreObject() - custom: keine Core-Anbindung; die relevante Logik (Geld, Speichern, Job, Notify) muss in client/open.lua / server/open.lua selbst implementiert werden.

Installation

1. Ordner ancomox_vehicleshop in das resources-Verzeichnis kopieren.
2. In der server.cfg ergänzen: cfg ensure ancomox_vehicleshop Reihenfolge: nach Framework (es_extended/qb-core), nach oxmysql und (falls genutzt) nach ox_target/qb-target sowie der Keys-Ressource.
3. config/config.lua: Framework, Interaktionsart, Shops und Fahrzeuge einrichten.
4. config/locales.lua: Sprache über Config.Locale ('en' oder 'de') wählen.
5. config_logs.lua: Discord-Webhooks eintragen (optional).
6. Fahrzeugbilder unter html/images/vehicles/<model>.png ablegen (Kleinschreibung; fehlt das Bild, wird images/vehicles/default.png genutzt).

Custom-Framework: Config.Framework = "custom" setzen und die entkapselte Logik in client/open.lua / server/open.lua ausfüllen. Achtung: In server/open.lua gibt ProcessPayment im custom-Modus immer true zurück (kein Geldabzug) und SaveVehicleToDatabase speichert nichts (cb(true)) — beides selbst implementieren.

Datenbank

Die Ressource bringt keine eigene .sql-Datei mit. Es werden die Standard-Tabellen des jeweiligen Frameworks verwendet (Speicherung nur wenn Config.Use_ESX_Owned_Vehicles = true).

ESX → Tabelle owned_vehicles:

QBCore → Tabelle player_vehicles:

Beide Tabellen müssen aus dem jeweiligen Framework bereits existieren. Der Fahrzeug-type ist bei ESX fest 'car' — für Boote/Helis/Flugzeuge ggf. anpassen, sonst erscheint das Fahrzeug evtl. nicht im korrekten Garagentyp.

Konfiguration

Globale Optionen — config/config.lua

Hinweis: Im ox_target/qb-target-Modus ist die Interaktionsdistanz in der Target-Option fest 2.5 hinterlegt (nicht aus Config.ShopInteractDistance).

Struktur eines Shop-Eintrags (Config.Shops[i])

Struktur einer Kategorie (Categories[j])

Ist useGlobal gesetzt, wird Config.GlobalVehicles[useGlobal] geladen; sonst vehicles. Ist keins vorhanden, ist die Kategorie leer.

Struktur eines Fahrzeug-Eintrags

Config.GlobalVehicles — verfügbare Pools

16 Pools mit fertigen Vanilla-Fahrzeuglisten, per useGlobal referenzierbar:

Super, Sports, SportsClassic, MuscleCars, Bikes, Trucks, Trailers, Helis, Planes, Boats, SUVs, Offroad, Sedans, Coupes, Vans, Bike

Zwei Stolperfallen: - Bikes = Motorräder, Bike = Fahrräder (BMX, Cruiser …). Nicht verwechseln. - Vans ist definiert, wird aber von keinem Default-Shop referenziert — bei Bedarf einer Kategorie über useGlobal = "Vans" zuweisen.

Beispiel: neuen Shop mit globaler und eigener Kategorie anlegen

Config.Shops[#Config.Shops + 1] = {
    Name                 = "Import Tuner",
    ShopCoords           = vector3(120.0, -1050.0, 29.2),
    ShopHeading          = 90.0,
    PreviewCoords        = vector3(124.0, -1047.0, 29.2),
    PreviewHeading       = 90.0,
    ReturnCoords         = vector3(120.0, -1050.0, 29.2),
    PurchaseSpawnCoords  = vector3(128.0, -1045.0, 29.2),
    PurchaseSpawnHeading = 180.0,
    -- restrictedJob      = "cardealer",  -- optional: Job-Sperre
    -- DisablePermanentPreview = true,    -- optional
    -- BlipSprite = 326, BlipColor = 3,   -- optional: Blip-Override
    Categories = {
        { name = "Sportwagen", useGlobal = "Sports" },        -- aus GlobalVehicles
        {
            name = "Sondermodelle",                            -- eigene Inline-Liste
            vehicles = {
                { name = "Mein Auto", model = "customcar1", price = 250000, maxSpeed = 200 },
                { name = "VIP GT",    model = "customcar2", price = 900000, maxSpeed = 200 },
            }
        }
    }
}

• Fahrzeug zu bestehendem Pool hinzufügen: neuen { name, model, price }-Eintrag in Config.GlobalVehicles.<Pool> einfügen — erscheint automatisch in jedem Shop, der diesen Pool via useGlobal nutzt.
• Preis ändern: price des jeweiligen Eintrags anpassen.
• Bild: html/images/vehicles/<model>.png (Kleinschreibung) ablegen, sonst default.png.

config/locales.lua

Config.Locale wählt die aktive Sprache (Standard 'en'; 'de' vorhanden). Jede Sprache ist ein Eintrag in Config.Locales:

Standardwerte (de): u. a. press_to_open = "Drücke ~INPUT_PICKUP~ um %s zu betreten", vehicle_bought = "Gekauft: ~b~%s~s~ für ~g~$%d~s~ (Kennz.: ~y~%s~s~)".

Events & Commands

Commands: Keine (RegisterCommand existiert nicht). Der Shop öffnet ausschließlich über Ped-Target oder Marker.

Netz-Events der Ressource:

Betreiber-Warnung (Anti-Cheat): price wird vom Client an buyVehicle übergeben und serverseitig ungeprüft an ProcessPayment/Discord-Log durchgereicht. Es findet keine serverseitige Preis-/Modell-Validierung gegen die Config statt — ein manipulierter Client könnte Preis 0 senden. Bei Bedarf serverseitige Validierung in server/open.lua ergänzen.

Extern erwartete Events (Kompatibilität / selbst bereitzustellen):

Interne NUI-Callbacks (nur zur Info, keine Integrationspunkte): closeUI, toggleAutoRotate, changeColor, toggleDoor, toggleLights, toggleEngine, selectVehicle, buyVehicle, startTestDrive, hoverVehicleList.

Discord-Logs

Konfiguration in config_logs.lua (globale Tabelle Config_Logs):

Versand über PerformHttpRequest als Embed (Username „Vehicle Shop", Footer „Ancomox Premium Vehicle Shop"). Kauf-Embed enthält Spielername, Identifier, Modell, Preis, Kennzeichen; Probefahrt-Embed Spielername, Identifier, Modell. Bei Use_ESX_Owned_Vehicles = false wird der Kauf als „(No DB Save)" geloggt.

Hinweise / Troubleshooting

• es_extended trotz qbcore/custom nötig: client/shop_fix.lua ruft exports['es_extended']:getSharedObject() unbedingt auf. Ohne es_extended bricht der Client-Start. Für reinen QB-/Custom-Betrieb muss diese Stelle editiert werden.
• Kein Geldabzug im custom-Modus: ProcessPayment gibt bei Config.Framework = "custom" immer true zurück und SaveVehicleToDatabase speichert nichts — eigene Logik in server/open.lua einbauen.
• Ghost-Cars / Preview-Reste: Vorschaufahrzeuge tragen das Kennzeichen SHOPPREV*. client/shop_fix.lua und ClearGhostCars/SafeDeleteEntity räumen sie beim Start, Öffnen und Ressourcen-Stopp auf. Manuell platzierte Fahrzeuge mit diesem Kennzeichenmuster werden ebenfalls gelöscht.
• fixDeleteVehicle.lua: überschreibt DeleteEntity/DeleteVehicle für AdvancedParking-Kompatibilität. Die Datei darf nicht innerhalb von AdvancedParking gestartet werden (bricht sonst mit Hinweismeldung ab).
• Fahrzeug erscheint nicht in Garage: Bei ESX wird type = 'car' fest gespeichert — für Boote/Helis/Flugzeuge ggf. Speicher-Typ in server/open.lua anpassen.
• Kein Schlüssel nach Kauf: Passende Keys-Ressource muss laufen und das jeweilige Event (vehicles_keys:selfGiveVehicleKeys bei ESX, vehiclekeys bei QB) bereitstellen.
• maxSpeed/DefaultScale/MinScale/MaxScale: in der Config vorhanden, aber im ausgelieferten Code nicht ausgewertet (ggf. Legacy).
• Vans-Pool ungenutzt, Bikes ≠ Bike — siehe Abschnitt GlobalVehicles.
• Preis-Manipulation: siehe Betreiber-Warnung unter „Events" — serverseitig kein Preisabgleich mit der Config.