Migrate ESX to QBox: what transfers, what breaks and a checklist

You run an ESX server and you want QBox. Before you start, you need to know one thing: nothing transfers by itself. ESX and QBox use different tables, different player identifiers, different item systems and different APIs. This guide tells you what that means, how to choose between a wipe and a migration, what needs a bridge, and gives you a timeline.

#What does not transfer automatically

Your players keep their license identifier, so a converted character can still be linked to the right person. The rest has to be mapped.

#Wipe or migrate

Wipe means a fresh QBox server and new characters. It is cleaner and much faster. It suits a server that is still small, a server whose data is a mess, or one that is changing its whole direction. Tell your players clearly and early.

Migrate means converting the data. It keeps player progress, but you need a conversion script that reads your ESX tables and writes QBox rows. Write it for your own server, because every ESX server has different tables and extra columns. Money is easy to map. Black money, custom items and vehicle properties take care. A common compromise is to migrate money and vehicles and give items back by hand.

Whichever you pick, test the conversion on a copy of the database, never the live one.

#Plan the stack

QBox runs on a stack that differs from a typical ESX server:

• qbx_core as the framework
• ox_lib, oxmysql, ox_inventory and ox_target

See install QBox for the details. If your ESX server already uses ox_inventory, ox_lib and ox_target, a good part of the stack is the same, but its data still lives in the framework's tables, so it does not carry over as it is.

#Scripts: convert, bridge or replace

Go through your resource list and sort each script:

1. Framework independent scripts (maps, vehicles, sounds, standalone tools): they usually just work.
2. Scripts that detect the framework (many store scripts support ESX, QBCore and QBox): they work, check their config for the framework setting.
3. ESX only scripts: these need one of three things:
   • Convert it yourself. The ESX to QBCore guide, convert an ESX script to QBCore, and then convert a QBCore script to QBox show the changes.
   • Use a bridge that provides the ESX functions on top of QBox, if you accept the layers it adds.
   • Replace it with a QBox native script. Often the best choice for jobs, housing and inventory based scripts.
4. Inventory scripts: these are the hardest, because item definitions and the inventory change with the framework.

Write the list down. It is your work estimate. Pay special attention to scripts that handle money, items or vehicles, since they touch the data you convert.

#Build a test server first

1. Create a second server with the QBox recipe (txAdmin recipes). Never work on the live one.
2. Copy over the maps, vehicles and standalone resources.
3. Add the converted or replaced scripts one at a time and restart after each, so you know which one breaks. See reading a script error.
4. Import a copy of your ESX data, run the conversion script, and check the result by joining with a test account.
5. Test the main loops: joining, jobs, money, shops, vehicles, housing.

#Timeline checklist

Use this order, and leave space for each step:

1. Decide wipe or migrate, and tell your community the plan and the date.
2. List all your scripts and mark each one as works, convert, bridge or replace.
3. Back up the ESX files and database. See backup your server.
4. Build the QBox test server.
5. Convert or replace the scripts, then write and test the data conversion if you migrate.
6. Test with real players if possible, in an open beta.
7. Fix what they find. This takes longer than you expect.
8. Switch: announce downtime, take a last backup of ESX, run the conversion on a fresh copy of the latest data, and start QBox.
9. Keep the ESX backup for a while, in case you must roll back.

Tip: do not change anything else at the same time. A framework change, a new map and a new economy together make it impossible to tell what broke.

If your players have a lot at stake, run the old and the new server in parallel for a short time. If your scripts come from a store, check which frameworks each one supports before you buy new ones, so you pick scripts that also work on QBox.

#Checklist