Qbox quick start

Qbox began as a fork of QBCore and is now its own framework, built on the Overextended stack (ox_lib, ox_inventory, ox_target) with a compatibility bridge so many QBCore resources still run. Official docs: docs.qbox.re.

Installing FiveM with QBox (BadCode.Codes)

1. Requirements

From the Qbox installation docs:

• MariaDB 10.9.0 or newer (a current LTS is recommended). MySQL is not supported, and XAMPP is not supported. See Database setup.
• An up to date recommended artifact and a license key.
• txAdmin, which Qbox “highly recommends” for installing.

2. Install with txAdmin

1. Start FXServer, link your Cfx.re account.
2. Popular Recipes > Qbox.
3. License key, database connection (leave the name empty), Run Recipe.
4. Save & Run Server.

What the recipe installs is in Popular recipes. Its config is split into server.cfg, permissions.cfg, ox.cfg, voice.cfg and misc.cfg, and it sets game build 3258.

3. The structure

resources/
├─ [cfx-default]/
├─ [ox]/             ox_lib, oxmysql, ox_target, ox_inventory, ox_doorlock, ox_fuel
├─ [qbx]/
│  ├─ qbx_core/      the framework
│  │  ├─ shared/     jobs.lua, gangs.lua, vehicles.lua, weapons.lua, locations.lua...
│  │  ├─ config/
│  │  └─ modules/    lib.lua, playerdata.lua (importable helpers)
│  ├─ qbx_garages/ ...
├─ [standalone]/     illenium-appearance, Renewed-Banking, scully_emotemenu...
├─ [voice]/          pma-voice, mm_radio
├─ [npwd]/           phone
└─ [assets]/         maps

Useful server.cfg convars from the recipe:

4. Make yourself admin

Qbox uses FiveM’s ACE groups. The deployer already added your identifiers through {{addPrincipalsMaster}}, and permissions.cfg defines the groups. To add another admin:

add_principal identifier.fivem:123456 group.admin

Restart, then open the admin menu (qbx_adminmenu) in game. qbx_core also has commands like /setjob, /givemoney, /car, /dv and /tp, and ox_inventory adds /giveitem.

5. Add a job

Jobs are in qbx_core/shared/jobs.lua. Job names must be lowercase, and grades use number keys:

return {
    -- ...existing jobs...
    ['burgershot'] = {
        label = 'Burger Shot',
        defaultDuty = true,
        offDutyPay = false,
        grades = {
            [0] = { name = 'Trainee', payment = 50 },
            [1] = { name = 'Cook', payment = 75 },
            [2] = { name = 'Manager', isboss = true, bankAuth = true, payment = 120 },
        },
    },
}

isboss gives access to the management menu, bankAuth to the society account. Police style jobs add type = 'leo'. Restart the server, then /setjob [id] burgershot 2.

6. Add an item (ox_inventory)

Qbox uses ox_inventory, so items are defined in ox_inventory/data/items.lua:

['burger'] = {
    label = 'Burger',
    weight = 220,
    stack = true,
    close = true,
    description = 'A juicy Burger Shot burger',
    client = {
        status = { hunger = 200000 },
        anim = 'eating',
        prop = 'burger',
        usetime = 2500,
    },
},

The client block alone makes it usable: ox_inventory plays the animation and prop, and the status field feeds hunger to the status system. Put burger.png in ox_inventory/web/images/ (the Inventory Icons tool makes transparent icons and items.lua entries). Test with /giveitem [id] burger 1.

For server logic on use, point the item at an export of your resource:

['lockpick'] = {
    label = 'Lockpick',
    weight = 160,
    server = { export = 'my_crime.lockpick' },
},

exports('lockpick', function(event, item, inventory, slot, data)
    if event == 'usingItem' then
        -- return false to cancel the use
        return true
    end
end)

Check the ox_inventory docs for the full item options (degrade, consume, buttons, weapons).

7. A small Qbox script

fx_version 'cerulean'
game 'gta5'

shared_scripts {
    '@ox_lib/init.lua',
    '@qbx_core/modules/lib.lua',
}
server_script 'server.lua'

dependencies { 'ox_lib', 'qbx_core' }

local lastClaim = {}

lib.addCommand('paycheck', { help = 'Claim a bonus paycheck (once per hour)' }, function(source)
    local player = exports.qbx_core:GetPlayer(source)
    if not player then return end

    local cid = player.PlayerData.citizenid
    if lastClaim[cid] and os.time() - lastClaim[cid] < 3600 then
        exports.qbx_core:Notify(source, 'You already claimed it this hour', 'error')
        return
    end

    local job = player.PlayerData.job
    local amount = 100 + (job.grade.level * 50)
    exports.qbx_core:AddMoney(source, 'bank', amount, 'paycheck-bonus')
    lastClaim[cid] = os.time()
    exports.qbx_core:Notify(source, ('Paid $%d for %s'):format(amount, job.label), 'success')
end)

Key qbx_core server exports (from the Qbox docs): GetPlayer(source), AddMoney(identifier, moneyType, amount, reason), RemoveMoney(...), SetJob(identifier, jobName, grade), CreateUseableItem(item, cb), Notify(source, text, type, duration), GetPlayersData(), HasPrimaryGroup(source, filter). identifier can be a server ID or a citizen ID.

Common pitfalls

• MySQL or XAMPP: not supported. Use MariaDB.
• Mixing inventories: Qbox is built around ox_inventory. Don’t install qb-inventory next to it.
• QBCore scripts: most work through the bridge, but scripts that edit qb-core internals or use removed QBCore functions need changes. Check the Qbox docs’ converting section.
• Downloading ox resources from source: use release zips.
• Editing jobs.lua without a restart: shared data is loaded on start.
• Deleting jobs with qbx:cleanPlayerGroups on: players lose that job from the database.

Next steps

• Read the Qbox docs for each qbx_* resource’s config.
• The video archive has a Qbox series (jobs, boss menu, items) in the frameworks course.