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

<Tabs items={["Burger", "Burger with description", "Burger with notification"]}> lua ['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, } } A modified burger item which includes a description.

```lua
['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,
    }
}
```

A modified burger item, which gives you notifications on add and remove arguments.

```lua
['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)

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

PreviousCrafting NextCreating Shops

Last updated 2 months ago