Inventory
phantom.aj.inventoryThings you own
What the player owns: clothing and den items, wearing, recycling.
Scripts and plugins
A script has all of it, as phantom.aj.inventory, and so does a plugin, from ctx.phantom(): the SDK runs in the plugin's own frame. Each call is marked with what it needs: game:read for what the area knows and hears, which "game": "read" in the manifest grants, and game:act for doing things in it as the player, which needs "game": "act" (see Permissions).
Overview
| Member | What it does | Plugins |
|---|---|---|
all() | Every item the player owns that passes filter, newest first; none before the client has the list (before login). | game:read |
avatarSlots() | The player's avatars and the slot (avInvId) item lists name each by. | game:read |
canWear() | Whether the avatar being played can wear an item (ItemXtCommManager.canUseItem): its animal, land or ocean, and membership. | game:read |
change() | Puts items on the avatar being played and takes others off, in the one request the avatar editor sends (ItemXtCommManager.requestItemUse), and resolves once the server agreed. | game:act |
get() | One owned item by its invId, or null when the player has no such item. | game:read |
have() | How many of one item the player owns and where they are, optionally in one colour. | game:read |
limits() | How many items the player may hold and holds; null before a world is joined. | game:read |
prize() | The prize the server last offered and the client has not shown yet, or null. | game:read |
recycle() | Recycles items for gems (ItemXtCommManager.requestItemRecycle, ir), as the recycle screen's button does, and resolves with what the server took. | game:act |
reload() | Asks the server for the player's whole item list again (ItemXtCommManager.requestItemListForAvatar), as the client does at login, and resolves with the items once it arrived. | game:act |
takeOff() | Takes items off the avatar being played. | game:act |
wear() | Puts items on the avatar being played. | game:act |
wearableBy() | The animals (avTypeIds) that can wear an item; none for an item with no definition. | game:read |
onChange() | Hears items come and go and be put on and taken off, as the server tells the client: a purchase, a trade, a gift, a recycle, the avatar editor. | game:read |
onPoint() | Hears the mouse move onto an item in any of the client's item grids (the recycle screen, a trade, a player card, the avatar editor…), and off it again as null. | game:read |
onPrize() | Hears the server offer the player a prize, once the client has taken it in. | game:read |
onUse() | Hears the server answer each change of what the avatar wears, whoever asked for it. | game:read |
inventory.recycleScreen: The client's recycle screen, driven as the player drives it.
| Member | What it does | Plugins |
|---|---|---|
ask() | Presses the screen's recycle button, which asks "are you sure", and resolves with the question. | game:act |
cancel() | Answers no to the screen's question; resolves once the question is gone. | game:act |
close() | Closes the screen with its own close button; resolves once it is gone. | game:act |
confirm() | Answers yes to the screen's question, and resolves with what the server recycled. | game:act |
current() | The screen as it stands, or null while none is open. | game:read |
items() | Every item the open screen lists, in its order; none while no screen is open. | game:read |
open() | Opens the recycle screen on a list, as the room's recycle button does (RoomManagerWorld.launchRecycle), and resolves with it once its grid is built. | game:act |
scroll() | Scrolls the grid a screen up or down, or to the row holding the item at index of the list, and resolves with where it is now. | game:act |
tick() | Ticks an item to recycle, by pressing its window as the player does, scrolling the grid's building on until it is there. | game:act |
untick() | Unticks an item. | game:act |
onClose() | Hears the screen close, and whether anything was recycled while it was open. | game:read |
onDone() | Hears the screen's items recycled, as the screen saw it. | game:read |
onOpen() | Hears a recycle screen open, once its grid is built. | game:read |
onQuestion() | Hears the screen ask "are you sure", and each answer to it: yes as true, no as false. | game:read |
onTick() | Hears the player tick or untick an item, with the screen's ticks and gems after it. | game:read |
Methods
all
all(filter?: InventoryFilter) => Promise<InventoryItem[]>Every item the player owns that passes filter, newest first; none before the client has the list (before login).
Parameters
| Name | Type | |
|---|---|---|
filter optional | InventoryFilter |
Returns
Promise<InventoryItem[]>
Types
InventoryFilter · ItemPlace · InventoryItem
Example
const worn = await phantom.aj.inventory.all({ where: 'worn' });
const spareRed = await phantom.aj.inventory.all({ defId: 222, color: 0xff0000, where: 'inventory' });avatarSlots
avatarSlots() => Promise<AvatarSlot[]>The player's avatars and the slot (avInvId) item lists name each by.
Returns
Promise<AvatarSlot[]>
Types
canWear
canWear(defId: number, options?: { custom?: boolean | undefined; }) => Promise<boolean>Whether the avatar being played can wear an item (ItemXtCommManager.canUseItem): its animal, land or ocean, and membership. False for an item the client has no definition for.
Parameters
| Name | Type | |
|---|---|---|
defId | number | |
options optional | { custom?: boolean | undefined; } |
Returns
Promise<boolean>
change
change(change: WearChange, options?: ActOptions) => Promise<void>Puts items on the avatar being played and takes others off, in the one request the avatar editor sends (ItemXtCommManager.requestItemUse), and resolves once the server agreed. Throws REFUSED for an item the player does not own or has up in a den shop, and when the server says no.
Parameters
| Name | Type | |
|---|---|---|
change | WearChange | |
options optional | ActOptions |
Returns
Promise<void>
Types
Example
get
get(invId: number) => Promise<InventoryItem | null>One owned item by its invId, or null when the player has no such item.
Parameters
| Name | Type | |
|---|---|---|
invId | number |
Returns
Promise<InventoryItem \| null>
Types
have
have(defId: number, options?: { color?: number | undefined; }) => Promise<ItemHolding>How many of one item the player owns and where they are, optionally in one colour.
Parameters
| Name | Type | |
|---|---|---|
defId | number | |
options optional | { color?: number | undefined; } |
Returns
Promise<ItemHolding>
Types
Example
const { spare } = await phantom.aj.inventory.have(222);
if (spare > 0) console.log('one is free to trade');limits
limits() => Promise<InventoryLimits | null>How many items the player may hold and holds; null before a world is joined.
Returns
Promise<InventoryLimits \| null>
Types
prize
prize() => Promise<ItemPrize | null>The prize the server last offered and the client has not shown yet, or null.
Returns
Promise<ItemPrize \| null>
Types
recycle
recycle(invIds: number | readonly number[], options?: ActOptions) => Promise<RecycleResult>Recycles items for gems (ItemXtCommManager.requestItemRecycle, ir), as the recycle screen's button does, and resolves with what the server took. It cannot be undone. Throws REFUSED for no items, an item the player does not own or has up in a den shop, and when the server took none of them.
Parameters
| Name | Type | |
|---|---|---|
invIds | number | readonly number[] | |
options optional | ActOptions |
Returns
Promise<RecycleResult>
Types
Example
reload
reload(options?: ActOptions) => Promise<InventoryItem[]>Asks the server for the player's whole item list again (ItemXtCommManager.requestItemListForAvatar), as the client does at login, and resolves with the items once it arrived. Only needed when something outside the client changed them.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<InventoryItem[]>
Types
takeOff
takeOff(invIds: number | readonly number[], options?: ActOptions) => Promise<void>Takes items off the avatar being played. See change.
Parameters
| Name | Type | |
|---|---|---|
invIds | number | readonly number[] | |
options optional | ActOptions |
Returns
Promise<void>
Types
wear
wear(invIds: number | readonly number[], options?: ActOptions) => Promise<void>Puts items on the avatar being played. See change.
Parameters
| Name | Type | |
|---|---|---|
invIds | number | readonly number[] | |
options optional | ActOptions |
Returns
Promise<void>
Types
wearableBy
wearableBy(defId: number) => Promise<number[]>The animals (avTypeIds) that can wear an item; none for an item with no definition.
Parameters
| Name | Type | |
|---|---|---|
defId | number |
Returns
Promise<number[]>
Events
onChange
onChange(listener: (change: InventoryChange) => void) => () => voidHears items come and go and be put on and taken off, as the server tells the client: a purchase, a trade, a gift, a recycle, the avatar editor.
Parameters
| Name | Type | |
|---|---|---|
listener | (change: InventoryChange) => void |
Returns
() => void. Call it to stop listening.
Types
Example
phantom.aj.inventory.onChange(({ added, wornOnly }) => {
if (!wornOnly) added.forEach(({ defId }) => console.log('received', defId));
});onPoint
onPoint(listener: (item: PointedItem | null) => void) => () => voidHears the mouse move onto an item in any of the client's item grids (the recycle screen, a trade, a player card, the avatar editor…), and off it again as null.
Parameters
| Name | Type | |
|---|---|---|
listener | (item: PointedItem | null) => void |
Returns
() => void. Call it to stop listening.
Types
onPrize
onPrize(listener: (prize: ItemPrize) => void) => () => voidHears the server offer the player a prize, once the client has taken it in.
Parameters
| Name | Type | |
|---|---|---|
listener | (prize: ItemPrize) => void |
Returns
() => void. Call it to stop listening.
Types
onUse
onUse(listener: (result: { success: boolean; }) => void) => () => voidHears the server answer each change of what the avatar wears, whoever asked for it.
Parameters
| Name | Type | |
|---|---|---|
listener | (result: { success: boolean; }) => void |
Returns
() => void. Call it to stop listening.
inventory.recycleScreen
The client's recycle screen, driven as the player drives it.
ask
ask(options?: ActOptions) => Promise<RecycleQuestion>Presses the screen's recycle button, which asks "are you sure", and resolves with the question. Throws REFUSED while nothing is ticked (the button is grey).
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<RecycleQuestion>
Types
cancel
cancel(options?: ActOptions) => Promise<void>Answers no to the screen's question; resolves once the question is gone.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
close
close(options?: ActOptions) => Promise<void>Closes the screen with its own close button; resolves once it is gone.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<void>
Types
confirm
confirm(options?: ActOptions) => Promise<{ recycled: number[]; gems: number | null; }>Answers yes to the screen's question, and resolves with what the server recycled. Throws REFUSED while the screen is not asking, and when the server recycled nothing.
Parameters
| Name | Type | |
|---|---|---|
options optional | ActOptions |
Returns
Promise<{ recycled: number[]; gems: number \| null; }>
Types
current
current() => Promise<RecycleScreen | null>The screen as it stands, or null while none is open.
Returns
Promise<RecycleScreen \| null>
Types
RecycleScreen · RecycleOpenedFrom · RecycleList · RecycleQuestion · RecycleScroll
items
items() => Promise<RecycleItem[]>Every item the open screen lists, in its order; none while no screen is open.
Returns
Promise<RecycleItem[]>
Types
open
open(list: "clothing" | "den-items" | "den-audio" | "den-items-ocean" | "den-items-land" | "clothing-ocean" | "clothing-land", options?: ActOptions) => Promise<RecycleScreen>Opens the recycle screen on a list, as the room's recycle button does (RoomManagerWorld.launchRecycle), and resolves with it once its grid is built.
Parameters
| Name | Type | |
|---|---|---|
list | "clothing" | "den-items" | "den-audio" | "den-items-ocean" | "den-items-land" | "clothing-ocean" | "clothing-land" | |
options optional | ActOptions |
Returns
Promise<RecycleScreen>
Types
scroll
scroll(to: number | "down" | "up", options?: ActOptions) => Promise<RecycleScroll>Scrolls the grid a screen up or down, or to the row holding the item at index of the list, and resolves with where it is now.
Parameters
| Name | Type | |
|---|---|---|
to | number | "down" | "up" | |
options optional | ActOptions |
Returns
Promise<RecycleScroll>
Types
tick
tick(invId: number, options?: ActOptions) => Promise<RecycleScreen>Ticks an item to recycle, by pressing its window as the player does, scrolling the grid's building on until it is there. Throws REFUSED for an item the screen does not list or will not take (a masterpiece not yet approved).
Parameters
| Name | Type | |
|---|---|---|
invId | number | |
options optional | ActOptions |
Returns
Promise<RecycleScreen>
Types
untick
untick(invId: number, options?: ActOptions) => Promise<RecycleScreen>Unticks an item. See tick.
Parameters
| Name | Type | |
|---|---|---|
invId | number | |
options optional | ActOptions |
Returns
Promise<RecycleScreen>
Types
onClose
onClose(listener: (closed: RecycleClosed) => void) => () => voidHears the screen close, and whether anything was recycled while it was open.
Parameters
| Name | Type | |
|---|---|---|
listener | (closed: RecycleClosed) => void |
Returns
() => void. Call it to stop listening.
Types
onDone
onDone(listener: (done: RecycleDone) => void) => () => voidHears the screen's items recycled, as the screen saw it.
Parameters
| Name | Type | |
|---|---|---|
listener | (done: RecycleDone) => void |
Returns
() => void. Call it to stop listening.
Types
onOpen
onOpen(listener: (opened: RecycleOpened) => void) => () => voidHears a recycle screen open, once its grid is built.
Parameters
| Name | Type | |
|---|---|---|
listener | (opened: RecycleOpened) => void |
Returns
() => void. Call it to stop listening.
Types
onQuestion
onQuestion(listener: (event: RecycleQuestion | { answered: boolean; }) => void) => () => voidHears the screen ask "are you sure", and each answer to it: yes as true, no as false.
Parameters
| Name | Type | |
|---|---|---|
listener | (event: RecycleQuestion | { answered: boolean; }) => void |
Returns
() => void. Call it to stop listening.
Types
onTick
onTick(listener: (ticks: { chosen: number[]; gems: number; }) => void) => () => voidHears the player tick or untick an item, with the screen's ticks and gems after it.
Parameters
| Name | Type | |
|---|---|---|
listener | (ticks: { chosen: number[]; gems: number; }) => void |
Returns
() => void. Call it to stop listening.
Types
The types the calls above take and give, with every field. Import any of them in a plugin from @phantomclient/plugin/sdk, or use them as they are in a script.
InventoryFilter
Which owned items to give: any filter left out keeps every item.
| Field | Type | |
|---|---|---|
defId optional | number | readonly number[] | undefined | |
color optional | number | undefined | |
where optional | ItemPlace | readonly ItemPlace[] | undefined |
ItemPlace
Where an owned item is: on an avatar, up for sale in a den shop, or put away.
type ItemPlace = 'worn' | 'den-shop' | 'inventory'InventoryItem
One item of clothing the player owns, as the client holds it.
| Field | Type | |
|---|---|---|
invId | number | Its place in the player's inventory (Item.invIdx): what wearing, trading and selling name. |
defId | number | Its definition (Item.defId), for phantom.aj.shops.definition. |
color | number | The colour it is owned in, packed as one number. |
name | string | null | Its name, from its definition; null before the definitions are loaded. |
wornOn | number[] | The avatars wearing it, by avInvId (avatarSlots maps them to perUserAvId). |
worn | boolean | Whether any avatar wears it, including the client's "worn by all" for the default items. |
where | ItemPlace | |
denStoreInvId | number | null | The den shop it is listed in (Item.denStoreInvId), or null when it is not. |
membersOnly | boolean | |
recycleValue | number | The gems recycling it pays. |
ItemHolding
How many of one item the player owns, and where they are.
| Field | Type | |
|---|---|---|
count | number | |
worn | number | |
spare | number | Put away, so free to wear, trade, list or recycle. |
listed | number | Up for sale in a den shop. |
items | InventoryItem[] |
InventoryLimits
How many items the player may hold.
| Field | Type | |
|---|---|---|
maxItems | number | The most clothing the client lets the player hold (ShopManager.maxItems). |
warningItemCount | number | Where the client starts warning (ShopManager.warningItemCount). |
count | number | How many the player holds now (inventoryClothing.numItems). |
AvatarSlot
One of the player's avatars and the slot the item lists name it by.
| Field | Type | |
|---|---|---|
perUserAvId | number | |
avInvId | number | What InventoryItem.wornOn holds. |
ItemPrize
A prize the server has offered the player, as the client keeps it until it is shown.
| Field | Type | |
|---|---|---|
userVarId | number | |
defId | number | |
isClothing | boolean | |
color | number | |
name | string | null | |
description | string | null |
WearChange
What putting items on and taking them off is to do.
| Field | Type | |
|---|---|---|
wear optional | readonly number[] | undefined | Items to put on the avatar being played, by invId. |
remove optional | readonly number[] | undefined | Items to take off it, by invId. |
ActOptions
How long something that acts may take, and what may end it first.
| Field | Type | |
|---|---|---|
timeoutMs optional | number | undefined | 10 seconds by default. |
signal optional | AbortSignal | undefined |
RecycleResult
What recycling items did.
| Field | Type | |
|---|---|---|
recycled | number[] | The items the server took, by invId; a partial recycle names only those. |
gems | number | null | The player's gems afterwards; null when the server did not say. |
InventoryChange
Items coming or going, as the server tells the client (il, its "changed" form).
| Field | Type | |
|---|---|---|
userName | string | |
perUserAvId | number | |
wornOnly | boolean | Only who wears what changed; nothing came or went. |
wear | boolean | Whether the added items were put on. |
color | number | |
added | { invId: number; defId: number; }[] | |
removed | number[] |
PointedItem
The item under the mouse in one of the client's grids.
type PointedItem = ShownItem & {
/** Its place in the grid. */
index: number;
grid: ItemGrid;
/** Whether it is ticked or pressed in its grid. */
selected: boolean;
}ShownItemKind
What kind of thing an item shown in one of the client's grids is (Iitem.itemType).
type ShownItemKind = 'den-item' | 'pet' | 'clothing' | 'unknown'ItemGrid
Which of the client's item grids an item is shown in.
type ItemGrid = | 'recycle'
| 'trade'
| 'player-card'
| 'gift'
| 'trade-list-choice'
| 'trade-list'
| 'den-shop'
| 'avatar-editor'
| 'other'ShownItem
An item shown in one of the client's grids.
| Field | Type | |
|---|---|---|
kind | ShownItemKind | |
defId | number | |
invId | number | |
color | number | null | |
version | number | null | |
name | string | null | |
recycleValue | number | |
membersOnly | boolean |
RecycleScreen
The recycle screen as it stands.
| Field | Type | |
|---|---|---|
opened | RecycleOpenedFrom | |
list | RecycleList | |
listId | number | |
showing | number | How many items it lists. |
chosen | number[] | The items ticked to recycle, by invId. |
gems | number | The gems the ticked items pay. |
oneAtATime | boolean | Whether it takes one item at a time. |
recycled | boolean | Whether anything was recycled since it opened. |
thisEnvironmentOnly | boolean | Whether it lists only what belongs to this environment, land or ocean. |
question | RecycleQuestion | null | The "are you sure" popup, or null while it is not asking. |
scroll | RecycleScroll | null |
RecycleOpenedFrom
Where the recycle screen was opened from.
type RecycleOpenedFrom = 'room' | 'avatar-editor' | 'den-editor'RecycleList
The list a recycle screen shows.
type RecycleList = (typeof RECYCLE_LISTS)[keyof typeof RECYCLE_LISTS] | 'unknown'RecycleQuestion
The screen's "are you sure" popup, while it asks.
| Field | Type | |
|---|---|---|
count | number | How many items it would recycle. |
gems | number | The gems they pay. |
message | string | null | |
counter | string | null |
RecycleScroll
Where the screen's grid is scrolled to.
| Field | Type | |
|---|---|---|
position | number | |
length | number | |
windows | number | How many items the grid holds. |
perScreen | number | |
built | number | How many of them it has built so far; it builds more as it scrolls. |
RecycleItem
One item the recycle screen lists.
type RecycleItem = ShownItem & {
/** Its place in the screen's list. */
index: number;
ticked: boolean;
/** False for a masterpiece not yet approved, which cannot be recycled. */
approved: boolean;
inDenShop: boolean;
}RecycleOpened
The screen opening, with what it lists.
| Field | Type | |
|---|---|---|
list | RecycleList | |
listId | number | |
showing | number | |
oneAtATime | boolean | |
thisEnvironmentOnly | boolean |
RecycleDone
The screen's items recycled, as the screen saw it.
| Field | Type | |
|---|---|---|
list | RecycleList | |
listId | number | |
invIds | number[] | |
gems | number |
RecycleClosed
The screen closing.
| Field | Type | |
|---|---|---|
list | RecycleList | |
listId | number | |
recycled | boolean |