Animals on screen

phantom.aj.avatarsOther players

Everyone in the room, by user id: how they are drawn and how they move.

Scripts and plugins

A script has all of it, as phantom.aj.avatars, 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
adventurePlayers()	The players in the adventure the player is in (AvatarManager.adventurePlayerData).	game:read
all()	Every animal drawn in the room, the player's own included; none between rooms.	game:read
buddyCard()	Who the open buddy card shows (AvatarManager.buddyCardAvatarView), or null.	game:read
byName()	One animal by its player's account name or by its own name (either, any case), or null.	game:read
fetchAnimal()	One of a player's animals as the server has it, by account name and perUserAvId, through the client's own ask (AvatarXtCommManager.requestADForAvatar), which answers from the client's cache when it already has it.	game:act
get()	One animal by user id, or null when nobody by that id is drawn here.	game:read
kindDefault()	The look a kind of animal comes in before anyone dresses or paints it (AvatarManager.getDefaultAvatarByDefId), or null for a kind the client does not have.	game:read
lastSeen()	Where the client last saw each player, room by room, as it keeps it for the edge markers (AvatarManager.getOffScreenMap()): user id to room name to point.	game:read
lastSeenAt()	Where somebody was last seen in a room (the room the player is in by default), or null.	game:read
lookup()	Asks the server about a player, by account name or by user id in the room, and resolves with what it says: their current animal when they are online, null when there is no such player.	game:act
within()	The animals a circle at point touches, as the room's own hit test has it (AvatarWorldView.circleTest: the two circles meet), nearest first.	game:read
onLookup()	Hears every player lookup the server answers, the client's own and lookup's.	game:read

avatars.nameBars: The name bar over each animal in the room: phantom.aj.avatars.nameBars.

Member	What it does	Plugins
get()	Somebody's name bar as it is drawn, or null when they have none drawn here.	game:read
hide()	Hides somebody's name bar, kept hidden through the client's redraws, until undone.	game:act
redraw()	Draws the bar again: level for its level shape (updateNameBarLevelShape), packed for a colour and badge (toggleNamebarSelNub), neither for the nub alone.	game:act
refresh()	Writes the name again from what the client holds (updateNameBarName), and gives the bar.	game:act
setBadges()	Draws the bar as a member's or a guide's (_isMember, _isGuide), then rebuilds its level shape, which is what reads them.	game:act
setHealth()	Draws the health meter at percent (0 to 100) (updateNameBarHealth), and gives the bar.	game:act
setHostingTime()	Sets how long the client thinks a player has left hosting a party (UserInfo.timeLeftHostingCustomParty), which the room's heartbeat redraws the host tag from every ten seconds.	game:act
setPetName()	Writes a pet's name on the bar (Be Your Pet): _currPetName, then updateNameBarName.	game:act
showHostTag()	Shows or hides the party host tag (updateIsHostingCustomParty), and gives the bar.	game:act
onChange()	Hears somebody in the room change their name bar (an).	game:read

avatars.drawing: How animals in the room are drawn on this screen: phantom.aj.avatars.drawing.

Member	What it does	Plugins
attachment()	Holds a thing beside somebody, by media id (setAvAttachment, which loads its art), until undone.	game:act
bringToFront()	Puts somebody in front of the others, balloon and attachment too (moveToFront).	game:act
clearBubble()	Has somebody's chat balloon cleared at the client's next chance (setChatBalloonReadyForClear).	game:act
clearPattern()	Takes the special pattern off somebody (clearSpecialPattern).	game:act
colors()	Draws somebody in other colours (AvatarView.setAvtColors, the three packed colours), on this screen alone, until undone, which draws them in their own again.	game:act
glow()	A glow around somebody, following them through the room, until undone.	game:act
hide()	Hides somebody, kept hidden until undone.	game:act
hideOffScreenMarkers()	Hides every off-screen marker (AvatarManager.hideAllOffscreenViews).	game:act
inviteBubble()	Draws a custom adventure or PVP invite balloon over somebody (setCustomAdventureMessage).	game:act
offScreenMarker()	Tells somebody's off-screen marker what to do: be placed again, sleep, wake, or flash.	game:act
opacity()	Draws somebody at percent opacity (0 to 100), kept until undone.	game:act
petTrick()	Has somebody's pet hop or sparkle (AvatarManager.setPetAction).	game:act
phantom()	Draws somebody as a Phantom (AvatarWorldView.setAvatarAsPhantom), optionally as one of the client's other NPC definitions, until undone.	game:act
pinEmote()	Pins an emote beside the player (AvatarManager.setPlayerAttachmentEmot), for frames frames (2880 by default), and tells the room unless tell: false.	game:act
refreshParticles()	Works out somebody's particle trail again (setupParticles); redraw repaints the pattern.	game:act
reloadClothing()	Dresses somebody again from the clothing the client cached for them (reloadItemsFromCache).	game:act
reset()	Puts one piece of the room-wide drawing back, by the client's own call for it.	game:act
room()	The room-wide drawing the client keeps for the player alone, one message.	game:read
scale()	Draws somebody at scale times their size (one number, or across and down), until undone.	game:act
splash()	Has somebody stand in a liquid (setSplashVolumeVolume: water, mud, ice…), until undone.	game:act
tint()	Tints somebody (AvatarWorldView.setBlendColor): a colour, the outline colour (the room's own by default), until undone.	game:act

avatars.motion: How each animal in the room moves, what it plays and what is drawn about it: phantom.aj.avatars.motion.

Member	What it does	Plugins
actions()	The client's action table: what each action plays, for animals and for pets.	game:read
animation()	The animation somebody's view plays now, or null.	game:read
effects()	What is drawn over and around somebody (splash, particles, glow, balloon), or null.	game:read
frame()	Draws a frame of the animation (frame), or the next one (advanceFrame).	game:act
holdAnimation()	Pins somebody's view to one animation, so it plays no other (holdAnimId), until undone.	game:act
idleOf()	The standing animation somebody falls back to (getBaseIdle), and, given an angle, the idle the client turns that angle into (AvatarWorldView.convertToIdle).	game:read
movement()	The walk, jump, platform and slide somebody is in now, or null when nobody is drawn there.	game:read
pause()	Pauses the animation somebody's view plays where it is (pauseAnim), until undone.	game:act
playLanding()	Plays the landing effect under somebody (jumpLand).	game:act
preload()	Loads the art of animations for somebody's view (AvatarView.preloadAnims), resolving once the client says it is in.	game:act
queueCommand()	Queues a side-scrolling command for somebody (queueCommand), as adventures script them.	game:act
setAction()	Changes what an action plays for every animal (_actionLookup), until undone.	game:act
slide()	Slides somebody along a line of points (startSlide), as an adventure's slides do, optionally advanceMs into it.	game:act
onAnimation()	Hears every animation started on an animal (AvatarView.playAnim), anywhere in the room.	game:read
onIdle()	Hears an animal fall back to standing still (AvatarWorldView.playIdle), by user id.	game:read
onMovement()	Hears somebody's movement change: a walk starting or stopping, a jump, a platform, a slide.	game:read

Methods

adventurePlayers

methodplugins · game:read

adventurePlayers() => Promise<AdventurePlayer[]>

The players in the adventure the player is in (AvatarManager.adventurePlayerData).

Returns

Promise<AdventurePlayer[]>

Types

AdventurePlayer

all

methodplugins · game:read

all() => Promise<RoomAvatar[]>

Every animal drawn in the room, the player's own included; none between rooms. One message.

Returns

Promise<RoomAvatar[]>

Types

RoomAvatar · Point · Facing · NameBarData

buddyCard

methodplugins · game:read

buddyCard() => Promise<{ userName: string; avatarName: string | null; animalType: number | null; } | null>

Who the open buddy card shows (AvatarManager.buddyCardAvatarView), or null.

Returns

Promise<{ userName: string; avatarName: string \| null; animalType: number \| null; } \| null>

byName

methodplugins · game:read

byName(name: string, options?: { perUserAvId?: number | undefined; }) => Promise<RoomAvatar | null>

One animal by its player's account name or by its own name (either, any case), or null. Give perUserAvId to pick one of a player's animals.

Parameters

Name	Type
name	string
options optional	{ perUserAvId?: number | undefined; }

Returns

Promise<RoomAvatar \| null>

Types

RoomAvatar

fetchAnimal

methodplugins · game:act

fetchAnimal(userName: string, perUserAvId: number, options?: ActOptions) => Promise<FetchedAnimal>

One of a player's animals as the server has it, by account name and perUserAvId, through the client's own ask (AvatarXtCommManager.requestADForAvatar), which answers from the client's cache when it already has it. lookup is the player's current animal; this reaches any of them. Throws REFUSED when the client has no such animal.

Parameters

Name	Type
userName	string
perUserAvId	number
options optional	ActOptions

Returns

Promise<FetchedAnimal>

Types

FetchedAnimal · ActOptions

get

methodplugins · game:read

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

One animal by user id, or null when nobody by that id is drawn here.

Parameters

Name	Type
userId	number

Returns

Promise<RoomAvatar \| null>

Types

RoomAvatar

kindDefault

methodplugins · game:read

kindDefault(avTypeId: number, options?: { custom?: boolean | undefined; }) => Promise<{ animalType: number; customAvId: number | null; colors: number[]; } | null>

The look a kind of animal comes in before anyone dresses or paints it (AvatarManager.getDefaultAvatarByDefId), or null for a kind the client does not have.

Parameters

Name	Type
avTypeId	number
options optional	{ custom?: boolean | undefined; }

Returns

Promise<{ animalType: number; customAvId: number \| null; colors: number[]; } \| null>

lastSeen

methodplugins · game:read

lastSeen() => Promise<Map<number, Map<string, Point>>>

Where the client last saw each player, room by room, as it keeps it for the edge markers (AvatarManager.getOffScreenMap()): user id to room name to point.

Returns

Promise<Map<number, Map<string, Point>>>

Types

Point

lastSeenAt

methodplugins · game:read

lastSeenAt(userId: number, options?: { room?: string | undefined; }) => Promise<Point | null>

Where somebody was last seen in a room (the room the player is in by default), or null.

Parameters

Name	Type
userId	number
options optional	{ room?: string | undefined; }

Returns

Promise<Point \| null>

Types

Point

lookup

methodplugins · game:act

lookup(who: LookupTarget, options?: ActOptions) => Promise<LookedUpPlayer | null>

Asks the server about a player, by account name or by user id in the room, and resolves with what it says: their current animal when they are online, null when there is no such player. It goes through the client's own ask (requestAvatarGet, requestAvatarGetBySfsId), so the client caches the answer as it would for a player card.

Parameters

Name	Type
who	LookupTarget
options optional	ActOptions

Returns

Promise<LookedUpPlayer \| null>

Types

LookupTarget · ActOptions · LookedUpPlayer

Example

const pal = await phantom.aj.avatars.lookup('Sxip');
if (pal?.avatar) console.log(pal.avatar.avatarName, 'level', pal.avatar.questLevel);

Run in Phantom

within

methodplugins · game:read

within(point: Point, radius: number) => Promise<RoomAvatar[]>

The animals a circle at point touches, as the room's own hit test has it (AvatarWorldView.circleTest: the two circles meet), nearest first.

Parameters

Name	Type
point	Point
radius	number

Returns

Promise<RoomAvatar[]>

Types

RoomAvatar · Point

Events

onLookup

eventplugins · game:read

onLookup(listener: (player: LookedUpPlayer) => void) => () => void

Hears every player lookup the server answers, the client's own and lookup's.

Parameters

Name	Type
listener	(player: LookedUpPlayer) => void

Returns

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

Types

LookedUpPlayer

avatars.nameBars

The name bar over each animal in the room: phantom.aj.avatars.nameBars. Everything that draws changes it on this screen alone; nothing is sent. The player's own bar, as Animal Jam stores it, is phantom.aj.player.avatar.nameBar.

get

methodplugins · game:read

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

Somebody's name bar as it is drawn, or null when they have none drawn here.

Parameters

Name	Type
userId	number

Returns

Promise<DrawnNameBar \| null>

Types

DrawnNameBar · NameBarNub

hide

methodplugins · game:act

hide(userId: number, options?: ActOptions) => Promise<Undo>

Hides somebody's name bar, kept hidden through the client's redraws, until undone.

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<Undo>

Types

Undo · ActOptions

redraw

methodplugins · game:act

redraw(userId: number, change: { level?: number | undefined; packed?: number | undefined; }, options?: ActOptions) => Promise<DrawnNameBar>

Draws the bar again: level for its level shape (updateNameBarLevelShape), packed for a colour and badge (toggleNamebarSelNub), neither for the nub alone.

Parameters

Name	Type
userId	number
change	{ level?: number | undefined; packed?: number | undefined; }
options optional	ActOptions

Returns

Promise<DrawnNameBar>

Types

ActOptions · DrawnNameBar

refresh

methodplugins · game:act

refresh(userId: number, options?: ActOptions) => Promise<DrawnNameBar>

Writes the name again from what the client holds (updateNameBarName), and gives the bar.

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<DrawnNameBar>

Types

ActOptions · DrawnNameBar

setBadges

methodplugins · game:act

setBadges(userId: number, badges: { member?: boolean | undefined; guide?: boolean | undefined; }, options?: ActOptions) => Promise<DrawnNameBar>

Draws the bar as a member's or a guide's (_isMember, _isGuide), then rebuilds its level shape, which is what reads them.

Parameters

Name	Type
userId	number
badges	{ member?: boolean | undefined; guide?: boolean | undefined; }
options optional	ActOptions

Returns

Promise<DrawnNameBar>

Types

ActOptions · DrawnNameBar

setHealth

methodplugins · game:act

setHealth(userId: number, percent: number, options?: ActOptions) => Promise<DrawnNameBar>

Draws the health meter at percent (0 to 100) (updateNameBarHealth), and gives the bar.

Parameters

Name	Type
userId	number
percent	number
options optional	ActOptions

Returns

Promise<DrawnNameBar>

Types

ActOptions · DrawnNameBar

setHostingTime

methodplugins · game:act

setHostingTime(userName: string, seconds: number, options?: ActOptions) => Promise<number>

Sets how long the client thinks a player has left hosting a party (UserInfo.timeLeftHostingCustomParty), which the room's heartbeat redraws the host tag from every ten seconds. Throws REFUSED when the client holds no record of that player.

Parameters

Name	Type
userName	string
seconds	number
options optional	ActOptions

Returns

Promise<number>

Types

ActOptions

setPetName

methodplugins · game:act

setPetName(userId: number, name: string, options?: ActOptions & { petOnly?: boolean | undefined; }) => Promise<DrawnNameBar>

Writes a pet's name on the bar (Be Your Pet): _currPetName, then updateNameBarName.

Parameters

Name	Type
userId	number
name	string
options optional	ActOptions & { petOnly?: boolean | undefined; }

Returns

Promise<DrawnNameBar>

Types

ActOptions · DrawnNameBar

showHostTag

methodplugins · game:act

showHostTag(userId: number, hosting: boolean, options?: ActOptions) => Promise<DrawnNameBar>

Shows or hides the party host tag (updateIsHostingCustomParty), and gives the bar.

Parameters

Name	Type
userId	number
hosting	boolean
options optional	ActOptions

Returns

Promise<DrawnNameBar>

Types

ActOptions · DrawnNameBar

onChange

eventplugins · game:read

onChange(listener: (change: { userId: number; nameBar: NameBarData; }) => void) => () => void

Hears somebody in the room change their name bar (an).

Parameters

Name	Type
listener	(change: { userId: number; nameBar: NameBarData; }) => void

Returns

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

Types

NameBarData

avatars.drawing

How animals in the room are drawn on this screen: phantom.aj.avatars.drawing. Nothing here is sent to Animal Jam unless it says so; nobody else sees it.

A change that has to last resolves with a function that puts it back. Those that keep a value (opacity, hidden, scale) write it in the game every frame, following the player through the views the client builds them, so the client cannot put its own back.

const undo = await phantom.aj.avatars.drawing.opacity(userId, 30);

Run in Phantom

attachment

methodplugins · game:act

attachment(userId: number, mediaId: number, options?: ActOptions & { extra?: string | undefined; }) => Promise<Undo>

Holds a thing beside somebody, by media id (setAvAttachment, which loads its art), until undone. On this screen only; pinEmote is the player's own, which is sent.

Parameters

Name	Type
userId	number
mediaId	number
options optional	ActOptions & { extra?: string | undefined; }

Returns

Promise<Undo>

Types

ActOptions · Undo

bringToFront

methodplugins · game:act

bringToFront(userId: number, options?: ActOptions) => Promise<void>

Puts somebody in front of the others, balloon and attachment too (moveToFront).

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

clearBubble

methodplugins · game:act

clearBubble(userId: number, options?: ActOptions) => Promise<void>

Has somebody's chat balloon cleared at the client's next chance (setChatBalloonReadyForClear).

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

clearPattern

methodplugins · game:act

clearPattern(userId: number, options?: ActOptions) => Promise<void>

Takes the special pattern off somebody (clearSpecialPattern).

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

colors

methodplugins · game:act

colors(userId: number, colors: readonly [number, number, number], options?: ActOptions) => Promise<Undo>

Draws somebody in other colours (AvatarView.setAvtColors, the three packed colours), on this screen alone, until undone, which draws them in their own again.

Parameters

Name	Type
userId	number
colors	readonly [number, number, number]
options optional	ActOptions

Returns

Promise<Undo>

Types

ActOptions · Undo

glow

methodplugins · game:act

glow(userId: number, glow?: AvatarGlow, options?: ActOptions) => Promise<Undo>

A glow around somebody, following them through the room, until undone.

Parameters

Name	Type
userId	number
glow optional	AvatarGlow
options optional	ActOptions

Returns

Promise<Undo>

Types

AvatarGlow · ActOptions · Undo

hide

methodplugins · game:act

hide(userId: number, options?: ActOptions) => Promise<Undo>

Hides somebody, kept hidden until undone. Their balloon and pet are drawn apart from them.

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<Undo>

Types

ActOptions · Undo

hideOffScreenMarkers

methodplugins · game:act

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

Hides every off-screen marker (AvatarManager.hideAllOffscreenViews).

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

inviteBubble

methodplugins · game:act

inviteBubble(userId: number, invite: { info: string; message: string; difficulty?: number | undefined; severity?: number | undefined; pvp?: boolean | undefined; }, options?: ActOptions) => Promise<void>

Draws a custom adventure or PVP invite balloon over somebody (setCustomAdventureMessage).

Parameters

Name	Type
userId	number
invite	{ info: string; message: string; difficulty?: number | undefined; severity?: number | undefined; pvp?: boolean | undefined; }
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

offScreenMarker

methodplugins · game:act

offScreenMarker(userId: number, what: OffScreenMarker, options?: ActOptions) => Promise<void>

Tells somebody's off-screen marker what to do: be placed again, sleep, wake, or flash.

Parameters

Name	Type
userId	number
what	OffScreenMarker
options optional	ActOptions

Returns

Promise<void>

Types

OffScreenMarker · ActOptions

opacity

methodplugins · game:act

opacity(userId: number, percent: number, options?: ActOptions) => Promise<Undo>

Draws somebody at percent opacity (0 to 100), kept until undone. Not sent.

Parameters

Name	Type
userId	number
percent	number
options optional	ActOptions

Returns

Promise<Undo>

Types

ActOptions · Undo

petTrick

methodplugins · game:act

petTrick(userId: number, trick: "hop" | "sparkle", options?: ActOptions & { sparkleId?: number | undefined; }) => Promise<void>

Has somebody's pet hop or sparkle (AvatarManager.setPetAction). Throws when they have none.

Parameters

Name	Type
userId	number
trick	"hop" | "sparkle"
options optional	ActOptions & { sparkleId?: number | undefined; }

Returns

Promise<void>

Types

ActOptions

phantom

methodplugins · game:act

phantom(userId: number, options?: ActOptions & { npcDefId?: number | undefined; }) => Promise<Undo>

Draws somebody as a Phantom (AvatarWorldView.setAvatarAsPhantom), optionally as one of the client's other NPC definitions, until undone. Resolves once the client draws them as one.

Parameters

Name	Type
userId	number
options optional	ActOptions & { npcDefId?: number | undefined; }

Returns

Promise<Undo>

Types

ActOptions · Undo

pinEmote

methodplugins · game:act

pinEmote(defId: number, options?: ActOptions & { extra?: string | undefined; frames?: number | undefined; tell?: boolean | undefined; }) => Promise<void>

Pins an emote beside the player (AvatarManager.setPlayerAttachmentEmot), for frames frames (2880 by default), and tells the room unless tell: false.

Parameters

Name	Type
defId	number
options optional	ActOptions & { extra?: string | undefined; frames?: number | undefined; tell?: boolean | undefined; }

Returns

Promise<void>

Types

ActOptions

refreshParticles

methodplugins · game:act

refreshParticles(userId: number, options?: ActOptions & { redraw?: boolean | undefined; }) => Promise<void>

Works out somebody's particle trail again (setupParticles); redraw repaints the pattern.

Parameters

Name	Type
userId	number
options optional	ActOptions & { redraw?: boolean | undefined; }

Returns

Promise<void>

Types

ActOptions

reloadClothing

methodplugins · game:act

reloadClothing(userId: number, options?: ActOptions) => Promise<void>

Dresses somebody again from the clothing the client cached for them (reloadItemsFromCache).

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

reset

methodplugins · game:act

reset(what: RoomDrawingReset, options?: ActOptions) => Promise<void>

Puts one piece of the room-wide drawing back, by the client's own call for it.

Parameters

Name	Type
what	RoomDrawingReset
options optional	ActOptions

Returns

Promise<void>

Types

RoomDrawingReset · ActOptions

room

methodplugins · game:read

room() => Promise<RoomDrawing>

The room-wide drawing the client keeps for the player alone, one message.

Returns

Promise<RoomDrawing>

Types

RoomDrawing

scale

methodplugins · game:act

scale(userId: number, scale: number | Point, options?: ActOptions) => Promise<Undo>

Draws somebody at scale times their size (one number, or across and down), until undone.

Parameters

Name	Type
userId	number
scale	number | Point
options optional	ActOptions

Returns

Promise<Undo>

Types

Point · ActOptions · Undo

splash

methodplugins · game:act

splash(userId: number, liquid: string, options?: ActOptions & { flipped?: boolean | undefined; }) => Promise<Undo>

Has somebody stand in a liquid (setSplashVolumeVolume: water, mud, ice…), until undone. The room sets it again as they walk into and out of its splash volumes.

Parameters

Name	Type
userId	number
liquid	string
options optional	ActOptions & { flipped?: boolean | undefined; }

Returns

Promise<Undo>

Types

ActOptions · Undo

tint

methodplugins · game:act

tint(userId: number, color: number, options?: ActOptions & { outline?: number | undefined; }) => Promise<Undo>

Tints somebody (AvatarWorldView.setBlendColor): a colour, the outline colour (the room's own by default), until undone. The client tints too, for splash volumes, and may draw over it.

Parameters

Name	Type
userId	number
color	number
options optional	ActOptions & { outline?: number | undefined; }

Returns

Promise<Undo>

Types

ActOptions · Undo

avatars.motion

How each animal in the room moves, what it plays and what is drawn about it: phantom.aj.avatars.motion. None of it is the server's: the room hears where an animal ended up, never how it got there, so all of it is this screen's.

actions

methodplugins · game:read

actions() => Promise<{ animal: ActionAnims[]; pet: { name: string; animation: number; }[]; }>

The client's action table: what each action plays, for animals and for pets.

Returns

Promise<{ animal: ActionAnims[]; pet: { name: string; animation: number; }[]; }>

animation

methodplugins · game:read

animation(userId: number) => Promise<AvatarAnimationState | null>

The animation somebody's view plays now, or null.

Parameters

Name	Type
userId	number

Returns

Promise<AvatarAnimationState \| null>

Types

AvatarAnimationState

effects

methodplugins · game:read

effects(userId: number) => Promise<AvatarEffects | null>

What is drawn over and around somebody (splash, particles, glow, balloon), or null.

Parameters

Name	Type
userId	number

Returns

Promise<AvatarEffects \| null>

Types

AvatarEffects

frame

methodplugins · game:act

frame(userId: number, frame: number | "next", options?: ActOptions) => Promise<number>

Draws a frame of the animation (frame), or the next one (advanceFrame). Resolves with it.

Parameters

Name	Type
userId	number
frame	number | "next"
options optional	ActOptions

Returns

Promise<number>

Types

ActOptions

holdAnimation

methodplugins · game:act

holdAnimation(userId: number, animation: number, options?: ActOptions) => Promise<Undo>

Pins somebody's view to one animation, so it plays no other (holdAnimId), until undone.

Parameters

Name	Type
userId	number
animation	number
options optional	ActOptions

Returns

Promise<Undo>

Types

ActOptions · Undo

idleOf

methodplugins · game:read

idleOf(userId: number, options?: { angle?: number | undefined; }) => Promise<{ base: number; forAngle: { animation: number; flipped: boolean; } | null; } | null>

The standing animation somebody falls back to (getBaseIdle), and, given an angle, the idle the client turns that angle into (AvatarWorldView.convertToIdle).

Parameters

Name	Type
userId	number
options optional	{ angle?: number | undefined; }

Returns

Promise<{ base: number; forAngle: { animation: number; flipped: boolean; } \| null; } \| null>

movement

methodplugins · game:read

movement(userId: number) => Promise<AvatarMovement | null>

The walk, jump, platform and slide somebody is in now, or null when nobody is drawn there.

Parameters

Name	Type
userId	number

Returns

Promise<AvatarMovement \| null>

Types

AvatarMovement

pause

methodplugins · game:act

pause(userId: number, options?: ActOptions) => Promise<Undo>

Pauses the animation somebody's view plays where it is (pauseAnim), until undone.

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<Undo>

Types

ActOptions · Undo

playLanding

methodplugins · game:act

playLanding(userId: number, options?: ActOptions) => Promise<void>

Plays the landing effect under somebody (jumpLand).

Parameters

Name	Type
userId	number
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

preload

methodplugins · game:act

preload(userId: number, animations: readonly number[], options?: ActOptions) => Promise<void>

Loads the art of animations for somebody's view (AvatarView.preloadAnims), resolving once the client says it is in.

Parameters

Name	Type
userId	number
animations	readonly number[]
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

queueCommand

methodplugins · game:act

queueCommand(userId: number, command: readonly (string | number)[], options?: ActOptions) => Promise<void>

Queues a side-scrolling command for somebody (queueCommand), as adventures script them.

Parameters

Name	Type
userId	number
command	readonly (string | number)[]
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

setAction

methodplugins · game:act

setAction(name: string, animation: ActionAnimation, options?: ActOptions) => Promise<Undo>

Changes what an action plays for every animal (_actionLookup), until undone. Throws REFUSED for an action the table has no row for.

Parameters

Name	Type
name	string
animation	ActionAnimation
options optional	ActOptions

Returns

Promise<Undo>

Types

ActionAnimation · ActOptions · Undo

slide

methodplugins · game:act

slide(userId: number, points: readonly Point[], options?: ActOptions & { advanceMs?: number | undefined; }) => Promise<void>

Slides somebody along a line of points (startSlide), as an adventure's slides do, optionally advanceMs into it. Resolves once the slide is under way.

Parameters

Name	Type
userId	number
points	readonly Point[]
options optional	ActOptions & { advanceMs?: number | undefined; }

Returns

Promise<void>

Types

Point · ActOptions

onAnimation

eventplugins · game:read

onAnimation(listener: (animation: AvatarAnimation) => void) => () => void

Hears every animation started on an animal (AvatarView.playAnim), anywhere in the room.

Parameters

Name	Type
listener	(animation: AvatarAnimation) => void

Returns

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

Types

AvatarAnimation

onIdle

eventplugins · game:read

onIdle(listener: (userId: number | null) => void) => () => void

Hears an animal fall back to standing still (AvatarWorldView.playIdle), by user id.

Parameters

Name	Type
listener	(userId: number | null) => void

Returns

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

onMovement

eventplugins · game:read

onMovement(userId: number, listener: (movement: AvatarMovement | null) => void, options?: { everyFrames?: number | undefined; }) => () => void

Hears somebody's movement change: a walk starting or stopping, a jump, a platform, a slide. Read in the game every everyFrames frames (3 by default); told with null when they go. A watch ends with the client, so listen again after a reload.

Parameters

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

Returns

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

Types

AvatarMovement

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.

RoomAvatar

One animal in the room, as this screen draws it.

Field	Type
userId	number	The SmartFox user id the room's packets name the player by.
userName	string
avatarName	string | null
animalType	number | null	Which kind of animal (avTypeId), and the recycled kind when it is one.
customAvId	number | null
perUserAvId	number | null	Which of the player's animals this is, and its slot.
avInvId	number | null
uuid	string | null	The account's uuid, when the client has it for this animal.
colors	[number, number, number] | null	The three packed colours it is drawn in.
enviroTypeFlag	number | null	The animal's environment flag (land, ocean, air bits).
position	Point
facing	Facing
moving	boolean	In the middle of a walk or a slide.
radius	number	How wide it is for the room's own hit tests.
environment	"land" | "water" | null	Whether the client draws it for land or for water.
idle	{ animation: number; flipped: boolean; }	The idle it last fell back to.
attachment	number | null	What is held beside it, by media id; null when nothing is.
emote	number | null	The emote pinned over it, by media id; null for none.
level	number	Its adventure level, from the shape on its name bar; 0 where it has none.
health	number | null	How wide its name bar's health is drawn; null where the bar has no meter.
isPhantom	boolean
switching	boolean	The player behind it is changing animals.
offScreen	boolean	Drawn as an edge marker rather than in the room.
splashing	string | null	The liquid it stands in, or null.
isMember	boolean
isGuide	boolean
nameBar	NameBarData | null	The name bar, as packed; null before the client drew one.
isSelf	boolean	The player's own animal.

Point

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

Field	Type
x	number
y	number

Facing

Which way an animal faces.

type Facing = 'left' | 'right'

NameBarData

What a name bar's packed number says (NameBar.setColorAndBadge).

Field	Type
packed	number	The number itself, as nameBarData carries it.
color	number	The colour the player chose, 0 to 9: the low byte.
badge	number	The badge, by its definition id: the second byte, plus one.
showsLevel	boolean	Whether the bar shows the adventure level: bits 16 to 19 are clear.

AdventurePlayer

A player in the adventure the player is in, as the client keeps them.

Field	Type
userId	number
userName	string | null
avatarName	string | null
isMember	boolean
nameBar	NameBarData

LookupTarget

Who to look up: an account name, or somebody's user id in the room.

type LookupTarget = string | { userId: 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

LookedUpPlayer

A player as the server describes them when looked up (ag).

Field	Type
userName	string
uuid	string
online	boolean	Status 0 or 1. An offline player (2) has no avatar.
avatar	{ userId: number; avatarName: string; animalType: number; customAvId: number; perUserAvId: number; avInvId: number; colors: [number, number, number]; accountType: number; isMember: boolean; isGuide: boolean; daysSinceLastLogin: number; nameBar: NameBarData; eyes: number; pattern: number; questLevel: number; nameShown: boolean; pet: { lBits: number; uBits: number; eBits: number; name: string; } | null; items: { defId: number; color: number; }[]; } | null

FetchedAnimal

One of a player's animals, as fetchAnimal has it from the server.

Field	Type
userName	string
uuid	string | null
perUserAvId	number
avInvId	number | null
avatarName	string | null
animalType	number | null
customAvId	number | null
colors	[number, number, number]

DrawnNameBar

The name bar over an animal, as it is drawn.

type DrawnNameBar = NameBarData & {
  userId: number;
  /** The name written on it, which is the moderated name for somebody who has one. */
  name: string | null;
  visible: boolean;
  nub: NameBarNub;
  /** Whether the badge is the VIP one (`NameBar.isVIPBadge`). */
  vipBadge: boolean;
  /** The adventure level its shape shows, 0 where it has none. */
  level: number;
  /** How wide the health bar is drawn, null where there is no meter. */
  meter: number | null;
  /** How many icons are along it. */
  icons: number;
  blocked: boolean;
  hostingParty: boolean;
}

NameBarNub

type NameBarNub = 'buddy' | 'nonBuddy' | 'guide' | null

Undo

A drawn change that lasts until this is called, which puts back what was there.

type Undo = () => Promise<void>

AvatarGlow

A glow around an animal, as phantom.flash.highlight draws one.

Field	Type
color optional	number | undefined	The glow's colour. A glow is drawn unless glow is false or another effect is asked for alone.
strength optional	number | undefined	How strong the glow is: 2 by default.
blur optional	number | undefined	How far the glow spreads, in pixels: 8 by default.
alpha optional	number | undefined
inner optional	boolean | undefined	Glow inside the object's edges rather than around them.
knockout optional	boolean | undefined	Only the glow, without the object.
pulse optional	boolean | { frames?: number | undefined; from?: number | undefined; to?: number | undefined; } | undefined	Fade in and out: true for a gentle pulse (from 60% to full strength and back every two and a half seconds), or how: frames for one cycle at the game's 24 a second, from and to as fractions of the glow.

OffScreenMarker

What the off-screen marker for an animal is told to do.

type OffScreenMarker = 'refresh' | 'sleeping' | 'awake' | 'flash'

RoomDrawing

What the client is drawing for the player alone, room-wide (AvatarManager).

Field	Type
splash	{ colour: number; lastColour: number; level: number; levelMax: number; countdown: number; }	The colour a splash volume tints the player, and how strongly (0 to 255).
alpha	{ now: number; last: number; countdown: number; }	How solid the player is drawn, 0 to 100. These are sent to the room on a throttle.
throttle	{ colour: number; position: number; }	Frames before the client may tell the room the colour again, and send positions.
positions	{ queued: number; lastSent: Point | null; sentThisRun: boolean; animation: number; }	Positions waiting to go out as one au, and the last one sent.
attachmentEmote	{ defId: number | null; extra: string | null; }	The emote attachment pinned to the player, by def id (null for none), and its text.
pet	{ sparkleId: number; needsReset: boolean; }
environment	{ now: number; previous: number; }	0 land, 1 ocean: this room's and the one before.
waitingForLanguagePack	boolean
inPreviewRoom	boolean

RoomDrawingReset

What reset puts back, each by the client's own call.

type RoomDrawingReset = | 'splashColour'
  /** `resetThrottle`: the next move goes out at once. */
  | 'positionThrottle'
  /** `updateAvatarNameBarNames`: every name bar, from the names the client holds. */
  | 'nameBars'
  /** `updateEmitParticles`: whether each animal emits particles. */
  | 'particles'
  /** `setupActivePet`: the pet beside the player. */
  | 'pet'
  /** `updateCustomPartyHostingDataForMyself`: the party hosting the client tells the room. */
  | 'hosting'
  /** `resetCustomAdventureState`: the custom adventure the client thinks the player hosts. */
  | 'customAdventure'
  /** `finishHandleAvatarCreate`: the avatars held back for the language pack. */
  | 'waitingAvatars'

AvatarMovement

The walk, jump, platform and slide the client is in the middle of for one animal.

Field	Type
userId	number
moving	number	The client's own moving flag: 1 walking, 0 standing, -1 starting a path.
moveTo	Point
step	Point	The step it takes each frame.
pathLength	number	Points left on the path it follows.
lastMoveAngle	number
frameTime	number
framesOffScreen	number
deleteOnMoveComplete	boolean	The client takes the view away once this walk ends.
jump	{ jumping: boolean; falling: boolean; velocity: number; enabled: boolean; fallsThrough: boolean; landType: string | null; bouncing: boolean; }
onLadder	boolean
leap	{ state: number; frames: number; }
platform	{ on: boolean; direction: number; velocity: number; startedAt: Point; isActor: boolean; }
sideScroll	{ mouseMovement: boolean; arrowEnabled: boolean; targetX: number; state: number; previousDirection: number; }
slide	{ at: number; frameTime: number; points: number; spin: number; }	The slide: which point (-1 for none), time into it, its points and spin.
commandsQueued	number
commandRunning	boolean
scale	Point

AvatarEffects

What the client draws over and around one animal, on this screen only.

Field	Type
userId	number
splash	{ inVolume: boolean; liquid: string | null; message: string | null; drawn: boolean; }
particles	{ emits: boolean; sinceLast: number; lastAt: Point; offset: number; }
pattern	{ index: number; colours: number; }
glowing	boolean
loadingEmote	number | null	The emote whose art is loading, by media id; null for none.
pet	{ name: string | null; only: boolean; }
attachmentExtra	string | null
sinceHostingUpdate	number
hasPhantomView	boolean
balloon	{ shown: boolean; text: string | null; }

AvatarAnimationState

The animation one animal's view plays now (AvatarView).

Field	Type
userId	number
animation	number
frame	number
flipped	boolean
heldAnimation	number	The animation the view is pinned to; 0 when it plays whatever it is told.
lastWanted	number
offScreen	boolean
skipsEnvironmentCheck	boolean
items	{ shown: number; bodyMods: number; clothing: number; }

AvatarAnimation

An animation started on an animal in the room.

Field	Type
userId	number | null	Whose; null for a view with no player behind it (a window's, a card's).
animation	number
flipped	boolean

ActionAnimation

What an action plays, as setAction writes it.

Field	Type
land	number
water	number
flipped optional	boolean | undefined