On-screen elements

phantom.aj.guiThe screen and sound

The client's display tree: find, click, type, wait for.

Scripts and plugins

A script has all of it, as phantom.aj.gui, 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
at()	The element at a target, with the words of the fields inside it, or null.	game:read
bounds()	Where an element is on the stage (getBounds(stage)), which is what the overlay and a click need; null for one that is not there or not on the stage.	game:read
click()	Clicks an element as the player does: the mouse events the client listens for there (asked of the element and what holds it), sent at the element so they travel up as a real click's do.	game:act
find()	The first element a query matches, highest up first, or null.	game:read
findAll()	Every element a query matches, highest up first, at most limit (20).	game:read
focus()	Puts the keyboard in a field (the element, or the first field inside it), as clicking it does.	game:act
hover()	Moves the mouse onto an element, or off it with leave, as rolling over it would.	game:act
isEnabled()	Whether an element answers the mouse: not greyed out, not deaf to it.	game:read
isVisible()	Whether an element shows: it and everything holding it visible.	game:read
keepVisible()	Keeps an element shown or hidden however often the client writes its visible or builds it again, until the handle is called; what the client had there is put back then.	game:act
on()	Hears an event one of the client's elements sends (click, rollOver, change).	game:read
setVisible()	Shows or hides an element once, by its own visible, as the client opens and closes its HUD windows.	game:act
text()	What an element shows: its own text when it is a field, or the words of the fields inside it (four levels down) joined by spaces, which is where buttons and windows keep theirs.	game:read
tree()	The display tree at a target, depth levels down (two by default), every node with the path the other methods take.	game:read
type()	Puts words in a field (the element, or the first field inside it) and sends the change event typing sends, so the client's own listeners react.	game:act
waitFor()	Waits until a query matches, looking again every few frames of the game, and resolves with the element.	game:read
onBuilt()	Hears the client build an element at a path: now if it is there, and each time again.	game:read
onClick()	Hears every click (press and release on the same thing) on anything the client draws.	game:read
onGone()	Hears the client take away the element at a path, each time it goes.	game:read
onPress()	Hears every press of the mouse on anything the client draws, with what it was.	game:read
onText()	Hears an element's text change (the element, or the first field in it), read in the game and told only on a change, and once at the start.	game:read
onVisible()	Hears an element's own visible change, which is how the HUD's windows open and close.	game:read

Methods

at

methodplugins · game:read

at(target: GuiTarget) => Promise<GuiElement | null>

The element at a target, with the words of the fields inside it, or null.

Parameters

Name	Type
target	GuiTarget

Returns

Promise<GuiElement \| null>

Types

GuiTarget · GuiElement

bounds

methodplugins · game:read

bounds(target: GuiTarget) => Promise<GuiBounds | null>

Where an element is on the stage (getBounds(stage)), which is what the overlay and a click need; null for one that is not there or not on the stage.

Parameters

Name	Type
target	GuiTarget

Returns

Promise<GuiBounds \| null>

Types

GuiBounds · GuiTarget

Example

const box = await phantom.aj.gui.bounds('hud.worldMapBtn');
if (box) await phantom.flash.overlay.rect({ ...box, stroke: { color: 0xffcc00, width: 2 } });

Run in Phantom

click

methodplugins · game:act

click(target: GuiTarget, options?: ActOptions & { force?: boolean | undefined; }) => Promise<GuiClick>

Clicks an element as the player does: the mouse events the client listens for there (asked of the element and what holds it), sent at the element so they travel up as a real click's do. The client's handlers run inside the dispatch, so a click that resolves has been heard. Throws NOT_READY when nothing is at the target and REFUSED when nothing listens for a click there, unless force sends the three events anyway.

Parameters

Name	Type
target	GuiTarget
options optional	ActOptions & { force?: boolean | undefined; }

Returns

Promise<GuiClick>

Types

ActOptions · GuiClick · GuiTarget

find

methodplugins · game:read

find(query: GuiQuery, search?: GuiSearch) => Promise<GuiElement | null>

The first element a query matches, highest up first, or null. Looks six levels down.

Parameters

Name	Type
query	GuiQuery
search optional	GuiSearch

Returns

Promise<GuiElement \| null>

Types

GuiQuery · GuiSearch · GuiElement

findAll

methodplugins · game:read

findAll(query: GuiQuery, { from, depth, limit }?: GuiSearch) => Promise<GuiElement[]>

Every element a query matches, highest up first, at most limit (20).

Parameters

Name	Type
query	GuiQuery
__1 optional	GuiSearch

Returns

Promise<GuiElement[]>

Types

GuiElement · GuiQuery · GuiSearch

focus

methodplugins · game:act

focus(target: GuiTarget, options?: ActOptions) => Promise<void>

Puts the keyboard in a field (the element, or the first field inside it), as clicking it does.

Parameters

Name	Type
target	GuiTarget
options optional	ActOptions

Returns

Promise<void>

Types

GuiTarget · ActOptions

hover

methodplugins · game:act

hover(target: GuiTarget, options?: ActOptions & { leave?: boolean | undefined; }) => Promise<GuiClick>

Moves the mouse onto an element, or off it with leave, as rolling over it would.

Parameters

Name	Type
target	GuiTarget
options optional	ActOptions & { leave?: boolean | undefined; }

Returns

Promise<GuiClick>

Types

GuiTarget · ActOptions · GuiClick

isEnabled

methodplugins · game:read

isEnabled(target: GuiTarget) => Promise<boolean>

Whether an element answers the mouse: not greyed out, not deaf to it. False when not there.

Parameters

Name	Type
target	GuiTarget

Returns

Promise<boolean>

Types

GuiTarget

isVisible

methodplugins · game:read

isVisible(target: GuiTarget) => Promise<boolean>

Whether an element shows: it and everything holding it visible. False when not there.

Parameters

Name	Type
target	GuiTarget

Returns

Promise<boolean>

Types

GuiTarget

keepVisible

methodplugins · game:act

keepVisible(target: GuiTarget, visible: boolean) => Promise<() => Promise<void>>

Keeps an element shown or hidden however often the client writes its visible or builds it again, until the handle is called; what the client had there is put back then. A target that is not there yet is waited for.

Parameters

Name	Type
target	GuiTarget
visible	boolean

Returns

Promise<() => Promise<void>>

Types

GuiTarget

on

methodplugins · game:read

on(target: GuiTarget, event: string, listener: (event: GuiEvent) => void, options?: GuiKeep) => () => void

Hears an event one of the client's elements sends (click, rollOver, change).

Parameters

Name	Type
target	GuiTarget
event	string
listener	(event: GuiEvent) => void
options optional	GuiKeep

Returns

() => void

Types

GuiEvent · GuiTarget · GuiKeep

Example

const stop = phantom.aj.gui.on('hud.newsBtn', 'click', () => console.log('news'), { keep: true });

Run in Phantom

setVisible

methodplugins · game:act

setVisible(target: GuiTarget, visible: boolean, options?: ActOptions) => Promise<void>

Shows or hides an element once, by its own visible, as the client opens and closes its HUD windows. The client writes many of these itself; keepVisible holds one.

Parameters

Name	Type
target	GuiTarget
visible	boolean
options optional	ActOptions

Returns

Promise<void>

Types

GuiTarget · ActOptions

text

methodplugins · game:read

text(target: GuiTarget) => Promise<string | null>

What an element shows: its own text when it is a field, or the words of the fields inside it (four levels down) joined by spaces, which is where buttons and windows keep theirs.

Parameters

Name	Type
target	GuiTarget

Returns

Promise<string \| null>

Types

GuiTarget

tree

methodplugins · game:read

tree(from?: GuiTarget, { depth }?: { depth?: number | undefined; }) => Promise<GuiNode | null>

The display tree at a target, depth levels down (two by default), every node with the path the other methods take. The way to learn what a window is made of before scripting it.

Parameters

Name	Type
from optional	GuiTarget
__1 optional	{ depth?: number | undefined; }

Returns

Promise<GuiNode \| null>

Types

GuiTarget · GuiNode · GuiElement

type

methodplugins · game:act

type(target: GuiTarget, text: string, options?: ActOptions) => Promise<string>

Puts words in a field (the element, or the first field inside it) and sends the change event typing sends, so the client's own listeners react. Nothing is submitted. Resolves with the field's text as the client now holds it.

Parameters

Name	Type
target	GuiTarget
text	string
options optional	ActOptions

Returns

Promise<string>

Types

GuiTarget · ActOptions

waitFor

methodplugins · game:read

waitFor(query: GuiQuery, options?: ActOptions & GuiSearch) => Promise<GuiElement>

Waits until a query matches, looking again every few frames of the game, and resolves with the element. Throws TIMEOUT when it never does.

Parameters

Name	Type
query	GuiQuery
options optional	ActOptions & GuiSearch

Returns

Promise<GuiElement>

Types

GuiElement · GuiQuery · GuiSearch · ActOptions

Events

onBuilt

eventplugins · game:read

onBuilt(target: GuiTarget, listener: (element: GuiElement) => void) => () => void

Hears the client build an element at a path: now if it is there, and each time again.

Parameters

Name	Type
target	GuiTarget
listener	(element: GuiElement) => void

Returns

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

Types

GuiTarget · GuiElement

onClick

eventplugins · game:read

onClick(listener: (press: GuiPress) => void) => () => void

Hears every click (press and release on the same thing) on anything the client draws.

Parameters

Name	Type
listener	(press: GuiPress) => void

Returns

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

Types

GuiPress

onGone

eventplugins · game:read

onGone(target: GuiTarget, listener: () => void) => () => void

Hears the client take away the element at a path, each time it goes.

Parameters

Name	Type
target	GuiTarget
listener	() => void

Returns

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

Types

GuiTarget

onPress

eventplugins · game:read

onPress(listener: (press: GuiPress) => void) => () => void

Hears every press of the mouse on anything the client draws, with what it was.

Parameters

Name	Type
listener	(press: GuiPress) => void

Returns

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

Types

GuiPress

onText

eventplugins · game:read

onText(target: GuiTarget, listener: (text: string) => void, options?: GuiKeep) => () => void

Hears an element's text change (the element, or the first field in it), read in the game and told only on a change, and once at the start. keep follows it as the client rebuilds it.

Parameters

Name	Type
target	GuiTarget
listener	(text: string) => void
options optional	GuiKeep

Returns

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

Types

GuiKeep · GuiTarget

onVisible

eventplugins · game:read

onVisible(target: GuiTarget, listener: (visible: boolean) => void, options?: GuiKeep) => () => void

Hears an element's own visible change, which is how the HUD's windows open and close.

Parameters

Name	Type
target	GuiTarget
listener	(visible: boolean) => void
options optional	GuiKeep

Returns

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

Types

GuiTarget · GuiKeep

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.

GuiTarget

Something on screen, as every gui method takes it: a path from a root (hud.chatBar, gui.#2.closeBtn, stage.loader), or a place in Flash already held (a typed place, a handle, what screens.place gives).

type GuiTarget = string | FlashPlaceLike

GuiNode

An element with what is inside it, as tree gives the display tree.

type GuiNode = GuiElement & { children: readonly GuiNode[] }

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.

GuiQuery

What to look for. Every rule given has to hold; name, class and text match part of the element's own name, dotted class or text, in any case.

Field	Type
name optional	string | undefined
class optional	string | undefined
text optional	string | undefined	A field's own words: finds a button's label, and clicking the label works the button.
visible optional	boolean | undefined	Only elements that show: neither hidden nor inside something hidden.

GuiSearch

Where a search looks: under a root or an element (gui by default), how deep, how many.

Field	Type
from optional	GuiTarget | undefined
depth optional	number | undefined
limit optional	number | undefined

GuiBounds

A rectangle on the stage, in stage coordinates.

Field	Type
x	number
y	number
width	number
height	number

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

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.

GuiKeep

Whether a listener follows its element through the client building it again.

Field	Type
keep optional	boolean | undefined	Put the listener on each new element the client builds at the target, and take it off the old one. Off by default: the element there when asked, and nothing after it.
everyFrames optional	number | undefined	How often a value is read in the game, in frames (6, about four times a second).

GuiEvent

An event one of the client's own elements sent, as on hands it over.

Field	Type
type	string
stageX	number	Where the mouse was on the stage; 0 for an event with no position.
stageY	number
raw	Record<string, FlashValue>	Everything the event carried. Its objects are handles the bridge releases once the listener returns, so use them (or start a request with them) before then.

GuiPress

A press or a click on anything the client draws, as onPress and onClick hand it over.

Field	Type
action	"click" | "press"	press as the button goes down, click once it has come up on the same thing.
name	string	The name of what was under the mouse.
className	string	Its class, dotted.
text	string | null	Its words, when it is a text field.
names	string[]	The names of everything it is inside, outermost first, ending with its own.
path	string | null	Its path, as the other methods take it; null when it is deeper than twelve.
stageX	number
stageY	number