Compiling for Android

Relevant source files

The following files were used as context for generating this wiki page:

• android/build.gradle
• android/src/main/java/com/shatteredpixel/shatteredpixeldungeon/android/AndroidLauncher.java
• android/src/main/AndroidManifest.xml
• README.md
• 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/v0_7_X_Changes.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java
• ios/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ios/IOSPlatformSupport.java

Shattered Pixel Dungeon is a cross-platform roguelike dungeon crawler that compiles for Android, iOS, and Desktop platforms. The Android build is a primary distribution target, available on the Google Play Store and other platforms. The project utilizes the libGDX framework, which allows for a shared core codebase with platform-specific launchers.

The build system is managed by Gradle, which handles dependencies, build configurations, and packaging for the Android application (APK/AAB). The project is structured into modules, with the core module containing the platform-independent game logic and the android module containing the necessary code and configurations to launch the game on Android devices. For more detailed setup instructions, developers can refer to the Compiling for Android guide.

Sources: README.md

Project Structure

The project uses a multi-module Gradle setup to separate shared game logic from platform-specific code. The android module depends on the core module. This architecture is crucial for maintaining a single codebase for the game's logic while allowing for native integrations and launch procedures on different platforms like Android, iOS, and Desktop.

The diagram below illustrates the dependency relationship between the main modules.

The conversion to a libGDX-based structure was a significant step, making the core module platform-independent and enabling easier builds for multiple platforms.

Sources: README.md, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:200-205

Android Build Configuration

The Android build is configured in the android/build.gradle file. This file defines SDK versions, application ID, versioning, dependencies, and signing configurations required to build the Android app.

SDK and Application Versions

The build configuration specifies the target Android SDK and the minimum version required to run the game. These values have evolved over time to support new Android features and meet platform requirements.

Property	Description	Example Value	Source
minSdkVersion	The minimum API level required for the app to run.	21 (Android 5.0)	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v3_X_Changes.java:232-233
targetSdkVersion	The API level the app is designed for.	33 or higher	Inferred from modern Android requirements.
applicationId	The unique package name for the application.	com.shatteredpixel.shatteredpixeldungeon	README.md (Google Play link)
versionCode	An integer representing the version of the application.	Incremental integer	Inferred from standard Android practice.
versionName	A string representing the public version of the application.	e.g., "v2.5.0"	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:51

The minimum required Android version has been raised over time, for instance, from 4.0 to 5.0 in version 3.2.2.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v3_X_Changes.java:232-233, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:230-231

Dependencies

The android module depends on the libGDX backend for Android (gdx-backend-android) and the shared core project module.

// Example from android/build.gradle
dependencies {
    implementation project(':core')
    api "com.badlogicgames.gdx:gdx-backend-android:$gdxVersion"
    // ... other dependencies
}

This snippet shows the dependency on the core project and the libGDX Android backend.

Application Manifest

The AndroidManifest.xml file describes essential information about the application to the Android system. This includes the package name, application components, permissions, and required hardware features.

Main Activity

The manifest declares AndroidLauncher as the main activity, which serves as the entry point for the application.

<!-- Example from AndroidManifest.xml -->
<activity
    android:name="com.shatteredpixel.shatteredpixeldungeon.android.AndroidLauncher"
    android:label="@string/app_name"
    android:screenOrientation="portrait"
    android:configChanges="keyboard|keyboardHidden|navigation|orientation|screenSize|screenLayout|uiMode"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

This manifest entry defines the main launcher activity for the application.

Features and Settings

The manifest also defines various application-level settings and features.

Feature/Setting	Description	Source
android:allowBackup	Enables or disables application data backup via ADB and Auto Backup. Set to true.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java:266-267
android:isGame	Declares the application as a game to the Android system. Set to true.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:181
Themed Icon Support	The app supports themed icons on Android 13+.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:406
Fullscreen Rendering	Menu screens render in true edge-to-edge fullscreen on Android 9+.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v3_X_Changes.java:228-229

Application Launch Sequence

The Android application is launched through the AndroidLauncher class, which is a standard implementation for a libGDX project on Android.

The AndroidLauncher Class

This class extends AndroidApplication from the libGDX framework. Its primary responsibility is to initialize the libGDX application with the core game logic and an Android-specific configuration.

// Simplified example from AndroidLauncher.java
public class AndroidLauncher extends AndroidApplication {
    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        AndroidApplicationConfiguration config = new AndroidApplicationConfiguration();
        // ... configuration settings
        initialize(new ShatteredPixelDungeon(), config);
    }
}

The launch sequence involves the Android OS creating an instance of AndroidLauncher, which in turn creates an instance of the core game class ShatteredPixelDungeon and passes it to the libGDX framework.

Platform-Specific Code

While most game logic resides in the core module, platform-specific features are handled in their respective modules. A comparison with the iOS implementation highlights the role of the Android module. For example, the ios/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ios/IOSPlatformSupport.java file contains complex logic to handle display cutouts like the "Dynamic Island" and to manage haptic feedback on different iPhone models.

// From ios/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ios/IOSPlatformSupport.java
public class IOSPlatformSupport extends PlatformSupport {
    // ...
	@Override
	public RectF getDisplayCutout() {
		// ... magic number BS for larger status bar caused by dynamic island
		boolean hasDynamicIsland = topInset / Gdx.graphics.getBackBufferScale() >= 51;
        // ... logic to estimate cutout size
    }

    public void vibrate(int millis ){
		if (ControllerHandler.isControllerConnected()){
			ControllerHandler.vibrate(millis);
		} else if (Gdx.input.isPeripheralAvailable(Input.Peripheral.HapticFeedback)){
			Gdx.input.vibrate( millis );
		} else {
			//devices without haptics but with 3d touch use a short vibrate
			AudioServices.playSystemSound(1520);
		}
	}
    // ...
}

This code from the iOS module shows platform-specific handling for display cutouts and vibration, which would be implemented differently in the Android module using Android-specific APIs.

Sources: ios/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ios/IOSPlatformSupport.java:56-76, 137-148

The Android module would contain similar platform-specific classes to handle features like Google Play Games integration, in-app purchases, and Android-specific UI behaviors, as mentioned in various changelogs.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_8_X_Changes.java:237-244, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_2_X_Changes.java:166-167