Updated 2026-09-21 · 3 min read
Create a Usable QBCore Item
Goal
Create docs_coffee: consuming one item enables a 60-second sprint effect. A server cooldown prevents consuming another while the effect is active. The unique name avoids overwriting the standard coffee item or its existing handler in another resource.
The API baseline is qb-core at 9b3cddcc and qb-inventory at dc3d07fc. These examples were reviewed against source; the in-game checks below are manual acceptance tests, not claimed runtime results. This guide targets qb-inventory, not ox_inventory's item schema.
Define the item
Add this entry inside the existing table in qb-core/shared/items.lua. Do not create a second QBCore.Shared.Items table or replace the file. Check commas before and after the entry.
['docs_coffee'] = {
name = 'docs_coffee',
label = 'Training Coffee',
weight = 200,
type = 'item',
image = 'docs_coffee.png',
unique = false,
useable = true,
shouldClose = true,
description = 'A short sprint boost for the training server.'
},In this schema, unique = false permits stacking and shouldClose = true requests closing the inventory on use. stack and close are not replacements for these QBCore fields. The spelling useable matches the upstream item definitions.
Place a PNG image you have permission to use at qb-inventory/html/images/docs_coffee.png. Match case exactly, especially on Linux. An absent image and an unregistered item are different faults: the former affects presentation, while the latter breaks item lookup.
Create the resource
Create this directory next to your other custom resources:
resources/[custom]/docs_coffee/
fxmanifest.lua
server.lua
client.luafxmanifest.lua:
fx_version 'cerulean'
game 'gta5'
dependencies { 'qb-core', 'qb-inventory' }
server_script 'server.lua'
client_script 'client.lua'Ensure the resources in dependency order, without adding a second start block for resources already started by your recipe:
ensure qb-core
ensure qb-inventory
ensure docs_coffeeAfter editing shared items, do a coordinated staging server restart. Do not hot-restart only qb-core under an active production session. Confirm the core and inventory start cleanly before testing the custom resource.
Register use effect
server.lua:
local QBCore = exports['qb-core']:GetCoreObject()
local nextUse = {}
local itemName = 'docs_coffee'
local durationSeconds = 60
QBCore.Functions.CreateUseableItem(itemName, function(playerSource, item)
local player = QBCore.Functions.GetPlayer(playerSource)
if not player or type(item) ~= 'table' then return end
local slot = tonumber(item.slot)
if not slot then return end
local stored = exports['qb-inventory']:GetItemBySlot(playerSource, slot)
if not stored or stored.name ~= itemName or stored.amount < 1 then return end
local now = os.time()
if (nextUse[playerSource] or 0) > now then
TriggerClientEvent('QBCore:Notify', playerSource, 'The coffee effect is already active.', 'error')
return
end
-- Reserve before invoking another resource. No client-supplied reward or amount.
nextUse[playerSource] = now + durationSeconds
local removed = exports['qb-inventory']:RemoveItem(
playerSource, itemName, 1, slot, 'docs-coffee:consume'
)
if not removed then
nextUse[playerSource] = nil
return
end
TriggerClientEvent('docs_coffee:client:apply', playerSource)
end)
AddEventHandler('playerDropped', function()
nextUse[source] = nil
end)The server re-reads the slot and grants the effect only after RemoveItem succeeds. There is deliberately no client-callable server event that grants coffee, money or a reward. CreateUseableItem registers behavior; it does not automatically consume an item.
client.lua:
local active = false
local generation = 0
local function clearEffect()
generation = generation + 1
if active then
SetRunSprintMultiplierForPlayer(PlayerId(), 1.0)
active = false
end
end
RegisterNetEvent('docs_coffee:client:apply', function()
-- Network events sent by the server use 65535 on the client.
if source ~= 65535 then return end
generation = generation + 1
local current = generation
active = true
SetRunSprintMultiplierForPlayer(PlayerId(), 1.1)
SetTimeout(60000, function()
if current == generation then clearEffect() end
end)
end)
RegisterNetEvent('QBCore:Client:OnPlayerUnload', clearEffect)
AddEventHandler('onResourceStop', function(resource)
if resource == GetCurrentResourceName() then clearEffect() end
end)The generation counter prevents an old timeout from cancelling a newer effect. Cleanup restores the multiplier on logout and resource stop. Client-side effects are not an anti-cheat boundary: the server remains responsible for inventory changes.
This example assumes no other resource owns the sprint multiplier. For a server with drugs, injuries or other movement modifiers, route the effect through one shared effect manager rather than letting independent scripts reset each other's state. Death handling and persistent cooldowns are policy decisions to add there; this example's server cooldown is in memory and resets on disconnect or resource restart.
Verification
On a staging character, use your authorized inventory/admin tooling to give two docs_coffee items. Do not add a public give-item command to this resource.
| Test | Expected result |
|---|---|
Core startup after editing items.lua | No syntax error; the shared item is registered |
| Inventory display | Correct label and image; ordinary stacking works |
| First use | Exactly one item removed; effect begins |
| Immediate second use | No second consumption; server reports the active cooldown |
| After 60 seconds | Multiplier restored; another use is allowed |
Logout or stop docs_coffee during effect | Multiplier restored; stale timeout cannot reapply anything |
| Failed removal or stale slot | No effect is granted |
| Reconnect after a normal save | The consumed item does not reappear |
If the item does not appear, check registration before debugging the PNG. If it appears but cannot be used, check useable, the running server handler and duplicate registrations. If an unrelated resource starts reporting nil items after your edit, follow the script-installation diagnostic, not a database reset.
See also
Next steps
Combine item interactions with qb-target or a NUI form, keeping consumption and authorization on the server.
Sources
- Core item definitions and server functions.
- Inventory slot lookup and removal.
- Cfx.re event security, checked 2026-09-21.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
NUI Form with Callback
Download a complete QBCore NUI resource with HTML, CSS, JavaScript, Lua callbacks, server validation, timeouts and focus cleanup.
ox_inventory on QBCore
Check ox_inventory forks, QBCore bridges, dependencies and migration risks before replacing qb-inventory. Diagnose missing exports and item failures.
