1

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.

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

2

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.

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

3

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.

['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!' }

4

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.

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

5

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.

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

6

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.

['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:

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

7

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.

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

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) } }

8

Preventing Items From Being Thrown

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

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

9

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.

['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?' }

10

Object Rotation

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

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

11

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.

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