Items
Add items to cobalt_inventory, make them usable, and run your own code when they're used.
Items live in data/items.lua, keyed by item name. Edit the file and run restart cobalt_inventory.
Adding an item
energy_drink = { label = 'Energy drink', weight = 330, description = 'Keeps you up all night.' },| Field | Default | Meaning |
|---|---|---|
label | the name | Shown in the UI |
weight | required | Grams per unit. The server prints an error at start listing every item without one |
description | none | Shown in the tooltip and item menu |
stack | stacks | false gives each unit its own cell. Containers and weapons never stack, except throwables |
container | none | { slots, maxWeight, whitelist? } makes the item a bag that opens an inventory of that size. whitelist lists the only items it takes |
throwable | none | true on a weapon makes it a thrown weapon that uses one item per throw. See Thrown weapons |
A stack has no size limit; the inventory's weight limit is the only cap. An item is a weapon when data/weapons.lua lists its name, in upper case, under weapons. The weapon_ prefix alone doesn't make one, so weapon_license is a plain item. Ammo, clips and attachments are the items data/weapons.lua lists.
Then add _nui/images/energy_drink.png. An item without an image shows a placeholder.
client = { image = 'can.png' } shows another file from _nui/images/. It can be any image type, in a subfolder ('drinks/can.webp'), or a full URL. An item whose metadata has image (a file name without .png) or imageurl shows that in its slot.
Weapon ammo
A weapon loads at most one ammo item, set in ammunition in data/weapons.lua. Each key there is an ammo item, and its list names the weapons that load it. Reloading with R, or using the ammo item, takes rounds from the player's pockets up to the clip size.
ammunition = {
rocket_ammo = { 'WEAPON_RPG' },
grenade_ammo = { 'WEAPON_GRENADELAUNCHER', 'WEAPON_COMPACTLAUNCHER' },
},The launchers load rocket_ammo, homing_ammo, grenade_ammo, smoke_grenade_ammo, firework_ammo, railgun_ammo and railgunxm3_ammo. The Minigun, Widowmaker and Unholy Hellbringer load mg_ammo.
Thrown weapons
A weapon with throwable = true is thrown one at a time, as in ox_inventory:
weapon_grenade = { label = 'Grenade', description = 'A handheld throwable bomb', weight = 500, throwable = true },- Throwables stack, and have no serial or durability.
- Drawing one puts a single round in the player's hand.
- Each throw or placement removes one from the stack. The next one is in hand right away; after the last, the hand is empty.
- Holstering, swapping or dropping the stack takes nothing.
The grenade, BZ gas, molotov, sticky bomb, proximity mine, snowball, pipe bomb, ball, smoke grenade and flare ship as throwables. They load no ammo item.
Usable items
An item is usable when its entry has client, server or consume, or when it is a weapon, ammo, a container or marked money. Plain food and drink need no code:
energy_drink = {
label = 'Energy drink', weight = 330,
client = {
usetime = 4000,
label = 'use.drinking',
anim = { dict = 'mp_player_intdrink', clip = 'loop_bottle', flag = 49 },
prop = { model = 'prop_ld_flow_bottle', bone = 18905, pos = vec3(0.12, 0.008, 0.03), rot = vec3(240.0, -60.0, 0.0) },
status = { thirst = { min = 30, max = 40 }, stress = -5 },
notification = 'You drank an energy drink',
},
},| Field | Meaning |
|---|---|
client.usetime | Progress bar length in ms, or { min, max } |
client.label | Progress bar text, as a key in locales/en.json. Without it the bar reads "Using" and the item label |
client.anim, client.prop, client.propTwo | Animation and props during the bar. prop can be a list. Animations several items share are locals at the top of data/items.lua (anim.drink, eat, drink) |
client.status | Applied when the bar completes: hunger and thirst through cobalt_core, stress and alcohol through cobalt_hud. A number or a { min, max } range; negative stress relieves it |
client.notification | Shown when the use finishes |
consume | How many are removed per use, default 1; 0 keeps the item |
close | false keeps the inventory open on use |
Item handlers
For behaviour of its own, an item names an export in the resource that owns it:
| Field | Called as | Use it for |
|---|---|---|
server.export = 'resource.Fn' | Fn(event, item, inventory, slot, data) on the server | Checks and outcomes the server must own |
client.export = 'resource.Fn' | Fn(event, item, slot) on the client | Opening a tool, screen effects |
inventoryis{ id, name, source }.idis the player's server id for their own pockets, and the inventory name otherwise.itemis the entry fromdata/items.lua, so extra fields such asserver.armourorclient.effectreach the export.slotis the stack that was used.
Each export runs twice:
- With
'usingItem', before the item is removed. Returningfalsecancels the use. - With
'usedItem', after the item is removed. On the server, this call also gets whateverusingItemreturned.
---@param event 'usingItem' | 'usedItem'
---@param item table
---@param inventory { id: string | integer, name: string, source: integer }
function Armor(event, item, inventory)
if event == 'usingItem' then
return GetPedArmour(GetPlayerPed(inventory.source)) < item.server.armour
end
SetPedArmour(GetPlayerPed(inventory.source), item.server.armour)
end
exports('Armor', Armor)A use runs in this order:
- The server export's
usingItem. - The
useItemhooks. - The client export's
usingItem, then the progress bar. - The item is removed and
statusapplied. - Both exports'
usedItem.
Carried items
An item with carry puts its prop in the player's hands for as long as they hold any of it:
drug_package = {
label = 'Sealed Package', weight = 4000,
carry = {
model = 'hei_prop_heist_box',
bone = 60309,
pos = vec3(0.025, 0.08, 0.255),
rot = vec3(-145.0, 290.0, 0.0),
anim = { dict = 'anim@heists@box_carry@', clip = 'idle', flag = 49 },
disable = { 'sprint', 'jump', 'enterVehicle', 'combat' },
},
},disable lists what the player can't do while carrying it: sprint, jump, enterVehicle and combat (aiming, shooting and melee). Leave it out to block nothing.