Getting about

phantom.aj.navigationWhere you are

Walking: the room's grid, routes, walks that resolve with where the player arrived.

Scripts and plugins

A script has all of it, as phantom.aj.navigation, 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
`cellAt()`	What the client's own collision test says of a point (`collisionTestGrid`), or null with no room.	`game:read`
`distances()`	How far each point is on foot from the player, in pixels, in one search; null for one there is no way to.	`game:read`
`grid()`	The room's walk grid (`RoomManagerWorld.instance._roomGrid._grid`), read whole in one message, or null for a room authored without one.	`game:read`
`nearestOpen()`	The open ground the client would walk to for a point (`findClosestOpenGridCell`), or null.	`game:read`
`plan()`	A walk from where the player stands (or `from`) to a point, worked out before a step is taken.	`game:read`
`position()`	Where the player stands, or null with no animal in the room.	`game:read`
`reach()`	Whether the player can walk to within `within` (40) pixels of a point.	`game:read`
`respawn()`	Puts the player back at the room's spawn point (`teleportPlayerToDefault`): the way out of somewhere a walk through walls left them with no way out of.	`game:act`
`steer()`	Holds arrow keys down as the room hears them, so the player walks as they would at the keyboard, until the function it gives back lets go.	`game:act`
`stop()`	Stops the player where they are (`forceStopMovement`), ending any walk here too.	`game:act`
`teleport()`	Puts the player somewhere at once, as the client's own teleport does (`teleportPlayer`): one move flagged immediate, seen by everyone in the room.	`game:act`
`tour()`	Points put in the order that covers them with the least walking, from where the player stands.	`game:read`
`walkThrough()`	Walks the player through walls in a straight line, a step every few frames (`AvatarManager.movePlayer`), and puts them on the point.	`game:act`
`walkTo()`	Walks the player to a point by the room's grid, as hops the client walks one after another, and resolves once they are within `within` (40) pixels.	`game:act`
`walkToSpawn()`	Walks the player to one of the room's spawn points by name (`RoomManagerView.walkToSpawn`), scattered within its radius as the client scatters arrivals, and resolves once they stop.	`game:act`

Methods

`cellAt`

methodplugins · game:read

TypeScript

cellAt(point: Point) => Promise<"air" | "open" | "wall" | "phantom" | null>

What the client's own collision test says of a point (collisionTestGrid), or null with no room.

Parameters

Name	Type
`point`	`Point`

Returns

Promise<"air" \| "open" \| "wall" \| "phantom" \| null>

Types

Point

`distances`

methodplugins · game:read

TypeScript

distances(points: readonly (Point | null)[]) => Promise<(number | null)[]>

How far each point is on foot from the player, in pixels, in one search; null for one there is no way to. Straight lines in a room with no grid.

Parameters

Name	Type
`points`	`readonly (Point \| null)[]`

Returns

Promise<(number \| null)[]>

Types

Point

`grid`

methodplugins · game:read

TypeScript

grid() => Promise<RoomGrid | null>

The room's walk grid (RoomManagerWorld.instance._roomGrid._grid), read whole in one message, or null for a room authored without one. Cut down to the player's own animal: a flier's grid is not a walker's.

Returns

Promise<RoomGrid \| null>

`nearestOpen`

methodplugins · game:read

TypeScript

nearestOpen(point: Point, options?: { clockwise?: boolean | undefined; }) => Promise<Point | null>

The open ground the client would walk to for a point (findClosestOpenGridCell), or null.

Parameters

Name	Type
`point`	`Point`
`options` optional	`{ clockwise?: boolean \| undefined; }`

Returns

Promise<Point \| null>

Types

Point

`plan`

methodplugins · game:read

TypeScript

plan(to: Point, options?: { from?: Point | undefined; }) => Promise<RoutePlan>

A walk from where the player stands (or from) to a point, worked out before a step is taken.

Parameters

Name	Type
`to`	`Point`
`options` optional	`{ from?: Point \| undefined; }`

Returns

Promise<RoutePlan>

Types

RoutePlan · Point

`position`

methodplugins · game:read

TypeScript

position() => Promise<Point | null>

Where the player stands, or null with no animal in the room.

Returns

Promise<Point \| null>

Types

Point

`reach`

methodplugins · game:read

TypeScript

reach(to: Point, options?: { within?: number | undefined; }) => Promise<Reach>

Whether the player can walk to within within (40) pixels of a point.

Parameters

Name	Type
`to`	`Point`
`options` optional	`{ within?: number \| undefined; }`

Returns

Promise<Reach>

Types

Reach · Point

`respawn`

methodplugins · game:act

TypeScript

respawn(options?: ActOptions) => Promise<Point>

Puts the player back at the room's spawn point (teleportPlayerToDefault): the way out of somewhere a walk through walls left them with no way out of. Resolves with where they are.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<Point>

Types

Point · ActOptions

`steer`

methodplugins · game:act

TypeScript

steer(keys: Steering, options?: ActOptions) => Promise<() => Promise<void>>

Holds arrow keys down as the room hears them, so the player walks as they would at the keyboard, until the function it gives back lets go. Kept in the game every frame, so the client's own key handling does not undo it.

Parameters

Name	Type
`keys`	`Steering`
`options` optional	`ActOptions`

Returns

Promise<() => Promise<void>>

Types

Steering · ActOptions

`stop`

methodplugins · game:act

TypeScript

stop(options?: ActOptions) => Promise<Point>

Stops the player where they are (forceStopMovement), ending any walk here too.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<Point>

Types

Point · ActOptions

`teleport`

methodplugins · game:act

TypeScript

teleport(to: Point, options?: ActOptions & { camera?: boolean | undefined; }) => Promise<Point>

Puts the player somewhere at once, as the client's own teleport does (teleportPlayer): one move flagged immediate, seen by everyone in the room. camera: false leaves the view where it was. Resolves once the player is drawn there.

Parameters

Name	Type
`to`	`Point`
`options` optional	`ActOptions & { camera?: boolean \| undefined; }`

Returns

Promise<Point>

Types

Point · ActOptions

`tour`

methodplugins · game:read

TypeScript

tour(points: readonly (Point | null)[]) => Promise<Tour>

Points put in the order that covers them with the least walking, from where the player stands.

Parameters

Name	Type
`points`	`readonly (Point \| null)[]`

Returns

Promise<Tour>

Types

Tour · Point

`walkThrough`

methodplugins · game:act

TypeScript

walkThrough(to: Point, options?: ActOptions & { pixelsPerSecond?: number | undefined; }) => Promise<Arrival>

Walks the player through walls in a straight line, a step every few frames (AvatarManager.movePlayer), and puts them on the point. The server keeps its own say over where a player may be. pixelsPerSecond is 300 by default.

Parameters

Name	Type
`to`	`Point`
`options` optional	`ActOptions & { pixelsPerSecond?: number \| undefined; }`

Returns

Promise<Arrival>

Types

Point · ActOptions · Arrival

`walkTo`

methodplugins · game:act

TypeScript

walkTo(to: Point, options?: WalkOptions) => Promise<Arrival>

Walks the player to a point by the room's grid, as hops the client walks one after another, and resolves once they are within within (40) pixels. Throws REFUSED when there is no way there on foot (after walking as near as it can), TIMEOUT when the walk stalls, and ABORTED when the signal ends it or another walk takes over.

Parameters

Name	Type
`to`	`Point`
`options` optional	`WalkOptions`

Returns

Promise<Arrival>

Types

WalkOptions · Motion · ActOptions · WalkTuning · Arrival · Point

Example

TypeScript

const { at } = await phantom.aj.navigation.walkTo({ x: 1200, y: 400 });

Run in Phantom

`walkToSpawn`

methodplugins · game:act

TypeScript

walkToSpawn(name: string, options?: ActOptions) => Promise<Arrival>

Walks the player to one of the room's spawn points by name (RoomManagerView.walkToSpawn), scattered within its radius as the client scatters arrivals, and resolves once they stop.

Parameters

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

Returns

Promise<Arrival>

Types

ActOptions · Arrival

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.

`Point`

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

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

`RoutePlan`

A plan, with no-grid for a room authored without one: the room saying nothing, not no.

TypeScript

type RoutePlan = Omit<Plan, 'verdict'> & {
  verdict: Plan['verdict'] | 'no-grid';
}

`Reach`

Whether somewhere can be walked to. no-grid and off-grid count: the room says nothing.

Field	Type
`reachable`	`boolean`
`verdict`	`"reachable" \| "walled-off" \| "off-grid" \| "no-grid"`
`point`	`Point \| null`
`distance`	`number \| null`
`gap`	`number \| null`

`Tour`

Several targets in the order that covers them with the least walking, by place in points.

Field	Type
`order`	`number[]`	Where to go, in order, as places in the points given.
`legs`	`number[]`	How far each step of that order is on foot, in pixels, the first from where the player stands.
`unreachable`	`number[]`	The places in `points` there is no way to at all, left out of `order`.
`length`	`number`	The whole round in pixels, which is `legs` added up.

`WalkOptions`

How a walk goes, and how long it may take: by default, as long as its length needs.

TypeScript

type WalkOptions = ActOptions & WalkTuning

`Motion`

Something moving, for working out where to meet it.

Field	Type
`at`	`Point`	Where it is now, in the avatar's coordinates.
`velocity`	`Point`	How fast it is going along each axis, in pixels a second; zero for something standing still.

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

`WalkTuning`

How a walk goes.

Field	Type
`within` optional	`number \| undefined`	How close counts as there, in pixels: 40 by default.
`goal` optional	`(() => Promise<Point \| null>) \| undefined`	Where the goal is now, asked again as the walk goes, for a goal that moves.
`motion` optional	`(() => Promise<Motion \| null>) \| undefined`	Where the goal is and how fast it goes, to walk to where it will be rather than where it was.
`pace` optional	`number \| undefined`	How fast the player walks, for `motion`: `PLAYER_PACE` by default.

`Arrival`

The player's walk ended where it was going.

Field	Type
`at`	`Point`	Where the player stands, in room coordinates.
`gap`	`number`	How far that is from the goal, in pixels.

`Steering`

Arrow keys and buttons held down, as the room hears them (RoomManagerView).

Field	Type
`left` optional	`boolean \| undefined`
`right` optional	`boolean \| undefined`
`up` optional	`boolean \| undefined`
`down` optional	`boolean \| undefined`
`ctrl` optional	`boolean \| undefined`	Ctrl held: the client's run.

Getting about ​

Overview ​

Methods ​

cellAt ​

distances ​

grid ​

nearestOpen ​

plan ​

position ​

reach ​

respawn ​

steer ​

stop ​

teleport ​

tour ​

walkThrough ​

walkTo ​

walkToSpawn ​

Types ​

Point ​

RoutePlan ​

Reach ​

Tour ​

WalkOptions ​

Motion ​

ActOptions ​

WalkTuning ​

Arrival ​

Steering ​

Getting about

Overview

Methods

`cellAt`

`distances`

`grid`

`nearestOpen`

`plan`

`position`

`reach`

`respawn`

`steer`

`stop`

`teleport`

`tour`

`walkThrough`

`walkTo`

`walkToSpawn`

Types

`Point`

`RoutePlan`

`Reach`

`Tour`

`WalkOptions`

`Motion`

`ActOptions`

`WalkTuning`

`Arrival`

`Steering`