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

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

```text
resources/[custom]/docs_coffee/
  fxmanifest.lua
  server.lua
  client.lua
```

`fxmanifest.lua`:

```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:

```cfg
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`:

```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`:

```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](/docs/troubleshooting/multicharacter-loading#worked-case-black-screen-after-installing-a-script), not a database reset.

## See also

- [Inventory API and storage](/docs/resources/qb-inventory)
- [Inventory update errors](/docs/troubleshooting/inventory-updates)
- [Safe server events](/docs/security/safe-server-events)

## Next steps

Combine item interactions with [qb-target](/docs/resources/qb-target) or a [NUI form](/docs/guides/nui-form-callback), keeping consumption and authorization on the server.

## Sources

- [Core item definitions](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/shared/items.lua) and [server functions](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/functions.lua).
- [Inventory slot lookup and removal](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/server/functions.lua).
- [Cfx.re event security](https://docs.fivem.net/docs/developers/server-security/), checked 2026-09-21.
