Item Configuration

Basic Item Structure

Every item is defined using a set of core properties that determine how it behaves in the inventory. These include the item identifier, the name shown to players, its weight, type (item or weapon), image, and whether it can stack or be used. You can also define if the inventory should close when the item is used and add a short description. These fields form the base configuration that every item should have before adding advanced behavior.

lua

['water_bottle'] = {
    name = 'water_bottle',        -- Unique ID used internally by the inventory
    label = 'Water Bottle',       -- Name shown to players
    weight = 500,                 -- Weight of the item
    type = 'item',                -- Type: item or weapon
    image = 'water_bottle.png',   -- Image located in html/images/
    unique = false,               -- Can stack with other items
    useable = true,               -- Player can use this item
    shouldClose = true,           -- Inventory closes when used
    description = 'A refreshing bottle of water.'
}

Item Configuration | Quasar Store

Durability and Item Decay

Some items can wear out after repeated use. This behavior is controlled through the decay and delete properties. The decay value determines how fast the item deteriorates, while the delete property decides if the item should be removed once its durability reaches zero.

lua

['lockpick'] = {
    name = 'lockpick',
    label = 'Lockpick',
    weight = 150,
    type = 'item',
    image = 'lockpick.png',
    unique = true,
    useable = true,
    decay = 10,        -- Higher value = faster durability loss
    delete = true,     -- Item is removed when it breaks
    description = 'A lockpick used for opening locked doors or vehicles.'
}

World Objects and Throwable Items

Items can also have a physical object assigned so they appear in the world when dropped or thrown. This is defined using the object property, which links the item to a GTA prop model. If an item has an object assigned, it can usually be thrown unless the throw behavior is disabled.

lua

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

Item Rarity

Items can be visually categorized using a rarity system. The rare field only affects how the item appears in the inventory by changing its color. This is useful for highlighting valuable items such as rare loot or special equipment.

lua

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

Job Restrictions

You can restrict items so that only certain jobs can use them. This is configured using the job field, which accepts one or multiple job names. It is commonly used for police equipment, medical tools, or job-exclusive gear.

lua

['radar_gun'] = {
    name = 'radar_gun',
    label = 'Radar Gun',
    weight = 1000,
    type = 'item',
    image = 'radar_gun.png',
    unique = true,
    useable = true,
    object = 'prop_radar_gun_01',
    job = { 'police' }, -- Only police can use or receive this item
    description = 'A device used by police to measure vehicle speed.'
}

Item Exports and Custom Logic

Items can trigger custom client logic when used by linking them to an export. This allows developers to attach their own scripts or features to the item usage system.

lua

['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' -- Calls a custom export
    },
}

Internal export example:

lua

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

Consumable Items (Food and Drinks)

Consumables are items that affect player needs such as hunger or thirst. They can include animations, props, usage duration, and movement restrictions during consumption.

lua

['tosti'] = {
    name = 'tosti',
    label = 'Grilled Cheese Sandwich',
    weight = 200,
    type = 'item',
    image = 'tosti.png',
    unique = false,
    useable = true,
    shouldClose = true,
    description = 'Nice to eat',
    decay = 0.07,
    delete = false,
    object = 'prop_sandwich_01',
    client = {
        status = {
            hunger = 200000 -- Restores hunger
        },
        usetime = 2500, -- Time required to consume
        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),
            bone = 60309
        },
        disable = {
            move = true,
            car = true,
            mouse = false,
            combat = true
        },
        removeAfterUse = true -- Item removed after consumption
    }
}

You can attach more than one prop to an item during its animation. This is useful for more complex actions such as eating with utensils or holding multiple objects.

lua

prop = {
    {
        model = 'prop_cs_burger_01',
        pos = vec3(0.02, 0.02, -0.02),
        rot = vec3(0.0, 0.0, 0.0)
    },
    {
        model = 'prop_cs_burger_01',
        pos = vec3(0.1, 0.02, -0.02),
        rot = vec3(0.0, 0.0, 0.0)
    }
}

Preventing Items From Being Thrown

If an item has a prop but should not be throwable, you can disable that behavior using disableThrow.

lua

['brick'] = {
    name = 'brick',
    label = 'Brick',
    weight = 500,
    type = 'item',
    image = 'brick.png',
    unique = false,
    useable = true,
    object = 'prop_brick_01',
    disableThrow = true, -- Prevents throwing the item
    description = 'A heavy brick. Probably not safe to throw.'
}

Usage Location Restrictions

Items can be restricted to specific sections of the inventory using useableIn. This ensures certain items only work from the hotbar, wallet, or main inventory.

lua

['phone'] = {
    name = 'phone',
    label = 'Classic Phone',
    weight = 150,
    type = 'item',
    image = 'phone.png',
    unique = true,
    useable = true,
    shouldClose = true,
    object = 'prop_amb_phone',
    useableIn = 'hotbar', -- Can only be used from the hotbar
    rare = 'common',
    description = 'They say that Quasar Smartphone is the same as an iPhone, what do you think?'
}

Object Rotation

Dropped items can be visually adjusted using objectRotation. This ensures the prop appears correctly aligned when placed in the world.

lua

['brick'] = {
    name = 'brick',
    label = 'Brick',
    weight = 500,
    type = 'item',
    image = 'brick.png',
    unique = false,
    useable = true,
    object = 'prop_brick_01',
    objectRotation = vec3(80.0, 60.0, 0.0), -- Adjusts world rotation
    description = 'A heavy brick. Probably not safe to throw.'
}

Level Restrictions

Items can also require a minimum player level before they can be used. This is defined using the level property and is commonly used for powerful weapons or advanced gear.

lua

['weapon_advancedrifle'] = {
    name = 'weapon_advancedrifle',
    label = 'Advanced Rifle',
    weight = 1000,
    type = 'weapon',
    ammotype = 'AMMO_RIFLE',
    image = 'weapon_advancedrifle.png',
    unique = true,
    useable = false,
    level = 20, -- Minimum level required
    rare = 'epic',
    description = 'An assault version of a rapid-fire rifle designed for infantry use'
}