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 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
      • rotOrder?: 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,
    }
}

['burger'] = {
    label = 'Burger',
    description = 'Just what is the secret formula?'
    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,
    }
}

['burger'] = {
    label = 'Burger',
    weight = 220,
    stack = true,
    consume = 0,
    client = {
        add = function(total)
            if total > 0 then
                lib.notify({description = 'Nice burger you got there!'})
            end
        end,

        remove = function(total)
            if total < 1 then
                lib.notify({description = 'You lost all of your burgers!'})
            end
        end
    }
}

Making the item usable#

• If you are using ESX, you can continue using ESX.RegisterUsableItem.
• If you are using QBox, you can continue using exports.qbx_core: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.

When defining item data, 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)

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 or using the setContainerProperties server export. 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: string
• properties: table
  • slots: number
    • Number of slots available in the container.
  • maxWeight: number
    • Maximum weight the container can hold.
  • whitelist?: table<string, true> | string[]
    • A table of item names that are allowed in the container.
    • If not provided, all items are allowed except those blacklisted.
  • blacklist?: table<string, true> | string[]
    • A table of item names that are not allowed in the container.
    • If not provided, no items are blacklisted unless whitelist is provided.

Example#

['pizzabox'] = {
    label = 'Pizza Box',
    weight = 50,
    stack = false,
    close = false,
    consume = 0,
},

setContainerProperties('pizzabox', {
    slots = 1,
    maxWeight = 1000,
    whitelist = { 'pizza' },
})