Updated readme/guide and put technical guides in their own directory

This commit is contained in:
Evan Debenham 2020-04-29 18:33:57 -04:00
parent b00d5296bc
commit 1daea3acb7
4 changed files with 187 additions and 75 deletions

View File

@ -1,82 +1,17 @@
# Shattered Pixel Dungeon
A Roguelike RPG, with randomly generated levels, items, enemies, and traps!
Based on the source code of Pixel Dungeon, by Watabou.
A Roguelike RPG, with randomly generated levels, items, enemies, and traps! Based on the [source code of Pixel Dungeon](https://github.com/00-Evan/pixel-dungeon-gradle), by [Watabou](https://www.watabou.ru).
Look below for compilation instructions.
Shattered Pixel Dungeon currently compiles for Android and desktop platforms. It is available from [GitHub](https://github.com/00-Evan/shattered-pixel-dungeon/releases), [Google Play](https://play.google.com/store/apps/details?id=com.shatteredpixel.shatteredpixeldungeon), [Amazon](https://www.amazon.com/Shattered-Pixel-Dungeon/dp/B00OH2C21M), and [F-Droid](https://f-droid.org/repository/browse/?fdid=com.shatteredpixel.shatteredpixeldungeon).
Shattered Pixel Dungeon on Google Play:
https://play.google.com/store/apps/details?id=com.shatteredpixel.shatteredpixeldungeon
If you like this game, please consider [supporting me on Patreon](https://www.patreon.com/ShatteredPixel)!
On Amazon:
https://www.amazon.com/Shattered-Pixel-Dungeon/dp/B00OH2C21M
There is an official blog for this project at [ShatteredPixel.com](http://www.shatteredpixel.com).
On F-Droid (Which compiles directly from this source code):
https://f-droid.org/repository/browse/?fdid=com.shatteredpixel.shatteredpixeldungeon
The game also has a translation project hosted on [Transifex](https://www.transifex.com/shattered-pixel/shattered-pixel-dungeon/).
Official website and blog:
http://www.shatteredpixel.com
Source code of original Pixel Dungeon (adapted to use newer build tools):
https://github.com/00-Evan/pixel-dungeon-gradle
# Compiling Shattered Pixel Dungeon
**Note that Shattered Pixel Dungeon is currently in the process of being converted to use the multiplatform game library LibGDX. The game currently compiles for desktop but is missing several important desktop features. Desktop compiling is suitable for debugging but releasing desktop builds from this codebase is not advised at the moment.**
To compile Shattered Pixel Dungeon you will need:
- A computer which meets the [system requirements for Android Studio](https://developer.android.com/studio#Requirements)
- (optional) a GitHub account to fork this repository, if you wish to use version control
- (optional) an android phone to test your build of Shattered Pixel Dungeon
#### 1. Installing programs
Download and install the latest version of [Android Studio](https://developer.android.com/studio). This is the development environment which android apps use, it includes all the tools needed to get started with building android apps.
It is optional, but strongly recommended, to use version control to manage your copy of the Shattered Pixel Dungeon codebase. Version control is software which helps you manage changes to code. To use version control you will need to download and install [Git](https://git-scm.com/downloads). You are welcome to use a separate graphical git client or git CLI if you prefer, but this guide will use Android Studio's built-in git tools.
#### 2. Setting up your copy of the code
If you are using version control, fork this repository using the 'fork' button at the top-right of this web page, so that you have your own copy of the code on GitHub.
If you do not wish to use version control, press the 'clone or download' button and then 'Download ZIP'. Unzip the downloaded zip to any directory on your computer you like.
#### 3. Opening the code in Android Studio
Open Android Studio, you will be greeted with a splash page with a few options.
If you are using version control, you must first tell Android Studio where your installation of Git is located:
- Select 'Configure' then 'Settings'
- From the settings window, select 'Version Control' then 'Git'
- Point 'Path to Git executable:' to 'bin/git.exe', which will be located where you installed git.
- Hit the 'test' button to make sure git works, then press 'Okay' to return to the splash page.
After that, you will want to select 'check out project from version control' then 'git'. Log in to GitHub through the button (use username instead of tokens), and select your forked repository from the list of URLs. Import to whatever directory on your computer you like. Accept the default options android studio suggests when opening the project. If you would like more information about working with Git and commiting changes you make back to version control, [consult this guide](https://code.tutsplus.com/tutorials/working-with-git-in-android-studio--cms-30514) (skip to chapter 4).
If you are not using version control, select 'Import project (Gradle, Eclipse ADT, etc.)' and select the folder you unzipped the code into. Accept the default options android studio suggests when opening the project.
#### 4. Running the code
Once the code is open in Android Studio, running it will require either a physical android device or an android emulator. Using a physical device is recommended as the Android Emulator is less convenient to work with and has additional system requirements. Note that when you first open and run the code Android Studio may take some time, as it needs to set up the project and download various android build tools.
The Android studio website has [a guide which covers the specifics of running a project you have already set up.](https://developer.android.com/studio/run)
This guide includes a [section on physical android devices...](https://developer.android.com/studio/run/device.html)
... and [a section on emulated android devices.](https://developer.android.com/studio/run/emulator)
#### 5. Generating an installable APK
An APK (Android PacKage) is a file used to distribute Android applications. The Android studio website has [a guide which covers building your app into an APK.](https://developer.android.com/studio/run#reference) Note that the option you will likely want to use is 'Generate Signed Bundle / APK'.
Note that APKs must be signed with a signing key. If you are making a small personal modification to Shattered Pixel Dungeon then your signing key is not important, but if you intend to distribute your modification to other people and want them to be able to receive updates, then your signing key is critical. The Android studio website has [a guide on signing keys.](https://developer.android.com/studio/publish/app-signing.html#opt-out)
Additionally, note that by default Shattered Pixel Dungeon uses R8 on release builds. R8 is a code optimizer which decreases the size of the APK and improves performance, but also makes error reports more difficult to read. You can disable R8 by setting minifyEnabled to false in 'android/build.grade'. If you wish to keep R8 enabled, you can learn more about it [here.](https://developer.android.com/studio/build/shrink-code)
#### 6. Distributing Your APK
The Android Studio website includes [a guide for ways to distribute your app.](https://developer.android.com/studio/publish)
Note that by distributing your modification of Shattered Pixel Dungeon, you are bound by the terms of the GPLv3 license, which requires that you make any modifications you have made open-source. If you followed this guide and are using version control, that is already set up for you as your forked repository is publicly hosted on GitHub.
If you intend to make your version of the game available on Google Play **PLEASE CONTACT ME AT THE FOLLOWING EMAIL ADDRESS:** Evan@ShatteredPixel.com . There are various aspects of Google's Developer Policies that go beyond the scope of a simple 'how to compile' guide. If you do not take necessary precautions before attempting to publish on Google Play, your version of the game will almost certainly be taken down for impersonating Shattered Pixel Dungeon or Pixel Dungeon.
If you'd like to work with the code, you can find the following guides in `/docs`:
- [Compiling for Android.](docs/getting-started-android.md)
- **[If you plan to distribute on Google Play please read the end of this guide.](docs/getting-started-android.md#distributing-your-apk)**
- [Compiling for desktop platforms.](docs/getting-started-desktop.md)
- [Recommended changes for making your own mod.](docs/recommended-changes.md)

View File

@ -0,0 +1,60 @@
### Prerequisites
To compile Shattered Pixel Dungeon for Android using this guide you will need:
- A computer which meets the [system requirements for Android Studio](https://developer.android.com/studio#Requirements)
- (optional) a GitHub account to fork this repository, if you wish to use version control
- (optional) an android phone to test your build of Shattered Pixel Dungeon
### Installing programs
Download and install the latest version of [Android Studio](https://developer.android.com/studio). This is the development environment which android apps use, it includes all the tools needed to get started with building android apps.
It is optional, but strongly recommended, to use version control to manage your copy of the Shattered Pixel Dungeon codebase. Version control is software which helps you manage changes to code. To use version control you will need to download and install [Git](https://git-scm.com/downloads). You are welcome to use a separate graphical git client or git CLI if you prefer, but this guide will use Android Studio's built-in git tools.
### Setting up your copy of the code
If you are using version control, fork this repository using the 'fork' button at the top-right of this web page, so that you have your own copy of the code on GitHub.
If you do not wish to use version control, press the 'clone or download' button and then 'Download ZIP'. Unzip the downloaded zip to any directory on your computer you like.
### Opening the code in Android Studio
Open Android Studio, you will be greeted with a splash page with a few options.
If you are using version control, you must first tell Android Studio where your installation of Git is located:
- Select 'Configure' then 'Settings'
- From the settings window, select 'Version Control' then 'Git'
- Point 'Path to Git executable:' to 'bin/git.exe', which will be located where you installed git.
- Hit the 'test' button to make sure git works, then press 'Okay' to return to the splash page.
After that, you will want to select 'check out project from version control' then 'git'. Log in to GitHub through the button (use username instead of tokens), and select your forked repository from the list of URLs. Import to whatever directory on your computer you like. Accept the default options android studio suggests when opening the project. If you would like more information about working with Git and commiting changes you make back to version control, [consult this guide](https://code.tutsplus.com/tutorials/working-with-git-in-android-studio--cms-30514) (skip to chapter 4).
If you are not using version control, select 'Import project (Gradle, Eclipse ADT, etc.)' and select the folder you unzipped the code into. Accept the default options android studio suggests when opening the project.
### Running the code
Once the code is open in Android Studio, running the Android build will require either a physical android device or an android emulator. Using a physical device is recommended as the Android Emulator is less convenient to work with and has additional system requirements. Note that when you first open and run the code Android Studio may take some time, as it needs to set up the project and download various android build tools.
The Android Studio website has [a guide which covers the specifics of running a project you have already set up.](https://developer.android.com/studio/run)
This guide includes a [section on physical android devices...](https://developer.android.com/studio/run/device.html)
... and [a section on emulated android devices.](https://developer.android.com/studio/run/emulator)
If you frequently wish to run your code for debugging purposes, and the changes you make are to platform-independent modules (such as core and SPD-classes), you may find that running the [desktop build](getting-started-desktop.md) is more convenient.
### Generating an installable APK
An APK (Android PacKage) is a file used to distribute Android applications. The Android studio website has [a guide which covers building your app into an APK.](https://developer.android.com/studio/run#reference) Note that the option you will likely want to use is 'Generate Signed Bundle / APK'.
Note that APKs must be signed with a signing key. If you are making a small personal modification to Shattered Pixel Dungeon then your signing key is not important, but **if you intend to distribute your modification to other people and want them to be able to receive updates, then your signing key is critical.** The Android studio website has [a guide on signing keys.](https://developer.android.com/studio/publish/app-signing.html#opt-out)
Additionally, note that by default Shattered Pixel Dungeon uses R8 on release builds. R8 is a code optimizer which decreases the size of the APK and improves performance, but also makes error reports more difficult to read. You can disable R8 by setting minifyEnabled to false in [android/build.grade](./android/build.gradle). If you wish to keep R8 enabled, you can learn more about it [here.](https://developer.android.com/studio/build/shrink-code)
### Distributing Your APK
The Android Studio website includes [a guide for ways to distribute your app.](https://developer.android.com/studio/publish)
Note that by distributing your modification of Shattered Pixel Dungeon, you are bound by the terms of the GPLv3 license, which requires that you make any modifications you have made open-source. If you followed this guide and are using version control, that is already set up for you as your forked repository is publicly hosted on GitHub. Just make sure to push any changes you make back to that repository.
**If you intend to make your version of the game available on Google Play PLEASE CONTACT ME AT THE FOLLOWING EMAIL ADDRESS:** Evan@ShatteredPixel.com . There are various aspects of Google's Developer Policies that go beyond the scope of a simple 'how to compile' guide. If you do not take necessary precautions before attempting to publish on Google Play, your version of the game will almost certainly be taken down for impersonating Shattered Pixel Dungeon or Pixel Dungeon.

View File

@ -0,0 +1,66 @@
## Quick Setup
If you merely wish to build the game from source, or make small personal changes to the code, then the project can be built with minimal setup:
- Ensure a [JDK (Java Development Kit)](https://www.oracle.com/java/technologies/javase-downloads.html) is installed on your computer.
- Copy the code by pressing the 'clone or download' button and then 'Download ZIP'. Unzip the downloaded zip to any directory on your computer you like.
- or optionally use version control (see full setup for details).
- Open a command prompt from the project's root folder and type `./gradlew desktop:debug` to run the game in debug mode.
- Type `./gradlew desktop:release` to build a release JAR file, which will be placed in `/desktop/build/libs`.
Any code changes you make will be applied when you newly run or compile the game.
## Full Setup
Performing a full setup is strongly recommended if you wish to make changes to the code beyond very minor personal modifications.
### Prerequisites
To compile Shattered Pixel Dungeon for desktop using this guide you will need:
- A computer which meets the system requirements for [Android Studio](https://developer.android.com/studio#Requirements) or [Intellij](https://www.jetbrains.com/help/idea/installation-guide.html)
- (optional) a GitHub account to fork this repository, if you wish to use version control
### Installing programs
Download and install the latest version of [Android Studio](https://developer.android.com/studio) (or [Intellij](https://www.jetbrains.com/idea/download)). Either software includes all the tools you will need to compile the game.
Android Studio is recommended over Intellij as it is required to compile the [Android version](getting-started-android.md) of the game. If you prefer Intellij and are certain you do not need Android functionality, you may use that instead. This guide will assume Android Studio is used, but the two programs are very similar.
It is optional, but strongly recommended, to use version control to manage your copy of the Shattered Pixel Dungeon codebase. Version control is software which helps you manage changes to code. To use version control you will need to download and install [Git](https://git-scm.com/downloads). You are welcome to use a separate graphical git client or git CLI if you prefer, but this guide will use Android Studio's built-in git tools.
### Setting up your copy of the code
If you are using version control, fork this repository using the 'fork' button at the top-right of this web page, so that you have your own copy of the code on GitHub.
If you do not wish to use version control, press the 'clone or download' button and then 'Download ZIP'. Unzip the downloaded zip to any directory on your computer you like.
### Opening the code in Android Studio
Open Android Studio, you will be greeted with a splash page with a few options.
If you are using version control, you must first tell Android Studio where your installation of Git is located:
- Select 'Configure' then 'Settings'.
- From the settings window, select 'Version Control' then 'Git'.
- Point 'Path to Git executable:' to 'bin/git.exe', which will be located where you installed git.
- Hit the 'test' button to make sure git works, then press 'Okay' to return to the splash page.
After that, you will want to select 'check out project from version control' then 'git'. Log in to GitHub through the button (use username instead of tokens), and select your forked repository from the list of URLs. Import to whatever directory on your computer you like. Accept the default options android studio suggests when opening the project. If you would like more information about working with Git and commiting changes you make back to version control, [consult this guide](https://code.tutsplus.com/tutorials/working-with-git-in-android-studio--cms-30514) (skip to chapter 4).
If you are not using version control, select 'Import project (Gradle, Eclipse ADT, etc.)' and select the folder you unzipped the code into. Accept the default options android studio suggests when opening the project.
### Running the code
Once the code is open, you can run it from Android Studio by specifying the gradle command from the quick guide as a run configuration:
- Select 'Run' on the top toolbar, and then 'Edit Configurations...'.
- Click the + icon to add a new configuration, and select 'gradle'.
- Set 'Gradle project' to 'Shattered-pixel-dungeon', and 'tasks' to 'desktop:debug'
- Name the configuration whatever you like, and select 'Apply' and 'OK' on the bottom right.
That configuration is now saved and can be selected from the configurations dropdown menu. It can be ran using the green arrow icon, and debugged with the green bug icon.
### Generating a distributable JAR file
A JAR (Java ARchive) is a file used to distribute Java applications. Just as with running the code, a run configuration must be set up to create the jar. Follow the above steps, but with 'desktop:release' instead of 'desktop:debug'. Running this configuration will generate a distributable JAR file in the `/desktop/build/libs` folder.
Note that by distributing your modification of Shattered Pixel Dungeon, you are bound by the terms of the GPLv3 license, which requires that you make any modifications you have made open-source. If you followed this guide and are using version control, that is already set up for you as your forked repository is publicly hosted on GitHub. Just make sure to push any changes you make back to that repository.
Note that JAR files will require a (Java runtime enviroment)[https://java.com/en/download/win10.jsp] to be installed on a user's computer in order to work. In future this codebase will likely be expanded to allow bundling a java runtime with the application, so that a simple runnable EXE file can be generated.

View File

@ -0,0 +1,51 @@
This guide covers a few technical changes developers will likely want to make when creating their own Pixel Dungeon mod based on Shattered's source code.
## Application name, version name, and package name
There are a number of variables defined in the root [build.gradle](/build.gradle) file that you may want to change:
- `appName` defines the user-visible name of your app. Change this to whatever you wish to call your mod.
- `appPackageName` defines the internal name of your app. The Android operating system uses this name to distinguish your app from others. You must change this from its initial value or Android will think your mod is Shattered Pixel Dungeon.
- `appVersionCode` defines the internal version number of your app. You want to increment this whenever releasing a new version. Read the next section for more details on this one.
- `appVersionName` defines the user-visible version name of your app. Change this to whatever you like, and increment it whenever you release a new version.
The other variables do not need to be changed when setting up your own mod, they are mainly technical configurations that do not need to be adjusted.
Note that some guides may recommend that you change the package structure (i.e. the folder names) of the application. This used to be required for Pixel Dungeon mods, but is now optional as the `appPackageName` variable can be used instead.
## Application version code
Shattered Pixel Dungeon has an internal version code which should be incremented with each release. It is defined with the `appVersionCode` variable in the root [build.gradle](/build.gradle) file.
You may be tempted to set this value back to 1 when starting a new mod, but Shattered has various compatibility code for previous versions which may be incorrectly triggered if you decrement the version code. The version code is entirely internal so there is no harm in using the game's current version code as a starting point.
If you wish to set it to 1 anyway, the various constant variables toward the top of [ShatteredPixelDungeon.java](/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ShatteredPixelDungeon.java) are a good starting point for finding all of the cases where the game refers to the version code for compatibility purposes.
## Credits & Supporter button
If you are making your own mod, you will likely want to add yourself to the credits or change the current supporter link. Feel free to adjust these however you like, the relevant code is in [AboutScene.java](/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/AboutScene.java) and [TitleScene.java](/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/TitleScene.java). If you wish to disable the supporter link, simply comment out the line `add(btnSupport);` in [TitleScene.java](/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/TitleScene.java).
Note that due to the GPLv3 license, any edits you make to the credits scene must avoid removing any existing credits, though you can reposition them however you like. Additionally, while not required, I would appreciate leaving in a reference and a link to my Patreon, though you are free to add your own as well.
**Note that if you plan to distribute on Google Play, Google has a history of removing apps which mention Patreon, as they want all revenue earned via Google Play apps to go through them. It is therefore strongly advised that you disable the supporter button or replace the text within it if you want to release on Google Play.**
## Update Notification
Shattered Pixel Dungeon includes a github-based update notification which likely will not be useful for mod developers unless it is modified.
To simply disable the notification change `:services:updates:githubUpdates` to `:services:updates:debugUpdates` for the release configurations in the build.gradle files in the [desktop](/desktop/build.gradle) and [android](/android/build.gradle) modules. The debug updates module does nothing by default and so works just fine in release builds.
To modify the notification to point to your own github releases, go to [GitHubUpdates.java](/services/updates/githubUpdates/src/main/java/com/shatteredpixel/shatteredpixeldungeon/services/updates/GitHubUpdate.java) and change the line: `httpGet.setUrl("https://api.github.com/repos/00-Evan/shattered-pixel-dungeon/releases");` to match your own username and repository name. The github updater looks for a title, body of text followed by three dashes, and the phrase \` internal version number: # \` in your release.
More advanced modders can change the format for releases if they like, or make entirely new update notification services.
## Translations
Shattered Pixel Dungeon supporters a number of languages which are translated via a [community translation project](https://www.transifex.com/shattered-pixel/shattered-pixel-dungeon/).
If you plan to add new text to the game, maintaining these translations may be difficult or impossible, and so you may wish to remove them:
- In [Languages.java](/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/messages/Languages.java) remove all of the enum constants except for ENGLISH.
- In the [language resource folders](/core/src/main/resources/com/shatteredpixel/shatteredpixeldungeon/messages) remove all of the .properties files which include an underscore followed by a language code (e.g. remove actors_ru.properties, but not actors.properties)
- Finally remove the language picker by commenting out the line `add( btnLang );` in [TitleScene.java](/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/TitleScene.java)
- Optionally, if you are multilingual or have translators and wish to retain some languages, do not comment out the language picker and only remove the enums/resources for the languages you won't be using.
If you want to have a language other than English as the base language, you can simply remove the .properties files that do not have a language code, and remove the underscore+language code from the language you want to use. The game will consider this language to be English internally however, so you may want to look into where the ENGLISH variable is used and make adjustments accordingly, and possibly rename it.