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:

---

Statuses support is coming very soon please bare rebuilding another system currently, once complete a modifiers.statuses = {} section will be added.

Consumable Items

A stackable consumable item with an animation and prop attachment.

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.

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.

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.

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.