Polls

phantom.aj.pollsPlaying

Polls in the world.

Scripts and plugins

A script has all of it, as phantom.aj.polls, 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
`answered()`	What the player answered for one poll, from the stat its definition names (`userVarCache.getUserVarValueById`); null while the definition is unknown.	`game:read`
`definition()`	One poll's definition as the client holds it (`_pollDefCache`): every poll a room set up since the game loaded; null for one it never fetched, which `loadDefinition` fetches.	`game:read`
`imageVotes()`	Both picture-grid stats: the t-shirt poll (312) and the den-item poll (374).	`game:read`
`inRoom()`	Every poll the room carries: where its tab goes, what a vote writes, its definition and what the player answered.	`game:read`
`loadDefinition()`	One poll's definition, fetched from the def pack when the client has not got it, as `PollManager` fetches one (`PollDefHelper.init`, then `onDefReceivedSetup`, which translates and caches it).	`game:act`
`pending()`	The room's poll set-up the client is holding while the tab artwork (media 153) loads (`_dataToSetupPolls`): the answer to a room that has polls and shows no tabs yet.	`game:read`
`vote()`	Votes on a question poll as its popup's vote button does (`PollManager.onPollVote`): the poll's stat set to the room's `params` (or `value`), then stat 113 bumped.	`game:act`
`voteImages()`	Votes in a grid of pictures as its done button does (`ImagePoll.onClose`): the round's number written to the grid's stat, once the server kept it.	`game:act`
`onImageVote()`	Hears a vote go through a grid of pictures (its done button, `ImagePoll.onClose`), with the windows ticked and the bitmask they make.	`game:read`
`onRoomPolls()`	Hears a room hand the client its polls (`PollManager.setUpPolls`), with the room's `params` for each: a poll appearing.	`game:read`
`onTab()`	Hears the client decide whether a poll's tab goes up (`PollManager.setUpPoll`), once its definition arrived: the definition, where it goes, the player's vote, and `shown`, the client's own test.	`game:read`
`onVote()`	Hears a vote go through a question popup (`PollManager.onPollVote`), with the option picked: the one place it is ever known.	`game:read`

polls.screens: The question popup and the grid of pictures.

Member	What it does	Plugins
`closeImagePoll()`	Takes the grid of pictures down (`ImagePoll.destroy`).	`game:act`
`closePoll()`	Closes the question popup in play, as its close button ends up doing (`PollManager.onPollDone`): destroyed, `_pollPopup` cleared.	`game:act`
`imagePoll()`	The grid of pictures, or null when none was opened this sitting.	`game:read`
`openImagePoll()`	Opens a grid of pictures (`ImagePoll.displayPoll`), as a t-shirt poll's tab and the newspaper's den-item vote do, with the client's own numbers for the kind; resolves with the grid once it is up.	`game:act`
`openPoll()`	Opens a poll's question popup with no tab (`PollManager.setupNonTabPoll`), as the login polls open, fetching its definition first if need be; resolves with the popup once it is in play.	`game:act`
`poll()`	The question popup in play, or null for none: its question, its options in the order on screen (the client shuffles them), and the option a vote would carry.	`game:read`
`onChange()`	Hears the poll windows open, close and change: a question popup or a grid going up or down, a window ticked, an option picked.	`game:read`
`onStep()`	Hears the client work a poll's screens: a definition arriving, the popup built, a tab clicked (with the frame that says which screen it opens), a grid closed.	`game:read`

Methods

`answered`

methodplugins · game:read

TypeScript

answered(pollDefId: number) => Promise<PollVote | null>

What the player answered for one poll, from the stat its definition names (userVarCache.getUserVarValueById); null while the definition is unknown. The stat says only that they answered: what it holds is the room's params, not the option.

Parameters

Name	Type
`pollDefId`	`number`

Returns

Promise<PollVote \| null>

Types

PollVote

`definition`

methodplugins · game:read

TypeScript

definition(pollDefId: number) => Promise<PollDefinition | null>

One poll's definition as the client holds it (_pollDefCache): every poll a room set up since the game loaded; null for one it never fetched, which loadDefinition fetches.

Parameters

Name	Type
`pollDefId`	`number`

Returns

Promise<PollDefinition \| null>

Types

PollDefinition

`imageVotes`

methodplugins · game:read

TypeScript

imageVotes() => Promise<{ tshirt: PollVote; denItem: PollVote; }>

Both picture-grid stats: the t-shirt poll (312) and the den-item poll (374). Each holds the round last voted in, so a new round opens with a new index.

Returns

Promise<{ tshirt: PollVote; denItem: PollVote; }>

Types

PollVote

`inRoom`

methodplugins · game:read

TypeScript

inRoom() => Promise<RoomPoll[]>

Every poll the room carries: where its tab goes, what a vote writes, its definition and what the player answered. Empty in a room with none, before the room set them up, and for a player with fewer than three logins, for whom the client never does.

Returns

Promise<RoomPoll[]>

Types

RoomPoll · PollDefinition · PollVote

`loadDefinition`

methodplugins · game:act

TypeScript

loadDefinition(pollDefId: number, options?: ActOptions) => Promise<PollDefinition>

One poll's definition, fetched from the def pack when the client has not got it, as PollManager fetches one (PollDefHelper.init, then onDefReceivedSetup, which translates and caches it). Costs one request to the content server and nothing to the game server. Throws REFUSED when the def pack has no such poll, TIMEOUT when the file never lands.

Parameters

Name	Type
`pollDefId`	`number`
`options` optional	`ActOptions`

Returns

Promise<PollDefinition>

Types

ActOptions · PollDefinition

`pending`

methodplugins · game:read

TypeScript

pending() => Promise<PollSetUp[] | null>

The room's poll set-up the client is holding while the tab artwork (media 153) loads (_dataToSetupPolls): the answer to a room that has polls and shows no tabs yet. Null when nothing waits.

Returns

Promise<PollSetUp[] \| null>

Types

PollSetUp

`vote`

methodplugins · game:act

TypeScript

vote(pollDefId: number, options?: ActOptions & { value?: number | undefined; option?: number | undefined; track?: boolean | undefined; }) => Promise<PollVoteSent>

Votes on a question poll as its popup's vote button does (PollManager.onPollVote): the poll's stat set to the room's params (or value), then stat 113 bumped. Resolves once the server kept it. option with track also sends the analytics line the client sends, which is the only place the option picked ever goes.

Throws NOT_READY for a poll whose definition the client has not got (loadDefinition), and REFUSED for one with no stat, while the player is invisible (the client sends nothing), or when the server kept another value.

Parameters

Name	Type
`pollDefId`	`number`
`options` optional	`ActOptions & { value?: number \| undefined; option?: number \| undefined; track?: boolean \| undefined; }`

Returns

Promise<PollVoteSent>

Types

PollVoteSent · ActOptions

`voteImages`

methodplugins · game:act

TypeScript

voteImages(items?: readonly number[] | undefined, options?: ActOptions & { userVarId?: number | undefined; index?: number | undefined; track?: boolean | undefined; }) => Promise<ImageVoteSent>

Votes in a grid of pictures as its done button does (ImagePoll.onClose): the round's number written to the grid's stat, once the server kept it. With no items, what the player ticked on screen. The bitmask of pictures, the vote itself, goes only to Animal Jam's analytics, and only with track. The grid stays up: screens.closeImagePoll({ thanks: true }) takes it down.

Throws NOT_READY with no grid opened and no userVarId given.

Parameters

Name	Type
`items` optional	`readonly number[] \| undefined`
`options` optional	`ActOptions & { userVarId?: number \| undefined; index?: number \| undefined; track?: boolean \| undefined; }`

Returns

Promise<ImageVoteSent>

Types

ImageVoteSent · ActOptions

Example

TypeScript

await phantom.aj.polls.voteImages([0, 4], { track: true });

Run in Phantom

Events

`onImageVote`

eventplugins · game:read

TypeScript

onImageVote(listener: (vote: ImageVoteHeard) => void) => () => void

Hears a vote go through a grid of pictures (its done button, ImagePoll.onClose), with the windows ticked and the bitmask they make. The close box is not a vote and is not heard.

Parameters

Name	Type
`listener`	`(vote: ImageVoteHeard) => void`

Returns

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

Types

ImageVoteHeard

`onRoomPolls`

eventplugins · game:read

TypeScript

onRoomPolls(listener: (polls: PollSetUp[]) => void) => () => void

Hears a room hand the client its polls (PollManager.setUpPolls), with the room's params for each: a poll appearing. Nothing in a room with none.

Parameters

Name	Type
`listener`	`(polls: PollSetUp[]) => void`

Returns

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

Types

PollSetUp

`onTab`

eventplugins · game:read

TypeScript

onTab(listener: (tab: PollTab) => void) => () => void

Hears the client decide whether a poll's tab goes up (PollManager.setUpPoll), once its definition arrived: the definition, where it goes, the player's vote, and shown, the client's own test. The vote is read just after the call.

Parameters

Name	Type
`listener`	`(tab: PollTab) => void`

Returns

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

Types

PollTab

`onVote`

eventplugins · game:read

TypeScript

onVote(listener: (vote: PollVoteHeard) => void) => () => void

Hears a vote go through a question popup (PollManager.onPollVote), with the option picked: the one place it is ever known. vote does not go through the popup and is not heard here.

Parameters

Name	Type
`listener`	`(vote: PollVoteHeard) => void`

Returns

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

Types

PollVoteHeard

`polls.screens`

The question popup and the grid of pictures.

`closeImagePoll`

methodplugins · game:act

TypeScript

closeImagePoll(options?: ActOptions & { thanks?: boolean | undefined; }) => Promise<void>

Takes the grid of pictures down (ImagePoll.destroy). thanks puts up the client's "thanks for voting" popup after, as its done button does. Nothing up resolves at once.

Parameters

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

Returns

Promise<void>

Types

ActOptions

`closePoll`

methodplugins · game:act

TypeScript

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

Closes the question popup in play, as its close button ends up doing (PollManager.onPollDone): destroyed, _pollPopup cleared. Nothing to close resolves at once.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`imagePoll`

methodplugins · game:read

TypeScript

imagePoll() => Promise<ImagePollWindow | null>

The grid of pictures, or null when none was opened this sitting. ImagePoll._imgPopup is never cleared, so a closed grid still reads back with its last vote: onScreen says whether it is up. Its pictures never load (onMediaListReceived only keeps the list when _mediaIds is set, which nothing sets), so order is null and mask is a plain bitmask of the places ticked.

Returns

Promise<ImagePollWindow \| null>

Types

ImagePollWindow

`openImagePoll`

methodplugins · game:act

TypeScript

openImagePoll(options?: OpenImagePollOptions) => Promise<ImagePollWindow>

Opens a grid of pictures (ImagePoll.displayPoll), as a t-shirt poll's tab and the newspaper's den-item vote do, with the client's own numbers for the kind; resolves with the grid once it is up. Throws REFUSED when the player already voted this round (the client shows "you have already voted" instead).

Parameters

Name	Type
`options` optional	`OpenImagePollOptions`

Returns

Promise<ImagePollWindow>

Types

OpenImagePollOptions · ImagePollWindow

`openPoll`

methodplugins · game:act

TypeScript

openPoll(pollDefId: number, options?: ActOptions) => Promise<PollWindow>

Opens a poll's question popup with no tab (PollManager.setupNonTabPoll), as the login polls open, fetching its definition first if need be; resolves with the popup once it is in play. Throws REFUSED while another popup is up, which the client would quietly drop it for.

Parameters

Name	Type
`pollDefId`	`number`
`options` optional	`ActOptions`

Returns

Promise<PollWindow>

Types

ActOptions · PollWindow

`poll`

methodplugins · game:read

TypeScript

poll() => Promise<PollWindow | null>

The question popup in play, or null for none: its question, its options in the order on screen (the client shuffles them), and the option a vote would carry. onScreen is false after a vote, while the thank-you popup stands in its place.

Returns

Promise<PollWindow \| null>

Types

PollWindow

`onChange`

eventplugins · game:read

TypeScript

onChange(listener: (screens: PollScreens) => void) => () => void

Hears the poll windows open, close and change: a question popup or a grid going up or down, a window ticked, an option picked. Read four times a second, told on change.

Parameters

Name	Type
`listener`	`(screens: PollScreens) => void`

Returns

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

Types

PollScreens

`onStep`

eventplugins · game:read

TypeScript

onStep(listener: (step: PollStep) => void) => () => void

Hears the client work a poll's screens: a definition arriving, the popup built, a tab clicked (with the frame that says which screen it opens), a grid closed.

Parameters

Name	Type
`listener`	`(step: PollStep) => void`

Returns

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

Types

PollStep

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.

`RoomPoll`

One poll the room carries.

Field	Type
`pollDefId`	`number`
`position`	`{ x: number; y: number; } \| null`	Where its tab goes, in room coordinates.
`param`	`number`	The room's `params` for it, the value a vote writes.
`kind`	`"image" \| "options"`	`image` for the t-shirt grid, `options` for a question.
`definition`	`PollDefinition \| null`	Null until the def pack has answered for it (`loadDefinition`).
`vote`	`PollVote \| null`	Null while the definition is unknown.

`PollDefinition`

One poll's definition, as the def pack holds it and the client has translated it.

Field	Type
`id`	`number`	The poll's def id, which a room's action point names.
`mediaId`	`number`	The popup's artwork.
`userVarId`	`number`	The stat a vote is written to; 0 for a poll the client sends nothing for.
`question`	`string`	The question, in the player's language.
`options`	`string[]`	The options in the file's order (the popup shuffles them).
`title`	`string`	The popup's title, translated.

`PollVote`

What the player holds against a poll's stat.

Field	Type
`pollDefId`	`number \| null`	The poll, or null for a stat read on its own (`imageVotes`).
`userVarId`	`number`
`value`	`number`	What the client holds for it; -1 for nothing.
`voted`	`boolean`	Anything from 0 up is a vote cast: the client puts a tab up only below 0.

`PollSetUp`

One poll a room handed the client, before its tab is drawn.

Field	Type
`pollDefId`	`number`
`param`	`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`

`PollVoteSent`

What a question poll's vote wrote.

Field	Type
`pollDefId`	`number`
`userVarId`	`number`
`value`	`number`	The value the server kept for the poll's stat.
`tracked`	`number \| null`	The option sent to Animal Jam's analytics, or null when nothing was tracked.

`ImageVoteSent`

What a grid of pictures' vote wrote.

Field	Type
`userVarId`	`number`
`index`	`number`	The round's number the server kept.
`ticked`	`number[]`	The windows voted for, from 0.
`mask`	`number`	The bitmask those windows make, the vote itself.
`tracked`	`boolean`	Whether the bitmask went to Animal Jam's analytics.

`PollTab`

A poll's tab the client is putting up, or not.

Field	Type
`definition`	`PollDefinition`
`position`	`{ x: number; y: number; } \| null`
`vote`	`PollVote`
`shown`	`boolean`	The client's own test: no vote yet.

`PollVoteHeard`

A vote heard going through a question popup.

Field	Type
`pollDefId`	`number`
`userVarId`	`number`
`option`	`number`	The option picked, from 1, as the definition numbers them.
`name`	`string \| null`	The name an adjustable poll took with the vote, or null.

`ImageVoteHeard`

A vote heard going through a grid of pictures.

Field	Type
`kind`	`"denItem" \| "tshirt" \| null`
`userVarId`	`number`
`index`	`number`
`ticked`	`number[]`
`mask`	`number`

`PollWindow`

The question popup in play.

Field	Type
`pollDefId`	`number`
`userVarId`	`number`
`title`	`string`
`question`	`string`
`options`	`string[]`	The options in the order on screen; empty until the artwork loaded.
`shown`	`number`	How many options it drew, 0 until its artwork has loaded.
`selected`	`number`	The place picked on screen, from 0; -1 for none.
`option`	`number \| null`	The definition's option number a vote would carry, from 1; null for none picked.
`onScreen`	`boolean`	False after a vote, while the thank-you popup stands in its place.

`ImagePollWindow`

The grid of pictures in play.

Field	Type
`kind`	`"denItem" \| "tshirt" \| null`
`userVarId`	`number`
`index`	`number`	This round's number, the value a vote writes.
`windows`	`number`
`allowedVotes`	`number`
`ticked`	`number[]`	The windows ticked, in order, from 0.
`order`	`number[] \| null`	The grid's shuffle; null in practice, as the client never fills it.
`mask`	`number`	The bitmask the done button would track.
`onScreen`	`boolean`

`OpenImagePollOptions`

How openImagePoll opens a grid: which one, and any of the client's arguments to change.

TypeScript

type OpenImagePollOptions = ActOptions & {
  /** The t-shirt poll by default. */
  kind?: ImagePollKind;
  userVarId?: number;
  /** The round; the room's `params` for the t-shirt poll, otherwise 1. */
  index?: number;
  popupMediaId?: number;
  mediaListId?: number;
  windows?: number;
  allowedVotes?: number;
}

`PollScreens`

The poll windows, as screens.onChange hears them.

Field	Type
`pollOpen`	`boolean`
`imagePollOpen`	`boolean`
`ticked`	`number`	How many of the grid's windows are ticked.
`selected`	`number \| null`	The place picked in the question popup, from 0; -1 for none, null with no popup.

`PollStep`

A step the client takes with a poll's screens.

Field	Type
`kind`	`"tabDefinition" \| "popupDefinition" \| "popupBuilt" \| "tabClicked" \| "imagePollClosed"`	`tabDefinition` / `popupDefinition`: a definition arrived. `popupBuilt`: the question popup was made (the client drops a second one while one is up). `tabClicked`: a tab was clicked, `frame` saying which screen it opens (`tshirtPoll` the grid). `imagePollClosed`: a grid went, taking the tab's listener with it.
`pollDefId`	`number \| null`
`frame`	`string \| null`

Polls ​

Overview ​

Methods ​

answered ​

definition ​

imageVotes ​

inRoom ​

loadDefinition ​

pending ​

vote ​

voteImages ​

Events ​

onImageVote ​

onRoomPolls ​

onTab ​

onVote ​

polls.screens ​

closeImagePoll ​

closePoll ​

imagePoll ​

openImagePoll ​

openPoll ​

poll ​

onChange ​

onStep ​

Types ​

RoomPoll ​

PollDefinition ​

PollVote ​

PollSetUp ​

ActOptions ​

PollVoteSent ​

ImageVoteSent ​

PollTab ​

PollVoteHeard ​

ImageVoteHeard ​

PollWindow ​

ImagePollWindow ​

OpenImagePollOptions ​

PollScreens ​

PollStep ​

Polls

Overview

Methods

`answered`

`definition`

`imageVotes`

`inRoom`

`loadDefinition`

`pending`

`vote`

`voteImages`

Events

`onImageVote`

`onRoomPolls`

`onTab`

`onVote`

`polls.screens`

`closeImagePoll`

`closePoll`

`imagePoll`

`openImagePoll`

`openPoll`

`poll`

`onChange`

`onStep`

Types

`RoomPoll`

`PollDefinition`

`PollVote`

`PollSetUp`

`ActOptions`

`PollVoteSent`

`ImageVoteSent`

`PollTab`

`PollVoteHeard`

`ImageVoteHeard`

`PollWindow`

`ImagePollWindow`

`OpenImagePollOptions`

`PollScreens`

`PollStep`