# Installation

> Installation guide for ML Inventory

Category: INVENTORY · Source: https://miciomods.it/docs/ml-inventory-installation · Last updated: 2026-10-02

# Installation

ML Inventory installs inside an existing `ox_inventory` folder, renamed `ml_inventory`. The package contains the addon and ML Clothing; it does not include the ox_inventory base, the server item catalog or its item images. ox_inventory is published under GPLv3 and is supplied separately from [its repository](https://github.com/overextended/ox_inventory).

> **DANGER:** Back up before the first start
>
> The number of cells a player carries comes from the grid in `micio/config/grid.lua`, not from the slot count the server used before. Slots 1 and 2 are the weapon slots and slots 11 to 25 are the clothing slots, so 17 slots per character are reserved and the pocket capacity is `playerCols` times `playerRows`.
>
> Anything a character was keeping in a reserved slot that does not belong there is moved into a free grid cell the first time that character loads, once per character. A firearm already in slot 1, a melee weapon in slot 2 or a clothing item already in its own slot stays where it is. Items saved in a slot number above the new total per character are moved the same way. An item that finds no free cell stays in the slot it was saved in and is placed as soon as the grid has room. Give the grid enough room to hold what your players were carrying, and back up the inventory table and your framework player table before the first start.

## Before you start

- OneSync enabled on the server.
- FiveM server artifact 6116 or newer.
- `ox_lib` 3.36.4 or newer and `oxmysql` 2.7.3 or newer, already running. ox_inventory checks both at start and refuses to run below them.
- `ml_bridge`, required by both ML Inventory and ML Clothing. It is a free download on the [Cfx.re portal](https://portal.cfx.re).
- The `ox_inventory` folder you run today, or a fresh copy from the [ox_inventory repository](https://github.com/overextended/ox_inventory). Tested on ox_inventory 2.47.7 through 2.47.9; releases outside that range have not been checked.

## Install the inventory

1. Stop the server.
2. Rename your `ox_inventory` folder to `ml_inventory`.
3. Delete the `web/build` folder inside it. The download replaces it, and copying over the top would leave the old interface files behind.
4. Copy the contents of the `ml_inventory` folder from the download into it. Say yes when asked to replace `fxmanifest.lua`: FiveM allows one manifest per resource, and this one loads the ox_inventory files that are already in the folder. Every other ox_inventory file stays exactly as you had it.
5. In `server.cfg`, replace the `ensure ox_inventory` line with `ensure ml_inventory`, still after `ox_lib` and `oxmysql`, add `ensure ml_bridge` before it and `ensure ml_clothing` after it.
6. On qb-core, add `setr inventory:framework "qbx"` to `server.cfg`. That convar decides which framework and which database table names the inventory uses. The server prints a warning at boot when qb-core runs with any other value.
7. If your config sets `inventory:imagepath`, delete the line or point it at `ml_inventory`. It normally points at `ox_inventory`, which no longer exists after the rename. Left unset, the resource serves icons from its own `web/images`. A path that names a resource which is not on the server prints a warning at boot, and item icons go missing here and in every other script that reads the convar.
8. Put the `ml_clothing` folder from the download into your resources folder.
9. Copy the 18 entries from `ml_clothing/_INSTALL/items.lua` into `ml_inventory/data/items.lua` and the PNG files from `_INSTALL/images/` into `ml_inventory/web/images`. The items are listed under Install ML Clothing below.
10. Start the server.

**server.cfg**

```cfg
ensure oxmysql
ensure ox_lib
ensure ml_bridge
ensure ml_inventory
ensure ml_clothing
```

On qb-core, one more line:

**server.cfg**

```cfg
setr inventory:framework "qbx"
```

> **INFO:** What the install leaves alone
>
> `data/` item definitions, `locales/` and every inventory table in your database are left alone. Items and saved inventories carry over as they are. Item icons stay in `web/images` and are served as PNG: an icon saved as `.webp` is not loaded and needs converting to `.png`.

> **WARNING:** Two inventory rows in txAdmin
>
> `ml_inventory` also answers to the name `ox_inventory`, so calls to `exports.ox_inventory` resolve through the resource alias. txAdmin may show the alias as a second row for the same inventory. Keep the resource running while the inventory is in use.

## Updating an addon installation

Back up the resources and database. Copy the supplied addon files into the existing installation. Keep the base `client.lua`, `server.lua`, `init.lua`, `modules/`, `data/`, `locales/` and existing item images. Keep the resource names unchanged.

Merge your settings into the new config files. Keep the placement flag and collection tables described in Configuration, and preserve custom edits in `open/`.

To use another placement resource, adapt `open/item_placement.lua` as described in Developer.

## Coming from an older install

If your current install lives inside a modified `ox_inventory` folder, do not install this one on top of it.

1. Download a fresh `ox_inventory` inside the tested range and unpack it next to the old folder.
2. Copy your `data/` folder from the old install into the fresh one.
3. Copy your item icons from the old `web/images` into the fresh one.
4. Leave the database untouched. Saved inventories, stashes and item metadata are read unchanged.
5. Replace your existing `ml_clothing` folder with the one from this download. Copy your edited values from the old `shared/config.lua` and `shared/invadmin_config.lua` into the new files by hand, key by key: a line for a key the new file does not have is ignored.
6. Delete or archive the old folder, then follow the steps above from the rename.

## Install ML Clothing

ML Clothing is the second resource in the package. It runs after `ml_inventory`, as in the `server.cfg` block above, and it needs `ml_bridge`, `ox_lib` and `oxmysql`.

### Database

There is no SQL file to import. ML Clothing creates what it needs on first start: `ml_invadmin_audit` for the admin panel audit log and `ml_clothing_stash_props` for placed stash props. Worn appearance is not kept in a table of its own: it is saved through the detected appearance script, or in item metadata when no appearance script is detected.

### Item registration

Clothing pieces, armor plates and the bag are inventory items. The 18 definitions are in `_INSTALL/items.lua` and their icons in `_INSTALL/images/`.

Clothing items, each `stack = false` and `close = true`:

- `hat`: Hat, 300 g
- `mask`: Mask, 200 g
- `glasses`: Glasses, 100 g
- `earrings`: Earrings, 50 g
- `chain`: Chain, 100 g
- `watch`: Watch, 150 g
- `bracelet`: Bracelet, 100 g
- `undershirt`: Undershirt, 250 g
- `jacket`: Jacket, 500 g
- `bodyarmor`: Body Armor, 1500 g
- `gloves`: Gloves, 150 g
- `pants`: Pants, 400 g
- `shoes`: Shoes, 600 g
- `bag`: Bag, 800 g
- `decals`: Decals, 50 g

Armor plate items, each `stack = true` and `close = true`:

- `lightplate`: Light Plate, 500 g. 25% armor when inserted in a plate carrier
- `heavyplate`: Heavy Plate, 1200 g. 50% armor when inserted in a plate carrier
- `brokenplate`: Broken Plate, 400 g. No protection

> **WARNING:** Restart, do not refresh
>
> Add `ml_clothing` with the server stopped, or restart the server after adding it. A live `refresh` can skip the files of a resource that was not on disk when the server started, and the resource then starts half loaded.

## Verify

- The server starts with `ml_inventory` and `ml_clothing` both up and no error in the console.
- The console prints the capacity line: grid columns by rows, the cells that grid gives, the 17 reserved equipment slots and the total per character. The same line prints the slot count in use before the install.
- No missing items are reported. ML Clothing lists any of the 18 bundle items that `data/items.lua` does not define, and tells you where to copy them from.
- Open the inventory in game: the grid, the clothing panel and the character preview come up, with your items where you left them.
- Use a clothing item, for example `jacket`: it equips into its slot and the ped updates.
- `bodyarmor` opens a plate carrier stash where plate items can be inserted, and a `bag` opens its own stash.
- The admin panel opens for an admin account with the chat command below.

### Admin panel

**shared/invadmin_config.lua**

```lua
Config.AdminAce = nil
Config.Command = 'invadmin'
```

- `Config.AdminAce`: default `nil`, an ACE permission that opens the panel. An account holding that ACE is let in; every other account is checked against the framework admin group, whether or not this is set. Setting it widens access, it does not restrict it.
- `Config.Command`: default `'invadmin'`, the chat command that opens the panel.

## Troubleshooting

**Another script says the inventory is missing**

`ml_inventory` answers to the name `ox_inventory`, so `exports.ox_inventory` keeps resolving. Check that `ml_inventory` started, and that no old `ensure ox_inventory` line is left in `server.cfg`.

**Item icons are missing after the rename**

Delete `inventory:imagepath` from your config, or point it at `ml_inventory`. Left unset, the resource serves icons from its own `web/images`.

**Icons saved as .webp show nothing**

`web/images` is served as PNG. An icon saved as `.webp` is not loaded and the slot stays empty. Convert those files to `.png`, keeping the file name.

**The console lists items missing from ml_inventory**

ML Clothing checks the inventory for each of the 18 bundle items a few seconds after boot and names the ones it cannot find. Copy the matching entries from `_INSTALL/items.lua` into `ml_inventory/data/items.lua`, copy `_INSTALL/images` into `ml_inventory/web/images`, then restart the server.

**A clothing item does nothing when used**

The item name must match a key in `Config.ClothingItems` in `shared/config.lua`. Register the item in `data/items.lua` using the exact names from `_INSTALL/items.lua`. An unregistered item has no definition to equip.

**Armor plates give no protection**

A plate only counts when its name is a key in `Config.Plates`. `brokenplate` is a repairable shell and gives no armor until it is repaired. Plates are inserted into the plate carrier stash that `bodyarmor` opens; loose plates in the grid do nothing.

**An outfit does not survive a reconnect**

The outfit is written back through the detected appearance script, and that script must start before `ml_clothing`. Outfits are saved back into illenium-appearance, bl_appearance, 4bit_appearance, codem-appearance and crm-appearance. fivem-appearance and qb-clothing are detected but have no save path back into them. With no appearance script detected, clothing lives in item metadata. The detected script is printed when `Config.Debug` is `true` in `shared/config.lua`.

**The admin panel refuses to open**

Access is checked on the server. An account holding the ACE in `Config.AdminAce` is let in; every other account is checked against the framework admin group. Grant your account that group, or set `Config.AdminAce` in `shared/invadmin_config.lua` to an ACE your account holds.

**Items land in the wrong slot**

Slots 1 and 2 hold weapons and slots 11 to 25 hold clothing. Each clothing item needs a unique slot number in `Config.ClothingItems`; two items on the same number leave one of them without a slot.

**A character carries less than before**

The pocket capacity is `playerCols` times `playerRows` in `micio/config/grid.lua`. When saved characters hold more cells than the grid can show, the console names how many rows would fit the fullest one. That scan runs while `MicioConfig.Rescue.report` is `true` in `micio/config/core.lua`; with it off, only the grid line is printed. Nothing is resized for you.

**The HUD is not on screen**

The HUD is drawn while the inventory is closed and `MicioConfig.UI.Hud.enabled` is `true` in `micio/config/ui.lua`. With `mode = 'key'` it shows only for a few seconds after the HUD key, TAB by default. With `locked = false` players can hide and move it from the settings, and those choices are saved on their machine. `locked = true` holds everyone to the config values.

**The number keys 1 to 5 do nothing**

They use the item wheel assignments, and an unassigned slot has nothing to trigger. Open the wheel, assign an item to each of its five slots, then the matching number key uses it. Assignments are saved on the player's machine.

**The character preview is blurred or unreadable**

`inventory:screenblur` set to true blurs the whole frame, preview ped included, and the console names it at boot. Set the convar to false, or turn `MicioConfig.UI.virtualPed` off in `micio/config/ui.lua`.

**The console warns about inventory:framework on qb-core**

Add `setr inventory:framework "qbx"` to `server.cfg` and restart. That convar decides which framework and which database table names the inventory uses.