Build Shattered Pixel Dungeon in Android Studio (Windows 10)

October 9, 2021

The developer's instructions are at this link:

https://github.com/00-Evan/shattered-pixel-dungeon/blob/master/docs/getting-started-android.md

It's recommended to log in to GitHub and fork the project under your account.

Otherwise, you will need to click Code and copy the address for local cloning: https://github.com/00-Evan/shattered-pixel-dungeon.git

Install Android Studio

Download Android Studio 2020.3.1 here: https://developer.android.com/studio

[TODO: repeat basic installation steps here]

Create an access token in your GitHub profile (https://github.com/settings/profile)

Click "Developer Settings", "Personal access tokens", "Generate new token".

Enter the description (Android Studio) and enable "repo", "admin:read", "gist" permissions.

Click "Generate token".

Copy the token string.

Load Shattered Pixel Dungeon in Android Studio

In the Android Studio "Welcome to Android Studio" dialog:

Click "Get from VCS".

In the "Get from Version Control" dialog, paste the Token and click "Log in".

Select "shattered-pixel-dungeon", type the local directory path, and click "Clone".

There will be errors if the correct Google SDKs aren't selected. Example:

Unable to find method ''void org.apache.commons.compress.archivers.zip.ZipFile.<init>(java.nio.channels.SeekableByteChannel)''

'void org.apache.commons.compress.archivers.zip.ZipFile.<init>(java.nio.channels.SeekableByteChannel)'

Use the "Tools" menu, "SDK Manager".

Under "SDK Platforms", enable "Android 8.0" through "Android 12.0". Click "Apply", "OK".

Components will install, then click "Finish".

Under "SDK Tools", click "Show Package Details".

Expand "Android SDK Build Tools 31" select "30.0.2" and "26.0.3" and click "OK", "OK".

Click "Finish" once downloaded.

Resume with "File", "Sync project with Gradle files".

Android Studio may offer to upgrade the project Gradle version. Accept and click "Begin Upgrade".

Click "Run selected steps".

Minimize the "Upgrade Assistant" once the upgrade is complete.

Change App Name (optional)

Use the "Edit" menu, "Find", "Replace in Files..." to locate com.shatteredpixel.shatteredpixeldungeon

In the "Replace" field, enter your fully qualified internal app name (i.e. com.axus.testpixeldungeon) and click "Replace All".

Find and replace Shattered Pixel Dungeon with your app name (i.e. Axus Pixel Dungeon Test).

Save and close the project.

Search the top level directory for "shatteredpixel".

Replace all folder names "shatteredpixel" with your internal app group (i.e. axus). These would all be subdirectories of "com".

Repeat the search.

Replace "shatteredpixeldungeon" with your internal app name (i.e. testpixeldungeon)

If you changed "com" to something else, replace "com" directories.

Build Shattered Pixel Dungeon in Android Studio

Use Build menu, Rebuild Project

There will be errors when APK signing has not been configured or you are missing "26.0.3":

Could not initialize class org.bouncycastle.operator.DefaultSignatureAlgorithmIdentifierFinder

Use the Build menu, Generate Signed Bundle / APK

Click "Next" to accept "Android App Bundle".

Click "Create new..."

If you are extra paranoid, browse to a "Key store path" on a removable USB drive. Otherwise, the .android subdirectory of your home folder. Enter a file name and click "OK".

Don't forget to make a backup!

Enter a password for the new key store.

The key "Alias" is an identifier for this app's key, i.e. shattered-clone

Enter a password for the app key.

Enter certificate information; e.g.

First and Last Name: Axus Grad
Organizational Unit: Dev
Organization: axus.club
City or Locality: Washington
State or Province: DC
Country Code: US

Click "OK".

Enter the "Key store password" and "Key password". "Key alias" should already be filled in.

Select a path to export the Google Play key, usually the project directory.

Click "Next".

Select "debug" and click "Finish".

Android Studio Settings

You may get a warning that "Your anti-virus program might be impacting build performance.

Click the Windows Start button and type Antivirus. Click "Virus & thread protection".

Scroll down to "Exclusions". Click "Add or remove exclusions".

Click "+ Add an exclusion", "Folder".

Navigate to "C:\Users\", username, ".gradle\.tmp".

Click "Select Folder".

Click "Yes" to approve the exclusion.

Repeat for the "shattered-pixel-dungeon\android\build" folder.

Connecting Android Device

Connect your device to PC with USB cable.

To enable USB debugging, on the phone go to Settings > System > About phone and tap Build number seven times.

Go to Settings > System > Developer Options.

Enable USB debugging.

Open Tools, Troubleshoot Device Connections. Click "Rescan devices".

On the Android device, check the box to "Always allow debugging from this device".

If it was not detected, click "Next", "Restart ADP server".

If "ADB could not be located", use Windows Task Manager to kill adb.exe and try again.

Testing on Android Device

Connect your device to PC with USB cable.

Use the "Run" menu to "Run android". It will install to the device and run.

Possible error with the signing process:

Installation did not succeed.
The application could not be installed: INSTALL_PARSE_FAILED_NO_CERTIFICATES

List of apks:
[0] 'release\..\..\extracted_apks\release\base-armeabi_v7a.apk'
[1] 'release\..\..\extracted_apks\release\base-master.apk'
[2] 'release\..\..\extracted_apks\release\base-xhdpi.apk'

APK signature verification failed.

So, fix the APK signing!

Release App Bundle to Google Play for testing

Use "Build" menu, "Generate Signed Bundle / APK ..."

Click "Next" to accept "Android App Bundle".

Enter the "Key store password" and "Key password". "Key alias" should already be filled in.

Select "release" and click "Finish" to create the signed bundle.

In the event log, click "locate" to open the folder with the app bundle.

Log in to the Google Play Console (play.google.com/console).

Navigate to "Release", "Internal testing".

Drag the .aab file from the release folder to the designated area on the web page. Google will analyze it, and report any problems.

If there are no problems, fill in "Release name", "Release notes".

Click "Save".