Item functionalities

If you need assistance, please reach out to a developer, as the setup for "Basic Item Declaration" is designed to be straightforward. However, if any difficulties arise, it’s best to consult a trusted developer to ensure a smooth integration.

To correctly set up items in qs-inventory, follow these instructions and examples. Note that this file is compatible with ESX. If using QBCore, move this file to qb-core/shared and rename the main function accordingly.

The items will be added in different locations depending on whether you are using QBCore or ESX. Please navigate to the recommended directory for your framework and then follow the guidelines provided below.

1

Items for ESX

Items are located in qs-inventory/shared/items.lua.

2

Items for QBCore

Items should be added in qb-core/shared/items.lua.

---

Basic Item Declaration

Each item has essential properties that determine its behavior. Here are the primary fields for setup:

• name: Unique ID for the item.

• label: Display name in the inventory.

• weight: Weight of the item in kg.

• type: Item type (item or weapon).

• image: Name of the image file in html/images/.

• unique: true if the item is non-stackable; false if it can stack.

• useable: true if the item can be used.

• shouldClose: true if the inventory should close when the item is used.

• description: Short description of the item.

Example:

['water_bottle'] = {
    name = 'water_bottle',
    label = 'Water Bottle',
    weight = 500,
    type = 'item',
    image = 'water_bottle.png',
    unique = false,
    useable = true,
    shouldClose = true,
    description = 'A refreshing bottle of water.'
}

---

Decay (Wear and Tear)

Certain items degrade with use.

• decay: Sets the rate of wear. The higher the value, the faster it wears out.

• delete: true to remove the item when it breaks.

Wear and Tear Example:

['lockpick'] = {
    name = 'lockpick',
    label = 'Lockpick',
    weight = 150,
    type = 'item',
    image = 'lockpick.png',
    unique = true,
    useable = true,
    decay = 10,
    delete = true,
    description = 'A lockpick used for opening locked doors or vehicles.'
}

---

Visible Object

If you don't have an item set, it will show a simple bag.

This will set a specific prop, when giving the item, throwing it or doing throw, this item will be seen in the game. You can configure an item to be thrown as an object.

• object: Model of the object that will be thrown.

Throwable Object Example:

['snowball'] = {
    name = 'snowball',
    label = 'Snowball',
    weight = 100,
    type = 'item',
    image = 'snowball.png',
    unique = false,
    useable = true,
    object = 'prop_snowball_01',
    description = 'A snowball to throw at your friends!'
}

---

Item Rarity

The rarity of an item changes the color of the item in the inventory.

• rare: Sets the item rarity (common, epic, legendary), which only affects the color of the item in the inventory.

Rarity Example:

['gold_chain'] = {
    name = 'gold_chain',
    label = 'Gold Chain',
    weight = 300,
    type = 'item',
    image = 'gold_chain.png',
    unique = true,
    useable = false,
    rare = 'epic',
    description = 'A valuable gold chain.'
}

---

Object with export

We can add a client export as follows.

• export: Sets an export as usability.

Export Example:

['security_card_02'] = {
    name = 'security_card_02',
    label = 'Security Card B',
    weight = 5,
    type = 'item',
    image = 'security_card_02.png',
    unique = true,
    useable = true,
    description = 'A security card... I wonder what it goes to',
    client = {
        export = 'qs-inventory.test'
    },
}

Internal Export Example:

exports('test', function(item, meta)
    print('item', json.encode(item))
    print('meta', json.encode(meta))
end)

---

Consumables

Please if you are not an experienced programmer, just skip this step and continue adding your consumable items in esx_basicneeds or qb-smallresources.

For this to work in esx we must have esx_status and esx_basicneeds.

Consumable items can affect thirst or hunger and may include animations, visible objects, and movement restrictions.

• thirst/hunger: Defines whether it affects thirst or hunger.

• usetime: Duration of use in ms.

• anim: Animation dictionary and clip.

• prop: Model and coordinates of the object during the animation.

• disable: Disables events (movement, combat, etc.).

• removeAfterUse: true deletes the item after use.

Consumable Example:

['sandwich'] = {
    name = 'sandwich',
    label = 'Sandwich',
    weight = 200,
    type = 'item',
    image = 'sandwich.png',
    unique = false,
    useable = true,
    shouldClose = true,
    client = {
        status = {
            hunger = 200000,
        },
        usetime = 2500,
        anim = {
            dict = 'mp_player_inteat@burger',
            clip = 'mp_player_int_eat_burger_fp'
        },
        prop = {
            model = 'prop_cs_burger_01',
            pos = vec3(0.02, 0.02, -0.02),
            rot = vec3(0.0, 0.0, 0.0)
        },
        disable = {
            move = true,
            car = true,
            mouse = false,
            combat = true,
        },
        removeAfterUse = true
    }
    description = 'A delicious sandwich to satisfy your hunger.'
}