# qb-inventory

`qb-inventory` is QBCore's inventory resource. It owns player/item storage behavior, registered
inventories and shops, drops, UI opening, persistence helpers, inventory hooks/listeners and the
player item methods it attaches while the resource is running.

Use the resource exports instead of directly mutating inventory tables.

![qb-inventory request and state synchronization](/diagrams/inventory.svg)

*Conceptual diagram; verify the behavior against your installed resource version.*

For opening failures, use [inventory diagnostics](/docs/troubleshooting/inventory-updates). Before replacing this resource, read the [ox_inventory bridge and migration checks](/docs/guides/ox-inventory-qbcore).

## Download and install qb-inventory

For **QBCore inventory**, use the [upstream qb-inventory repository](https://github.com/qbcore-fivem/qb-inventory).
The `qb-core` download is the framework core, not the inventory resource. Setting up a whole server?
See [Download QBCore and the txAdmin recipe](/download) before installing individual resources.

The [upstream README](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/README.md) lists
`qb-core` and `qb-smallresources` for logging as dependencies. Check the
[manifest](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/fxmanifest.lua), configuration and
README at your selected commit as well; forks can have different requirements.

1. Back up your resource files and database. Work on a staging copy first.
2. Download or clone the upstream repository, record its commit, and keep the resource folder named `qb-inventory` inside your `[qb]` group.
3. For a fresh install, review and import the repository's `qb-inventory.sql` into the intended server database. Do not import it blindly over an existing inventory installation.
4. For an upgrade, follow the SQL and migration instructions for your existing and target revisions. Validate migrated player inventories and stashes before removing any old tables; keep a restorable backup.
5. Start the dependencies before inventory and any resources consuming its exports. Check the first server-console error before testing the UI.
6. Test item use, capacity limits, shops, stashes, reconnects and persistence after a server restart.

For UI-only changes, use the [qb-inventory reskin guide](/docs/guides/qb-inventory-reskin).
For failed opens or item operations, jump to [troubleshooting](#troubleshooting) or
[inventory update troubleshooting](/docs/troubleshooting/inventory-updates).

## Start order

A normal QBCore setup starts the core before inventory consumers:

```cfg
ensure qb-core
ensure [qb]
```

When debugging, confirm `qb-inventory` itself is started before a custom resource calls its exports.
See [Resource load order](/docs/troubleshooting/resource-load-order).

## Current server exports

The current `server/functions.lua` exposes inventory operations including:

- `OpenInventory`
- `OpenInventoryById`
- `CreateInventory`
- `GetInventory`
- `RemoveInventory`
- `AddItem`
- `RemoveItem`
- `CanAddItem`
- `CreateShop`
- `OpenShop`
- `ClearStash`

The exact source file contains additional helpers. Pin your integration to the revision you deploy.

### Add an item

```lua
local added = exports['qb-inventory']:AddItem(
    source,
    'water_bottle',
    1,
    false,
    false,
    'my-resource:reward'
)

if not added then
    -- Handle full/invalid inventory.
end
```

### Remove an item

```lua
local removed = exports['qb-inventory']:RemoveItem(
    source,
    'water_bottle',
    1,
    false,
    'my-resource:consume'
)
```

### Check capacity before adding

```lua
local canAdd, reason = exports['qb-inventory']:CanAddItem(source, 'water_bottle', 1)
if not canAdd then
    print(reason) -- for example weight or slots
    return
end
```

### Create and open a custom inventory

```lua
exports['qb-inventory']:CreateInventory('evidence-123', {
    label = 'Evidence 123',
    maxweight = 100000,
    slots = 30
})

exports['qb-inventory']:OpenInventory(source, 'evidence-123')
```

Treat identifiers as server-owned values when access matters. Do not let a client choose an
arbitrary stash name and then open it without authorization.

## Player methods

Current qb-inventory adds item methods to connected QBCore player objects, including `AddItem`,
`RemoveItem`, item lookup, `ClearInventory` and `SetInventory`.

That compatibility layer comes from **qb-inventory**, not from the permanent qb-core API. Direct
inventory exports make ownership clearer in new integrations.

## Inventory busy state

The resource uses the player state bag `inv_busy` to prevent conflicting opens/moves.

Before building a custom UI that manipulates inventory, understand when the resource sets or clears
that state rather than introducing a second independent lock.

## Shops

Register server-defined shops through the current inventory API instead of sending authoritative
prices from the client.

A shop definition should be built on the server from trusted config, then opened for the player
through the inventory's shop path.

For QBCore's dedicated shop resource, see [qb-shops](/docs/resources/qb-shops).

## Hooks and listeners

Current qb-inventory exposes server-side `AddHook` and `AddListener` exports for operations such as
opening an inventory, moving items, and adding or removing them. Hooks can reject a supported
operation before it completes; listeners observe completed operations.

See the [source-verified hooks, payloads and event reference](/docs/resources/qb-inventory/events)
for runnable registration examples, event names and differences between hooks, listeners and UI
transport events. Always authorize inventory access in your server resource; a hook is not a
substitute for the caller's own permission checks.

## Persistence

Player inventory is synchronized with the QBCore player object and persisted by the inventory/core
integration. Non-player inventories are handled by qb-inventory's own storage paths.

Do not create random tables such as `player_items`, `stashitems` or `trunkitems` because an old
tutorial used them. Import only SQL shipped by the repository/recipe version you deploy.

## Security pattern

For a reward:

```lua
RegisterNetEvent('myjob:server:claimReward', function(jobId)
    local src = source
    local Player = exports['qb-core']:GetPlayer(src)
    if not Player then return end

    -- Validate jobId, player state, proximity, cooldown and ownership server-side.
    local reward = resolveTrustedReward(jobId)
    if not reward then return end

    exports['qb-inventory']:AddItem(src, reward.name, reward.amount, false, false, 'myjob:reward')
end)
```

The client may request an action; it should not decide item names, quantities, prices or reward
eligibility.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Inventory will not open | Resource state, first console error, `inv_busy`, and caller API version. |
| `AddItem` returns false | Item exists in shared items, available slots/weight, correct identifier. |
| Item shows no image | Item definition image name and files in the inventory UI assets. |
| A stash can be opened by anyone | Authorization is missing in the calling server resource. |
| Old export/event is missing | Compare your code against current `server/functions.lua` and migration notes. |

See [Inventory update troubleshooting](/docs/troubleshooting/inventory-updates) and the
[events/functions reference](/docs/resources/qb-inventory/events).

If you replace the default inventory instead of patching it, compare
[inventory scripts on RPScripts](https://rpscripts.net/product-category/fivem-inventory-scripts/) by declared QBCore
version, dependencies and data migration path. RPScripts and qbcore.net are operated by the same owner.

## Sources

- [qb-inventory repository](https://github.com/qbcore-fivem/qb-inventory)
- [Current server functions](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/server/functions.lua)
- [Current server main](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/server/main.lua)
- [Official qb-inventory documentation](https://github.com/qbcore-framework/qb-docs/blob/930c12ec4f60dfbba60253571f1a58980129516d/qbcore-resources/qb-inventory.md)

Source references and literal export names rechecked against commit `dc3d07fc` on **2026-10-13**. This is static evidence, not FXServer or database acceptance.
