Skip to Content
Cobalt

ox_inventory compatibility

Scripts written for ox_inventory run unchanged on cobalt_inventory. How ox's exports, ids, money, hooks and events map onto the grid.

cobalt_inventory declares provide 'ox_inventory' and answers every exports.ox_inventory:* call, event and hook, so scripts written for ox_inventory run unchanged. GetResourceState('ox_inventory') reports started and dependency 'ox_inventory' is met. Keep the stock ox_inventory resource out of resources/: if a folder of that name is present, FiveM resolves the name to it instead.

For the API itself, read Overextended's ox_inventory docs. Cobalt resources call cobalt_inventory's own exports instead.

How ox maps onto the grid

  • Slots are grid cells. Every grid is 5 cells wide, so the cell in column x and row y is slot y * 5 + x + 1, and an inventory has exactly the slots it was created with. Slots 1 to 5 of the pockets are the quick-access row.
  • Inventory ids:
    • a player is their server id;
    • a stash is its name, or name:citizenid for a personal copy;
    • a vehicle is trunk<PLATE> or glove<PLATE>;
    • drops and temporary stashes use the id the export returned.
  • Evidence lockers are evidence-<id>. As in ox, any export that names one creates it with ox's size, 100 slots and 100,000 g, and GetInventory, GetInventories and hook typeFilters report its type as policeevidence.
  • Vehicle ids win over stash names. As in ox, an id that starts with trunk or glove names that vehicle's store even when a stash was registered under it. AddItem('trunkABC123', ...) reaches the trunk of the vehicle with plate ABC123, and fails when no such vehicle is spawned or owned.
  • Items keep their names, with weapons in upper case (WEAPON_PISTOL) as ox spells them. Weights are in grams in both.
    • Stacking: as in ox, a cell holds any amount of an item, and an item with stack = false takes a cell per unit. Containers and weapons never stack, except throwables, which stack as ox's do.
    • Wear: ox's degrade and decay do nothing. Only firearms wear, by shots fired; throwables have no durability.
    • Weapon fields: Items('WEAPON_PISTOL') gives a weapon ox's hash, model and ammoname, the ammo item listed for it in data/weapons.lua. Throwables report throwable = true. Weapons and weapon components report close = false, as ox's do.

Money

In a player's pockets, money is the player's cash in cobalt_core:

  • AddItem, RemoveItem, GetItemCount, Search and CanCarryItem with 'money' read or change cash.
  • GetItemSlots and the GetSlot*WithItem exports report it as one slot with no slot number.
  • ClearInventory takes it, unless keep names money.
  • The client's ox_inventory:itemCount event fires when cash changes.
  • ConfiscateInventory and CreateDropFromPlayer leave cash with the player.

Anywhere else (a stash, trunk, glovebox, drop, bag or temporary stash), money is the money item: weightless, one stack of any size per cell, and treated like any other item. A script that pays its takings into a stash, as a player-run shop does with RemoveItem(buyer, 'money', price) and AddItem(stash, 'money', price, nil, slot), works unchanged.

Pockets never hold the item. The moment money reaches a player's pockets it becomes cash, however it got there:

  • by AddItem or SwapSlots;
  • by a restored confiscation, which pays out even when the pockets have no free cell;
  • by a player dragging or splitting it out of a stash, trunk or drop.

moveItem and swapItems hooks run for the item and then for the money, and a hook that refuses either one stops both. If cobalt_core refuses the credit, the money goes back to where it came from. Money that can't go back is logged to cobalt_core's inventory log at level error.

Stashes, drops and shops

  • RegisterShop adds a shop at runtime:
    • each inventory entry becomes an item with its price, count as stock, license and metadata;
    • locations (or the targets' loc) get a shopkeeper ped and the blip;
    • groups (or ox's older jobs) limits the shop to those jobs or gangs at or above each grade, and an item's grade limits that item the same way;
    • the shop takes cash, as ox's money currency does, and an entry priced in another currency is left out with a warning;
    • a shop with no locations opens from anywhere with openInventory('shop', { type = name });
    • registering a shop again replaces it.
  • RegisterStash and CreateTemporaryStash make a stash with the requested slots and maxWeight. Both throw ox's error when slots or maxWeight isn't a number. A stash with an instance opens only for players in that routing bucket.
  • Owners:
    • a fixed owner (a string or a number) makes a shared stash named name:owner;
    • owner = true gives each character a personal copy;
    • an export that names the stash with no owner reaches the copy named name;
    • a client can open only its own copy.
  • Drops:
    • Instances: a drop belongs to an instance, CustomDrop's instance argument or the dropper's routing bucket. Players in another bucket neither see it nor open it.
    • Model: CustomDrop's model shows that prop in place of the marker.
    • Size: CustomDrop's slots and maxWeight size the drop. Without them it takes the drops size from config/inventory.lua.

Robbing players

openInventory('player', id) opens another player's pockets for police, and for anyone else only while Player(id).state.canSteal is true.

Ox sets that state from the target's client. Here the server sets it: canSteal is true while any of the target's isDead, cuffed or handsUp states is set. The server runs with sv_stateBagStrictMode, which drops a client's own LocalPlayer.state:set('canSteal', ...). A script that makes players robbable some other way should set one of those states, or canSteal itself, from its server side.

Hooks

swapItems, openInventory, createItem, usingItem, buyItem, openShop and craftItem run with ox's payloads, filters and return values, in the order they were registered.

  • Payload extras: each payload carries its hookId. createItem also carries resource, the resource that called AddItem.
  • Units: as in ox, adding several of an item that doesn't stack runs createItem once per unit, with count = 1.
  • Extra actions: swapItems also fires for splitting a stack, dropping an item (toInventory is newdrop) and giving one to another player (action is give).
  • Post-hook event: each hook that ran gets ox's TriggerEvent(hookId, success, payload), 50 ms after the action ends.
  • removeHooks removes only the caller's own hooks.

Item handlers

A server.export in a cobalt_ resource gets cobalt's (event, item, inventory, slot, data) call; see Items. Any other resource's server.export is called as ox calls it, (event, item, inventory, slot):

  • item is ox's item;
  • inventory is a copy in GetInventory's shape;
  • slot is the slot number;
  • usedItem runs only when the use removes items.

When a player buys the item from a shop, an ox-style export also gets ('buying', item, inventory, slot, shop) before the payment. Returning false stops the purchase.

Client handlers from other resources, and any client.event, are called as ox calls them, (data, { name, slot, metadata }). The item is used only if the handler calls exports.ox_inventory:useItem(data, cb).

Set server.exportStyle or client.exportStyle to 'cobalt' or 'ox' to override the guess, as the phone item does for npwd.

Exports that behave differently

  • AddItem:
    • it ignores the weight limit, as ox's does, so check CanCarryItem first;
    • grid space still applies, and it returns nil when no free cell or stack can take the item;
    • an item that doesn't stack is added as far as there is room.
  • GetInventory returns a copy in ox's shape (id, label, type, slots, weight, maxWeight, owner, items by slot). Changing it does nothing.
  • SwapSlots swaps the two cells in the live inventories, where ox's export only swaps the copies it was passed. It never merges stacks.
  • SetSlotCount never goes below the slot of the last item in the grid.
  • setContainerProperties sets the item's container (slots, maxWeight and whitelist) and resizes the loaded bags of that item. Bags already loaded keep their old whitelist, and blacklist is ignored.
  • CanCarryAmount counts by weight alone, as in ox.
  • forceOpenInventory does nothing for a player whose pockets aren't loaded, as in ox.
  • Client openInventory returns true once the inventory is open and false when it isn't, as ox does.
  • weaponWheel(true) unblocks GTA's weapon wheel, for weaponised vehicles.
  • displayMetadata adds rows to item tooltips.
  • setStashTarget(id, owner) makes the inventory key open that stash.

Events

On the client:

  • Events fired: ox_inventory:itemCount, ox_inventory:updateInventory, ox_inventory:usedItem and ox_inventory:currentWeapon, as ox fires them.
  • LocalPlayer.state.invOpen follows the inventory.
  • Events handled: ox's openInventory, closeInventory, notify, disarm, clearWeapons, suppressItemNotifications, inventoryConfiscated and inventoryReturned net events, and the local ox_inventory:item event.

On the server:

  • Events fired: ox_inventory:itemList while it starts, ox_inventory:usedItem after every use, and ox_inventory:openedInventory and ox_inventory:closedInventory when a player opens or closes another inventory.
  • Handled and answered: the local ox_inventory:customDrop event, and the ox_inventory:getItemCount and ox_inventory:getInventory callbacks.

Starting and stopping cobalt_inventory fires the resource start and stop events again with 'ox_inventory' as the resource name. Scripts that register stashes or shops when ox_inventory starts do so then, and restart cobalt_inventory keeps their cached exports working.

Item images

Item images are in _nui/images/<item>.png. An item's client.image from Items() is the full nui://cobalt_inventory/_nui/images/... path.

Known gaps

  • nui://ox_inventory/... URLs load nothing, because NUI resolves hosts by folder name and ignores provide. Use nui://cobalt_inventory/... instead.
  • web/images/: images are not at ox's path, so LoadResourceFile('ox_inventory', 'web/images/<item>.png') finds nothing.
  • Version checks: lib.checkDependency('ox_inventory', version) reads cobalt_inventory's version, 1.0.0, so a script that requires a newer ox_inventory refuses to start.
  • AddItem refuses a count of NaN or infinity.
  • metadata.weight counts in CanCarryItem only. Everywhere else, weight comes from the item definition.
  • ox_inventory:loadInventory never fires.
  • No-ops: degrade, decay, setGetPlayerNameMethod and PEFCL's getBank, getCards and giveCard do nothing.

On this page