Server

Last updated on

local inventory = OPX.Api.Get('inventory')

From server code inside opx_infinity.

• A target is a player id (their loaded character's bag) or a citizen id (also reaches an offline bag: loaded for the call, then written and released).
• Every function that takes a target, a vehicle or a container yields: call it from a thread.
• A Result is { ok = true, value } or { ok = false, error, detail }. Codes: Refusal codes.

CreateThread(function()
    local inventory = OPX.Api.Get('inventory')
    local result = inventory.AddItem(source, 'water', 2)
    if not result.ok then print('refused: ' .. result.error) end
end)

AddItem

Adds items. Adds nothing on no_room / too_heavy. Yields. Audited.

inventory.AddItem(target, name, count, metadata)

Parameters

• target: number|string
• name: string
• count?: integer — default 1
• metadata?: table — copied onto each unit, max MAX_METADATA_BYTES encoded

Returns

• Result — value true

RemoveItem

Takes from the last slot backwards. not_enough removes nothing. Yields.

inventory.RemoveItem(target, name, count, metadata)

Parameters

• target: number|string
• name: string
• count?: integer — default 1
• metadata?: table — nil matches any stack

Returns

• Result — value true

RemoveFromSlot

One slot only. Yields.

inventory.RemoveFromSlot(target, slot, count)

Parameters

• target: number|string
• slot: integer
• count?: integer — default the whole stack

Returns

• Result — value true

SetMetadata

Replaces the stack's metadata. Yields.

inventory.SetMetadata(target, slot, metadata)

Parameters

• target: number|string
• slot: integer
• metadata?: table — nil clears it

Returns

• Result — value true

ClearInventory

Empties the bag. Yields.

inventory.ClearInventory(target)

Parameters

• target: number|string

Returns

• Result — value true

GetItemCount

Yields.

inventory.GetItemCount(target, name, metadata)

Parameters

• target: number|string
• name: string
• metadata?: table — counts only stacks whose metadata is equal as a whole

Returns

• Result — value integer

CountWhere

Counts stacks whose metadata has every field of match. Yields.

inventory.CountWhere(target, name, match)

Parameters

• target: number|string
• name: string
• match: table — non-empty; scalar values only (a table value matches nothing)

Returns

• Result — value integer

local keys = inventory.CountWhere(source, 'vehicle_key', { plate = 'ABC123' })
if keys.ok and keys.value > 0 then --[[ has a key ]] end

RemoveWhere

Takes every unit of name whose metadata carries all fields of match (plain values only), whatever its other fields. Used to revoke keys. Yields for an offline bag. Audited inventory.removeWhere.

inventory.RemoveWhere(target, name, match)

Parameters

• target: number|string
• name: string
• match: table

Returns

• Result — value integer (units taken)

HasItem

Ignores metadata. Yields.

inventory.HasItem(target, name, count)

Parameters

• target: number|string
• name: string
• count?: integer

Returns

• Result — value boolean

CanCarry

Checks slots and weight. Gives no reason when false. Yields.

inventory.CanCarry(target, name, count, metadata)

Parameters

• target: number|string
• name: string
• count?: integer
• metadata?: table

Returns

• Result — value boolean

GetInventory

Yields.

inventory.GetInventory(target)

Parameters

• target: number|string

Returns

• Result — value { id, kind, title, slots, maxWeight, weight, items }
  • items: { slot, name, count, metadata }[]
  • For a very large container, metadata other than serial, ammo, durability, label, description may be trimmed.

GetSlot

A copy. Yields.

inventory.GetSlot(target, slot)

Parameters

• target: number|string
• slot: integer

Returns

• Result — value { slot, name, count, metadata } or nil

AddToStash

Adds to a stash by its storage key, loading it without opening it. Yields. Audited inventory.stashAdd.

inventory.AddToStash(name, item, count, metadata, options)

Parameters

• name: string
• item: string
• count?: integer
• metadata?: table
• options?: table — { creator, cap } (what the export passes); limits creation
  • A missing stash is created at the configured size (or 50 slots / 100 000 g).
  • With options: only configured stashes, or names <creator>.<name> while the creator holds fewer than cap (default 25, counted in the database); else stash_namespace / stash_cap.

Returns

• Result — value true

RemoveFromStash

Never creates a stash: a missing one answers not_enough. Yields. Audited inventory.stashRemove.

inventory.RemoveFromStash(name, item, count, metadata)

Parameters

• name: string
• item: string
• count?: integer
• metadata?: table — nil matches any stack

Returns

• Result — value true

CountInStash

0 for a stash that does not exist (none is created). Yields.

inventory.CountInStash(name, item, metadata)

Parameters

• name: string
• item: string
• metadata?: table

Returns

• Result — value integer

OpenStash

Opens a stash beside the player's bag and raises their screen. Yields. The caller decides who may open it; this checks that the player can act (not down: dead; past the readiness gate: not_ready) and reach, the latter only when position is given.

inventory.OpenStash(playerId, name, options)

Parameters

• playerId: number
• name: string
• options?: table
  • slots: default 50
  • maxWeight: default 100000
  • label, position ({ x, y, z }), bucket

Returns

• Result — value: container id

inventory.OpenStash(source, 'police_evidence', {
    label = 'Evidence', position = { x = 10.0, y = 20.0, z = 7.5 },
})

AddToTrunk

Adds to a vehicle's trunk. Yields. A locked vehicle refuses (locked). With source, an owned trunk answers to its owner only while TRUNK_OWNER_ONLY is on (not_yours). No reach check.

inventory.AddToTrunk(vehicleId, name, count, metadata, source)

Parameters

• vehicleId: number|string — the host id (number or decimal string)
• name: string
• count?: integer
• metadata?: table
• source?: number

Returns

• Result — value true

RemoveFromTrunk

Same rules as AddToTrunk. Yields.

inventory.RemoveFromTrunk(vehicleId, name, count, metadata, source)

Parameters

• vehicleId: number|string
• name: string
• count?: integer
• metadata?: table — nil matches any stack
• source?: number

Returns

• Result — value true

CountInTrunk

Same rules as AddToTrunk. Yields.

inventory.CountInTrunk(vehicleId, name, metadata, source)

Parameters

• vehicleId: number|string
• name: string
• metadata?: table
• source?: number

Returns

• Result — value integer

TrunkLocked

Whether the trunk is shut to everybody. Does not yield. Not a Result.

inventory.TrunkLocked(vehicleId)

Parameters

• vehicleId: number|string

Returns

• boolean — false when the host cannot answer

GetItem

Does not yield. Not a Result.

inventory.GetItem(name)

Parameters

• name: string

Returns

• table? — { label, description, weight, image, usable, stackable, droppable, category, weapon, ammo }; weapon and ammo are booleans

GetItems

The whole catalogue. Does not yield. Not a Result.

inventory.GetItems()

Returns

• { [name] = item } — same shape as GetItem

Holders

Database read, largest stacks first. Yields.

inventory.Holders(name, limit)

Parameters

• name: string
• limit?: integer — 1–200, default 20

Returns

• Result — value { id, kind, owner, slot, count }[]

ResizeContainer

The only way to change a stored container's size. Stacks past the new slot count are kept but not drawn. A container it had to load (an offline bag, an unopened stash) is put away again afterwards. Yields.

inventory.ResizeContainer(kind, owner, slots, maxWeight)

Parameters

• kind: string
• owner: string
• slots: integer — 1–200
• maxWeight: integer — grams

Returns

• Result — value: container id; bad_argument when kind is not a string

DeleteContainer

Deletes the row and everything in it. Refuses memory-only containers. Yields.

inventory.DeleteContainer(kind, owner)

Parameters

• kind: string — a container kind
• owner: string

Returns

• Result — value true; bad_argument when kind is not a string

CloseInventory

Closes the player's screen and the second container.

inventory.CloseInventory(playerId)

Parameters

• playerId: number

Returns

• Result — value true

RegisterUsable

Sets the function called when the item is used. The last registration wins. Not called for weapons or ammunition.

inventory.RegisterUsable(name, handler, owner)

Parameters

• name: string
• handler: function — handler(source, info)
  • info: { name, slot, count, metadata, label, citizenId }
  • Must return { ok = true, consume? } or { ok = false, error? } within USE_HANDLER_MS. Runs on its own thread and may yield.
  • consume overrides USE.CONSUME.
• owner?: string

Returns

• ok: boolean, code: string?

inventory.RegisterUsable('lockpick', function(source, info)
    if not nearDoor(source) then return { ok = false, error = 'too_far' } end
    return { ok = true, consume = 0 }
end, 'mymodule')

UnregisterUsable

Removes the handler only if owner matches the one that registered it.

inventory.UnregisterUsable(name, owner)

Parameters

• name: string
• owner?: string

Returns

• boolean

UsableOwner

Who handles the use of an item.

inventory.UsableOwner(name)

Returns

• string? — the owner given at registration

UnregisterUsables

Removes every use handler one owner registered. The creator surface calls it when a resource stops.

inventory.UnregisterUsables(owner)

Returns

• integer — how many went

RegisterItem

Adds an item to the catalogue at runtime, on the server and every client, or replaces one its own owner registered. Validated whole by Catalog.Register, which both halves run; sent to a client that joins later on its hello. Never a weapon or ammunition, never a name config or another owner holds. Not persisted. The RegisterItem export is the door for another resource.

inventory.RegisterItem(name, definition, owner, cap)

Parameters

• name: string
• definition: table — { label?, description?, weight?, stack?, drop?, category?, image?, model?, use? } (lower case); use.status holds at most 8 needs
• owner: string
• cap?: integer — most items this owner may hold registered (default 64)

Returns

• Result — the item as GetItem reads it; errors bad_name, bad_owner, item_taken, item_cap, bad_definition:<field>

Withdraw

Balance → eddies items. Yields. See Eddies as an item.

inventory.Withdraw(source, amount)

Parameters

• source: number
• amount: integer — 1 to CURRENCY.MAX_WITHDRAW

Returns

• ok: boolean, code: string?

Deposit

eddies in that bag slot → balance. Yields.

inventory.Deposit(source, slot, count)

Parameters

• source: number
• slot: integer
• count?: integer — default the whole stack

Returns

• ok: boolean, code: string?

CurrencyWired

Whether the money bridge is on.

local wired, item, moneyType = inventory.CurrencyWired()

Returns

• wired: boolean, item: string, moneyType: string

GetHeldWeapon

The weapon this module put in the player's hands. Not a Result.

inventory.GetHeldWeapon(playerId)

Parameters

• playerId: number

Returns

• { name, serial, slot } or nil

HolsterWeapon

Puts away the weapon this module put in the player's hands, reading its rounds back into the bag first. The one way another module may holster somebody; the admin /opx.admin.weapon.holster goes through it.

inventory.HolsterWeapon(playerId)

Parameters

• playerId: number

Returns

• Result — value { name, serial }; errors bad_argument, not_armed

local put = inventory.HolsterWeapon(target)
if not put.ok and put.error == 'not_armed' then print('unarmed') end