# 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](/new/inventory-v2/api/runtime-items).

```lua title="shared/items.lua"
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

```lua title="shared/items.lua"
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:

```lua
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:

```lua
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](/new/inventory-v2/features#durability-and-repair).

## Salvage

```lua
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.