> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Containers

> Define items that open their own mini-inventory when used.

Containers are special inventory items that, when used, open their own miniature inventory inside the right-hand panel. They are perfect for restricted-content carriers like food bags, weapon cases, and medical kits.

The Awoken rework introduces a dedicated `data/containers.lua` file that registers **both the item AND its container behaviour** in a single entry - no duplication across `data/items.lua` and `setup/` scripts.

## How containers work

* A container is an inventory item players can hold and stack.
* Opening it (Use action) reveals a slot grid inside the right panel.
* Each container has its own slot count and weight limit, independent of the player's inventory.
* Optional `whitelist` or `blacklist` controls which items can be placed inside.
* Optional `fixedWeight` makes the container weigh the same no matter what's inside.
* Containers can carry a `rarity` and `tags` like any other item.

## The `data/containers.lua` file

```lua data/containers.lua theme={"dark"}
return {
    paperbag = {
        label       = 'Paper Bag',
        weight      = 50,
        description = 'A simple paper bag. Handy for carrying small everyday items.',
        tags        = { 'storage' },
        slots       = 5,
        maxWeight   = 2000,
        blacklist   = {
            'WEAPON_PISTOL', 'WEAPON_PISTOL_MK2', 'WEAPON_COMBATPISTOL',
            'WEAPON_MICROSMG', 'WEAPON_SMG', 'WEAPON_PUMPSHOTGUN',
        },
    },

    happy_meal = {
        label       = 'Happy Meal',
        weight      = 300,
        description = 'A cheerful little box with just enough room for a meal and a drink.',
        tags        = { 'storage' },
        slots       = 2,
        maxWeight   = 1000,
        whitelist   = { 'burger', 'testburger', 'mustard', 'water', 'sprunk' },
    },

    gun_box = {
        label       = 'Gun Box',
        weight      = 800,
        description = 'A secure box designed for firearm storage.',
        tags        = { 'storage' },
        rarity      = 'uncommon',
        slots       = 6,
        maxWeight   = 20000,
        fixedWeight = true, -- always weighs 800g, loaded or empty
        whitelist   = {
            'WEAPON_PISTOL', 'WEAPON_PISTOL_MK2', 'WEAPON_COMBATPISTOL',
            'WEAPON_APPISTOL', 'WEAPON_MICROSMG', 'WEAPON_SMG',
            'WEAPON_SMG_MK2', 'WEAPON_PUMPSHOTGUN', 'WEAPON_PUMPSHOTGUN_MK2',
        },
    },

    first_aid_kit = {
        label       = 'First Aid Kit',
        weight      = 600,
        description = 'A compact kit stocked with medical supplies.',
        tags        = { 'storage' },
        rarity      = 'uncommon',
        slots       = 8,
        maxWeight   = 3000,
        whitelist   = { 'bandage' },
    },
}
```

## Fields

### Item fields (same as `data/items.lua`)

| Field         | Type                | Purpose                                                         |
| ------------- | ------------------- | --------------------------------------------------------------- |
| `label`       | string              | Display name shown in the inventory UI.                         |
| `weight`      | number              | Weight of the **empty** container (grams). Contents add on top. |
| `description` | string *(optional)* | Tooltip text shown on hover.                                    |
| `tags`        | table *(optional)*  | Filter tags. See [Tags](/configuration/tags).                   |
| `rarity`      | string *(optional)* | Rarity key. See [Rarity](/configuration/rarity).                |
| `image`       | string *(optional)* | Custom image name. Defaults to the entry key.                   |

### Container behaviour fields

| Field         | Type                 | Purpose                                                                                                                       |
| ------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `slots`       | number               | Number of slots inside the container.                                                                                         |
| `maxWeight`   | number               | Maximum total weight of contents (grams).                                                                                     |
| `whitelist`   | table *(optional)*   | Only these item names can be placed inside.                                                                                   |
| `blacklist`   | table *(optional)*   | These item names **cannot** be placed inside.                                                                                 |
| `fixedWeight` | boolean *(optional)* | When `true`, the container always weighs its empty `weight` regardless of contents. Contents still count against `maxWeight`. |

<Warning>
  `whitelist` and `blacklist` are **mutually exclusive**. If both are set, the whitelist wins and the blacklist is ignored. Pick one or the other.
</Warning>

<Note>
  `fixedWeight` only changes what the **carrier** feels - the container's weight in the player's inventory stays constant whether it's empty or full. The container's internal `maxWeight` still limits how much can be stored inside, so a fixed-weight box can't hold unlimited cargo.
</Note>

## Adding a new container

The whole process is three steps:

<Steps>
  <Step title="Add an entry to `data/containers.lua`">
    Use a unique lowercase key (underscores allowed, no spaces).

    ```lua data/containers.lua theme={"dark"}
    duffel_bag = {
        label       = 'Duffel Bag',
        weight      = 1200,
        description = 'A heavy-duty sports bag.',
        tags        = { 'storage' },
        rarity      = 'rare',
        slots       = 12,
        maxWeight   = 30000,
        -- no whitelist or blacklist = anything goes
    },
    ```
  </Step>

  <Step title="Add the image">
    Drop a PNG named after the entry key into `web/images/`. Example: `web/images/duffel_bag.png`. The UI auto-resolves this - no manifest edit required.
  </Step>

  <Step title="Restart the resource">
    `ensure ox_inventory`. The new container item is now spawnable and stashable.
  </Step>
</Steps>

## Spawning a container in game

Use the standard admin command:

```text theme={"dark"}
/giveitem 1 duffel_bag 1
```

Where `1` is the target player's server ID. Open it with the standard inventory Use action.

## Worked example - restricted medical kit

A medical-only container, locked to the EMS group:

```lua data/containers.lua theme={"dark"}
ems_response_kit = {
    label       = 'EMS Response Kit',
    weight      = 1500,
    description = 'A heavy-duty paramedic kit. EMS only.',
    tags        = { 'storage', 'medical' },
    rarity      = 'rare',
    slots       = 10,
    maxWeight   = 5000,
    whitelist   = {
        'bandage', 'medikit', 'painkillers',
        'adrenaline', 'antibiotics', 'splint',
    },
},
```

Combine this with a stash or job-check hook ([see Hooks in the Exports page](/exports#hooks)) to gate who can equip the kit.

## Tips

* **Whitelist for themed bags** (food-only, ammo-only, medical-only). Players instantly understand the bag's purpose by what slides in.
* **Blacklist for "everything except"** (paper bag refuses weapons, but anything else fits).
* **`rarity` doubles as visual cue** - a legendary gold-bar case reads instantly on screen.
* **Use the `storage` tag** so containers appear together when the player filters by Storage.
* **Container weight stacks by default** - a Paper Bag (50g) holding 1kg of items weighs 1.05kg in the player's inventory.
* **`fixedWeight` for rigid cases** - the Gun Box uses it, so it always reads 800g whether empty or holding 20kg of weapons. Great for hard cases, briefcases, and lockboxes where carried weight shouldn't betray the contents.