Levels, Regions, & Rooms
Relevant source files
The following files were used as context for generating this wiki page:
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/Dungeon.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/RegularLevel.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/SewerLevel.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/MiningLevel.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/HallsLevel.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/standard/entrance/EntranceRoom.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/special/DemonSpawnerRoom.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/standard/ChasmRoom.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/tiles/DungeonTileSheet.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/quest/BlacksmithRoom.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/special/WeakFloorRoom.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/standard/SegmentedLibraryRoom.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/quest/RitualSiteRoom.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/special/MagicWellRoom.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/rooms/standard/RuinsRoom.java
The procedural generation of the dungeon in Shattered Pixel Dungeon is a core system that ensures a unique experience for every playthrough. This system is built upon a hierarchy of concepts: the Dungeon manages the overall progression through Levels, which are constructed from a collection of Rooms. Each Level belongs to a specific region (e.g., Sewers, Caves), which defines its theme, enemies, and special features.
The generation process is highly modular, with different Level subclasses defining the characteristics of each region and various Room subclasses providing specific layouts and content. This architecture allows for a wide variety of level structures and encounters, from standard corridors to unique quest rooms and hidden secrets. The entire process is driven by a seeded random number generator, ensuring that a given seed will always produce the same dungeon layout.
Level Generation Architecture
The creation of a new dungeon level is a multi-stage process orchestrated by the Dungeon and RegularLevel classes. It involves initializing a set of rooms, arranging them into a coherent layout, and then "painting" the level with terrain, items, and mobs.
Sources: Dungeon.java:214-281, RegularLevel.java:65-81
Generation Flow
The following diagram illustrates the high-level flow of level generation, starting from the Dungeon.newLevel() call.
This diagram shows the sequence of method calls for generating a new level.
Sources: Dungeon.java:214, RegularLevel.java:65, RegularLevel.java:84, RegularLevel.java:141
Key Components
| Component | Class | Description | Source File |
|---|---|---|---|
| Level Manager | Dungeon | Manages overall game state, including current depth, and initiates the creation of new levels. | Dungeon.java |
| Level Template | RegularLevel | An abstract class that defines the core generation logic for most dungeon floors. | RegularLevel.java |
| Layout Builder | Builder | An interface (inferred) with implementations like LoopBuilder and FigureEightBuilder that arrange rooms into a map. | RegularLevel.java:142-153 |
| Content Painter | Painter | An interface (inferred) with implementations like SewerPainter that fill the arranged rooms with terrain, traps, and other features. | SewerLevel.java:100-104 |
Dungeon Regions
The dungeon is divided into five main regions, plus a final area. Each region spans four floors, followed by a boss level. The Dungeon.newLevel() method acts as a factory, instantiating the appropriate Level subclass based on the current depth.
Sources: Dungeon.java:217-268
| Depth | Region | Level Class | Boss Level Class | Source |
|---|---|---|---|---|
| 1-4 | Sewers | SewerLevel | SewerBossLevel | Dungeon.java:223-229 |
| 6-9 | Prison | PrisonLevel | PrisonBossLevel | Dungeon.java:230-236 |
| 11-14 | Caves | CavesLevel | CavesBossLevel | Dungeon.java:237-243 |
| 16-19 | City | CityLevel | CityBossLevel | Dungeon.java:244-250 |
| 21-24 | Demon Halls | HallsLevel | HallsBossLevel | Dungeon.java:251-257 |
| 26 | Yog-Dzewa | LastLevel | N/A | Dungeon.java:258-261 |
Branch Levels
Certain quests, like the Blacksmith's quest, take place in special "branch" levels. These are managed by the branch variable in the Dungeon class. For example, the MiningLevel is instantiated when branch is 1 and the depth is within the Caves region.
Sources: Dungeon.java:270-276, MiningLevel.java
Room System
Rooms are the fundamental building blocks of a level. The RegularLevel class initializes a list of Room objects, which are then passed to a Builder to be connected.
Room Class Hierarchy
The room system uses a clear inheritance structure to define different categories of rooms.
This diagram shows the inheritance relationships between different room types.
Sources: RegularLevel.java:87-123, EntranceRoom.java:31, DemonSpawnerRoom.java:30, BlacksmithRoom.java:34
Room Types
Standard Rooms
These form the bulk of a level's layout. They include the EntranceRoom and ExitRoom, as well as various themed rooms like ChasmRoom, RuinsRoom, and SegmentedLibraryRoom. The specific type of EntranceRoom is chosen based on the dungeon depth, providing visual variety as the player descends.
Sources: RegularLevel.java:93-102, EntranceRoom.java:162-192
Special Rooms
These rooms contain unique encounters or features. SpecialRoom.initForFloor() is called to prepare a weighted list of possible special rooms for the current depth. Examples include:
ShopRoom: Contains a shopkeeper. Spawns on specific floors.DemonSpawnerRoom: Contains aDemonSpawnermob.MagicWellRoom: Contains aWELLterrain tile with magical water.WeakFloorRoom: A room with a hidden chasm that leads to the floor below.
Sources: RegularLevel.java:108-116, DemonSpawnerRoom.java, MagicWellRoom.java, WeakFloorRoom.java
Secret Rooms
These rooms are always hidden behind secret doors and contain valuable loot. The number of secret rooms per floor is determined by SecretRoom.secretsForFloor(Dungeon.depth).
Sources: RegularLevel.java:118-123
Quest Rooms
These rooms are tied to specific NPC quests. They have unique layouts and logic.
BlacksmithRoom: Contains the Blacksmith NPC and a transition to theMiningLevel.RitualSiteRoom: Contains a ritual marker for the Wandmaker's quest.MassGraveRoom: A special room for the Ghost's quest, filled with skeletons and loot.
Sources: BlacksmithRoom.java, RitualSiteRoom.java, MassGraveRoom.java
Level Painting and Terrain
After rooms are arranged by a Builder, a Painter class fills them with terrain. Each region has its own painter (e.g., SewerPainter, HallsPainter) that defines the probabilities for features like water, grass, and traps.
The paint() method within each Room subclass defines its specific structure using Painter utility methods like Painter.fill() and Painter.drawInside().
Sources: SewerLevel.java:100-104, HallsLevel.java:97-101, ChasmRoom.java:79-87
Terrain and Tile Stitching
The visual representation of the dungeon is handled by DungeonTileSheet, which maps Terrain constants to specific sprites on a tilesheet. For complex terrain like walls and water, the system uses a "stitching" logic to select the correct tile based on its neighbors. This creates a seamless, connected appearance.
For example, stitchWaterTile() determines the correct water tile by checking if the four adjacent tiles are "stitcheable" (e.g., floor, grass, door). A bitmask is created from these checks to select one of 16 possible water-to-ground transition tiles. A similar, more complex logic is used for walls to create overhangs and internal corners.
This diagram shows the logic for selecting a water tile based on its neighbors.
Sources: DungeonTileSheet.java:101-118, DungeonTileSheet.java:120-127
Key terrain types include:
WALL,WALL_DECOEMPTY,EMPTY_SP(Special Floor)DOOR,LOCKED_DOOR,SECRET_DOORWATER,CHASMGRASS,HIGH_GRASSENTRANCE,EXIT
Sources: DungeonTileSheet.java
Summary
The level generation system in Shattered Pixel Dungeon is a robust and extensible framework. It combines a high-level regional theme system with a modular room-based construction process. The use of Builder and Painter patterns separates the concerns of layout and content, while the Room class hierarchy allows for easy creation of new and varied dungeon features. This procedural approach is fundamental to the game's replayability, ensuring that every descent into the dungeon is a new and unpredictable adventure.