Platform-Specific Integration

Relevant source files

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

• SPD-classes/src/main/java/com/watabou/utils/PlatformSupport.java
• android/src/main/java/com/shatteredpixel/shatteredpixeldungeon/android/AndroidPlatformSupport.java
• desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopPlatformSupport.java
• ios/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ios/IOSPlatformSupport.java
• README.md

Shattered Pixel Dungeon is a cross-platform game, compiling for Android, iOS, and Desktop environments. To manage the differences between these platforms, the game utilizes a platform abstraction layer. This system is centered around the PlatformSupport abstract class, which defines a common interface for platform-dependent functionalities. Each target platform (Android, iOS, Desktop) provides a concrete implementation of this class, handling specifics such as display management, font rendering, hardware interaction, and network status checks.

This architecture allows the core game logic to remain platform-agnostic, interacting with a consistent API for services that vary between operating systems. This is a crucial design pattern that enables the game's portability and maintainability across its supported platforms.

Sources: README.md, SPD-classes/src/main/java/com/watabou/utils/PlatformSupport.java

Architecture Overview

The platform integration system is built on an abstract base class, PlatformSupport, which declares a set of methods that the core game logic depends on. Each platform-specific module (Android, Desktop, iOS) contains a concrete subclass that implements these methods using platform-native APIs.

Sources: SPD-classes/src/main/java/com/watabou/utils/PlatformSupport.java, android/src/main/java/com/shatteredpixel/shatteredpixeldungeon/android/AndroidPlatformSupport.java, desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopPlatformSupport.java, ios/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ios/IOSPlatformSupport.java

Class Diagram

The following diagram illustrates the inheritance structure of the PlatformSupport system.

Core PlatformSupport Interface

The PlatformSupport class defines the contract for all platform-specific implementations. It contains a mix of abstract methods that must be overridden and concrete methods with default or shared logic.

Sources: SPD-classes/src/main/java/com/watabou/utils/PlatformSupport.java

Key Methods

Method	Description
updateDisplaySize()	Abstract. Called to handle changes in display size, often to persist the new dimensions.
updateSystemUI()	Abstract. Manages system UI elements like fullscreen mode, status bars, and navigation bars.
getSafeInsets(int level)	Returns the safe area insets of the display to avoid notches, cutouts, and system bars. The level parameter determines the sensitivity to different types of insets.
getDisplayCutout()	Returns the bounding box of a display cutout (e.g., a notch), if present.
connectedToUnmeteredNetwork()	Abstract. Checks if the device is connected to a non-metered network (e.g., Wi-Fi).
supportsVibration()	Abstract. Checks if the device or a connected controller supports vibration.
vibrate(int millis)	Triggers device or controller vibration for a specified duration. Prioritizes controller vibration if available.
setupFontGenerators(...)	Abstract. Initializes FreeTypeFontGenerator instances for rendering text.
getFont(...)	Retrieves or generates a BitmapFont for a given text string, size, and style.
splitforTextBlock(...)	Abstract. Splits a string into renderable chunks, accounting for language-specific line-breaking rules (e.g., for CJK characters).

Sources: SPD-classes/src/main/java/com/watabou/utils/PlatformSupport.java:31-163

Platform-Specific Implementations

Each platform provides a concrete class that tailors these abstract functionalities to the specific operating system and hardware.

Android

The AndroidPlatformSupport class handles integration with the Android OS.

• System UI: updateSystemUI() manipulates Android View flags to control fullscreen mode, status bar, and navigation bar visibility. It supports different UI modes for modern Android versions.
• Safe Area & Cutouts: getSafeInsets() and getDisplayCutout() use the Android DisplayCutout API (available on API 28+) to safely position UI elements around screen notches and hole-punch cameras.
• Network: connectedToUnmeteredNetwork() queries Android's ConnectivityManager to check for an unmetered network connection.
• Vibration: supportsVibration() checks if the device has a Vibrator service.
• Fonts: It uses pixel_font.ttf for most languages and falls back to droid_sans.ttf for Asian languages, determined by a regex matcher.

Sources: android/src/main/java/com/shatteredpixel/shatteredpixeldungeon/android/AndroidPlatformSupport.java

Desktop

The DesktopPlatformSupport class is tailored for PC environments (Windows, macOS, Linux) using LWJGL3.

• System UI: updateSystemUI() uses Gdx.graphics.setFullscreenMode() and Gdx.graphics.setWindowedMode() to toggle between fullscreen and windowed display. It includes logic to manage window state across multiple monitors.
• Display Size: updateDisplaySize() persists the window resolution to settings, with special handling to avoid saving the resolution of a maximized window.
• Network: connectedToUnmeteredNetwork() always returns true, assuming desktop users are on unmetered connections.
• Vibration: supportsVibration() delegates to ControllerHandler.vibrationSupported() to check for vibration capabilities in connected game controllers.
• Fonts: It uses a Pattern (asianMatcher) to detect CJK, Hiragana, or Katakana characters to decide whether to use the standard pixel font or the Droid Sans fallback for Asian characters.

The following diagram shows the flow for updating the display mode on desktop.

iOS

The IOSPlatformSupport class handles integration with Apple's iOS.

• System UI: updateSystemUI() is empty, as most system UI is managed by the OS and cannot be directly controlled by the app in the same way as on Android or Desktop.
• Vibration: vibrate() uses the modern Haptics API if available, providing more nuanced feedback than the standard Gdx.input.vibrate().
• Silent Switch: It provides a unique setHonorSilentSwitch(boolean value) method to respect the state of the physical silent switch on iPhones.
• Fonts: It uses a specific regex pattern (iosSplitter) to handle string splitting for text layout, adapted for the platform's needs.

Sources: ios/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ios/IOSPlatformSupport.java

Font Rendering

A significant responsibility of the PlatformSupport layer is text rendering. The system uses LibGDX's FreeTypeFontGenerator to generate bitmap fonts from .ttf files at runtime.

This process is abstracted to handle different character sets. A primary font (pixel_font.ttf) is used for Latin and Cyrillic scripts, while a fallback font (droid_sans.ttf) is used for Asian scripts (CJK, Hangul, Hiragana, Katakana). Each platform implementation contains logic to detect which generator to use for a given string.

The splitforTextBlock method is also critical, providing platform-specific regex patterns to split text into words or characters for proper layout, especially for languages that don't use spaces.

The flow for selecting a font generator on Desktop is as follows:

Summary

The PlatformSupport system is a well-defined abstraction layer that effectively decouples the core game from platform-specific dependencies. By defining a clear interface and providing tailored implementations for Android, iOS, and Desktop, it ensures that Shattered Pixel Dungeon can deliver a consistent experience while leveraging the unique capabilities of each platform. This design is fundamental to the game's successful multi-platform distribution and ongoing development.