# Creating Items

Items are defined via a shared `item_list` table, stored in `data/items.lua`. \
Each item is fully data-driven and supports data, actions, props, degradation, attachments, and more.

Below are fully built examples covering the major item types:

***

{% hint style="warning" %}
Statuses support is coming very soon please bare rebuilding another system currently, once complete a `modifiers.statuses = {}` section will be added. 
{% endhint %}

## Consumable Items

A stackable consumable item with an animation and prop attachment.

```lua
water = {
    id = "water",
    label = "Water",
    description = { "A refreshing bottle of clean water.." },
    image = "water.png",
    stackable = 10,
    data = {
        rarity = "common",
        degrade_rate = 0.25,
        quality = 100
    },
    actions = {
        use = {
            animation = {
                progress = {
                    type = "circle",
                    message = "Drinking Water..",
                    segments = 30,
                    gap = 3
                },
                dict = "mp_player_intdrink",
                anim = "loop_bottle",
                flags = 49,
                duration = 5000,
                freeze = false,
                continuous = false,
                props = {
                    {
                        model = "ba_prop_club_water_bottle",
                        bone = 60309,
                        coords = { x = 0.0, y = 0.0, z = -0.05 },
                        rotation = { x = 0.0, y = 0.0, z = 0.0 },
                        is_ped = true,
                        sync_rot = true
                    }
                },
                callback = function(_src, slot)
                    TriggerEvent("list_inventory:sv:remove_item", _src, slot)
                end
            }
        },
        drop = true
    }
}
```

***

## Ammo Items

Ammo items store bullet count and are used to reload compatible weapons.

```lua
ammo_pistol = {
    id = "ammo_pistol",
    label = "Pistol Ammo",
    description = { "A clip of pistol ammo" },
    image = "ammo_pistol.png",
    data = {
        rarity = "common",
        ammo_count = 12
    },
    actions = {
        use = function(source, slot, id, def)
            add_ammo_to_weapon(source, slot, id, def)
        end,
        drop = true
    }
}
```

***

## Weapons

Weapons track serials, ammo, durability, and can be modified with attachments.\
Serials are automatically assigned to weapons if one does not already exist.

```lua
weapon_pistol = {
    id = "weapon_pistol",
    label = "Pistol",
    description = {
        "A standard semi-automatic 9mm handgun.",
        "Can be purchased from any ammunation."
    },
    image = "weapon_pistol.png",
    data = {
        rarity = "common",
        serial = "", -- assigned on add_item
        ammo = 0,
        ammo_types = { "ammo_pistol" },
        attachments = {},
        degrade_rate = 0.25,
        durability = 100
    },
    actions = {
        use = function(source, slot, id, def)
            use_weapon(source, slot, id, def)
        end,
        modify = true,
        drop = true
    }
}
```

***

## Weapon Attachments

Attachments use `modifiers.attachments` to define compatibility with weapons and GTA components.

```lua
pistol_mag_extended = {
    id = "pistol_mag_extended",
    label = "Extended Mag: Pistol",
    description = { "Extended magazine for supported 9mm pistols." },
    image = "pistol_mag_extended.png",
    data = {
        rarity = "rare"
    },
    modifiers = {
        attachments = {
            { weapon = "weapon_pistol", component = "COMPONENT_PISTOL_CLIP_02" },
            { weapon = "weapon_heavypistol", component = "COMPONENT_HEAVYPISTOL_CLIP_02" }
        }
    },
    actions = {
        drop = true
    }
}
```

***

## Notes

* Use `data` to define any item-specific metadata (quality, ammo, serials, etc.)
* `actions.use` supports either a full animation table or a function
* Use `modify = true` on weapon actions to enable the modification UI
* Attachments are matched to weapons using `modifiers.attachments`
* Avoid mixing `quality` and `durability` in a single item (visual conflict)
* Clothing as items & consumables status modifying coming **very soon**

This structure supports **deep customization** with minimal boilerplate. New item types can be added by following these patterns.

Want to define a new item? Just copy one of these and tweak the fields.