> For the complete documentation index, see [llms.txt](https://oph3zdev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oph3zdev.gitbook.io/docs/paid-scripts/inventory/configuration/items.md).

# Items

Before an item can be seen or used in game it must be defined. All items are defined in <mark style="color:$primary;">config/items.lua</mark> inside the `Items` table as key, value pairs - the key is the item name (not the label) your scripts use, the value is a table with the item's options.

Items can also be created live from the admin panel's Items tab (saved to the database, no file edit), or brought over from another inventory with the import tool.

### Item options

Fields marked with `?` are optional.

#### Basics

* **`label`** : `string` - display name shown in the inventory.
* **`type`** : `string` - `food`, `drink`, `tool`, `clothing`, `armor`, `bag`, `money`, `misc`. Food takes bites, drinks take sips, bags open, money mirrors an account.
* **`weight`** : `number` - grams per unit.
* **`width`** / **`height`** : `number` - size in grid layout.
* **`description?`** : `string` - tooltip text.
* **`image?`** : `string` - file in the `images/` folder. Without it `<itemname>.png` is used, then a placeholder.
* **`propModel?`** : `string` - object model shown when the item is dropped, placed or thrown.

#### Stacking

* **`unique?`** : `boolean` - `true` = never stacks and every copy gets its own serial number.
* **`stack?`** : `boolean` - `false` = no stacking, without a serial.

#### Using

* **`usable?`** : `boolean` - `true` = usable with double click or a hotbar key.
* **`consume?`** : `boolean` - `false` = the item survives the use. Default: one is consumed.
* **`status?`** : `table` - what the use does to the player: `hunger`, `thirst`, `stress`, `hp`. Negative values work.
* **`use?`** : `table` - the use takes time, with animation and prop:
  * **`duration`** : `number` - milliseconds.
  * **`anim`** : `table` - `dict`, `clip`.
  * **`prop?`** : `table` - `model`, `bone` (`18905` left hand, `57005` right), `pos`, `rot`.
  * **`cancel?`** : `boolean` - `true` = moving cancels the use, nothing is consumed.
* **`onUse?`** : `table` - runs your own code on use, the item becomes usable automatically:
  * **`server?`** / **`client?`** : `string` - exports, `"resource.ExportName"`.
  * **`serverEvent?`** / **`clientEvent?`** : `string` - event names.
  * Handlers receive `(source, item)`. Framework `RegisterUsableItem` still works and takes priority.

#### Food and drink

* **`portions?`** : `number` or `table` - multi-use consumable, status split per portion:
  * **`count`** : `number` - bites or sips.
  * **`weight?`** : `boolean` - `true` = gets lighter as it empties.
  * **`alcohol?`** : `number` - handed to your drunk script per sip.
  * **`leftover?`** : `string` - item created when the last portion is taken.
* **`decay?`** : `table` - spoils in real time, on the server, also while offline:
  * **`hours`** : `number` - shelf life at normal speed.
  * **`to?`** : `string` - item it turns into. Without it, it vanishes.
  * **`at?`** : `number` - convert at this percent instead of 0.
  * **`stages?`** : `table` - override the global freshness labels for this item.

#### Wearing and storage

* **`equipSlot?`** : `string` - makes it wearable: `hat`, `mask`, `glasses`, `ears`, `shirt`, `undershirt`, `vest`, `gloves`, `watch`, `bracelet`, `accessory`, `pants`, `shoes`, `bag`.
* **`wornVisual?`** : `table` - real drawable on the ped while worn: `male` / `female` with `drawable`, `texture`.
* **`armor?`** : `table` - `value` = armor given, scaled by durability, drains with damage. With armor plates turned on it becomes the vest's ceiling instead.
* **`plate?`** : `table` - `value` = armor one plate adds to a worn vest. Only used when the plate has no rarity, otherwise the rarity decides. See `Config.VestPlates` on the config page.
* **`container?`** : `table` - the item opens its own inventory:
  * **`slots`** / **`maxWeight`** / **`grid`** - capacity.
  * **`weightPercent?`** : `number` - how much of the contents weight the holder feels, `25` = a magic bag.
  * **`whitelist?`** / **`blacklist?`** : `table` - item types or names allowed or banned inside.
  * **`equippedOnly?`** : `boolean` - only openable while worn.
  * **`cold?`** : `number` - spoilage multiplier inside, `0.35` = cooler, `0` = freezer.

#### Special

* **`money?`** : `table` - `account` = the framework account the item mirrors, moving it converts into real money.
* **`craftKit?`** : `string` - using the item opens that crafting station anywhere. Add `consume = false` so the kit survives.
* **`tradeable?`** : `boolean` - `false` = can never be offered in a player trade.
* **`rarity?`** : `string` - fixed tier from `config/rarity.lua`, shown as the tile colour.

### Weapon options

Weapons, ammo and attachments live in <mark style="color:$primary;">config/weapons\_items.lua</mark> (`Weapons`, `WeaponAmmo`, `WeaponComponents` tables). They are normal items - everything above applies - plus one extra block:

* **`weapon?`** : `table` - makes the item a weapon:
  * **`hash`** : `string` - the game weapon.
  * **`ammo`** : `string` - the ammo item it loads.
  * **`clip`** : `number` - clip size.
  * **`degrade`** : `number` - durability lost per shot.
  * **`attachSlots`** : `table` - workbench slots the weapon offers.
* **`attachment?`** : `table` - makes the item a weapon attachment:
  * **`slot`** : `string` - the workbench slot it mounts into.
  * **`components`** : `table` - list of game components, the workbench picks the one that fits the weapon.

Ammo items need no extra block - the weapon's `ammo` field points at them by name.

### Examples

A basic item:

```lua
cloth = {
    label = "Cloth",
    type = "misc",
    weight = 60,
    width = 1,
    height = 1,
    description = "A piece of clean fabric."
}
```

A consumable with portions, spoilage and an eat animation:

```lua
burger = {
    label = "Burger",
    propModel = "prop_cs_burger_01",
    type = "food",
    weight = 220,
    width = 1,
    height = 1,
    description = "A greasy cheeseburger.",
    decay = { hours = 48 },
    status = { hunger = 35 },
    portions = 4,
    use = {
        duration = 3000,
        anim = { dict = "mp_player_inteat@burger", clip = "mp_player_int_eat_burger" },
        prop = { model = "prop_cs_burger_01", bone = 18905, pos = { x = 0.13, y = 0.05, z = 0.02 }, rot = { x = -50.0, y = 16.0, z = 60.0 } }
    }
}
```

An item that runs your own code:

```lua
magic_pill = {
    label = "Magic Pill",
    type = "misc",
    weight = 50,
    width = 1,
    height = 1,
    onUse = {
        server = "myscript.OnPillUsed",
        client = "myscript.OnPillUsedClient"
    }
}
```

A wearable bag with its own inventory:

```lua
bag = {
    label = "Duffel Bag",
    propModel = "prop_cs_heist_bag_02",
    type = "bag",
    weight = 900,
    width = 2,
    height = 2,
    equipSlot = "bag",
    wornVisual = {
        male = { drawable = 45, texture = 0 },
        female = { drawable = 45, texture = 0 }
    },
    container = {
        slots = 12,
        maxWeight = 20000,
        grid = { cols = 6, rows = 3 },
        weightPercent = 100,
        blacklist = { "weapon" }
    }
}
```

An armor vest:

```lua
armor_vest = {
    label = "Armor Vest",
    type = "armor",
    weight = 3500,
    width = 2,
    height = 2,
    equipSlot = "vest",
    armor = { value = 50 },
    wornVisual = {
        male = { drawable = 4, texture = 0 },
        female = { drawable = 4, texture = 0 }
    }
}
```

A money item:

```lua
cash = {
    label = "Cash",
    type = "money",
    weight = 0,
    width = 1,
    height = 1,
    money = { account = "cash" }
}
```

A weapon and an attachment (<mark style="color:$primary;">config/weapons\_items.lua</mark>):

```lua
["weapon_pistol"] = {
    label = "Walther P99",
    type = "weapon",
    weight = 1000,
    width = 2,
    height = 1,
    unique = true,
    weapon = {
        hash = "WEAPON_PISTOL",
        ammo = "pistol_ammo",
        clip = 12,
        degrade = 0.15,
        attachSlots = { "muzzle", "barrel", "clip", "flashlight", "scope", "grip", "skin", "paint" }
    }
}

["at_suppressor_light"] = {
    label = "Suppressor",
    type = "attachment",
    weight = 280,
    width = 1,
    height = 1,
    attachment = {
        slot = "muzzle",
        components = { "COMPONENT_AT_PI_SUPP", "COMPONENT_AT_PI_SUPP_02" }
    }
}
```