QBCore Frameworkqbcore.netCommunity docs
On this page

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.lua

fxmanifest.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_coffee

After 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.

TestExpected result
Core startup after editing items.luaNo syntax error; the shared item is registered
Inventory displayCorrect label and image; ordinary stacking works
First useExactly one item removed; effect begins
Immediate second useNo second consumption; server reports the active cooldown
After 60 secondsMultiplier restored; another use is allowed
Logout or stop docs_coffee during effectMultiplier restored; stale timeout cannot reapply anything
Failed removal or stale slotNo effect is granted
Reconnect after a normal saveThe 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

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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website