Game UI (HUD)

Relevant source files

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

• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/Toolbar.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/StatusPane.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/QuickSlotButton.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/MenuPane.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/BossHealthBar.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/GameLog.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/hero/Hero.java

The Game User Interface (HUD) is the primary means by which players interact with and receive information about the game world in Shattered Pixel Dungeon. It is a composite of several distinct UI components, each responsible for a specific aspect of information display or player interaction. The entire HUD is constructed and managed within the GameScene class, which acts as the central orchestrator for all in-game UI elements.

The HUD is designed to be responsive, adapting its layout based on the device's screen size and orientation. It supports both a compact mobile view and an expanded desktop view, which includes a persistent inventory pane. The system is also designed to handle modern mobile device features like display notches and cutouts by dynamically adjusting the layout of its components.

Architecture Overview

The GameScene class is responsible for the creation, layout, and management of all HUD components. During its create() method, it instantiates and adds the various panes, toolbars, and indicators to the scene.

The diagram below illustrates the main components that form the Game UI and their relationship within the GameScene.

UI Component Summary

Component	Class	Description	Source File
Status Pane	StatusPane	Displays the hero's health, experience, level, buffs, and debuffs.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/StatusPane.java
Toolbar	Toolbar	Contains the main action buttons (Search, Wait, Inventory) and quickslots for items.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/Toolbar.java
Menu Pane	MenuPane	Located at the top-right, it provides access to the game menu, journal, and a display for collected keys.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/MenuPane.java
Game Log	GameLog	A text area that displays messages and descriptions of events happening in the game.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/GameLog.java
Inventory Pane	InventoryPane	A persistent inventory display available on large-screen (desktop) layouts.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java
Boss Health Bar	BossHealthBar	Appears at the top of the screen during boss fights to show the boss's current health.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/BossHealthBar.java
Action Indicators	AttackIndicator, LootIndicator, ActionIndicator	Context-sensitive buttons that appear for actions like attacking, picking up loot, or performing special actions.	core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java

Core Components

GameScene

The GameScene is the container for the entire in-game experience. It initializes and positions all UI elements, handles player input, and manages the main game loop's interaction with the UI.

A key responsibility of GameScene is adapting the UI to different screen configurations. In its create() method, it checks the SPDSettings.interfaceSize() and the device's safe area insets to determine the layout.

• UI Sizing: The interfaceSize setting determines whether to use the compact mobile UI or the larger desktop UI with the persistent InventoryPane.
• Display Cutout Handling: The scene calculates adjustments for display notches and hole-punch cutouts. It can modify the width and position of the StatusPane's health bar, the MenuPane, and the buff bar to avoid being obscured. This logic is implemented in GameScene.create() and the values are passed to the respective components.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java:252-320

The update() method in GameScene is responsible for synchronizing the UI with the game state, which is processed in a separate actorThread.

This diagram shows the logic within GameScene.update() for managing the actor thread and triggering UI updates.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java:433-470

Status Pane

The StatusPane is the primary display for the hero's vital statistics. It is located at the top of the screen in the mobile UI and at the top-left in the desktop UI.

It is composed of:

• Hero Avatar: Shows the hero's sprite.
• Health and Experience Bars: Visual indicators for the hero's current HP and XP. The HP bar blinks red at low health.
• Level Indicator: Shows the hero's current level.
• Buff/Debuff Icons: A dynamic list of BuffIndicator icons representing active status effects on the hero. The layout of these icons can be adjusted to accommodate display cutouts.

The layout is dynamically adjusted in GameScene to handle display cutouts. Properties like heroPaneExtraWidth, hpBarMaxWidth, buffBarRowMaxWidths, and buffBarRowAdjusts are set in GameScene and used by StatusPane during its layout phase.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java:270-320, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/StatusPane.java

Toolbar and QuickSlots

The Toolbar is the main action bar. In the mobile UI, it's at the bottom of the screen. In the desktop UI, it's positioned above the InventoryPane.

It contains:

1. Main Action Buttons:
   • Search (btnSearch)
   • Wait (btnWait)
   • Inventory (btnBag)
2. QuickSlot Buttons: A variable number of QuickSlotButton instances for rapid item use. Desktop UI has more quickslots than mobile.

The QuickSlotButton is a sophisticated component that represents a single quickslot.

• It can be assigned an Item.
• It automatically updates its icon, quantity, and visual state (e.g., cursed, upgraded) by observing the assigned item.
• Clicking a quickslot button can either use the item directly or enter a targeting mode if the item requires a target.

The following sequence diagram shows the process of using a targeted item from a quickslot.

Menu Pane

The MenuPane is a small panel at the top-right of the screen. It contains:

• A Keyring display that shows icons for each type of key the hero possesses (IronKey, GoldenKey, SkeletonKey, CrystalKey). The display is dynamically updated by the updateKeys() method.
• A Journal button that opens the journal window. It flashes when a new page is discovered.
• A Menu button that opens the main game menu (WndGame).

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/MenuPane.java:47-73, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java:265-269

Other UI Elements

• BossHealthBar: This element is managed by GameScene and becomes visible during boss encounters. It attaches to the boss Mob and displays its health.
  Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java:322-331, [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/BossHealthBar.java]
• GameLog: Positioned by GameScene, this log receives messages via the static GLog class, providing textual feedback to the player.
  Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java:342-345, [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/GameLog.java]
• Action/Status Indicators: GameScene manages several contextual indicators (AttackIndicator, LootIndicator, ActionIndicator, ResumeIndicator) that are positioned on the side of the screen. The layoutTags() method is responsible for their positioning, which can be flipped to the left or right side based on user settings.
  Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java:500-551

Conclusion

The Game UI in Shattered Pixel Dungeon is a modular and robust system orchestrated by the GameScene class. Each component has a clearly defined responsibility, from displaying hero status in the StatusPane to handling item usage in the Toolbar and QuickSlotButton. The architecture is notable for its adaptability to different screen sizes and its thoughtful handling of modern device constraints like display cutouts, ensuring a consistent and usable interface across all supported platforms. The separation of the UI from the game logic (managed in the actorThread) allows for a responsive user experience even while complex game calculations are being performed.