Installation

10 min readUpdated 2 weeks ago

Installation

ML Inventory installs inside an existing ox_inventory folder, renamed ml_inventory. The download holds Micio Mods files only: a replacement fxmanifest.lua, the micio/ folder, the compiled interface in web/build and the placeholder slot art in web/images. No ox_inventory file is included. ox_inventory is the work of Overextended, published under the GPLv3, and is downloaded separately from its repository.

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, which ML Clothing uses to reach your framework. It is a free download on the Cfx.re portal.
  • The ox_inventory folder you run today, or a fresh copy from the ox_inventory repository. 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
1ensure oxmysql
2ensure ox_lib
3ensure ml_bridge
4ensure ml_inventory
5ensure ml_clothing

On qb-core, one more line:

server.cfg
1setr inventory:framework "qbx"
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.

Two inventory rows in txAdmin

ml_inventory also answers to the name ox_inventory, so every script that calls exports.ox_inventory keeps working with no edit. txAdmin shows that name as a second row. It is the same resource listed twice, not a second inventory: leave it alone and never stop it.

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
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
1Config.AdminAce = nil
2Config.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

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.

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

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.

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.

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.

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.

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.

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.

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.

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 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.

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.

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.

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