Compiling for Desktop
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopLauncher.java
- desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopPlatformSupport.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_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/v3_X_Changes.java
Shattered Pixel Dungeon is a cross-platform game that compiles for Android, iOS, and Desktop. The desktop version is built using the libGDX framework with the LWJGL3 backend, providing a native-like experience on Windows, macOS, and Linux. This document outlines the technical architecture and configuration of the desktop build.
The project provides official guides for compilation, including one for desktop platforms, which can be found in the /docs directory of the repository.
Sources: README.md
Application Entry Point and Launch Sequence
The entry point for the desktop application is the main method within the DesktopLauncher class. This class is responsible for initializing the game window, setting up platform-specific configurations, and handling the application lifecycle.
The launch sequence can be visualized as follows:
This diagram shows the step-by-step process inside the DesktopLauncher's main method, from initial validation to launching the game.
Sources: desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopLauncher.java:44-183
Pre-launch Validation
Before any game logic is executed, DesktopLaunchValidator.verifyValidJVMState(args) is called. This method ensures that the Java Virtual Machine environment is suitable for running the game.
Sources: desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopLauncher.java:46-48
Exception Handling
A default uncaught exception handler is set up to provide user-friendly crash reports. It uses TinyFileDialogs to display a message box containing the game version and a simplified stack trace. This helps in debugging by giving users a clear way to report critical errors. For specific errors like Couldn’t create window, a more targeted message is shown to help diagnose graphics driver or OpenGL support issues.
Sources: desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopLauncher.java:57-101
Window and Application Configuration
The DesktopLauncher class configures the application window and behavior using Lwjgl3ApplicationConfiguration.
OS-Specific Save Paths
The game determines the base path for storing preferences and save files based on the operating system. This ensures that game data is stored in standard user data locations for each platform.
| Operating System | Base Path | FileType |
|---|---|---|
| Windows (not XP) | AppData/Roaming/.[vendor]/[title]/ | External |
| Windows XP | Application Data/.[vendor]/[title]/ | External |
| macOS | Library/Application Support/[title]/ | External |
| Linux/FreeBSD | $XDG_DATA_HOME/.[vendor]/[title-linux]/ | Absolute |
[vendor]is extracted from the package's implementation title (e.g., "shatteredpixel").[title]is the application title (e.g., "Shattered Pixel Dungeon").[title-linux]is the lower-cased, space-replaced title.
Sources: desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopLauncher.java:138-164
Window Properties
The following window properties are configured:
| Property | Value/Source | Description |
|---|---|---|
Title | Read from package specification | Sets the window title. |
WindowSizeLimits | Min: 720x400, Max: -1x-1 | Sets the minimum window dimensions. |
WindowedMode | SPDSettings.windowResolution() | Sets the initial window size from saved settings. |
Maximized | SPDSettings.windowMaximized() | Restores the window's maximized state. |
WindowIcon | Paths to icon files | Sets multiple icon sizes for the application. |
The game starts in windowed mode and then switches to fullscreen if configured, as a workaround for launch bugs. This is handled in DesktopPlatformSupport.updateSystemUI.
Sources: desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopLauncher.java:166-181, desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopPlatformSupport.java:55-78
Platform-Specific Support
The DesktopPlatformSupport class provides desktop-specific implementations for features that vary across platforms.
This diagram illustrates how DesktopLauncher instantiates and uses DesktopPlatformSupport to provide a platform-specific implementation to the core ShatteredPixelDungeon game class.
Sources: desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopLauncher.java:183, desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopPlatformSupport.java
Display and UI
- Fullscreen and Multi-monitor: The
updateSystemUImethod handles setting the game to fullscreen mode on the correct monitor. It reads the desired monitor index fromSPDSettingsand usesGdx.graphics.setFullscreenMode()to apply it. - Window Size: The
updateDisplaySizemethod is called when the window is resized. It saves the new window dimensions toSPDSettings, but includes a workaround to avoid saving the dimensions of a maximized window. - Vibration: Vibration is supported only via a controller, checked with
ControllerHandler.vibrationSupported().
Sources: desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopPlatformSupport.java:31-78, desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopPlatformSupport.java:86-89
Font Rendering
The desktop build uses FreeTypeFontGenerator to render text. A dual-font strategy is employed to support a wide range of languages:
pixel_font.ttf: The primary custom pixel font used for Latin and Cyrillic characters.droid_sans.ttf: A fallback font used for Asian languages (Hangul, CJK, Hiragana, Katakana).
The getGeneratorForString method uses a regular expression (asianMatcher) to detect if a given string contains Asian characters and selects the appropriate font generator. This ensures that the game maintains its pixelated aesthetic where possible while still supporting languages with complex character sets.
// desktop/src/main/java/com/shatteredpixel/shatteredpixeldungeon/desktop/DesktopPlatformSupport.java:120-123
private static Matcher asianMatcher = Pattern.compile("\\p{InHangul_Syllables}|" +
"\\p{InCJK_Unified_Ideographs}|\\p{InCJK_Symbols_and_Punctuation}|\\p{InHalfwidth_and_Fullwidth_Forms}|" +
"\\p{InHiragana}|\\p{InKatakana}").matcher("");
Summary
The desktop build of Shattered Pixel Dungeon is a well-configured libGDX application that leverages the LWJGL3 backend. The DesktopLauncher class serves as the central point for configuration, handling OS-specific paths, window settings, and robust exception reporting. Platform-specific features like font rendering and display management are abstracted into the DesktopPlatformSupport class, allowing the core game logic to remain platform-agnostic. This architecture results in a stable and native-feeling desktop application for Windows, macOS, and Linux users.