Creating Items

Defining item data

Before being able to see or use an item in game it must first be defined.

All of the items are defined in the /data/items.lua (opens in a new tab) file with key, value pairs. Key is the name (not the label) of an item and the value is a table containing the options for the item.

• Item options: table
  • label: string
  • weight?: number
  • stack?: boolean
    • If set to false will not allow the item to be stacked.
  • degrade?: number
    • Amount of time in minutes the item will degrade after.
  • decay?: boolean
    • If true the item will be deleted when durability reaches 0 (not instant for degraded items).
  • close?: boolean
    • If set to false does not close the inventory on item use.
  • description?: string
    • Item description that will be shown in the tooltip
  • consume?: number
    • Item count needed and removed use.
    • Default: 1
    • If set to a decimal will consume durability instead (0.2 = 20%).
  • allowArmed?: boolean
    • If set to true will allow use of item while armed with a weapon.
  • server?: table
    • export?: string
  • client?: table
    • export?: string
      • Export to be triggered after item use.
    • event?: string
      • Event to be triggered after item use.
    • status?: table
      • Adjust esx_status values after use.
    • anim?: table
      • Animation that will be played during the progress bar.
      • dict: string
      • clip: string
    • prop?: table
      • Attached prop that will be displayed during the progress bar.
      • model: string or hash
      • pos: table (x, y, z)
      • rot: table (x, y, z)
      • bone: number
    • disable?: table
      • Actions to be disabled during the progress bar.
      • move?: boolean
      • car?: boolean
      • combat?: boolean
      • mouse?: boolean
      • sprint?: boolean
    • usetime?: number
    • cancel?: boolean
      • If set to true the player canc cancel item use.
    • add?: function(total: number)
      • Function that triggers when receiving an item
      • Returns total item count as total
    • remove?: function(total: number)
      • Function that triggers when removing an item
      • Returns total item count as total
  • buttons?: table
    • label: string
    • action: function(slot: number)
      • Callback function when button is clicked in context menu, returns item slot.

Examples

['burger'] = {
    label = 'Burger',
    weight = 220,
    stack = true,
    close = true,
    client = {
        status = { hunger = 200000 },
        anim = { dict = 'mp_player_inteat@burger', clip = 'mp_player_int_eat_burger_fp' },
        prop = {
            model = 'prop_cs_burger_01',
            pos = { x = 0.02, y = 0.02, y = -0.02},
            rot = { x = 0.0, y = 0.0, y = 0.0}
        },
        usetime = 2500,
    }
}

Making the item usable

• If you are using ESX, you can continue using ESX.RegisterUsableItem.
• If you are using QBCore, you can continue using QBCore.Functions.CreateUseableItem.

Using the built-in system is more secure and provides much more functionality.

Client callbacks

Item callbacks can be added by defining an export (recommended), or by adding it to items/client.lua (opens in a new tab).

When defining item data (opens in a new tab), adding client.export will trigger an event on item use. The correct formatting is export = resourceName.exportName.

exports('bandage', function(data, slot)
    local playerPed = PlayerPedId()
    local maxHealth = GetEntityMaxHealth(playerPed)
    local health = GetEntityHealth(playerPed)
 
    -- Does the ped need to heal? We can cancel the item from being used.
    if health < maxHealth then
        -- Triggers internal-code to correctly use items.
        -- This adds security, removes the item on use, adds progressbar support, and is necessary for server callbacks.
        exports.ox_inventory:useItem(data, function(data)
            -- The server has verified the item can be used.
            if data then
                SetEntityHealth(playerPed, math.min(maxHealth, math.floor(health + maxHealth / 16)))
                lib.notify({description = 'You feel better already'})
            end
        end)
    else
        -- Don't use the item
        lib.notify({type = 'error', description = 'You don\'t need a bandage right now'})
    end
end)

Server callbacks

A callback function can be defined on the server to handle several events (usingItem, usedItem, buyItem). This can either be an export (recommended), or added to the bottom of items/server.lua (opens in a new tab). When defining item data (opens in a new tab), adding server.export will trigger an event for the actions above. The correct formatting is export = resourceName.exportName.

exports('bandage', function(event, item, inventory, slot, data)
    -- Player is attempting to use the item.
    if event == 'usingItem' then
        local playerPed = GetPlayerPed(inventory.id)
        local maxHealth = GetEntityMaxHealth(playerPed)
        local health = GetEntityHealth(playerPed)
 
        -- Check if the player needs to be healed.
        if health >= maxHealth then
            TriggerClientEvent('ox_lib:notify', inventory.id, {type = 'error', description = 'You don\'t need a bandage right now'})
 
            -- Returning 'false' will prevent the item from being used
            return false
        end
 
        return
    end
 
    -- Player has finished using the item.
    if event == 'usedItem' then
        return TriggerClientEvent('ox_lib:notify', inventory.id, {description = 'You feel better already'})
    end
 
    -- Player is attempting to purchase the item.
    if event == 'buying' then
        return TriggerClientEvent('ox_lib:notify', inventory.id, {type = 'success', description = 'You bought a bandage'})
    end
end)

Creating container items

Like with other items the item must first be registered.

When registered you can define the item as a container in /modules/items/containers.lua The key for the container is the name you gave it when registering the item. You can also define the number of slots, the maximum weight, blacklist and whitelist items.

• itemName:
  • slots: number
  • The number represents the amount of slots
  • maxWeight: number
  • The number represents the maximum weight within the container
  • blacklist:
    • Supports single and multiple items
    • { 'testburger', 'testburger2' }
  • whitelist:
    • Supports single and multiple items
    • { 'testburger', 'testburger2' }

Example

['paperbag'] = {
    label = 'Paper Bag',
    weight = 1,
    stack = false,
    close = false,
    consume = 0
},

setContainerProperties('paperbag', {
	slots = 5,
	maxWeight = 1000,
	blacklist = { 'testburger' }
})