Adding Items

Guide for Adding Items

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.

This configuration works in both qb-core/shared/items.lua for QBCore and qs-inventory/shared/items.lua for ESX (the latter only applies to ESX setups). You can use these examples and combine various features—such as rarities, consumables, props, and item animations—to create custom items tailored to your server’s needs. By mixing these options, you can design unique, functional items that enhance player experience and gameplay dynamics.

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.'
}

Complete Examples

Items such as "tosti" and "water_bottle" serve as basic examples that include all the properties and functionalities discussed here. Use these examples along with the above guidelines to customize and adapt the items.lua file to fit your requirements.

Last updated 1 month ago