The den shop

phantom.aj.denShopThings you own

Players' den shops.

Scripts and plugins

A script has all of it, as phantom.aj.denShop, 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
`buy()`	Buys a listing from someone else's den shop, as the shop's buy button does (`requestStoreBuy`, `dsb`), and resolves with what it cost and the balance left.	`game:act`
`close()`	Closes the den shop window, if one is open (`ShopManager.ifShopToSellOpenCloseIt`).	`game:act`
`forSale()`	Everything for sale in every den shop in the den on screen, with each shop's token.	`game:act`
`inDen()`	The den shop stands placed in the den on screen; none outside a den.	`game:read`
`list()`	Lists one of the player's own items in their den shop, or prices one already listed again, as the den shop editor does (`requestStoreUpdateItems`, `dsu`).	`game:act`
`offering()`	A den shop's listings and version token, the player's own or someone else's (`ShopToSellXtCommManager.requestStoreInfo`, `dsi`).	`game:act`
`open()`	Opens the den shop window for a stand in the den on screen, as clicking it does (`ShopManager.launchDenShopStore`).	`game:act`
`unlist()`	Takes one of the player's listings down.	`game:act`
`update()`	Several changes to the player's own den shop in the one request the editor sends, resolving with the shop's new token once the server took them.	`game:act`
`onBuy()`	Hears every purchase the player makes from a den shop, whoever asked for it.	`game:read`
`onChange()`	Hears every answer to a change of the player's own den shop.	`game:read`
`onOffering()`	Hears every den shop's listings arrive, whoever asked: the player opening a stand, this area, a plugin.	`game:read`
`onSale()`	Hears one of the player's own listings sell.	`game:read`

Methods

`buy`

methodplugins · game:act

TypeScript

buy(line: DenShopLine, options?: ActOptions) => Promise<DenShopPurchase>

Buys a listing from someone else's den shop, as the shop's buy button does (requestStoreBuy, dsb), and resolves with what it cost and the balance left. Without the line's state the shop is read afresh first, and a listing gone or repriced since is refused rather than bought.

Throws REFUSED for the player's own shop, for not enough gems or diamonds, for no room left for clothing or pets, and when the server refuses (sold, or the shop changed).

Parameters

Name	Type
`line`	`DenShopLine`
`options` optional	`ActOptions`

Returns

Promise<DenShopPurchase>

Types

DenShopPurchase · ActOptions · DenShopLine

`close`

methodplugins · game:act

TypeScript

close(options?: ActOptions) => Promise<void>

Closes the den shop window, if one is open (ShopManager.ifShopToSellOpenCloseIt).

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`forSale`

methodplugins · game:act

TypeScript

forSale(options?: ActOptions) => Promise<DenShopLine[]>

Everything for sale in every den shop in the den on screen, with each shop's token.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<DenShopLine[]>

Types

DenShopLine · ActOptions

`inDen`

methodplugins · game:read

TypeScript

inDen() => Promise<DenShopStand[]>

The den shop stands placed in the den on screen; none outside a den.

Returns

Promise<DenShopStand[]>

Types

DenShopStand

`list`

methodplugins · game:act

TypeScript

list(storeInvId: number, listing: { item: DenShopItem; cost: number; currency?: DenShopCurrency | undefined; }, options?: DenShopChangeOptions) => Promise<DenShopChanged>

Lists one of the player's own items in their den shop, or prices one already listed again, as the den shop editor does (requestStoreUpdateItems, dsu). A listed item cannot be worn, placed or recycled until it is taken down.

Parameters

Name	Type
`storeInvId`	`number`
`listing`	`{ item: DenShopItem; cost: number; currency?: DenShopCurrency \| undefined; }`
`options` optional	`DenShopChangeOptions`

Returns

Promise<DenShopChanged>

Types

DenShopChangeOptions · DenShopChanged · DenShopCurrency · DenShopItem

Example

TypeScript

await phantom.aj.denShop.list(4, { item: { kind: 'den-item', invIdx: 12 }, cost: 500 });

Run in Phantom

`offering`

methodplugins · game:act

TypeScript

offering(ownerUserName: string, storeInvId: number, options?: ActOptions) => Promise<DenShopContents>

A den shop's listings and version token, the player's own or someone else's (ShopToSellXtCommManager.requestStoreInfo, dsi). Throws REFUSED for a shop the server has no record of.

Parameters

Name	Type
`ownerUserName`	`string`
`storeInvId`	`number`
`options` optional	`ActOptions`

Returns

Promise<DenShopContents>

Types

ActOptions · DenShopContents · DenShopListing · DenShopItemKind · DenShopCurrency · DenShopClothingLook · DenShopDenItemLook · DenShopPetLook · DenShopItem

Example

TypeScript

const shop = await phantom.aj.denShop.offering('jam', 4);
for (const listing of shop.listings) console.log(listing.defId, listing.cost, listing.currency);

Run in Phantom

`open`

methodplugins · game:act

TypeScript

open(storeInvId: number, options?: ActOptions) => Promise<void>

Opens the den shop window for a stand in the den on screen, as clicking it does (ShopManager.launchDenShopStore). Throws REFUSED for a stand that is not there.

Parameters

Name	Type
`storeInvId`	`number`
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`unlist`

methodplugins · game:act

TypeScript

unlist(storeInvId: number, item: DenShopItem, options?: DenShopChangeOptions) => Promise<DenShopChanged>

Takes one of the player's listings down. See update.

Parameters

Name	Type
`storeInvId`	`number`
`item`	`DenShopItem`
`options` optional	`DenShopChangeOptions`

Returns

Promise<DenShopChanged>

Types

DenShopItem · DenShopChangeOptions · DenShopChanged

`update`

methodplugins · game:act

TypeScript

update(storeInvId: number, change: DenShopUpdate, options?: DenShopChangeOptions) => Promise<DenShopChanged>

Several changes to the player's own den shop in the one request the editor sends, resolving with the shop's new token once the server took them. Throws REFUSED when the server refuses (a stale token, an item that cannot be listed) and, when the shop was read first, for more than MAX_STORE_ITEMS listings.

Parameters

Name	Type
`storeInvId`	`number`
`change`	`DenShopUpdate`
`options` optional	`DenShopChangeOptions`

Returns

Promise<DenShopChanged>

Types

DenShopUpdate · DenShopChangeOptions · DenShopChanged

Events

`onBuy`

eventplugins · game:read

TypeScript

onBuy(listener: (purchase: DenShopBought) => void) => () => void

Hears every purchase the player makes from a den shop, whoever asked for it.

Parameters

Name	Type
`listener`	`(purchase: DenShopBought) => void`

Returns

() => void. Call it to stop listening.

Types

DenShopBought

`onChange`

eventplugins · game:read

TypeScript

onChange(listener: (change: { ok: boolean; state: string | null; }) => void) => () => void

Hears every answer to a change of the player's own den shop.

Parameters

Name	Type
`listener`	`(change: { ok: boolean; state: string \| null; }) => void`

Returns

() => void. Call it to stop listening.

`onOffering`

eventplugins · game:read

TypeScript

onOffering(listener: (offering: DenShopOffering) => void) => () => void

Hears every den shop's listings arrive, whoever asked: the player opening a stand, this area, a plugin. Whose shop each is comes from the request it answers, heard on its way out.

Parameters

Name	Type
`listener`	`(offering: DenShopOffering) => void`

Returns

() => void. Call it to stop listening.

Types

DenShopOffering

`onSale`

eventplugins · game:read

TypeScript

onSale(listener: (sale: DenShopSale) => void) => () => void

Hears one of the player's own listings sell.

Parameters

Name	Type
`listener`	`(sale: DenShopSale) => void`

Returns

() => void. Call it to stop listening.

Types

DenShopSale

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.

`DenShopStand`

A den shop stand placed in the den on screen.

Field	Type
`ownerUserName`	`string`
`storeInvId`	`number`
`defId`	`number`	The stand's den item definition.

`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`

`DenShopContents`

A den shop's listings, and the version token the next change to it sends back.

Field	Type
`ownerUserName`	`string`
`storeInvId`	`number`	The shop's id: its placed stand's own `invIdx` (`inDen`).
`state`	`string`	The shop's version token; a stale one is how the server refuses a change or a purchase.
`listings`	`DenShopListing[]`

`DenShopListing`

One listing in a den shop.

TypeScript

type DenShopListing = DenShopItem & {
  /** The item's own definition id. */
  defId: number;
  cost: number;
  currency: DenShopCurrency;
  /**
   * Which one of the item it is: the colour of clothing, the version and masterpiece of a den item,
   * the look and name of a pet. Null in the player's own shop, where the server leaves it out
   * (the client has those items already; `phantom.aj.inventory.all` has their looks).
   */
  look: DenShopLook | null;
}

Run in Phantom

`DenShopItemKind`

What kind of thing a den shop listing is (Iitem.itemType).

TypeScript

type DenShopItemKind = 'den-item' | 'pet' | 'clothing'

`DenShopCurrency`

What a den shop price is paid in.

TypeScript

type DenShopCurrency = 'gems' | 'diamonds'

`DenShopClothingLook`

What a clothing listing's own tail says it looks like: the one colour the seller owns it in.

onDenStoreInfo hands the field straight to item.Item.init's third argument, which the client keeps as Item._color and passes to item.SimpleIcon.init to paint the icon with (Item.makeSmallIcon). So it is the same packed colour every other one on the wire is, and nothing has to be converted to draw with it.

Field	Type
`kind`	`"clothing"`
`color`	`number`	The colour the seller owns it in, packed as one number.

`DenShopDenItemLook`

What a den item listing's own tail says it looks like: which of its looks, and, when it is a masterpiece, the drawing hung in it and who drew it.

onDenStoreInfo hands the five fields to den.DenItem.init as its version, isApproved, uniqueImageId, uniqueImageCreatorDbId and uniqueImageCreatorUUID. They are the five den.masterpiece-items reads, in the same order.

Field	Type
`kind`	`"den-item"`
`version`	`number`	Which of the item's looks is drawn, for the ones that have several.
`approved`	`boolean`	Whether Animal Jam has approved a masterpiece's drawing; an empty field is the only false.
`uniqueImageId`	`string`	The id `loader.MasterpieceFileServer` loads a drawing by; empty for an ordinary item.
`uniqueImageCreatorDbId`	`number`	A masterpiece's creator, by their account id.
`uniqueImageCreatorUUID`	`string`	A masterpiece's creator, by their account's uuid.

`DenShopPetLook`

What a pet listing's own tail says it looks like: its packed look, what it likes, its name and its mastery counter.

onDenStoreInfo hands the first eight to pet.PetItem.init as its createdTs, the three numbers of petBits, traitDefId, toyDefId, foodDefId and petName, then reads a ninth field on its own. That ninth is the mastery counter: onDenStoreBuy reads the same nine in the same order and gives the ninth to PetManager.insertPetItem, which stores it as masteryCounter. onDenStoreInfo reads it into a local it never uses again, so the shop window throws it away.

Field	Type
`kind`	`"pet"`
`createdTs`	`number`	When it was adopted, in seconds since the epoch (`PetItem._createdTs`, a Number).
`lBits`	`number`	The first of the packed look's numbers (`PetManager.packPetBits`); its low byte is the def id.
`uBits`	`number`	The second of the packed look's numbers.
`eBits`	`number`	The third of the packed look's numbers.
`personalityDefId`	`number`	The def id of its personality (`PetItem._traitDefId`).
`favoriteToyDefId`	`number`	The def id of its favourite toy.
`favoriteFoodDefId`	`number`	The def id of its favourite food.
`name`	`string`	The name its owner gave it; empty for an egg that has not hatched.
`masteryCounter`	`number`	Its mastery counter, as the client stores it. What it counts is unknown.

`DenShopItem`

One item by kind and its place in its owner's inventory: what names a listing.

Field	Type
`kind`	`DenShopItemKind`
`invIdx`	`number`	The item's place in its owner's inventory (`Iitem.invIdx`).

`DenShopLine`

One thing for sale in a den shop, with whose shop it is in: what buy takes.

TypeScript

type DenShopLine = DenShopListing & {
  ownerUserName: string;
  storeInvId: number;
  /** The shop's version token as it was read. Left out, `buy` reads the shop afresh. */
  state?: string;
}

`DenShopChangeOptions`

A change to the player's own den shop: how long it may take, and the token to send.

TypeScript

type DenShopChangeOptions = ActOptions & {
  /**
   * The shop's version token, from `offering` or the last change. Left out, the shop is read
   * afresh first, which costs one more ask and never sends a stale token.
   */
  state?: string;
}

`DenShopChanged`

What a change to the player's own den shop left.

Field	Type
`storeInvId`	`number`
`state`	`string`	The shop's new version token, for the next change.

`DenShopUpdate`

Several changes to the player's own den shop, sent as the one request the editor sends.

Field	Type
`list` optional	`readonly { item: DenShopItem; cost: number; currency?: DenShopCurrency \| undefined; }[] \| undefined`	Items to list, or listings to price again.
`unlist` optional	`readonly DenShopItem[] \| undefined`	Listings to take down.

`DenShopPurchase`

What buying from a den shop did.

Field	Type
`item`	`DenShopItem`
`defId`	`number`
`cost`	`number`
`currency`	`DenShopCurrency`
`newInvIdx`	`number`	The item's place in the player's own inventory now.
`balance`	`number`	The player's balance in `currency` afterwards.

`DenShopOffering`

A den shop's listings arriving, whoever asked for them.

TypeScript

type DenShopOffering = Omit<DenShopContents, 'ownerUserName' | 'storeInvId'> & {
  /** From the request the answer belongs to; null for one asked before anyone listened. */
  ownerUserName: string | null;
  storeInvId: number | null;
}

`DenShopBought`

A purchase the player made, as the server answered it, whoever asked for it.

TypeScript

type DenShopBought = DenShopPurchase & { ownerUserName: string; storeInvId: number }

`DenShopSale`

One of the player's own listings sold, as the server tells the seller. Who bought is not said.

Field	Type
`storeInvId`	`number`
`item`	`DenShopItem`	What sold, by kind and its place in the player's inventory before it went.
`defId`	`number`
`cost`	`number`
`currency`	`DenShopCurrency`
`balance`	`number`	The player's balance in `currency` once the sale was paid in.

The den shop ​

Overview ​

Methods ​

buy ​

close ​

forSale ​

inDen ​

list ​

offering ​

open ​

unlist ​

update ​

Events ​

onBuy ​

onChange ​

onOffering ​

onSale ​

Types ​

DenShopStand ​

ActOptions ​

DenShopContents ​

DenShopListing ​

DenShopItemKind ​

DenShopCurrency ​

DenShopClothingLook ​

DenShopDenItemLook ​

DenShopPetLook ​

DenShopItem ​

DenShopLine ​

DenShopChangeOptions ​

DenShopChanged ​

DenShopUpdate ​

DenShopPurchase ​

DenShopOffering ​

DenShopBought ​

DenShopSale ​

The den shop

Overview

Methods

`buy`

`close`

`forSale`

`inDen`

`list`

`offering`

`open`

`unlist`

`update`

Events

`onBuy`

`onChange`

`onOffering`

`onSale`

Types

`DenShopStand`

`ActOptions`

`DenShopContents`

`DenShopListing`

`DenShopItemKind`

`DenShopCurrency`

`DenShopClothingLook`

`DenShopDenItemLook`

`DenShopPetLook`

`DenShopItem`

`DenShopLine`

`DenShopChangeOptions`

`DenShopChanged`

`DenShopUpdate`

`DenShopPurchase`

`DenShopOffering`

`DenShopBought`

`DenShopSale`