Rooms

phantom.aj.roomWhere you are

The room the player is in: its players, camera, scene, volumes, music and items.

Scripts and plugins

A script has all of it, as phantom.aj.room, 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
current()	The room the player is in, read from the client, or null before the first join.	game:read
isLoaded()	Whether a room is built and on screen.	game:read
join()	Joins a room by name, through the client's own join (RoomXtCommManager.sendRoomJoinRequest), and resolves with the room once the server has put the player in it.	game:act
leaveGame()	Leaves the in-room game the player is in (RoomXtCommManager.sendRoomLeaveRequest), which is the only room left without joining another.	game:act
loaded()	Waits for a room to be built and on screen, and resolves with it: at once when one already is.	game:read
sceneToRoom()	A point in the scene's own coordinates (as scene.spawns() and scene.portals() give them) moved into the room's, which is what walking takes (convertToWorldSpace, on a copy).	game:read
setArrival()	Says where the next room puts the player as they arrive: a spawn point by name (setGotoSpawnPoint), or a point (setGotoSpawnLocation).	game:act
toScreen()	Where a point of the room is drawn on screen (convertWorldToScreen), or null with no room.	game:read
toWorld()	Where a point on screen stands in the room (convertScreenToWorldSpace), or null with no room.	game:read
onJoin()	Hears each room the player joins, as the server's join answer describes it.	game:read
onJoinFailed()	Hears each join the server refuses.	game:read
onLeave()	Hears the client take the room down (RoomManagerWorld.exitRoom), before the next loads.	game:read
onLoaded()	Hears the client finish building each room (RoomManagerWorld.sceneAssetsLoaded): the moment its spawns, portals, volumes, grid and layers stop being empty, which onJoin is too early for.	game:read

room.players: Who is in the room.

Member	What it does	Plugins
all()	Everyone drawn in the room, the player too.	game:read
byAvatarName()	One player by the name of the animal they are out as, or null.	game:read
byUserName()	One player by account name, in any case, or null.	game:read
count()	How many are drawn in the room, the player too.	game:read
follow()	Follows one player's position in the game, told when it changes: read every everyFrames frames (6, four times a second, by default), and set up again after a reload.	game:read
get()	One player by user id, or null when they are not drawn here.	game:read
onChange()	Hears who is in the room change, with everyone drawn now: once at the start, and each time the client draws someone or takes someone away (createAvatar, removeAvatar).	game:read
onEnter()	Hears someone appear in the room, the player included, as the server announces them.	game:read
onLeave()	Hears someone leave the room (avatar.left).	game:read
onMove()	Hears others walk (avatar.moved) and the player's own moves as the client sends them.	game:read

room.camera: Where the room is seen from.

Member	What it does	Plugins
current()	The camera now, or null with no room.	game:read
focus()	Points the camera at a place in the room as the game does for a cut scene: it travels there, stays, and comes back by itself (setCameraFocus, which stops the player's walk too).	game:act
hold()	Holds the camera where it is, so the player can walk out of view (setRoomMode to its stay, with a stay that never runs out).	game:act
scrollTo()	Scrolls the room to an offset (_scrollOffset, then updateBackground).	game:act
setBounds()	How far the camera may scroll (_stageMin and _stageMax), until the next room sets its own.	game:act
zoom()	Zooms the room, in per cent of its normal size (updateRoomZoom).	game:act
onChange()	Hears the camera move, read in the game every everyFrames frames (3 by default, about eight times a second) and told only when something changed: what an overlay following the room's scroll needs.	game:read

room.scene: What the room was built from: spawns, portals, layers, art, the minimap.

Member	What it does	Plugins
actionPoints()	The room's action points (_actionPoints).	game:read
art()	Every piece of the scene's art (_layers).	game:read
blockActionPoints()	Empties the room's action points (_actionPoints) the same way: shops and totems go quiet.	game:act
blockPortals()	Empties the room's list of ways out (_portals), so walking into one goes nowhere, until the function it gives back puts the scene's own list back.	game:act
bounds()	How far the room reaches (_stageMin, _stageMax), or null with no room.	game:read
darkAreas()	The shapes a dark room is masked with; none in a room that is not dark.	game:read
fadeLayer()	Keeps one of the room's display layers at an opacity, 0 to 1, until it is stopped.	game:act
hideArt()	Hides every piece of the scene's art by that name, kept hidden while the room is the one it was hidden in, until the function it gives back is called.	game:act
hideLayer()	Hides one of the room's display layers until the function it gives back is called.	game:act
hidePlayers()	Takes every player off the screen, balloons and emotes too, leaving the room's own art: the three layers players are drawn in, hidden until the function it gives back is called.	game:act
layers()	Every display layer the client draws the room in, in order, back to front.	game:read
lines()	The scene's collision outline (_lines), which only side-scrolling rooms have.	game:read
minimap()	The room's minimap, or null for a room without one.	game:read
objectAt()	What a click at a point of the screen would land on, or null for nothing.	game:read
paths()	The scene's named paths (_paths), with their points.	game:read
portals()	The room's ways out (_portals).	game:read
redirectPortal()	Sends the room's portals to target somewhere else instead, until the room is loaded again.	game:act
spawns()	The room's spawn points (_spawns).	game:read

room.volumes: The room's volumes: the shapes it reacts to an animal being in.

Member	What it does	Plugins
all()	Every volume of the room, as the scene wrote it and as the client holds it.	game:read
at()	The volumes a point of the scene is inside, by their polygons.	game:read
block()	Stops the room minding one kind of volume until the function it gives back puts them back: splash (no splashes), socialTriggers (art that fills as animals gather) or bounce (the room's bouncing area).	game:act
contains()	Whether a point of the room is inside one volume, by the client's own test (testAvatarVolume).	game:read
enable()	Turns a volume on or off as an adventure does (RoomManagerBase.enableVolume), walls and all: the grid forgets or stamps back the volume's block.	game:act
objects()	The little animations the room's volumes drive (VolumeManager._roomObjs).	game:read
tests()	What each of the client's own tests says about a point of the room, in one message.	game:read

room.music: The room's music and sounds.

Member	What it does	Plugins
current()	The track the room is playing (_roomMusic), or null before the client played any.	game:read
play()	Plays another track as the room's music (RoomManagerWorld.playMusic), as a den's music item does, until the function it gives back puts the one before it back (playPreviousMusic).	game:act
onChange()	Hears the room's music change, whoever changed it.	game:read
onSound()	Hears the sounds the room sets off: its events and the named effects it plays.	game:read

room.worldItems: The gift objects placed around Jamaa.

Member	What it does	Plugins
all()	The world items the room has now (WorldItemsManager._usableWorldItems), with whether each is taken.	game:read
get()	One world item by def id (getWorldItemDef), or null before the defs have loaded.	game:read
take()	Takes a world item's gift (WorldItemsXtCommManager.sendAcceptGift), as clicking it and keeping what it offers does.	game:act
onTaken()	Hears every world item gift the server gives, whoever took it.	game:read

Methods

current

methodplugins · game:read

current() => Promise<Room | null>

The room the player is in, read from the client, or null before the first join.

Returns

Promise<Room \| null>

Types

Room · RoomJoined

isLoaded

methodplugins · game:read

isLoaded() => Promise<boolean>

Whether a room is built and on screen.

Returns

Promise<boolean>

join

methodplugins · game:act

join(name: string, options?: JoinOptions) => Promise<RoomJoined>

Joins a room by name, through the client's own join (RoomXtCommManager.sendRoomJoinRequest), and resolves with the room once the server has put the player in it. A den's name goes the way the client sends dens. It throws REFUSED with the server's code when the server says no, and when the client already has a join in flight, which it would otherwise drop without a word. A room on another server node is followed there, as the client does, so give such a join a longer timeoutMs. The room's art loads afterwards: loaded() waits for it.

Parameters

Name	Type
name	string
options optional	JoinOptions

Returns

Promise<RoomJoined>

Types

JoinOptions · ActOptions · RoomJoined

Example

const room = await phantom.aj.room.join('jamaa_township.room_main');

Run in Phantom

leaveGame

methodplugins · game:act

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

Leaves the in-room game the player is in (RoomXtCommManager.sendRoomLeaveRequest), which is the only room left without joining another. NOT_READY when the player is in none.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

loaded

methodplugins · game:read

loaded(options?: ActOptions) => Promise<Room>

Waits for a room to be built and on screen, and resolves with it: at once when one already is. TIMEOUT after 30 seconds by default.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<Room>

Types

Room · ActOptions

sceneToRoom

methodplugins · game:read

sceneToRoom(point: Point) => Promise<Point | null>

A point in the scene's own coordinates (as scene.spawns() and scene.portals() give them) moved into the room's, which is what walking takes (convertToWorldSpace, on a copy).

Parameters

Name	Type
point	Point

Returns

Promise<Point \| null>

Types

Point

setArrival

methodplugins · game:act

setArrival(at: string | Point, options?: ActOptions) => Promise<string | Point>

Says where the next room puts the player as they arrive: a spawn point by name (setGotoSpawnPoint), or a point (setGotoSpawnLocation). The client keeps it until the next room is built. Resolves with what the client now holds.

Parameters

Name	Type
at	string | Point
options optional	ActOptions

Returns

Promise<string \| Point>

Types

ActOptions · Point

toScreen

methodplugins · game:read

toScreen(point: Point) => Promise<Point | null>

Where a point of the room is drawn on screen (convertWorldToScreen), or null with no room. The client rounds to whole pixels.

Parameters

Name	Type
point	Point

Returns

Promise<Point \| null>

Types

Point

toWorld

methodplugins · game:read

toWorld(point: Point) => Promise<Point | null>

Where a point on screen stands in the room (convertScreenToWorldSpace), or null with no room.

Parameters

Name	Type
point	Point

Returns

Promise<Point \| null>

Types

Point

Events

onJoin

eventplugins · game:read

onJoin(listener: (room: RoomJoined) => void) => () => void

Hears each room the player joins, as the server's join answer describes it.

Parameters

Name	Type
listener	(room: RoomJoined) => void

Returns

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

Types

RoomJoined

onJoinFailed

eventplugins · game:read

onJoinFailed(listener: (failure: RoomJoinFailure) => void) => () => void

Hears each join the server refuses.

Parameters

Name	Type
listener	(failure: RoomJoinFailure) => void

Returns

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

Types

RoomJoinFailure

onLeave

eventplugins · game:read

onLeave(listener: (left: RoomLeft) => void) => () => void

Hears the client take the room down (RoomManagerWorld.exitRoom), before the next loads.

Parameters

Name	Type
listener	(left: RoomLeft) => void

Returns

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

Types

RoomLeft

onLoaded

eventplugins · game:read

onLoaded(listener: (room: RoomLoaded) => void) => () => void

Hears the client finish building each room (RoomManagerWorld.sceneAssetsLoaded): the moment its spawns, portals, volumes, grid and layers stop being empty, which onJoin is too early for.

Parameters

Name	Type
listener	(room: RoomLoaded) => void

Returns

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

Types

RoomLoaded

room.players

Who is in the room.

all

methodplugins · game:read

all() => Promise<RoomPlayer[]>

Everyone drawn in the room, the player too.

Returns

Promise<RoomPlayer[]>

Types

RoomPlayer

byAvatarName

methodplugins · game:read

byAvatarName(avatarName: string) => Promise<RoomPlayer | null>

One player by the name of the animal they are out as, or null.

Parameters

Name	Type
avatarName	string

Returns

Promise<RoomPlayer \| null>

Types

RoomPlayer

byUserName

methodplugins · game:read

byUserName(userName: string) => Promise<RoomPlayer | null>

One player by account name, in any case, or null.

Parameters

Name	Type
userName	string

Returns

Promise<RoomPlayer \| null>

Types

RoomPlayer

count

methodplugins · game:read

count() => Promise<number>

How many are drawn in the room, the player too.

Returns

Promise<number>

follow

methodplugins · game:read

follow(userId: number, listener: (position: RoomPlayerPosition) => void, options?: { everyFrames?: number | undefined; }) => () => void

Follows one player's position in the game, told when it changes: read every everyFrames frames (6, four times a second, by default), and set up again after a reload. Stops when the function it gives back is called.

Parameters

Name	Type
userId	number
listener	(position: RoomPlayerPosition) => void
options optional	{ everyFrames?: number | undefined; }

Returns

() => void

Types

RoomPlayerPosition

get

methodplugins · game:read

get(userId: number) => Promise<RoomPlayer | null>

One player by user id, or null when they are not drawn here.

Parameters

Name	Type
userId	number

Returns

Promise<RoomPlayer \| null>

Types

RoomPlayer

onChange

eventplugins · game:read

onChange(listener: (players: RoomPlayer[]) => void) => () => void

Hears who is in the room change, with everyone drawn now: once at the start, and each time the client draws someone or takes someone away (createAvatar, removeAvatar).

Parameters

Name	Type
listener	(players: RoomPlayer[]) => void

Returns

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

Types

RoomPlayer

onEnter

eventplugins · game:read

onEnter(listener: (player: RoomPlayerArrival) => void) => () => void

Hears someone appear in the room, the player included, as the server announces them.

Parameters

Name	Type
listener	(player: RoomPlayerArrival) => void

Returns

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

Types

RoomPlayerArrival

onLeave

eventplugins · game:read

onLeave(listener: (departure: RoomPlayerDeparture) => void) => () => void

Hears someone leave the room (avatar.left). See RoomPlayerDeparture for the names.

Parameters

Name	Type
listener	(departure: RoomPlayerDeparture) => void

Returns

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

Types

RoomPlayerDeparture

onMove

eventplugins · game:read

onMove(listener: (move: RoomPlayerMove) => void) => () => void

Hears others walk (avatar.moved) and the player's own moves as the client sends them.

Parameters

Name	Type
listener	(move: RoomPlayerMove) => void

Returns

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

Types

RoomPlayerMove

room.camera

Where the room is seen from.

current

methodplugins · game:read

current() => Promise<RoomCamera | null>

The camera now, or null with no room.

Returns

Promise<RoomCamera \| null>

Types

RoomCamera

focus

methodplugins · game:act

focus(at: Point, options?: FocusOptions) => Promise<RoomCamera>

Points the camera at a place in the room as the game does for a cut scene: it travels there, stays, and comes back by itself (setCameraFocus, which stops the player's walk too). Resolves once it is back, with the camera as it then is.

Parameters

Name	Type
at	Point
options optional	FocusOptions

Returns

Promise<RoomCamera>

Types

FocusOptions · Point · RoomCamera

Example

await phantom.aj.room.camera.focus({ x: 600, y: 400 }, { travel: 1, stay: 2, back: 1 });

Run in Phantom

hold

methodplugins · game:act

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

Holds the camera where it is, so the player can walk out of view (setRoomMode to its stay, with a stay that never runs out). Calling what it gives back lets it follow the player again.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<() => Promise<void>>

Types

ActOptions

scrollTo

methodplugins · game:act

scrollTo(offset: Point, options?: ActOptions) => Promise<RoomCamera>

Scrolls the room to an offset (_scrollOffset, then updateBackground). In player mode the client scrolls back after the player on the next frame, so hold the camera first.

Parameters

Name	Type
offset	Point
options optional	ActOptions

Returns

Promise<RoomCamera>

Types

ActOptions · Point · RoomCamera

setBounds

methodplugins · game:act

setBounds(bounds: { min?: Point | undefined; max?: Point | undefined; }, options?: ActOptions) => Promise<RoomCamera>

How far the camera may scroll (_stageMin and _stageMax), until the next room sets its own. Leave out a corner to keep it.

Parameters

Name	Type
bounds	{ min?: Point | undefined; max?: Point | undefined; }
options optional	ActOptions

Returns

Promise<RoomCamera>

Types

ActOptions · Point · RoomCamera

zoom

methodplugins · game:act

zoom(percent: number, options?: ActOptions) => Promise<RoomCamera>

Zooms the room, in per cent of its normal size (updateRoomZoom). The client will not zoom out past the room's own edges, and keeps what it took: the camera answered has the zoom set.

Parameters

Name	Type
percent	number
options optional	ActOptions

Returns

Promise<RoomCamera>

Types

ActOptions · RoomCamera

onChange

eventplugins · game:read

onChange(listener: (camera: RoomCamera) => void, options?: { everyFrames?: number | undefined; }) => () => void

Hears the camera move, read in the game every everyFrames frames (3 by default, about eight times a second) and told only when something changed: what an overlay following the room's scroll needs.

Parameters

Name	Type
listener	(camera: RoomCamera) => void
options optional	{ everyFrames?: number | undefined; }

Returns

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

Types

RoomCamera

room.scene

What the room was built from: spawns, portals, layers, art, the minimap.

actionPoints

methodplugins · game:read

actionPoints() => Promise<RoomActionPoint[]>

The room's action points (_actionPoints).

Returns

Promise<RoomActionPoint[]>

Types

RoomActionPoint

art

methodplugins · game:read

art() => Promise<RoomArt[]>

Every piece of the scene's art (_layers).

Returns

Promise<RoomArt[]>

Types

RoomArt

blockActionPoints

methodplugins · game:act

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

Empties the room's action points (_actionPoints) the same way: shops and totems go quiet.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<() => Promise<void>>

Types

ActOptions

blockPortals

methodplugins · game:act

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

Empties the room's list of ways out (_portals), so walking into one goes nowhere, until the function it gives back puts the scene's own list back. The next room has its own.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<() => Promise<void>>

Types

ActOptions

bounds

methodplugins · game:read

bounds() => Promise<RoomBounds | null>

How far the room reaches (_stageMin, _stageMax), or null with no room.

Returns

Promise<RoomBounds \| null>

Types

RoomBounds

darkAreas

methodplugins · game:read

darkAreas() => Promise<RoomDarkArea[]>

The shapes a dark room is masked with; none in a room that is not dark.

Returns

Promise<RoomDarkArea[]>

Types

RoomDarkArea

fadeLayer

methodplugins · game:act

fadeLayer(name: RoomLayerName, alpha: number, options?: ActOptions) => Promise<() => Promise<void>>

Keeps one of the room's display layers at an opacity, 0 to 1, until it is stopped.

Parameters

Name	Type
name	RoomLayerName
alpha	number
options optional	ActOptions

Returns

Promise<() => Promise<void>>

Types

ActOptions · RoomLayerName

hideArt

methodplugins · game:act

hideArt(name: string, options?: ActOptions) => Promise<() => Promise<void>>

Hides every piece of the scene's art by that name, kept hidden while the room is the one it was hidden in, until the function it gives back is called. NOT_READY when there is none.

Parameters

Name	Type
name	string
options optional	ActOptions

Returns

Promise<() => Promise<void>>

Types

ActOptions

hideLayer

methodplugins · game:act

hideLayer(name: RoomLayerName, options?: ActOptions) => Promise<() => Promise<void>>

Hides one of the room's display layers until the function it gives back is called.

Parameters

Name	Type
name	RoomLayerName
options optional	ActOptions

Returns

Promise<() => Promise<void>>

Types

ActOptions · RoomLayerName

hidePlayers

methodplugins · game:act

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

Takes every player off the screen, balloons and emotes too, leaving the room's own art: the three layers players are drawn in, hidden until the function it gives back is called.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<() => Promise<void>>

Types

ActOptions

layers

methodplugins · game:read

layers() => Promise<RoomLayer[]>

Every display layer the client draws the room in, in order, back to front.

Returns

Promise<RoomLayer[]>

Types

RoomLayer · RoomLayerName

lines

methodplugins · game:read

lines() => Promise<RoomLine[]>

The scene's collision outline (_lines), which only side-scrolling rooms have.

Returns

Promise<RoomLine[]>

Types

RoomLine

minimap

methodplugins · game:read

minimap() => Promise<RoomMinimap | null>

The room's minimap, or null for a room without one.

Returns

Promise<RoomMinimap \| null>

Types

RoomMinimap

objectAt

methodplugins · game:read

objectAt(point: Point, options?: { journeyBookOnly?: boolean | undefined; }) => Promise<RoomObjectAt | null>

What a click at a point of the screen would land on, or null for nothing.

Parameters

Name	Type
point	Point
options optional	{ journeyBookOnly?: boolean | undefined; }

Returns

Promise<RoomObjectAt \| null>

Types

RoomObjectAt · Point

paths

methodplugins · game:read

paths() => Promise<RoomPath[]>

The scene's named paths (_paths), with their points.

Returns

Promise<RoomPath[]>

Types

RoomPath

portals

methodplugins · game:read

portals() => Promise<RoomPortal[]>

The room's ways out (_portals).

Returns

Promise<RoomPortal[]>

Types

RoomPortal

redirectPortal

methodplugins · game:act

redirectPortal(target: string, to: string, options?: ActOptions & { spawn?: string | undefined; }) => Promise<RoomPortal[]>

Sends the room's portals to target somewhere else instead, until the room is loaded again. Resolves with the portals as they now are; NOT_READY when none leads there.

Parameters

Name	Type
target	string
to	string
options optional	ActOptions & { spawn?: string | undefined; }

Returns

Promise<RoomPortal[]>

Types

ActOptions · RoomPortal

spawns

methodplugins · game:read

spawns() => Promise<RoomSpawn[]>

The room's spawn points (_spawns).

Returns

Promise<RoomSpawn[]>

Types

RoomSpawn

room.volumes

The room's volumes: the shapes it reacts to an animal being in.

all

methodplugins · game:read

all() => Promise<RoomVolume[]>

Every volume of the room, as the scene wrote it and as the client holds it.

Returns

Promise<RoomVolume[]>

Types

RoomVolume · RoomVolumeKind

at

methodplugins · game:read

at(point: Point) => Promise<RoomVolume[]>

The volumes a point of the scene is inside, by their polygons.

Parameters

Name	Type
point	Point

Returns

Promise<RoomVolume[]>

Types

Point · RoomVolume

block

methodplugins · game:act

block(kind: "splash" | "socialTriggers" | "bounce", options?: ActOptions) => Promise<() => Promise<void>>

Stops the room minding one kind of volume until the function it gives back puts them back: splash (no splashes), socialTriggers (art that fills as animals gather) or bounce (the room's bouncing area). The client only acts on each while its list has something in it.

Parameters

Name	Type
kind	"splash" | "socialTriggers" | "bounce"
options optional	ActOptions

Returns

Promise<() => Promise<void>>

Types

ActOptions

contains

methodplugins · game:read

contains(name: string, point: Point) => Promise<boolean>

Whether a point of the room is inside one volume, by the client's own test (testAvatarVolume).

Parameters

Name	Type
name	string
point	Point

Returns

Promise<boolean>

Types

Point

enable

methodplugins · game:act

enable(name: string, enabled: boolean, options?: ActOptions) => Promise<RoomVolume>

Turns a volume on or off as an adventure does (RoomManagerBase.enableVolume), walls and all: the grid forgets or stamps back the volume's block. Resolves with the volume as it now is; NOT_READY for a name the room has not got.

Parameters

Name	Type
name	string
enabled	boolean
options optional	ActOptions

Returns

Promise<RoomVolume>

Types

ActOptions · RoomVolume

objects

methodplugins · game:read

objects() => Promise<RoomObject[]>

The little animations the room's volumes drive (VolumeManager._roomObjs).

Returns

Promise<RoomObject[]>

Types

RoomObject

tests

methodplugins · game:read

tests(point: Point) => Promise<RoomVolumeTests>

What each of the client's own tests says about a point of the room, in one message.

Parameters

Name	Type
point	Point

Returns

Promise<RoomVolumeTests>

Types

RoomVolumeTests · Point

room.music

The room's music and sounds.

current

methodplugins · game:read

current() => Promise<RoomMusic | null>

The track the room is playing (_roomMusic), or null before the client played any.

Returns

Promise<RoomMusic \| null>

Types

RoomMusic

play

methodplugins · game:act

play(file: string, options?: ActOptions & { volume?: number | undefined; }) => Promise<() => Promise<void>>

Plays another track as the room's music (RoomManagerWorld.playMusic), as a den's music item does, until the function it gives back puts the one before it back (playPreviousMusic). The next room starts its own. volume is 0 to 1, 0.5 by default.

Parameters

Name	Type
file	string
options optional	ActOptions & { volume?: number | undefined; }

Returns

Promise<() => Promise<void>>

Types

ActOptions

onChange

eventplugins · game:read

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

Hears the room's music change, whoever changed it.

Parameters

Name	Type
listener	(change: RoomMusicChange) => void

Returns

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

Types

RoomMusicChange

onSound

eventplugins · game:read

onSound(listener: (sound: RoomSound) => void) => () => void

Hears the sounds the room sets off: its events and the named effects it plays.

Parameters

Name	Type
listener	(sound: RoomSound) => void

Returns

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

Types

RoomSound

room.worldItems

The gift objects placed around Jamaa.

all

methodplugins · game:read

all() => Promise<WorldItem[]>

The world items the room has now (WorldItemsManager._usableWorldItems), with whether each is taken.

Returns

Promise<WorldItem[]>

Types

WorldItem · WorldItemGift

get

methodplugins · game:read

get(defId: number) => Promise<WorldItem | null>

One world item by def id (getWorldItemDef), or null before the defs have loaded.

Parameters

Name	Type
defId	number

Returns

Promise<WorldItem \| null>

Types

WorldItem

take

methodplugins · game:act

take(defId: number, options?: ActOptions & { version?: number | undefined; colorIndex?: number | undefined; }) => Promise<WorldItemTaken>

Takes a world item's gift (WorldItemsXtCommManager.sendAcceptGift), as clicking it and keeping what it offers does. A gift is taken once, ever. REFUSED when the server will not give it, which is what one already taken answers. version (a den item's) and colorIndex (a clothing item's) are 0 when left out, as for gems and diamonds.

Parameters

Name	Type
defId	number
options optional	ActOptions & { version?: number | undefined; colorIndex?: number | undefined; }

Returns

Promise<WorldItemTaken>

Types

WorldItemTaken · ActOptions

onTaken

eventplugins · game:read

onTaken(listener: (taken: WorldItemTaken) => void) => () => void

Hears every world item gift the server gives, whoever took it. The answer names no item, so the item is the request this listener heard go out before it, matched in order as the client matches its one callback: requests it did not hear give defId null.

Parameters

Name	Type
listener	(taken: WorldItemTaken) => void

Returns

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

Types

WorldItemTaken

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.

Room

The room the player is in, as the client holds it now.

type Room = RoomJoined & {
  /** The room's asset path, which `join` takes: `jamaa_township.room_main`. Null before it loads. */
  path: string | null;
  /** The room's definition (`_roomDefID`), as `phantom.aj.world.roomDefinitions()` lists them. */
  defId: number | null;
  /** `clientInfo.roomType`: 2 a den, 5 a party, 7 an adventure, and the rest the game's own. */
  type: number | null;
  /** What kind of place it is (`_roomEnviroType`): 0 land, and the flags `Utility.isAir` reads. */
  environment: number | null;
  /** A den being previewed (the den shop), rather than lived in. */
  preview: boolean;
  /** For a den: whose it is, and whether it is the player's own. */
  den: { owner: string | null; mine: boolean } | null;
  /** The in-room game's room the player is also in, by name, or null. */
  subRoom: string | null;
  /** Whether the room's art is in and on screen (`layerManager.bkg.visible`). */
  loaded: boolean;
}

Run in Phantom

RoomJoined

A room as the server's join answer describes it.

Field	Type
name	string	Its full name, with the copy of it the player is in after #: jamaa_township.room_main#12.
id	number	Its id on the server, the room every later message is sent in.
maxUsers	number	How many players it holds.
isPrivate	boolean
isGame	boolean	An in-room game's room, or one of the game rooms the client treats as such.
isLimbo	boolean	A SmartFox limbo room, whose users are not sent to each other.
isTemp	boolean	Made when needed and removed once empty.
isSubRoom	boolean	A room inside the room: an in-room game.
displayName	string | null	The name the HUD shows. For a player's party (pparty…) the server sends three localization ids joined with |, which the client translates; current() reads the translated one.
shard	number | null	The shard (RoomManagerWorld.shardId), when the server said.

JoinOptions

type JoinOptions = ActOptions & {
  /** Join without being seen, as moderators do (`forceInvisMode`). */
  invisible?: boolean;
}

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

RoomJoinFailure

A join the server refused.

Field	Type
error	string | null	The server's code: BSJ, SSJ, CSJ, QSJL, RQJF and the like, or its words.
node	string | null	For N: the server node the room is on, which the client switches to by itself.
extra	string[]

RoomLoaded

The room the client has just finished building.

Field	Type
defId	number | null
path	string | null
environment	number | null
preview	boolean	A den being previewed builds the same way.

RoomLeft

The room the client is taking down.

Field	Type
path	string | null
forPreview	boolean	It is only being put aside to preview a den, and comes back after.

Point

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

Field	Type
x	number
y	number

RoomPlayer

Someone in the room, as the client draws them.

Field	Type
userId	number	Their id in the room's server (sfsUserId), which the room's packets name them by.
userName	string
avatarName	string | null	The name of the animal they are out as.
uuid	string | null
perUserAvId	number | null	Which of their animals it is.
x	number	Where they are drawn, in room coordinates.
y	number
facing	"left" | "right"
moving	boolean	In the middle of a walk or a slide.
me	boolean	Whether this is the player themselves.

RoomPlayerArrival

Someone appearing in the room, as the server announces them (avatar.joined).

Field	Type
userId	number
userName	string
avatarName	string
uuid	string
perUserAvId	number
x	number
y	number

RoomPlayerDeparture

Someone leaving the room.

Field	Type
userId	number
userName	string | null	Their names, as this area saw them arrive; null for someone it never saw.
avatarName	string | null
walkingTo	Point | null	Where they walk to before the client takes them away, when they walk out.

RoomPlayerMove

Someone walking or being placed: the path the server sent, or the player's own.

Field	Type
userId	number
path	Point[]
to	Point	Where the walk ends.
me	boolean

RoomPlayerPosition

Where someone is, as follow reads it.

Field	Type
userId	number
x	number
y	number
moving	boolean

RoomCamera

Where the camera is looking, and what it is doing.

Field	Type
offset	Point	How far the room has scrolled (_scrollOffset), which moves opposite to the view.
zoom	number | null	The zoom the client last set, in per cent (_zoom).
mode	"back" | "den" | "player" | "travel" | "stay" | null	player follows the player; den is a den being laid out; travel, stay and back are a camera move of the client's own, out to a point, held there, and back (setRoomMode).
held	boolean	Sitting still rather than following the player: the middle of a camera move.

FocusOptions

A camera move: the client's own cut-scene camera (setCameraFocus). Times are in seconds.

type FocusOptions = ActOptions & {
  /** How long it travels there: 1 by default. */
  travel?: number;
  /** How long it stays: 2 by default. */
  stay?: number;
  /** How long it travels back: 1 by default. */
  back?: number;
  /** Centre the point on screen, rather than putting the view's corner there: true by default. */
  centre?: boolean;
  /** Where it travels back to: where it was, by default. */
  returnTo?: Point;
}

RoomSpawn

One of the room's spawn points (ActorSpawn), in the scene's own coordinates.

type RoomSpawn = Point & {
  /** What a portal in another room asks for: `default` is the ordinary one. */
  name: string;
  /** How far round it arrivals are scattered (`getRandomRadiusOffset`). */
  radius: number;
  /** The spawn it walks arrivals on to, when it names one. */
  then: string | null;
}

RoomPortal

A way out of the room (ActorPortal), in the scene's own coordinates.

type RoomPortal = Point & {
  /** Its place in the room's list, which `redirectPortal` names. */
  index: number;
  /** How close the animal must come for the client to take it. */
  radius: number;
  /** `room` joins another room; `slide` is a slide inside this one. */
  kind: 'room' | 'slide';
  /** The room it joins, or the slide it starts. */
  target: string;
  /** The spawn it asks that room for. */
  spawn: string | null;
}

RoomActionPoint

One of the scene's action points (ActorAction): a shop, a totem, an adventure's respawn.

type RoomActionPoint = Point & {
  name: string;
  radius: number;
  /** 0 a minigame totem, 7 an adventure respawn, and the rest the client's own. */
  type: number;
  /** A minigame's type, an adventure's id. */
  typeDefId: number;
  message: string | null;
}

RoomLine

One line of the scene's collision outline (ActorCollisionPoint), for side-scrolling rooms.

Field	Type
from	Point
to	Point

RoomPath

One of the scene's named paths, which the client walks things along.

Field	Type
name	string
points	Point[]

RoomDarkArea

One of the shapes a dark room is masked with (getDarknessFromScene).

type RoomDarkArea = Point & { rotation: number; width: number; height: number }

RoomBounds

How far the room reaches, and how big a cell of its walk grid is.

Field	Type
min	Point
max	Point
cell	number

RoomLayer

One display layer, and what is in it.

Field	Type
name	RoomLayerName
visible	boolean
alpha	number
children	number

RoomLayerName

The display layers the client's LayerManager holds, by name.

type RoomLayerName = | 'bkg'
  | 'room_bkg'
  | 'room_bkg_group'
  | 'room_bkg_main'
  | 'room_avatars'
  | 'preview_room_avatar'
  | 'preview_room_flying_avatar'
  | 'room_fg'
  | 'room_super_fg'
  | 'flying_avatars'
  | 'room_chat'
  | 'room_orbs'
  | 'layer_worldGame'
  | 'gui'
  | 'fps'

RoomArt

One piece of the scene's art (ActorLayer, in _layers).

Field	Type
index	number
name	string
place	"unknown" | "background" | "among-players" | "foreground" | "top"	How deep it is drawn: under the players, among them, in front of them, or over everything.
layer	number
x	number
y	number
width	number
height	number
scaleX	number
scaleY	number
flipped	boolean
visible	boolean
alwaysLoaded	boolean	Never culled when off screen (excludeFromCull).

RoomMinimap

The room's minimap, as the client has drawn it.

Field	Type
shown	boolean
crop	{ x: number; y: number; width: number; height: number; }
scale	number
centre	Point
player	Point	Where the player's marker is on it.

RoomObjectAt

What a click at a point would land on (getObjUnderPoint).

Field	Type
name	string | null	The display object's instance name, or null when it has none.
className	string | null
isJourneyBookItem	boolean

RoomVolume

A shape the room reacts to an animal being in (ActorVolume): an emote spot, a shop's door, a splash, a gate an adventure opens. As the scene wrote it, joined with the record the client made of it (VolumeManager._volumeActors).

Field	Type
name	string
type	number	VOLUMETYPE_*'s number, and the word for it.
kind	RoomVolumeKind
typeDefId	number	A def id it carries, where its kind uses one (a pet shop's pet); 0 otherwise.
message	string | null
walkTo	boolean	The client walks the player to it first.
points	Point[]	Its corners, in the scene's own coordinates.
enabled	boolean | null	Whether the client still minds it (enableVolume); null where it made no record of it.
objects	number	How many pieces of art it drives (interactiveObjs).
animationIds	number[]	A social trigger's animation ids, split out of its message.

RoomVolumeKind

type RoomVolumeKind = keyof typeof VOLUME_TYPES | 'unknown'

RoomVolumeTests

What each of the client's own volume tests says about one point of the room.

Field	Type
avatar	string | null	The emote or walk-in volume there (testAvatarVolumes).
splash	string | null
ladder	string | null
plant	string | null	Where a seed may be planted.
stealth	string | null

RoomObject

One of the little animations a volume drives (room.RoomObject and its four kinds).

Field	Type
kind	"unknown" | "social" | "idle" | "random" | "gem" | "hold"
held	boolean
mouseOver	boolean
direction	number	1 playing forwards, -1 back, 0 at rest.
count	number | null	A social trigger's count of animals in its volume, and its stages.
stage	number | null
stages	number | null

RoomMusic

The track the room plays as its music.

Field	Type
file	string	Its file name, as audio/<file> on Animal Jam's content server.
volume	number | null	How loud, 0 to 1, after the player's own music volume.

RoomMusicChange

The room's music changing.

Field	Type
kind	"track" | "previous" | "original"	A track put on, the one before put back, or the room's own tried again.
file	string | null
volume	number | null

RoomSound

A sound the room set off (RoomManagerBase.onRoomEvent, playRoomEventSfx).

Field	Type
kind	string	The room event's kind, or play for a named sound effect.
detail	string | null	What it names: the event's second type, or the sound effect's name.
extra	string | null
persistent	boolean

WorldItem

One of the gift objects placed around Jamaa (Enums.WorldItemDef).

Field	Type
defId	number
position	number	Which spot in the room it sits at, counted from 1 as the room's list is.
gift	WorldItemGift
giftRefId	number	The den item's or clothing item's def; 0 for gems and diamonds.
amount	number	How many gems or diamonds.
description	string | null	The line its popup shows, in the player's language.
mediaRefId	number
popupType	number
available	boolean	Inside its availability window.
taken	boolean	Whether this account has taken it: a bit of a user var (hasReceivedGift). A gift is taken once, ever.

WorldItemGift

What a world item gives, by Enums.WorldItemDef's TYPE_ constants.

type WorldItemGift = 'denItem' | 'gems' | 'diamonds' | 'accessory' | 'unknown'

WorldItemTaken

A world item's gift, as the server answered it.

Field	Type
defId	number | null	The item, from the request this area heard go out; null where it heard none.
balance	number | null	The account's new gems or diamonds, for a currency gift.