Client

Exports

Client-side exports.

All client exports are called as exports.one_inventory:Name(...) from a client script. Read-only exports are served from a local mirror that refreshes whenever the server pushes inventory state, so they don't round-trip the network.

Reads

SearchInventory

Search the local inventory mirror for items by name (and optional metadata filter).

exports.one_inventory:SearchInventory(searchType, itemName, metadata)

searchType

string required

'count' returns a summed number. 'slots' returns the matching slot list.

itemName

string required

Item name to match.

metadata

table

Optional metadata filter.

Returns: number | table[].

GetInventoryItems

Every populated slot in the local inventory mirror.

exports.one_inventory:GetInventoryItems()

Returns: table[] - array of { name, slot, count, metadata }.

GetSlot

Slot data at a given slot index.

exports.one_inventory:GetSlot(slot)

slot

number required

Slot index to read.

Returns: table | nil.

GetSlotWithItem

First slot containing the named item, optionally filtered by metadata.

exports.one_inventory:GetSlotWithItem(itemName, metadata)

itemName

string required

Item name to match.

metadata

table

Optional metadata filter.

Returns: table | nil.

GetSlotsWithItem

Every slot containing the named item, optionally filtered by metadata.

exports.one_inventory:GetSlotsWithItem(itemName, metadata)

itemName

string required

Item name to match.

metadata

table

Optional metadata filter.

Returns: table[] - empty array when no matches.

GetSlotIdWithItem

First slot index containing the item.

exports.one_inventory:GetSlotIdWithItem(itemName, metadata)

itemName

string required

Item name to match.

metadata

table

Optional metadata filter.

Returns: number | nil.

GetSlotIdsWithItem

Every slot index containing the item.

exports.one_inventory:GetSlotIdsWithItem(itemName, metadata)

itemName

string required

Item name to match.

metadata

table

Optional metadata filter.

Returns: number[] | nil - nil when no matches.

GetItemCount

Total count of an item across every slot in the local mirror.

exports.one_inventory:GetItemCount(itemName, metadata)

itemName

string required

Item name to match.

metadata

table

Optional metadata filter.

Returns: number.

HasItem

Same signature as qb-inventory's HasItem. Accepts a single name, an array of names, or a { name = required } map.

exports.one_inventory:HasItem(items, amount)

items

string | string[] | table<string, number> required

Single name, array of names, or per-item required counts.

amount

number

Required count when items is a string or array. Defaults to 1.

Returns: boolean.

Weight

GetWeightHolding

Current weight the player is carrying (grams).

exports.one_inventory:GetWeightHolding()

Returns: number.

GetMaxWeight

Maximum weight the player's inventory can hold (grams).

exports.one_inventory:GetMaxWeight()

Returns: number.

Weapons

GetEquippedWeapon

Currently-equipped weapon entry from the local mirror.

exports.one_inventory:GetEquippedWeapon()

Returns: table | nil - { slot, name }, or nil when no weapon is equipped.

Clothing

These exports operate on the local player only; there is no src argument because they always target the calling client. Add or remove the clothing items themselves through the player's regular inventory via AddItem / RemoveItem; use the exports below to actually equip / unequip them on the ped.

GetEquippedClothing

Currently equipped clothing.

exports.one_inventory:GetEquippedClothing()

Returns: table - map of { [componentType] = { name, count, drawable, texture, ... } }. Empty components are absent. Returns {} when nothing is equipped.

EquipClothing

Equip a clothing item from the player's inventory. Round-trips to the server; the ped auto-updates when the server pushes the new state back.

local ok, reason = exports.one_inventory:EquipClothing(item, metadata)

item

string required

Item name to equip.

metadata

table

Optional metadata filter, used to disambiguate stacks when the item appears multiple times.

Returns: boolean, string? - ok, plus a reason on failure: no_player, no_clothing_inv, not_clothing, item_not_in_inventory, invalid_component, no_room, unknown_error, no_response.

UnequipClothing

Unequip a clothing component and return the item to the player's inventory. Round-trips to the server.

local ok, reason = exports.one_inventory:UnequipClothing(componentType)

componentType

string required

One of hat, mask, glasses, ear, chain, shirt, armor, jacket, bag, gloves, pants, shoes, watch, bracelet.

Returns: boolean, string? - ok, plus a reason on failure: no_player, no_clothing_inv, invalid_component, nothing_equipped, inventory_full, no_response.

inventory_full also covers the case where the underlying addItem returns no_slot server-side, so a single failure reason is enough to drive UI feedback.

SetClothingPollingEnabled

Pause or resume the clothing polling thread (the loop that reads the ped to auto-create items for appearance scripts without a save event). Pause it around a custom clothing-shop or character-creator preview so intermediate try-on looks aren't captured as items.

exports.one_inventory:SetClothingPollingEnabled(enabled)

enabled

boolean required

false pauses the thread, true resumes it.

Pauses ONLY the polling thread. Appearance scripts that expose a save event keep syncing while it is paused.

Definitions

GetItemDefinition

Definition by name (label, weight, stack rules, metadata defaults, ...). Resolves any definition type (item, weapon, ammo, component, backpack, clothing); the returned table carries a type field. Lazy-fetched from the server on first call (5s timeout) and cached for the rest of the client session.

exports.one_inventory:GetItemDefinition(itemName)

itemName

string required

Definition name to look up.

Returns: table | nil - the definition with an added type field, or nil if unknown.

GetAllItemDefinitions

Complete { [name] = definition } map across all definition types, each tagged with a type field. Same backing cache as GetItemDefinition.

exports.one_inventory:GetAllItemDefinitions(filter)

filter

string | string[]

Narrow to one or more types, e.g. 'weapon' or { 'weapon', 'ammo' }. Omit (or pass an empty value) to return everything.

Returns: table<string, table> - each definition carries a type field.

Config

GetClientConfig

A copy of the shared, client-facing config table (locale, keybinds, appearance, gameplay, ...). The same export is available server-side; it never exposes server-only keys.

exports.one_inventory:GetClientConfig()

Returns: table - a copy of the client-facing config. Mutating it does not affect the live config.

There is no client-side equivalent for the server-only config. GetServerConfig is server-side only.

UI

OpenInventory

Open a secondary inventory locally. Honors every per-type security gate (distance, lock, ownership, access). Use the server-side OpenInventory export to bypass those checks.

exports.one_inventory:OpenInventory(invType, data)

invType

string required

One of stash, shop, crafting, drop, vehicle:trunk, vehicle:glovebox, player, license.

data

string | number | table

Identifier shorthand or full data table - meaning varies by invType (see below).

Returns: boolean.

Vehicle inventories resolve locally: vehicle:glovebox opens the seated vehicle (no id), vehicle:trunk opens the nearest vehicle within interact distance while the ped is not seated.backpack and dumpster are intentionally rejected here: backpacks open from inside an existing inventory, dumpsters from the world interaction loop.

Data fields (per `invType`)

`invType`	Data
`stash`	`{ id, owner?, slots?, maxWeight?, label?, groups? }` - `slots` / `maxWeight` apply on auto-create AND live-resize
`shop`	`'<shop name>'`
`crafting`	`'<bench name>'`
`drop`	`'<drop id>'`
`vehicle:trunk`	omit - nearest vehicle
`vehicle:glovebox`	omit - seated vehicle
`player`	`<target server id>`
`license`	`'<license name>'`

Examples

The owner field controls how the stash contents are isolated. groups optionally gates access by job. slots, maxWeight, and label apply on auto-create AND resize an already-loaded stash live.

`owner`	Flavour	Behaviour
omit / `false`	Shared	One bucket. Everyone with access sees the same contents.
`true`	Per-player	Per-opener private bucket, keyed automatically by the opener's identifier.
`'<identifier>'`	Owned	Identifier should match with this one on server

exports.one_inventory:OpenInventory('stash', { id = 'evidence_locker' })

exports.one_inventory:OpenInventory('stash', {
  id    = 'personal_storage',
  owner = true,
})

exports.one_inventory:OpenInventory('stash', {
  id     = 'police_armory',
  groups = { { name = 'police', minGrade = 0 } },
})

-- Auto-creates a 100-slot warehouse OR live-resizes one that already exists.
exports.one_inventory:OpenInventory('stash', {
  id        = 'warehouse',
  label     = 'Warehouse',
  slots     = 100,
  maxWeight = 200000,
})

exports.one_inventory:OpenInventory('shop', 'ammunation')

exports.one_inventory:OpenInventory('crafting', 'workbench')

-- Glovebox: opens the vehicle you're seated in (no id needed)
exports.one_inventory:OpenInventory('vehicle:glovebox')

-- Trunk: opens the nearest vehicle while NOT seated
exports.one_inventory:OpenInventory('vehicle:trunk')

exports.one_inventory:OpenInventory('drop', 'drop_xxx')

exports.one_inventory:OpenInventory('player', targetServerId)

exports.one_inventory:OpenInventory('license', 'weapon_license')

OpenNearbyInventory

Open the inventory of the nearest player within a 3m radius (the police "search nearby" feature). No-op if no eligible player is found.

exports.one_inventory:OpenNearbyInventory()

Returns: boolean.

CloseInventory

Close the inventory if it's open (no-op otherwise). Runs the full player-facing close: hides the NUI, releases the server-side viewers, and cleans up whatever secondary is open (vehicle doors / anim, stash, drop, backpacks, dumpster, player search).

exports.one_inventory:CloseInventory()

This is a forced close. Unlike the Escape key, it ignores the craft / action-busy guards and closes regardless.

SetCanOpenInventory

Lock or unlock the player's ability to open the inventory. While locked, the keybind, every interaction (stash, shop, crafting, dumpster, trunk, glovebox) and the hotbar (both showing it and its 1-5 quick-use keys) are all blocked. The typical use is locking the inventory while another resource's UI is open.

exports.one_inventory:SetCanOpenInventory(allowed)

allowed

boolean required

false locks opening, true restores it.

Locking also hides the hotbar if it's currently on screen. It does not close an already-open inventory; pair it with CloseInventory for that. Server-forced opens (admin inspect, the server-side OpenInventory export) still bypass the lock.

CanOpenInventory

Whether the player can currently open the inventory (see SetCanOpenInventory).

exports.one_inventory:CanOpenInventory()

Returns: boolean.

UseItemInSlot

Trigger the standard "use item" flow on the given slot. Returns true only when the server actually consumed / used the item: filled slot, item registered usable, no hook or definition guard blocked it.

exports.one_inventory:UseItemInSlot(slot)

slot

number required

Slot index to use (coerced via tonumber).

Returns: boolean.

ShowItemMetadata

Register metadata key -> label mappings so an item whose metadata contains that key renders an extra tooltip line with the configured label.

exports.one_inventory:ShowItemMetadata(data, label, item)

data

string | table required

The mapping(s): a single key string, a { key = label } map, or a { { key, label }, ... } array.

label

string

Label to use, only when data is a single key string.

item

string

Restrict the labels to this item only. Omit to apply them to all items.

Returns: boolean - true when at least one mapping was registered.

Hooks

Cancellable beforeX hooks.

Events

Client-side events.