Inventory

The Inventory component manages character inventories, item storage, weights, and item operations. It’s one of the most complex and frequently used components in Mythic Framework.

Overview

Access via Inventory (server-side only).

Slot-Based System

Grid inventory with configurable slot count

Weight Management

Item weight and max capacity limits

Item Metadata

Custom data per item instance

Multiple Inventories

Character, vehicle, stash, shop inventories

Server-Side Only: All inventory operations must be performed on the server. Never attempt to modify inventory from the client.

Inventory Management

Items:GetCounts

Get item counts for an inventory.

Inventory.Items:GetCounts(owner, invType)

owner

number

required

Owner identifier (Character SID for personal inventory)

invType

number

required

Inventory type (1 = personal, other values for stashes/vehicles)

counts

table

Table of item name → count pairs

Examples:

-- Get all item counts for a character
local counts = Inventory.Items:GetCounts(char:GetData('SID'), 1)

for itemName, count in pairs(counts) do
    print(itemName, ':', count)
end

Create

Create a new inventory for a character.

Inventory:Create(characterId, maxSlots, maxWeight)

characterId

number

required

Character SID

maxSlots

number

default:"50"

Maximum number of inventory slots

maxWeight

number

default:"100"

Maximum weight capacity

Examples:

-- Create default inventory
Inventory:Create(char.SID)

-- Create with custom limits
Inventory:Create(char.SID, 75, 150)

-- Create inventory on character creation
AddEventHandler('mythic-characters:server:CharacterCreated', function(source, character)
    Inventory:Create(character.SID, 50, 100)

    -- Give starter items
    Inventory:AddItem(character.SID, 'phone', 1)
    Inventory:AddItem(character.SID, 'water', 2)
end)

Delete

Delete an inventory permanently.

Inventory:Delete(characterId)

characterId

number

required

Character SID

Examples:

-- Delete inventory
Inventory:Delete(char.SID)

-- Delete on character deletion
AddEventHandler('mythic-characters:server:CharacterDeleted', function(source, characterId)
    Inventory:Delete(characterId)
end)

Item Operations

AddItem

Add an item to an inventory.

Inventory:AddItem(owner, itemName, count, metadata, invType)

owner

number

required

Owner identifier (Character SID for personal inventory)

itemName

string

required

Item identifier (e.g., ‘water’, ‘phone’, ‘weapon_pistol’)

count

number

default:"1"

Quantity to add

metadata

table

Custom item metadata (serial number, durability, etc.)

invType

number

default:"1"

Inventory type (1 = personal)

success

boolean

true if item was added successfully

slot

number|nil

Slot where item was added, or nil if failed

Examples:

-- Add single item
local success, slot = Inventory:AddItem(char.SID, 'water', 1)

if success then
    print('Added water to slot', slot)
else
    print('Failed to add item (inventory full or no space)')
end

-- Add multiple items
Inventory:AddItem(char.SID, 'sandwich', 5)

-- Add with metadata
Inventory:AddItem(char.SID, 'weapon_pistol', 1, {
    serial = 'ABC123456',
    durability = 100,
    ammo = 12
})

-- Add to specific slot
Inventory:AddItem(char.SID, 'phone', 1, {
    number = char.Phone
}, 1)  -- Always in slot 1

-- Add item with validation
function GiveItemToPlayer(source, itemName, count)
    local player = Fetch:Source(source)

    if not player then
        return false, 'Player not found'
    end

    local char = player:GetData('Character')

    if not char then
        return false, 'No character'
    end

    -- Check if item exists
    local itemData = Items:Get(itemName)
    if not itemData then
        return false, 'Invalid item'
    end

    -- Add item
    local stateId = char:GetData('SID')
    local success, slot = Inventory:AddItem(stateId, itemName, count)

    if success then
        -- Notify player
        TriggerClientEvent('mythic-notifications:client:Send', source, {
            message = 'Received ' .. count .. 'x ' .. itemData.label,
            type = 'success'
        })

        return true, slot
    else
        TriggerClientEvent('mythic-notifications:client:Send', source, {
            message = 'Inventory full',
            type = 'error'
        })

        return false, 'Inventory full'
    end
end

Items:Remove

Remove an item from an inventory by item name.

Inventory.Items:Remove(owner, invType, itemName, count)

owner

number

required

Owner identifier (Character SID for personal inventory)

invType

number

required

Inventory type (1 = personal)

itemName

string

required

Item identifier to remove

count

number

default:"1"

Quantity to remove

Examples:

-- Remove single item by name
Inventory.Items:Remove(char:GetData('SID'), 1, 'water', 1)

-- Remove multiple
Inventory.Items:Remove(char:GetData('SID'), 1, 'lockpick', 3)

-- Remove with validation
local stateId = char:GetData('SID')
if Inventory.Items:Has(stateId, 1, 'lockpick', 1) then
    Inventory.Items:Remove(stateId, 1, 'lockpick', 1)
    Notification:Success(source, 'Used lockpick')
else
    Notification:Error(source, 'No lockpick found')
end

Items:Has

Check if an inventory has a specific item in sufficient quantity.

Inventory.Items:Has(owner, invType, itemName, count)

owner

number

required

Owner identifier (Character SID for personal inventory)

invType

number

required

Inventory type (1 = personal)

itemName

string

required

Item identifier

count

number

default:"1"

Required quantity

hasItem

boolean

true if inventory has the item in sufficient quantity

Examples:

-- Check if has item
local stateId = char:GetData('SID')

if Inventory.Items:Has(stateId, 1, 'water', 1) then
    print('Has water')
else
    print('No water')
end

-- Require item for action
function CanCraftItem(stateId, recipe)
    for _, ingredient in ipairs(recipe.ingredients) do
        if not Inventory.Items:Has(stateId, 1, ingredient.item, ingredient.count) then
            return false, 'Missing ' .. ingredient.item
        end
    end
    return true
end

-- Consume items for crafting
function CraftItem(source, recipeId)
    local player = Fetch:Source(source)
    if not player then return false end

    local char = player:GetData('Character')
    if not char then return false end

    local stateId = char:GetData('SID')
    local recipe = Recipes[recipeId]

    -- Check has ingredients
    local canCraft, error = CanCraftItem(stateId, recipe)
    if not canCraft then return false, error end

    -- Remove ingredients
    for _, ingredient in ipairs(recipe.ingredients) do
        Inventory.Items:Remove(stateId, 1, ingredient.item, ingredient.count)
    end

    -- Give crafted item
    Inventory:AddItem(stateId, recipe.result, 1)
    return true
end

Items:GetCount

Get the count of a specific item in an inventory.

Inventory.Items:GetCount(owner, invType, itemName)

owner

number

required

Owner identifier

invType

number

required

Inventory type (1 = personal)

itemName

string

required

Item identifier

count

number

Total count of the item across all slots

Examples:

local stateId = char:GetData('SID')
local waterCount = Inventory.Items:GetCount(stateId, 1, 'water')
print('Has', waterCount, 'water')

GetItemInSlot

Get the item in a specific slot.

Inventory:GetItemInSlot(characterId, slot)

characterId

number

required

Character SID

slot

number

required

Slot number

item

table|nil

Item data or nil if slot is empty

Examples:

-- Get item in slot
local item = Inventory:GetItemInSlot(char.SID, 1)

if item then
    print('Slot 1 contains:', item.label)
    print('Count:', item.count)
    print('Weight:', item.weight)
else
    print('Slot 1 is empty')
end

-- Use item callback
Callbacks:RegisterServerCallback('inventory:useItem', function(source, data, cb)
    local player = Fetch:Source(source)

    if not player then
        return cb(false, 'Player not found')
    end

    local char = player:GetData('Character')

    if not char then
        return cb(false, 'No character')
    end

    local stateId = char:GetData('SID')
    local item = Inventory:GetItemInSlot(stateId, data.slot)

    if not item then
        return cb(false, 'No item in slot')
    end

    -- Use item
    local success = Items:Use(source, item)

    cb(success)
end)

MoveItem

Move an item from one slot to another.

Inventory:MoveItem(characterId, fromSlot, toSlot, count)

characterId

number

required

Character SID

fromSlot

number

required

Source slot

toSlot

number

required

Destination slot

count

number

Amount to move (moves all if not specified)

Examples:

-- Move entire stack
Inventory:MoveItem(char.SID, 1, 5)

-- Move partial stack
Inventory:MoveItem(char.SID, 1, 5, 3)  -- Move 3 items from slot 1 to slot 5

-- Swap items
Inventory:MoveItem(char.SID, 1, 2)  -- Swaps items in slots 1 and 2

Weight Management

GetWeight

Get the current weight of an inventory.

Inventory:GetWeight(characterId)

characterId

number

required

Character SID

currentWeight

number

Total weight of all items in inventory

Examples:

-- Get current weight
local weight = Inventory:GetWeight(char.SID)

print('Current weight:', weight, 'kg')

-- Check before adding item
function CanAddItem(characterId, itemName, count)
    local currentWeight = Inventory:GetWeight(characterId)
    local itemData = Items:Get(itemName)

    local additionalWeight = itemData.weight * count

    if currentWeight + additionalWeight > inventory.maxWeight then
        return false, 'Too heavy'
    end

    -- Check slot availability
    local emptySlots = Inventory:GetEmptySlots(characterId)

    if #emptySlots == 0 and not CanStack(characterId, itemName) then
        return false, 'No empty slots'
    end

    return true
end

GetEmptySlots

Get all empty slots in an inventory.

Inventory:GetEmptySlots(characterId)

characterId

number

required

Character SID

emptySlots

table

Array of empty slot numbers

Examples:

-- Get empty slots
local emptySlots = Inventory:GetEmptySlots(char.SID)

print('Empty slots:', #emptySlots)

for _, slot in ipairs(emptySlots) do
    print('Slot', slot, 'is empty')
end

-- Check if full
if #emptySlots == 0 then
    print('Inventory is full')
end

Item Search

Items:GetFirst

Get the first instance of an item in an inventory.

Inventory.Items:GetFirst(owner, invType, itemName)

owner

number

required

Owner identifier

invType

number

required

Inventory type (1 = personal)

itemName

string

required

Item identifier

item

table|nil

First item instance found, or nil if not found

Examples:

-- Find first instance of an item
local stateId = char:GetData('SID')
local item = Inventory.Items:GetFirst(stateId, 1, 'lockpick')

if item then
    print('Found lockpick')
else
    print('No lockpick found')
end

Items:GetAll

Get all instances of an item in an inventory.

Inventory.Items:GetAll(owner, invType, itemName)

owner

number

required

Owner identifier

invType

number

required

Inventory type (1 = personal)

itemName

string

required

Item identifier

items

table

Array of all item instances found

Examples:

-- Find all instances of an item
local stateId = char:GetData('SID')
local items = Inventory.Items:GetAll(stateId, 1, 'water')

print('Found', #items, 'water stacks')

Items:Use

Use an item in a specific slot.

Inventory.Items:Use(owner, invType, slot)

owner

number

required

Owner identifier

invType

number

required

Inventory type (1 = personal)

slot

number

required

Slot number of item to use

Examples:

-- Use item in slot 1
Inventory.Items:Use(char:GetData('SID'), 1, 1)

Best Practices

Always Validate Before Operations

❌ Bad:

-- Assume operation succeeds
Inventory:AddItem(char.SID, 'water', 1)
print('Item added')  -- Maybe not!

✅ Good:

local success, slot = Inventory:AddItem(char.SID, 'water', 1)

if success then
    print('Item added to slot', slot)
    -- Notify player
    TriggerClientEvent('notify', source, 'Item added')
else
    print('Failed to add item')
    TriggerClientEvent('notify', source, 'Inventory full')
end

Check Weight Before Adding

function SafeAddItem(characterId, itemName, count)
    local canAdd, error = CanAddItem(characterId, itemName, count)

    if not canAdd then
        return false, error
    end

    return Inventory:AddItem(characterId, itemName, count)
end

Use Metadata for Unique Items

-- Weapons with serial numbers
Inventory:AddItem(char.SID, 'weapon_pistol', 1, {
    serial = GenerateSerial(),
    durability = 100,
    ammo = 12,
    attachments = { 'flashlight', 'suppressor' }
})

-- Phones with numbers
Inventory:AddItem(char.SID, 'phone', 1, {
    number = char.Phone,
    contacts = {},
    messages = {}
})

-- ID cards
Inventory:AddItem(char.SID, 'id_card', 1, {
    name = char.First .. ' ' .. char.Last,
    dob = char.DOB,
    photo = 'url_to_photo'
})

Clean Up on Character Delete

AddEventHandler('mythic-characters:server:CharacterDeleted', function(source, characterId)
    Inventory:Delete(characterId)
end)

Sync Inventory to Client

-- After inventory changes, update client
function UpdateInventoryUI(source)
    local player = Fetch:Source(source)

    if not player then return end

    local char = player:GetData('Character')

    if not char then return end

    local stateId = char:GetData('SID')
    -- The inventory UI is automatically synced by the Inventory component
end

-- Call after add/remove
local stateId = char:GetData('SID')
Inventory:AddItem(stateId, 'water', 1)
UpdateInventoryUI(source)

Next Steps

Inventory - Events

Inventory-related events

Inventory - Item Definition

Item data structure and definitions

Characters API

Character management

Items System

Using and creating items

Performance Tip: Inventory operations update the database. For bulk operations (giving many items at once), consider batching updates or using transactions where possible.

Mythic Components API

Characters

Jobs

Vehicles

HUD & Status

Finance

Phone

Doors

Status

Chat

Admin

​Overview

Slot-Based System

Weight Management

Item Metadata

Multiple Inventories

​Inventory Management

​Items:GetCounts

​Create

​Delete

​Item Operations

​AddItem

​Items:Remove

​Items:Has

​Items:GetCount

​GetItemInSlot

​MoveItem

​Weight Management

​GetWeight

​GetEmptySlots

​Item Search

​Items:GetFirst

​Items:GetAll

​Items:Use

​Best Practices

​Next Steps

Inventory - Events

Inventory - Item Definition

Characters API

Items System

Overview

Inventory Management

Items:GetCounts

Create

Delete

Item Operations

AddItem

Items:Remove

Items:Has

Items:GetCount

GetItemInSlot

MoveItem

Weight Management

GetWeight

GetEmptySlots

Item Search

Items:GetFirst

Items:GetAll

Items:Use

Best Practices

Next Steps