> For the complete documentation index, see [llms.txt](https://docs.northscripts.dev/site/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.northscripts.dev/site/documentation/resources/ox-inventory-rework/adding-items.md).

# Adding items

#### Normal items — `data/items.lua`

Upstream ox\_inventory fields all still work (`label`, `weight`, `stack`, `close`, `description`, `client`, `server`, `buttons`, `consume`…). The rework adds:

| Field                              | Description                                                   |
| ---------------------------------- | ------------------------------------------------------------- |
| `size = { width = 2, height = 2 }` | Size in grid cells (default 1×1)                              |
| `rarity`                           | `'common'`, `'uncommon'`, `'rare'`, `'mythic'`, `'legendary'` |
| `rename = true`                    | Players can rename it                                         |
| `client.prop`                      | World prop. It also enables **Place** and **Throw**.          |
| `stackModels`                      | Prop chosen by amount                                         |
| `durability` + `decay = true`      | The item is deleted when durability reaches 0                 |

```lua
['bandage'] = {
    label = 'Bandage',
    weight = 115,
    rarity = 'common',
    size = { width = 1, height = 1 },
    client = {
        anim = { dict = 'missheistdockssetup1clipboard@idle_a', clip = 'idle_a', flag = 49 },
        prop = { model = `prop_rolled_sock_02`, pos = vec3(-0.14, -0.14, -0.08), rot = vec3(-50.0, -50.0, 0.0) },
        disable = { move = true, car = true, combat = true },
        usetime = 2500,
    },
},

['money'] = {
    label = 'Money',
    stackModels = {
        { count = 1, model = `prop_anim_cash_note` },
        { count = 2, model = `prop_money_bag_01` },
    },
},
```

Weapons in `data/weapons.lua` accept `size` and `rarity` too, for example `size = { width = 2, height = 1 }` for rifles.

#### Containers — `data/containers.lua`

```lua
['backpack'] = { slots = 20, maxWeight = 15000, isBackpack = true },
['phone']    = { slots = 1, maxWeight = 100, whitelist = { 'simcard' }, quickDeposit = false },
```

| Field                     | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `slots`, `maxWeight`      | Capacity                                       |
| `whitelist` / `blacklist` | Items allowed / refused                        |
| `isBackpack`              | Worn in the backpack slot, opens its own panel |
| `quickDeposit = false`    | Disables quick deposit for this container      |

####  Carryable containers and safes — `data/placeables.lua`

Listing an item here registers it. **Nothing is needed in `items.lua`.**

```lua
['briefcase'] = {
    label = 'Briefcase', weight = 1500, size = { width = 2, height = 2 },
    image = 'WEAPON_BRIEFCASE.png', rename = true,
    model = `prop_ld_case_01`, distance = 1.0, useTarget = true,
    slots = 10, maxWeight = 15000, carryFull = true,
    carryAnim = { dict = 'move_weapon@jerrycan@generic', clip = 'idle', flag = 51 },
    carryProp = { bone = 57005, offset = { 0.12, 0.0, 0.0 }, rotation = { 0.0, 255.0, 80.0 } },
},

['packaged_safe'] = {
    label = 'Packaged Safe', weight = 45000, size = { width = 3, height = 4 },
    model = `p_v_43_safe_s`, distance = 2.0, requireFlat = true,
    slots = 50, maxWeight = 100000, useTarget = true, rename = true,
    lock   = { pin = true, minLength = 4 },
    anchor = { tool = 'drill', consumes = { bolts = 4, install_kit = 1 }, installTime = 12000, removeTime = 8000 },
},
```

| Field                                                  | Description                                |
| ------------------------------------------------------ | ------------------------------------------ |
| `model`                                                | World prop                                 |
| `distance`                                             | Max placement distance (default 3.0 m)     |
| `requireFlat`                                          | Can only be placed on a flat surface       |
| `useTarget`                                            | `false` disables the ox\_target options    |
| `slots`, `maxWeight`                                   | Storage                                    |
| `carryFull`                                            | Can be carried while full (boxes and bags) |
| `carryAnim`, `carryProp`                               | How it is held                             |
| `lock = { pin, minLength }`                            | PIN lock (makes it a safe)                 |
| `anchor = { tool, consumes, installTime, removeTime }` | Can be bolted down                         |

`carryFull` **can't be combined** with `lock` or `anchor`. If you combine them, a warning is printed and `lock` and `anchor` are ignored.

#### Images

* Put a `<itemname>.png` file in `web/images/` (100×100 is recommended).
* Clothing items look for `web/images/<slot>_<gender>_<drawable>_<texture>.png` and fall back to the generic slot icon if it is missing.
* Custom images per item: `metadata.imageurl`, which must point to a host in `inventory:validhosts`.