The world

phantom.aj.worldWhere you are

Servers, shards, room counts and parties.

Scripts and plugins

A script has all of it, as phantom.aj.world, 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
firstFiveMinutesRoom()	Asks whether the player's first-five-minutes room is ready (sendRoomFFMRequest).	game:act
goToPlayer()	Goes to wherever a player is, as the buddy card's "go to" does: asks the server where they are (sendBuddyRoomRequest), then joins that room, following them to another server node when they are on one.	game:act
nodeHop()	Asks the server to move this game to another node, as a draining server does (NodeHop).	game:act
roomCounts()	How many are in each room the server counts (sendRoomCountRequest).	game:act
roomDefinition()	One room definition, or null.	game:read
roomDefinitions()	Every room definition the client has loaded, by def id; none before they load.	game:read
server()	The server node the game is connected to (gMainFrame.server), or null before it is.	game:read
shardName()	A shard's name, as the server list shows it (ServerSelector.getShardName), or null.	game:read
shards()	Every server node and its shards (sendMoreShardRequest).	game:act
switchShard()	Moves the player to another shard (GamePlay.joinChosenShardIdNode), resolving once there.	game:act
onFirstFiveMinutesRoom()	Hears every answer about the first-five-minutes room.	game:read
onNodeHop()	Hears the server tell the game to move to another node.	game:read
onRoomCounts()	Hears every room count the server sends, whoever asked.	game:read
onRoomList()	Hears the server list the rooms the client knows (room.list, and SmartFox's own on login).	game:read

world.parties: Scheduled and custom parties.

Member	What it does	Plugins
canUseAvatar()	Whether the party the player is in lets them out as one of their animals (PartyManager.canSwitchToAvatar).	game:read
custom()	The parties players are hosting, a page at a time (sendCustomPartyListRequest).	game:act
definition()	One party definition, or null.	game:read
definitions()	Every party definition the client has loaded.	game:read
host()	Hosts a party (sendCustomPartyHostRequest), named by three localization ids as the client's name picker builds it, with a music def.	game:act
hostingTimeLeft()	How long a host's party has left, in seconds (sendCustomPartyIsHosting); 0 for none.	game:act
join()	Joins a scheduled party (sendJoinPartyRequest), resolving with its room.	game:act
joinCustom()	Joins a party a player is hosting, by its host's uuid (PartyManager.sendCustomPartyJoin).	game:act
masterpieces()	The masterpieces a party shows (sendPartyMasterpiece).	game:act
node()	Which server node a host's party is on (sendCustomPartyNodeId), or null when it is not found.	game:act
rules()	What the party the player is in allows; all false outside a party.	game:read
scheduled()	The scheduled parties, with how long until each starts and ends (sendPartyListRequest).	game:act
onCustom()	Hears every hosted-party list the server sends.	game:read
onHostingEnded()	Hears a party the player was hosting end, with the diamonds given back.	game:read
onHostingTimeLeft()	Hears every "time left" the server sends about a hosted party.	game:read
onHostResult()	Hears the server answer a hosting request, granted or refused.	game:read
onJoinFailed()	Hears the server refuse a party join, either kind.	game:read
onMasterpieces()	Hears every masterpiece pool the server sends.	game:read
onScheduled()	Hears every scheduled party list the server sends.	game:read

Methods

firstFiveMinutesRoom

methodplugins · game:act

firstFiveMinutesRoom(options?: ActOptions) => Promise<boolean>

Asks whether the player's first-five-minutes room is ready (sendRoomFFMRequest).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<boolean>

Types

ActOptions

goToPlayer

methodplugins · game:act

goToPlayer(userName: string, options?: ActOptions) => Promise<PlayerWhereabouts>

Goes to wherever a player is, as the buddy card's "go to" does: asks the server where they are (sendBuddyRoomRequest), then joins that room, following them to another server node when they are on one. REFUSED for somewhere the game will not follow (an adventure, a locked den, the first five minutes). The room's art loads after: room.loaded() waits for it.

Parameters

Name	Type
userName	string
options optional	ActOptions

Returns

Promise<PlayerWhereabouts>

Types

PlayerWhereabouts · ActOptions

nodeHop

methodplugins · game:act

nodeHop(options?: ActOptions) => Promise<string>

Asks the server to move this game to another node, as a draining server does (NodeHop).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<string>

Types

ActOptions

roomCounts

methodplugins · game:act

roomCounts(options?: ActOptions) => Promise<RoomCount[]>

How many are in each room the server counts (sendRoomCountRequest).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<RoomCount[]>

Types

RoomCount · ActOptions

roomDefinition

methodplugins · game:read

roomDefinition(defId: number) => Promise<RoomDefinition | null>

One room definition, or null.

Parameters

Name	Type
defId	number

Returns

Promise<RoomDefinition \| null>

Types

RoomDefinition

roomDefinitions

methodplugins · game:read

roomDefinitions() => Promise<RoomDefinition[]>

Every room definition the client has loaded, by def id; none before they load.

Returns

Promise<RoomDefinition[]>

Types

RoomDefinition

server

methodplugins · game:read

server() => Promise<WorldServer | null>

The server node the game is connected to (gMainFrame.server), or null before it is.

Returns

Promise<WorldServer \| null>

Types

WorldServer

shardName

methodplugins · game:read

shardName(shardId: number) => Promise<string | null>

A shard's name, as the server list shows it (ServerSelector.getShardName), or null.

Parameters

Name	Type
shardId	number

Returns

Promise<string \| null>

shards

methodplugins · game:act

shards(options?: ActOptions) => Promise<ShardNode[]>

Every server node and its shards (sendMoreShardRequest). The answer is kept from the client, so its server list does not open on it.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<ShardNode[]>

Types

ActOptions · ShardNode · Shard

switchShard

methodplugins · game:act

switchShard(shardId: number, options?: ActOptions) => Promise<WorldServer>

Moves the player to another shard (GamePlay.joinChosenShardIdNode), resolving once there.

Parameters

Name	Type
shardId	number
options optional	ActOptions

Returns

Promise<WorldServer>

Types

WorldServer · ActOptions

Events

onFirstFiveMinutesRoom

eventplugins · game:read

onFirstFiveMinutesRoom(listener: (ready: boolean) => void) => () => void

Hears every answer about the first-five-minutes room.

Parameters

Name	Type
listener	(ready: boolean) => void

Returns

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

onNodeHop

eventplugins · game:read

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

Hears the server tell the game to move to another node.

Parameters

Name	Type
listener	(host: string) => void

Returns

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

onRoomCounts

eventplugins · game:read

onRoomCounts(listener: (rooms: RoomCount[]) => void) => () => void

Hears every room count the server sends, whoever asked.

Parameters

Name	Type
listener	(rooms: RoomCount[]) => void

Returns

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

Types

RoomCount

onRoomList

eventplugins · game:read

onRoomList(listener: (rooms: ListedRoom[]) => void) => () => void

Hears the server list the rooms the client knows (room.list, and SmartFox's own on login).

Parameters

Name	Type
listener	(rooms: ListedRoom[]) => void

Returns

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

Types

ListedRoom

world.parties

Scheduled and custom parties.

canUseAvatar

methodplugins · game:read

canUseAvatar(perUserAvId: number) => Promise<boolean>

Whether the party the player is in lets them out as one of their animals (PartyManager.canSwitchToAvatar). NOT_READY for an animal they have not got.

Parameters

Name	Type
perUserAvId	number

Returns

Promise<boolean>

custom

methodplugins · game:act

custom(options?: ActOptions & { start?: number | undefined; limit?: number | undefined; }) => Promise<CustomParty[]>

The parties players are hosting, a page at a time (sendCustomPartyListRequest).

Parameters

Name	Type
options optional	ActOptions & { start?: number | undefined; limit?: number | undefined; }

Returns

Promise<CustomParty[]>

Types

CustomParty · ActOptions

definition

methodplugins · game:read

definition(defId: number) => Promise<PartyDefinition | null>

One party definition, or null.

Parameters

Name	Type
defId	number

Returns

Promise<PartyDefinition \| null>

Types

PartyDefinition

definitions

methodplugins · game:read

definitions() => Promise<PartyDefinition[]>

Every party definition the client has loaded.

Returns

Promise<PartyDefinition[]>

Types

PartyDefinition

host

methodplugins · game:act

host(partyDefId: number, name: readonly [number, number, number], musicDefId: number, options?: ActOptions) => Promise<PartyHosting>

Hosts a party (sendCustomPartyHostRequest), named by three localization ids as the client's name picker builds it, with a music def. REFUSED with the server's reason (ND not enough diamonds, EXISTS, NM).

Parameters

Name	Type
partyDefId	number
name	readonly [number, number, number]
musicDefId	number
options optional	ActOptions

Returns

Promise<PartyHosting>

Types

PartyHosting · ActOptions

hostingTimeLeft

methodplugins · game:act

hostingTimeLeft(creatorUuid: string, options?: ActOptions & { userName?: string | undefined; }) => Promise<number>

How long a host's party has left, in seconds (sendCustomPartyIsHosting); 0 for none.

Parameters

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

Returns

Promise<number>

Types

ActOptions

join

methodplugins · game:act

join(defId: number, options?: ActOptions) => Promise<RoomJoined>

Joins a scheduled party (sendJoinPartyRequest), resolving with its room. REFUSED with the reason.

Parameters

Name	Type
defId	number
options optional	ActOptions

Returns

Promise<RoomJoined>

Types

RoomJoined · ActOptions

joinCustom

methodplugins · game:act

joinCustom(creatorUuid: string, options?: ActOptions & { node?: string | undefined; }) => Promise<RoomJoined>

Joins a party a player is hosting, by its host's uuid (PartyManager.sendCustomPartyJoin).

Parameters

Name	Type
creatorUuid	string
options optional	ActOptions & { node?: string | undefined; }

Returns

Promise<RoomJoined>

Types

ActOptions · RoomJoined

masterpieces

methodplugins · game:act

masterpieces(options?: ActOptions) => Promise<PoolMasterpiece[]>

The masterpieces a party shows (sendPartyMasterpiece).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<PoolMasterpiece[]>

Types

PoolMasterpiece · ActOptions

node

methodplugins · game:act

node(creatorUuid: string, options?: ActOptions) => Promise<{ creatorUuid: string; node: string; } | null>

Which server node a host's party is on (sendCustomPartyNodeId), or null when it is not found.

Parameters

Name	Type
creatorUuid	string
options optional	ActOptions

Returns

Promise<{ creatorUuid: string; node: string; } \| null>

Types

ActOptions

rules

methodplugins · game:read

rules() => Promise<PartyRules>

What the party the player is in allows; all false outside a party.

Returns

Promise<PartyRules>

Types

PartyRules

scheduled

methodplugins · game:act

scheduled(options?: ActOptions) => Promise<ScheduledParty[]>

The scheduled parties, with how long until each starts and ends (sendPartyListRequest).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<ScheduledParty[]>

Types

ScheduledParty · ActOptions

onCustom

eventplugins · game:read

onCustom(listener: (parties: CustomParty[]) => void) => () => void

Hears every hosted-party list the server sends.

Parameters

Name	Type
listener	(parties: CustomParty[]) => void

Returns

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

Types

CustomParty

onHostingEnded

eventplugins · game:read

onHostingEnded(listener: (ended: { diamondsRefunded: number; }) => void) => () => void

Hears a party the player was hosting end, with the diamonds given back.

Parameters

Name	Type
listener	(ended: { diamondsRefunded: number; }) => void

Returns

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

onHostingTimeLeft

eventplugins · game:read

onHostingTimeLeft(listener: (secondsLeft: number) => void) => () => void

Hears every "time left" the server sends about a hosted party.

Parameters

Name	Type
listener	(secondsLeft: number) => void

Returns

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

onHostResult

eventplugins · game:read

onHostResult(listener: (result: PartyHosting & { hosting: boolean; reason: string | null; }) => void) => () => void

Hears the server answer a hosting request, granted or refused.

Parameters

Name	Type
listener	(result: PartyHosting & { hosting: boolean; reason: string | null; }) => void

Returns

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

Types

PartyHosting

onJoinFailed

eventplugins · game:read

onJoinFailed(listener: (failure: PartyJoinFailure) => void) => () => void

Hears the server refuse a party join, either kind.

Parameters

Name	Type
listener	(failure: PartyJoinFailure) => void

Returns

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

Types

PartyJoinFailure

onMasterpieces

eventplugins · game:read

onMasterpieces(listener: (pool: PoolMasterpiece[]) => void) => () => void

Hears every masterpiece pool the server sends.

Parameters

Name	Type
listener	(pool: PoolMasterpiece[]) => void

Returns

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

Types

PoolMasterpiece

onScheduled

eventplugins · game:read

onScheduled(listener: (parties: ScheduledParty[]) => void) => () => void

Hears every scheduled party list the server sends.

Parameters

Name	Type
listener	(parties: ScheduledParty[]) => void

Returns

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

Types

ScheduledParty

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.

WorldServer

The server node the game is connected to, and the shard it is in.

Field	Type
host	string
port	number | null
shard	number | null	The copy of the world the player is in (RoomManagerWorld.shardId).

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

ShardNode

A server node and the shards it serves.

Field	Type
host	string	The node's host name or address.
shards	Shard[]	The shards the node serves.

Shard

A shard, as GamePlay.showServerSelectorMore caches it (i, l, p, b).

Field	Type
id	number	The shard's id, which the player picks it by.
language	number	Its language id.
population	number	How full it is: the server selector counts 4 and above as full.
buddies	number	How many of the player's buddies are on it.

RoomCount

How many of the player's buddies are in a room's land.

Field	Type
name	string	A room's name, such as jamaa_township.room_main#12. The map reads only its land: the part before the first ., or in the ocean the room's own name up to its # (oceans.kelp_forest#12 is kelp_forest).
users	number	How many of the player's buddies are there: the count the map shows on that land.

ListedRoom

A room in the server's list, as SFClient.setRoomList builds a SmartFox Room from it.

Field	Type
id	number	The room's id.
name	string	The room's name, such as _init for the limbo room.
maxUsers	number	How many players it holds.
isTemp	boolean	A SmartFox temporary room: made when needed and removed once empty.
isGame	boolean	The room is a game room.
users	number	How many players are in it.

RoomDefinition

One of the client's room definitions (RoomXtCommManager._roomDefs).

Field	Type
defId	number
pathName	string	The name phantom.aj.room.join takes: jamaa_township.room_main.
environment	number
isPlatformer	boolean

PlayerWhereabouts

Where goToPlayer found someone, and how the client is getting there.

Field	Type
roomName	string
displayName	string
node	string | null	The server node they are on, when it is not this one.
alreadyThere	boolean	The player was already in that room.
switchingNode	boolean	The client is moving to their node; the join follows once it has.

ScheduledParty

One of Animal Jam's parties, by its party def, with its times from now.

Field	Type
defId	number	The party's def id.
secondsToStart	number	Seconds until it starts; 0 when it is on.
secondsToEnd	number	Seconds until it ends.

CustomParty

A party a player hosts.

Field	Type
creatorUuid	string	The host's uuid, which joining the party names.
name	string	Three localization ids joined with |, which the client translates into the party's name.
node	string	The server node the party is on.
defId	number	The party's def id.
timeLeft	number	Seconds left.

RoomJoined

A room as the server's join answer describes it.

Field	Type
name	string	Its full name, with the copy of it the player is in after #: jamaa_township.room_main#12.
id	number	Its id on the server, the room every later message is sent in.
maxUsers	number	How many players it holds.
isPrivate	boolean
isGame	boolean	An in-room game's room, or one of the game rooms the client treats as such.
isLimbo	boolean	A SmartFox limbo room, whose users are not sent to each other.
isTemp	boolean	Made when needed and removed once empty.
isSubRoom	boolean	A room inside the room: an in-room game.
displayName	string | null	The name the HUD shows. For a player's party (pparty…) the server sends three localization ids joined with |, which the client translates; current() reads the translated one.
shard	number | null	The shard (RoomManagerWorld.shardId), when the server said.

PartyHosting

A party the player is hosting.

Field	Type
secondsLeft	number | null	The seconds left on it, when the server said.

PoolMasterpiece

One masterpiece in the bulletin board's pool, as MasterpieceDisplayItem.initFromPool reads it. Whatever else the server puts in an entry is kept as it came.

Field	Type
frameId	number	The frame it hangs in (frameId), the masterpiece's version.
resourceId	number	The picture itself, the unique image id (resourceId).
userName	string	Who painted it (userName); a name starting with # is a localisation id instead. Empty when the entry names nobody.
creatorDbId	number	The painter's database id (creatorDBId).
creatorUuid	string	The painter's uuid (creatorId).
raw	Record<string, unknown>	The entry as the server sent it, every field included.

PartyDefinition

One of the client's party definitions (PartyManager._partyDefs).

Field	Type
defId	number
titleStrId	number
mediaRefId	number
iconMediaRefId	number
roomDefId	number
isGame	boolean
isCustom	boolean
restrictions	number
avatarDefFlags	number
petDefScalableFlags	number

PartyRules

What the party the player is in allows.

Field	Type
inParty	boolean
petParty	boolean	A "be your pet" party (isBeYourPetParty).
petSpecific	boolean	A party that needs a particular pet out.
canSwitchPet	boolean

PartyJoinFailure

A party join the server refused.

Field	Type
kind	"scheduled" | "custom"
reason	string | null	NM not a member, NA / NP an avatar or pet the party will not have, and the like.
extra	string[]