Dialogs and popups

phantom.aj.popupsThe screen and sound

The client's plain dialogs.

Scripts and plugins

A script has all of it, as phantom.aj.popups, 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
`all()`	Every popup open, the first opened first (`SBPopupManager.popups`).	`game:read`
`answer()`	Presses one of a popup's buttons, as the player does: the button its kind offers for the answer, which the client's handler hears inside the press.	`game:act`
`autoAnswer()`	Answers every popup that offers `choice` (and matches, and passes `when`) as it opens, until the handle is called or `times` have been answered.	`game:act`
`close()`	Closes a popup through its own `SBPopup.close`, as the client closes them, so its close callback and the next queued popup happen as usual.	`game:act`
`top()`	The last opened popup whose name, content or class holds `match`; the last opened without.	`game:read`
`waitFor()`	Waits for a popup that matches, and resolves with it; one already open answers at once.	`game:read`
`onClose()`	Hears each popup the client closes, read inside its own `close` before it goes.	`game:read`
`onOpen()`	Hears each popup the client opens, read inside its own `open`.	`game:read`

popups.prize: A prize waiting to be kept or thrown away.

Member	What it does	Plugins
`current()`	The prize waiting, or null.	`game:read`
`discard()`	Throws the prize away, as its Discard button does.	`game:act`
`dismiss()`	Takes the prize's popup down without answering (`destroyPrizePopup`): the server still has it.	`game:act`
`keep()`	Keeps the prize, as its Keep button does, and resolves with it once the client lets it go.	`game:act`
`show()`	Has the client show the prize's popup (`showPrizePopupIfAny`), and resolves with the prize.	`game:act`
`onChange()`	Hears a prize arrive, show, and be kept, thrown away or dropped, and gem gifts.	`game:read`

popups.tooltip: The client's tooltip.

Member	What it does	Plugins
`current()`	The HUD's tooltip as it stands, or null before the client has made it.	`game:read`
`hide()`	Hides the tooltip and stops its timer (`resetTimerAndSetVisibility`).	`game:act`
`setText()`	Puts other words in the tooltip as it stands (`setToolTipText`), where it is.	`game:act`
`show()`	Shows words in the client's own tooltip at a place on the stage, as its own buttons do (`ToolTipPopup.init` on the window layer, then its timer), and resolves once it holds them.	`game:act`
`onShow()`	Hears any of the client's tooltips being given words, with where it is.	`game:read`

Methods

`all`

methodplugins · game:read

TypeScript

all() => Promise<Popup[]>

Every popup open, the first opened first (SBPopupManager.popups).

Returns

Promise<Popup[]>

Types

Popup · PopupKind · PopupAnswer · PopupChange

`answer`

methodplugins · game:act

TypeScript

answer(choice: PopupAnswer, options?: ActOptions & PopupMatch) => Promise<Popup>

Presses one of a popup's buttons, as the player does: the button its kind offers for the answer, which the client's handler hears inside the press. Resolves with the popup answered. Throws NOT_READY when no popup matches, REFUSED when it offers no such answer.

Parameters

Name	Type
`choice`	`PopupAnswer`
`options` optional	`ActOptions & PopupMatch`

Returns

Promise<Popup>

Types

ActOptions · PopupMatch · Popup · PopupAnswer

`autoAnswer`

methodplugins · game:act

TypeScript

autoAnswer(choice: PopupAnswer, options?: AutoAnswer) => Promise<AutoAnswering>

Answers every popup that offers choice (and matches, and passes when) as it opens, until the handle is called or times have been answered.

Parameters

Name	Type
`choice`	`PopupAnswer`
`options` optional	`AutoAnswer`

Returns

Promise<AutoAnswering>

Types

AutoAnswer · AutoAnswering · PopupAnswer

Example

TypeScript

const stop = await phantom.aj.popups.autoAnswer('ok', {
  when: (popup) => popup.message?.includes('room for') ?? false,
});

Run in Phantom

`close`

methodplugins · game:act

TypeScript

close(options?: ActOptions & PopupMatch) => Promise<Popup>

Closes a popup through its own SBPopup.close, as the client closes them, so its close callback and the next queued popup happen as usual. Resolves with the popup closed.

Parameters

Name	Type
`options` optional	`ActOptions & PopupMatch`

Returns

Promise<Popup>

Types

Popup · ActOptions · PopupMatch

`top`

methodplugins · game:read

TypeScript

top(match?: string | undefined) => Promise<Popup | null>

The last opened popup whose name, content or class holds match; the last opened without.

Parameters

Name	Type
`match` optional	`string \| undefined`

Returns

Promise<Popup \| null>

Types

Popup

`waitFor`

methodplugins · game:read

TypeScript

waitFor(match?: string | undefined, options?: ActOptions) => Promise<Popup>

Waits for a popup that matches, and resolves with it; one already open answers at once.

Parameters

Name	Type
`match` optional	`string \| undefined`
`options` optional	`ActOptions`

Returns

Promise<Popup>

Types

Popup · ActOptions

Events

`onClose`

eventplugins · game:read

TypeScript

onClose(listener: (popup: PopupChange) => void) => () => void

Hears each popup the client closes, read inside its own close before it goes.

Parameters

Name	Type
`listener`	`(popup: PopupChange) => void`

Returns

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

Types

PopupChange

`onOpen`

eventplugins · game:read

TypeScript

onOpen(listener: (popup: PopupChange) => void) => () => void

Hears each popup the client opens, read inside its own open.

Parameters

Name	Type
`listener`	`(popup: PopupChange) => void`

Returns

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

Types

PopupChange

`popups.prize`

A prize waiting to be kept or thrown away.

`current`

methodplugins · game:read

TypeScript

current() => Promise<PendingPrize | null>

The prize waiting, or null.

Returns

Promise<PendingPrize \| null>

Types

PendingPrize

`discard`

methodplugins · game:act

TypeScript

discard(options?: ActOptions) => Promise<PendingPrize>

Throws the prize away, as its Discard button does.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<PendingPrize>

Types

ActOptions · PendingPrize

`dismiss`

methodplugins · game:act

TypeScript

dismiss(options?: ActOptions) => Promise<PendingPrize>

Takes the prize's popup down without answering (destroyPrizePopup): the server still has it.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<PendingPrize>

Types

ActOptions · PendingPrize

`keep`

methodplugins · game:act

TypeScript

keep(options?: ActOptions) => Promise<PendingPrize>

Keeps the prize, as its Keep button does, and resolves with it once the client lets it go.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<PendingPrize>

Types

ActOptions · PendingPrize

`show`

methodplugins · game:act

TypeScript

show(options?: ActOptions) => Promise<PendingPrize>

Has the client show the prize's popup (showPrizePopupIfAny), and resolves with the prize.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<PendingPrize>

Types

ActOptions · PendingPrize

`onChange`

eventplugins · game:read

TypeScript

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

Hears a prize arrive, show, and be kept, thrown away or dropped, and gem gifts.

Parameters

Name	Type
`listener`	`(change: PrizeChange) => void`

Returns

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

Types

PrizeChange

`popups.tooltip`

The client's tooltip.

`current`

methodplugins · game:read

TypeScript

current() => Promise<Tooltip | null>

The HUD's tooltip as it stands, or null before the client has made it.

Returns

Promise<Tooltip \| null>

Types

Tooltip

`hide`

methodplugins · game:act

TypeScript

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

Hides the tooltip and stops its timer (resetTimerAndSetVisibility).

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`setText`

methodplugins · game:act

TypeScript

setText(text: string, options?: ActOptions) => Promise<void>

Puts other words in the tooltip as it stands (setToolTipText), where it is.

Parameters

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

Returns

Promise<void>

Types

ActOptions

`show`

methodplugins · game:act

TypeScript

show(text: string, options?: ActOptions & { x?: number | undefined; y?: number | undefined; }) => Promise<void>

Shows words in the client's own tooltip at a place on the stage, as its own buttons do (ToolTipPopup.init on the window layer, then its timer), and resolves once it holds them.

Parameters

Name	Type
`text`	`string`
`options` optional	`ActOptions & { x?: number \| undefined; y?: number \| undefined; }`

Returns

Promise<void>

Types

ActOptions

`onShow`

eventplugins · game:read

TypeScript

onShow(listener: (shown: TooltipShown) => void) => () => void

Hears any of the client's tooltips being given words, with where it is.

Parameters

Name	Type
`listener`	`(shown: TooltipShown) => void`

Returns

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

Types

TooltipShown

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.

`Popup`

One of the client's popups open now (com.sbi.popup.SBPopup).

TypeScript

type Popup = PopupChange & {
  /** Where it is in `SBPopupManager.popups`, the first opened first. */
  index: number;
  visible: boolean;
}

`PopupKind`

What kind of popup it is, by its class: which answers it offers.

TypeScript

type PopupKind = 'ok' | 'yesNo' | 'okCancel' | 'blockCancel' | 'leaveCancel' | 'message' | 'other'

`PopupAnswer`

A button a popup offers.

TypeScript

type PopupAnswer = 'ok' | 'yes' | 'no' | 'cancel' | 'block' | 'leave'

`PopupChange`

A popup as the client's own open and close see it.

Field	Type
`name`	`string`
`className`	`string`	Its class, dotted: `com.sbi.popup.SBYesNoPopup`.
`kind`	`PopupKind`
`content`	`string \| null`	The name of what it shows (`SBPopup.content.name`), which says more than its own name.
`message`	`string \| null`	Its words, as the player reads them.
`modal`	`boolean`	Nothing else answers the mouse while a modal popup is up.
`answers`	`readonly PopupAnswer[]`	The buttons it offers.

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

`PopupMatch`

Which popup an act is about: the last opened whose name, content or class holds match.

Field	Type
`match` optional	`string \| undefined`

`AutoAnswer`

When an auto answer applies.

TypeScript

type AutoAnswer = PopupMatch & {
  /** A test of your own on each popup that offers the answer. */
  when?: (popup: PopupChange) => boolean;
  /** Answer this many, then stop by itself. For ever when left out. */
  times?: number;
}

`AutoAnswering`

A running auto answer: call it to stop.

TypeScript

type AutoAnswering = (() => Promise<void>) & {
  /** How many popups it has answered. */
  readonly answered: number;
}

`PendingPrize`

A prize the server gave and the player has not yet kept or thrown away (GuiManager._prizeData).

Field	Type
`defId`	`number`
`userVarId`	`number`	The user variable the answer is written to.
`clothing`	`boolean`
`itemName`	`string \| null`
`description`	`string \| null`
`color`	`number`

`PrizeChange`

Something happening to a prize: it arrived, its popup was shown, it was kept, thrown away or dropped.

Field	Type
`kind`	`"arrived" \| "shown" \| "kept" \| "discarded" \| "dropped" \| "gemGift"`
`defId`	`number \| null`
`itemName`	`string \| null`
`gems`	`number \| null`	The gems of a gem gift (`setupGemGiftPopup`), null for the rest.

`Tooltip`

The client's tooltip (GuiManager.toolTip, a gui.ToolTipPopup).

Field	Type
`visible`	`boolean`
`text`	`string`
`details`	`{ label: string; value: string; }[]`	The extra rows some tooltips carry (an item's attributes), as label and value.
`x`	`number`
`y`	`number`
`waiting`	`boolean`	Whether it is counting down to show (`toolTipTimer.running`).

`TooltipShown`

A tooltip being given words, by any of the client's tooltips (ToolTipPopup.setToolTipText).

Field	Type
`text`	`string`
`x`	`number`
`y`	`number`
`visible`	`boolean`

Dialogs and popups ​

Overview ​

Methods ​

all ​

answer ​

autoAnswer ​

close ​

top ​

waitFor ​

Events ​

onClose ​

onOpen ​

popups.prize ​

current ​

discard ​

dismiss ​

keep ​

show ​

onChange ​

popups.tooltip ​

current ​

hide ​

setText ​

show ​

onShow ​

Types ​

Popup ​

PopupKind ​

PopupAnswer ​

PopupChange ​

ActOptions ​

PopupMatch ​

AutoAnswer ​

AutoAnswering ​

PendingPrize ​

PrizeChange ​

Tooltip ​

TooltipShown ​

Dialogs and popups

Overview

Methods

`all`

`answer`

`autoAnswer`

`close`

`top`

`waitFor`

Events

`onClose`

`onOpen`

`popups.prize`

`current`

`discard`

`dismiss`

`keep`

`show`

`onChange`

`popups.tooltip`

`current`

`hide`

`setText`

`show`

`onShow`

Types

`Popup`

`PopupKind`

`PopupAnswer`

`PopupChange`

`ActOptions`

`PopupMatch`

`AutoAnswer`

`AutoAnswering`

`PendingPrize`

`PrizeChange`

`Tooltip`

`TooltipShown`