The map and the server list

phantom.aj.mapWhere you are

The world map and travelling by it.

Scripts and plugins

A script has all of it, as phantom.aj.map, 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
close()	Closes the map (closeWorldMapIfOpen).	game:act
current()	The map on screen, or null while it is closed.	game:read
goHome()	Goes to the player's own den, as the map's den button does (gotoHome).	game:act
load()	Loads the danger map's art ahead of opening it (loadDangerAssets); resolves once it is in.	game:act
mark()	Stars the zone the player is in on the map (setStar), resolving with its name.	game:act
open()	Opens a map (GuiManager.openWorldMap, or show for the danger map), resolving once it is up.	game:act
showMarkers()	Shows a kind of marker over the world map's zones, or none with null, as its sort buttons do.	game:act
showTab()	Opens a pull-out tab of the world map, or closes the open one with null, as its buttons do.	game:act
travelTo()	Travels to a zone as the map's own buttons do (VolumeSelector.gotoRoom, which joins it on the player's shard), resolving with the room joined; at once with the room the player is in when they are already there.	game:act
zones()	The world map's zones, with the buddies its badges count and the starred one.	game:read
onClose()	Hears a map close.	game:read
onOpen()	Hears a map open (VolumeSelector.show).	game:read
onTravel()	Hears the player travel from the map, with the zone (VolumeSelector.gotoRoom).	game:read

map.servers: The server list the map opens.

Member	What it does	Plugins
close()	Closes the server list (ServerSelector.destroy).	game:act
current()	Whether the list is open, and the shards it shows with their names and counts.	game:read
name()	A shard's name, as the list shows it (getShardName), or null.	game:read
open()	Opens the server list over the game (ServerSelector.init on the GUI layer).	game:act
pick()	Picks a server, as pressing it in the open list does: the client then goes there.	game:act
onChange()	Hears the server list open (true) and close (false).	game:read

Methods

close

methodplugins · game:act

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

Closes the map (closeWorldMapIfOpen).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

current

methodplugins · game:read

current() => Promise<MapState | null>

The map on screen, or null while it is closed.

Returns

Promise<MapState \| null>

Types

MapState · MapKind

goHome

methodplugins · game:act

goHome(options?: ActOptions) => Promise<RoomJoined>

Goes to the player's own den, as the map's den button does (gotoHome).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<RoomJoined>

Types

ActOptions · RoomJoined

load

methodplugins · game:act

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

Loads the danger map's art ahead of opening it (loadDangerAssets); resolves once it is in.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

mark

methodplugins · game:act

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

Stars the zone the player is in on the map (setStar), resolving with its name.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<string>

Types

ActOptions

open

methodplugins · game:act

open(kind?: MapKind, options?: ActOptions) => Promise<MapState>

Opens a map (GuiManager.openWorldMap, or show for the danger map), resolving once it is up.

Parameters

Name	Type
kind optional	MapKind
options optional	ActOptions

Returns

Promise<MapState>

Types

ActOptions · MapState · MapKind

showMarkers

methodplugins · game:act

showMarkers(kind: MapMarkers | null, options?: ActOptions) => Promise<MapState>

Shows a kind of marker over the world map's zones, or none with null, as its sort buttons do.

Parameters

Name	Type
kind	MapMarkers | null
options optional	ActOptions

Returns

Promise<MapState>

Types

MapState · ActOptions

showTab

methodplugins · game:act

showTab(tab: MapTab | null, options?: ActOptions) => Promise<MapState>

Opens a pull-out tab of the world map, or closes the open one with null, as its buttons do.

Parameters

Name	Type
tab	MapTab | null
options optional	ActOptions

Returns

Promise<MapState>

Types

MapState · ActOptions

travelTo

methodplugins · game:act

travelTo(zone: string, options?: ActOptions) => Promise<RoomJoined>

Travels to a zone as the map's own buttons do (VolumeSelector.gotoRoom, which joins it on the player's shard), resolving with the room joined; at once with the room the player is in when they are already there.

Parameters

Name	Type
zone	string
options optional	ActOptions

Returns

Promise<RoomJoined>

Types

RoomJoined · ActOptions

zones

methodplugins · game:read

zones() => Promise<MapZone[]>

The world map's zones, with the buddies its badges count and the starred one.

Returns

Promise<MapZone[]>

Types

MapZone

Events

onClose

eventplugins · game:read

onClose(listener: (event: MapEvent) => void) => () => void

Hears a map close.

Parameters

Name	Type
listener	(event: MapEvent) => void

Returns

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

Types

MapEvent

onOpen

eventplugins · game:read

onOpen(listener: (event: MapEvent) => void) => () => void

Hears a map open (VolumeSelector.show).

Parameters

Name	Type
listener	(event: MapEvent) => void

Returns

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

Types

MapEvent

onTravel

eventplugins · game:read

onTravel(listener: (zone: string) => void) => () => void

Hears the player travel from the map, with the zone (VolumeSelector.gotoRoom).

Parameters

Name	Type
listener	(zone: string) => void

Returns

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

map.servers

The server list the map opens.

close

methodplugins · game:act

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

Closes the server list (ServerSelector.destroy). NOT_READY when it is not open.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

current

methodplugins · game:read

current() => Promise<MapServers>

Whether the list is open, and the shards it shows with their names and counts.

Returns

Promise<MapServers>

Types

MapServers · MapServer

name

methodplugins · game:read

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

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

Parameters

Name	Type
shardId	number

Returns

Promise<string \| null>

open

methodplugins · game:act

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

Opens the server list over the game (ServerSelector.init on the GUI layer).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<MapServers>

Types

ActOptions · MapServers

pick

methodplugins · game:act

pick(shardId: number, options?: ActOptions) => Promise<MapServer>

Picks a server, as pressing it in the open list does: the client then goes there. Resolves with the server picked. NOT_READY when the list is not open, REFUSED for a server it does not offer.

Parameters

Name	Type
shardId	number
options optional	ActOptions

Returns

Promise<MapServer>

Types

ActOptions · MapServer

onChange

eventplugins · game:read

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

Hears the server list open (true) and close (false).

Parameters

Name	Type
listener	(open: boolean) => 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.

MapState

The map as it is on screen.

Field	Type
kind	MapKind
tab	MapTab | null	The pull-out tab that is open, on the world map.
markers	MapMarkers | null	The markers shown, on the world map.

MapKind

The two maps: Jamaa, and the danger map adventures are picked from.

type MapKind = 'world' | 'danger'

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

MapZone

One of the world map's zones, by the name its travel takes.

Field	Type
name	string
buddies	number | null	How many buddies are there, as the map's own badge says; null where it shows none.
marked	boolean	The zone the player starred (userInfo.worldMapRoomName).

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.

MapEvent

The map opening or closing.

Field	Type
open	boolean
kind	MapKind

MapServers

The server list (gui.ServerSelector), open or not, with what it last showed.

Field	Type
open	boolean
servers	MapServer[]

MapServer

One shard on the server list.

Field	Type
shardId	number
name	string | null
population	number
buddies	number
languageId	number