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
- export?:
- 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
orhash
- 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
- export?:
- buttons?:
table
- label:
string
- action:
function
(slot:number
)- Callback function when button is clicked in context menu, returns item slot.
- label:
- label:
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 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 (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' }
})