Item Structure

Core Inventory uses a grid-based system where every item has a size, category, and optional metadata. This page covers how to register items, categories, inventories, and clothing.

Registering Items

Items are added via items.lua (QBCore), the items database table (ESX), or live through C8RE Tools (/core_inventory). Every item follows this field structure:

Required Fields

Field	Type	Purpose
name	string	Item ID used in scripts and commands (must be lowercase)
label	string	Display name shown in the inventory UI
x	number	How many grid slots the item takes up horizontally
y	number	How many grid slots the item takes up vertically
category	string	Must match a key in Config.ItemCategories
description	string	Info text shown in the item info panel

Optional Fields

Field	Type	Purpose
componentHash	string	GTA component hash — only for weapon attachments when using UniqueComponent mode
componentTint	number	Weapon skin tint index — used for weapon finish items
componentCapacity	number	Magazine capacity — only for items with category = 'component_clip'. Defaults to 30 if not set
backpackModel	number	Ped component drawable ID for male characters when this item is equipped as a backpack
backpackTexture	number	Texture variant for the male backpack model
femaleBackpackModel	number	Ped component drawable ID for female characters (overrides backpackModel)
femaleBackpackTexture	number	Texture variant for the female backpack model

Items Location

Where your items live depends on your framework. Choose your setup below:

Items are defined in your framework's shared items file:

qb-core/shared/items.lua

['bread'] = {
    name = 'bread',
    label = 'Bread',
    x = 1,
    y = 1,
    category = 'misc',
    description = 'A loaf of bread'
},

['weapon_pistol'] = {
    name = 'weapon_pistol',
    label = 'Pistol',
    x = 2,
    y = 2,
    category = 'weapons',
    description = 'A standard 9mm pistol'
},

['at_clip_extended_pistol'] = {
    name = 'at_clip_extended_pistol',
    label = 'Extended Pistol Mag',
    x = 1,
    y = 1,
    category = 'component_clip',
    description = 'Extended magazine for pistols',
    componentCapacity = 24
},

['large_backpack'] = {
    name = 'large_backpack',
    label = 'Large Backpack',
    x = 2,
    y = 3,
    category = 'backpacks',
    description = 'A large hiking backpack',
    backpackModel = 45,
    backpackTexture = 0,
    femaleBackpackModel = 45,
    femaleBackpackTexture = 0
},

Items are stored in your database's items table:

MySQL database → items table

INSERT INTO `items` (`name`, `label`, `x`, `y`, `category`, `description`)
VALUES
('bread', 'Bread', 1, 1, 'misc', 'A loaf of bread'),
('weapon_pistol', 'Pistol', 2, 2, 'weapons', 'A standard 9mm pistol');

INFO

The [items]/ESX/setup.sql file adds the required x, y, category, and description columns to your existing items table.

Items are loaded from a file inside the core_inventory resource. Set UseItemsFile = true and ItemsFileMode = 'ox' in config:

resources/[c8re]/core_inventory/data/items.lua

return {
    ['bread'] = {
        label = 'Bread',
        weight = 100,
        stack = true,
        close = false,
        description = 'A loaf of bread',
        x = 1,
        y = 1,
        category = 'misc',
    },

    ['weapon_pistol'] = {
        label = 'Pistol',
        weight = 2500,
        stack = false,
        close = true,
        description = 'A standard 9mm pistol',
        x = 2,
        y = 2,
        category = 'weapons',
    },

    ['at_clip_extended_pistol'] = {
        label = 'Extended Pistol Mag',
        weight = 300,
        stack = false,
        close = false,
        description = 'Extended magazine for pistols',
        x = 1,
        y = 1,
        category = 'component_clip',
        componentCapacity = 24,
    },

    ['large_backpack'] = {
        label = 'Large Backpack',
        weight = 5000,
        stack = false,
        close = false,
        description = 'A large hiking backpack',
        x = 2,
        y = 3,
        category = 'backpacks',
        backpackModel = 45,
        backpackTexture = 0,
        femaleBackpackModel = 45,
        femaleBackpackTexture = 0,
    },
}

You can also use QB format with ItemsFileMode = 'qb' — place a standard shared/items.lua file in the data/ folder instead.

TIP

This is the recommended approach for QBX and ESX Legacy since they don't expose a shared items table that core_inventory can read at runtime.

Item Categories

Categories define the behavior and appearance of items. Each category controls color, sounds, stacking, durability, and serial numbers.

ItemCategories = {
    ["misc"] = {
        color = "#f2f2f2",
        takeSound = 'take',
        putSound = 'put',
        stack = 5           -- Stack up to 5
    },
    ["weapons"] = {
        color = "#4ac3ff",
        takeSound = 'take_gun',
        putSound = 'put_gun',
        durability = true,  -- Track durability
        serial = true,      -- Auto-generate serial
    },
    ["ammunition"] = {
        color = "#ed2b41",
        takeSound = 'take_ammo',
        putSound = 'put_ammo',
        stack = 60
    },
}

Category Properties

Property	Type	Description
color	string	Hex color for the item slot background
takeSound	string	Sound played when picking up the item
putSound	string	Sound played when placing the item
stack	number	Max stack size. -1 for infinite, omit for no stacking
durability	boolean	Enable durability tracking for this category
serial	boolean	Auto-generate unique serial numbers

Default Categories

Backpacks

Containers with their own inventory grid.

Wallets

Money-only containers.

Cases

General purpose containers (weapon cases, storage cases).

Misc

General items. Stackable (default 5).

Weapons

Durability + serial number. Not stackable.

Ammunition

Ammo items. Stackable (default 60).

Components

Weapon attachments — suppressors, scopes, grips, clips, barrels, flashlights, finishes.

Clothing

Wearable items — masks, pants, shoes, torso, hats, glasses, etc.

Money

Cash items. Stackable (default 100,000).

Clothing System

Core Inventory manages clothing through dedicated holder slots. Each clothing category maps to a GTA ped component:

InventoryClothing = {
    ['mask']      = {mID = 1, mModel = 0, ...},
    ['pants']     = {mID = 4, mModel = 15, ...},
    ['shoes']     = {mID = 6, mModel = 5, ...},
    ['tshirt']    = {mID = 8, mModel = 15, ...},
    ['torso']     = {mID = 11, mModel = 15, ...},
    ['hat']       = {mPropID = 0, mPropModel = -1, ...},
    ['glass']     = {mPropID = 1, mPropModel = 0, ...},
    ['watch']     = {mPropID = 6, mPropModel = -1, ...},
    ['bracelet']  = {mPropID = 7, mPropModel = -1, ...},
},

Clothing Item Metadata

For a clothing item to display on the player, it needs these metadata fields:

Body components (mask, pants, shoes, tshirt, torso, etc.):

Metadata	Description
mID / wID	Component ID for male/female
mModel / wModel	Drawable model for male/female
mTexture / wTexture	Texture/color for male/female
mTorso / wTorso	Arm model (only for tshirt and torso)

Prop components (hat, glasses, ears, watch, bracelet):

Metadata	Description
mPropID / wPropID	Prop ID for male/female
mPropModel / wPropModel	Prop drawable for male/female
mPropTexture / wPropTexture	Prop texture for male/female

Testing Clothing Items

Use the /giveitem command with JSON metadata to give yourself a clothing item and test it. The metadata must include the drawable IDs for the item to display on your character.

Body component example (pants for male character — component ID 4, drawable 24, texture 0):

/giveitem me pants 1 {"mID":4,"mModel":24,"mTexture":0,"wID":4,"wModel":24,"wTexture":0}

Torso example (includes arm model to prevent clipping):

/giveitem me torso 1 {"mID":11,"mModel":10,"mTexture":0,"mTorso":5,"wID":11,"wModel":10,"wTexture":0,"wTorso":5}

Prop component example (hat — prop ID 0, drawable 12, texture 0):

/giveitem me hat 1 {"mPropID":0,"mPropModel":12,"mPropTexture":0,"wPropID":0,"wPropModel":12,"wPropTexture":0}

Glasses example:

/giveitem me glass 1 {"mPropID":1,"mPropModel":5,"mPropTexture":0,"wPropID":1,"wPropModel":5,"wPropTexture":0}

INFO

Drawable IDs can be found at the Rage.MP Clothes Wiki. Use mID/wID for body components and mPropID/wPropID for prop components.

TIP

Set DisableClothing = true if you don't use clothing items and don't want the clothing holder slots.

Item Metadata

Items can carry arbitrary metadata for custom functionality. The server/metadata.lua file defines default metadata assigned when items are created:

-- Example: ID card auto-fills with player data
if itemData["name"] == "id_card" then
    info.citizenid = Player.PlayerData.citizenid
    info.firstname = Player.PlayerData.charinfo.firstname
    info.lastname = Player.PlayerData.charinfo.lastname
    info.birthdate = Player.PlayerData.charinfo.birthdate
end

Common Metadata Fields

Field	Used By	Description
ammo	Weapons	Current ammo count
durability	Weapons/tools	Current durability (0-100)
serial	Weapons	Unique serial number
quality	Any item	Rarity tier (common, rare, epic, legendary, import)
uses	Consumables	Remaining uses
firstname / lastname	ID cards	Player identity