Recommended Changes for Forks
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_2_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/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
- services/news/shatteredNews/src/main/java/com/shatteredpixel/shatteredpixeldungeon/services/news/NewsImpl.java
- services/updates/githubUpdates/src/main/java/com/shatteredpixel/shatteredpixeldungeon/services/updates/UpdateImpl.java
Shattered Pixel Dungeon is an open-source project, but it does not accept pull requests. The code is provided for others to learn from or use for their own projects. If you are creating a fork or your own version of Shattered Pixel Dungeon, it is highly recommended to make several key changes to distinguish your project from the original and to ensure external services function correctly.
This document outlines the most important changes to consider, based on the project's structure and service implementations. These include replacing service integrations, updating branding and monetization links, and managing your own changelog.
Sources: README.md
Service Implementations
The base game includes several services that are specific to the original Shattered Pixel Dungeon project. These services handle news, update notifications, and analytics. Forks must replace or disable these to avoid misdirecting users or data.
| Service | Purpose | Original Implementation File | Recommended Action |
|---|---|---|---|
| News Feed | Displays developer blog posts from ShatteredPixel.com. | services/news/shatteredNews/NewsImpl.java | Replace with your own news source or disable. |
| Update Checker | Notifies users of new versions from the official GitHub. | services/updates/githubUpdates/UpdateImpl.java | Point to your own repository or distribution site. |
| Gameplay Analytics | Collects anonymous gameplay data via Google Firebase. | Mentioned in v0.7.2_Changes.java | Disable or replace with your own analytics service. |
Sources: services/news/shatteredNews/src/main/java/com/shatteredpixel/shatteredpixeldungeon/services/news/NewsImpl.java, services/updates/githubUpdates/src/main/java/com/shatteredpixel/shatteredpixeldungeon/services/updates/UpdateImpl.java, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:400-405
News Service
The game includes an in-game news feed that pulls blog posts from ShatteredPixel.com. This is handled by the NewsImpl class. Forks should replace this implementation to point to their own news feed or disable it entirely.
The following diagram illustrates the flow of the default news service.
Diagram showing the data flow for the in-game news service.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_8_X_Changes.java:137-142, services/news/shatteredNews/src/main/java/com/shatteredpixel/shatteredpixeldungeon/services/news/NewsImpl.java
Update Service
The game checks for updates by querying the GitHub releases API for the original repository. This is implemented in the UpdateImpl class. Forks must change this to point to their own GitHub repository or another distribution platform to ensure users receive the correct updates.
The following diagram illustrates the flow of the update check.
Diagram showing the data flow for the update notification service.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_8_X_Changes.java:680-696, services/updates/githubUpdates/src/main/java/com/shatteredpixel/shatteredpixeldungeon/services/updates/UpdateImpl.java
Gameplay Data Sharing
Shattered Pixel Dungeon includes an option to share gameplay data, which uses Google Firebase Analytics. This service sends data to the original developer's analytics account. Forks should disable this feature or replace it with their own analytics implementation to maintain user privacy and data integrity.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:400-405, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java:348-349
Distribution and Monetization
To properly distribute a fork, especially on platforms like Google Play, several changes related to identity and monetization are necessary.
Package Name and Branding
Before distributing, especially on Google Play, you must change the application's package name to avoid conflicts with the original game. It is also essential to change the game's name, icons, and any other branding elements to create a distinct identity for your fork. The changelogs show numerous examples of the original developer adding unique branding, such as custom splash arts and music, which is a practice forks should follow.
Sources: README.md, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v3_X_Changes.java:613-625, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java:684-694
Supporter and Donation Features
The original game includes a supporter system and donation links (e.g., Patreon). These are mentioned in the README.md and documented in changelogs, such as the implementation of a donation system in v0.2.3. Forks must remove these features or replace them with their own monetization links to prevent funds from being misdirected to the original developer.
Sources: README.md, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_2_X_Changes.java:150-155, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_8_X_Changes.java:150-155
Changelog Management
Shattered Pixel Dungeon features a detailed, in-game changelog screen. This system is modular, with dedicated classes for major version groups (e.g., v1_X_Changes, v2_X_Changes).
System Architecture
Each major version class contains methods to add changes for specific minor/patch versions. These methods construct the UI using ChangeInfo and ChangeButton objects, often including developer commentary, icons, and categorized sections for new features, buffs, and nerfs.
The following diagram shows the class structure for the changelog system.
Class diagram illustrating the modular structure of the changelog system.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v3_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/v1_X_Changes.java
Recommendation for Forks
A fork will have its own set of changes and versioning. It is recommended to either:
- Adapt the existing system: Create new
vX_Y_Changes.javafiles that reflect your fork's versioning and changes. - Replace the system: Implement a new, simpler changelog system if the existing one is too complex for your needs.
In either case, the original changelog files should be removed or heavily modified to avoid showing outdated or irrelevant information to your users.
Summary
Forking Shattered Pixel Dungeon provides a rich foundation for creating a new roguelike experience. However, to ensure a successful and distinct project, it is crucial to address the points above. Replacing backend services, establishing a unique brand, and managing your own project-specific information like changelogs are essential first steps for any developer looking to build upon this codebase.