Build a Small FiveM Framework Adapter

Un adaptateur de framework donne à votre ressource une petite interface tout en gardant les détails ESX, QBCore et Qbox au même endroit. Commencez par une opération en lecture seule, vérifiez-la sur chaque framework pris en charge, et n'ajoutez des opérations d'argent ou d'inventaire que lorsque leur comportement en cas d'échec est défini.

Les exemples de configuration et de code ici ciblent FiveM pour GTA V Legacy. Enhanced a des règles d'exécution et de compatibilité différentes ; vérifiez les changements Legacy-to-Enhanced de Cfx.re avant de les appliquer à un serveur Enhanced.

Définissez d'abord le contrat

L'exemple ci-dessous renvoie l'identifiant du personnage connecté, ou nil si aucun personnage n'est chargé. Il ne s'exécute que sur le serveur. Il ne convertit pas les identifiants existants et ne permet pas aux trois frameworks de partager une base de données. Utilisez un seul framework sélectionné par déploiement.

Créez la ressource

Créez resources/[local]/character_adapter/ avec les trois fichiers suivants. Cet exemple utilise QBCore. Pour ESX ou Qbox, modifiez à la fois la dépendance du manifeste et la valeur framework. N’activez pas les trois frameworks pour tester l’adaptateur.

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)

Exécuter et vérifier

Ajouter ensure character_adapter après le framework sélectionné dans votre configuration de serveur active. Avec un personnage de test connecté dont l'ID de serveur est 12, exécutez adapter_check 12 dans la console FXServer. Attendez-vous à Character resolved.; répétez après la déconnexion de ce personnage et attendez-vous à No loaded character.. La commande n'affiche délibérément pas les identifiants.

Répétez l'opération sur des installations de test ESX et Qbox distinctes après avoir sélectionné leur dépendance et leur branche d'adaptateur. Une vérification de la syntaxe Lua ou un test d'exportation simulé seul ne peut pas confirmer une intégration de framework en direct.

Étendre sans masquer les échecs

Pour chaque nouvelle opération, documentez les arguments, les valeurs de retour et les erreurs. Les ajouts d'inventaire doivent distinguer un inventaire plein des articles inconnus. Les opérations monétaires doivent utiliser les méthodes de framework prises en charge et préserver leur résultat de succès. Ne renvoyez jamais le succès inconditionnellement ou ne modifiez pas PlayerData.money directement.

Gardez les gestionnaires de cycle de vie spécifiques au framework installé. playerJoining n'est pas une preuve qu'un personnage a été chargé. Utilisez des gestionnaires locaux pour les événements locaux ; ne rendez pas les gestionnaires internes d'octroi ou de mise à jour de métier accessibles via le réseau par commodité.

Testez la limite

Vérifiez les joueurs manquants, l'ordre de démarrage des ressources, le changement de personnage et les reconnexions. Pour les opérations d'écriture, testez également les accès refusés, les requêtes en double, les fonds insuffisants et les échecs partiels. Gardez les identifiants opaques et conservez tout tableau de correspondance de migration comme preuve de récupération.

Documentation de référence

Source : docs.qbox.re · Source: qbcore.org · Source : esx-framework/esx_core · Cfx.re — écoute des événements

Utilisation simultanée d'ESX et de QBCore : pourquoi ce n'est pas faisable

Construire un petit adaptateur de framework FiveM