Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/AboutScene.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_2_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_3_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_8_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_9_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v3_X_Changes.java
The changelog system in Shattered Pixel Dungeon provides a structured and visually rich in-game presentation of the game's version history. It is designed to be easily updatable and maintainable, with each major version's changes encapsulated in its own class. The system aggregates these changes into a single, scrollable list for the player, presented within the ChangesScene.
A key feature of this system is the inclusion of "Developer Commentary" for many versions, offering players direct insight into the design decisions and development process behind the updates. This commentary is a distinct feature that enriches the player's understanding of the game's evolution.
Sources: README.md:15, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:62-67
System Architecture
The changelog is constructed from a series of data-holding classes that are processed and rendered by the UI. The core logic resides in the core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/ directory, where each file (e.g., v2_X_Changes.java) corresponds to a major version release series.
Core Components
The system is built around two main data structures, ChangeInfo and ChangeButton, which are populated by static methods within the version-specific classes.
| Class | Description | Source File |
|---|---|---|
v*_X_Changes | A static class containing all change data for a major version series (e.g., v2.X). | v2_X_Changes.java |
ChangeInfo | Represents a section in the changelog, such as a version header ("v2.5") or a category ("New", "Buffs"). It contains a title and a list of ChangeButtons. | v2_X_Changes.java:59 |
ChangeButton | Represents a single, collapsible entry within a ChangeInfo section. It holds an icon, a title, and the detailed description text. | v2_X_Changes.java:62 |
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:59, 62, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java
Data Flow and Aggregation
The complete changelog is built by sequentially calling the addAllChanges method from each version-specific class. Each of these methods, in turn, calls more granular methods for each minor version (e.g., add_v2_5_Changes, add_v2_4_Changes), which populate an ArrayList<ChangeInfo>. This creates a chronologically ordered, hierarchical list of all changes.
The following diagram illustrates the aggregation flow for building the changelog.
This diagram shows how the main ChangesScene would aggregate change information by calling static methods from each version-specific class in sequence.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:53-57, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java:44-48, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_9_X_Changes.java:44-48
Content and Presentation
The system uses a combination of categorization, color-coding, and iconography to present the information in a clear and engaging manner.
Categorization and Styling
Changes are grouped into standard categories. Each category, as well as major version headers, can be styled with a specific color using the hardlight() method on a ChangeInfo object. This provides immediate visual cues to the user about the nature of the changes.
| Category | Color Constant | Visual Cue | Source |
|---|---|---|---|
| Version Header | Window.TITLE_COLOR | White/Title Color | v2_X_Changes.java:59 |
| New | Window.TITLE_COLOR | White/Title Color | v2_X_Changes.java:62 |
| Changes | CharSprite.WARNING | Orange | v2_X_Changes.java:101 |
| Buffs | CharSprite.POSITIVE | Green | v2_X_Changes.java:302 |
| Nerfs | CharSprite.NEGATIVE | Red | v2_X_Changes.java:353 |
| Bugfixes | N/A (uses default) | Default (with spinner icon) | v2_X_Changes.java:237 |
Visual Elements and Icons
Each ChangeButton is associated with an icon that visually represents the change. The system leverages a wide array of existing game sprites and icons, creating a strong thematic link between the changelog and the game itself.
Icons are sourced from various classes, including:
Icons: General-purpose UI icons (e.g.,Icons.SHPX,Icons.TALENT).ItemSprite: Sprites for in-game items (e.g.,new ItemSprite(ItemSpriteSheet.SALT_CUBE)).HeroSprite: Sprites for hero characters and their avatars (e.g.,HeroSprite.avatar(HeroClass.DUELIST, 1)).TalentIcon: Specific icons for hero talents.- Other character sprites like
GnollGuardSprite,GhostSprite, etc.
This use of in-game assets makes the changelog entries instantly recognizable and more engaging for the player.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:62, 80, 305, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_9_X_Changes.java:102, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v3_X_Changes.java:352
Developer Commentary
A unique aspect of this changelog system is the "Developer Commentary" section included in many updates. This provides players with behind-the-scenes information, design rationale, and historical context for the changes made in a particular version. This feature fosters a strong connection between the developer and the community.
The commentary is added just like any other change, using a ChangeButton with a specific icon and title.
// Example from v2.5.0
changes.addButton( new ChangeButton(Icons.get(Icons.SHPX), "Developer Commentary",
"_-_ Released September 11th, 2024\n" +
"_-_ 119 days after v2.4.0\n" +
"\n" +
"Dev commentary will be added here in the future"));
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:62-67, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_9_X_Changes.java:59-65, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java:82-92
Conclusion
Shattered Pixel Dungeon's changelog system is a well-designed, data-driven module that effectively communicates version history to players. By encapsulating changes in version-specific classes and using a hierarchical structure of ChangeInfo and ChangeButton objects, it remains easy to maintain and extend. The extensive use of color-coding, in-game icons, and direct developer commentary makes the changelog not just a list of changes, but an integral and engaging part of the game's user experience.