Containers

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

data/containers.lua

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.
`rarity`	string (optional)	Rarity key. See 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`.

whitelist and blacklist are mutually exclusive. If both are set, the whitelist wins and the blacklist is ignored. Pick one or the other.

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.

Adding a new container

The whole process is three steps:

Add an entry to `data/containers.lua`

Use a unique lowercase key (underscores allowed, no spaces).

data/containers.lua

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
},

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.

Restart the resource

ensure ox_inventory. The new container item is now spawnable and stashable.

Spawning a container in game

Use the standard admin command:

/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:

data/containers.lua

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) 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.

Get Started

Awoken Scripts

How containers work

The `data/containers.lua` file

Fields

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

Container behaviour fields

Adding a new container

Spawning a container in game

Worked example - restricted medical kit

Tips

​How containers work

​The data/containers.lua file

​Fields

​Item fields (same as data/items.lua)

​Container behaviour fields

​Adding a new container

​Spawning a container in game

​Worked example - restricted medical kit

​Tips

How containers work

The `data/containers.lua` file

Fields

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

Container behaviour fields

Adding a new container

Spawning a container in game

Worked example - restricted medical kit

Tips