Inventory
constInventory:object
Defined in: server/api.d.ts:2343
Player and NPC inventories. The server holds the stock and clients project it. Native NPC default stock is censused once by its elected simulator; Inventory.set establishes scripted stock immediately. Other NPC writes require ready stock. Every operation happens at once and in full, or not at all. revision is optional everywhere: give the one you read to refuse the operation when the inventory changed since.
Type Declaration
Section titled “Type Declaration”add(
owner,request):InventoryResult
Gives an owner items of a class, 1 to 10000 at a time. item is the class GUID or the exact name the game’s own item tables use, the same spelling giveItem takes. Left-out properties mean quality 1 at full condition; metadata.quality asks for a higher tier, up to what the class is made in, and invalidQuality refuses one past it. The units join the row that already holds this class with these properties, if there is one. A player’s game announces them with its own “You received” toast unless notify is false.
Parameters
Section titled “Parameters”request
Section titled “request”amount
Section titled “amount”number
string
metadata?
Section titled “metadata?”Record<string, unknown>
notify?
Section titled “notify?”boolean
revision?
Section titled “revision?”number
Returns
Section titled “Returns”classes()
Section titled “classes()”classes():
object[]
Lists every equippable item in the compiled game catalog. Names are table identifiers; nameKey is the native localization key. Maximum quality is the same bound Inventory.add enforces.
Returns
Section titled “Returns”object[]
get(
owner):InventoryState|null
Reads a player’s or NPC’s inventory.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”InventoryState | null
A copy, or null for an owner that no longer exists.
getItemPrice()
Section titled “getItemPrice()”getItemPrice(
item,metadata?): {current:number;pristine:number; } |null
What the game prices one unit of an item at, in money units, worked out the way the game does it. pristine is the price at the best health its quality allows, current at its own health. Quality changes the price only through that health. The metadata reads as Inventory.add reads it – left out, quality 1 at full condition – so Inventory.getItemPrice(row.item, row.metadata) prices a row. This is the item’s own worth: what the game’s shopkeepers would ask depends on their terms and the haggling, and a Vendor charges whatever its script says.
Parameters
Section titled “Parameters”string
metadata?
Section titled “metadata?”Record<string, unknown>
The item’s properties, as a row’s metadata holds them.
Returns
Section titled “Returns”{ current: number; pristine: number; } | null
Null for a class the server does not know, or metadata Inventory.add would refuse.
remove()
Section titled “remove()”remove(
owner,request):InventoryResult
Takes exact units from named rows, every one of them or none. A player’s game announces the loss with its own toast unless notify is false.
Parameters
Section titled “Parameters”request
Section titled “request”notify?
Section titled “notify?”boolean
revision?
Section titled “revision?”number
Returns
Section titled “Returns”set(
owner,request):InventoryResult
Replaces an owner’s whole inventory, which is how a saved one comes back. It is never announced in the player’s game. Rows keep the ids they are given (letters, digits and -_:., up to 64) and get new ones when they have none. equipped is how many units of a gear row the body wears, up to 48 in all; their game dresses in them. Optional quickslots restores assignments and selected slots in the current native outfit; every referenced ID must occur in items. Invalid shape or missing references returns invalidQuickslots before changing anything. Omitted or null quickslots leaves assignment to the game’s normal equipment handling. Native item eligibility and slot capacity still apply. An empty list clears the inventory.
Parameters
Section titled “Parameters”request
Section titled “request”harvested?
Section titled “harvested?”boolean
object[]
quickslots?
Section titled “quickslots?”InventoryQuickslots | null
revision?
Section titled “revision?”number
Returns
Section titled “Returns”setItemName()
Section titled “setItemName()”setItemName(
item,name):string[]
Changes what every player’s game calls an item, in their inventory, the shops, loot and anywhere else the game names it; null gives the game its own name back. Every player sees it, including those who join later, until the server stops.
The game does not name classes one by one: many classes show the same name – every kite shield is a Kite Shield – and renaming one renames all of them. The result lists them. A name is up to 128 bytes with no control characters, and is not translated.
Parameters
Section titled “Parameters”string
string | null
Returns
Section titled “Returns”string[]
The GUIDs of every class that now shows this name.
setProperties()
Section titled “setProperties()”setProperties(
owner,request):InventoryResult
Replaces a row’s properties. The row keeps its identity and amount. It replaces rather than merges: carry over anything you want to keep, and give health or condition, not two that disagree.
Parameters
Section titled “Parameters”request
Section titled “request”string
metadata
Section titled “metadata”Record<string, unknown>
revision?
Section titled “revision?”number
Returns
Section titled “Returns”transfer()
Section titled “transfer()”transfer(
source,target,request):InventoryResult
Moves exact units between players or NPCs with their properties, all or nothing. They join matching rows in the target, so the target’s row ids are the ones in the result’s items. The script decides access, distance and consent. Players’ games announce what they lost and gained unless notify is false.
Parameters
Section titled “Parameters”source
Section titled “source”target
Section titled “target”request
Section titled “request”notify?
Section titled “notify?”boolean
sourceRevision?
Section titled “sourceRevision?”number
targetRevision?
Section titled “targetRevision?”number
Returns
Section titled “Returns”updateCustom()
Section titled “updateCustom()”updateCustom(
player,request):InventoryResult
Updates only named custom fields. Null resets a display override or clears data. Supplied data replaces the old object. The whole row keeps its identity, amount and native properties.
Parameters
Section titled “Parameters”player
Section titled “player”request
Section titled “request”Record<string, unknown> | null
description?
Section titled “description?”string | null
string
string | null
revision?
Section titled “revision?”number