Items
Items are defined in shared/items.lua. Items from ox_inventory's data/items.lua and data/weapons.lua are imported automatically; define an item here to override the imported version (for example to give it a better grid size). Items can also be created at runtime from other resources. See Runtime items.
WEAPON_CARBINERIFLE = {
label = 'Carbine rifle',
size = { 4, 2 },
weight = 3800,
stack = 1,
category = 'weapon',
rarity = 'epic',
equip = 'weapon_primary',
weapon = { ammo = 'ammo_rifle', clip = 30 },
description = '5.56 mm assault carbine.',
salvage = { duration = 8000, results = { { name = 'scrap_metal', count = { 4, 8 } } } },
},Basic fields
| Field | Description |
|---|---|
label | Name shown in the UI. |
description | Text in the item popup. |
size | { width, height } in cells. |
weight | Grams per unit. |
stack | Max units in one stack. 1 means it never stacks. |
category | Free text used for filters, repair rules and slot rules, e.g. weapon, tools, food. |
rarity | common, uncommon, rare, epic or legendary. Colours the tile. |
image | File name in Config.ImagePath without .png. Defaults to the item name. |
prop | Model used when the item lies on the ground or is held. |
close | false keeps the inventory open after using the item. |
Equipment and containers
| Field | Description |
|---|---|
equip | Slot type it fits: backpack, vest, weapon_primary, weapon_secondary, or clothing_<key>. |
container | { width, height, maxWeight, allow } gives the item its own grid, like a backpack. allow limits it to categories. A backpack cannot go inside another backpack. |
armor | Armour points of a vest. Wear is saved back into the item. |
ped | Look on the character when equipped: { male = { drawable, texture }, female = { drawable, texture } }. Used for backpacks (component 5) and vests (component 9) when Config.Gear.enabled is on. Set it to drawables that exist on your server. |
Weapons
| Field | Description |
|---|---|
weapon.ammo | Ammo item used to reload. |
weapon.clip | Magazine size. |
weapon.melee | true for melee weapons (no ammo, no wear). |
attachment | On an attachment item: list of component names, or a table per weapon. |
attachSlot | Mount point in the workshop: sight, muzzle, barrel, flashlight, grip, magazine or skin. |
Weapons keep their ammo, serial number, attachments and durability in metadata.
Usable items
burger = {
label = 'Burger',
size = { 1, 1 },
weight = 350,
stack = 3,
category = 'food',
rarity = 'common',
description = 'A double cheeseburger. Four big bites.',
degrade = 2880,
prop = `prop_cs_burger_01`,
consume = 1,
uses = 4,
use = {
duration = 2200,
anim = { dict = 'mp_player_inteat@burger', clip = 'mp_player_int_eat_burger_fp' },
prop = { model = `prop_cs_burger_01`, bone = 18905, pos = vec3(0.13, 0.05, 0.02), rot = vec3(-50.0, 16.0, 60.0) },
status = { hunger = 12 },
},
},| Field | Description |
|---|---|
use | { duration, anim, prop, status, heal }: a progress bar with animation and prop. status adds hunger/thirst (ESX status or QB metadata), heal adds health. |
consume | Units removed per use. |
uses | Bites or sips per unit (2 to 100). Each use applies use.status once; the item is gone after the last one. |
degrade | Minutes until it spoils. Shows a freshness bar; spoiled items cannot be used. |
usable | true marks an item usable that has no use block (for example handled by RegisterUsableItem). |
Usable items also work through RegisterUsableItem, ox client.export / server.export, ESX.RegisterUsableItem and QBCore CreateUseableItem.
Held items
hold controls how the item sits in the hand:
hold = { model = `prop_ld_flow_bottle`, bone = 28422, pos = vec3(0.0, 0.0, -0.02), rot = vec3(0.0, 0.0, 0.0), anim = false, carry = false },hold = true uses the default prop, hold = false makes the item impossible to hold. carry = true uses the two-handed box carry. Without hold, the prop comes from Config.Hands.props, then use.prop, then prop, then a bag or box by item size.
Durability
Weapons and tools listed in Config.Durability wear out automatically. Override it per item:
durability = { shot = 0.2, use = 10, craft = 5 },shot is percent per shot, use per use, craft per craft when the item is a recipe tool. See Features.
Salvage
salvage = { duration = 6000, results = { { name = 'scrap_metal', count = { 1, 4 } }, { name = 'cable', count = 1, chance = 50 } } },Right click → Salvage takes the item apart. count can be a number or { min, max }; chance is a percent.