Keyboard shortcuts

phantom.aj.inputThe screen and sound

Keys and the mouse.

Scripts and plugins

A script has all of it, as phantom.aj.input, 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
`bind()`	Binds a keyboard shortcut and calls `listener` for each press (and release, with `release`).	`game:act`
`bound()`	The shortcuts bound through this area now, and how each is heard.	`game:read`
`movementKeys()`	Whether the arrow keys walk the player's animal (`_keyboardEnabled`).	`game:read`
`pointer()`	Where the pointer is over the room and which buttons the room believes are held, read in one message: what the game is acting on, rather than Flash's own idea.	`game:read`
`pointerInRoom()`	Where the pointer is in the room's own coordinates, the ones avatars walk in (`convertScreenToWorldSpace`), or null with no room.	`game:read`
`releaseMouse()`	Lets go of the mouse for the room, as the button coming up does (`forceMouseUp`): the animal stops following a pointer a plugin took mid-press.	`game:act`
`setMovementKeys()`	Stops the arrow keys walking the animal, or lets them again, so a plugin can have them: the room's own switch (`_keyboardEnabled`), read every frame.	`game:act`
`onAnyInput()`	Hears every press and every key anywhere in the game, whatever is on screen (`KeepAlive.inputReceivedHandler`): the one event that hears the player doing anything.	`game:read`
`onAnyKey()`	Hears every key the player presses while the game has the keyboard, without naming any first: for asking the player to pick a key.	`game:read`
`onClick()`	Hears every press over the room the game acts on, left and right (`RoomManagerView`'s `onMouseDownEvt`, `onMouseRightEvt`): not while a window is modal or the screen darkened.	`game:read`
`onPointer()`	Hears the pointer move over the room, read in the game every `everyFrames` frames (6, about four times a second) and told only when something changed.	`game:read`
`onRelease()`	Hears the button come up (`onMouseUpEvt`, `onMouseRightUpEvt`): where a drag ends.	`game:read`
`onShortcut()`	Hears every shortcut bound through this area, told apart by `shortcut`: for code that binds in one place and listens in another.	`game:read`

Methods

`bind`

methodplugins · game:act

TypeScript

bind(shortcut: string, listener: (press: ShortcutPress) => void, options?: ShortcutOptions & ActOptions) => Promise<Shortcut>

Binds a keyboard shortcut and calls listener for each press (and release, with release). Resolves once the loader is hearing it, with the handle that takes it away.

Keys are named as phantom.flash.onKey names them: 'H', 'F2', 'Space', 'ArrowUp', 'Ctrl+Shift+H', with Cmd counting as Ctrl; a name it does not know is REFUSED. The same shortcut may be bound more than once, each binding heard on its own. A release is told only for a press that was heard, whatever has the keyboard by then.

Parameters

Name	Type
`shortcut`	`string`
`listener`	`(press: ShortcutPress) => void`
`options` optional	`ShortcutOptions & ActOptions`

Returns

Promise<Shortcut>

Types

ShortcutPress · ShortcutOptions · ActOptions · Shortcut

Example

TypeScript

const walk = await phantom.aj.input.bind('W', (press) => console.log('W', press.phase), {
  release: true,
  anyModifiers: true,
  consume: true,
});
await walk();

Run in Phantom

`bound`

methodplugins · game:read

TypeScript

bound() => BoundShortcut[]

The shortcuts bound through this area now, and how each is heard.

Returns

BoundShortcut[]

Types

BoundShortcut

`movementKeys`

methodplugins · game:read

TypeScript

movementKeys() => Promise<boolean>

Whether the arrow keys walk the player's animal (_keyboardEnabled). False before the room manager is there.

Returns

Promise<boolean>

`pointer`

methodplugins · game:read

TypeScript

pointer() => Promise<PointerState | null>

Where the pointer is over the room and which buttons the room believes are held, read in one message: what the game is acting on, rather than Flash's own idea. Null before the first room.

Returns

Promise<PointerState \| null>

Types

PointerState

`pointerInRoom`

methodplugins · game:read

TypeScript

pointerInRoom() => Promise<Point | null>

Where the pointer is in the room's own coordinates, the ones avatars walk in (convertScreenToWorldSpace), or null with no room.

Returns

Promise<Point \| null>

Types

Point

`releaseMouse`

methodplugins · game:act

TypeScript

releaseMouse(options?: ActOptions) => Promise<PointerState>

Lets go of the mouse for the room, as the button coming up does (forceMouseUp): the animal stops following a pointer a plugin took mid-press. Resolves with the pointer after; NOT_READY before the first room.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<PointerState>

Types

ActOptions · PointerState

`setMovementKeys`

methodplugins · game:act

TypeScript

setMovementKeys(on: boolean, options?: ActOptions) => Promise<boolean>

Stops the arrow keys walking the animal, or lets them again, so a plugin can have them: the room's own switch (_keyboardEnabled), read every frame. It lasts room to room until set back; nothing is sent. Resolves with the switch as the game now holds it; NOT_READY before the first room.

Parameters

Name	Type
`on`	`boolean`
`options` optional	`ActOptions`

Returns

Promise<boolean>

Types

ActOptions

Example

TypeScript

await phantom.aj.input.setMovementKeys(false);
const up = await phantom.aj.input.bind('ArrowUp', () => console.log('up'), { consume: true });

Run in Phantom

Events

`onAnyInput`

eventplugins · game:read

TypeScript

onAnyInput(listener: (input: AnyInput) => void) => () => void

Hears every press and every key anywhere in the game, whatever is on screen (KeepAlive.inputReceivedHandler): the one event that hears the player doing anything.

Parameters

Name	Type
`listener`	`(input: AnyInput) => void`

Returns

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

Types

AnyInput

`onAnyKey`

eventplugins · game:read

TypeScript

onAnyKey(listener: (press: KeyPress) => void) => () => void

Hears every key the player presses while the game has the keyboard, without naming any first: for asking the player to pick a key. Presses only, no repeats, nothing kept from the game, and quiet while a message is being written, so it never reads what the player types.

Parameters

Name	Type
`listener`	`(press: KeyPress) => void`

Returns

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

Types

KeyPress

`onClick`

eventplugins · game:read

TypeScript

onClick(listener: (click: RoomClick) => void) => () => void

Hears every press over the room the game acts on, left and right (RoomManagerView's onMouseDownEvt, onMouseRightEvt): not while a window is modal or the screen darkened. A press on the HUD or a window is heard by onAnyInput instead.

Parameters

Name	Type
`listener`	`(click: RoomClick) => void`

Returns

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

Types

RoomClick

`onPointer`

eventplugins · game:read

TypeScript

onPointer(listener: (pointer: PointerState) => void, options?: { everyFrames?: number | undefined; }) => () => void

Hears the pointer move over the room, read in the game every everyFrames frames (6, about four times a second) and told only when something changed. Nothing crosses while it sits still. For a press use onClick, which is told at once.

Parameters

Name	Type
`listener`	`(pointer: PointerState) => void`
`options` optional	`{ everyFrames?: number \| undefined; }`

Returns

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

Types

PointerState

`onRelease`

eventplugins · game:read

TypeScript

onRelease(listener: (click: RoomClick) => void) => () => void

Hears the button come up (onMouseUpEvt, onMouseRightUpEvt): where a drag ends.

Parameters

Name	Type
`listener`	`(click: RoomClick) => void`

Returns

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

Types

RoomClick

`onShortcut`

eventplugins · game:read

TypeScript

onShortcut(listener: (press: ShortcutPress) => void) => () => void

Hears every shortcut bound through this area, told apart by shortcut: for code that binds in one place and listens in another.

Parameters

Name	Type
`listener`	`(press: ShortcutPress) => void`

Returns

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

Types

ShortcutPress

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.

`ShortcutPress`

A shortcut pressed or let go.

Field	Type
`shortcut`	`string`	The shortcut, exactly as `bind` was given it.
`phase`	`"down" \| "up"`	Down as the key is pressed (and for each repeat, with `repeat`), up as it is let go.
`code`	`number`	Flash's key code (`KeyboardEvent.keyCode`), which for these keys is the browser's.
`ctrl`	`boolean`
`shift`	`boolean`
`alt`	`boolean`
`consumed`	`boolean`	Whether the game, the chat bar included, was kept from the key.

`ShortcutOptions`

How a shortcut is heard.

Field	Type
`release` optional	`boolean \| undefined`	Also hear the key go up (`phase: 'up'`), for a key that is held, such as a movement key.
`repeat` optional	`boolean \| undefined`	Hear the repeats of a key held down. Off by default.
`consume` optional	`boolean \| undefined`	Keep the key from the game, which then never hears it, and keep the character it would type out of the chat bar, its repeats included. Off by default.
`anyModifiers` optional	`boolean \| undefined`	Hear the key whatever modifiers are held. By default a modifier the shortcut does not name must not be held, so `W` is not heard as Shift+W.
`whileTyping` optional	`ShortcutTyping \| undefined`	`'empty'` (the default) goes quiet while a message is being written in the chat bar, so a shortcut on W does not fire in the middle of "wow". `'always'` is heard whatever has the keyboard: for a key that is not a letter (`Escape`, `F2`, `Ctrl+…`) the player wants while typing.
`yieldToTyping` optional	`boolean \| undefined`	Give way to typing as well: quiet, and so not consumed, while the player has clicked into the chat bar, empty or not, until they leave it (Escape, Enter, a click elsewhere), and a press still held when typing begins is let go. Decided in Flash at each press, with no round trip. For a key that walks, so a message can start with W. Off by default.

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

`Shortcut`

A shortcut bound with bind: call it to take the shortcut away. Calling it twice does nothing.

TypeScript

type Shortcut = (() => Promise<void>) & {
  /** The shortcut as it was named, which is how its presses are told apart. */
  readonly shortcut: string;
  /** How it is heard, every option filled in. */
  readonly options: Required<ShortcutOptions>;
}

`BoundShortcut`

A bound shortcut, as bound() lists it.

Field	Type
`shortcut`	`string`
`options`	`Required<ShortcutOptions>`

`KeyPress`

A key as the listener hears it.

Field	Type
`code`	`number`
`char`	`string`	The character typed, when there is one.
`ctrl`	`boolean`
`shift`	`boolean`
`alt`	`boolean`
`phase`	`"down" \| "up"`
`consumed`	`boolean`	Whether the loader kept the key from the game, and out of the chat bar. False for a key bound without `consume`, and for a loader from before it said so.

`PointerState`

Where the pointer is over the room, and which buttons the room believes are held.

Field	Type
`x`	`number`	Where the pointer was on the last move or press, in stage pixels (`_mousePos`).
`y`	`number`
`held`	`boolean`	The left button is held as far as the room is concerned, which makes the animal follow the pointer (`_bMouseDown`). A click that opened a window can leave it true: `releaseMouse` is the client's own way out.
`rightHeld`	`boolean`	The right button is held (`_bMouseRight`, which the room counts rather than flags).
`moved`	`boolean`	A move the room has been told of and has not yet worked on (`_bMouseMove`).

`Point`

A point in the room or on the stage, in pixels. One type for every area.

Field	Type
`x`	`number`
`y`	`number`

`RoomClick`

A press or a release over the room, as the room's own stage handler heard it.

Field	Type
`phase`	`"down" \| "up"`
`button`	`"left" \| "right"`
`x`	`number`	Where, in stage pixels (`MouseEvent.stageX`, `stageY`).
`y`	`number`
`ctrl`	`boolean`
`shift`	`boolean`
`alt`	`boolean`
`target`	`string \| null`	The name of the display object under the pointer, or null for the many the client never named.

`AnyInput`

One press or key press anywhere in the game.

Field	Type
`type`	`string`	Flash's own name for it: `mouseDown` or `keyDown`.

Keyboard shortcuts ​

Overview ​

Methods ​

bind ​

bound ​

movementKeys ​

pointer ​

pointerInRoom ​

releaseMouse ​

setMovementKeys ​

Events ​

onAnyInput ​

onAnyKey ​

onClick ​

onPointer ​

onRelease ​

onShortcut ​

Types ​

ShortcutPress ​

ShortcutOptions ​

ActOptions ​

Shortcut ​

BoundShortcut ​

KeyPress ​

PointerState ​

Point ​

RoomClick ​

AnyInput ​

Keyboard shortcuts

Overview

Methods

`bind`

`bound`

`movementKeys`

`pointer`

`pointerInRoom`

`releaseMouse`

`setMovementKeys`

Events

`onAnyInput`

`onAnyKey`

`onClick`

`onPointer`

`onRelease`

`onShortcut`

Types

`ShortcutPress`

`ShortcutOptions`

`ActOptions`

`Shortcut`

`BoundShortcut`

`KeyPress`

`PointerState`

`Point`

`RoomClick`

`AnyInput`