> ## Documentation Index
> Fetch the complete documentation index at: https://mythicframework.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```lua theme={null}
{
    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

<ParamField path="name" type="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"`
</ParamField>

<ParamField path="label" type="string" required>
  Display name shown to players

  **Examples:** `"Water Bottle"`, `"Pistol"`, `"Lockpick"`, `"Driver's License"`
</ParamField>

<ParamField path="weight" type="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
</ParamField>

***

## Optional Fields

### Display Properties

<ParamField path="description" type="string" optional>
  Detailed item description shown in tooltips

  **Example:**

  ```lua theme={null}
  description = "A refreshing bottle of water. Restores thirst when consumed."
  ```
</ParamField>

<ParamField path="image" type="string" optional default="default.png">
  Image filename in `ui/assets/items/` directory

  **Format:** PNG, recommended 150x150px

  **Example:** `"water.png"`, `"weapon_pistol.png"`
</ParamField>

### Usage Properties

<ParamField path="isUsable" type="boolean" optional default="false">
  Whether the item can be used from inventory

  **Example:**

  ```lua theme={null}
  isUsable = true  -- For consumables, tools, etc.
  isUsable = false -- For passive items, materials
  ```
</ParamField>

<ParamField path="isRemoved" type="boolean" optional 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:**

  ```lua theme={null}
  isRemoved = true  -- Item consumed on use (food, drinks)
  isRemoved = false -- Item stays in inventory (ID cards, tools)
  ```
</ParamField>

<ParamField path="isStackable" type="number|boolean" optional default="false">
  Stack size limit. Use `false` for non-stackable items, or a number for the maximum stack size.

  **Example:**

  ```lua theme={null}
  isStackable = 50   -- Max 50 items per slot
  isStackable = false -- Cannot stack (weapons, unique items)
  ```
</ParamField>

<ParamField path="isDestroyed" type="boolean" optional default="false">
  Whether item is completely removed when durability reaches 0

  **Example:**

  ```lua theme={null}
  isDestroyed = true  -- Item deleted when durability = 0
  isDestroyed = false -- Item remains but unusable
  ```
</ParamField>

<ParamField path="durability" type="number" optional default="0">
  Time in seconds for the item to fully degrade. Set to `0` for no decay.

  **Example:**

  ```lua theme={null}
  durability = (60 * 60 * 24)  -- 1 day durability
  durability = 0               -- No decay
  ```
</ParamField>

<ParamField path="closeUi" type="boolean" optional default="false">
  Whether to close the inventory UI after using the item

  **Example:**

  ```lua theme={null}
  closeUi = true  -- Close UI after use
  ```
</ParamField>

<ParamField path="metalic" type="boolean" optional default="false">
  Whether the item is metallic (affects metal detectors, etc.)

  **Example:**

  ```lua theme={null}
  metalic = true  -- Weapons, tools
  metalic = false -- Food, documents
  ```
</ParamField>

<ParamField path="state" type="string" optional>
  Character state key that is added when item is used and removed when item is lost

  **Example:**

  ```lua theme={null}
  state = "WEAPON_EQUIPPED"  -- Adds this state to character
  ```
</ParamField>

***

## Item Types

The `type` field uses **numeric codes** to categorize items:

```lua theme={null}
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:

```lua theme={null}
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

```lua theme={null}
{
    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

```lua theme={null}
{
    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

```lua theme={null}
{
    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

```lua theme={null}
{
    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

```lua theme={null}
{
    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)

```lua theme={null}
{
    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

```lua theme={null}
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

```lua theme={null}
-- 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

```lua theme={null}
-- 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

```lua theme={null}
-- 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

```lua theme={null}
-- 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:

```lua theme={null}
-- 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

<AccordionGroup>
  <Accordion title="Consistent Naming" icon="signature">
    **Use a consistent naming scheme:**

    ```lua theme={null}
    -- ✅ Good
    "water"
    "weapon_pistol"
    "lockpick"
    "driver_license"

    -- ❌ Bad
    "Water"
    "pistolWeapon"
    "lock-pick"
    "DriversLicense"
    ```
  </Accordion>

  <Accordion title="Realistic Weights" icon="weight-scale">
    **Balance gameplay with realism:**

    ```lua theme={null}
    -- 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
    ```
  </Accordion>

  <Accordion title="Clear Descriptions" icon="file-alt">
    **Write helpful descriptions:**

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

    -- ❌ Bad
    description = "Lockpick"
    ```
  </Accordion>

  <Accordion title="Appropriate Pricing" icon="dollar-sign">
    **Balance economy:**

    ```lua theme={null}
    -- 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
    ```
  </Accordion>

  <Accordion title="Metadata Defaults" icon="brackets-curly">
    **Provide sensible defaults:**

    ```lua theme={null}
    metadata = {
        durability = 100,  -- Full durability
        quality = "good",  // Default quality
        ammo = 12,         -- Full magazine
        fuel = 100         -- Full tank
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Item Validation

Validate items before adding to inventory:

```lua theme={null}
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

<CardGroup cols={2}>
  <Card title="Inventory - Exports" icon="cube" href="/api/inventory/exports">
    Inventory management methods
  </Card>

  <Card title="Inventory - Events" icon="bolt" href="/api/inventory/events">
    Inventory events
  </Card>

  <Card title="Items System" icon="box" href="/features/inventory/items">
    Using and creating items
  </Card>

  <Card title="Crafting System" icon="hammer" href="/features/inventory/crafting">
    Item crafting and recipes
  </Card>
</CardGroup>

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