Build a Small FiveM Framework Adapter

Ein Framework-Adapter gibt deiner Ressource eine kleine Schnittstelle, während ESX-, QBCore- und Qbox-Details an einem Ort bleiben. Beginne mit einer reinen Leseoperation, überprüfe sie auf jedem unterstützten Framework und füge Geld- oder Inventaroperationen nur hinzu, wenn ihr Fehlerverhalten definiert ist.

Die hier gezeigten Konfigurations- und Codebeispiele beziehen sich auf FiveM für GTA V Legacy. Enhanced hat andere Laufzeit- und Kompatibilitätsregeln; überprüfe die Legacy-zu-Enhanced-Änderungen von Cfx.re bevor du sie auf einen Enhanced-Server anwendest.

Definiere zuerst das Schnittstellenverhalten

Das folgende Beispiel gibt den angemeldeten Charakter-Identifikator zurück, oder nil wenn kein Charakter geladen ist. Es läuft nur auf dem Server. Es konvertiert keine vorhandenen Identifikatoren und sorgt auch nicht dafür, dass die drei Frameworks eine Datenbank teilen. Verwende pro Bereitstellung ein ausgewähltes Framework.

Erstelle die Ressource

Erstelle resources/[local]/character_adapter/ mit den folgenden drei Dateien. Dieses Beispiel wählt QBCore. Für ESX oder Qbox ändere sowohl die Manifest-Abhängigkeit als auch den framework Wert. Aktiviere nicht alle drei Frameworks, um den Adapter zu testen.

fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'

dependency 'qb-core'
server_scripts { 'adapter.lua', 'server.lua' }

adapter.lua:

local framework = 'qbcore' -- 'esx', 'qbcore' or 'qbox'
CharacterAdapter = {}

if framework == 'esx' then
    local ESX = exports['es_extended']:getSharedObject()
    function CharacterAdapter.identifier(src)
        local player = ESX.GetPlayerFromId(src)
        return player and player.identifier or nil
    end
elseif framework == 'qbcore' then
    local QBCore = exports['qb-core']:GetCoreObject()
    function CharacterAdapter.identifier(src)
        local player = QBCore.Functions.GetPlayer(src)
        return player and player.PlayerData.citizenid or nil
    end
elseif framework == 'qbox' then
    function CharacterAdapter.identifier(src)
        local player = exports.qbx_core:GetPlayer(src)
        return player and player.PlayerData.citizenid or nil
    end
else
    error('Select a supported framework in adapter.lua')
end

server.lua:

RegisterCommand('adapter_check', function(src, args)
    if src ~= 0 then return end -- server console only
    local target = tonumber(args[1])
    if not target or target < 1 or target % 1 ~= 0 then
        print('Usage: adapter_check <player server ID>')
        return
    end
    local identifier = CharacterAdapter.identifier(target)
    print(identifier and 'Character resolved.' or 'No loaded character.')
end, false)

Ausführen und überprüfen

Füge ensure character_adapter in deiner aktiven Serverkonfiguration nach dem ausgewählten Framework ein. Führe mit einem angemeldeten Testcharakter mit der Server-ID 12 den Befehl adapter_check 12 in der FXServer-Konsole aus. Erwarte Character resolved.; wiederhole den Test nach dem Verbindungsabbruch dieses Charakters und erwarte No loaded character.. Der Befehl gibt absichtlich keine Kennungen aus.

Wiederhole dies auf separaten ESX- und Qbox-Testinstallationen, nachdem du deren Abhängigkeit und Adapter-Branch ausgewählt hast. Eine Lua-Syntaxprüfung oder ein gemockter Export-Test allein kann eine Live-Framework-Integration nicht bestätigen.

Erweitern, ohne Fehler zu verbergen

Dokumentiere für jede neue Operation Argumente, Rückgabewerte und Fehler. Beim Hinzufügen zum Inventar muss zwischen vollem Inventar und unbekannten Gegenständen unterschieden werden. Geldoperationen müssen unterstützte Framework-Methoden nutzen und deren Erfolgsergebnis beibehalten. Gib niemals bedingungslos Erfolg zurück und ändere nicht PlayerData.money direkt.

Halte Lebenszyklus-Handler spezifisch für das installierte Framework. playerJoining ist kein Beweis dafür, dass ein Charakter geladen wurde. Verwende lokale Handler für lokale Ereignisse; mache interne Grant- oder Job-Update-Handler nicht aus Bequemlichkeit über das Netzwerk zugänglich.

Teste die Grenze

Prüfe fehlende Spieler, Ressourcenstartreihenfolge, Charakterwechsel und erneute Verbindungen. Teste bei Schreiboperationen auch verweigerten Zugriff, doppelte Anfragen, unzureichendes Guthaben und Teilfehler. Leite keine Bedeutung aus dem Inhalt von Kennungen ab und bewahre jede Migrationszuordnung als Wiederherstellungsnachweis auf.

Referenzdokumentation

Quelle: docs.qbox.re · Quelle: qbcore.org · Quelle: esx-framework/esx_core · Cfx.re – Ereignisse abhören

Gleichzeitige Nutzung von ESX und QBCore: Warum das nicht machbar ist

Baue einen kleinen FiveM Framework Adapter