Crea un pequeño adaptador de framework para FiveM

Un adaptador de framework le da a tu recurso una interfaz pequeña mientras mantiene los detalles de ESX, QBCore y Qbox en un solo lugar. Comienza con una operación de solo lectura, verifícala en cada framework compatible y añade operaciones de dinero o inventario solo cuando su comportamiento de fallo esté definido.

Los ejemplos de configuración y código aquí están dirigidos a FiveM para GTA V Legacy. Enhanced tiene diferentes reglas de tiempo de ejecución y compatibilidad; consulta los cambios de Legacy a Enhanced de Cfx.re antes de aplicarlos a un servidor Enhanced.

Define el contrato primero

El ejemplo siguiente devuelve el identificador del personaje conectado, o nil si no hay ningún personaje cargado. Se ejecuta solo en el servidor. No convierte identificadores existentes ni hace que los tres frameworks compartan una base de datos. Utiliza un framework seleccionado por despliegue.

Crea el recurso

Crea resources/[local]/character_adapter/ con los tres archivos siguientes. Este ejemplo utiliza QBCore. Para ESX o Qbox, cambia tanto la dependencia del manifiesto como el valor de framework. No actives los tres frameworks para probar el 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)

Ejecuta y comprueba

Añade ensure character_adapter después del framework seleccionado en tu configuración de servidor activa. Con un personaje de prueba conectado cuyo ID de servidor es 12, ejecuta adapter_check 12 en la consola de FXServer. Espera Character resolved.; repite después de que ese personaje se desconecte y espera No loaded character.. El comando deliberadamente no imprime identificadores.

Repite en instalaciones de prueba separadas de ESX y Qbox después de seleccionar su dependencia y rama de adaptador. Una comprobación de sintaxis de Lua o una prueba de exportación simulada por sí solas no pueden confirmar una integración de framework en vivo.

Extiende sin ocultar fallos

Para cada nueva operación, documenta los argumentos, los valores de retorno y los errores. Las adiciones de inventario deben distinguir el inventario lleno de los ítems desconocidos. Las operaciones de dinero deben usar métodos de framework compatibles y preservar su resultado de éxito. Nunca devuelvas éxito incondicionalmente ni modifiques PlayerData.money directamente.

Mantén los manejadores de ciclo de vida específicos del framework instalado. playerJoining no es prueba de que un personaje se haya cargado. Utiliza manejadores locales para eventos locales; no hagas que los manejadores internos de concesión o actualización de trabajos sean accesibles por red por comodidad.

Prueba el límite

Comprueba jugadores ausentes, orden de inicio de recursos, cambio de personaje y reconexiones. Para operaciones de escritura, también prueba acceso denegado, solicitudes duplicadas, fondos insuficientes y fallos parciales. Mantén los identificadores opacos y conserva cualquier tabla de correspondencias de la migración como evidencia de recuperación.

Documentación de referencia

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

Uso simultáneo de ESX y QBCore: ¿Por qué no es viable?