Build a Small FiveM Framework Adapter

Um adaptador de framework oferece ao seu recurso uma interface pequena, mantendo os detalhes de ESX, QBCore e Qbox em um só lugar. Comece com uma operação somente leitura, verifique-a em cada framework suportado e adicione operações de dinheiro ou inventário apenas quando o comportamento de falha for definido.

A configuração e os exemplos de código aqui são voltados ao FiveM para GTA V Legacy. O Enhanced tem regras diferentes de runtime e de compatibilidade; verifique as alterações de Legacy para Enhanced do Cfx.re antes de aplicá-las a um servidor Enhanced.

Defina o contrato primeiro

O exemplo abaixo retorna o identificador do personagem logado, ou nil se nenhum personagem estiver carregado. Ele é executado apenas no servidor. Ele não converte identificadores existentes nem faz com que os três frameworks compartilhem um banco de dados. Use um framework selecionado por implantação.

Crie o recurso

Crie resources/[local]/character_adapter/ com os três arquivos a seguir. Este exemplo usa QBCore. Para ESX ou Qbox, altere tanto a dependência no manifest quanto o valor de framework. Não ative os três frameworks para testar o adaptador.

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)

Execute e verifique

Adicione ensure character_adapter após o framework selecionado na configuração ativa do servidor. Com um personagem de teste conectado cujo ID de servidor é 12, execute adapter_check 12 no console do FXServer. Espere Character resolved.; repita depois que o personagem se desconectar e espere No loaded character.. O comando deliberadamente não imprime identificadores.

Repita em instalações de teste separadas de ESX e Qbox após selecionar sua dependência e ramificação do adaptador. Uma verificação de sintaxe Lua ou um teste de export mockado sozinho não pode confirmar uma integração de framework ao vivo.

Estenda sem ocultar falhas

Para cada nova operação, documente argumentos, valores de retorno e erros. A inclusão de itens no inventário deve distinguir inventário cheio de itens desconhecidos. Operações financeiras devem usar métodos compatíveis do framework e preservar seu resultado de sucesso. Nunca retorne sucesso incondicionalmente nem altere PlayerData.money diretamente.

Mantenha os manipuladores de ciclo de vida específicos para o framework instalado. playerJoining não é prova de que um personagem foi carregado. Use manipuladores locais para eventos locais; não torne os manipuladores internos de concessão ou atualização de trabalho acessíveis pela rede por conveniência.

Teste o limite

Verifique jogadores ausentes, ordem de inicialização dos recursos, troca de personagem e reconexões. Para operações de escrita, teste também acesso negado, solicitações duplicadas, saldo insuficiente e falhas parciais. Trate os identificadores como valores opacos e guarde qualquer tabela de correspondências da migração como evidência para recuperação.

Documentação de referência

Fonte: docs.qbox.re · Fonte: qbcore.org · Fonte: esx-framework/esx_core · Cfx.re — escutando eventos

Uso simultâneo de ESX e QBCore: por que não é viável

Construa um Pequeno Adaptador de Framework FiveM