Agency Phone Setup-Guide: FiveM Installation & Konfiguration

Dieser Guide führt dich durch den vollständigen Prozess der Installation und Konfiguration von Agency Phone auf deinem FiveM-Server. Egal ob du QBCore, ESX oder ein vollständig eigenes Framework betreibst – hier findest du alles, was du brauchst: von den Voraussetzungen über den ersten Start bis zur Feinabstimmung der Config. Die vollständige technische Referenz findest du in der offiziellen Dokumentation unter docs.agencyg.de/phone.

Voraussetzungen

Stelle vor der Installation von Agency Phone sicher, dass deine Server-Umgebung folgende Anforderungen erfüllt:

• FiveM-Server-Artifact: Version 6633 oder neuer (empfohlen: Artifacts stets aktuell halten)
• Datenbank: MySQL 5.7+ oder MariaDB 10.3+, mit oxmysql (empfohlen) oder mysql-async installiert und konfiguriert
• CFX Keymaster: Der Lizenzschlüssel deines Servers muss unter keymaster.fivem.net registriert und aktiv sein
• Framework (optional): QBCore oder ESX, falls du die tiefere Framework-Integration nutzen möchtest. Für den Standalone-Betrieb nicht erforderlich.
• Aktiver Agency Phone-Kauf: Die Ressource wird nach dem Kauf über das CFX Asset Portal bereitgestellt

Schritt 1 — Kauf und Download

Nachdem du deinen Kauf im Agency Scripts Shop abgeschlossen hast, wird deine Lizenz automatisch in deinem CFX-Konto registriert. So lädst du die Ressource herunter:

1. Melde dich unter keymaster.fivem.net mit dem CFX-Konto an, das mit deinem Kauf verknüpft ist.
2. Navigiere zu Granted Assets und suche nach agency-phone.
3. Klicke auf Download, um das aktuelle Release-ZIP zu erhalten.
4. Wenn du die QBCore- oder ESX-Bridge erworben hast, lade ebenfalls agency-phone-bridge-qb bzw. agency-phone-bridge-esx aus derselben Liste herunter.

Schritt 2 — Ordnerstruktur

Entpacke die ZIP-Datei(en). Dein resources-Verzeichnis sollte nach dem Entpacken so aussehen:

resources/
  [agency]/
    agency-phone/
      client/
      server/
      html/
      config.lua
      fxmanifest.lua
    agency-phone-bridge-qb/   (nur QBCore)
      client/
      server/
      fxmanifest.lua

Der Ordner [agency] ist ein Kategorieordner (eckige Klammern signalisieren FiveM eine Ressourcengruppe). Er ist nicht zwingend erforderlich – du kannst agency-phone auch direkt in resources/ ablegen –, hilft aber dabei, alles übersichtlich zu halten.

Schritt 3 — Datenbankeinrichtung

Agency Phone legt seine Datenbanktabellen beim ersten Start mithilfe des in oxmysql integrierten Auto-Migrations-Systems automatisch an. Du musst keine SQL-Dateien manuell importieren. Stelle lediglich sicher, dass deine Datenbankverbindung in der server.cfg konfiguriert ist:

# server.cfg — Datenbankverbindungsstring (oxmysql-Beispiel)
set mysql_connection_string "mysql://user:password@localhost/fivem_db?charset=utf8mb4"

Beim ersten Serverstart erstellt Agency Phone folgende Tabellen: phone_contacts, phone_messages, phone_calls, phone_gallery, phone_social_posts und phone_settings. Bei einer frischen Datenbank werden die Tabellen automatisch angelegt. Wenn du von einem anderen Phone Script migrierst, stelle sicher, dass es keine Namenskonflikte in deinem bestehenden Schema gibt.

Schritt 4 — Einträge in der server.cfg

Füge folgende ensure-Zeilen zu deiner server.cfg hinzu. Die Reihenfolge ist wichtig – oxmysql muss vor Agency Phone geladen werden:

# Abhängigkeiten
ensure oxmysql

# Agency Phone (standalone oder mit Framework-Bridge)
ensure agency-phone

# Nur hinzufügen, wenn QBCore-Bridge verwendet wird:
# ensure qb-core
# ensure agency-phone-bridge-qb

# Nur hinzufügen, wenn ESX-Bridge verwendet wird:
# ensure es_extended
# ensure agency-phone-bridge-esx

Wenn du QBCore oder ESX einsetzt, stelle sicher, dass das Framework selbst vor der Bridge-Ressource geladen wird, wie in den Kommentaren oben gezeigt. Die Standalone-Kern-Ressource (agency-phone) muss immer vor einer Bridge-Ressource gestartet werden.

Schritt 5 — Konfiguration (config.lua)

Öffne agency-phone/config.lua in einem Texteditor. Dies ist die primäre Konfigurationsdatei und steuert nahezu jeden Aspekt des Verhaltens des Handys. Hier eine ausführliche Erläuterung der wichtigsten Einstellungen:

Config = {}

-- ============================================================
-- FRAMEWORK
-- "standalone" | "qbcore" | "esx"
-- ============================================================
Config.Framework = "standalone"

-- ============================================================
-- PHONE NUMBERS
-- ============================================================
-- Format string for auto-generated numbers. X = random digit.
Config.PhoneNumberFormat = "555-XXXX"

-- Allow players to pay in-game currency to change their number
Config.AllowNumberChange = true
Config.NumberChangeCost   = 500  -- default currency (adjust per framework)

-- ============================================================
-- APPS: enable/disable individual apps
-- ============================================================
Config.EnableBankingApp   = true
Config.EnableSocialApp    = true
Config.EnableGPSApp       = true
Config.EnableCameraApp    = true
Config.EnableMDT          = false   -- set true only for LEO servers
Config.EnableNotesApp     = true

-- ============================================================
-- MDT (only relevant when Config.EnableMDT = true)
-- ============================================================
-- Jobs that can access the MDT app
Config.MDTJobs = { "police", "sheriff", "highway_patrol" }

-- ============================================================
-- SOCIAL MEDIA
-- ============================================================
-- Rename the social app to match your server's lore
Config.SocialAppName = "Chirper"
-- Max post length in characters
Config.SocialPostMaxLength = 280

-- ============================================================
-- ENCRYPTED MESSAGING
-- Requires players to hold a specific inventory item
-- ============================================================
Config.EncryptedChat     = false
Config.EncryptedChatItem = "burner_phone"

-- ============================================================
-- UI
-- ============================================================
-- Default theme: "dark" or "light"
Config.DefaultTheme = "dark"
-- Notification display duration in milliseconds
Config.NotificationDuration = 5000
-- Phone open keybind (FiveM key name)
Config.PhoneKey = "F1"

Hinweise für QBCore

Bei Verwendung der QBCore-Bridge (Config.Framework = "qbcore") ruft die Banking-App Kontostand und Transaktionsdaten automatisch aus der QBCore-Wirtschaft ab. Jobbasierte App-Berechtigungen (z. B. MDT-Zugang) nutzen das native QBCore-Jobsystem – es ist keine weitere Konfiguration nötig, außer die Jobnamen in Config.MDTJobs einzutragen. Telefonnummern werden pro Charakter gespeichert und sind an den QBCore-Charakterbezeichner gebunden.

Hinweise für ESX

Mit der ESX-Bridge (Config.Framework = "esx") verbindet sich die Banking-App mit ESX-Konten (Standard: bank). Falls dein ESX-Setup benutzerdefinierte Kontonamen verwendet, konfiguriere diese in der eigenen config.lua der Bridge. ESX-Job-Ränge werden für den MDT-Zugang berücksichtigt – es müssen nur die Jobnamen eingetragen werden; alle Ränge innerhalb dieses Jobs erhalten automatisch Zugang, sofern du keine Rang-Beschränkungen in der Bridge-Config festlegst.

Schritt 6 — Überprüfung des ersten Starts

Starte deinen Server und beobachte die Konsolenausgabe. Eine erfolgreiche Agency Phone-Initialisierung sieht so aus:

[agency-phone] Database tables verified/created — OK
[agency-phone] Framework: standalone
[agency-phone] Loaded 0 contacts, 0 messages (fresh install)
[agency-phone] Resource started successfully — v2.x.x

Falls an dieser Stelle Fehler auftreten, lies den Abschnitt zur Fehlerbehebung weiter unten. Sobald der Server läuft, verbinde dich mit einem Client und drücke F1 (oder die von dir konfigurierte Handy-Taste), um das Handy zu öffnen. Bei der ersten Nutzung wird der Spieler aufgefordert, seine Nummer festzulegen, falls noch keine zugewiesen wurde.

Häufige Fehler und Lösungen

Fehler: „oxmysql is not started"

Das bedeutet, oxmysql wird in deiner server.cfg nicht vor agency-phone geladen. Verschiebe die Zeile ensure oxmysql über ensure agency-phone und starte den Server neu.

Fehler: „Failed to create table phone_contacts — Table already exists"

Dies ist eine Warnung, kein fataler Fehler – sie bedeutet, dass du über eine bestehende Datenbank neu installierst. Die vorhandenen Daten bleiben erhalten. Du kannst diese Warnung bedenkenlos ignorieren. Wenn du eine saubere Neuinstallation wünschst, lösche zunächst manuell alle phone_*-Tabellen in deiner Datenbank.

Handy-UI öffnet sich nicht beim Tastendruck

Prüfe zunächst, ob die Ressource in der Server-Konsole fehlerfrei gestartet ist. Stelle dann sicher, dass keine andere Ressource denselben Tastenbelegung nutzt (Standard: F1). Du kannst den Tastenbelegung in config.lua unter Config.PhoneKey ändern. Prüfe außerdem auf NUI-Fokus-Konflikte: Wenn eine andere Ressource zur selben Zeit den NUI-Fokus hält, empfängt das Handy den Tastendruck möglicherweise nicht korrekt.

Banking-App zeigt $0 / leeres Guthaben

Im Standalone-Modus verwendet die Banking-App standardmäßig eine interne Geldbörse. Um sie mit der QBCore- oder ESX-Wirtschaft zu verbinden, musst du die entsprechende Bridge-Ressource verwenden und Config.Framework korrekt setzen. Wenn die Bridge gestartet ist, aber das Guthaben trotzdem null anzeigt, stelle sicher, dass der Charakter des Spielers im Framework vollständig geladen ist, bevor das Handy initialisiert wird (Ladereihenfolge in der server.cfg).

MDT-App für Polizeibeamte nicht sichtbar

Stelle sicher, dass Config.EnableMDT = true in der config.lua gesetzt ist und dass der aktuelle Jobname des Spielers exakt mit einem der Einträge in Config.MDTJobs übereinstimmt. Der Jobname-Abgleich ist Groß-/Kleinschreibungs-sensitiv. Verwende den exakten Jobnamen-String, wie er in der Job-Konfiguration deines Frameworks definiert ist.

Weitere Konfigurationsoptionen

Agency Phone bietet weit mehr Konfigurationsoptionen, als dieser Guide abdecken kann. Zu den nützlichsten erweiterten Einstellungen zählen:

• Config.MaxContactsPerPlayer — begrenzt die Anzahl der Kontakte, die ein Spieler speichern kann (Standard: unbegrenzt)
• Config.GPSUpdateInterval — wie häufig der Standort-Blip des Spielers beim geteilten GPS aktualisiert wird (Millisekunden)
• Config.SocialPostCooldown — Mindestzeit zwischen Social-Media-Beiträgen zur Spam-Vorbeugung (Sekunden)
• Config.AllowAnonCalls — ob Spieler Anrufe tätigen können, bei denen ihre Nummer vor dem Empfänger verborgen bleibt
• Config.CameraPhotoQuality — NUI-Screenshot-Qualitätsstufe (1–10, beeinflusst die Bildgröße in der In-Game-Galerie)

Die vollständige kommentierte Konfigurationsdatei mit allen Optionen ist in der offiziellen Dokumentation unter docs.agencyg.de/phone verfügbar. Die Dokumentation wird mit jeder Version aktualisiert und enthält versionsspezifische Migrationshinweise, wenn sich Einstellungen ändern.

Agency Phone aktuell halten

Wenn eine neue Version veröffentlicht wird, erhältst du eine Benachrichtigung in deinem CFX-Keymaster-Konto. Für ein Update lädst du das neue ZIP von der Granted-Assets-Seite herunter, entpackst es und ersetzt den vorhandenen agency-phone-Ordner auf deinem Server. Lies stets das Update-Changelog, bevor du auf einem Live-Server aktualisierst – es listet alle Änderungen an config.lua-Schlüsseln auf, die deine Aufmerksamkeit erfordern. Deine Datenbank und vorhandene Spielerdaten werden durch ein Update niemals gelöscht.