Convert a QBCore script to QBox: qbx_core, ox_inventory, ox_target

You have a script written for QBCore and a server running QBox. Sometimes it starts and works, sometimes the console fills with errors about a missing qb-inventory, qb-target or qb-menu. Here is the order to port it in, and the places where it usually breaks.

If you are still choosing a core, the same job from the other direction is in convert an ESX script to QBCore.

#What QBox changes and what it keeps

QBox is built on qbx_core plus the Overextended resources: ox_lib, oxmysql, ox_inventory and ox_target. It keeps a compatibility layer, so exports['qb-core']:GetCoreObject() still answers and PlayerData has the same shape (citizenid, job, charinfo, metadata, money). That is why many scripts run untouched.

What it does not keep is the old QB utility resources. Where QBCore used qb-inventory, qb-target, qb-menu, qb-input and qb-progressbar, QBox expects ox_inventory, ox_target and ox_lib. Those are the parts you port.

The first step is making sure the core is started correctly:

ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure ox_inventory
ensure ox_target
ensure my_script

Remove any leftover qb-core folder, since two cores conflict. See QBCore is nil: GetCoreObject if the object is missing.

#Step 1: dependencies in the manifest

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

shared_script '@ox_lib/init.lua'

dependencies { 'qbx_core', 'ox_lib', 'ox_inventory', 'ox_target' }

@ox_lib/init.lua is what gives you the lib global. If it is not found, see ox_lib init.lua not found.

#Step 2: getting the player

Both of these work on QBox. The first is the compatibility style, the second is the QBox way:

-- QBCore style (still works through the compatibility layer)
local QBCore = exports['qb-core']:GetCoreObject()
local Player = QBCore.Functions.GetPlayer(source)

-- QBox style
local player = exports.qbx_core:GetPlayer(source)
if player then
    print(player.PlayerData.citizenid, player.PlayerData.job.name)
end

Both return nil for a player who is not loaded, so keep the nil check. To find a loaded player by citizen id, QBox also has GetPlayerByCitizenId. When you port, you can leave the QBCore calls in place and replace them one by one later.

#Step 3: inventory

This is where most scripts break. qb-inventory and ox_inventory do not share item definitions or function names.

local src = source
local ok = exports.ox_inventory:AddItem(src, 'water', 2, { quality = 100 })
if not ok then
    lib.notify(src, { description = 'Your inventory is full', type = 'error' })
end

AddItem returns a falsy value when the item does not exist or cannot be carried, so check it. Item definitions move too. QBCore keeps them in qb-core/shared/items.lua, ox_inventory in ox_inventory/data/items.lua. Add every item the script uses there, in ox_inventory's format. How to do that is in add items to ox_inventory, and the QBCore format you are coming from is in add items to qb-inventory.

Usable items are registered differently as well: QBCore.Functions.CreateUseableItem becomes an export set in the item's definition in ox_inventory, which points at a function in your script. The QBCore calls may still work through the compatibility layer, so test an item before you rewrite it.

#Step 4: notifications, progress and menus with ox_lib

ox_lib replaces the separate QB utility resources. The calls are close to what you know:

-- QBCore
QBCore.Functions.Notify('Done', 'success', 5000)

-- ox_lib (client)
lib.notify({ title = 'Job', description = 'Done', type = 'success', duration = 5000 })

-- QBCore: QBCore.Functions.Progressbar(...) with a callback
-- ox_lib: returns true when completed, false when cancelled
if lib.progressBar({
    duration = 5000,
    label = 'Repairing',
    useWhileDead = false,
    canCancel = true,
    disable = { car = true, move = true },
    anim = { dict = 'mini@repair', clip = 'fixing_a_ped' },
}) then
    print('finished')
else
    print('cancelled')
end

Menus move from qb-menu to lib.registerContext and lib.showContext, and input forms from qb-input to lib.inputDialog. Full examples are in notifications and progress bars on ESX, QBCore and ox_lib and ox_lib context menus.

#Step 5: ox_target instead of qb-target

qb-target takes a name, coordinates and a table of options in its own layout. ox_target takes one table:

-- qb-target
exports['qb-target']:AddBoxZone('my_zone', vector3(215.0, -810.0, 30.7), 1.5, 1.5, {
    name = 'my_zone', heading = 0, minZ = 29.7, maxZ = 32.7,
}, {
    options = { { event = 'my_script:client:open', icon = 'fas fa-box', label = 'Open', job = 'police' } },
    distance = 2.0,
})

-- ox_target
exports.ox_target:addBoxZone({
    coords = vector3(215.0, -810.0, 30.7),
    size = vector3(1.5, 1.5, 3.0),
    rotation = 0,
    options = {
        { name = 'my_zone_open', icon = 'fas fa-box', label = 'Open', groups = 'police',
          onSelect = function() TriggerEvent('my_script:client:open') end },
    },
})

Notice event becomes onSelect (or event still works for a client event), and job becomes groups. The details are in qb-target vs ox_target and ox_target zones.

#What usually breaks

• Missing item errors. The item exists in qb-core's shared file but not in ox_inventory's. Add it.
• No such export for qb-inventory, qb-target or qb-menu. The script calls them directly: port those calls, or it will never run.
• Callbacks. lib.callback is the QBox style. If a script still uses QBCore.Functions.CreateCallback, test it and move it to ox_lib if it fails: see server callbacks.
• Jobs and gangs with grades. QBox has its own job and group data. Test every job check, especially on-duty and grade comparisons.
• Mixed cores. A leftover qb-core resource started next to qbx_core.
• Start order. Your script above ox_lib, ox_inventory or qbx_core in server.cfg.

#Checklist