Gems and diamonds

phantom.aj.currencyYou and your animal

Gems, diamonds and tickets.

Scripts and plugins

A script has all of it, as phantom.aj.currency, 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 currency the client keeps, in `UserCurrency` order, with the balance it shows; `amount` is null for one it has no figure for yet.	`game:read`
`canAfford()`	Whether the player can pay, decided as the client's own price tags decide it (`UserCurrency.hasEnoughCurrency`).	`game:read`
`crafting()`	The crafting currencies, as the client lists them (`UserCurrency.usableCraftTypes`).	`game:read`
`diamondDefinitionId()`	The diamond catalogue row selling something (`getDiamondDefIdByRefId`), by what it is and its own definition id; null when it is not sold for diamonds or the catalogue has not loaded.	`game:read`
`diamondsLoaded()`	Whether the client has loaded the diamond catalogue (`DiamondXtCommManager.diamondDefsLoaded`).	`game:read`
`donateGems()`	Donates gems (`requestDonateGems`), as the donation screens do, and resolves with the amount once the server took it.	`game:act`
`exchange()`	Exchanges one currency for another at an exchange shop, as its buy button does (`requestCurrencyExchange`), and resolves once the server agreed, with the balance it set.	`game:act`
`exchangeDefinition()`	A row of a currency exchange shop's catalogue (`ItemXtCommManager.getCurrencyExchangeDef`): what it takes and what it gives.	`game:read`
`get()`	The balance the client shows (`UserCurrency.getCurrency`), or null before it has one.	`game:read`
`priceParts()`	A price in several currencies at once (`4x10,6x5`), in parts.	`game:read`
`redeemCode()`	Redeems a code (`GameRedemptionXtCommManager.requestRedeemCode`), as the redemption popup does, and resolves with what it gave.	`game:act`
`onChange()`	Hears each balance move: the server's `currency.update` (with its reason) and every balance the client sets itself (a prize a screen pays out at once), told once each.	`game:read`
`onDonate()`	Hears every gem donation the server answers, whoever asked: whether it went through.	`game:read`
`onExchange()`	Hears every currency exchange the server answers, whoever asked: whether it went through.	`game:read`
`onMembershipRedeemed()`	Hears a membership redeemed on the account (`currency.membership-redeemed` with result 1).	`game:read`
`onRedeem()`	Hears every answer to a code, whoever sent it: `redeemCode` or the game's own popup.	`game:read`

Methods

`all`

methodplugins · game:read

TypeScript

all() => Promise<(CurrencyRef & { amount: number | null; })[]>

Every currency the client keeps, in UserCurrency order, with the balance it shows; amount is null for one it has no figure for yet.

Returns

Promise<(CurrencyRef & { amount: number \| null; })[]>

Types

CurrencyRef

`canAfford`

methodplugins · game:read

TypeScript

canAfford(price: number, currency: CurrencyKey) => Promise<boolean>
canAfford(price: string, part?: CurrencyKey | undefined) => Promise<boolean>

Whether the player can pay, decided as the client's own price tags decide it (UserCurrency.hasEnoughCurrency). A number is a price in the currency named; a string is a combined price (4x10,6x5), all of it, or only its currency part when one is named. False before the client has balances.

Parameters

Name	Type
`price`	`number`
`currency`	`CurrencyKey`

Returns

Promise<boolean>

Types

CurrencyKey

Example

TypeScript

await phantom.aj.currency.canAfford(500, 'gems');
await phantom.aj.currency.canAfford('4x10,6x5');

Run in Phantom

`crafting`

methodplugins · game:read

TypeScript

crafting() => Promise<CurrencyRef[]>

The crafting currencies, as the client lists them (UserCurrency.usableCraftTypes).

Returns

Promise<CurrencyRef[]>

Types

CurrencyRef

`diamondDefinitionId`

methodplugins · game:read

TypeScript

diamondDefinitionId(refDefId: number, type: number | "den" | "pet" | "denItem" | "item" | "avatar") => Promise<number | null>

The diamond catalogue row selling something (getDiamondDefIdByRefId), by what it is and its own definition id; null when it is not sold for diamonds or the catalogue has not loaded.

Parameters

Name	Type
`refDefId`	`number`
`type`	`number \| "den" \| "pet" \| "denItem" \| "item" \| "avatar"`

Returns

Promise<number \| null>

`diamondsLoaded`

methodplugins · game:read

TypeScript

diamondsLoaded() => Promise<boolean>

Whether the client has loaded the diamond catalogue (DiamondXtCommManager.diamondDefsLoaded).

Returns

Promise<boolean>

`donateGems`

methodplugins · game:act

TypeScript

donateGems(amount: number, options?: ActOptions) => Promise<number>

Donates gems (requestDonateGems), as the donation screens do, and resolves with the amount once the server took it. Throws REFUSED when the player has too few or the server says no.

Parameters

Name	Type
`amount`	`number`
`options` optional	`ActOptions`

Returns

Promise<number>

Types

ActOptions

`exchange`

methodplugins · game:act

TypeScript

exchange(shopId: number, exchangeDefId: number, options?: ActOptions) => Promise<CurrencyExchange>

Exchanges one currency for another at an exchange shop, as its buy button does (requestCurrencyExchange), and resolves once the server agreed, with the balance it set. Throws REFUSED when the player cannot pay (checked first, as the shop does) or the server says no. It spends the player's currency and cannot be undone.

Parameters

Name	Type
`shopId`	`number`
`exchangeDefId`	`number`
`options` optional	`ActOptions`

Returns

Promise<CurrencyExchange>

Types

ActOptions · CurrencyExchange · CurrencyAmount

Example

TypeScript

await phantom.aj.currency.exchange(1051, 31);

Run in Phantom

`exchangeDefinition`

methodplugins · game:read

TypeScript

exchangeDefinition(defId: number) => Promise<CurrencyExchangeDefinition | null>

A row of a currency exchange shop's catalogue (ItemXtCommManager.getCurrencyExchangeDef): what it takes and what it gives. Null when the client has no such row.

Parameters

Name	Type
`defId`	`number`

Returns

Promise<CurrencyExchangeDefinition \| null>

Types

CurrencyExchangeDefinition

`get`

methodplugins · game:read

TypeScript

get(currency: CurrencyKey) => Promise<number | null>

The balance the client shows (UserCurrency.getCurrency), or null before it has one.

Parameters

Name	Type
`currency`	`CurrencyKey`

Returns

Promise<number \| null>

Types

CurrencyKey

`priceParts`

methodplugins · game:read

TypeScript

priceParts(price: string) => PricePart[]

A price in several currencies at once (4x10,6x5), in parts. See priceParts.

Parameters

Name	Type
`price`	`string`

Returns

PricePart[]

Types

PricePart

`redeemCode`

methodplugins · game:act

TypeScript

redeemCode(code: string, options?: RedeemOptions) => Promise<RedeemedCode>

Redeems a code (GameRedemptionXtCommManager.requestRedeemCode), as the redemption popup does, and resolves with what it gave. Throws REFUSED with the client's own reason: not valid, for another game, captcha needed (pass captcha)…

Parameters

Name	Type
`code`	`string`
`options` optional	`RedeemOptions`

Returns

Promise<RedeemedCode>

Types

RedeemOptions · RedeemedCode

Events

`onChange`

eventplugins · game:read

TypeScript

onChange(listener: (change: CurrencyChange) => void) => () => void

Hears each balance move: the server's currency.update (with its reason) and every balance the client sets itself (a prize a screen pays out at once), told once each. A balance set to what this listener last heard is not told again.

Parameters

Name	Type
`listener`	`(change: CurrencyChange) => void`

Returns

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

Types

CurrencyChange

`onDonate`

eventplugins · game:read

TypeScript

onDonate(listener: (donated: boolean) => void) => () => void

Hears every gem donation the server answers, whoever asked: whether it went through.

Parameters

Name	Type
`listener`	`(donated: boolean) => void`

Returns

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

`onExchange`

eventplugins · game:read

TypeScript

onExchange(listener: (exchanged: boolean) => void) => () => void

Hears every currency exchange the server answers, whoever asked: whether it went through.

Parameters

Name	Type
`listener`	`(exchanged: boolean) => void`

Returns

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

`onMembershipRedeemed`

eventplugins · game:read

TypeScript

onMembershipRedeemed(listener: (membership: RedeemedMembership) => void) => () => void

Hears a membership redeemed on the account (currency.membership-redeemed with result 1).

Parameters

Name	Type
`listener`	`(membership: RedeemedMembership) => void`

Returns

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

Types

RedeemedMembership

`onRedeem`

eventplugins · game:read

TypeScript

onRedeem(listener: (answer: CodeAnswer) => void) => () => void

Hears every answer to a code, whoever sent it: redeemCode or the game's own popup.

Parameters

Name	Type
`listener`	`(answer: CodeAnswer) => void`

Returns

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

Types

CodeAnswer

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.

`CurrencyKey`

A currency, by the SDK's name for it (gems, wood) or by its index in UserCurrency.

TypeScript

type CurrencyKey = CurrencyKind | number

`CurrencyRef`

A currency, by both of its names.

Field	Type
`currency`	`number`	Its index in `UserCurrency` (`CURRENCY`, 0 for gems).
`name`	`"gems" \| "tickets" \| "diamonds" \| "straw" \| "bamboo" \| "wood" \| "stone" \| "silver" \| "gold" \| "gemstone" \| "ecoCredits" \| "crystals" \| null`	The SDK's name for it; null for an index the SDK does not name.

`PricePart`

One part of a price in several currencies at once.

TypeScript

type PricePart = CurrencyRef & { amount: number }

`CurrencyExchangeDefinition`

One row of a currency exchange shop's catalogue (ItemXtCommManager.getCurrencyExchangeDef).

Field	Type
`defId`	`number`
`name`	`string \| null`	Its title, translated; null before the translations arrived.
`titleStrId`	`number \| null`
`mediaId`	`number \| null`
`value`	`number`	What it takes: this much of `currencyType`.
`currencyType`	`number`
`result`	`number`	What it gives back: this much of `resultType`.
`resultType`	`number`
`availableFrom`	`number`	When it is offered, in seconds since the epoch; 0 for always.
`availableUntil`	`number`

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

`CurrencyExchange`

What an exchange came to.

Field	Type
`definition`	`CurrencyExchangeDefinition \| null`	The catalogue row exchanged, or null when the client did not have it.
`balances`	`CurrencyAmount[]`	What the server set the spent currency to, as it wrote it, shaped.

`CurrencyAmount`

A balance of one currency.

TypeScript

type CurrencyAmount = CurrencyRef & { amount: number }

`RedeemOptions`

What redeemCode takes beyond the code: the captcha, when the server asked for one.

TypeScript

type RedeemOptions = ActOptions & {
  captcha?: { question: string; answer: string };
}

`RedeemedCode`

A code the server redeemed.

Field	Type
`code`	`string`
`details`	`unknown`	What the code gave, as the server describes it (its JSON, parsed).
`hasGiftsElsewhere`	`boolean`	The account has gifts waiting on another of its domains.

`CurrencyChange`

A balance that moved.

TypeScript

type CurrencyChange = CurrencyAmount & {
  /** The balance before, or null the first time this listener heard of the currency. */
  previous: number | null;
  /** The server's reason (`CURRENCY_REASON`); null for a balance the client set itself. */
  reason: number | null;
  /**
   * `server` for Animal Jam's `currency.update`; `client` for a balance the client set itself,
   * such as a screen paying out a prize (the daily gift, the gem wheel) before the server says so.
   */
  source: 'server' | 'client';
}

`CodeAnswer`

An answer to a code, whoever sent it.

Field	Type
`redeemed`	`boolean`	Whether it was redeemed.
`refusal`	`string \| null`	Why not, in words; null when it was.
`result`	`string`	The server's result (`REDEMPTION_RESULT`).
`details`	`unknown`
`hasGiftsElsewhere`	`boolean`

`RedeemedMembership`

A membership redeemed on the account.

Field	Type
`accountType`	`number`
`daysLeft`	`number`
`sourceType`	`string \| null`	Where it came from (`subscriptionSourceType`); null when the server sent none.

Gems and diamonds ​

Overview ​

Methods ​

all ​

canAfford ​

crafting ​

diamondDefinitionId ​

diamondsLoaded ​

donateGems ​

exchange ​

exchangeDefinition ​

get ​

priceParts ​

redeemCode ​

Events ​

onChange ​

onDonate ​

onExchange ​

onMembershipRedeemed ​

onRedeem ​

Types ​

CurrencyKey ​

CurrencyRef ​

PricePart ​

CurrencyExchangeDefinition ​

ActOptions ​

CurrencyExchange ​

CurrencyAmount ​

RedeemOptions ​

RedeemedCode ​

CurrencyChange ​

CodeAnswer ​

RedeemedMembership ​

Gems and diamonds

Overview

Methods

`all`

`canAfford`

`crafting`

`diamondDefinitionId`

`diamondsLoaded`

`donateGems`

`exchange`

`exchangeDefinition`

`get`

`priceParts`

`redeemCode`

Events

`onChange`

`onDonate`

`onExchange`

`onMembershipRedeemed`

`onRedeem`

Types

`CurrencyKey`

`CurrencyRef`

`PricePart`

`CurrencyExchangeDefinition`

`ActOptions`

`CurrencyExchange`

`CurrencyAmount`

`RedeemOptions`

`RedeemedCode`

`CurrencyChange`

`CodeAnswer`

`RedeemedMembership`