The connection

phantom.aj.sessionThe connection

The connection and login: connected, in the world, keeping active.

Scripts and plugins

A script has all of it, as phantom.aj.session, 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
`disconnect()`	Drops the game's own connection (`SFClient.disconnect`), and resolves once the client says it is down.	`game:act`
`email()`	The account's email address and the one waiting to be confirmed, from `clientInfo`.	`game:read`
`isConnected()`	Whether the game is connected to Animal Jam right now (`SFClient.isConnected`).	`game:read`
`keepActive()`	Keeps the player from being sent away for being idle, by counting as input now and once a minute (`markActive`), until the handle is called.	`game:act`
`keepAlive()`	Sends one keep-alive now through the client (`KeepAlive.sendKeepAliveReset`, `ka`), and puts its idle countdown back to the start (`restartTimeLeftTimer`), for a session held open with nothing touching the game.	`game:act`
`list()`	Asks for one of the game's generic lists by id (`gl`), and resolves with the server's answer, decoded as far as the SDK knows its shape: a shop's lists as `items` or `combined`, anything else as `other` with its raw fields.	`game:read`
`markActive()`	Counts as the player doing something, as a click does: the stage's own input handler (`KeepAlive.inputReceivedHandler`, which sends the client's keep-alive when one is due) and an adventure's (`QuestManager.resetMouseDownIdleTimer`).	`game:act`
`mode()`	How the connection is carried (`SFClient.getConnectionMode`); `disconnected` before one.	`game:read`
`sendEmailActivation()`	Asks Animal Jam to send the email that confirms an address for this account, as the email confirmation popup's resend button does (`requestSendEmailActivation`, `ves`).	`game:act`
`server()`	The node the client talks to, and the pool it was handed at login; null before it has one.	`game:read`
`state()`	How far the client has got: every step and the mode, in one message.	`game:read`
`whenReady()`	Waits until the client has got as far as `step` (`inWorld` by default), and resolves with the whole state then; at once when it already has.	`game:read`
`onConnection()`	Hears each attempt to connect end (`SFClient.onConnection`), the first and every reconnect.	`game:read`
`onEmailActivation()`	Hears the server answer a request for an activation email (`ves`), whoever asked.	`game:read`
`onEmailValidated()`	Hears the account's email confirmed from the activation link (`vea`).	`game:read`
`onHandshake()`	Hears the server answer the SmartFox version the client speaks: `accepted` (`apiOK`, the connection is up) or `obsolete` (`apiKO`, the connection is over before any login).	`game:read`
`onIdleWarning()`	Hears the client warn the player they are about to be sent away for being idle (`AJAudio.playIdleWarningSound`, which both the world's and an adventure's warnings play).	`game:read`
`onList()`	Hears every generic list arrive (`gl`), whoever asked: shops and everything else.	`game:read`
`onLost()`	Hears the game lose its connection (`SFClient.onConnectionLost`).	`game:read`
`onNodeSwitch()`	Hears the client move to another server node (`SFClient.switchServerNode`), by its address: a shard switch, a party on another node, a room join routed there, or a reconnect.	`game:read`

Methods

`disconnect`

methodplugins · game:act

TypeScript

disconnect(options?: ActOptions & { dispatchEvent?: boolean | undefined; }) => Promise<void>

Drops the game's own connection (SFClient.disconnect), and resolves once the client says it is down. This ends the game until it is relaunched or reloaded. dispatchEvent: false closes it quietly, without the client's own onConnectionLost (or onLost here).

Parameters

Name	Type
`options` optional	`ActOptions & { dispatchEvent?: boolean \| undefined; }`

Returns

Promise<void>

Types

ActOptions

`email`

methodplugins · game:read

TypeScript

email() => Promise<AccountEmail>

The account's email address and the one waiting to be confirmed, from clientInfo.

Returns

Promise<AccountEmail>

Types

AccountEmail

`isConnected`

methodplugins · game:read

TypeScript

isConnected() => Promise<boolean>

Whether the game is connected to Animal Jam right now (SFClient.isConnected).

Returns

Promise<boolean>

`keepActive`

methodplugins · game:act

TypeScript

keepActive(options?: ActOptions) => Promise<KeepingActive>

Keeps the player from being sent away for being idle, by counting as input now and once a minute (markActive), until the handle is called. What reaches Animal Jam is the client's own keep-alive on its own schedule. A minute that could not be marked is logged, and the next is tried as ever.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<KeepingActive>

Types

KeepingActive · ActOptions

Example

TypeScript

const stop = await phantom.aj.session.keepActive();

Run in Phantom

`keepAlive`

methodplugins · game:act

TypeScript

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

Sends one keep-alive now through the client (KeepAlive.sendKeepAliveReset, ka), and puts its idle countdown back to the start (restartTimeLeftTimer), for a session held open with nothing touching the game. Resolves once the ka has gone out.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`list`

methodplugins · game:read

TypeScript

list(listId: number, options?: ActOptions) => Promise<ShopListFields>

Asks for one of the game's generic lists by id (gl), and resolves with the server's answer, decoded as far as the SDK knows its shape: a shop's lists as items or combined, anything else as other with its raw fields.

The packet is sent here rather than through GenericListXtCommManager.requestGenericList, which answers a list it has seen before out of its own cache and asks the server nothing: the answer would never come.

Parameters

Name	Type
`listId`	`number`
`options` optional	`ActOptions`

Returns

Promise<ShopListFields>

Types

ShopListFields · ShopListHead · ActOptions

`markActive`

methodplugins · game:act

TypeScript

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

Counts as the player doing something, as a click does: the stage's own input handler (KeepAlive.inputReceivedHandler, which sends the client's keep-alive when one is due) and an adventure's (QuestManager.resetMouseDownIdleTimer). Nothing is sent the client would not have sent for a click.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`mode`

methodplugins · game:read

TypeScript

mode() => Promise<ConnectionMode>

How the connection is carried (SFClient.getConnectionMode); disconnected before one.

Returns

Promise<ConnectionMode>

Types

ConnectionMode

`sendEmailActivation`

methodplugins · game:act

TypeScript

sendEmailActivation(email: string, options?: ActOptions) => Promise<void>

Asks Animal Jam to send the email that confirms an address for this account, as the email confirmation popup's resend button does (requestSendEmailActivation, ves). This sends a real email. Resolves once the server says it went; throws REFUSED when it would not.

Parameters

Name	Type
`email`	`string`
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`server`

methodplugins · game:read

TypeScript

server() => Promise<ConnectionServer | null>

The node the client talks to, and the pool it was handed at login; null before it has one.

Returns

Promise<ConnectionServer \| null>

Types

ConnectionServer

`state`

methodplugins · game:read

TypeScript

state() => Promise<SessionState>

How far the client has got: every step and the mode, in one message. All false before it starts.

Returns

Promise<SessionState>

Types

SessionState · ConnectionMode

`whenReady`

methodplugins · game:read

TypeScript

whenReady(options?: ActOptions & { step?: SessionStep | undefined; }) => Promise<SessionState>

Waits until the client has got as far as step (inWorld by default), and resolves with the whole state then; at once when it already has. The wait is held in the game, so nothing crosses until the flag is set. Throws TIMEOUT after timeoutMs (a minute by default).

Parameters

Name	Type
`options` optional	`ActOptions & { step?: SessionStep \| undefined; }`

Returns

Promise<SessionState>

Types

ActOptions · SessionState

Example

TypeScript

await phantom.aj.session.whenReady();

Run in Phantom

Events

`onConnection`

eventplugins · game:read

TypeScript

onConnection(listener: (outcome: { connected: boolean; }) => void) => () => void

Hears each attempt to connect end (SFClient.onConnection), the first and every reconnect.

Parameters

Name	Type
`listener`	`(outcome: { connected: boolean; }) => void`

Returns

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

`onEmailActivation`

eventplugins · game:read

TypeScript

onEmailActivation(listener: (answer: { sent: boolean; }) => void) => () => void

Hears the server answer a request for an activation email (ves), whoever asked.

Parameters

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

Returns

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

`onEmailValidated`

eventplugins · game:read

TypeScript

onEmailValidated(listener: () => void) => () => void

Hears the account's email confirmed from the activation link (vea).

Parameters

Name	Type
`listener`	`() => void`

Returns

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

`onHandshake`

eventplugins · game:read

TypeScript

onHandshake(listener: (handshake: Handshake) => void) => () => void

Hears the server answer the SmartFox version the client speaks: accepted (apiOK, the connection is up) or obsolete (apiKO, the connection is over before any login).

Parameters

Name	Type
`listener`	`(handshake: Handshake) => void`

Returns

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

Types

Handshake

`onIdleWarning`

eventplugins · game:read

TypeScript

onIdleWarning(listener: () => void) => () => void

Hears the client warn the player they are about to be sent away for being idle (AJAudio.playIdleWarningSound, which both the world's and an adventure's warnings play).

Parameters

Name	Type
`listener`	`() => void`

Returns

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

`onList`

eventplugins · game:read

TypeScript

onList(listener: (list: ShopListFields) => void) => () => void

Hears every generic list arrive (gl), whoever asked: shops and everything else.

Parameters

Name	Type
`listener`	`(list: ShopListFields) => void`

Returns

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

Types

ShopListFields

`onLost`

eventplugins · game:read

TypeScript

onLost(listener: () => void) => () => void

Hears the game lose its connection (SFClient.onConnectionLost). A real disconnection: unless something reconnects, the game is over until it is relaunched.

Parameters

Name	Type
`listener`	`() => void`

Returns

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

`onNodeSwitch`

eventplugins · game:read

TypeScript

onNodeSwitch(listener: (host: string) => void) => () => void

Hears the client move to another server node (SFClient.switchServerNode), by its address: a shard switch, a party on another node, a room join routed there, or a reconnect.

Parameters

Name	Type
`listener`	`(host: string) => 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.

`SessionState`

How far the client has got with Animal Jam, each step the client's own flag as it stands. The steps come in this order; until inWorld the world extension answers nothing, so a request sent before it can go quietly nowhere (the client holds its own back for it).

Field	Type
`connected`	`boolean`	`SFClient.isConnected`: the socket is up.
`loggedIn`	`boolean`	`SFClient.isLoggedIn`: the account's login went through.
`inWorld`	`boolean`	`SFClient.isWorldXtReady`: the world's login reply is in, and the world answers.
`mode`	`ConnectionMode`

`ConnectionMode`

How the connection is carried (SmartFoxClient.getConnectionMode, its own words): a plain socket, polling over HTTP where a socket cannot be made, or nothing.

TypeScript

type ConnectionMode = 'socket' | 'http' | 'disconnected'

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

`ConnectionServer`

The node the client is talking to (SFClient.serverIp, serverPort, serverIps).

Field	Type
`host`	`string`
`port`	`number`
`ips`	`string[]`	Every address the client was handed at login; a move to another node picks from these.

`AccountEmail`

The account's email address as the client holds it, and the one waiting to be confirmed.

Field	Type
`address`	`string \| null`	`clientInfo.userEmail`, or null when the account has none.
`pending`	`string \| null`	`clientInfo.pendingEmail`: sent a confirmation link and not yet confirmed; null for none.

`ShopListFields`

TypeScript

type ShopListFields = | (ShopListHead & {
      /**
       * Which shape the list has: `items` for a shop that is a plain list of ids, `combined` for a
       * combined list (1060), `other` for a generic list that is not a shop's.
       */
      kind: 'items';
      /** The definition ids of the shop's items, in shop order. */
      defIds: number[];
    })
  | (ShopListHead & {
      /**
       * Which shape the list has: `items` for a shop that is a plain list of ids, `combined` for a
       * combined list (1060), `other` for a generic list that is not a shop's.
       */
      kind: 'combined';
      /** The lists the combined list is made of, in order. */
      groups: ShopListGroup[];
    })
  /** A generic list that is not a shop's: its body is kept unread. */
  | {
      /**
       * Which shape the list has: `items` for a shop that is a plain list of ids, `combined` for a
       * combined list (1060), `other` for a generic list that is not a shop's.
       */
      kind: 'other';
      /** The list's id, the one asked for in `shop.list-request`. */
      listId: number;
      /** The list's type, such as 1000 for clothing (`SHOP_LIST_TYPE`). */
      listType: number;
      /** Everything after the list's type, unread. */
      body: string[];
    }

`ShopListHead`

The head every shop list shares, read by shopListResponse before the items.

Field	Type
`listId`	`number`	The list's id, the one asked for in `shop.list-request`.
`listType`	`number`	The list's type, such as 1000 for clothing (`SHOP_LIST_TYPE`).
`titleStrId`	`string`	The shop's title, a localization string id as text, or empty when the shop keeps its own (`Shop.gotItemListCallback` reads it as `_shopNameId`).
`unused`	`string`	Read by no handler in the client; kept so the message can be written back as it came.
`diamondBundle`	`boolean`	The bundle shop only: everything in the list is bought at once for diamonds (`BundleShop`). Animal Jam's server writes it `true` or `false`, as Java spells a boolean, on every list. The client reads it with `Boolean(...)`, which is true for any text that is not empty, `false` included, but only the bundle shop's callback takes it, so the server's spelling is what counts.
`diamondCost`	`number`	What that bundle costs; 0 in every other shop.

`KeepingActive`

A running keepActive: call it to stop counting as input.

TypeScript

type KeepingActive = () => void

`Handshake`

What the server made of the SmartFox version this client speaks (apiOK, apiKO).

TypeScript

type Handshake = 'accepted' | 'obsolete'

The connection ​

Overview ​

Methods ​

disconnect ​

email ​

isConnected ​

keepActive ​

keepAlive ​

list ​

markActive ​

mode ​

sendEmailActivation ​

server ​

state ​

whenReady ​

Events ​

onConnection ​

onEmailActivation ​

onEmailValidated ​

onHandshake ​

onIdleWarning ​

onList ​

onLost ​

onNodeSwitch ​

Types ​

SessionState ​

ConnectionMode ​

ActOptions ​

ConnectionServer ​

AccountEmail ​

ShopListFields ​

ShopListHead ​

KeepingActive ​

Handshake ​

The connection

Overview

Methods

`disconnect`

`email`

`isConnected`

`keepActive`

`keepAlive`

`list`

`markActive`

`mode`

`sendEmailActivation`

`server`

`state`

`whenReady`

Events

`onConnection`

`onEmailActivation`

`onEmailValidated`

`onHandshake`

`onIdleWarning`

`onList`

`onLost`

`onNodeSwitch`

Types

`SessionState`

`ConnectionMode`

`ActOptions`

`ConnectionServer`

`AccountEmail`

`ShopListFields`

`ShopListHead`

`KeepingActive`

`Handshake`