Skip to main content

Installation

This guide covers a clean installation of wasabi_inventory and the safest path when replacing another inventory resource.

1. Back up your server​

Before replacing an inventory system, back up:

  • Your database.
  • Existing item, weapon, shop, and stash definitions.
  • Your server configuration.
  • Any scripts that call inventory exports or events.
warning

Inventory data is economy-critical. Test the replacement with a copy of your production database before deploying it to a live server.

2. Install dependencies​

Install and start:

See Dependencies for framework-specific notes.

3. Install the resource​

  1. Download the latest release from your Wasabi Scripts account.
  2. Extract it into your server's resources directory.
  3. Rename the folder to exactly:
wasabi_inventory
  1. Do not run another full inventory resource at the same time.
danger

Do not rename the resource to ox_inventory. Keep it named wasabi_inventory; its manifest provides the ox_inventory capability for supported compatibility calls.

4. Configure the framework​

ESX​

Configure ESX to use an external inventory. In current ESX installations this is the CustomInventory option expected by the inventory bridge:

Config.CustomInventory = 'ox'

The resource stores inventory JSON in users.inventory. The column is added automatically if it does not exist.

QBCore​

The resource detects qb-core, stores inventory JSON in players.inventory, and redirects the supported player item methods to the inventory engine.

Disable your previous inventory resource and remove duplicate inventory startup entries.

Qbox​

The resource detects qbx_core and stores inventory JSON in players.inventory.

Disable your previous inventory resource and remove duplicate inventory startup entries.

5. Review items and integrations​

  • Merge your item definitions into data/items.lua, or replace the starter file with your existing item definitions when the schema matches.
  • Review weapon, ammunition, and component definitions in data/weapons.lua.
  • Copy required item images into ui/images/.
  • Review built-in shops in data/shops.lua.
  • Review trunk/glovebox capacities and model rules in data/vehicles.lua.
  • Update scripts that depend on undocumented behavior from your previous inventory.

Migrating item and weapon data from ox_inventory​

data/items.lua and data/weapons.lua use a compatible schema (tables keyed by item name with fields such as label, weight, durability, and ammoname). The engine resolves items by name, so third-party scripts and exports keep working when names match.

If you are replacing ox_inventory and want to keep your existing weights, durability, and labels exactly:

  1. Back up the Wasabi starter data/items.lua and data/weapons.lua.
  2. Copy your ox_inventory data/items.lua and data/weapons.lua into wasabi_inventory/data/ (or merge carefully).
  3. Re-add any Wasabi-only entries you still need (for example backpacks or canThrow fields).
  4. Restart and verify shops, weapons, and dependent scripts.

Explicitly set consume on items that should be consumed: omitted values now default to zero, even when an item has a use time or server export. See Consumption rules.

Fresh installs can keep the Wasabi starter catalogs and extend them as needed.

The compatibility layer handles the supported API surface, but it should not be treated as a guarantee that every third-party script written for another inventory works without testing.

6. Configure startup order​

Use an order equivalent to:

ensure oxmysql
ensure ox_lib

# Start one framework
ensure es_extended
# ensure qb-core
# ensure qbx_core

ensure wasabi_inventory

Start resources that consume inventory exports after wasabi_inventory.

7. First start​

Perform a full server restart and check the console.

On startup, the resource:

  • Creates the configured stash table when it does not exist.
  • Adds the framework inventory column when it does not exist.
  • Adds missing trunk and glovebox LONGTEXT columns to the framework vehicle table.
  • Detects the active framework bridge.
  • Loads item, weapon, component, shop, and locale data.

8. Validation checklist​

Vehicle storage and upgrades​

Vehicle contents are stored separately from config.StashTable:

  • ESX: owned_vehicles, keyed by plate.
  • QBCore: player_vehicles, keyed by plate.
  • Qbox: player_vehicles, preferring the owned vehicle ID from the vehicleid state bag or optional qbx_vehicles lookup; otherwise falling back to a plate lookup.

The framework vehicle table must already exist, and the database user needs permission to add missing columns. Startup adds columns, not the vehicle table or vehicle ownership records. Saving uses an UPDATE of the matching vehicle row; storage on vehicles without a matching row is not guaranteed to persist. Existing compatible trunk/glovebox JSON is read from these columns; this is not a general converter for every previous inventory's vehicle-storage format.

Back up vehicle records before upgrading. Check plate formatting, custom table mappings, and saved item definitions on a restored database. Config.TrimVehiclePlate removes all whitespace by default, and keys are uppercased; verify those keys match your garage's records. Avoid reducing capacities without reconciling existing contents: slots outside the configured capacity are not hydrated on load.

Checks before launch​

Before opening the server to players, verify:

  • A player can join and open their inventory.
  • Items persist after reconnecting and after a server restart.
  • Adding, removing, using, moving, and giving items work.
  • Cash synchronization works for your framework.
  • Shops charge the intended currency and grant the correct quantity.
  • Shared and personal stashes remain separated correctly.
  • Trunks and gloveboxes respect capacities and access rules, and saved contents survive closing, reopening, and a server restart on an owned vehicle.
  • Garage plate changes preserve storage; integrations use UpdateVehicle alongside their own entity/database changes.
  • Weapons reload, retain metadata, and save correctly.
  • All dependent Wasabi and third-party resources start without missing-export errors.