QBCore, ESX oder standalone: So funktionieren Agency Scripts mit deinem Framework

Das Framework-Kompatibilitätsproblem

Die meisten FiveM-Scripts sind fest an ein Framework gebunden. Wenn du QBCore verwendest, brauchst du QBCore-Scripts. ESX-Nutzer sind auf ESX-Scripts beschränkt. Wer standalone arbeitet, muss sich meist mit selbst zusammengebastelten Lösungen behelfen. Agency Scripts verfolgen den entgegengesetzten Ansatz: Das Framework ist ein Adapter, keine Voraussetzung.

Das Adapter-Muster

Jedes Agency-Script stellt eine kleine Gruppe von Lookup-Funktionen bereit: getPlayerData, getInventory, addMoney, removeItem, getJob . Wir liefern Adapter mit, die diese Funktionen sofort auf QBCore und ESX abbilden. Für standalone implementierst du die vier oder fünf Funktionen selbst. Das dauert in der Regel einen Vormittag, danach ist jedes Agency-Script kompatibel.

Was das in der Praxis bedeutet

Wenn du deinen Server von QBCore auf ESX umstellst, was bei der Weiterentwicklung der Frameworks durchaus alle paar Jahre vorkommt, musst du Agency-Scripts weder neu installieren noch neu konfigurieren. Du tauschst den Adapter aus, und alles andere funktioniert weiter. Das ist im FiveM-Ökosystem äußerst selten und der Hauptgrund, warum Serverbetreiber langfristig auf unsere Tools setzen.

Was die Framework-Angabe auf unseren Produktseiten bedeutet

Wenn auf einer Produktseite „QBCore, ESX“ steht, liefern wir fertige Adapter für beide Frameworks mit. Bei „Standalone“ ist das Script frameworkunabhängig, braucht keinen Adapter und läuft auf jedem Server. In der Praxis lässt sich fast jedes Agency-Script mit einem kleinen Kompatibilitäts-Shim auch in standalone-Setups verwenden.

Wann du vor dem Kauf nachfragen solltest

Wenn du ein ungewöhnliches Setup, ein eigenes Framework, ein stark angepasstes QBCore oder eine Sonderlösung verwendest, eröffne vor dem Kauf ein Ticket auf unserem Discord. Wir sagen dir ehrlich, was funktioniert, was nur leicht angepasst werden muss und wovon wir abraten. Kein Verkaufsdruck: Uns ist lieber, du kaufst ein Script, das zu deinem Setup passt, als drei, die es nicht tun.

So funktioniert das Adapter-Muster in der Praxis

Wenn du ein Agency-Script installierst, enthält der Ressourcenordner ein framework Unterverzeichnis mit mindestens drei Dateien: qb.lua, esx.lua , und standalone.lua . Das Hauptscript erkennt automatisch, welches Framework vorhanden ist, indem es prüft, ob der QBCore- oder ESX-Export verfügbar ist. Die passende Adapterdatei wird geladen, die anderen nicht. Diese automatische Erkennung findet statt, bevor irgendeine Spiellogik ausgeführt wird. Die Framework-Erkennung verursacht also keinen Laufzeit-Overhead.

Jeder Adapter implementiert dieselbe interne API. Wenn ein Script einem Spieler Geld geben muss, ruft es intern Framework.AddMoney(src, amount) auf. Diese Funktion ruft in qb.lua den QBCore-Geld-Export auf, in esx.lua das ESX-Kontensystem und in standalone.lua die Funktion, die du in config.luadefiniert hast. Ein Aufruf, drei Implementierungen, keine Änderungen am Script beim Wechsel des Frameworks.

Installation auf QBCore

Bei QBCore-Servern besteht die Installation normalerweise aus drei Schritten: Lade die Ressource herunter, lege sie in den Ressourcenordner und füge sie zu server.cfg hinzu. Das Framework wird automatisch erkannt. Wenn du ein stark angepasstes QBCore verwendest, etwa mit einem eigenen Geldsystem, Inventar oder Jobs, musst du möglicherweise bestimmte Adapterfunktionen in config.lua überschreiben, statt qb.lua direkt zu bearbeiten. Mit dem Override in der Config bleiben deine Änderungen auch nach Ressourcen-Updates erhalten.

Installation auf ESX

Die ESX-Installation folgt demselben Ablauf. Manchmal ist ein zusätzlicher Schritt nötig: Wenn deine ESX-Version deutlich älter ist, also vor 1.7, verwenden manche Adapterfunktionen neuere ESX-Exportnamen. Die Ressource enthält ein Legacy-Kompatibilitäts-Flag Config.ESXLegacy = true , das bei allen Agency-Scripts, die es benötigen, auf ältere ESX-API-Aufrufe umschaltet.

Installation auf Standalone

Standalone ist der Bereich, in dem Serverbesitzer bei anderen Scripts bisher meist auf Probleme gestoßen sind. Der Standalone-Weg von Agency Scripts ist klar beschrieben und gut dokumentiert. Für jedes Script listet die Standalone-Adapterdatei genau auf, welche Funktionen du implementieren musst. Die meisten Scripts benötigen vier bis acht Funktionen. Jede Funktion enthält einen Kommentar dazu, was sie zurückgeben soll. Eine typische Standalone-Implementierung dauert je nach Komplexität deines benutzerdefinierten Spielerdatensystems ein bis drei Stunden.

Sobald du den Adapter für ein Agency-Script implementiert hast, geht es bei den folgenden Scripts deutlich schneller. Dieselben benutzerdefinierten Funktionen gelten oft für mehrere Ressourcen.

Warum das für den langfristigen Serverbetrieb wichtig ist

FiveM-Frameworks sind nicht dauerhaft. Server, die seit drei oder mehr Jahren laufen, mussten sich wahrscheinlich schon mindestens einmal mit einem größeren Framework-Wechsel befassen, etwa mit einer Migration von einem Community-ESX-Fork zu Mainline ESX oder von einem älteren QBCore zur aktuellen Version. Server, die auf Scripts mit enger Framework-Kopplung setzen, zahlen bei einer Migration einen hohen Preis: Jedes Script muss aktualisiert oder ersetzt werden, wenn sich das Framework grundlegend ändert.

Dank der Adapter-Architektur von Agency Scripts betrifft eine Framework-Migration nur die Adapter-Ebene. Deine Agency-Phone-Daten, Agency-Admin-Protokolle, der Transaktionsverlauf von Agency-Blackmarket und der Spielfortschritt in Agency-Minerjob bleiben vollständig erhalten. Du tauschst die Adapterdateien aus, aktualisierst config.lua und die Scripts laufen weiter. Darin liegt der tatsächliche langfristige Wert dieses Kompatibilitätsansatzes: Es geht nicht nur darum, mehrere Frameworks zu unterstützen, sondern deinen Server vor der Weiterentwicklung von Frameworks abzuschirmen.

Häufig gestellte Fragen

Verwenden alle Agency-Scripts dasselbe Adaptermuster?

Ja. Jedes kostenpflichtige Agency-Script und die meisten kostenlosen Scripts verwenden dieses Muster. Die einzigen Ausnahmen sind reine UI-Ressourcen wie Agency-Loadingscreen und Agency-Notify. Sie haben keinerlei Framework-Interaktion und funktionieren überall gleich.

Kann ich Framework-Adapter kombinieren? Zum Beispiel QBCore-Geld mit einem Standalone-Inventar verwenden?

Ja, über Konfigurationsüberschreibungen. Stelle die Framework-Erkennung auf QBCore ein und überschreibe dann bestimmte Adapterfunktionen in config.lua, damit sie dein benutzerdefiniertes Inventarsystem statt das von QBCore aufrufen. Das Überschreibungssystem ist genau für Server mit hybriden Setups vorgesehen.

Was ist, wenn ein neues Framework beliebt wird und noch nicht unterstützt wird?

Eröffne ein Support-Ticket auf Discord. Wir bewerten Anfragen zur Unterstützung neuer Frameworks anhand ihrer Verbreitung in der Community. Bei Frameworks mit größeren Communities haben wir die Unterstützung in der Vergangenheit innerhalb von 2-4 Wochen hinzugefügt. Bis dahin funktioniert der Standalone-Adapter als Übergangslösung mit jedem Framework.

Werden Framework-Adapter aktualisiert, wenn das Framework selbst aktualisiert wird?

Ja. Wenn QBCore oder ESX eine Änderung veröffentlicht, die bestehende Funktionen beeinträchtigt, stellen wir innerhalb weniger Tage nach der Framework-Veröffentlichung Adapter-Updates bereit. Aktive Abonnenten erhalten Update-Benachrichtigungen über Tebex. Das ist einer der Gründe für das Abonnementmodell: Die Wartung der Adapter ist laufende Arbeit und keine einmalige Ausgabe.

Anforderungen nach Framework im Überblick

• QBCore, jede aktuelle QBCore-Version. Automatische Erkennung, keine Konfiguration für Standard-Setups erforderlich.
• ESX, ESX Legacy 1.7+ oder Mainline ESX. Aktiviere bei älteren Versionen die Legacy-Option.
• Standalone, implementiere 4-8 Funktionen pro Script in config.lua. Einmalige Einrichtung, für Agency-Scripts wiederverwendbar.
• Alle Setups, cfx.re-Konto mit gültiger Lizenz, FiveM-Server mit Artifacts 5181 oder höher empfohlen.