How assets load

phantom.aj.assetsHow assets load

The client's art and media.

Scripts and plugins

A script has all of it, as phantom.aj.assets, 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
copy()	A copy of one media asset of the game's own, loaded afresh through the client's own loader (MediaHelper.init) and kept, for a feature to take its clips from and put on the screen: a second instance of a window's own art, built in the game's memory, nothing of it shipped.	game:read
defPack()	Fetches one of the game's data packs (DefPacksDefHelper.init), as a room or a screen does the first time it needs one, and resolves with the pack as the client parsed it, as plain data: its shape is the pack's own.	game:act
media()	Loads one media asset by id through the client's own loader (MediaHelper.init), as a popup's art or a poll's picture is, and resolves with what it is: its class, frames and size.	game:act
picture()	A picture of one media asset, as a PNG data URL: loaded through the client's own loader, drawn off screen (phantom.flash.snapshot) and let go of.	game:read
url()	The address the client would load an asset from (LoaderCache.fetchCDNURL), for an asset as the client names it (assets/rooms/room_jamaa.swf).	game:read
versions()	The deploy and build versions every asset address is built with (LoaderCache).	game:read
waitFor()	Waits for one file to come in, by the id it was asked for, and resolves with how it went: a failure resolves too, with success false.	game:read
onLoaded()	Hears every file any of the client's file servers reports in (BaseFileServer.newEvent): media, def packs, den items, feedback art, masterpieces, facts and polls, failed ones too.	game:read

Methods

copy

methodplugins · game:read

copy(mediaId: number, options?: ActOptions) => Promise<MediaCopy>

A copy of one media asset of the game's own, loaded afresh through the client's own loader (MediaHelper.init) and kept, for a feature to take its clips from and put on the screen: a second instance of a window's own art, built in the game's memory, nothing of it shipped. The copy is the asset's own top clip (as MediaHelper calls back with it), on no display list, its text localized as the client localizes every asset it loads. It stays alive until released; what was taken out of it and put somewhere stays where it was put. REFUSED for an id the file server could not load, TIMEOUT when it does not come.

Parameters

Name	Type
mediaId	number
options optional	ActOptions

Returns

Promise<MediaCopy>

Types

MediaCopy · ActOptions

Example

const copy = await phantom.aj.assets.copy(4620);
const card = await copy.content.at('getChildAt').call(0);
await copy.release();

Run in Phantom

defPack

methodplugins · game:act

defPack(pack: DefPackId, options?: ActOptions) => Promise<unknown>

Fetches one of the game's data packs (DefPacksDefHelper.init), as a room or a screen does the first time it needs one, and resolves with the pack as the client parsed it, as plain data: its shape is the pack's own. The client answers again from its cache. REFUSED when the file server reports the fetch failed, which the client itself never answers.

Parameters

Name	Type
pack	DefPackId
options optional	ActOptions

Returns

Promise<unknown>

Types

DefPackId · ActOptions

media

methodplugins · game:act

media(mediaId: number, options?: ActOptions) => Promise<LoadedMedia>

Loads one media asset by id through the client's own loader (MediaHelper.init), as a popup's art or a poll's picture is, and resolves with what it is: its class, frames and size. It is let go of after: for finding out what an id is, not for drawing it (picture draws). REFUSED for an id the file server could not load.

Parameters

Name	Type
mediaId	number
options optional	ActOptions

Returns

Promise<LoadedMedia>

Types

LoadedMedia · ActOptions

picture

methodplugins · game:read

picture(mediaId: number, options?: MediaPictureOptions) => Promise<string>

A picture of one media asset, as a PNG data URL: loaded through the client's own loader, drawn off screen (phantom.flash.snapshot) and let go of. A moving asset is drawn as its first frame. Nothing is kept: keep the string where it is wanted again.

Parameters

Name	Type
mediaId	number
options optional	MediaPictureOptions

Returns

Promise<string>

Types

MediaPictureOptions

Example

const url = await phantom.aj.assets.picture(1678, { maxSize: 256 });

Run in Phantom

url

methodplugins · game:read

url(assetPath: string, options?: { cdnRoot?: string | undefined; versioned?: boolean | undefined; }) => Promise<string | null>

The address the client would load an asset from (LoaderCache.fetchCDNURL), for an asset as the client names it (assets/rooms/room_jamaa.swf). Only the client can make it: every name is hashed first. Nothing is fetched. An asset phantom.aj.content has replaced answers with Phantom's address for it. Null where the client cannot build one.

Parameters

Name	Type
assetPath	string
options optional	{ cdnRoot?: string | undefined; versioned?: boolean | undefined; }

Returns

Promise<string \| null>

Example

const address = await phantom.aj.assets.url('assets/rooms/room_jamaa.swf');
if (address) await phantom.aj.content.replace(new URL(address).pathname, '/home/me/jamaa.swf');

Run in Phantom

versions

methodplugins · game:read

versions() => Promise<AssetVersions>

The deploy and build versions every asset address is built with (LoaderCache).

Returns

Promise<AssetVersions>

Types

AssetVersions

waitFor

methodplugins · game:read

waitFor(id: string | number, options?: ActOptions) => Promise<LoadedFile>

Waits for one file to come in, by the id it was asked for, and resolves with how it went: a failure resolves too, with success false. TIMEOUT when nothing with that id comes. Start waiting before asking for the file.

Parameters

Name	Type
id	string | number
options optional	ActOptions

Returns

Promise<LoadedFile>

Types

LoadedFile · ActOptions

Example

const arriving = phantom.aj.assets.waitFor(1678);
await phantom.aj.assets.media(1678).catch(() => undefined);
console.log((await arriving).success);

Run in Phantom

Events

onLoaded

eventplugins · game:read

onLoaded(listener: (file: LoadedFile) => void) => () => void

Hears every file any of the client's file servers reports in (BaseFileServer.newEvent): media, def packs, den items, feedback art, masterpieces, facts and polls, failed ones too. The bytes are not handed over, only what finished and how.

Parameters

Name	Type
listener	(file: LoadedFile) => void

Returns

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

Types

LoadedFile

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.

AssetVersions

The two versions every asset address is built with.

Field	Type
deploy	string | null	The folder Animal Jam's content lives under (/content/<deploy>/); 0 for a local build.
build	string | null	The ?v= every address is stamped with as a cache buster.

DefPackId

A def pack by name, or by the pack's own number for one not named.

type DefPackId = keyof typeof DEF_PACK_IDS | 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

LoadedMedia

One of the game's media assets, loaded to see what it is.

Field	Type
mediaId	number
className	string	The class Flash made it as, such as flash.display::MovieClip.
totalFrames	number	How many frames it has: 1 for a still.
width	number
height	number

MediaPictureOptions

How picture draws a media asset, as phantom.flash.snapshot takes it.

type MediaPictureOptions = ActOptions & {
  /** How much bigger or smaller than its own size: 1 by default. */
  scale?: number;
  /** A colour behind it, or null (the default) for nothing. */
  background?: number | null;
  /** The most pixels on a side, which the scale is cut down to fit. */
  maxSize?: number;
}

LoadedFile

One file a file server reported in (BaseFileServer.newEvent).

Field	Type
id	string | number	What it was asked for by: a media id, a def pack id or a path, by which server it was.
success	boolean	Whether it loaded. A failure is reported nowhere else.
contentType	number | null	The file server's content type code, or null where it gave none.

MediaCopy

A media asset's own copy, from phantom.aj.assets.copy, alive until released.

Field	Type
mediaId	number
content	FlashHandle	The asset's top clip, as the client's MediaHelper calls back with it.
release	() => Promise<void>	Lets the copy go; what was taken out of it and put on the screen stays. Safe to call twice.