Migrating from ESX or QBCore to QBox

01Why move to QBox

QBox is the successor of QBCore, started in 2022 to carry its development forward. It keeps a compatibility bridge for most resources written for QBCore, and relies on open libraries that have become the standard: ox_lib for menus and server callbacks, ox_inventory for the inventory, oxmysql for the database.

It also ships what older bases needed separate scripts for: choosing between several characters, several jobs or gangs per player if you allow it, a queue when the server is full, and vehicles that stay where they were left. For a point-by-point comparison of the three frameworks, read ESX vs QBCore vs QBox.

02What carries over, what gets rewritten, what gets rebuilt

Before touching a file, sort every part of your current server. The table sums up what happens to each one when you move to Nova; the steps below go through each line.

03Step 1: take stock of your server

A failed migration nearly always starts with a resources folder copied wholesale. Take the time to list what actually runs, and keep a way back.

1. Export your current database to .sql and keep a copy off the server: it is your way back.
2. List every resource your server.cfg starts, and note its framework: it depends on qb-core, on es_extended, or on neither.
3. Sort them into four groups: the framework and its core resources, gameplay scripts, added maps and vehicles, scripts written for you.
4. Write down your city settings: jobs, grades and salaries, prices, items, doors, gangs. They are not copied, they are rebuilt, and a written list saves hours.
5. For every script bought under licence, ask its author whether a QBox or QBCore version exists before rewriting anything.

04Step 2: drop the duplicates

The whole framework and its core resources are not migrated: the new base already provides them. On Nova, that covers the inventory, phone, targeting, banking, appearance, chat, spawn selection, vehicle keys and door locks. Two versions of the same resource step on each other, and the error rarely shows on the first start.

05Step 3: move your QBCore scripts to QBox

To migrate QBCore to QBox, the bridge answers most of a script's calls: the object returned by exports['qb-core']:GetCoreObject(), player functions such as Player.Functions.AddMoney or SetJob, and callbacks created with QBCore.Functions.CreateCallback. On Nova, it is on by default and can be set in your server's Configuration screen (Enable QB Bridge). Four things remain to check, script by script:

• Targeting: a script that calls qb-target has to move to ox_target, which Nova provides (the older qtarget is recognised too).
• Items added at runtime with QBCore.Functions.AddItem: ox_inventory does not know them. On Nova, an item is declared in the catalogue, in game.
• Direct calls to qb-inventory: replace them with ox_inventory's exports (AddItem, RemoveItem, Search).
• An @ox_lib/init.lua line in the fxmanifest: on Nova, ox_lib is provided by nova_lib, and no ox_lib folder exists on disk. Replace the line with @nova_lib/shared/lib_init.lua, or the console shows "Failed to load script".

Then upload your scripts into the resources/[client] folder from the Files screen, one by one or as an archive. A new resource arrives switched off: turn it on in the Resources card, restart the server, then read the console. The walkthrough is in the documentation on your scripts.

06Step 4: port your ESX scripts

Migrating ESX to QBox takes more work, since nothing translates ESX calls. Every gameplay script is rewritten, or replaced with an equivalent written for QBox or QBCore. For a short script, the rewrite often comes down to a handful of replacements:

The script logic stays yours: only the way you get the player, their accounts and their inventory changes. Callbacks and menus go through ox_lib, already there. Keep one rule in mind while rewriting: every sensitive action, money, items or jobs, is decided on the server, never on the word of what the client sends.

07Step 5: bring your data across

Characters, their inventories and their vehicles are not converted automatically: Nova's database does not have the same shape as ESX's or QBCore's. The account area's import also refuses any statement that names a framework table, such as players, users, player_vehicles or ox_inventory.

So plan a fresh start for characters. Tell your community early, and make an occasion of it: a relaunch where everyone starts level is easier to take than a loss discovered on day one.

Your own scripts' data does carry over. Export their tables to .sql, then import the file from the Databases screen: it is read in full before running, and a single refused statement means nothing is applied. The documentation on databases says how many databases your plan allows.

08Step 6: rebuild the city in game

On a plain QBox server, jobs, items and vehicles are declared in Lua files. On Nova, they are rebuilt inside the game by typing /admin, from the list you made in step 1. Link the server to the Discord bot first: until it is linked, the panel only opens the linking screen.

• Jobs and gangs: grades, salaries and boss access are created from the panel.
• Items: an item is declared in the catalogue and lands in inventories; its image is uploaded from the account area's Media screen.
• Vehicles: the dealership catalogue is filled in game, and can import every vehicle QBox knows in one go.
• Doors, properties, shops and prices: each has its own screen, with no file to open.
• Staff: ranks come from the roles of your Discord server. They are no longer written as add_principal lines in server.cfg.

An uploaded script that reads ACE permissions at startup, for a restricted command for instance, gets them from the Configuration screen, under Script permissions. You have no access to server.cfg, and you do not need it.

09Step 7: test, then open

1. Take a backup from the Backups screen before each batch of scripts: restoring puts files and databases back as they were.
2. Turn your scripts on in small batches, restart, and read the console after each batch: a missing dependency or fxmanifest is named there.
3. Play a full loop with two or three people: create a character, take a job, get paid, buy something, get arrested, get treated.
4. Open the city once the console stays clean after a restart.
5. If something blocks you, open a request from the server page: it attaches the server's status, and support will know you are migrating.

10Migrating to Nova: what it costs

Nova is one subscription per server, hosting, updates and support included: NOVA at €99 a month for 64 players, NOVA+ at €149 for 128 players, NOVA INFINITY at €229 for 256 players. Yearly billing charges ten months for twelve, and the server is installed when you subscribe, with no setup fee.

For your own scripts, the three plans set aside 2 GB, 8 GB or 20 GB, and one, two or three databases. As with any FiveM server, you need your own Cfx key, created on the Cfx.re portal. The pricing page shows which plans are open today, and the guide to what a FiveM server costs does the maths over twelve months.

Frequently asked questions