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
xand rowyis sloty * 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:citizenidfor a personal copy; - a vehicle is
trunk<PLATE>orglove<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, andGetInventory,GetInventoriesand hooktypeFilters report its type aspoliceevidence. - Vehicle ids win over stash names. As in ox, an id that starts with
trunkorglovenames that vehicle's store even when a stash was registered under it.AddItem('trunkABC123', ...)reaches the trunk of the vehicle with plateABC123, 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 = falsetakes a cell per unit. Containers and weapons never stack, except throwables, which stack as ox's do. - Wear: ox's
degradeanddecaydo nothing. Only firearms wear, by shots fired; throwables have no durability. - Weapon fields:
Items('WEAPON_PISTOL')gives a weapon ox'shash,modelandammoname, the ammo item listed for it indata/weapons.lua. Throwables reportthrowable = true. Weapons and weapon components reportclose = false, as ox's do.
- Stacking: as in ox, a cell holds any amount of an item, and an item with
Money
In a player's pockets, money is the player's cash in cobalt_core:
AddItem,RemoveItem,GetItemCount,SearchandCanCarryItemwith'money'read or change cash.GetItemSlotsand theGetSlot*WithItemexports report it as one slot with no slot number.ClearInventorytakes it, unlesskeepnamesmoney.- The client's
ox_inventory:itemCountevent fires when cash changes. ConfiscateInventoryandCreateDropFromPlayerleave 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
AddItemorSwapSlots; - 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
RegisterShopadds a shop at runtime:- each
inventoryentry becomes an item with itsprice,countas stock,licenseandmetadata; locations(or the targets'loc) get a shopkeeper ped and the blip;groups(or ox's olderjobs) limits the shop to those jobs or gangs at or above each grade, and an item'sgradelimits that item the same way;- the shop takes cash, as ox's
moneycurrency 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.
- each
RegisterStashandCreateTemporaryStashmake a stash with the requestedslotsandmaxWeight. Both throw ox's error whenslotsormaxWeightisn't a number. A stash with aninstanceopens only for players in that routing bucket.- Owners:
- a fixed owner (a string or a number) makes a shared stash named
name:owner; owner = truegives 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.
- a fixed owner (a string or a number) makes a shared stash named
- Drops:
- Instances: a drop belongs to an instance,
CustomDrop'sinstanceargument or the dropper's routing bucket. Players in another bucket neither see it nor open it. - Model:
CustomDrop'smodelshows that prop in place of the marker. - Size:
CustomDrop'sslotsandmaxWeightsize the drop. Without them it takes thedropssize fromconfig/inventory.lua.
- Instances: a drop belongs to an instance,
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.createItemalso carriesresource, the resource that calledAddItem. - Units: as in ox, adding several of an item that doesn't stack runs
createItemonce per unit, withcount = 1. - Extra actions:
swapItemsalso fires for splitting a stack, dropping an item (toInventoryisnewdrop) and giving one to another player (actionisgive). - Post-hook event: each hook that ran gets ox's
TriggerEvent(hookId, success, payload), 50 ms after the action ends. removeHooksremoves 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):
itemis ox's item;inventoryis a copy inGetInventory's shape;slotis the slot number;usedItemruns 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
CanCarryItemfirst; - grid space still applies, and it returns
nilwhen no free cell or stack can take the item; - an item that doesn't stack is added as far as there is room.
- it ignores the weight limit, as ox's does, so check
GetInventoryreturns a copy in ox's shape (id,label,type,slots,weight,maxWeight,owner,itemsby slot). Changing it does nothing.SwapSlotsswaps the two cells in the live inventories, where ox's export only swaps the copies it was passed. It never merges stacks.SetSlotCountnever goes below the slot of the last item in the grid.setContainerPropertiessets the item'scontainer(slots,maxWeightandwhitelist) and resizes the loaded bags of that item. Bags already loaded keep their old whitelist, andblacklistis ignored.CanCarryAmountcounts by weight alone, as in ox.forceOpenInventorydoes nothing for a player whose pockets aren't loaded, as in ox.- Client
openInventoryreturnstrueonce the inventory is open andfalsewhen it isn't, as ox does. weaponWheel(true)unblocks GTA's weapon wheel, for weaponised vehicles.displayMetadataadds 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:usedItemandox_inventory:currentWeapon, as ox fires them. LocalPlayer.state.invOpenfollows the inventory.- Events handled: ox's
openInventory,closeInventory,notify,disarm,clearWeapons,suppressItemNotifications,inventoryConfiscatedandinventoryReturnednet events, and the localox_inventory:itemevent.
On the server:
- Events fired:
ox_inventory:itemListwhile it starts,ox_inventory:usedItemafter every use, andox_inventory:openedInventoryandox_inventory:closedInventorywhen a player opens or closes another inventory. - Handled and answered: the local
ox_inventory:customDropevent, and theox_inventory:getItemCountandox_inventory:getInventorycallbacks.
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 ignoresprovide. Usenui://cobalt_inventory/...instead.web/images/: images are not at ox's path, soLoadResourceFile('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. AddItemrefuses a count of NaN or infinity.metadata.weightcounts inCanCarryItemonly. Everywhere else, weight comes from the item definition.ox_inventory:loadInventorynever fires.- No-ops:
degrade,decay,setGetPlayerNameMethodand PEFCL'sgetBank,getCardsandgiveCarddo nothing.