Skip to Content
Cobalt

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.' },
FieldDefaultMeaning
labelthe nameShown in the UI
weightrequiredGrams per unit. The server prints an error at start listing every item without one
descriptionnoneShown in the tooltip and item menu
stackstacksfalse gives each unit its own cell. Containers and weapons never stack, except throwables
containernone{ slots, maxWeight, whitelist? } makes the item a bag that opens an inventory of that size. whitelist lists the only items it takes
throwablenonetrue 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',
    },
},
FieldMeaning
client.usetimeProgress bar length in ms, or { min, max }
client.labelProgress bar text, as a key in locales/en.json. Without it the bar reads "Using" and the item label
client.anim, client.prop, client.propTwoAnimation 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.statusApplied 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.notificationShown when the use finishes
consumeHow many are removed per use, default 1; 0 keeps the item
closefalse keeps the inventory open on use

Item handlers

For behaviour of its own, an item names an export in the resource that owns it:

FieldCalled asUse it for
server.export = 'resource.Fn'Fn(event, item, inventory, slot, data) on the serverChecks and outcomes the server must own
client.export = 'resource.Fn'Fn(event, item, slot) on the clientOpening a tool, screen effects
  • inventory is { id, name, source }. id is the player's server id for their own pockets, and the inventory name otherwise.
  • item is the entry from data/items.lua, so extra fields such as server.armour or client.effect reach the export.
  • slot is the stack that was used.

Each export runs twice:

  1. With 'usingItem', before the item is removed. Returning false cancels the use.
  2. With 'usedItem', after the item is removed. On the server, this call also gets whatever usingItem returned.
---@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:

  1. The server export's usingItem.
  2. The useItem hooks.
  3. The client export's usingItem, then the progress bar.
  4. The item is removed and status applied.
  5. 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.

On this page