Discord
Edit

🎒qb-inventory

Store your precious!

Introduction

  • Handles all the player's storage such as personal, vehicle, stash, drops

  • qb-shops integration for displaying all items available to buy

  • Built-in support for usable vending machines

All exports listed are SERVER only unless specified

Inventory State

The inventory state is controlled via state bags using a state bag name of inv_busy. You can use this state to control whether the inventory should be able to be opened or not

Example (server):

RegisterCommand('checkState', function(source)
    local player = Player(source)
    local state = player.state.inv_busy
    print('Inventory current state is', state)
end, true)

RegisterCommand('lockInventory', function(source)
    local player = Player(source)
    player.state.inv_busy = true
    print('Inventory current state is', state)
end, true)

RegisterCommand('unlockInventory', function(source)
    local player = Player(source)
    player.state.inv_busy = false
    print('Inventory current state is', state)
end, true)

Example (client):

Item Info

You can use SetItemData to achieve this

Items support additional information that can be added to them via an info attribute. This information will display on the item when the player hovers over it in a key,value pair format. You can also add a special display keyword and make it false to hide any data inside the info table from being shown!

LoadInventory

This function retrieves the player's inventory from the database using their citizenid, decodes it from JSON, and builds a structured table of items using data from QBCore.Shared.Items. If an item is found that no longer exists in the shared items table, it is skipped and logged to the console. The returned inventory contains detailed information like item label, weight, image, and usage properties

  • source: number

  • citizenid: string

  • returns: table

SaveInventory

Saves the player's current inventory to the database by serializing item data into JSON format. Supports both online and offline player data

  • source: number

  • offline: boolean

ClearInventory

Clears a player's inventory, optionally preserving specific items by name. Updates player data, logs the action, and removes the currently equipped weapon if applicable

  • source: number

  • filterItems: string | table

ClearStash

Empties all items from the specified stash inventory and updates the database to reflect the cleared state

  • identifier: string

CloseInventory

Closes the specified inventory and marks the player as no longer busy, then notifies the client to close the inventory UI

  • source: number

  • identifier: string

OpenInventory

Opens a specified inventory or the player's own if no identifier is given. Prevents access if the inventory is already in use, initializes it if needed, and sends formatted inventory data to the client for display

  • source: number

  • identifier: string | optional

  • data: table | optional

OpenInventoryById

Opens another player's inventory for viewing or interaction, formatting their data for display and marking their state as busy to prevent conflicts

  • source: number

  • playerId: number

OpenInventoryById will close the target players inventory (if open) and lock it via state. It will then unlock when the opening player closes it

CreateInventory

Creates and registers a new inventory using the provided identifier and initialization data if it doesn't already exist

  • identifier: string

  • data: table

RemoveInventory

Deletes the inventory associated with the specified identifier from the in-memory registry

  • identifier: string

CreateShop

Registers one or multiple shops by storing their data, including name, label, coordinates, item slots, and available items, into the global shop registry

  • shopData: table

    • name: string

    • label: string

    • coords: vector3

    • slots: number

    • items: table

Coords being passed to createShop will be checked against the player's current coords when OpenShopis called if coords were provided during createShop

OpenShop

Opens a shop inventory for the player if they're within range, formatting the shop data for client display and sending it alongside the player's current inventory

  • source: number

  • name: string

CanAddItem

Determines whether a specified item and amount can be added to a player or inventory, checking both weight limits and slot availability. Returns false with a reason if constraints are exceeded

  • source: number

  • item: string

  • amount: number

  • returns: boolean

AddItem

Adds an item to a player or specific inventory, accounting for weight limits and available slots. Logs the action and returns whether it succeeded

  • identifier: number

  • item: string

  • amount: number

  • slot: number | boolean

  • info: table | boolean

  • reason: string

  • returns: boolean

RemoveItem

Removes a specified amount of an item from a player or inventory, optionally from a specific slot. Updates data and logs the removal

  • identifier: number

  • item: string

  • amount: number

  • slot: number | boolean

  • reason: string

  • returns: boolean

SetInventory

Sets the item list for a specified player, drop, or custom inventory, updating in-memory data and logging the change for auditing purposes

  • source: number

  • items: table

SetItemData

Sets a specific key-value pair in a player's item data and updates the player's inventory with the modified item. If a slot number is provided, it directly targets the item in that slot. Otherwise, it uses GetItemByName to find the first matching item by name

  • source: number

  • itemName: string

  • key: string

  • val: string | table

  • slot: number (optional)

  • returns: boolean

Item Info Example:

UseItem

Triggers the use function of a specified usable item if it exists, passing any additional arguments to the item's handler

  • itemName: string

  • . . . : function

HasItem

Checks whether a player possesses a specific item or set of items in their inventory, optionally verifying that the required amount is met for each

This export is also available to use on the client

  • source: number

  • items: string | table

  • amount: number

  • returns: boolean

GetFreeWeight

Calculates and returns the remaining weight capacity in a player's inventory. Returns 0 if the player is not found or the source is invalid

  • source: number

  • returns: number

GetTotalWeight

Calculates and returns the total weight of all items in the inventory, accounting for item quantities

  • items: table

  • returns: number

GetSlots

Returns the number of used and available slots in a player's inventory, a custom inventory, or a drop, based on the provided identifier

  • identifier: number | string

  • returns: number, number

GetSlotsByItem

Returns a list of all inventory slots containing the specified item, ignoring case sensitivity

  • items: table

  • itemName: string

  • returns: table

GetFirstSlotByItem

Finds and returns all inventory slots that contain a specified item by name, ignoring case sensitivity

  • items: table

  • itemName: string

  • returns: number

GetItemBySlot

Retrieves the item from a player's inventory at the specified slot, or returns nil if the slot is empty or the player is not found

  • source: number

  • slot: number

  • returns: table

GetItemByName

Retrieves the first instance of a specified item from a player's inventory by name, returning its data if found

  • source: number

  • item: string

  • returns: table

GetItemsByName

Retrieves all instances of a specified item from a player's inventory, returning a list of matching items by name

  • source: number

  • item: string

  • returns: table

GetItemCount

Calculates the total quantity of one or more specified items in a player's inventory, supporting both single item names and tables of item names

  • source: number

  • items: string | table

  • returns: number

GetInventory

Retrieves the inventory object associated with the given identifier, or nil if not found

  • identifier: string

  • returns: table | nil

Previousqb-interiorNextqb-jewelry

Last updated

Was this helpful?