The Jamaa Journal

phantom.aj.newspaperYou and your animal

The Jamaa Journal.

Scripts and plugins

A script has all of it, as phantom.aj.newspaper, 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
available()	The issues the Journal would show this player, in its strip's order (0 is the newest): the ones the server lists as printed now (generic list 627, which the client caches), sifted as the popup sifts them by country, membership and date.	game:read
close()	Closes the Journal as its close button does (NewspaperPopup.destroy).	game:act
hasSeenFirstPage()	Whether the player has opened the Journal this sitting, or the client opened it for them at login (NewspaperManager.hasSeenFirstPage).	game:read
hasUnseenPages()	Whether the HUD shows its "new issue" burst (NewspaperManager.hasUnseenPages).	game:read
isOpen()	Whether the Journal's popup is on screen.	game:read
issue()	One issue by its def id, from the defs the client holds (getNewspaperDef), in one read.	game:read
issues()	Every issue the Journal has ever printed, in the def pack's order.	game:act
markSeen()	Marks an issue seen, as the popup does when it turns to a new page (sendSetPageSeenRequest, nps), and resolves with when the server marked it.	game:act
open()	Opens the Journal as the HUD's button does (openNewspaperPopup), and resolves once its art and strip are up with the page it shows: null for a Journal with nothing for this player.	game:act
reading()	The issue the open Journal shows, and its page in the strip (NewspaperPopup._currSelectedPage); null when the Journal is not open or has not laid out its strip yet.	game:read
seenAt()	When the player last read an issue, in seconds since the epoch (getNewspaperData), or null for one never marked seen.	game:read
setUnseenPages()	Lights or puts out the HUD's "new issue" burst and redraws the button from it (GuiManager.onMyUserVarsReceived).	game:act
turnTo()	Turns the open Journal to a page of its strip (0 is the newest, in available's order), as its arrows and icons do: the strip scrolls to it and its icon is pressed, which loads the page.	game:act
onOpenChange()	Hears the Journal's popup asked up (true) and taken down (false), whoever did it.	game:read
onPageSeen()	Hears every issue marked seen (nps), whoever asked: markSeen or the popup's page turn.	game:read

Methods

available

methodplugins · game:read

available(options?: ActOptions) => Promise<NewspaperIssue[]>

The issues the Journal would show this player, in its strip's order (0 is the newest): the ones the server lists as printed now (generic list 627, which the client caches), sifted as the popup sifts them by country, membership and date. turnTo counts pages in this order.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<NewspaperIssue[]>

Types

ActOptions · NewspaperIssue

close

methodplugins · game:act

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

Closes the Journal as its close button does (NewspaperPopup.destroy). Nothing when closed.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

hasSeenFirstPage

methodplugins · game:read

hasSeenFirstPage() => Promise<boolean>

Whether the player has opened the Journal this sitting, or the client opened it for them at login (NewspaperManager.hasSeenFirstPage).

Returns

Promise<boolean>

hasUnseenPages

methodplugins · game:read

hasUnseenPages() => Promise<boolean>

Whether the HUD shows its "new issue" burst (NewspaperManager.hasUnseenPages).

Returns

Promise<boolean>

isOpen

methodplugins · game:read

isOpen() => Promise<boolean>

Whether the Journal's popup is on screen.

Returns

Promise<boolean>

issue

methodplugins · game:read

issue(defId: number) => Promise<NewspaperIssue | null>

One issue by its def id, from the defs the client holds (getNewspaperDef), in one read. Null for an id it has no issue by, and before the def pack has loaded (issues loads it).

Parameters

Name	Type
defId	number

Returns

Promise<NewspaperIssue \| null>

Types

NewspaperIssue

issues

methodplugins · game:act

issues(options?: ActOptions) => Promise<NewspaperIssue[]>

Every issue the Journal has ever printed, in the def pack's order. Loads the def pack the first time (loadNewspaperDefs), which the HUD has usually done by then; TIMEOUT when it does not load. Loading it does not count as the player opening the Journal.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<NewspaperIssue[]>

Types

ActOptions · NewspaperIssue · NewspaperAudience

markSeen

methodplugins · game:act

markSeen(defId: number, options?: ActOptions) => Promise<NewspaperSeen>

Marks an issue seen, as the popup does when it turns to a new page (sendSetPageSeenRequest, nps), and resolves with when the server marked it.

Parameters

Name	Type
defId	number
options optional	ActOptions

Returns

Promise<NewspaperSeen>

Types

NewspaperSeen · ActOptions

open

methodplugins · game:act

open(options?: ActOptions) => Promise<NewspaperPage | null>

Opens the Journal as the HUD's button does (openNewspaperPopup), and resolves once its art and strip are up with the page it shows: null for a Journal with nothing for this player. When it is open already, resolves with the page it is on.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<NewspaperPage \| null>

Types

ActOptions · NewspaperPage

reading

methodplugins · game:read

reading() => Promise<NewspaperPage | null>

The issue the open Journal shows, and its page in the strip (NewspaperPopup._currSelectedPage); null when the Journal is not open or has not laid out its strip yet.

Returns

Promise<NewspaperPage \| null>

Types

NewspaperPage

seenAt

methodplugins · game:read

seenAt(defId: number) => Promise<number | null>

When the player last read an issue, in seconds since the epoch (getNewspaperData), or null for one never marked seen.

Parameters

Name	Type
defId	number

Returns

Promise<number \| null>

setUnseenPages

methodplugins · game:act

setUnseenPages(unseen: boolean, options?: ActOptions) => Promise<void>

Lights or puts out the HUD's "new issue" burst and redraws the button from it (GuiManager.onMyUserVarsReceived). Putting it out also counts the Journal as looked at, as the HUD's button does. This screen only: the server and the pages read are left as they were.

Parameters

Name	Type
unseen	boolean
options optional	ActOptions

Returns

Promise<void>

Types

ActOptions

turnTo

methodplugins · game:act

turnTo(page: number, options?: ActOptions) => Promise<NewspaperPage>

Turns the open Journal to a page of its strip (0 is the newest, in available's order), as its arrows and icons do: the strip scrolls to it and its icon is pressed, which loads the page. A page still marked "new" is marked seen as it opens, as the client does (onPageSeen hears it). Throws NOT_READY when the Journal is not open, RangeError past its last page.

Parameters

Name	Type
page	number
options optional	ActOptions

Returns

Promise<NewspaperPage>

Types

ActOptions · NewspaperPage

Events

onOpenChange

eventplugins · game:read

onOpenChange(listener: (open: boolean) => void) => () => void

Hears the Journal's popup asked up (true) and taken down (false), whoever did it.

Parameters

Name	Type
listener	(open: boolean) => void

Returns

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

onPageSeen

eventplugins · game:read

onPageSeen(listener: (seen: NewspaperSeen) => void) => () => void

Hears every issue marked seen (nps), whoever asked: markSeen or the popup's page turn.

Parameters

Name	Type
listener	(seen: NewspaperSeen) => void

Returns

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

Types

NewspaperSeen

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

NewspaperIssue

One issue of the Jamaa Journal, as the client's def pack holds it (newspaper.NewspaperDef).

Field	Type
defId	number	The issue's def id, as issue, seenAt and markSeen take it.
title	string	Its name, already translated by the client.
pageMediaId	number	The media the client loads to draw its page.
iconMediaId	number	The media for its icon in the archive strip.
giftType	number	What reading it gives: an item kind (giftType), which one (giftRefId), how many.
giftRefId	number
giftAmount	number
country	string | null	The country codes it is printed for, as the client matches them; null for everywhere.
startTime	number | null	When it went up, in seconds since the epoch; null when it always has been.
endTime	number | null	When it comes down; null when it never does.
audience	NewspaperAudience
printing	boolean	Whether the client counts it as printing now (NewspaperDef.isAvailable).

NewspaperAudience

Who may read an issue, as NewspaperDef.getIsViewable decides it from _usability: 0 anyone, 1 members, 2 non-members, and any other number nobody.

type NewspaperAudience = 'everyone' | 'members' | 'nonMembers' | 'nobody'

NewspaperPage

The issue the open Journal shows, and where it is in the strip (0 at the newest).

Field	Type
page	number
issue	NewspaperIssue

NewspaperSeen

An issue marked seen, and when, as the server's clock has it (seconds since the epoch).

Field	Type
defId	number
seenAt	number