Masterpieces

phantom.aj.masterpiecesThings you own

Masterpieces: in dens, their creators, likes and previews.

Scripts and plugins

A script has all of it, as phantom.aj.masterpieces, 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
`closePreview()`	Closes the client's masterpiece preview (`closeMasterpiecePreview`).	`game:act`
`creatorOf()`	Who drew a masterpiece, by their account name (`requestDenMasterpieceCreatorName`, `dmc`).	`game:act`
`inDen()`	Every masterpiece in someone's den (`requestDenMasterpieceItems`, `dmi`), approved by Animal Jam or not (`approved`).	`game:act`
`isPreviewing()`	Whether the client's masterpiece preview is up.	`game:read`
`like()`	Likes a masterpiece as the player (`sendResourceArrayPutRequest`, `crp`), as the heart in its preview does.	`game:act`
`likes()`	How many have liked a masterpiece and whether the player has (`sendResourceArrayGetRequest`, `crg`), as its preview asks.	`game:act`
`picture()`	The drawing itself as a PNG `data:` URL, loaded the way a den loads it (`loader.MasterpieceDefHelper`, over `MasterpieceFileServer`), off screen, and the helper put away after.	`game:read`
`preview()`	Opens a masterpiece in the client's own preview, as clicking it in a den does (`GuiManager.openMasterpiecePreview`): the drawing in its frame, its creator, its likes and heart, and the report button.	`game:act`
`onCreator()`	Hears every masterpiece's creator the server names (`dmc`), whoever asked.	`game:read`
`onLiked()`	Hears every like the player gives a masterpiece taken (`crp`), whoever gave it.	`game:read`
`onLikes()`	Hears every masterpiece's likes the server gives (`crg`), whoever asked; walls' are not told.	`game:read`
`onList()`	Hears every den's masterpieces the server lists (`dmi`), whoever asked: `inDen`, a den loading its art, a wall.	`game:read`

Methods

`closePreview`

methodplugins · game:act

TypeScript

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

Closes the client's masterpiece preview (closeMasterpiecePreview).

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions

`creatorOf`

methodplugins · game:act

TypeScript

creatorOf(denUserName: string, uniqueImageId: string, options?: ActOptions) => Promise<string>

Who drew a masterpiece, by their account name (requestDenMasterpieceCreatorName, dmc).

Parameters

Name	Type
`denUserName`	`string`
`uniqueImageId`	`string`
`options` optional	`ActOptions`

Returns

Promise<string>

Types

ActOptions

`inDen`

methodplugins · game:act

TypeScript

inDen(userName: string, options?: ActOptions) => Promise<DenMasterpieceItem[]>

Every masterpiece in someone's den (requestDenMasterpieceItems, dmi), approved by Animal Jam or not (approved).

Parameters

Name	Type
`userName`	`string`
`options` optional	`ActOptions`

Returns

Promise<DenMasterpieceItem[]>

Types

ActOptions · DenMasterpieceItem

`isPreviewing`

methodplugins · game:read

TypeScript

isPreviewing() => Promise<boolean>

Whether the client's masterpiece preview is up.

Returns

Promise<boolean>

`like`

methodplugins · game:act

TypeScript

like(masterpiece: MasterpieceRef, options?: ActOptions) => Promise<void>

Likes a masterpiece as the player (sendResourceArrayPutRequest, crp), as the heart in its preview does. It cannot be taken back. A drawing whose creator's account id is not above 0 is refused at once, since the client sends nothing for one.

Parameters

Name	Type
`masterpiece`	`MasterpieceRef`
`options` optional	`ActOptions`

Returns

Promise<void>

Types

MasterpieceRef · ActOptions

`likes`

methodplugins · game:act

TypeScript

likes(uniqueImageId: string, options?: ActOptions) => Promise<MasterpieceLikes>

How many have liked a masterpiece and whether the player has (sendResourceArrayGetRequest, crg), as its preview asks. REFUSED when the server cannot say.

Parameters

Name	Type
`uniqueImageId`	`string`
`options` optional	`ActOptions`

Returns

Promise<MasterpieceLikes>

Types

MasterpieceLikes · ActOptions

`picture`

methodplugins · game:read

TypeScript

picture(uniqueImageId: string, options?: MasterpiecePictureOptions) => Promise<string>

The drawing itself as a PNG data: URL, loaded the way a den loads it (loader.MasterpieceDefHelper, over MasterpieceFileServer), off screen, and the helper put away after. The frame around it in a den is the den item's, not part of this. An unapproved drawing still draws. TIMEOUT (20 seconds by default) is what a drawing the file server serves nothing for gives: it says no by never answering.

Parameters

Name	Type
`uniqueImageId`	`string`
`options` optional	`MasterpiecePictureOptions`

Returns

Promise<string>

Types

MasterpiecePictureOptions

`preview`

methodplugins · game:act

TypeScript

preview(denUserName: string, masterpiece: MasterpieceRef, options?: ActOptions) => Promise<void>

Opens a masterpiece in the client's own preview, as clicking it in a den does (GuiManager.openMasterpiecePreview): the drawing in its frame, its creator, its likes and heart, and the report button. The popup asks the server for the creator and likes itself. Resolves once the popup is up; any preview open before is closed first, as the client does.

Parameters

Name	Type
`denUserName`	`string`
`masterpiece`	`MasterpieceRef`
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions · MasterpieceRef

Events

`onCreator`

eventplugins · game:read

TypeScript

onCreator(listener: (creator: MasterpieceCreator) => void) => () => void

Hears every masterpiece's creator the server names (dmc), whoever asked.

Parameters

Name	Type
`listener`	`(creator: MasterpieceCreator) => void`

Returns

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

Types

MasterpieceCreator

`onLiked`

eventplugins · game:read

TypeScript

onLiked(listener: (uniqueImageId: string) => void) => () => void

Hears every like the player gives a masterpiece taken (crp), whoever gave it.

Parameters

Name	Type
`listener`	`(uniqueImageId: string) => void`

Returns

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

`onLikes`

eventplugins · game:read

TypeScript

onLikes(listener: (likes: MasterpieceLikesEvent) => void) => () => void

Hears every masterpiece's likes the server gives (crg), whoever asked; walls' are not told.

Parameters

Name	Type
`listener`	`(likes: MasterpieceLikesEvent) => void`

Returns

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

Types

MasterpieceLikesEvent

`onList`

eventplugins · game:read

TypeScript

onList(listener: (list: MasterpieceList) => void) => () => void

Hears every den's masterpieces the server lists (dmi), whoever asked: inDen, a den loading its art, a wall. The den is paired from the request each list answers, as the client pairs it.

Parameters

Name	Type
`listener`	`(list: MasterpieceList) => void`

Returns

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

Types

MasterpieceList

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.

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

`DenMasterpieceItem`

A masterpiece: a den item that carries a player drawn image, as masterpiece.MasterpieceDisplayItem loads it. Read from den/DenXtCommManager.as, denMasterpieceInventoryResponse, whose fields are always these seven regardless of the item's own definition (unlike di's den items, which the den item's own def pack shapes).

Field	Type
`defId`	`number`
`invIdx`	`number`	The item's place in that player's inventory.
`version`	`number`	Which of the item's looks is drawn, for a frame that has several.
`approved`	`boolean`	Whether Animal Jam has approved the drawing; an unapproved one is not shown to other players.
`uniqueImageId`	`string`	The id `loader.MasterpieceFileServer` loads the drawing's own image by.
`uniqueImageCreatorDbId`	`number`	The drawing's creator, by their account id.
`uniqueImageCreatorUUID`	`string`	The drawing's creator, by their account's uuid.

`MasterpieceLikes`

How many have liked a masterpiece, and whether the player has.

Field	Type
`count`	`number`
`liked`	`boolean`

`MasterpieceRef`

What like and preview need of a masterpiece: the fields inDen gives each one.

Field	Type
`uniqueImageId`	`string`	The id `loader.MasterpieceFileServer` loads the drawing's own image by.
`uniqueImageCreatorUUID`	`string`	The drawing's creator, by their account's uuid.
`uniqueImageCreatorDbId`	`number`	The drawing's creator, by their account id.
`version`	`number`	Which of the item's looks is drawn, for a frame that has several.

`MasterpiecePictureOptions`

TypeScript

type MasterpiecePictureOptions = ActOptions & {
  /** How much bigger or smaller than the drawing's own size; 1 when left out. */
  scale?: number;
  /** A colour behind it, or null (the default) for nothing. */
  background?: number | null;
  /** The most pixels on a side. */
  maxSize?: number;
}

`MasterpieceList`

Every masterpiece in a den, as the server lists them.

Field	Type
`userName`	`string \| null`	Whose den, from the request the list answers; null when that request was not heard.
`items`	`DenMasterpieceItem[]`

`MasterpieceCreator`

Who drew a masterpiece, as the server names them.

Field	Type
`denUserName`	`string \| null`	The den and the drawing asked about, from the request; null when it was not heard.
`uniqueImageId`	`string \| null`
`creatorName`	`string`

`MasterpieceLikesEvent`

A masterpiece's likes as the server gives them, whoever asked.

TypeScript

type MasterpieceLikesEvent = MasterpieceLikes & { uniqueImageId: string }

Masterpieces ​

Overview ​

Methods ​

closePreview ​

creatorOf ​

inDen ​

isPreviewing ​

like ​

likes ​

picture ​

preview ​

Events ​

onCreator ​

onLiked ​

onLikes ​

onList ​

Types ​

ActOptions ​

DenMasterpieceItem ​

MasterpieceLikes ​

MasterpieceRef ​

MasterpiecePictureOptions ​

MasterpieceList ​

MasterpieceCreator ​

MasterpieceLikesEvent ​

Masterpieces

Overview

Methods

`closePreview`

`creatorOf`

`inDen`

`isPreviewing`

`like`

`likes`

`picture`

`preview`

Events

`onCreator`

`onLiked`

`onLikes`

`onList`

Types

`ActOptions`

`DenMasterpieceItem`

`MasterpieceLikes`

`MasterpieceRef`

`MasterpiecePictureOptions`

`MasterpieceList`

`MasterpieceCreator`

`MasterpieceLikesEvent`