Jam-a-grams

phantom.aj.ecardsOther players

Jam-a-grams.

Scripts and plugins

A script has all of it, as phantom.aj.ecards, 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
acceptBuddyRequest()	Accepts the buddy request a jam-a-gram carries (sendECardBuddyRequest, eb), as the card's accept button does.	game:act
acceptGift()	Takes the gift a jam-a-gram carries (sendECardAcceptDiscardGiftRequest, eg), in one of its colours for a gift offered in several.	game:act
all()	Every jam-a-gram in the client's inbox, newest first as the inbox shows them.	game:read
declineBuddyRequest()	Declines the buddy request a jam-a-gram carries, as its reject button does.	game:act
designs()	The card pictures and stamps the client has loaded, as send takes them; empty before.	game:read
discardGift()	Throws away the gift a jam-a-gram carries, as the gift popup's reject does.	game:act
get()	One jam-a-gram by its messageId, or null when the inbox has none by it.	game:read
isLoaded()	Whether the client has fetched the inbox this sitting (ECardManager.isFirstTime off).	game:read
isMessageAllowed()	Whether the game would let a message be sent (ECardManager.isECardTextValid).	game:read
markRead()	Marks a jam-a-gram read, as opening it in the inbox does (sendECardReadRequest, er), once the server agrees; the client's card and unread count follow.	game:act
privacy()	Who may send the player jam-a-grams, as the client holds the setting (_privacySettingId).	game:read
refresh()	Fetches the inbox from the server (sendECardListRequest, el), as opening the inbox does the first time, and resolves with it once the client has it.	game:act
remainingSends()	How many more jam-a-grams the client lets the player send someone this sitting: 25 to a buddy, 5 to anyone else, counted since login (ECardXtCommManager._jaggedPlayers).	game:read
remove()	Deletes a jam-a-gram, as the inbox's delete button does (sendECardDeleteRequest, ed), and resolves with every id the server deleted: more than one where the card was part of a batch.	game:act
send()	Sends a jam-a-gram, as the composer's send button does (sendECardSendRequest, es), and resolves with what was sent once the server took it.	game:act
setPrivacy()	Changes who may send the player jam-a-grams (sendECardPrivacySettingUpdateRequest, ei), as the inbox's settings do; resolves with the setting once the server agrees.	game:act
unreadCount()	How many unread jam-a-grams the HUD's badge counts (ECardManager.unreadCount).	game:read
onBuddyAnswer()	Hears every answer to a jam-a-gram's buddy request, from here or the card's own buttons.	game:read
onChange()	Hears the client's inbox change: the whole list arriving, a card received, its message changed, cards deleted (however they were), and the unread count changing (a card read).	game:read
onGiftAnswer()	Hears every answer about a jam-a-gram's gift, from here or the client's own popups.	game:read
onPrivacyAnswer()	Hears every answer to a change of who may send the player jam-a-grams.	game:read
onReceive()	Hears each jam-a-gram arriving while the player is online, as the client takes it in (ECardManager.processECardPush), with its words translated.	game:read
onSendAnswer()	Hears every answer to a jam-a-gram sent, from send or the composer: sent when it went.	game:read

ecards.composer: The card-writing screen.

Member	What it does	Plugins
close()	Closes the composer, as its back button does, leaving the inbox up if it was.	game:act
current()	The card being written and not sent, or null when the composer is closed: who it is to, its words, picture, stamp and gift, the same the send button would send.	game:read
isOpen()	Whether the composer is open (ECardManager.isECardCreationOpen).	game:read
open()	Opens the composer on someone, as a buddy card's jam-a-gram button does (ECardManager.openCreateCard), and resolves with the empty card once it is up.	game:act
pickCard()	Picks the card's picture, as clicking it in the composer's row does (ECardCreation.eCardBtnDownHandler), and resolves with the card once the composer holds it.	game:act
pickStamp()	Picks the card's stamp, as clicking it in the stamp list does (stampBtnDownHandler).	game:act
send()	Sends the card being written, as the composer's own send button does (ECardCreation.sendMailBtnHandler): every check the composer makes is made, and the composer closes as it does for the player.	game:act
setPhrase()	Writes a predefined phrase on the card, as picking it from the composer's phrase list does (ECardCreation.onECardTextClose): the words go on the card and the code is what it carries.	game:act
whenReady()	Waits until the open composer has built its row of cards and loaded the one shown, which pickCard, pickStamp and setPhrase need; resolves with the card.	game:read
onOpenChange()	Hears the composer open and close, however it was opened (openCreateCard, a buddy card, an answered card): true as it opens, false as it closes.	game:read

ecards.screen: The inbox screen.

Member	What it does	Plugins
close()	Closes the inbox and the composer, as their close button does (ECardManager.closeECard).	game:act
isOpen()	Whether the inbox screen is up.	game:read
open()	Opens the inbox screen, as the HUD's jam-a-gram button does (eCardBtnDownHandler), once it is up.	game:act
show()	Turns the open inbox to one card, as clicking it in the inbox's list does (ECardInbox.windowMouseDown), and resolves with it once shown.	game:act
showing()	The card the inbox screen shows, or null when it is closed or shows none (ECardInbox._currMsgId).	game:read

Methods

acceptBuddyRequest

methodplugins · game:act

acceptBuddyRequest(messageId: number, options?: ActOptions) => Promise<void>

Accepts the buddy request a jam-a-gram carries (sendECardBuddyRequest, eb), as the card's accept button does. Throws REFUSED when the buddy list is full or the server could not add the buddy. The card leaves the inbox, as it does for the button.

Parameters

Name	Type
messageId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

acceptGift

methodplugins · game:act

acceptGift(messageId: number, options?: ActOptions & { colorIndex?: number | undefined; }) => Promise<void>

Takes the gift a jam-a-gram carries (sendECardAcceptDiscardGiftRequest, eg), in one of its colours for a gift offered in several. What it gave arrives as an inventory or balance change.

Parameters

Name	Type
messageId	number
options optional	ActOptions & { colorIndex?: number | undefined; }

Returns

Promise<void>

Types

ActOptions

all

methodplugins · game:read

all() => Promise<Ecard[]>

Every jam-a-gram in the client's inbox, newest first as the inbox shows them. Empty before the client has the list; isLoaded() says whether it has, and refresh() fetches it.

Returns

Promise<Ecard[]>

Types

Ecard · EcardKind

declineBuddyRequest

methodplugins · game:act

declineBuddyRequest(messageId: number, options?: ActOptions) => Promise<void>

Declines the buddy request a jam-a-gram carries, as its reject button does.

Parameters

Name	Type
messageId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

designs

methodplugins · game:read

designs() => Promise<{ cards: number[]; stamps: number[]; }>

The card pictures and stamps the client has loaded, as send takes them; empty before.

Returns

Promise<{ cards: number[]; stamps: number[]; }>

discardGift

methodplugins · game:act

discardGift(messageId: number, options?: ActOptions) => Promise<void>

Throws away the gift a jam-a-gram carries, as the gift popup's reject does. Not undone.

Parameters

Name	Type
messageId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

get

methodplugins · game:read

get(messageId: number) => Promise<Ecard | null>

One jam-a-gram by its messageId, or null when the inbox has none by it.

Parameters

Name	Type
messageId	number

Returns

Promise<Ecard \| null>

Types

Ecard

isLoaded

methodplugins · game:read

isLoaded() => Promise<boolean>

Whether the client has fetched the inbox this sitting (ECardManager.isFirstTime off). Until it has, a card that arrives is counted but not added to all().

Returns

Promise<boolean>

isMessageAllowed

methodplugins · game:read

isMessageAllowed(message: string) => Promise<boolean>

Whether the game would let a message be sent (ECardManager.isECardTextValid).

Parameters

Name	Type
message	string

Returns

Promise<boolean>

markRead

methodplugins · game:act

markRead(messageId: number, options?: ActOptions) => Promise<void>

Marks a jam-a-gram read, as opening it in the inbox does (sendECardReadRequest, er), once the server agrees; the client's card and unread count follow. Throws REFUSED while the player is invisible, when the client sends nothing.

Parameters

Name	Type
messageId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

privacy

methodplugins · game:read

privacy() => Promise<number | null>

Who may send the player jam-a-grams, as the client holds the setting (_privacySettingId).

Returns

Promise<number \| null>

refresh

methodplugins · game:act

refresh(options?: ActOptions & { fresh?: boolean | undefined; }) => Promise<Ecard[]>

Fetches the inbox from the server (sendECardListRequest, el), as opening the inbox does the first time, and resolves with it once the client has it. fresh first has the server drop the inbox it cached (sendECardClearCache, ec), which the client does after a delete, so the list cannot be an old one.

Parameters

Name	Type
options optional	ActOptions & { fresh?: boolean | undefined; }

Returns

Promise<Ecard[]>

Types

ActOptions · Ecard

remainingSends

methodplugins · game:read

remainingSends(userName: string) => Promise<number>

How many more jam-a-grams the client lets the player send someone this sitting: 25 to a buddy, 5 to anyone else, counted since login (ECardXtCommManager._jaggedPlayers).

Parameters

Name	Type
userName	string

Returns

Promise<number>

remove

methodplugins · game:act

remove(messageId: number, options?: ActOptions) => Promise<number[]>

Deletes a jam-a-gram, as the inbox's delete button does (sendECardDeleteRequest, ed), and resolves with every id the server deleted: more than one where the card was part of a batch. The client's own handler takes it out of the inbox and recounts the unread.

Parameters

Name	Type
messageId	number
options optional	ActOptions

Returns

Promise<number[]>

Types

ActOptions

send

methodplugins · game:act

send(userName: string, card: EcardToSend, options?: ActOptions & { shownName?: string | undefined; }) => Promise<EcardSent>

Sends a jam-a-gram, as the composer's send button does (sendECardSendRequest, es), and resolves with what was sent once the server took it. Throws REFUSED for a message the game would not let through, for someone sent too many this sitting (remainingSends), and when the server refuses (one who takes none from the player).

Parameters

Name	Type
userName	string
card	EcardToSend
options optional	ActOptions & { shownName?: string | undefined; }

Returns

Promise<EcardSent>

Types

EcardToSend · EcardSent · ActOptions

Example

await phantom.aj.ecards.send('friend', { message: 'Be mine', valentine: true });

Run in Phantom

setPrivacy

methodplugins · game:act

setPrivacy(setting: number, options?: ActOptions) => Promise<number>

Changes who may send the player jam-a-grams (sendECardPrivacySettingUpdateRequest, ei), as the inbox's settings do; resolves with the setting once the server agrees.

Parameters

Name	Type
setting	number
options optional	ActOptions

Returns

Promise<number>

Types

ActOptions

unreadCount

methodplugins · game:read

unreadCount() => Promise<number>

How many unread jam-a-grams the HUD's badge counts (ECardManager.unreadCount).

Returns

Promise<number>

Events

onBuddyAnswer

eventplugins · game:read

onBuddyAnswer(listener: (answer: { result: number; refused: boolean; }) => void) => () => void

Hears every answer to a jam-a-gram's buddy request, from here or the card's own buttons. refused is the buddy not added. The answer names no card.

Parameters

Name	Type
listener	(answer: { result: number; refused: boolean; }) => void

Returns

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

onChange

eventplugins · game:read

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

Hears the client's inbox change: the whole list arriving, a card received, its message changed, cards deleted (however they were), and the unread count changing (a card read).

Parameters

Name	Type
listener	(change: EcardChange) => void

Returns

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

Types

EcardChange

onGiftAnswer

eventplugins · game:read

onGiftAnswer(listener: (answer: { messageId: number; success: boolean; }) => void) => () => void

Hears every answer about a jam-a-gram's gift, from here or the client's own popups.

Parameters

Name	Type
listener	(answer: { messageId: number; success: boolean; }) => void

Returns

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

onPrivacyAnswer

eventplugins · game:read

onPrivacyAnswer(listener: (answer: { changed: boolean; }) => void) => () => void

Hears every answer to a change of who may send the player jam-a-grams.

Parameters

Name	Type
listener	(answer: { changed: boolean; }) => void

Returns

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

onReceive

eventplugins · game:read

onReceive(listener: (card: Ecard) => void) => () => void

Hears each jam-a-gram arriving while the player is online, as the client takes it in (ECardManager.processECardPush), with its words translated. Cards sent while the player was away come in the full list instead (onChange, cause list).

Parameters

Name	Type
listener	(card: Ecard) => void

Returns

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

Types

Ecard

onSendAnswer

eventplugins · game:read

onSendAnswer(listener: (answer: { result: number; sent: boolean; }) => void) => () => void

Hears every answer to a jam-a-gram sent, from send or the composer: sent when it went.

Parameters

Name	Type
listener	(answer: { result: number; sent: boolean; }) => void

Returns

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

ecards.composer

The card-writing screen.

close

methodplugins · game:act

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

Closes the composer, as its back button does, leaving the inbox up if it was.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

current

methodplugins · game:read

current() => Promise<EcardDraft | null>

The card being written and not sent, or null when the composer is closed: who it is to, its words, picture, stamp and gift, the same the send button would send.

Returns

Promise<EcardDraft \| null>

Types

EcardDraft

isOpen

methodplugins · game:read

isOpen() => Promise<boolean>

Whether the composer is open (ECardManager.isECardCreationOpen).

Returns

Promise<boolean>

open

methodplugins · game:act

open(userName: string, options?: ActOptions & { shownName?: string | undefined; }) => Promise<EcardDraft>

Opens the composer on someone, as a buddy card's jam-a-gram button does (ECardManager.openCreateCard), and resolves with the empty card once it is up.

Parameters

Name	Type
userName	string
options optional	ActOptions & { shownName?: string | undefined; }

Returns

Promise<EcardDraft>

Types

ActOptions · EcardDraft

pickCard

methodplugins · game:act

pickCard(mediaId: number, options?: ActOptions) => Promise<EcardDraft>

Picks the card's picture, as clicking it in the composer's row does (ECardCreation.eCardBtnDownHandler), and resolves with the card once the composer holds it. Throws RangeError for a picture the composer does not offer, NOT_READY while it is loading or has nobody to write to.

Parameters

Name	Type
mediaId	number
options optional	ActOptions

Returns

Promise<EcardDraft>

Types

ActOptions · EcardDraft

pickStamp

methodplugins · game:act

pickStamp(mediaId: number, options?: ActOptions) => Promise<EcardDraft>

Picks the card's stamp, as clicking it in the stamp list does (stampBtnDownHandler).

Parameters

Name	Type
mediaId	number
options optional	ActOptions

Returns

Promise<EcardDraft>

Types

ActOptions · EcardDraft

send

methodplugins · game:act

send(options?: ActOptions) => Promise<EcardDraft>

Sends the card being written, as the composer's own send button does (ECardCreation.sendMailBtnHandler): every check the composer makes is made, and the composer closes as it does for the player. Resolves with the card sent once the server took it; throws REFUSED for a card with nobody to send to or no words, and when the server refuses.

This sends a jam-a-gram to Animal Jam.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<EcardDraft>

Types

ActOptions · EcardDraft

setPhrase

methodplugins · game:act

setPhrase(code: string, options?: ActOptions) => Promise<EcardDraft>

Writes a predefined phrase on the card, as picking it from the composer's phrase list does (ECardCreation.onECardTextClose): the words go on the card and the code is what it carries. Throws RangeError for a code the jam-a-gram list does not have.

Parameters

Name	Type
code	string
options optional	ActOptions

Returns

Promise<EcardDraft>

Types

ActOptions · EcardDraft

whenReady

methodplugins · game:read

whenReady(options?: ActOptions) => Promise<EcardDraft>

Waits until the open composer has built its row of cards and loaded the one shown, which pickCard, pickStamp and setPhrase need; resolves with the card. Throws NOT_READY with no composer open, TIMEOUT when it never gets there.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<EcardDraft>

Types

ActOptions · EcardDraft

onOpenChange

eventplugins · game:read

onOpenChange(listener: (open: boolean) => void) => () => void

Hears the composer open and close, however it was opened (openCreateCard, a buddy card, an answered card): true as it opens, false as it closes. Read four times a second.

Parameters

Name	Type
listener	(open: boolean) => void

Returns

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

ecards.screen

The inbox screen.

close

methodplugins · game:act

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

Closes the inbox and the composer, as their close button does (ECardManager.closeECard).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

isOpen

methodplugins · game:read

isOpen() => Promise<boolean>

Whether the inbox screen is up.

Returns

Promise<boolean>

open

methodplugins · game:act

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

Opens the inbox screen, as the HUD's jam-a-gram button does (eCardBtnDownHandler), once it is up. Throws REFUSED when the button is greyed (in a minigame).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

show

methodplugins · game:act

show(messageId: number, options?: ActOptions) => Promise<Ecard>

Turns the open inbox to one card, as clicking it in the inbox's list does (ECardInbox.windowMouseDown), and resolves with it once shown. A card not read yet is marked read with Animal Jam, as the player's click would. Throws NOT_READY with the inbox closed and RangeError for a card it does not list.

Parameters

Name	Type
messageId	number
options optional	ActOptions

Returns

Promise<Ecard>

Types

Ecard · ActOptions

showing

methodplugins · game:read

showing() => Promise<Ecard | null>

The card the inbox screen shows, or null when it is closed or shows none (ECardInbox._currMsgId). What markRead, remove and acceptGift want of the card in front of the player.

Returns

Promise<Ecard \| null>

Types

Ecard

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.

Ecard

A jam-a-gram as the client's own inbox holds it (ecard.ECard), its words already translated.

Field	Type
messageId	number	The card's id, which every request about it names.
senderUserName	string	Who sent it, by account name.
senderShownName	string | null	The sender's name as the game shows it; null where it is the account name.
senderIsMember	boolean
fromPlayer	boolean	Sent by a player, rather than by Animal Jam or a redemption.
read	boolean	The player has opened it.
message	string	What it says, a predefined phrase already turned into its words.
type	number	What it carries, as the client numbers it (ECard.TYPE_*), and its name.
kind	EcardKind
gift	{ id: number; color: number; name: string; } | null	The gift it carries, or null for a card that carries none.
buddyRequest	boolean	The card is a buddy request (kind buddy), answered with acceptBuddyRequest.
cardMediaId	number
stampMediaId	number
valentine	boolean	A valentine (ECard.SPECIAL_TYPE_VALENTINES).

EcardKind

What a jam-a-gram carries, by the client's ECard.TYPE_* name; unknown for a number it has none for.

type EcardKind = keyof typeof ECARD_TYPE | 'unknown'

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

EcardToSend

What a jam-a-gram is sent with. Anything left out is the plain card the composer starts on.

Field	Type
message	string	Typed words, or a predefined phrase's code such as 12,3 (phantom.aj.chat finds codes).
cardMediaId optional	number | undefined	The picture, from designs(); the first the client loaded by default.
stampMediaId optional	number | undefined	The stamp, from designs(); the first the client loaded by default.
messageType optional	number | undefined	1 bubble chat (MESSAGE_TYPE_BUBBLECHAT, the default), 2 typed (MESSAGE_TYPE_LIMITEDCHAT).
type optional	number | undefined	What it carries (ECARD_TYPE); a plain card by default.
giftInvId optional	number | undefined	The gift's place in the player's inventory; none by default.
valentine optional	boolean | undefined	Send it as a valentine (ECard.SPECIAL_TYPE_VALENTINES).

EcardSent

A jam-a-gram the server took, as it was sent.

Field	Type
toUserName	string
message	string
messageType	number
cardMediaId	number
stampMediaId	number
type	number
giftInvId	number | null
result	number	The server's number for it, 1 and above.

EcardChange

What a change of the client's inbox was.

type EcardChange = | { cause: 'list' }
  | { cause: 'received'; messageId: number }
  | { cause: 'updated'; messageId: number }
  | { cause: 'removed'; messageIds: number[] }
  | { cause: 'unread'; unread: number }

EcardDraft

The card the player is writing in the composer and has not sent.

Field	Type
toUserName	string | null	Who it is addressed to; null before anybody is picked.
toShownName	string | null	Their name as the game shows it; null where it is the account name.
message	string	What it says: a phrase's code such as 12,3 for bubble chat (messageType 1), the words themselves for typed text; empty before anything is written.
messageType	number	1 bubble chat (MESSAGE_TYPE_BUBBLECHAT), 2 typed (MESSAGE_TYPE_LIMITEDCHAT).
cardMediaId	number | null
stampMediaId	number | null
type	number	What it would carry (ECard.TYPE_*).
giftInvId	number | null	The gift's place in the player's inventory, or null for none.
ready	boolean	The composer's row of cards is built and nothing is loading: picking works.
sendable	boolean	The send button would send (sendBtn.isGray off).