Convert an ESX script to QBCore (and back): function map and bridge

You have a script written for ESX, and your server runs QBCore, or the other way round. Most of the script is plain Lua and natives that do not change. Only the framework calls do, and there are fewer than you expect. This article gives you a map of them, and then shows how to isolate them in one bridge file.

#What stays and what changes

Natives, NUI, your own events, loops, targets and menus work on any framework. What changes is a short list:

• how you get the framework object
• how you get a player
• money, jobs and items
• notifications
• usable items and callbacks
• the database tables for players

Search the script for ESX. and xPlayer, and every hit is something to convert.

#Function map

Two details trip people up. Money types: ESX has money for cash and bank, QBCore uses 'cash' and 'bank' as the first argument. And the grade: ESX gives a plain number, QBCore a table, so job.grade.level.

Callbacks, which every second script uses, are compared in detail in server callbacks on ESX, QBCore and ox_lib.

#The database

The player tables differ, so any SELECT or UPDATE on them needs a change:

A script that stores its own data, with its own tables, usually keeps working, as long as it keys the rows on a value you can get from either framework. Using the license identifier for that works on both.

#QBox

QBox is closer to QBCore than to ESX. Its core is qbx_core, it keeps a compatibility layer for exports['qb-core']:GetCoreObject(), and its inventory is ox_inventory. A script converted to QBCore usually runs on QBox with few changes, apart from inventory calls.

#The bridge file approach

If the script must run on both, do not litter it with if ESX then ... else ... end. Put every framework call in one file, and have the rest of the script call that file.

-- bridge.lua (server)
Bridge = {}

local framework
if GetResourceState('es_extended') == 'started' then
    framework = 'esx'
    ESX = exports['es_extended']:getSharedObject()
elseif GetResourceState('qb-core') == 'started' then
    framework = 'qb'
    QBCore = exports['qb-core']:GetCoreObject()
end

function Bridge.GetPlayer(src)
    if framework == 'esx' then return ESX.GetPlayerFromId(src) end
    return QBCore.Functions.GetPlayer(src)
end

function Bridge.AddCash(src, amount)
    local player = Bridge.GetPlayer(src)
    if not player then return false end

    if framework == 'esx' then
        player.addMoney(amount)
    else
        player.Functions.AddMoney('cash', amount)
    end
    return true
end

function Bridge.GetJob(src)
    local player = Bridge.GetPlayer(src)
    if not player then return nil end

    if framework == 'esx' then
        return player.job.name, player.job.grade
    end
    return player.PlayerData.job.name, player.PlayerData.job.grade.level
end

In the manifest, load it before the files that use it:

server_scripts {
    'bridge.lua',
    'server.lua',
}

The script then reads like this, and never mentions a framework:

RegisterNetEvent('my_script:pay', function()
    local src = source
    local job = Bridge.GetJob(src)
    if job == 'mechanic' then
        Bridge.AddCash(src, 100)
    end
end)

Add a client bridge for notifications and player data in the same way. When you add a new framework, such as QBox with qbx_core, you add a branch in the bridge, and the script stays as it is.

Remember that a bridge only works if the framework starts first. Put ensure es_extended or ensure qb-core above the script in server.cfg, and read ESX is nil if the object comes back nil.

#Checklist