Migration

Migration

Switching inventory is the riskiest thing a server does. The usual reason it goes badly is a migration tool that knew what the old data looked like — it knew, it was wrong about one field, and three hundred people lost a weapon.

This one does not know. It looks.

Supported sources

qb-inventory, ox_inventory, codem, tgiann, core_inventory, qs — and in practice anything storing bags as JSON, because the forks differ in almost nothing that matters. Every one stores a container as one of two shapes:

[ { name, amount, slot, info }, … ]           an ARRAY
{ "3": { name, count, slot, metadata }, … }   a SLOT MAP

with field names drawn from a handful of synonyms. The importer reads the shape out of your actual rows instead of assuming one.

The order matters

1. The item list. Names are the vocabulary. Migrating a bag before the catalogue knows what a fishing_rod is imports a word nothing can read.

invmigrate items          dry run
invmigrate items write    write data/items.generated.lua

The generated file is a starting point to read and edit. Add it to fxmanifest.lua after data/items.lua, then refresh and restart.

2. The player data.

invmigrate scan                              dry run: what is out there
invmigrate run                               write — refuses on unknown names or existing containers
invmigrate run allow-unknown                 accept losing unknown names
invmigrate run force                         overwrite containers that already exist here

Importing from another inventory's tables

invimport                       what is on this server, and what would come across
invimport <id>                  dry-run one source
invimport <id> run              write — containers that already exist here are skipped
invimport <id> run force        overwrite them (writes export_before_force_<time>.json first)
invimport export                dump what THIS inventory holds
invrestore <file> <id> confirm  put one container back from an export file

The admin panel's Migration tab does the same thing in three steps:

1. Pick where from — every inventory it found on this server, with how much each one holds.
2. See what would happen — the dry run, in sentences: how many containers and items would come across, and what would be lost.
3. Move it — one button, blocked until every loss on the report has been accepted with its own switch: leave the items this server does not know behind, replace what players are already carrying here.

Nothing is written before step 3.

Three rules the importer keeps

Dry run first, always. Every command reports before it writes, and writing is a different command with a different word after it.

An unknown name is never dropped silently. An item in the source with no entry in the catalogue stops the run. You can accept the loss explicitly with allow-unknown, and then it is named in the report and written to the ledger. An item that vanishes quietly is an item the player can never get back.

A container that already exists here is never overwritten without force: invimport skips it, invmigrate run refuses.

Keeping the old name working

Other resources call qb-inventory by name. Rather than editing them, install the proxy from compat/ — see Compatibility.