The HUD

phantom.aj.hudThe screen and sound

The HUD: labels, buttons, parts, counters, the room label.

Scripts and plugins

A script has all of it, as phantom.aj.hud, 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
`button()`	One button as it is now; `there` is false for one this HUD has not got.	`game:read`
`buttons()`	Every button, read in one message, in the order `gui.GuiHud` lists them.	`game:read`
`click()`	Clicks one of the HUD's buttons (`buddyListBtn`, `newsBtn`), as the player would.	`game:act`
`diamonds()`	The diamonds the HUD's counter shows, or null before it shows any.	`game:read`
`gems()`	The gems the HUD's counter shows, or null before it shows any.	`game:read`
`greyButton()`	Greys a button out so it cannot be pressed, or brings it back, as the client does in a private adventure lobby (`GuiSoundButton.activateGrayState`).	`game:act`
`hide()`	Hides parts of the HUD until the handle is called, whatever the client does meanwhile and through every rebuild: a button a plugin answers itself, a panel it draws over.	`game:act`
`hideTopRow()`	Takes the whole top strip off (`updateMainHudButtons(true)`), as the client does under a screen.	`game:act`
`isDarkened()`	Whether the room is dimmed behind something, one reason the player will not walk.	`game:read`
`isModal()`	Whether a modal window is up, which keeps the room from the mouse (`GuiManager.isModal`).	`game:read`
`isReconnecting()`	Whether the client is putting a dropped connection back together.	`game:read`
`isShown()`	Whether the HUD is shown (`GuiManager.toggleHud` hides it).	`game:read`
`isUp()`	Whether a HUD is on screen at all; false before the first room and in a den preview.	`game:read`
`keepLabel()`	Keeps one label saying `text` whatever the client writes there, through new rooms and the HUD being rebuilt, until the handle puts back what it said.	`game:act`
`label()`	What one label says on screen, or null when this HUD has not got it.	`game:read`
`labels()`	All four labels, read in one message so they are the same moment's HUD.	`game:read`
`mail()`	The unread jam-a-gram count the mail badge shows; 0 when it shows none.	`game:read`
`mode()`	Which HUD is up (`GuiHud`'s frame label), or null when there is none.	`game:read`
`part()`	One part of the HUD, such as `denBtn`, or null when the HUD or the part is not there.	`game:read`
`parts()`	The HUD's own parts, each with its path (`hud.<name>`); none before the HUD is up.	`game:read`
`pinCurrency()`	Holds the HUD's gem and diamond display open, rather than only while the mouse is on it, until the handle is called.	`game:act`
`setAvatar()`	Draws the HUD's own picture of the player's animal again, or greys it out.	`game:act`
`setDenVisitorCount()`	Shows a number on the HUD's den visitor badge, or hides it for 0.	`game:act`
`setLabel()`	Writes over one label, once, and resolves with what it said before.	`game:act`
`setRoomLabel()`	Writes the room's name on the HUD, as the client does when a room is joined (the label, the name it remembers and the bar's width).	`game:act`
`setShown()`	Shows or hides the HUD, as the client's own key does (`GuiManager.toggleHud`), and resolves with whether it is shown now.	`game:act`
`showTopButton()`	Shows or hides a button of the top strip and closes the row up after it, the client's own call for the Journey Book, the player wall and the news (`updateMainHudButtons`).	`game:act`
`windows()`	The windows the HUD opens over itself; `visible` says which is open.	`game:read`
`onLabel()`	Hears one label change, whoever changed it: read in the game a few times a second, told on a change and once at the start.	`game:read`
`onRebuild()`	Hears the client build the HUD again (`GuiHud.init`), after it jumps between the room's, an adventure's and a minigame's: with which one it built.	`game:read`

Methods

`button`

methodplugins · game:read

TypeScript

button(button: "soundBtn" | "denBtn" | "editCharBtn" | "swapBtn" | "actionsBtn" | "safeChatBtn" | "emotesBtn" | "worldMapBtn" | "furnBtn" | "eCardBtn" | "buddyListBtn" | "newsBtn" | "reportBtn" | "mySettingsBtn" | "partyBtn" | "playerWallBtn" | "combatCardDeckBtn" | "ajEmailBtn" | "sendChatBtn" | "ansChatBtn" | "emailChatBtn" | "chatRepeatBtn" | "chatHistUpDownBtn" | "questExitBtn" | "questPlayersBtn") => Promise<HudPartState>

One button as it is now; there is false for one this HUD has not got.

Parameters

Name	Type
`button`	`"soundBtn" \| "denBtn" \| "editCharBtn" \| "swapBtn" \| "actionsBtn" \| "safeChatBtn" \| "emotesBtn" \| "worldMapBtn" \| "furnBtn" \| "eCardBtn" \| "buddyListBtn" \| "newsBtn" \| "reportBtn" \| "mySettingsBtn" \| "partyBtn" \| "playerWallBtn" \| "combatCardDeckBtn" \| "ajEmailBtn" \| "sendChatBtn" \| "ansChatBtn" \| "emailChatBtn" \| "chatRepeatBtn" \| "chatHistUpDownBtn" \| "questExitBtn" \| "questPlayersBtn"`

Returns

Promise<HudPartState>

Types

HudPartState

`buttons`

methodplugins · game:read

TypeScript

buttons() => Promise<HudPartState[]>

Every button, read in one message, in the order gui.GuiHud lists them.

Returns

Promise<HudPartState[]>

Types

HudPartState

`click`

methodplugins · game:act

TypeScript

click(name: string, options?: ActOptions) => Promise<GuiClick>

Clicks one of the HUD's buttons (buddyListBtn, newsBtn), as the player would.

Parameters

Name	Type
`name`	`string`
`options` optional	`ActOptions`

Returns

Promise<GuiClick>

Types

GuiClick · ActOptions

`diamonds`

methodplugins · game:read

TypeScript

diamonds() => Promise<number | null>

The diamonds the HUD's counter shows, or null before it shows any.

Returns

Promise<number \| null>

`gems`

methodplugins · game:read

TypeScript

gems() => Promise<number | null>

The gems the HUD's counter shows, or null before it shows any.

Returns

Promise<number \| null>

`greyButton`

methodplugins · game:act

TypeScript

greyButton(button: "soundBtn" | "denBtn" | "editCharBtn" | "swapBtn" | "actionsBtn" | "safeChatBtn" | "emotesBtn" | "worldMapBtn" | "furnBtn" | "eCardBtn" | "buddyListBtn" | "newsBtn" | "reportBtn" | "mySettingsBtn" | "partyBtn" | "playerWallBtn" | "combatCardDeckBtn" | "ajEmailBtn" | "sendChatBtn" | "ansChatBtn" | "emailChatBtn" | "chatRepeatBtn" | "chatHistUpDownBtn" | "questExitBtn" | "questPlayersBtn", grey: boolean, options?: ActOptions) => Promise<HudPartState>

Greys a button out so it cannot be pressed, or brings it back, as the client does in a private adventure lobby (GuiSoundButton.activateGrayState). Resolves with its state; lasts until the client greys or ungreys it itself. REFUSED for a button with no grey face.

Parameters

Name	Type
`button`	`"soundBtn" \| "denBtn" \| "editCharBtn" \| "swapBtn" \| "actionsBtn" \| "safeChatBtn" \| "emotesBtn" \| "worldMapBtn" \| "furnBtn" \| "eCardBtn" \| "buddyListBtn" \| "newsBtn" \| "reportBtn" \| "mySettingsBtn" \| "partyBtn" \| "playerWallBtn" \| "combatCardDeckBtn" \| "ajEmailBtn" \| "sendChatBtn" \| "ansChatBtn" \| "emailChatBtn" \| "chatRepeatBtn" \| "chatHistUpDownBtn" \| "questExitBtn" \| "questPlayersBtn"`
`grey`	`boolean`
`options` optional	`ActOptions`

Returns

Promise<HudPartState>

Types

ActOptions · HudPartState

`hide`

methodplugins · game:act

TypeScript

hide(parts: HudPart | readonly HudPart[], options?: ActOptions) => Promise<() => Promise<void>>

Hides parts of the HUD until the handle is called, whatever the client does meanwhile and through every rebuild: a button a plugin answers itself, a panel it draws over. It leaves a hole; showTopButton closes the strip up instead. The whole HUD is phantom.aj.view.hide('hud').

Parameters

Name	Type
`parts`	`HudPart \| readonly HudPart[]`
`options` optional	`ActOptions`

Returns

Promise<() => Promise<void>>

Types

ActOptions · HudPart

`hideTopRow`

methodplugins · game:act

TypeScript

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

Takes the whole top strip off (updateMainHudButtons(true)), as the client does under a screen. Nothing brings it back in one call: showTopButton each, or the client's next rebuild.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`isDarkened`

methodplugins · game:read

TypeScript

isDarkened() => Promise<boolean>

Whether the room is dimmed behind something, one reason the player will not walk.

Returns

Promise<boolean>

`isModal`

methodplugins · game:read

TypeScript

isModal() => Promise<boolean>

Whether a modal window is up, which keeps the room from the mouse (GuiManager.isModal).

Returns

Promise<boolean>

`isReconnecting`

methodplugins · game:read

TypeScript

isReconnecting() => Promise<boolean>

Whether the client is putting a dropped connection back together.

Returns

Promise<boolean>

`isShown`

methodplugins · game:read

TypeScript

isShown() => Promise<boolean>

Whether the HUD is shown (GuiManager.toggleHud hides it). False before it is built.

Returns

Promise<boolean>

`isUp`

methodplugins · game:read

TypeScript

isUp() => Promise<boolean>

Whether a HUD is on screen at all; false before the first room and in a den preview.

Returns

Promise<boolean>

`keepLabel`

methodplugins · game:act

TypeScript

keepLabel(label: HudLabel, text: string, options?: ActOptions) => Promise<() => Promise<void>>

Keeps one label saying text whatever the client writes there, through new rooms and the HUD being rebuilt, until the handle puts back what it said. The land's plate is fitted to the words as the client fits its own (resizeHudZoneNameBar).

Parameters

Name	Type
`label`	`HudLabel`
`text`	`string`
`options` optional	`ActOptions`

Returns

Promise<() => Promise<void>>

Types

HudLabel · ActOptions

`label`

methodplugins · game:read

TypeScript

label(label: HudLabel) => Promise<string | null>

What one label says on screen, or null when this HUD has not got it.

Parameters

Name	Type
`label`	`HudLabel`

Returns

Promise<string \| null>

Types

HudLabel

`labels`

methodplugins · game:read

TypeScript

labels() => Promise<HudLabels>

All four labels, read in one message so they are the same moment's HUD.

Returns

Promise<HudLabels>

Types

HudLabels

`mail`

methodplugins · game:read

TypeScript

mail() => Promise<number>

The unread jam-a-gram count the mail badge shows; 0 when it shows none.

Returns

Promise<number>

`mode`

methodplugins · game:read

TypeScript

mode() => Promise<HudMode | null>

Which HUD is up (GuiHud's frame label), or null when there is none.

Returns

Promise<HudMode \| null>

`part`

methodplugins · game:read

TypeScript

part(name: string) => Promise<GuiElement | null>

One part of the HUD, such as denBtn, or null when the HUD or the part is not there.

Parameters

Name	Type
`name`	`string`

Returns

Promise<GuiElement \| null>

Types

GuiElement

`parts`

methodplugins · game:read

TypeScript

parts() => Promise<GuiElement[]>

The HUD's own parts, each with its path (hud.<name>); none before the HUD is up.

Returns

Promise<GuiElement[]>

Types

GuiElement

`pinCurrency`

methodplugins · game:act

TypeScript

pinCurrency() => Promise<() => Promise<void>>

Holds the HUD's gem and diamond display open, rather than only while the mouse is on it, until the handle is called. The client fills it in as it opens, so it is opened again after each new balance arrives.

Returns

Promise<() => Promise<void>>

`setAvatar`

methodplugins · game:act

TypeScript

setAvatar(look: "drawn" | "grey", options?: ActOptions) => Promise<void>

Draws the HUD's own picture of the player's animal again, or greys it out.

Parameters

Name	Type
`look`	`"drawn" \| "grey"`
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`setDenVisitorCount`

methodplugins · game:act

TypeScript

setDenVisitorCount(count: number, options?: ActOptions) => Promise<void>

Shows a number on the HUD's den visitor badge, or hides it for 0. Only this screen changes.

Parameters

Name	Type
`count`	`number`
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`setLabel`

methodplugins · game:act

TypeScript

setLabel(label: HudLabel, text: string, options?: ActOptions) => Promise<string>

Writes over one label, once, and resolves with what it said before. The client writes its own words back the next time it has news (the next room, the next jam-a-gram); keepLabel holds them. NOT_READY when this HUD has not got the label.

Parameters

Name	Type
`label`	`HudLabel`
`text`	`string`
`options` optional	`ActOptions`

Returns

Promise<string>

Types

ActOptions · HudLabel

`setRoomLabel`

methodplugins · game:act

TypeScript

setRoomLabel(words: string, options?: ActOptions & { stringId?: number | undefined; }) => Promise<string>

Writes the room's name on the HUD, as the client does when a room is joined (the label, the name it remembers and the bar's width). Only this screen changes; the next room puts its own.

Parameters

Name	Type
`words`	`string`
`options` optional	`ActOptions & { stringId?: number \| undefined; }`

Returns

Promise<string>

Types

ActOptions

`setShown`

methodplugins · game:act

TypeScript

setShown(shown: boolean, options?: ActOptions) => Promise<boolean>

Shows or hides the HUD, as the client's own key does (GuiManager.toggleHud), and resolves with whether it is shown now. The client will not show it in a preview room.

Parameters

Name	Type
`shown`	`boolean`
`options` optional	`ActOptions`

Returns

Promise<boolean>

Types

ActOptions

`showTopButton`

methodplugins · game:act

TypeScript

showTopButton(part: HudPart, show: boolean, options?: ActOptions) => Promise<HudPartState>

Shows or hides a button of the top strip and closes the row up after it, the client's own call for the Journey Book, the player wall and the news (updateMainHudButtons). Lasts until the client rebuilds the HUD. A part of the bottom bar is not in the strip: NOT_READY.

Parameters

Name	Type
`part`	`HudPart`
`show`	`boolean`
`options` optional	`ActOptions`

Returns

Promise<HudPartState>

Types

HudPart · ActOptions · HudPartState

`windows`

methodplugins · game:read

TypeScript

windows() => Promise<HudPartState[]>

The windows the HUD opens over itself; visible says which is open.

Returns

Promise<HudPartState[]>

Types

HudPartState

Events

`onLabel`

eventplugins · game:read

TypeScript

onLabel(label: HudLabel, listener: (text: string) => void) => () => void

Hears one label change, whoever changed it: read in the game a few times a second, told on a change and once at the start. It follows the field through the HUD being rebuilt.

Parameters

Name	Type
`label`	`HudLabel`
`listener`	`(text: string) => void`

Returns

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

Types

HudLabel

`onRebuild`

eventplugins · game:read

TypeScript

onRebuild(listener: (mode: HudMode) => void) => () => void

Hears the client build the HUD again (GuiHud.init), after it jumps between the room's, an adventure's and a minigame's: with which one it built.

Parameters

Name	Type
`listener`	`(mode: HudMode) => void`

Returns

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

Types

HudMode

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.

`HudLabel`

The HUD's labels, by what they hold.

TypeScript

type HudLabel = 'land' | 'animal' | 'mail' | 'objective'

`HudLabels`

The HUD's four labels at once; null for each that is not on this HUD.

Field	Type
`land`	`string \| null`
`animal`	`string \| null`
`mail`	`string \| null`
`objective`	`string \| null`

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

`HudPartState`

One part of the HUD as it is now.

Field	Type
`name`	`string`	Its name on `gui.GuiHud`.
`there`	`boolean`	Whether this HUD has it: each of the three HUDs has parts the others have not.
`visible`	`boolean`	Whether it is drawn.
`greyed`	`boolean`	Whether the client has greyed it out, its way of saying it cannot be pressed (`isGray`, which its own handlers check first). False for a part with no grey state.

`HudPart`

Everything on the HUD by name.

TypeScript

type HudPart = | HudButton
  | HudWindow
  | 'chatBar'
  | 'chatHist'
  | 'chatTxt'
  | 'chatHistTxt'
  | 'money'
  | 'zoneName'
  | 'games'
  | 'journeyBook'
  | 'eCardCount'

`HudMode`

Which HUD is up: the room's, an adventure's or a minigame's.

TypeScript

type HudMode = 'room' | 'adventure' | 'minigame'

`GuiElement`

One of the client's display objects, described so it crosses whole.

Field	Type
`path`	`string \| null`	Where it is, as every other method takes it: a root and the steps down (`hud.chatBar`, `gui.#2.closeBtn`). Null for an element found under a place rather than a root, which has no path of its own: hand the place itself to the other methods instead.
`name`	`string`	Its name in the client; empty for a child the client never named.
`className`	`string`	Its class, dotted (`flash.text.TextField`).
`visible`	`boolean`	Its own `visible`. Whether it shows also depends on what holds it: `isVisible`.
`enabled`	`boolean`	Neither greyed out (`enabled`) nor deaf to the mouse (`mouseEnabled`).
`x`	`number`	Where it is in the coordinates of what holds it; `bounds` gives it on the stage.
`y`	`number`
`width`	`number`
`height`	`number`
`text`	`string \| null`	Its own text, or the text of the fields inside it as far as the walk went.
`childCount`	`number`	How many children it has, whether or not the walk went that deep.

`GuiClick`

What a click or a hover sent.

Field	Type
`dispatched`	`string[]`	The mouse events sent, in the order the player's own would arrive.

The HUD ​

Overview ​

Methods ​

button ​

buttons ​

click ​

diamonds ​

gems ​

greyButton ​

hide ​

hideTopRow ​

isDarkened ​

isModal ​

isReconnecting ​

isShown ​

isUp ​

keepLabel ​

label ​

labels ​

mail ​

mode ​

part ​

parts ​

pinCurrency ​

setAvatar ​

setDenVisitorCount ​

setLabel ​

setRoomLabel ​

setShown ​

showTopButton ​

windows ​

Events ​

onLabel ​

onRebuild ​

Types ​

HudLabel ​

HudLabels ​

ActOptions ​

HudPartState ​

HudPart ​

HudMode ​

GuiElement ​

GuiClick ​

The HUD

Overview

Methods

`button`

`buttons`

`click`

`diamonds`

`gems`

`greyButton`

`hide`

`hideTopRow`

`isDarkened`

`isModal`

`isReconnecting`

`isShown`

`isUp`

`keepLabel`

`label`

`labels`

`mail`

`mode`

`part`

`parts`

`pinCurrency`

`setAvatar`

`setDenVisitorCount`

`setLabel`

`setRoomLabel`

`setShown`

`showTopButton`

`windows`

Events

`onLabel`

`onRebuild`

Types

`HudLabel`

`HudLabels`

`ActOptions`

`HudPartState`

`HudPart`

`HudMode`

`GuiElement`

`GuiClick`