nCore Inventory Installation Guide

Requirements#

OneSync on (set onesync on in server.cfg, or the OneSync setting in txAdmin). The server reads player peds and vehicles for reach checks, clothing checks, ground drops, trunks, gloveboxes and car keys. With OneSync off those fail, and the console prints a warning at start.
oxmysql is optional. Without it everything is saved in the server's own KVP store (unless Config.Database.prefer is 'none', which saves nothing). You need oxmysql for:
- invmigrate, which brings over another inventory's saved data;
- keeping the trunks and gloveboxes of owned vehicles, and owner-only trunks (the framework's vehicle table is read through oxmysql);
- the starter kit's check, on a framework, that a character is really new.
No ox_lib and no build step are needed.
A framework is optional: ESX, QBCore, QBox, ND_Core or ox_core. Without one there are no jobs or police checks, no bank accounts and no licenses, and money is the cash item.
QBox and ESX Legacy also need the bundled ox_inventory compatibility folder (step 2).
A recent game build is recommended. Some shipped weapons and models come from recent GTA Online updates. On a server that enforces an older build (sv_enforceGameBuild in server.cfg), those weapons are refused as invalid, and a pile model the build lacks falls back to a plainer one (the console says so once). The Large backpack's model needs build 2545 or newer and the Tactical backpack's needs 2802 or newer; below that they show an older bag model. Set sv_enforceGameBuild to a recent build your FiveM server artifacts support.

Steps#

Copy the ncore_inventory folder into resources/[ncore] (create the [ncore] folder if you do not have one yet). Do not rename it.
QBox and ESX Legacy only: copy the shipped ox_inventory folder, a compatibility layer for ncore_inventory, into resources/[ncore] next to ncore_inventory. Delete any other folder named ox_inventory first (stopping it is not enough). Do not lower its version line and do not add provide 'ox_inventory': qbx_core reads that version and stops the server when it fails its check. QBCore, ND_Core, ox_core and standalone servers do not need this folder.
Optional: if you run oxmysql, import sql/install.sql into your database. The resource also creates its tables by itself at start, so this is only for owners who prefer to create the schema by hand. See Database below.
Add the resource to server.cfg. The framework is detected once, at start, so oxmysql and your framework go above ensure ncore_inventory. If you use ox_target or qb-target, put it above as well. Resources that call RegisterStash (housing scripts and the like) go below it.

Standalone
server.cfg
```
ensure oxmysql            # optional
ensure ncore_inventory
```
QBCore
server.cfg
```
ensure oxmysql
ensure qb-core
ensure ncore_inventory
# your qb- resources after this line
```
ESX Legacy (the bundled compatibility folder goes directly after ncore_inventory)
server.cfg
```
setr inventory:accounts "[]"
ensure oxmysql
ensure es_extended
ensure ncore_inventory
ensure ox_inventory
```
The setr inventory:accounts "[]" line is required on ESX Legacy 1.14 and 1.15. Without it es_extended uses ["money", "black_money"], and black_money is also an item in this inventory. es_extended copies every change to that ESX account into the item, and nothing copies the item back, so the two drift apart the first time a player drops or hands over the item. The console prints a warning at every start until the line is set. ESX 1.16 and newer always mirror black_money into an item, with no write-back, whatever this line says; there the ESX black_money account and the black_money item are separate balances.

On ESX Legacy the console confirms "ESX is in its ox_inventory mode". If it prints a red "ESX IS RUNNING ITS OWN INVENTORY" box instead, follow the fix in that box. ESX 1.1 and 1.2 have no third-party inventory mode: xPlayer item calls keep using ESX's own inventory there, and the console says so at start.

QBox
server.cfg
```
setr inventory:framework "qbx"   # qbx_core shuts the server down without this line
ensure oxmysql
ensure ox_lib                    # qbx_core needs it
ensure qbx_core
ensure ncore_inventory
ensure ox_inventory
```
ND_Core or ox_core: ensure the framework (and what it needs itself), then ensure ncore_inventory.

A framework that starts after ncore_inventory is not picked up. The console names it and tells you to move its ensure line above.
Grant the admin ace:
server.cfg
```
add_ace group.admin lri.admin allow
add_principal identifier.license:<license> group.admin
```
lri.admin covers every admin part (lri.admin.panel, .edit, .give, .capacity, .storage, .shops, .economy, .logs, .config, .pose) and premium coins (lri.admin.premium). For smaller staff roles grant single parts instead; lri.admin.panel is always needed to open the panel. The test lab has its own lri.lab ace, for test servers only. A VIP capacity tier is granted with add_ace group.vip lri.tier.vip allow.

Make sure Config.Debug.commands is false in config.lua (that is how it ships).

You can switch on the extra console lines (Config.Debug.console) from server.cfg without touching config.lua. The convar wins over the config value, and it never turns on the test commands:
server.cfg
```
setr ncore_inventory:debug true
```
Language: with Config.Locale = 'auto' the server picks one language for everyone from the lr:locale, locale, ox:locale, esx:locale or txAdmin-locale convar, in that order, and otherwise uses English. The shipped languages are en, hu, de, fr, es, pt-br, pl and tr. GTA has no Hungarian or Turkish game language, so a Hungarian or Turkish server sets Config.Locale = 'hu' (or 'tr') or adds setr lr:locale "hu" to server.cfg.
Restart, join and press F2. From the server console, invgive <player id> water 10 proves the round trip.

Database#

This section applies only when oxmysql is running and Config.Database.prefer is 'auto' (the default) or 'mysql'. With 'kvp' the server's own KVP store is used, and with 'none' nothing is saved at all, even with oxmysql. The console confirms it at start with storage: oxmysql, table followed by the table name.

The main table is ncore_inventory (the name comes from Config.Database.table). At every start the resource creates it if it is missing and adds any column it lacks. The other tables are created the same way: ncore_inventory_logs (Config.Logs.table), ncore_inventory_placed for storages placed in the world, and ncore_inventory_premium when premium coins are switched on (Config.Premium.enabled).

If the database user has no ALTER right, a missing column cannot be added. The console then prints an error that names the column and the exact statement. Run that statement as a database user with ALTER rights, then restart the resource. For the default table name the statements are:

SQL

ALTER TABLE `ncore_inventory` ADD COLUMN `owner` VARCHAR(96) DEFAULT NULL;
ALTER TABLE `ncore_inventory` ADD COLUMN `kind` VARCHAR(24) NOT NULL DEFAULT 'player';
ALTER TABLE `ncore_inventory` ADD COLUMN `label` VARCHAR(96) DEFAULT NULL;
ALTER TABLE `ncore_inventory` ADD COLUMN `parent` VARCHAR(96) DEFAULT NULL;
ALTER TABLE `ncore_inventory` ADD COLUMN `slots` SMALLINT UNSIGNED NOT NULL DEFAULT 24;
ALTER TABLE `ncore_inventory` ADD COLUMN `max_weight` INT UNSIGNED NOT NULL DEFAULT 32000;
ALTER TABLE `ncore_inventory` ADD COLUMN `accepts` VARCHAR(255) DEFAULT NULL;
ALTER TABLE `ncore_inventory` ADD COLUMN `meta` VARCHAR(1024) DEFAULT NULL;
ALTER TABLE `ncore_inventory` ADD COLUMN `data` LONGTEXT DEFAULT NULL;
ALTER TABLE `ncore_inventory` ADD COLUMN `modstate` LONGTEXT DEFAULT NULL;
ALTER TABLE `ncore_inventory` ADD COLUMN `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP;

Run only the lines the console names. If you changed Config.Database.table, use your table name; the console already prints it.

Without the modstate column, module state (crafting queue jobs, what a worn container remembers) lasts only until a restart. With Config.Drops.persist on, piles on the ground also last only until a restart, and the console prints the same modstate statement for that.
The meta column must be 1024 characters wide. The resource widens a narrower one at start; if it cannot, the console says how wide it still is, and a row whose meta is longer is not saved until the column is widened. As a user with ALTER rights run this, then restart the resource:
SQL
```
ALTER TABLE `ncore_inventory` MODIFY COLUMN `meta` VARCHAR(1024) DEFAULT NULL;
```
If a column cannot be added to ncore_inventory_placed, the console tells you to run the CREATE TABLE for that table from sql/install.sql.

Test drive in 5 minutes#

Add the two ace lines from step 5, restart and join.
Type /invadmin. The admin panel opens on the Testing tab: a guided tour (326 steps in 42 parts) with setup buttons and "Show on map" buttons that set a waypoint. The shield button in the inventory header opens the panel too.
Open the Items tab and its Kits view. Give yourself food and drink, medical supplies, tools, containers, evidence, every firearm loaded, one of every key item, 1000 of each money item, one of every stackable item, or everything a crafting bench needs. Your own kits go in Config.Admin.kits.
From the server console:
- invgive <id> cash 1000 - on standalone and ox_core the cash item is the money shops take. On ESX, QBCore, QBox and ND_Core shops charge the framework's cash account, so use your framework's money command there.
- invkey <id> vehicle <plate> - cuts a car key for that plate. Using it near the car locks and unlocks it, and so does the L key (Settings, Key Bindings, FiveM, "Lock or unlock the nearest car you hold a key for"). Where a vehicle key resource with its own lock key runs, that resource handles the press.
On a test server only, set Config.Debug.commands = true and add add_ace group.admin lri.lab allow. That switches on the test lab and the bench commands: the Testing tab's teleport, car and money buttons, invitem, invfill, invmoney <amount> [player id] (through the framework's cash account, or the cash item without one) and /invdebughelp. Never do this on a live server: anyone holding the lri.admin ace can then create any item and open any inventory.

Important#

Do not rename the ncore_inventory folder; exports, pictures and the NUI page are found by that name.
Stop every other inventory resource first. This resource refuses to start beside a known one and names it in the console (add your own to Config.Conflicts.extra). On QBCore also remove qb-weapons; the console warns while it runs.
A shop another resource registers while the inventory is still starting is built as soon as the shop module is up; a refused registration is logged with its reason.
The Binco counters and the wardrobes stand inside GTA's clothing stores, where clothing resources often have their own spots. With ox_target or qb-target running, the Binco counter opens through the target eye. The wardrobe always keeps its marker and E prompt, also with a target eye. If your clothing resource opens its own menu with E in the same place, one E press opens both: move those points, or add enabled = false to wardrobe_store in data/stashes.lua and to binco in modules/shop/shops.lua.
With ncore_character running, its own clerk stands at the Binco counter and the inventory draws no Binco blip of its own, because ncore_character marks the same store. E at the clerk opens the item shop and G opens ncore_character's fitting room. With ox_target or qb-target running, the fitting room is a "Fitting room" option on the target eye instead of G. The wardrobe has its own marker beside the counter.
qb-pawnshop uses the same Vinewood counter as the shipped pawn shop; keep one of them (enabled = false on pawn_downtown in modules/shop/shops.lua turns ours off).
Saved inventories from another inventory are brought across with invmigrate in the server console (needs oxmysql). The dry run works any time; apply runs only with nobody online. Stashes, trunks and gloveboxes come across from the ox, qb and qs-style sources; from ESX only player inventories (with loadout and accounts) come across. See DOCUMENTATION.md.
A server that ran on KVP and adds oxmysql later gets a console banner. invmigrate kvp followed by invmigrate kvp apply copies the saved containers from the KVP store into the database; the KVP rows stay where they are. Admin item edits and old log lines stay in KVP, premium coin balances are read from KVP until each one is next saved to the database, and owners that already have rows in the database are skipped.
Keep your own config.lua: any setting it leaves out is filled in from shared/defaults.lua. When you update, copy the new shared/defaults.lua over the old one.