/Alonso-pixel/shattered-pixel-dungeon

Wiki directory

Browse AI-generated documentation for any repository.

Windows & Panes System

Relevant source files

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

The Windows and Panes system is a core part of Shattered Pixel Dungeon's user interface, responsible for displaying modal dialogs, informational screens, and interactive menus. The system is built around a base Window class, which is extended to create specialized windows for various purposes. These windows are composed of smaller UI components like panes, lists, buttons, and text blocks to create rich, interactive displays.

Key features of this system include scrollable content areas, consistent styling through a shared color palette, and a component-based architecture that allows for flexible and varied UI layouts. This is evident in complex screens like the game's changelog, the journal, and the score breakdown, which all leverage these underlying components to present information to the player.

Core Components and Concepts

The system is built from several key components that are reused across different windows and scenes.

Window Styling

A consistent visual style is maintained across windows using a predefined set of colors applied via a hardlight method. This allows for semantic coloring to convey information to the player.

Constant	Hex Value (Inferred)	Usage	Source
`Window.TITLE_COLOR`	`0xFFA500` (Orange)	Used for window titles, version numbers, and important "New" sections in the changelog.	`[v0_6_X_Changes.java:68](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/v0_6_X_Changes.java#L68)`
`CharSprite.POSITIVE`	`0x00FF00` (Green)	Used for "Buffs" sections in the changelog.	`[v0_6_X_Changes.java:189](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/v0_6_X_Changes.java#L189)`
`CharSprite.NEGATIVE`	`0xFF0000` (Red)	Used for "Nerfs" sections in the changelog.	`[v0_6_X_Changes.java:208](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/v0_6_X_Changes.java#L208)`
`CharSprite.WARNING`	`0xFFFF00` (Yellow)	Used for "Changes" sections in the changelog.	`[v0_6_X_Changes.java:138](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/v0_6_X_Changes.java#L138)`
`Window.WHITE`	`0xFFFFFF` (White)	Used to indicate a read document page.	`[WndDocument.java:46](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/WndDocument.java#L46)`
`0x999999`	`0x999999` (Grey)	Used for missing document pages or disabled elements.	`[WndDocument.java:53](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/WndDocument.java#L53)`

Sources: ui/changelist/v0_6_X_Changes.java, windows/WndDocument.java

Panes and Scrollable Content

Many windows need to display more content than can fit on the screen. This is handled by scrollable panes.

ScrollPane: A generic container for a component that allows vertical scrolling. It is used in the AboutScene to display a long list of credits.
Sources: scenes/AboutScene.java:51
ScrollingListPane: A specialized pane used in WndDocument to display a list of items. It supports adding a title and individual list items.
Sources: windows/WndDocument.java:31

The following diagram shows how a scrollable window like WndDocument is composed.

Generating architecture diagram...

This diagram illustrates the logic within WndDocument for creating and styling list items based on the document's state. Sources: windows/WndDocument.java:34-59

Window Implementations

The repository contains several concrete implementations of windows, each tailored for a specific purpose.

Changelog System

The ChangesScene displays the game's version history. It is dynamically built from static methods in v*_X_Changes.java files. This system is not a single Window but a collection of ChangeInfo objects that act as collapsible panes.

ChangeInfo: Represents a specific version or a category of changes (e.g., "New", "Buffs", "Nerfs"). It contains a title and a list of ChangeButtons.
ChangeButton: An interactive element within a ChangeInfo pane. It consists of an icon and a text block describing a specific change.

The structure of the changelog is hierarchical, as shown below.

Generating architecture diagram...

This diagram shows the relationship between the ChangesScene, ChangeInfo panes, and ChangeButton elements. Sources: ui/changelist/v1_X_Changes.java:60-90

`WndDocument`

This window is used to display the contents of a Document, such as the in-game lore pages. It presents a list of pages, indicating whether each page has been found and read.

It uses a ScrollingListPane to manage the list of pages.
Each page is represented by a ScrollingListPane.ListItem.
The onClick handler for each list item checks if the page has been found. If so, it creates and displays a WndStory to show the page content and marks the page as read.
The visual state of each item (color) is updated based on whether the page is unread (TITLE_COLOR), read (WHITE), or missing (0x999999).

Sources: windows/WndDocument.java:29-62

`WndScoreBreakdown`

This window provides a detailed breakdown of the player's score at the end of a run. It is a static, non-interactive window that uses RenderedTextBlock components to display formatted text.

An IconTitle is used for the main window title.
The layout is constructed by sequentially adding text blocks for each score category.
The statSlot helper method is responsible for creating a line with a label and a value, aligning the value to the right.
The addInfo helper method adds a smaller, greyed-out description text below a score category.
Score categories that meet a certain threshold are highlighted with Window.TITLE_COLOR to draw the player's attention.

Sources: windows/WndScoreBreakdown.java:35-98

`AboutScene`

While technically a Scene and not a Window, the AboutScene uses the same pane-based layout principles. It displays the game's credits in a vertically scrollable view.

It uses a ScrollPane to contain all credit information.
A custom CreditsBlock component is used to group related credits (e.g., for Shattered PD, Pixel Dungeon, libGDX).
Each CreditsBlock can contain a title, an avatar image, body text, and a clickable hyperlink, demonstrating the composition of complex UI elements from simpler ones.

Sources: scenes/AboutScene.java:48-118

Windows & Panes System

Relevant source files

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

Core Components and Concepts

The system is built from several key components that are reused across different windows and scenes.

Window Styling

A consistent visual style is maintained across windows using a predefined set of colors applied via a hardlight method. This allows for semantic coloring to convey information to the player.

Constant	Hex Value (Inferred)	Usage	Source
`Window.TITLE_COLOR`	`0xFFA500` (Orange)	Used for window titles, version numbers, and important "New" sections in the changelog.	`[v0_6_X_Changes.java:68](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/v0_6_X_Changes.java#L68)`
`CharSprite.POSITIVE`	`0x00FF00` (Green)	Used for "Buffs" sections in the changelog.	`[v0_6_X_Changes.java:189](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/v0_6_X_Changes.java#L189)`
`CharSprite.NEGATIVE`	`0xFF0000` (Red)	Used for "Nerfs" sections in the changelog.	`[v0_6_X_Changes.java:208](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/v0_6_X_Changes.java#L208)`
`CharSprite.WARNING`	`0xFFFF00` (Yellow)	Used for "Changes" sections in the changelog.	`[v0_6_X_Changes.java:138](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/v0_6_X_Changes.java#L138)`
`Window.WHITE`	`0xFFFFFF` (White)	Used to indicate a read document page.	`[WndDocument.java:46](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/WndDocument.java#L46)`
`0x999999`	`0x999999` (Grey)	Used for missing document pages or disabled elements.	`[WndDocument.java:53](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/WndDocument.java#L53)`

Sources: ui/changelist/v0_6_X_Changes.java, windows/WndDocument.java

Panes and Scrollable Content

Many windows need to display more content than can fit on the screen. This is handled by scrollable panes.

ScrollPane: A generic container for a component that allows vertical scrolling. It is used in the AboutScene to display a long list of credits.
Sources: scenes/AboutScene.java:51
ScrollingListPane: A specialized pane used in WndDocument to display a list of items. It supports adding a title and individual list items.
Sources: windows/WndDocument.java:31

The following diagram shows how a scrollable window like WndDocument is composed.

Generating architecture diagram...

This diagram illustrates the logic within WndDocument for creating and styling list items based on the document's state. Sources: windows/WndDocument.java:34-59

Window Implementations

The repository contains several concrete implementations of windows, each tailored for a specific purpose.

Changelog System

ChangeInfo: Represents a specific version or a category of changes (e.g., "New", "Buffs", "Nerfs"). It contains a title and a list of ChangeButtons.
ChangeButton: An interactive element within a ChangeInfo pane. It consists of an icon and a text block describing a specific change.

The structure of the changelog is hierarchical, as shown below.

Generating architecture diagram...

This diagram shows the relationship between the ChangesScene, ChangeInfo panes, and ChangeButton elements. Sources: ui/changelist/v1_X_Changes.java:60-90

`WndDocument`

This window is used to display the contents of a Document, such as the in-game lore pages. It presents a list of pages, indicating whether each page has been found and read.

It uses a ScrollingListPane to manage the list of pages.
Each page is represented by a ScrollingListPane.ListItem.
The onClick handler for each list item checks if the page has been found. If so, it creates and displays a WndStory to show the page content and marks the page as read.
The visual state of each item (color) is updated based on whether the page is unread (TITLE_COLOR), read (WHITE), or missing (0x999999).

Sources: windows/WndDocument.java:29-62

`WndScoreBreakdown`

This window provides a detailed breakdown of the player's score at the end of a run. It is a static, non-interactive window that uses RenderedTextBlock components to display formatted text.

An IconTitle is used for the main window title.
The layout is constructed by sequentially adding text blocks for each score category.
The statSlot helper method is responsible for creating a line with a label and a value, aligning the value to the right.
The addInfo helper method adds a smaller, greyed-out description text below a score category.
Score categories that meet a certain threshold are highlighted with Window.TITLE_COLOR to draw the player's attention.

Sources: windows/WndScoreBreakdown.java:35-98

`AboutScene`

While technically a Scene and not a Window, the AboutScene uses the same pane-based layout principles. It displays the game's credits in a vertically scrollable view.

It uses a ScrollPane to contain all credit information.
A custom CreditsBlock component is used to group related credits (e.g., for Shattered PD, Pixel Dungeon, libGDX).
Each CreditsBlock can contain a title, an avatar image, body text, and a clickable hyperlink, demonstrating the composition of complex UI elements from simpler ones.

Sources: scenes/AboutScene.java:48-118