Inventory - Item Definition

Item data structure, metadata, and item configuration

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

name · string · required

Unique item identifier

Rules:

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

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

label · string · required

Display name shown to players

Examples: "Water Bottle", "Pistol", "Lockpick", "Driver's License"

weight · number · required

Item weight in kilograms

Guidelines:

• 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

description · string

Detailed item description shown in tooltips

Example:

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

image · string · default: "default.png"

Image filename in ui/assets/items/ directory

Format: PNG, recommended 150x150px

Example: "water.png", "weapon_pistol.png"

Usage Properties

isUsable · boolean · default: "false"

Whether the item can be used from inventory

Example:

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

isRemoved · boolean · default: "false"

Whether the item is removed from inventory when used

Note: 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)

isStackable · 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)

isDestroyed · boolean · default: "false"

Whether item is completely removed when durability reaches 0

Example:

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

durability · 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

closeUi · boolean · default: "false"

Whether to close the inventory UI after using the item

Example:

closeUi = true  -- Close UI after use

metalic · boolean · default: "false"

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

Example:

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

state · string

Character state key that is added when item is used and removed when item is lost

Example:

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 = COMPONENTS.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
COMPONENTS.Inventory:AddItem(char.SID, 'weapon_pistol', 1, {
    serial = GenerateSerial(),
    durability = 100,
    ammo = 12,
    attachments = {}
})

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

COMPONENTS.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
        COMPONENTS.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
        COMPONENTS.Characters:UpdateCharacter(characterId, {
            ['metadata.needs.energy'] = 100
        })

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

        -- Remove item
        COMPONENTS.Inventory:RemoveItem(characterId, slot, 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 = COMPONENTS.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 COMPONENTS.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.