> For the complete documentation index, see [llms.txt](https://corex-zombies.gitbook.io/corex-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://corex-zombies.gitbook.io/corex-docs/reference/native-inventory.md).

# Native inventory

`corex-inventory` is the native CoreX inventory. Items occupy grid space and contribute weight; the resource also handles item metadata, weapons, shops, bags and world drops.

This page targets the September 2026 compatibility update. Persistence and recovery changes belong to this candidate; do not assume an older download has them. Automated tests do not certify connected-player gameplay or live-database recovery.

## Configuration and item files <a href="#configuration-and-item-files" id="configuration-and-item-files"></a>

For shop NPC interactions versus portable-vehicle pickup, see [Target systems](/corex-docs/start-here/add-a-resource.md#target-systems). The two paths do not use the same target implementation.

| File                                                   | What to edit                                                                                     |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `resources/[corex]/corex-inventory/config.lua`         | Grid, maximum weight, pickup/give distances, drop lifetime, recoil and portable-vehicle settings |
| `resources/[corex]/corex-inventory/shared/items.lua`   | Native item definitions                                                                          |
| `resources/[corex]/corex-inventory/shared/weapons.lua` | Weapon and ammunition definitions                                                                |
| `resources/[corex]/corex-inventory/shared/shops.lua`   | Shop definitions                                                                                 |
| `resources/[corex]/corex-inventory/html/images/`       | Native inventory images                                                                          |

Native definition weights and `Config.MaxWeight` use **kilograms**. Compatibility item catalogs use **grams**. For imported items, use [Add items](/corex-docs/start-here/add-items.md) and a content pack so the conversion occurs once.

The manifest requires `corex-core`; player inventory storage uses `oxmysql` and `corex_inventories`. Use the release's real migration files and installation instructions rather than creating an abbreviated `inventories` table.

## Inspect possessions without changing them <a href="#inspect-possessions-without-changing-them" id="inspect-possessions-without-changing-them"></a>

```lua
-- Server helper; src is a loaded player's server ID.
local function inspectInventory(src)
    local inventory = exports['corex-inventory']:GetInventory(src)
    if not inventory then return end
    for _, item in pairs(inventory.items or {}) do
        print(item.slot, item.name, item.count)
    end
end
```

Treat returned inventory and catalog tables as read-only. Directly changing a row bypasses dirty tracking and synchronization.

## Useful server exports <a href="#useful-server-exports" id="useful-server-exports"></a>

Use the [native inventory export table](/corex-docs/reference/exports.md#corex-inventory) for complete signatures: reads, count/capacity checks, additions/removals, metadata, drops and pickups. Keep the caveats below beside your implementation.

Trailing placement and metadata arguments may be omitted when you do not need them. Use the item's actual slot value; native slots can be strings. `UpdateItemMeta` takes the **item name before metadata**, and its optional slot comes after metadata. The simpler remove-by-name API does not select a specific metadata stack.

These mutation exports belong in trusted server workflows. Check the result before awarding a related payment or marking a transaction complete. A carry check does not reserve capacity, and a successful item mutation is separate from later SQL acknowledgment.

## Weapon state, reloads and modifications <a href="#weapon-state" id="weapon-state"></a>

Weapon state is stored on the weapon item's metadata so it follows the exact inventory slot. `metadata.ammo` is the saved round count. The owning client may report a lower live count after firing, but the public network path cannot increase it; increases happen through trusted server flows such as the timed reload transaction.

`metadata.ammoRevision` fences reports from before a completed reload. Legacy items without this field start at revision zero. A confirmed reload advances it alongside the ammo mutation, and the client consumes newer inventory snapshots to recover even if the dedicated reload reply is delayed. Preserve this field with the item's metadata; it is an internal ammo-generation marker, not a general SQL transaction revision. Deploy matching client/server versions together.

Reloading is server-timed. The client requests a reload for the equipped weapon/slot, the server snapshots the player session and calculates the duration from the Skills modifier, and the ammo item is consumed only after the timer completes. Death, changing weapons, session reuse/reconnect and expiry cancel the pending operation without granting rounds.

Installed weapon modifications are persisted in `metadata.attachments` as a map from the CoreX mod ID to the exact GTA component name, for example:

```lua
metadata.attachments = {
    suppressor = 'COMPONENT_AT_PI_SUPP'
}
```

CoreX re-applies compatible saved components whenever the weapon is equipped. The built-in Weapon Modder flow supports `grip`, `suppressor`, `compensator`, `heavybarrel` and `muzzlebrake`. Craft the corresponding mod at a workbench, equip a weapon that accepts one of that mod's allowed components, stay at the workbench, then run:

```
/weaponmod suppressor
```

The client resolves a component supported by the equipped weapon. The server independently checks the `unlocksWeaponMods` skill flag, current session, workbench proximity, exact weapon and slot, component allowlist and required mod item before changing inventory state. The component allowlist is not an independent server-side per-weapon compatibility check. One logical attachment slot can hold one mod at a time.

Client shop exports are `OpenShop(shopName)`, `CloseShop()` and `GetShopNPCs()`. Internal inventory UI network events are not a substitute for the public server API.

## Compatibility and recovery <a href="#compatibility-and-recovery" id="compatibility-and-recovery"></a>

When the capability layer is active, this resource can provide the canonical inventory operations. Keep one selected possessions owner. Switching to an external inventory does not migrate stored player items.

Do not delete recovery JSON files to suppress an error. Preserve them, inspect the specific migration or persistence diagnostic and follow the release's recovery instructions. Stop testing if item readback differs across reconnects; do not grant replacement items repeatedly while the cause is unknown.

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

**Empty cells but capacity rejection:** check both weight and whether the item's rectangular footprint fits.

**Unknown item:** confirm the exact definition exists and its content pack is active. An entry in a third-party README is not imported automatically.

**Two stacks have different metadata:** this can be intentional. Use the returned slot to inspect the specific stack rather than assuming all copies share metadata.

**Reward shown but no item:** compare the mutation result, native count and selected-provider diagnostic. Inspect persistence separately after delivery works.

Source checked: `config.lua`, `fxmanifest.lua`, `shared/weapon_mods.lua`, `client/weapons.lua`, `server/reload_runtime.lua`, `server/main.lua`, `server/catalog.lua`, `server/capability_provider.lua` and `server/usable_bridge.lua`.