Journal System
Relevant source files
The following files were used as context for generating this wiki page:
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Journal.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Document.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Catalog.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Bestiary.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/windows/WndJournal.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/journal/DocumentPage.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/hero/Hero.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java
The Journal System in Shattered Pixel Dungeon serves as an in-game repository of information, designed to provide players with guides, lore, and tracking of in-game entities, reducing the need for external wikis. Initially expanded in version 0.6.1 to replace a signpost-based tutorial system, it has since evolved into a comprehensive information hub. A major overhaul in version 2.5 introduced a grid-based UI, custom player notes, and a massively expanded catalog and bestiary.
The system is composed of several key parts: Documents for guides and lore, Catalogs for tracking items and characters (Bestiary), a Notes section for landmarks and custom player entries, and a section for viewing Badges. Content is primarily unlocked by finding and picking up DocumentPage items scattered throughout the dungeon.
Sources: ui/changelist/v2_X_Changes.java:82-93, ui/changelist/v0_6_X_Changes.java:1010-1013
Core Architecture
The Journal System is managed by a set of static and instance-based classes that handle data persistence, UI presentation, and content management.
Key Components
| Class/Enum | File Path | Description |
|---|---|---|
Journal | journal/Journal.java | A static utility class that acts as the central manager for all journal data. It orchestrates the saving and loading of journal content. |
WndJournal | windows/WndJournal.java | The main UI window for the journal. It is a tabbed interface that presents all the journal's content to the player. |
Document | journal/Document.java | An enum defining all discoverable documents, such as the Adventurer's Guide, Alchemy Guide, and various lore books. It manages the state of each page. |
DocumentPage | items/journal/DocumentPage.java | An abstract Item class representing a physical page found in the dungeon. Picking up this item unlocks content in the journal. |
Catalog | journal/Catalog.java | An abstract class for tracking game entities. It maintains a map of known and unknown items. |
Bestiary | journal/Bestiary.java | A concrete implementation of Catalog specifically for tracking characters, traps, and plants. |
Sources: journal/Journal.java, windows/WndJournal.java, journal/Document.java, items/journal/DocumentPage.java, journal/Catalog.java, journal/Bestiary.java
Class Relationships
The following diagram shows the main classes of the Journal System and their relationships.
Documents and Pages
Documents are collections of pages containing text-based information like guides and lore. The system tracks the state of each page individually.
Document Types
The Document enum defines all the documents available in the journal.
| Document Enum | Description |
|---|---|
ADVENTURERS_GUIDE | The main tutorial and gameplay guide. |
ALCHEMY_GUIDE | A guide to the alchemy crafting system. |
INTROS | Introductory story text for each dungeon region. |
SEWERS_GUARD | Lore story for the Sewers region. |
PRISON_WARDEN | Lore story for the Prison region. |
CAVES_EXPLORER | Lore story for the Caves region. |
CITY_WARLOCK | Lore story for the City region. |
HALLS_KING | Lore story for the Demon Halls region. |
Sources: journal/Document.java:31-39
Page States
Each page within a document can be in one of three states, managed by the Document enum.
| State | Value | Description |
|---|---|---|
NOT_FOUND | 0 | The player has not yet found this page. |
FOUND | 1 | The player has found the page but has not read it yet. The journal button will blink to indicate new content. |
READ | 2 | The player has read the page. |
Sources: journal/Document.java:42-44
Unlocking Content
Content is unlocked when the Hero picks up a DocumentPage item. This action triggers a sequence of events to update the journal state and the UI.
The following diagram illustrates the process of a hero picking up a DocumentPage.
Catalogs and Bestiary
The Journal includes catalogs for tracking items and a bestiary for tracking characters, plants, and traps. This functionality helps players keep track of what they have identified and encountered.
Catalog.java
This abstract class provides the base functionality for all catalogs. It uses a HashMap<Class<? extends Item>, Integer> to store the state of each item. An item is considered "known" if it has been identified. This is used for badges related to identifying all items of a certain type.
Sources: journal/Catalog.java:33-34, ui/changelist/v0_6_X_Changes.java:1015-1016
Bestiary.java
The Bestiary is a specific implementation of Catalog that tracks non-item entities. It was significantly expanded in version 2.5 to include almost every character, plant, and trap in the game.
- It uses a
HashMap<Class<?>, Integer>to store entries. - The state of an entry can be
UNKNOWN,SEEN, orDEFEATED. - Filling out the bestiary contributes to unlocking new badges.
Sources: journal/Bestiary.java:29, ui/changelist/v2_X_Changes.java:85-87
Journal UI (WndJournal)
The WndJournal class is the graphical interface for the Journal. It is organized into several tabs, which were significantly updated in version 2.5 to use a grid-based layout for better information density and usability.
The following diagram shows the tab structure of the WndJournal.
UI Tabs
- Notes Tab: Displays discovered lore pages, landmarks, and allows the player to create custom notes. This tab was overhauled in v2.5 to use a grid UI.
- Catalog Tab: Shows the item catalog and the bestiary, also in a grid UI since v2.5. It tracks which items have been identified and which enemies/traps/plants have been encountered.
- Guidebook Tab: Contains the
ADVENTURERS_GUIDEandALCHEMY_GUIDE. - Badges Tab: Allows the player to view their earned badges for the current run and overall progress.
Sources: windows/WndJournal.java:70-76, ui/changelist/v2_X_Changes.java:82-93
Data Persistence
The state of the journal is saved with the game's progress. The static Journal class orchestrates this process.
- The
Journal.saveNeededflag is set totruewhenever a change occurs (e.g., a page is found or read). - The
Journal.store(Bundle)method is called during the game save process. It delegates the saving of data to thestoremethods ofDocument,Catalog, andNotes. - Conversely,
Journal.restore(Bundle)is used to load the journal state from a saved game.
Sources: journal/Journal.java:29-49, journal/Document.java:209-231
Summary
The Journal System is a critical in-game information resource that has evolved from a simple tutorial replacement to a comprehensive, multi-faceted wiki. It tracks player discoveries, from lore pages to encountered enemies, and presents this information through a clean, tabbed interface. Its architecture is designed for easy content extension and robust data persistence, making it an integral part of the player's journey through the dungeon.