Custom rooms

phantom.aj.customRoomsWhere you are

Building and playing custom rooms.

Scripts and plugins

A script has all of it, as phantom.aj.customRooms, 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
`character()`	A character of a room.	`game:read`
`characters()`	Every character of a room, as each stands now.	`game:read`
`current()`	The custom room the player is in, or null.	`game:read`
`define()`	Builds a room from its description and resolves with its id.	`game:act`
`enter()`	Takes the player into a room `define` built, resolving once they are in it.	`game:act`
`isAvailable()`	Whether this copy of the SDK can build rooms: plugins can, a script in the window cannot.	`game:read`
`leave()`	Brings the player back to the room they came from.	`game:act`
`limits()`	What a room's shared objects are held to, or null where the host does not say.	`game:read`
`object()`	A shared object of a room.	`game:read`
`objects()`	Every shared object of a room, as each stands now.	`game:read`
`open()`	`define`, once per description, then `enter`: a room opened from one place in a plugin.	`game:act`
`prop()`	A changeable prop of a room: the one the player is in, unless `roomId` says.	`game:read`
`remove()`	Forgets a room.	`game:act`
`shared()`	The shared rooms with people in them now, from any plugin in the Phantom store.	`game:act`
`onCharacterClick()`	Hears the player click one of the room's characters, with the line it said.	`game:read`
`onChat()`	Hears the player say something in one.	`game:read`
`onEnter()`	Hears the player enter a custom room.	`game:read`
`onLeave()`	Hears the player leave one, and why.	`game:read`
`onMove()`	Hears the player walk in one.	`game:read`
`onObject()`	Hears a room's shared objects change hands or move, as the server settled it.	`game:read`
`onPropClick()`	Hears the player click a `clickable` prop.	`game:read`
`onPropEnter()`	Hears the player step onto a prop's area.	`game:read`
`onPropLeave()`	Hears the player step off a prop's area.	`game:read`
`onPropNear()`	Hears the player come within a prop's `nearDistance`.	`game:read`

Methods

`character`

methodplugins · game:read

TypeScript

character(id: string, roomId?: string | undefined) => CustomRoomCharacterHandle

A character of a room.

Parameters

Name	Type
`id`	`string`
`roomId` optional	`string \| undefined`

Returns

CustomRoomCharacterHandle

Types

CustomRoomCharacterHandle · CustomRoomCharacterState · CustomRoomCharacterChange

`characters`

methodplugins · game:read

TypeScript

characters(roomId?: string | undefined) => Promise<CustomRoomCharacterState[]>

Every character of a room, as each stands now.

Parameters

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

Returns

Promise<CustomRoomCharacterState[]>

Types

CustomRoomCharacterState

`current`

methodplugins · game:read

TypeScript

current() => Promise<CustomRoomInfo | null>

The custom room the player is in, or null.

Returns

Promise<CustomRoomInfo \| null>

Types

CustomRoomInfo

`define`

methodplugins · game:act

TypeScript

define(spec: CustomRoomSpec, options?: ActOptions) => Promise<string>

Builds a room from its description and resolves with its id. The same room gives the same id.

Parameters

Name	Type
`spec`	`CustomRoomSpec`
`options` optional	`ActOptions`

Returns

Promise<string>

Types

CustomRoomSpec · CustomRoomPicture · CustomRoomArea · CustomRoomProp · CustomRoomMotion · CustomRoomFrames · CustomRoomExit · CustomRoomCharacter · CustomRoomCharacterLook · CustomRoomSpawn · CustomRoomDoorway · CustomRoomDestination · CustomRoomVolume · CustomRoomScroll · ActOptions

`enter`

methodplugins · game:act

TypeScript

enter(roomId: string, options?: ActOptions & CustomRoomEnterOptions) => Promise<CustomRoomInfo>

Takes the player into a room define built, resolving once they are in it.

Parameters

Name	Type
`roomId`	`string`
`options` optional	`ActOptions & CustomRoomEnterOptions`

Returns

Promise<CustomRoomInfo>

Types

CustomRoomEnterOptions · CustomRoomInfo · ActOptions

`isAvailable`

methodplugins · game:read

TypeScript

isAvailable() => Promise<boolean>

Whether this copy of the SDK can build rooms: plugins can, a script in the window cannot.

Returns

Promise<boolean>

`leave`

methodplugins · game:act

TypeScript

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

Brings the player back to the room they came from. NOT_READY when they are in no custom room.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`limits`

methodplugins · game:read

TypeScript

limits() => Promise<CustomRoomLimits | null>

What a room's shared objects are held to, or null where the host does not say.

Returns

Promise<CustomRoomLimits \| null>

Types

CustomRoomLimits

`object`

methodplugins · game:read

TypeScript

object(id: string, roomId?: string | undefined) => CustomRoomObjectHandle

A shared object of a room.

Parameters

Name	Type
`id`	`string`
`roomId` optional	`string \| undefined`

Returns

CustomRoomObjectHandle

Types

CustomRoomObjectHandle · CustomRoomObjectChange · CustomRoomObjectState · CustomRoomObjectTurn

`objects`

methodplugins · game:read

TypeScript

objects(roomId?: string | undefined) => Promise<CustomRoomObjectState[]>

Every shared object of a room, as each stands now.

Parameters

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

Returns

Promise<CustomRoomObjectState[]>

Types

CustomRoomObjectState

`open`

methodplugins · game:act

TypeScript

open(spec: CustomRoomSpec, options?: ActOptions & CustomRoomEnterOptions) => Promise<CustomRoomInfo>

define, once per description, then enter: a room opened from one place in a plugin.

Parameters

Name	Type
`spec`	`CustomRoomSpec`
`options` optional	`ActOptions & CustomRoomEnterOptions`

Returns

Promise<CustomRoomInfo>

Types

CustomRoomInfo · CustomRoomSpec · ActOptions · CustomRoomEnterOptions

`prop`

methodplugins · game:read

TypeScript

prop(id: string, roomId?: string | undefined) => CustomRoomPropHandle

A changeable prop of a room: the one the player is in, unless roomId says.

Parameters

Name	Type
`id`	`string`
`roomId` optional	`string \| undefined`

Returns

CustomRoomPropHandle

Types

CustomRoomPropHandle · CustomRoomPropState · CustomRoomPropChange

`remove`

methodplugins · game:act

TypeScript

remove(roomId: string, options?: ActOptions) => Promise<void>

Forgets a room. NOT_READY for one that is not defined.

Parameters

Name	Type
`roomId`	`string`
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`shared`

methodplugins · game:act

TypeScript

shared(options?: ActOptions) => Promise<SharedRoomListing[]>

The shared rooms with people in them now, from any plugin in the Phantom store.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<SharedRoomListing[]>

Types

SharedRoomListing · ActOptions

Events

`onCharacterClick`

eventplugins · game:read

TypeScript

onCharacterClick(listener: (event: { room: CustomRoomInfo; character: string; said: string | null; }) => void) => () => void

Hears the player click one of the room's characters, with the line it said.

Parameters

Name	Type
`listener`	`(event: { room: CustomRoomInfo; character: string; said: string \| null; }) => void`

Returns

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

Types

CustomRoomInfo

`onChat`

eventplugins · game:read

TypeScript

onChat(listener: (event: { room: CustomRoomInfo; text: string; kind: number; }) => void) => () => void

Hears the player say something in one.

Parameters

Name	Type
`listener`	`(event: { room: CustomRoomInfo; text: string; kind: number; }) => void`

Returns

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

Types

CustomRoomInfo

`onEnter`

eventplugins · game:read

TypeScript

onEnter(listener: (room: CustomRoomInfo) => void) => () => void

Hears the player enter a custom room.

Parameters

Name	Type
`listener`	`(room: CustomRoomInfo) => void`

Returns

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

Types

CustomRoomInfo

`onLeave`

eventplugins · game:read

TypeScript

onLeave(listener: (event: { room: CustomRoomInfo; reason: CustomRoomLeaveReason; }) => void) => () => void

Hears the player leave one, and why.

Parameters

Name	Type
`listener`	`(event: { room: CustomRoomInfo; reason: CustomRoomLeaveReason; }) => void`

Returns

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

Types

CustomRoomInfo

`onMove`

eventplugins · game:read

TypeScript

onMove(listener: (event: { room: CustomRoomInfo; x: number; y: number; }) => void) => () => void

Hears the player walk in one.

Parameters

Name	Type
`listener`	`(event: { room: CustomRoomInfo; x: number; y: number; }) => void`

Returns

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

Types

CustomRoomInfo

`onObject`

eventplugins · game:read

TypeScript

onObject(listener: (event: CustomRoomObjectEvent) => void) => () => void

Hears a room's shared objects change hands or move, as the server settled it.

Parameters

Name	Type
`listener`	`(event: CustomRoomObjectEvent) => void`

Returns

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

Types

CustomRoomObjectEvent

`onPropClick`

eventplugins · game:read

TypeScript

onPropClick(listener: (event: { room: CustomRoomInfo; prop: string; }) => void) => () => void

Hears the player click a clickable prop.

Parameters

Name	Type
`listener`	`(event: { room: CustomRoomInfo; prop: string; }) => void`

Returns

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

Types

CustomRoomInfo

`onPropEnter`

eventplugins · game:read

TypeScript

onPropEnter(listener: (event: { room: CustomRoomInfo; prop: string; }) => void) => () => void

Hears the player step onto a prop's area.

Parameters

Name	Type
`listener`	`(event: { room: CustomRoomInfo; prop: string; }) => void`

Returns

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

Types

CustomRoomInfo

`onPropLeave`

eventplugins · game:read

TypeScript

onPropLeave(listener: (event: { room: CustomRoomInfo; prop: string; }) => void) => () => void

Hears the player step off a prop's area.

Parameters

Name	Type
`listener`	`(event: { room: CustomRoomInfo; prop: string; }) => void`

Returns

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

Types

CustomRoomInfo

`onPropNear`

eventplugins · game:read

TypeScript

onPropNear(listener: (event: { room: CustomRoomInfo; prop: string; }) => void) => () => void

Hears the player come within a prop's nearDistance.

Parameters

Name	Type
`listener`	`(event: { room: CustomRoomInfo; prop: string; }) => void`

Returns

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

Types

CustomRoomInfo

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.

`CustomRoomInfo`

A custom room built from a description, and while the player is in it.

Field	Type
`id`	`string`	What `define` gave back for it.
`name`	`string`
`shared` optional	`boolean \| undefined`	Whether the player is in it with others, entered with `shared`.

`CustomRoomLimits`

What a room's objects will carry: the limits Phantom's server holds an instance to.

Read from the community protocol rather than written down again here, so the number a plugin sizes itself by is the number the server counts with.

Field	Type
`objects`	`number`	How many objects one shared room instance holds at once.
`objectTag`	`number`	The longest the word kept on an object may be, in bytes as UTF-8.

`CustomRoomSpec`

A custom room, described. Every measure is in the room's pixels, 0, 0 its top left corner.

Field	Type
`name`	`string`	What the game shows as the room's name.
`width`	`number`	The room's size: 900 by 550 (one screen) up to 3000 by 2000. Larger than a screen, the view follows the player as in Animal Jam's own rooms.
`height`	`number`
`background`	`CustomRoomPicture`	The picture behind everything, stretched over the whole room: paint it at the room's size and nothing is stretched.
`walkable` optional	`CustomRoomArea[] \| undefined`	Where avatars may walk: the whole room, less a margin at its edges, when left out.
`blocked` optional	`CustomRoomArea[] \| undefined`	Taken out of `walkable`: walls, anything every animal walks round.
`landWalls` optional	`CustomRoomArea[] \| undefined`	Laid over what is walkable: areas an animal on the ground may not enter, though one in the air may. Water is this. The client's grid has four kinds of cell, not two (`GRID_CELL` in `@phantom/swf`), and it settles which of them stop this avatar as it reads the room in, so one room file walks one way for an animal on the ground and another for an animal in the air.
`airWalls` optional	`CustomRoomArea[] \| undefined`	Laid over what is walkable: areas an animal in the air may not enter, though one on the ground may.
`spawn`	`{ x: number; y: number; }`	Where the player appears.
`props` optional	`CustomRoomProp[] \| undefined`
`exits` optional	`CustomRoomExit[] \| undefined`
`characters` optional	`CustomRoomCharacter[] \| undefined`	Who is standing in it who is not a player: up to 8 of them.
`music` optional	`{ track: string; volume?: number \| undefined; } \| undefined`	One of Animal Jam's own music tracks, by its file name, at a volume from 0 to 100.
`spawns` optional	`CustomRoomSpawn[] \| undefined`	The room's spawns besides `spawn`, each named, for a doorway to arrive at: up to 16 of them. The one `spawn` names is `default` and is not written here again.
`doorways` optional	`CustomRoomDoorway[] \| undefined`	Doorways to somewhere else: up to 8 of them. An exit goes back where the player came from; a doorway names where it leads, either another room of your own or one of Animal Jam's.
`volumes` optional	`CustomRoomVolume[] \| undefined`	Named areas of the room the client can find by name, `bouncevolume` among them: up to 32 of them. A prop with `bounce` or `clickable` already makes one of its own, so this is for the areas that are not a prop.
`scroll` optional	`CustomRoomScroll \| undefined`	How far the view scrolls: the whole room, worked out from its size, when left out. What a player can see spans `xmin` to `xmax + 900` across and `ymin` to `ymax + 550` down.

`CustomRoomPicture`

A picture: a PNG, a JPEG or a SWF, as a data: URL (what import art from './art.png?inline' gives a plugin) or as its bytes. A PNG keeps its transparency, which is what a prop wants.

A SWF is what Animal Jam's own room art is, and the client loads one exactly as it loads a picture (SceneLoader.loadAsset hands any of the three to Loader.loadBytes). It is drawn at its stage's size unless width and height say otherwise, and it plays whatever is on its timeline. What a SWF cannot be is a prop Phantom draws rather than the room: changeable, motion and frames are all Phantom drawing the picture itself, and it has no Flash player to do it with.

TypeScript

type CustomRoomPicture = string | Uint8Array

`CustomRoomArea`

An area of the room, in the room's pixels.

TypeScript

type CustomRoomArea = | { rect: { x: number; y: number; width: number; height: number } }
  | { circle: { x: number; y: number; radius: number } }
  | { polygon: Array<[number, number]> }

`CustomRoomProp`

Something standing in the room: decoration, or something the player can walk into or click.

Field	Type
`id`	`string`	Your own name for it, which its events carry. Letters, digits, `-` and `_`.
`art`	`CustomRoomPicture`	Its picture, a PNG with a clear background for anything that is not a rectangle.
`x`	`number`	Where the picture's top left corner goes, in the room.
`y`	`number`
`width` optional	`number \| undefined`	How large it is drawn, and its box: the picture's own size (one frame's, for a strip) when left out. Drawn at its own size, a picture stays sharp.
`height` optional	`number \| undefined`
`layer` optional	`"top" \| "floor" \| "standing" \| "front" \| undefined`	`floor`: under every avatar (a rug, a dance floor). `standing` (the default): among them, in front of those behind it and behind those in front. `front`: over every avatar. `top`: over everything the room draws at all, which is the client's own fourth layer (`RoomLayerDepth`).
`sortHeight` optional	`number \| undefined`	`standing` only: how far above its lowest point it counts as standing, in pixels, which is what sorts it in front of or behind a player near it (`SortLayer`). Left out, the client decides, which is the whole of its box.
`scaleX` optional	`number \| undefined`	How much the picture is scaled inside its box, across and down; 1 by default, which is the box itself. Its box is still `width` by `height`, so what avatars walk round and what the player clicks do not move when the picture is scaled.
`scaleY` optional	`number \| undefined`
`motion` optional	`CustomRoomMotion \| undefined`	Moves the picture: a pulse, a spin, a bob, or any of them together.
`frames` optional	`CustomRoomFrames \| undefined`	Plays the picture as a strip of frames.
`solid` optional	`boolean \| undefined`	Avatars cannot walk through its box, or through `area` when it has one.
`area` optional	`CustomRoomArea \| undefined`	Where it is, for walking into, clicking and nearness: its box when left out.
`clickable` optional	`boolean \| undefined`	`onPropClick` hears the player clicking it, and the pointer shows it can be clicked.
`nearDistance` optional	`number \| undefined`	`onPropNear` hears the player coming within this many pixels of its area.
`bounce` optional	`boolean \| undefined`	Every avatar standing in its area bounces.
`changeable` optional	`boolean \| undefined`	Phantom draws this one rather than the room, so `phantom.aj.customRooms.prop(id)` can move it, hide it and give it another picture while the player stands there. What a changeable prop cannot have is what the room's file settles once and for all: `motion`, `frames`, `solid` and `bounce`, each of which is built into the room or its walking map, which are the room itself. Clicking and nearness follow it wherever it goes. Phantom draws it on top of its own layer rather than sorting it with what the room draws, so a `standing` one is over the avatars rather than among them; `floor` is what puts a changeable prop under them.
`shared` optional	`boolean \| undefined`	Makes it an object: a changeable prop whose state Phantom's server holds, so that everyone in the same shared room instance agrees about it and two people cannot both walk off with it. `phantom.aj.customRooms.object(id)` is the handle; `prop(id)` refuses one, since where it stands is not this player's to decide. It needs `changeable: true`, and it is part of what the room is: a room whose sword is shared is a different room from one whose sword is not, and people on the two do not meet. Where the sword has got to is not, which is the whole point of the split. In a room the player entered on their own there is nobody to take it from, so it works the same way with the player as its only company: one piece of code for both.

`CustomRoomMotion`

How a prop's picture moves, looping, each of these at once.

Field	Type
`pulse` optional	`{ seconds: number; min?: number \| undefined; } \| undefined`	Fades down to `min` opacity (0 to 1, 0.35 by default) and back, every `seconds`.
`spin` optional	`{ seconds: number; } \| undefined`	Turns once round its middle every `seconds`; below 0 turns the other way.
`bob` optional	`{ seconds: number; height: number; } \| undefined`	Rises `height` pixels and falls back, every `seconds`.

`CustomRoomFrames`

A prop's picture as a strip of frames: count frames of the same size side by side, left to right, shown in turn fps times a second and looping, as a flip book.

Field	Type
`count`	`number`
`fps`	`number`

`CustomRoomExit`

A way out: walking into its circle takes the player back to the room they came from.

Field	Type
`id`	`string`
`x`	`number`
`y`	`number`
`radius`	`number`

`CustomRoomCharacter`

Somebody standing in the room who is not a player: a character with a name over its head, a place to stand, a look, a round it walks and lines it says when it is clicked.

It is drawn by the game's own client, from the same packets that draw everyone else, so it has Animal Jam's own name bar, chat balloon and walk. Only this player sees it: nothing about a character is sent to Animal Jam, and the room's engine drops anything the client tries to send that names one, so clicking it can never become a question about a player who does not exist.

Field	Type
`id`	`string`	Your own name for it, which its events carry. Letters, digits, `-` and `_`, up to 40 long.
`name`	`string`	The name over its head, 1 to 20 characters.
`x`	`number`	Where it stands when the player walks in.
`y`	`number`
`flipped` optional	`boolean \| undefined`	Facing left.
`look` optional	`CustomRoomCharacterLook \| undefined`	What it looks like: the player's own animal, undressed, when left out.
`greeting` optional	`string \| undefined`	What it says as the player walks in, once, in its own balloon.
`says` optional	`string[] \| undefined`	What it says when it is clicked: one line to a click, in order, starting again at the first once it has said the last. Up to 20 lines of up to 200 characters, which is what a balloon over an animal's head holds. A character with no lines still takes the click, and `onCharacterClick` still hears it, which is how a plugin says something worked out as it is asked for rather than written down here.
`path` optional	`{ x: number; y: number; }[] \| undefined`	A round it walks, over and over: from where it stands to each of these points in turn, and back to where it started. Up to 12 points, each somewhere the room lets avatars walk.
`pace` optional	`number \| undefined`	How long it takes over each step of `path`, in seconds: 4 by default, 1 to 60.
`clickable` optional	`boolean \| undefined`	Whether clicking it does anything at all: true by default. The click is taken from the game either way, so a character nobody is meant to click cannot open a card on itself.

`CustomRoomCharacterLook`

How a character is drawn: one of Animal Jam's own animals, in the colours and clothes you name.

Everything here but phantom and tint is carried by the packet that walks the character into the room, which is the same packet that describes any other player, so it costs nothing at all: whatever animal you name, the client loads its art exactly as it does for a stranger walking into Jamaa. The two that are not are asked of the client itself once the character is standing there, which is one call each and why they are the only two.

Field	Type
`animal` optional	`number \| undefined`	The animal, by its def id: `(await phantom.player.animalOf())?.defId` is the player's own, and `phantom.player.customAnimalsOf` and the client's own def packs have the rest. Left out, it is whatever animal the player is wearing. That is the one animal whose art the client certainly has, and it is what a room only the player sees wants; name one for a shared room, or the others in it each see a character of their own animal.
`customAnimal` optional	`number \| undefined`	A custom (recycled) animal's id, as `AnimalKind.custom` has them; -1 for an ordinary one.
`colors` optional	`[number, number, number] \| undefined`	Its three colours, as the client packs them (`AnimalKind.colors`); the animal's own by default.
`eyes` optional	`number \| undefined`	Its eyes, by their def id; the animal's own by default.
`pattern` optional	`number \| undefined`	Its pattern, by its def id; none by default.
`wearing` optional	`{ defId: number; color?: number \| undefined; }[] \| undefined`	What it wears, each by its def id and colour, up to 24 of them.
`member` optional	`boolean \| undefined`	Draw it with a member's name bar, as the game draws a member.
`phantom` optional	`boolean \| undefined`	Draw it as one of Animal Jam's own Phantoms, over the animal underneath: the look the game gives a player it has turned into one, with its own name bar and its own chat balloon, none of which Phantom has to draw.
`tint` optional	`number \| undefined`	A tint pulled over its colours, `0xAARRGGBB`, where the alpha is how far each colour is pulled toward it: `0xb03a3a40` is Phantom's own dark grey, most of the way.

`CustomRoomSpawn`

Somewhere a player can appear in the room besides the one spawn names.

A doorway leading here names one of these by its name, so a room with several ways in can put the player at the one they came through. The room's own spawn is the default one and is not written here.

Field	Type
`name`	`string`	What a doorway leading here asks for. Letters, digits, `-` and `_`, up to 40 long, and not `default`, which is what the room's own `spawn` is.
`x`	`number`
`y`	`number`
`radius` optional	`number \| undefined`	How far from the point a player may appear: 10 pixels when left out, as `spawn` is.
`walkTo` optional	`string \| undefined`	Another spawn of the same room to walk to on arriving, by name, so the player walks in rather than simply being there.

`CustomRoomDoorway`

A doorway: walking into its circle takes the player to another room, rather than back to the one they came from.

It is the room file's own portal (ActorPortal), which is how Animal Jam joins its own rooms up, so the player walks through it exactly as they walk from Jamaa Township into the Chamber of Knowledge. An exit (CustomRoomExit) is the other kind of portal and stays what it is: a doorway names somewhere to go, an exit names nowhere and means "back".

A doorway to a room of your own does nothing out of a shared room: walking out of the company's room into one the player would be in alone would take them out of the instance without their asking. Use an exit there, or enter the next room shared yourself.

Field	Type
`id`	`string`	Your own name for it. Letters, digits, `-` and `_`, up to 40 long.
`x`	`number`	The middle of the circle a player walks into.
`y`	`number`
`radius`	`number`	How wide that circle is, 10 to 300 pixels.
`to`	`CustomRoomDestination`	Where it leads.
`spawn` optional	`string \| undefined`	Which spawn of the room it leads to the player arrives at, by name: that room's `default` when left out. Naming one of another custom room's `spawns` is what puts the player at its door rather than in the middle of it.

`CustomRoomDestination`

Where a doorway leads. One of the two, never both.

The difference is who answers the join. A room is one of yours, so Phantom answers it and Animal Jam hears nothing; a jamaa room is a real one, so the join goes to Animal Jam and the player genuinely leaves the custom room for it.

TypeScript

type CustomRoomDestination = | { room: string }
  /**
   * One of Animal Jam's own rooms, by the name `phantom.aj.room.join` takes
   * (`jamaa_township.room_main`). `phantom.aj.world.roomDefinitions()` lists every one the client
   * knows, each with that name as its `pathName`, which is where to get it from rather than
   * writing one out and hoping.
   */
  | { jamaa: string }

Run in Phantom

`CustomRoomVolume`

A named area of the room, which the client finds by its name (VolumeManager).

This is the room file's own ActorVolume, the thing a bouncing prop and a clickable prop are each built from. It is here for the names the client itself knows, and for the names a plugin's own code looks up over the bridge.

bouncevolume is the one name the client acts on by itself: every avatar standing in it bounces. It bounces in the first one the room has and ignores the rest, so a room has one bouncing area however many are written, and a second is refused rather than quietly ignored.

Field	Type
`name`	`string`	What the client finds it by. Letters, digits, `-`, `_` and `:`, up to 40 long.
`area`	`CustomRoomArea`	The shape it covers, in the room's pixels.
`kind` optional	`number \| undefined`	`VolumeManager`'s type: 0, a plain named area, when left out.
`message` optional	`string \| undefined`	The message it carries, for the kinds of volume that have one.
`walkTo` optional	`boolean \| undefined`	Clicking in it walks the player there.

`CustomRoomScroll`

How far the view scrolls over a room larger than a screen.

The view's top left corner stays within these, so what a player can see spans xmin to xmax + 900 across and ymin to ymax + 550 down. Worked out from the room's size when left out: xmin: 0, xmax: width - 900, ymin: 0 and ymax: height - 550, which is the whole room and nothing beyond it.

Narrowing them keeps a border out of sight, so a background painted with a margin can be drawn whole and never walked to the edge of.

Field	Type
`xmin`	`number`
`xmax`	`number`
`ymin`	`number`
`ymax`	`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`

`CustomRoomEnterOptions`

How the player goes into a room.

Field	Type
`shared` optional	`boolean \| undefined`	Put the player in the room with everyone else who entered it shared from this plugin: they see each other there and can talk. Only a plugin installed from the Phantom store can share a room, and only a room its store version builds (one in Developer mode can too, to test, with other developers only). The community's rules apply, and the player must be signed in to Phantom.

`SharedRoomListing`

A shared room with people in it now, from any plugin in the Phantom store: its name, the plugin's title, and how many are in it across its instances. Never who.

Field	Type
`name`	`string`	The room's name, as its plugin defined it.
`title`	`string`	The plugin's title, as the store lists it.
`people`	`number`	How many people are in it.

`CustomRoomPropHandle`

A prop of one of your rooms: what moves it, hides it and repictures it (changeable props).

Field	Type
`id`	`string`
`move`	`(x: number, y: number) => Promise<CustomRoomPropState>`	Where its picture's top left corner goes, in the room's pixels.
`hide`	`() => Promise<CustomRoomPropState>`
`show`	`() => Promise<CustomRoomPropState>`
`art`	`(picture: CustomRoomPicture \| null) => Promise<CustomRoomPropState>`	Another picture, or null for the one the room describes.
`change`	`(change: CustomRoomPropChange) => Promise<CustomRoomPropState>`	Several of those at once, so nothing is drawn halfway between.
`reset`	`() => Promise<CustomRoomPropState>`	Back as the room describes it.
`now`	`() => Promise<CustomRoomPropState \| null>`

`CustomRoomPropState`

Where a changeable prop stands now, and how it looks: the room's state rather than the room.

None of this is part of what the room is. A room is the same room whether its sword is on the wall or on the floor, which is why two people who described the same room still meet in it after one of them has moved something.

Field	Type
`id`	`string`
`room`	`string`	The room it belongs to, as `define` gave its id back.
`x`	`number`	Where its picture's top left corner is drawn now.
`y`	`number`
`shown`	`boolean`	Whether it is drawn at all.
`changed`	`boolean`	Whether anything has been changed about it: false for one standing as the room describes it.

`CustomRoomPropChange`

What to change about a prop. Anything left out is left as it is.

Field	Type
`x` optional	`number \| undefined`
`y` optional	`number \| undefined`
`shown` optional	`boolean \| undefined`	False hides it: it is not drawn, and stepping where it was says nothing.
`art` optional	`CustomRoomPicture \| null \| undefined`	Another picture, or null for the one the room describes.
`reset` optional	`boolean \| undefined`	Puts it back as the room describes it first, so what this change leaves out goes back rather than staying as it was. `reset` on its own is how a prop forgets everything done to it.

`CustomRoomCharacterHandle`

A character of one of your rooms: what makes it speak, walk, go and come back.

Field	Type
`id`	`string`
`say`	`(text: string) => Promise<CustomRoomCharacterState>`	Something to say in its own balloon, instead of the next of its own lines.
`walk`	`(x: number, y: number) => Promise<CustomRoomCharacterState>`	Walks it there, at its own pace.
`put`	`(x: number, y: number) => Promise<CustomRoomCharacterState>`	Puts it there at once.
`hide`	`() => Promise<CustomRoomCharacterState>`
`show`	`() => Promise<CustomRoomCharacterState>`
`change`	`(change: CustomRoomCharacterChange) => Promise<CustomRoomCharacterState>`
`now`	`() => Promise<CustomRoomCharacterState \| null>`

`CustomRoomCharacterState`

A character as it stands now: where it has walked to, whether it is in the room, and how far through its lines it has got.

None of this is part of what the room is, in the same way a prop's place is not. A room is the same room whether its gatekeeper is by the door or half way round its round, which is why two people who described the same room still meet in it while their characters walk about separately.

Field	Type
`id`	`string`
`room`	`string`	The room it belongs to, as `define` gave its id back.
`name`	`string`	The name over its head, as the room describes it.
`x`	`number`	Where it is standing now.
`y`	`number`
`shown`	`boolean`	Whether it is in the room at all.
`said`	`number`	How many of its lines it has said since the player walked in.

`CustomRoomCharacterChange`

What to do to a character. Anything left out is left as it is.

Field	Type
`say` optional	`string \| undefined`	Something for it to say, in its own balloon, instead of the next of its own lines.
`x` optional	`number \| undefined`	Where to send it.
`y` optional	`number \| undefined`
`walk` optional	`boolean \| undefined`	Walk there, at its own pace and with its own walk, rather than simply being there.
`shown` optional	`boolean \| undefined`	False takes it out of the room; true puts it back where it stands.

`CustomRoomObjectHandle`

A shared object of one of your rooms (shared: true), whose state Phantom's server settles: what takes it, puts it down, moves it and marks it. Everything but take needs it held by this player.

Field	Type
`id`	`string`
`take`	`(change?: CustomRoomObjectChange \| undefined) => Promise<CustomRoomObjectState>`	Takes it, with anything else to do to it in the same breath. `held` when somebody has it.
`drop`	`(change?: CustomRoomObjectChange \| undefined) => Promise<CustomRoomObjectState>`	Gives it up where it stands, with anything else to do to it first.
`move`	`(x: number, y: number) => Promise<CustomRoomObjectState>`
`hide`	`() => Promise<CustomRoomObjectState>`
`show`	`() => Promise<CustomRoomObjectState>`
`mark`	`(word: string \| null) => Promise<CustomRoomObjectState>`	A short word to keep on it, or null to take it off.
`reset`	`() => Promise<CustomRoomObjectState>`
`change`	`(change: CustomRoomObjectChange) => Promise<CustomRoomObjectState>`	Several at once, made whole or refused whole.
`now`	`() => Promise<CustomRoomObjectState \| null>`
`onTaken`	`(listener: (turn: CustomRoomObjectTurn) => void) => () => void`	Hears somebody take it, this player included.
`onDropped`	`(listener: (turn: CustomRoomObjectTurn) => void) => () => void`	Hears it put down, by whoever had it or by Phantom when they left.
`onChanged`	`(listener: (turn: CustomRoomObjectTurn) => void) => () => void`	Hears anything happen to it.

`CustomRoomObjectChange`

What to do to an object, made whole or refused whole.

The order is take, then reset, then the rest, then drop, so one call does the whole of what you mean: a sword picked up and put out of sight is { take: true, shown: false }, a lever somebody flips without keeping is { take: true, tag: 'on', drop: true }.

Everything but take needs the object held by this player, which is what keeps two people from changing one thing at once. There is no art: an object's picture stays the one the room describes, because a room's shared state is no place to send pictures to thirty people. A thing with two looks is two props with one of them hidden.

Field	Type
`take` optional	`boolean \| undefined`	Takes it. Refused if somebody else has it.
`drop` optional	`boolean \| undefined`	Gives it up, once the rest of the change is made.
`reset` optional	`boolean \| undefined`	Puts it back as the room describes it, before the rest of the change.
`x` optional	`number \| undefined`
`y` optional	`number \| undefined`
`shown` optional	`boolean \| undefined`	False hides it: it is not drawn, and stepping where it was says nothing.
`tag` optional	`string \| null \| undefined`	A short word to keep on it, up to 64 bytes, or null to take the word off.

`CustomRoomObjectState`

An object as it stands: a prop given shared: true, whose state Phantom's server owns for the shared room instance the player is in.

Like a prop's state, none of it is part of what the room is. Two people meet in a room because their descriptions hash alike; who is holding its sword is what has happened there since.

Field	Type
`id`	`string`
`room`	`string`	The room it belongs to, as `define` gave its id back.
`holder`	`string \| null`	Who holds it, or null for nobody. It is an id that means something only inside the room instance the player is in: never an account, a player or a screen name, and a different one each time the same person comes back.
`mine`	`boolean`	Whether this player is the one holding it.
`x`	`number`	Where its picture's top left corner is drawn now.
`y`	`number`
`shown`	`boolean`	Whether it is drawn at all.
`tag`	`string \| null`	The word the plugin has kept on it (`open`, `lit`, a score as text); null for none.
`changed`	`boolean`	Whether anything has been done to it: false for one standing as the room describes it.

`CustomRoomObjectTurn`

One object's part of an event, as a handle's listeners hear it.

Field	Type
`object`	`CustomRoomObjectState`
`by`	`string \| null`	Who did it, as `holder` names people; null where Phantom did.
`yours`	`boolean`
`took`	`boolean`
`dropped`	`boolean`

`CustomRoomObjectEvent`

Something that happened to a room's objects, as the server settled it.

Field	Type
`room`	`CustomRoomInfo`
`objects`	`CustomRoomObjectState[]`	Only the objects that changed, each as it stands now.
`by`	`string \| null`	Who changed them, as `holder` names people; null where Phantom did, their holder having left.
`yours`	`boolean`	Whether it was this player who did it.
`took`	`boolean`	Whether the change took them, and whether it gave them up.
`dropped`	`boolean`

Custom rooms ​

Overview ​

Methods ​

character ​

characters ​

current ​

define ​

enter ​

isAvailable ​

leave ​

limits ​

object ​

objects ​

open ​

prop ​

remove ​

shared ​

Events ​

onCharacterClick ​

onChat ​

onEnter ​

onLeave ​

onMove ​

onObject ​

onPropClick ​

onPropEnter ​

onPropLeave ​

onPropNear ​

Types ​

CustomRoomInfo ​

CustomRoomLimits ​

CustomRoomSpec ​

CustomRoomPicture ​

CustomRoomArea ​

CustomRoomProp ​

CustomRoomMotion ​

CustomRoomFrames ​

CustomRoomExit ​

CustomRoomCharacter ​

CustomRoomCharacterLook ​

CustomRoomSpawn ​

CustomRoomDoorway ​

CustomRoomDestination ​

CustomRoomVolume ​

CustomRoomScroll ​

ActOptions ​

CustomRoomEnterOptions ​

SharedRoomListing ​

CustomRoomPropHandle ​

CustomRoomPropState ​

CustomRoomPropChange ​

CustomRoomCharacterHandle ​

CustomRoomCharacterState ​

CustomRoomCharacterChange ​

CustomRoomObjectHandle ​

CustomRoomObjectChange ​

CustomRoomObjectState ​

CustomRoomObjectTurn ​

CustomRoomObjectEvent ​

Custom rooms

Overview

Methods

`character`

`characters`

`current`

`define`

`enter`

`isAvailable`

`leave`

`limits`

`object`

`objects`

`open`

`prop`

`remove`

`shared`

Events

`onCharacterClick`

`onChat`

`onEnter`

`onLeave`

`onMove`

`onObject`

`onPropClick`

`onPropEnter`

`onPropLeave`

`onPropNear`

Types

`CustomRoomInfo`

`CustomRoomLimits`

`CustomRoomSpec`

`CustomRoomPicture`

`CustomRoomArea`

`CustomRoomProp`

`CustomRoomMotion`

`CustomRoomFrames`

`CustomRoomExit`

`CustomRoomCharacter`

`CustomRoomCharacterLook`

`CustomRoomSpawn`

`CustomRoomDoorway`

`CustomRoomDestination`

`CustomRoomVolume`

`CustomRoomScroll`

`ActOptions`

`CustomRoomEnterOptions`

`SharedRoomListing`

`CustomRoomPropHandle`

`CustomRoomPropState`

`CustomRoomPropChange`

`CustomRoomCharacterHandle`

`CustomRoomCharacterState`

`CustomRoomCharacterChange`

`CustomRoomObjectHandle`

`CustomRoomObjectChange`

`CustomRoomObjectState`

`CustomRoomObjectTurn`

`CustomRoomObjectEvent`