Consider two test cases: one bandage heals the player but stays in their bag; another disappears before the animation starts, then takes a second bandage when it finishes. Both bugs can come from the same missing decision: which part of the resource owns consumption?
In a QBCore setup, making an item usable, playing its animation, applying its effect and removing its inventory entry are separate responsibilities. They need to agree on one successful use. This guide follows that single operation through the server so you can find missing removals, double consumption and cancellation mistakes.
The examples assume QBCore with qb-inventory. A replacement inventory may provide different exports, hooks or automatic consumption rules. Confirm that integration first, even when the item name looks identical.
Registration tells the server what use means
QBCore.Functions.CreateUseableItem registers a handler for an item. The function reference demonstrates checking the player's inventory inside that handler before running the item's behavior. Registration itself is not a general promise that one unit will be consumed. See the QBCore server function reference.
That distinction matters for reusable objects. A radio, a document and a sandwich may all be usable, yet removing all three on every click would be an unusual inventory policy. The item handler or inventory integration must define the intended result.
If the item never reaches its handler, work through its definition and registration first. The custom item setup guide covers those foundations. If the handler runs and the count behaves incorrectly, adding another registration is unlikely to help.
Trace one use from click to final count
Choose an ordinary test character and give them a known quantity. Record the count before the interaction, after the animation starts, after success and after cancellation. Include a reconnect check only after the immediate behavior is understood.
Search the involved resources for the item name, its use event, removal calls and any bridge that forwards the request. Draw the sequence in plain language: inventory invokes handler, handler authorizes use, client performs animation, server completes use, effect is granted.
Now identify every line that changes inventory quantity. Two legitimate looking removal calls in different resources can still describe the same consumption. A framework adapter may already remove the item before forwarding to a custom effect. A copied example may then remove it again.
Also count the effect calls. One removal with two effects is a different defect from two removals with one effect. Logging the operation identifier and stage makes that distinction visible without dumping a player's entire inventory.
Give consumption one owner
Write a brief contract for the item. For an illustrative first aid item: a completed, authorized use consumes one matching item and grants the configured effect once. A rejected request grants no effect. A cancelled animation follows the cancellation policy chosen for that item.
Assign one server path to make the removal decision. Other parts can request or display the action, but should not independently repeat it. If an inventory offers built-in consumption, integrate with that mechanism and its documented lifecycle instead of layering a second removal on top.
The current qb-inventory documentation describes RemoveItem as returning success or failure and allows a specific slot to be supplied. Use the actual result to decide whether a consumption-dependent effect may proceed. An earlier possession check cannot guarantee the later removal succeeded. The qb-inventory export reference documents the parameters for the current version.
Do not repair a failed removal by granting the effect anyway because the animation looked convincing. Animation is presentation. It is not evidence that an inventory mutation happened.
Choose when the item is spent
Removing the item at the start gives a clear cost for beginning the action. It also means a cancelled action may require compensation if your rules promise the item back. That compensation needs its own reliable ownership: one refund, to the correct character, for one previously consumed item.
Removing at completion is often easier for cancellable interactions. However, the item must still be present and eligible when the server completes the action. During the delay, the player may have moved it, handed it away or started another use.
Neither timing choice solves all concurrency problems by itself. A sensible implementation needs a pending-use record or another mechanism appropriate to the inventory. Associate the action with the character and item, reject overlapping uses where required, and define how the record ends on success, cancellation or timeout.
Avoid a refund that simply creates a fresh generic item if the consumed object carried meaningful information. Its metadata might represent remaining charges or a unique object. Returning the wrong object repairs the count while damaging the inventory's meaning.
A slot is part of the request, not proof of ownership
For items carrying distinct information, identify which object the player intended to use. Removing the first item with a matching name can consume a different instance from the one shown in the interface.
But a supplied slot can become stale. Revalidate the current item in that slot before committing. Where your inventory allows items to move during an action, either support that movement through an appropriate stable identity or cancel when the selected item changes. Do not pretend a slot number stays attached to an object forever.
Validate the request on the server. The client should not be able to choose an arbitrary removal amount, award or effect strength. Cfx.re's event security documentation explains why server checks must establish the relevant inventory and player conditions rather than trusting submitted values.
For your own design, keep the set of accepted actions narrow. A use request for a bandage should resolve to the server's bandage policy, not to an open-ended instruction to grant whatever effect the client names.
Make repeats harmless
A player can double-click, a user interface can submit twice, or a delayed completion can arrive after a cancellation. Test those paths intentionally on staging. One action should reach one terminal outcome.
Store a server-created operation identifier and the current status when the interaction warrants it. A completion for an already completed or cancelled operation should not consume or reward again. Expire abandoned records, and release any temporary block when the operation ends.
For persistent rewards, a memory-only flag may not cover a resource restart. Decide whether the operation needs a durable record. A sandwich animation and a rare item conversion deserve different levels of persistence, but both need a clear answer to “what happens if this completion is repeated?”
Test the failures before restoring normal use
Use one item, then two items in separate slots where supported. Complete normally, cancel midway, move the chosen item, attempt a second use, and disconnect during the delay. Repeat with a deliberately delayed callback on the test server.
For each case, check the inventory count, the exact affected item, the effect and any pending state. Verify that the player can use items again afterward. A fix that stops duplication by leaving everybody permanently busy has merely changed the complaint.
Once the operation behaves correctly, remove excessive diagnostic logging and retain a concise reason on meaningful failures. The useful result is a readable chain with one owner for consumption, one decision about cancellation and one final outcome for every use.
