# Items

Items are defined like in ox_inventory: in `data/items.lua`, or live on the admin **Items** pages.
Koja adds optional fields. An item without them works exactly as before.

## New item fields

```lua title="data/items.lua"
['water'] = {
    label = 'Water',
    weight = 500,
    rarity = 'common',              -- key from data/koja/rarity.lua
    throwable = true,               -- can be thrown (weight decides how far)
    prop = 'prop_ld_flow_bottle',   -- world prop for throws
    unique = true,                  -- never stacks, gets a serial number
},
```

| Field | Type | What it does |
| --- | --- | --- |
| `rarity` | string | Rarity key (`common`, `uncommon`, `rare`, `epic`, `legendary`, `mythic` or your own). Colours the slot and sets the discovery time. Default `common`. `metadata.rarity` overrides it per item |
| `throwable` | boolean | `true` = can be thrown, `false` = never. Without the field, `throw.anyItem` decides |
| `prop` | string | Model thrown for this item. Default `throw.defaultProp` |
| `unique` | boolean | Never stacks and gets `metadata.serial` |
| `isStash` | table | Turns the item into a mini stash. See below |
| `hanger` | boolean | Marks a mini stash as a clothing hanger |
| `backpack` | table | `{ slots, weight }` unlocked while worn in the bag slot |
| `clothing` | table | Makes the item wearable. See below |
| `plate` | table | `{ armor = n }` — an armour plate for a vest |
| `tint` | number | Weapon tint index (also read from `tintIndex`). The item applies that tint in the attachments view |

Items with `unique`, `isStash`, `backpack` or `plate` never stack. `unique` and `isStash` items get a serial number.

## Mini stashes

```lua title="data/items.lua"
['toolbox'] = {
    label = 'Toolbox',
    weight = 1500,
    isStash = { slots = 6, maxWeight = 8000, whitelist = { 'screwdriver', 'wrench' } },
},
```

| Field | What it does |
| --- | --- |
| `slots` | Slots of the container |
| `maxWeight` | Max weight of the contents in grams |
| `whitelist` | Item names allowed inside. Without it every item fits |

A mini stash cannot hold another mini stash or itself.

## Wearable items

```lua title="data/items.lua"
['backpack_large'] = {
    label = 'Large Backpack',
    weight = 1500,
    stack = false,
    rarity = 'rare',
    backpack = { slots = 10, weight = 20000 },
    clothing = { kind = 'component', id = 5, male = { drawable = 82, texture = 0 }, female = { drawable = 82, texture = 0 } },
},
```

`clothing` decides which slot the item goes to and what the ped wears:

| Field | What it is |
| --- | --- |
| `kind` | `component` or `prop` |
| `id` | Component or prop id — it picks the clothing slot (`5` = bag, `9` = vest, `11` = torso...) |
| `male`, `female` | `{ drawable, texture }` for each freemode ped |

Clothes taken off the ped without their own item become the generic `clothing` item, whose metadata holds the piece: `{ kind, id, drawable, texture, gender, category, label, imageurl }` — the same shape as Koja Appearance's `getClothingMeta`.

## Bundled items

The shipped `data/items.lua` contains these Koja items. Keep them when you merge your own file.

| Item | What it is |
| --- | --- |
| `clothing` | Generic clothing piece (one per undressed piece) |
| `clothing_hanger` | Hanger: a 15 slot mini stash that stores one outfit. Using it swaps outfits |
| `backpack_small` | Bag, `backpack = { slots = 5, weight = 10000 }` |
| `backpack_large` | Bag, `backpack = { slots = 10, weight = 20000 }` |
| `armor_vest` | Plate carrier (clothing id 9) that holds plates |
| `plate_light`, `plate_medium`, `plate_heavy` | Plates with 25, 50 and 100 armour |
| `tint_1` … `tint_7` | Weapon tints: green, gold, pink, army, LSPD, orange, platinum |

:::hint{type="warning" title="Tint item names"}
Tint items are named `tint_1`…`tint_7`, not `weapon_tint_*`. ox_inventory treats every name starting with `weapon_` as a weapon.
:::

## Images

Item images are PNG files named after the item in `web/images/` (or the `inventory:imagepath` convar), like in ox_inventory.
An item without an image shows an icon instead.

Clothing items use `metadata.imageurl`, filled from the `getClothingImage` export of `clothing.imageResource`.
Without it they fall back to `web/images/clothing_<slot>.png` and then to an icon.

## Items from the admin panel

Items created or edited on the admin **Items** pages are stored in `koja_inv_items` and pushed to every player live.

- Items from `data/items.lua` can be edited; the saved version overrides the file. Lua functions in the file are left untouched.
- **Hidden / disabled** keeps the definition but blocks creating and using the item. Copies already in inventories stay.
- Only items created in the panel can be deleted.

See [Admin panel](/new/inventory/admin-panel#items).