A framework adapter gives your resource a small interface while keeping ESX, QBCore and Qbox details in one place. Start with a read-only operation, verify it on each supported framework, and add money or inventory operations only when their failure behavior is defined.<\/p>\n
The configuration and code examples here target FiveM for GTA V Legacy. Enhanced has different runtime and compatibility rules; check Cfx.re\u2019s Legacy-to-Enhanced changes<\/a> before applying them to an Enhanced server.<\/p>\n The example below returns the logged-in character identifier, or Create Add Repeat on separate ESX and Qbox test installations after selecting their dependency and adapter branch. A Lua syntax check or mocked export test alone cannot confirm a live framework integration.<\/p>\n For each new operation, document arguments, return values and errors. Inventory additions must distinguish full inventory from unknown items. Money operations must use supported framework methods and preserve their success result. Never return success unconditionally or mutate Keep lifecycle handlers specific to the installed framework. Check missing players, resource start order, character switching and reconnects. For write operations, also test denied access, duplicate requests, insufficient funds and partial failures. Keep identifiers opaque and retain any migration crosswalk as recovery evidence.<\/p>\n Source: docs.qbox.re<\/a> \u00b7 Source: qbcore.org<\/a> \u00b7 Source: esx-framework\/esx_core<\/a> \u00b7 Cfx.re \u2014 listening for events<\/a><\/p>\nDefine the contract first<\/h2>\n
nil<\/code> if no character is loaded. It runs on the server only. It does not convert existing identifiers or make the three frameworks share a database. Use one selected framework per deployment.<\/p>\nCreate the resource<\/h2>\n
resources\/[local]\/character_adapter\/<\/code> with the following three files. This example selects QBCore. For ESX or Qbox, change both the manifest dependency and the framework<\/code> value. Do not enable all three frameworks to test the adapter.<\/p>\nfxmanifest.lua<\/code>:<\/p>\nfx_version 'cerulean'\ngame 'gta5'\n\ndependency 'qb-core'\nserver_scripts { 'adapter.lua', 'server.lua' }<\/code><\/pre>\nadapter.lua<\/code>:<\/p>\nlocal framework = 'qbcore' -- 'esx', 'qbcore' or 'qbox'\nCharacterAdapter = {}\n\nif framework == 'esx' then\n local ESX = exports['es_extended']:getSharedObject()\n function CharacterAdapter.identifier(src)\n local player = ESX.GetPlayerFromId(src)\n return player and player.identifier or nil\n end\nelseif framework == 'qbcore' then\n local QBCore = exports['qb-core']:GetCoreObject()\n function CharacterAdapter.identifier(src)\n local player = QBCore.Functions.GetPlayer(src)\n return player and player.PlayerData.citizenid or nil\n end\nelseif framework == 'qbox' then\n function CharacterAdapter.identifier(src)\n local player = exports.qbx_core:GetPlayer(src)\n return player and player.PlayerData.citizenid or nil\n end\nelse\n error('Select a supported framework in adapter.lua')\nend<\/code><\/pre>\nserver.lua<\/code>:<\/p>\nRegisterCommand('adapter_check', function(src, args)\n if src ~= 0 then return end -- server console only\n local target = tonumber(args[1])\n if not target or target < 1 or target % 1 ~= 0 then\n print('Usage: adapter_check <player server ID>')\n return\n end\n local identifier = CharacterAdapter.identifier(target)\n print(identifier and 'Character resolved.' or 'No loaded character.')\nend, false)<\/code><\/pre>\nRun and check<\/h2>\n
ensure character_adapter<\/code> after the selected framework in your active server configuration. With a logged-in test character whose server ID is 12, run adapter_check 12<\/code> in the FXServer console. Expect Character resolved.<\/code>; repeat after that character disconnects and expect No loaded character.<\/code>. The command deliberately does not print identifiers.<\/p>\nExtend without hiding failures<\/h2>\n
PlayerData.money<\/code> directly.<\/p>\nplayerJoining<\/code> is not proof that a character has loaded. Use local handlers for local events; do not make internal grant or job-update handlers network-accessible for convenience.<\/p>\nTest the boundary<\/h2>\n
Reference documentation<\/h2>\n