Inventory - Item Definition - Mythic Framework

Items in Mythic Framework are defined with properties that control their behavior, appearance, and usage. Understanding the item structure is essential for creating custom items and integrating with the inventory system.

Item Definition Structure

Items are defined in shared/items.lua files across resources:

{
    name = "water",                      -- Unique identifier
    label = "Water Bottle",              -- Display name
    description = "A refreshing bottle of water",
    weight = 0.5,                        -- Weight in kg
    price = 10,                          -- Base price

    -- Type classification (numeric)
    type = 1,                            -- Item type (see type codes below)
    rarity = 1,                          -- Rarity level (0-5)

    -- Usage properties
    isUsable = true,                     -- Can be used from inventory
    isRemoved = true,                    -- Removed from inventory when used
    isStackable = 10,                    -- Stack size (false if not stackable, number for max stack)
    isDestroyed = false,                 -- Completely removed when durability reaches 0

    -- Durability/decay
    durability = 0,                      -- Time in seconds for full degradation (0 = no decay)

    -- UI properties
    closeUi = true,                      -- Close inventory UI after use
    metalic = false,                     -- Item is metallic (affects detection)

    -- State system (optional)
    state = nil,                         -- State key added to character on use (e.g., "WEAPON_EQUIPPED")

    -- Container properties (for container types)
    container = nil                      -- Container identifier if type = 10
}

Required Fields

string

required

Unique item identifierRules:

Lowercase, no spaces
Use underscores for multi-word items
Descriptive and consistent

Examples: "water", "weapon_pistol", "lockpick", "driver_license"

string

required

Display name shown to playersExamples: "Water Bottle", "Pistol", "Lockpick", "Driver's License"

number

required

Item weight in kilogramsGuidelines:

Small items: 0.1 - 0.5 kg
Medium items: 0.5 - 2 kg
Large items: 2 - 10 kg
Very heavy: 10+ kg

Optional Fields

Display Properties

string

Detailed item description shown in tooltipsExample:

description = "A refreshing bottle of water. Restores thirst when consumed."

string

default:"default.png"

Image filename in ui/assets/items/ directoryFormat: PNG, recommended 150x150pxExample: "water.png", "weapon_pistol.png"

Usage Properties

boolean

default:"false"

Whether the item can be used from inventoryExample:

isUsable = true  -- For consumables, tools, etc.
isUsable = false -- For passive items, materials

boolean

default:"false"

Whether the item is removed from inventory when usedNote: This is a client interpretation flag. The actual removal must be implemented in the use code.Example:

isRemoved = true  -- Item consumed on use (food, drinks)
isRemoved = false -- Item stays in inventory (ID cards, tools)

number|boolean

default:"false"

Stack size limit. Use false for non-stackable items, or a number for the maximum stack size.Example:

isStackable = 50   -- Max 50 items per slot
isStackable = false -- Cannot stack (weapons, unique items)

boolean

default:"false"

Whether item is completely removed when durability reaches 0Example:

isDestroyed = true  -- Item deleted when durability = 0
isDestroyed = false -- Item remains but unusable

number

default:"0"

Time in seconds for the item to fully degrade. Set to 0 for no decay.Example:

durability = (60 * 60 * 24)  -- 1 day durability
durability = 0               -- No decay

boolean

default:"false"

Whether to close the inventory UI after using the itemExample:

closeUi = true  -- Close UI after use

boolean

default:"false"

Whether the item is metallic (affects metal detectors, etc.)Example:

metalic = true  -- Weapons, tools
metalic = false -- Food, documents

string

Character state key that is added when item is used and removed when item is lostExample:

state = "WEAPON_EQUIPPED"  -- Adds this state to character

Item Types

The type field uses numeric codes to categorize items:

type = 1   -- Consumable (food, drinks, medical items)
type = 2   -- Weapon (firearms, melee weapons)
type = 3   -- Tool (repair kits, special items)
type = 4   -- Crafting ingredient (materials, resources)
type = 5   -- Collectable (rare items, valuables)
type = 6   -- Junk (trash, low-value items)
type = 7   -- Unknown/Special (drugs, plants)
type = 8   -- Evidence (police evidence items)
type = 9   -- Ammo (ammunition)
type = 10  -- Container (backpacks, bags, storage)
type = 11  -- Gem (precious stones)
type = 12  -- Paraphernalia (drug-related items)
type = 13  -- Wearable (clothing, accessories)
type = 14  -- Contraband (illegal items)
type = 15  -- Gang chain (gang-specific items)
type = 16  -- Weapon attachment (scopes, suppressors)
type = 17  -- Schematic (crafting recipes)

Rarity Levels

The rarity field also uses numeric codes:

rarity = 0  -- Nothing/default
rarity = 1  -- Common (white)
rarity = 2  -- Uncommon (green)
rarity = 3  -- Rare (blue)
rarity = 4  -- Epic (purple)
rarity = 5  -- Labor objective (yellow)

Complete Item Examples

Consumable Item

{
    name = "water",
    label = "Water Bottle",
    description = "A refreshing bottle of water. Restores thirst.",
    weight = 0.5,
    price = 5,
    type = 1,                -- Consumable
    rarity = 1,              -- Common

    isUsable = true,
    isRemoved = true,        -- Consumed when used
    isStackable = 10,        -- Max 10 per slot
    closeUi = false,
    metalic = false
}

Weapon Item

{
    name = "weapon_pistol",
    label = "Pistol",
    description = "A standard 9mm pistol. Reliable and accurate.",
    weight = 1.5,
    price = 5000,
    type = 2,                -- Weapon
    rarity = 2,              -- Uncommon

    isUsable = false,        -- Not directly usable from inventory
    isRemoved = false,
    isStackable = false,     -- Weapons don't stack
    isDestroyed = false,     -- Remains when broken
    closeUi = false,
    metalic = true,          -- Metal detector will detect

    -- Durability in seconds (7 days)
    durability = (60 * 60 * 24 * 7)
}

Note: Weapon-specific properties like ammo, serial numbers, and attachments are stored in item metadata, not in the item definition.

Tool Item

{
    name = "lockpick",
    label = "Lockpick",
    description = "A bent piece of metal used for picking locks. May break on failed attempts.",
    weight = 0.1,
    price = 50,
    type = 3,                -- Tool
    rarity = 1,              -- Common

    isUsable = true,
    isRemoved = false,       -- Not consumed (but can break via code)
    isStackable = 5,         -- Max 5 per slot
    closeUi = true,          -- Close UI when used
    metalic = true
}

Document Item

{
    name = "govid",
    label = "Government ID",
    description = "Official government identification card.",
    weight = 0,              -- Weightless
    price = 0,               -- Not sold
    type = 5,                -- Collectable
    rarity = 1,              -- Common

    isUsable = true,         -- Can view/show
    isRemoved = false,
    isStackable = false,     -- Each ID is unique
    closeUi = true,
    metalic = false
}

Note: Character-specific data like name, DOB, photo are stored in item metadata.

Material Item

{
    name = "steel",
    label = "Steel Bar",
    description = "High-quality steel. Used in crafting and construction.",
    weight = 2.0,
    price = 20,
    type = 4,                -- Crafting ingredient
    rarity = 1,              -- Common

    isUsable = false,        -- Not directly usable
    isRemoved = false,
    isStackable = 100,       -- Max 100 per slot
    closeUi = false,
    metalic = true
}

Phone Item (with Durability)

{
    name = "phone",
    label = "Smartphone",
    description = "A modern smartphone. Access contacts, messages, and apps.",
    weight = 0.2,
    price = 500,
    type = 3,                -- Tool
    rarity = 2,              -- Uncommon

    isUsable = true,
    isRemoved = false,
    isStackable = false,     -- Each phone is unique
    isDestroyed = true,      -- Destroyed when durability reaches 0
    closeUi = true,
    metalic = true,

    -- 30 day durability
    durability = (60 * 60 * 24 * 30)
}

Note: Phone number, contacts, messages, battery, and apps are stored in item metadata.

Item Metadata

Metadata stores instance-specific data for unique or stackable items:

Common Metadata Fields

metadata = {
    -- Weapons
    serial = "ABC123456",
    durability = 95,
    ammo = 10,
    attachments = { "flashlight", "suppressor" },

    -- Consumables
    quality = "excellent",
    expiration = 1705334400,  -- Unix timestamp

    -- Documents
    name = "John Doe",
    dob = "1990-01-15",
    photo = "https://...",
    issued = 1700000000,
    expires = 1800000000,

    -- Vehicles
    plate = "ABC123",
    vin = "1HGBH41JXMN109186",
    fuel = 75,
    mileage = 12500,

    -- Containers
    items = {
        { name = "water", count = 5 },
        { name = "sandwich", count = 3 }
    },

    -- Custom data
    customField = "value",
    owner = 123,
    craftedBy = 456,
    craftedAt = 1705334400
}

Accessing Metadata

-- Get item with metadata
local item = Inventory:GetItemInSlot(char.SID, 1)

if item then
    print('Item:', item.label)
    print('Serial:', item.metadata.serial)
    print('Durability:', item.metadata.durability)
    print('Ammo:', item.metadata.ammo)
end

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

-- Update metadata
local item = Inventory:GetItemInSlot(char.SID, 1)
item.metadata.ammo = 10
item.metadata.durability = 95

Inventory:UpdateSlot(char.SID, 1, item)

Creating Custom Items

Step 1: Define the Item

-- shared/items.lua (in your resource)

Config.Items = {
    ["energy_drink"] = {
        name = "energy_drink",
        label = "Energy Drink",
        description = "Restores energy and gives a temporary speed boost.",
        weight = 0.3,
        type = "consumable",
        image = "energy_drink.png",

        usable = true,
        unique = false,
        stackable = true,
        maxStack = 5,

        sellable = true,
        price = 25
    }
}

Step 2: Register with Items Component

-- server/main.lua

AddEventHandler('Core:Shared:Ready', function()
    for itemName, itemData in pairs(Config.Items) do
        Items:Register(itemName, itemData)
    end
end)

Step 3: Handle Item Usage

-- server/items.lua

AddEventHandler('mythic-inventory:server:ItemUsed', function(source, characterId, itemName, slot, metadata)
    if itemName == 'energy_drink' then
        -- Restore energy
        Characters:UpdateCharacter(characterId, {
            ['metadata.needs.energy'] = 100
        })

        -- Give speed boost
        TriggerClientEvent('mythic-effects:client:SpeedBoost', source, 30000)

        -- Remove item
        Inventory.Items:Remove(characterId, 1, 'energy_drink', 1)

        -- Notify
        TriggerClientEvent('mythic-notifications:client:Send', source, {
            message = 'You feel energized!',
            type = 'success'
        })
    end
end)

Step 4: Add Item Image

Place energy_drink.png (150x150px) in:

mythic-inventory/ui/assets/items/energy_drink.png

Item Categories and Organization

Group related items for easy management:

-- Consumables
local Consumables = {
    ["water"] = { ... },
    ["sandwich"] = { ... },
    ["burger"] = { ... },
    ["cola"] = { ... }
}

-- Weapons
local Weapons = {
    ["weapon_pistol"] = { ... },
    ["weapon_smg"] = { ... },
    ["weapon_rifle"] = { ... }
}

-- Tools
local Tools = {
    ["lockpick"] = { ... },
    ["repairkit"] = { ... },
    ["fishing_rod"] = { ... }
}

-- Combine
Config.Items = {}
for k, v in pairs(Consumables) do Config.Items[k] = v end
for k, v in pairs(Weapons) do Config.Items[k] = v end
for k, v in pairs(Tools) do Config.Items[k] = v end

Best Practices

Consistent Naming

Use a consistent naming scheme:

-- ✅ Good
"water"
"weapon_pistol"
"lockpick"
"driver_license"

-- ❌ Bad
"Water"
"pistolWeapon"
"lock-pick"
"DriversLicense"

Realistic Weights

Balance gameplay with realism:

-- Reference weights
water = 0.5          -- 500ml bottle
sandwich = 0.3       -- Light snack
phone = 0.2          -- Smartphone
weapon_pistol = 1.5  -- Loaded pistol
lockpick = 0.1       -- Small tool
steel = 2.0          -- Metal bar

Clear Descriptions

Write helpful descriptions:

-- ✅ Good
description = "A lockpick made from bent metal. Used to pick locks on doors and vehicles. May break on failed attempts."

-- ❌ Bad
description = "Lockpick"

Appropriate Pricing

Balance economy:

-- Basic consumables: $5-50
price = 10

-- Tools: $50-500
price = 150

-- Weapons: $500-10,000
price = 5000

-- Vehicles: $10,000-1,000,000
price = 50000

Metadata Defaults

Provide sensible defaults:

metadata = {
    durability = 100,  -- Full durability
    quality = "good",  // Default quality
    ammo = 12,         -- Full magazine
    fuel = 100         -- Full tank
}

Item Validation

Validate items before adding to inventory:

function ValidateItem(itemName)
    local item = Items:Get(itemName)

    if not item then
        return false, 'Item does not exist'
    end

    if not item.name or item.name == '' then
        return false, 'Invalid item name'
    end

    if not item.label or item.label == '' then
        return false, 'Invalid item label'
    end

    if not item.weight or item.weight < 0 then
        return false, 'Invalid item weight'
    end

    return true
end

-- Use in add item
function SafeAddItem(characterId, itemName, count)
    local valid, error = ValidateItem(itemName)

    if not valid then
        return false, error
    end

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

Next Steps

Inventory - Exports

Inventory management methods

Inventory - Events

Inventory events

Items System

Using and creating items

Crafting System

Item crafting and recipes

Item Images: Use consistent image sizes (150x150px recommended) and transparent backgrounds (PNG) for best results in the inventory UI.

​Item Definition Structure

​Required Fields

​Optional Fields

​Display Properties

​Usage Properties

​Item Types

​Rarity Levels

​Complete Item Examples

​Consumable Item

​Weapon Item

​Tool Item

​Document Item

​Material Item

​Phone Item (with Durability)

​Item Metadata

​Common Metadata Fields

​Accessing Metadata

​Creating Custom Items

​Step 1: Define the Item

​Step 2: Register with Items Component

​Step 3: Handle Item Usage

​Step 4: Add Item Image

​Item Categories and Organization

​Best Practices

​Item Validation

​Next Steps

Inventory - Exports

Inventory - Events

Items System

Crafting System

Item Definition Structure

Required Fields

Optional Fields

Display Properties

Usage Properties

Item Types

Rarity Levels

Complete Item Examples

Consumable Item

Weapon Item

Tool Item

Document Item

Material Item

Phone Item (with Durability)

Item Metadata

Common Metadata Fields

Accessing Metadata

Creating Custom Items

Step 1: Define the Item

Step 2: Register with Items Component

Step 3: Handle Item Usage

Step 4: Add Item Image

Item Categories and Organization

Best Practices

Item Validation

Next Steps