The Journey Book

phantom.aj.journeyBookPlaying

The journey book.

Scripts and plugins

A script has all of it, as phantom.aj.journeyBook, 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
`close()`	Closes the Journey Book with its own close button (`GuiManager.onPageFlipCloseNP`) and waits for it to go.	`game:act`
`counts()`	Both counts the HUD's book button shows, read in one message; 0 before the fact list loads.	`game:read`
`inRoom()`	The room's Journey Book items, found or not.	`game:read`
`keepGlow()`	Keeps the glow on the HUD's book button lit, or out, from room to room, until the handle it resolves with is called (which puts back how it was).	`game:act`
`leftInRoom()`	How many of the room's Journey Book items are still to find (`getNumJBItemsLeftInWorld`).	`game:read`
`open()`	Opens the Journey Book as the HUD's button does (`GuiManager.openJourneyBook`), at the land the player is in, or at a fact's page with its popup.	`game:act`
`pageStat()`	The stat behind a page, by the book's own name for it (`PageFlip.jbUserVarIdForPageName`), with `sequence` picking between the alpha page's three.	`game:read`
`showing()`	The Journey Book on screen, or null when it is closed or the book up is another one (an e-book, the membership book).	`game:read`
`turnTo()`	Turns the open Journey Book to a page, as its own page links do (`PageFlip.turnTo`), and resolves with where it stands once the client has moved it.	`game:act`
`unseenPageIds()`	Which pages are unseen, by the stat the client marks as each is first looked at (`JBManager._unseenPagesIds`), which `phantom.aj.achievements` can read and name.	`game:read`
`onChange()`	Hears either count change: a page first looked at, a gift earned or claimed, the counts first worked out.	`game:read`
`onGiftReady()`	Hears a Journey Book gift come up for claiming: once for the gifts already waiting, and again each time that count rises.	`game:read`

journeyBook.book: The page-flip book on screen, whichever book it is, and the e-book shelf.

Member	What it does	Plugins
`current()`	The book open, or null.	`game:read`
`openFromShelf()`	Opens one of the shelf's books, as pressing it does, and resolves once it is open.	`game:act`
`openShelf()`	Opens the e-book shelf of a kind (`GuiManager.openEBookChooser`), once its list is in.	`game:act`
`setZoom()`	Zooms in on the page, or out, as the magnifier does.	`game:act`
`shelf()`	The e-books on the shelf open, in its order; none when it is not open.	`game:read`
`stickers()`	The stickers on the page open, by the names the page gives them.	`game:read`
`turnAhead()`	Turns a page ahead, as the right corner does.	`game:act`
`turnBack()`	Turns a page back, as the left corner does.	`game:act`
`turnTo()`	Turns to a page: at once (`turnTo`), or leafing through as the corner buttons do with `flip`.	`game:act`
`onChange()`	Hears the book turn, its spread come in, its zoom, its quiz, its popups and its travel.	`game:read`
`onPress()`	Hears the player press something on a page: a link, a game, a sticker, a fact, a gift.	`game:read`

Methods

`close`

methodplugins · game:act

TypeScript

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

Closes the Journey Book with its own close button (GuiManager.onPageFlipCloseNP) and waits for it to go. Resolves false, touching nothing, when the book up is not the Journey Book.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<boolean>

Types

ActOptions

`counts`

methodplugins · game:read

TypeScript

counts() => Promise<JourneyBookCounts>

Both counts the HUD's book button shows, read in one message; 0 before the fact list loads.

Returns

Promise<JourneyBookCounts>

Types

JourneyBookCounts

`inRoom`

methodplugins · game:read

TypeScript

inRoom() => Promise<JourneyBookItem[]>

The room's Journey Book items, found or not.

Returns

Promise<JourneyBookItem[]>

Types

JourneyBookItem

`keepGlow`

methodplugins · game:act

TypeScript

keepGlow(on: boolean) => Promise<() => Promise<void>>

Keeps the glow on the HUD's book button lit, or out, from room to room, until the handle it resolves with is called (which puts back how it was). Held in the game every frame (mainHud.book.glow.visible), and left alone while the button is greyed out, as the client's own showJBGlow leaves it.

Parameters

Name	Type
`on`	`boolean`

Returns

Promise<() => Promise<void>>

`leftInRoom`

methodplugins · game:read

TypeScript

leftInRoom() => Promise<number>

How many of the room's Journey Book items are still to find (getNumJBItemsLeftInWorld).

Returns

Promise<number>

`open`

methodplugins · game:act

TypeScript

open(options?: { factDefId?: number | undefined; } & ActOptions) => Promise<JourneyBookPage>

Opens the Journey Book as the HUD's button does (GuiManager.openJourneyBook), at the land the player is in, or at a fact's page with its popup. The client fetches the pages first, so this waits for the book to be up and resolves with where it opened.

Parameters

Name	Type
`options` optional	`{ factDefId?: number \| undefined; } & ActOptions`

Returns

Promise<JourneyBookPage>

Types

ActOptions · JourneyBookPage

`pageStat`

methodplugins · game:read

TypeScript

pageStat(pageName: string, options?: { sequence?: number | undefined; }) => Promise<number | null>

The stat behind a page, by the book's own name for it (PageFlip.jbUserVarIdForPageName), with sequence picking between the alpha page's three. Null when no Journey Book is open (it is a lookup on the open book) and for a name it does not know.

Parameters

Name	Type
`pageName`	`string`
`options` optional	`{ sequence?: number \| undefined; }`

Returns

Promise<number \| null>

`showing`

methodplugins · game:read

TypeScript

showing() => Promise<JourneyBookPage | null>

The Journey Book on screen, or null when it is closed or the book up is another one (an e-book, the membership book).

Returns

Promise<JourneyBookPage \| null>

Types

JourneyBookPage

`turnTo`

methodplugins · game:act

TypeScript

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

Turns the open Journey Book to a page, as its own page links do (PageFlip.turnTo), and resolves with where it stands once the client has moved it. NOT_READY when the Journey Book is not the book on screen, so an e-book is never turned by accident.

Parameters

Name	Type
`page`	`number`
`options` optional	`ActOptions`

Returns

Promise<JourneyBookPage>

Types

JourneyBookPage · ActOptions

`unseenPageIds`

methodplugins · game:read

TypeScript

unseenPageIds() => Promise<number[]>

Which pages are unseen, by the stat the client marks as each is first looked at (JBManager._unseenPagesIds), which phantom.aj.achievements can read and name.

Returns

Promise<number[]>

Events

`onChange`

eventplugins · game:read

TypeScript

onChange(listener: (counts: JourneyBookCounts) => void) => () => void

Hears either count change: a page first looked at, a gift earned or claimed, the counts first worked out. Hooked where the client updates them, and told only when they differ from the last this listener was told.

Parameters

Name	Type
`listener`	`(counts: JourneyBookCounts) => void`

Returns

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

Types

JourneyBookCounts

`onGiftReady`

eventplugins · game:read

TypeScript

onGiftReady(listener: (gifts: number) => void) => () => void

Hears a Journey Book gift come up for claiming: once for the gifts already waiting, and again each time that count rises. A page being read says nothing.

Parameters

Name	Type
`listener`	`(gifts: number) => void`

Returns

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

`journeyBook.book`

The page-flip book on screen, whichever book it is, and the e-book shelf.

`current`

methodplugins · game:read

TypeScript

current() => Promise<Book | null>

The book open, or null.

Returns

Promise<Book \| null>

Types

Book · BookKind

`openFromShelf`

methodplugins · game:act

TypeScript

openFromShelf(index: number, options?: ActOptions) => Promise<Book>

Opens one of the shelf's books, as pressing it does, and resolves once it is open.

Parameters

Name	Type
`index`	`number`
`options` optional	`ActOptions`

Returns

Promise<Book>

Types

ActOptions · Book

`openShelf`

methodplugins · game:act

TypeScript

openShelf(type: string, options?: ActOptions) => Promise<EBookOnShelf[]>

Opens the e-book shelf of a kind (GuiManager.openEBookChooser), once its list is in.

Parameters

Name	Type
`type`	`string`
`options` optional	`ActOptions`

Returns

Promise<EBookOnShelf[]>

Types

EBookOnShelf · ActOptions

`setZoom`

methodplugins · game:act

TypeScript

setZoom(zoomed: boolean, options?: ActOptions) => Promise<Book>

Zooms in on the page, or out, as the magnifier does.

Parameters

Name	Type
`zoomed`	`boolean`
`options` optional	`ActOptions`

Returns

Promise<Book>

Types

ActOptions · Book

`shelf`

methodplugins · game:read

TypeScript

shelf() => Promise<EBookOnShelf[]>

The e-books on the shelf open, in its order; none when it is not open.

Returns

Promise<EBookOnShelf[]>

Types

EBookOnShelf

`stickers`

methodplugins · game:read

TypeScript

stickers() => Promise<string[]>

The stickers on the page open, by the names the page gives them.

Returns

Promise<string[]>

`turnAhead`

methodplugins · game:act

TypeScript

turnAhead(options?: ActOptions) => Promise<Book>

Turns a page ahead, as the right corner does.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<Book>

Types

ActOptions · Book

`turnBack`

methodplugins · game:act

TypeScript

turnBack(options?: ActOptions) => Promise<Book>

Turns a page back, as the left corner does.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<Book>

Types

ActOptions · Book

`turnTo`

methodplugins · game:act

TypeScript

turnTo(page: number, options?: ActOptions & { flip?: boolean | undefined; }) => Promise<Book>

Turns to a page: at once (turnTo), or leafing through as the corner buttons do with flip. Resolves with the book as it then stands.

Parameters

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

Returns

Promise<Book>

Types

ActOptions · Book

`onChange`

eventplugins · game:read

TypeScript

onChange(listener: (change: BookChange) => void) => () => void

Hears the book turn, its spread come in, its zoom, its quiz, its popups and its travel.

Parameters

Name	Type
`listener`	`(change: BookChange) => void`

Returns

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

Types

BookChange

`onPress`

eventplugins · game:read

TypeScript

onPress(listener: (press: BookPress) => void) => () => void

Hears the player press something on a page: a link, a game, a sticker, a fact, a gift.

Parameters

Name	Type
`listener`	`(press: BookPress) => void`

Returns

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

Types

BookPress · BookPressKind

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.

`JourneyBookCounts`

What the Journey Book's button on the HUD counts.

Field	Type
`unseenPages`	`number`	Pages of facts the player has not opened yet (`JBManager.numUnseenPages`).
`unclaimedGifts`	`number`	Gifts earned by filling a page and not yet claimed (`JBManager.numUnclaimedGifts`).

`JourneyBookPage`

Where the open Journey Book is (gui.PageFlip).

Field	Type
`page`	`number`	The page showing, as the client means it (`Math.round(PageFlip._currentPage)`).
`pages`	`number`	How many pages the book has (`_numberOfPages`).
`name`	`string \| null`	The book's own name for that page (`_pageNameArray`), such as `crystal_sands`; null before its art.

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

`JourneyBookItem`

A Journey Book item hidden in the room (RoomManagerWorld._jbItems).

Field	Type
`name`	`string`
`refId`	`number`
`refObjName`	`string \| null`
`ready`	`boolean`	Ready to be found.
`x`	`number`
`y`	`number`

`Book`

The book open (gui.PageFlip), as it stands.

Field	Type
`kind`	`BookKind`
`page`	`number`
`pages`	`number`
`spread`	`number`	The spread turned to (`_pageTurnedTo`).
`singlePage`	`boolean`
`flipping`	`boolean`
`pageIds`	`number[]`	The page art of the book, by media id.
`ready`	`boolean`	The spread's art and its facts are in.
`canTurnBack`	`boolean`
`canTurnAhead`	`boolean`
`zoomed`	`boolean`
`pageName`	`string \| null`
`quiz`	`{ questions: number; answered: number; pages: number; }`
`stickerPage`	`number \| null`

`BookKind`

Which book is open: the Journey Book, or one the client opens through the same page flip.

TypeScript

type BookKind = 'journeyBook' | 'membership' | 'animalJamEBook' | 'comic' | 'newspaper'

`EBookOnShelf`

One e-book on the shelf (gui.EBookChooser._currEBooks).

Field	Type
`index`	`number`
`ebookId`	`number`
`mediaId`	`number`
`listId`	`number`

`BookChange`

Something happening in the book.

TypeScript

type BookChange = | { kind: 'turned'; page: number; spread: number; pages: number }
  | { kind: 'ready'; spread: number }
  | { kind: 'zoom'; zoomed: boolean }
  | { kind: 'quiz'; questions: number; answered: number }
  | { kind: 'popup'; open: boolean; name: string | null }
  | { kind: 'travel'; to: 'room' | 'party'; going: boolean }

`BookPress`

A press on a book's page: what it was, and the names and ids the page gave it.

Field	Type
`kind`	`BookPressKind`
`name`	`string \| null`
`id`	`string \| null`
`factId`	`string \| null`

`BookPressKind`

Something on a book's page the player pressed, by the handler the client gave it.

TypeScript

type BookPressKind = | 'turnTo'
  | 'link'
  | 'joinRoom'
  | 'joinParty'
  | 'joinClub'
  | 'game'
  | 'pet'
  | 'video'
  | 'poll'
  | 'popup'
  | 'feedback'
  | 'stamp'
  | 'sticker'
  | 'stickerPickUp'
  | 'submit'
  | 'tryAgain'
  | 'fact'
  | 'gift'

The Journey Book ​

Overview ​

Methods ​

close ​

counts ​

inRoom ​

keepGlow ​

leftInRoom ​

open ​

pageStat ​

showing ​

turnTo ​

unseenPageIds ​

Events ​

onChange ​

onGiftReady ​

journeyBook.book ​

current ​

openFromShelf ​

openShelf ​

setZoom ​

shelf ​

stickers ​

turnAhead ​

turnBack ​

turnTo ​

onChange ​

onPress ​

Types ​

JourneyBookCounts ​

JourneyBookPage ​

ActOptions ​

JourneyBookItem ​

Book ​

BookKind ​

EBookOnShelf ​

BookChange ​

BookPress ​

BookPressKind ​

The Journey Book

Overview

Methods

`close`

`counts`

`inRoom`

`keepGlow`

`leftInRoom`

`open`

`pageStat`

`showing`

`turnTo`

`unseenPageIds`

Events

`onChange`

`onGiftReady`

`journeyBook.book`

`current`

`openFromShelf`

`openShelf`

`setZoom`

`shelf`

`stickers`

`turnAhead`

`turnBack`

`turnTo`

`onChange`

`onPress`

Types

`JourneyBookCounts`

`JourneyBookPage`

`ActOptions`

`JourneyBookItem`

`Book`

`BookKind`

`EBookOnShelf`

`BookChange`

`BookPress`

`BookPressKind`