Floor Generation Overview: Difference between revisions

From PMDOWiki
← Older edit
Imbion (talk | contribs)
3,593 edits
Added redlinks for all spawn steps, also put the priority steps under their own heading for page readability
Imbion (talk | contribs)
3,593 edits
 
(21 intermediate revisions by the same user not shown)
Line 1: Line 1:
Floor generation is performed as a list of steps, which allows a developer to customize their floor layout at every part of the pipeline. This page covers the basics of what each step is responsible for and why it is needed.
Floor generation is performed as a list of steps, which allows a developer to customize their floor layout at every part of the pipeline. This page covers the basics of what each step is responsible for and why it is needed.
For information on what steps are required to create a floor from scratch, see [[Creating Dungeons from Scratch]].


== Overview ==
== Overview ==


A dungeon map can be generated without items, enemies, or traps.  But at a bare minimum, a dungeon map must generate [[terrain]] (plus entrance/exit) in order to complete without errors. There are 4 main options on how to do this:
A dungeon map can be generated without items, enemies, or traps.  But at a bare minimum, a dungeon map must generate [[terrain]] (plus entrance/exit) in order to complete without errors. There are 4 main options on how to do this.
 
{| class="wikitable"
* Generate a Grid of Rooms, which is then converted into a connected List of Rooms, which are then used to generate tiles.
|-
* Generate a connected List of Rooms, and then use those rooms to generate tiles.
! Type !! Example !! Description !! Usage
* Generate Tiles directly.
|-
* Load a Pre-made Map.
| [[Grid of Rooms Generation]] || [[File:FloorGen_Grid_Tiles.png|Frameless]] || Rooms generate inside of a grid with cells. ||Most dungeon floors
 
|-
The type of floor gen you choose in the editor will dictate which options you have:
| [[List of Rooms Generation]] || [[File:FloorGen_Floor_Tiles.png|Frameless]] || Rooms generate freely, spreading out from defined halls and rooms. || Uncommon, but used for some dungeon floors
 
|-
[[File:FloorGen_Type.png|frameless]]
| [[Stairs Floor Generation]] || [[File:FloorGen_Tiles_Tiles.png |Frameless]] || Tiles are generated directly on a base of walls. || Rare, primarily debugging
 
|-
 
| [[Load Generation]] || Anything! || Load a pre-made map. || Secret rooms, final floor treasure rooms
=== Generating Tiles Directly ===
|}
 
To learn more about the technical details of how they generate, visit their pages.
Direct tile generation will randomly generate wall and floor tiles, and then add a start and end point somewhere in the result.  To use this approach, make the floor a <code>StairsFloorGen</code>.
 
* The first step needed is <code>InitTilesStep</code>, which specifies the dimensions of the floor in tiles and initializes a grid of wall tiles.
 
[[File:FloorGen_Tiles_Empty.png|frameless]]
 
* Then an algorithm is used to carve out floor tiles out of the dungeon, such as <code>SpecificTilesStep</code> or <code>PerlinWaterStep</code>.
 
[[File:FloorGen_Tiles_Tiles.png|frameless]]
 
* Finally, <code>StairsStep</code> is used to choose a start and end tile on a walkable tile(purple).
 
[[File:FloorGen_Tiles_Start_End.png|frameless]]
 
While this approach theoretically works has been used in some debug room tests, it has never shown up in practice due to its inflexibility compared to the Grid or List of Rooms methods that follow.
 
=== List of Rooms ===
 
List of Rooms is an approach that splits generation into rooms and hallways, planning out their dimensions before filling in the tile details.  To use this approach, make the floor a <code>RoomFloorGen</code>. 
 
 
* The first step needed is <code>InitFloorPlanStep</code>, which initializes a space for which to plan out rooms and halls:
 
[[File:FloorGen_Tiles_Empty.png|frameless]]
 
* Then, a path generator such as <code>FloorPathBranch</code> is run to place the rooms with connecting halls between them (yellow):
 
[[File:FloorGen_Floor_Rooms_Halls.png|frameless]]
 
* Then, the list of rooms and halls is then translated into tiles, using <code>DrawFloorToTileStep</code>.
 
It accomplishes this by first asking each room to generate its tiles:
 
[[File:FloorGen_Floor_Rooms_To_Tiles.png|frameless]]
 
Then, the hall algorithms are asked to generate:
 
[[File:FloorGen_Floor_Rooms_Halls_To_Tiles.png|frameless]]
 
This leaves us with all floor tiles:
 
[[File:FloorGen_Floor_Tiles.png|frameless]]
 
* Lastly, the start and end tile are marked, by first selecting 2 separate rooms (pink) and then choosing a tile (purple) in each room to put the marker.  The step responsible for this is <code>FloorStairsStep</code>
 
[[File:FloorGen_Floor_Start_End.png|frameless]]
 
Room Floors are somewhat uncommon and has few templates to choose from for floor shape.  However it's possible to vary the floor shape a lot simply by choosing different room types to generate with.
 
 
=== Grid of Rooms ===
 
Grid of Rooms is an approach that starts generation off with a grid of rooms, before planning out their dimensions and then filling in the tile details. It is basically the List of Rooms approach with extra steps. To use this approach, make the floor a <code>GridFloorGen</code>.
 
* The first step needed is <code>InitGridPlanStep</code>, which initializes a grid of cells:
 
[[File:FloorGen_Grid_Cells.png|frameless]]
 
* Then, a path generator such as <code>GridPathBranch</code> is run to place rooms in the grid (blue) with connecting halls between them (yellow):
 
[[File:FloorGen_Grid_Cells_Chosen.png|frameless]]
 
Each room and hall filled in here are also assigned an algorithm at this step.
 
* The grid rooms and grid connectors are then translated into a list of rooms and halls, using <code>DrawGridToFloorStep</code>.
 
It accomplishes this by first having each room algorithm then choose its size and location:
 
[[File:FloorGen_Grid_Cells_To_Rooms.png|frameless]]
 
The rooms then signal their connection requirements to the halls, which then have their sizes chosen:
 
[[File:FloorGen_Grid_Cells_To_Rooms_Halls.png|frameless]]
 
Then finally by writing it out to an actual list of rooms and halls:
 
[[File:FloorGen_Grid_Rooms_Halls.png|frameless]]
 
* Then, the list of room and halls are then translated into tiles, using <code>DrawFloorToTileStep</code>.
 
It accomplishes this by first asking each room to generate its tiles:
 
[[File:FloorGen_Grid_Rooms_To_Tiles.png|frameless]]
 
Then, the hall algorithms are asked to generate:
 
[[File:FloorGen_Grid_Rooms_Halls_To_Tiles.png|frameless]]
 
This leaves us with all floor tiles:
 
[[File:FloorGen_Grid_Tiles.png|frameless]]
 
* Lastly, the start and end tile are marked, by first selecting 2 separate rooms (pink) and then choosing a tile (purple) in each room to put the marker.  The step responsible for this is <code>FloorStairsStep</code>
 
[[File:FloorGen_Grid_Start_End.png|frameless]]
 
Grid Floors are the most common approach to dungeon generation, with a large number of unique templates for floor shape.
 
=== Pre-Made Map ===
 
Pre-made maps directly load a file from the Data/Maps/ directory to be used as a dungeon map. To use this approach, make the floor a <code>LoadGen</code>.
 
Only one step is needed, which is the file-loading step: <code>MappedRoomStep</code>
 
Pre-made maps are often used for fixed dungeon floors such as the reward rooms at the end of a dungeon, or secret rooms.


== Priority System ==
== About Steps ==


Floor generation is broken down into an ordered list of steps, each assigned a priority.  The priority determines at what point in the generation process the step should be performed, with a lower number means a step will execute earlier.  While these priority numbers do not need to be obeyed for modding, they are the numbers that base PMDO uses.  Priority becomes especially handy when using [[Zone Step Overview|Zone Steps]] to plan out dungeon features across multiple floors instead of a single one.
Floor generation is broken down into an ordered list of steps, each assigned a priority.  The priority determines at what point in the generation process the step should be performed, with a lower number means a step will execute earlier.  While these priority numbers do not need to be obeyed for modding, they are the numbers that base PMDO uses.


== Steps Summary ==
Priority becomes especially handy when using [[Zone Steps]] to plan out dungeon features across multiple floors, rather than a single one.


While the Overview section covers the bare minimum steps to generate without error, you may notice that generating a map only with those steps will have no name, no music, no time limit, and even no textures, forcing you to rely on the minimap to understand the terrain.  Below is a table of commonly used steps, what priorities PMDO places them in, and what they are used for.
To view each step that exists and what they do, see [[Floor Generation Steps]].


{| class="wikitable" style="margin:auto"
== Priority Brackets ==
Each range of priority is generally used to perform different tasks. These are each bracket present in PMDO, and what they are generally used for.
{| class="wikitable"
|-
|-
! Priority !! Step !! Description
! Priority !! Bracket !! Purpose
|-
|-
| -7 || [[Mapped Room Step|MappedRoomStep]] || Loads a dungeon map to use as this floor's layout, including its entities and properties.
| -7 || File Load || Loading a pre-loaded map.
|-
|-
| -6 || [[Map Data Step|MapDataStep]] || Sets the music, time limit, and [[darkness]] of the floor.
| -6 || Floor Data || Setting the initial data of a floor.
|-
|-
| -6 || [[Map Name ID Step|MapNameIDStep]] || Gives the map a name.
| -5 || Grid Creation || Initializing the grid for [[GridFloorGen]].
|-
|-
| -6 || [[Map Title Drop Step|MapTitleDropStep]] || Makes the map name show up before fading in.
| -4 || Grid Path Generation || Generating the initial rooms and halls for [[GridFloorGen]].
|-
|-
| -6 || [[Map Effect Step|MapEffectStep]] || Sets event data for the floor.
| -4.1 || Grid Special Generation || Generates special rooms outside of the general generation for [[GridFloorGen]].
|-
|-
| -5 || [[Init Grid Plan Step|InitGridPlanStep]] || Initializes a grid for GridFloorGen.
| -3 || Room List Creation|| Initializing the floorpan for [[RoomFloorGen]].
|-
|-
| -4 || [[Grid Path Steps|GridPathBranch, GridPathCircle, GridPathTwoSides, etc.]] || Generates a path of rooms and halls for GridFloorGen.
| -2 || Room List Generation || Generating the rooms and halls for [[RoomFloorGen]].
|-
|-
| -4 || [[Set Grid|SetGridDefaultsStep]] || Turns some rooms into halls (1 tile size), for GridFloorGen.
| -2.1 || Vault Pregen || Generation prior to special gen for [[RoomFloorGen]].
|-
|-
| -4 || [[Connect Grid Branch Step|ConnectGridBranchStep]] || Connects some adjacent rooms, for GridFloorGen.
| -2.2 || Room List Special || Generates special rooms for [[RoomFloorGen]].
|-
|-
| -4 || [[Combine Grid Room Step|CombineGridRoomStep]] || Combines some rooms into larger rooms, for GridFloorGen.
| -2.5 || Pre-Vault Clamp || Clamping of the map for vaults.{{Unverified}}
|-
|-
| -3 || [[Init Floor Plan Step|InitFloorPlanStep]] || Initializes a list of rooms and halls for RoomFloorGen.
| -1 || Init Map || Initialize the size of the map.
|-
|-
| -3 || [[Draw Grid To Floor Step|DrawGridToFloorStep]] || Initializes a list of rooms and halls and populates it with the grid from GridFloorGen.
| 0 || Draw Tiles || Draw tiles to the actual map.
|-
|-
| -2 || [[Floor Path Branch|FloorPathBranch]]|| Generates a path of rooms and halls for RoomFloorGen.
| 0.1 || Unbreakable Layers || Create the unbreakable border around the map borders.
|-
|-
| -1 || [[Init Tiles Step|InitTilesStep]] || Sets the floor dimensions and initializes a grid of tiles, for StairsFloorGen.
| 0.2 || Floor Extras 1 || Add extra floor changes. This is one layer to perform them for priority reasons. Usually has vaults and barriers.
|-
|-
| -1 || [[Draw Floor To Tile Step|DrawFloorToTileStep]] || Creates a grid of tiles and draws onto it based on the list of rooms and halls from a RoomFloorGen or GridFloorGen.
| 0.3 || Floor Extras 2 || Add extra floor changes. This is one layer to perform them for priority reasons. Usually has tunnels.
|-
|-
| 0 || [[Specific Tiles Step|SpecificTilesStep]] || Sets the floor to specific tiles. Only used for debug.
| 1 || Spawn Tables || Defining spawn tables for the floor.
|-
|-
| 0.1 || [[Unbreakable Border Step|UnbreakableBorderStep]] || Adds a border of unbreakable tiles at the edge of the map.
| 2 || Exits || Placement of entrances and exists.
|-
|-
| 0.3 || [[Add Tunnel Step|AddTunnelStep]] || Digs tunnels into the walls starting from a room.
| 2.1 || Save Variables || Things that change depending on save variabes, such as rescues.
|-
|-
| 1 || [[Money Spawn Step|MoneySpawnStep]] || Sets the spawn table for money on this floor.
| 2.2 || Sealed Detours || Generation for sealed detours.
|-
|-
| 1.1 || [[Item Spawn Step|ItemSpawnStep]] || Sets the spawn table for items on this floor.
| 3 || Extra Terrain || The placement of extra terrain types, such as water and tall grass.
|-
|-
| 1.2 || [[Mob Spawn Step|MobSpawnStep]] || Sets the spawn table for mobs on this floor.
| 3.1 || Drop Diagonal || Uses [[DropDiagonalBlockStep]] on the extra terrain if needed.
|-
|-
| 1.2 || [[Mob Spawn Settings Step|MobSpawnSettingsStep]] || Sets the rules for enemies respawning on the floor.
| 3.2 || Erase Isolated || Uses [[EraseIsolatedStep]] on the extra terrain if needed.
|-
|-
| 1.3 || [[Tile Spawn Step|TileSpawnStep]] || Sets the spawn table for traps on this floor.
| 4 || Textures || Assigns textures to the map.<br>At 4 because textures were formerly placed during this step, but are now placed after all steps are done.
|-
|-
| 2 || [[Floor Stairs Step|FloorStairsStep]] || Places the start point and the end stairs on different rooms of the floor, for RoomFloorGen or GridFloorGen.
| 4.1|| Houses || Placement of [[houses]].
|-
|-
| 2 || [[Stairs Step|StairsStep]] || Places the start point and the end stairs on different tiles of the floor, for StairsFloorGen.
| 4.2|| Shops || Placement of [[shops]].
|-
|-
| 3 || [[Perlin Water Step|PerlinWaterStep]] || Adds water/lava/etc. using Perlin Noise.
| 5 || Tile Spawns || Spawning tiles, such as traps.
|-
|-
| 3 || [[Blob Water Step|BlobWaterStep]] || Adds water/lava/etc. by placing several blobs made from cellular automata.
| 5.1 || Compass Spawns || The spawning of [[compass tiles]] specifically.
|-
|-
| 4 || [[Map Texture Step|MapTextureStep]] || Defines the textures for floors, walls, and water.
| 6 || Spawn Money || The spawning of money.
|-
|-
| 4 || [[Map Dict Texture Step|MapDictTextureStep]] || Defines the textures in a more advanced way, needed if the layout uses grass.
| 6.1 || Spawn Items || The spawning of items.
|-
|-
| 5 || [[Random Room Spawn Step|RandomRoomSpawnStep<?, EffectTile>]] || Spawns traps in random rooms.
| 6.2 || Spawn Extra Items || The spawning of additional items with other steps.
|-
|-
| 5 || [[Spaced Room Spawn Step|SpacedRoomSpawnStep<?, EffectTile>]] || Spawns traps in random rooms, taking care not to place in the same room or adjacent rooms.
| 6.2 || Spawn Mobs|| The spawning of mobs.
|-
|-
| 6 || [[Terminal Spawn Step|TerminalSpawnStep<?, MoneySpawn>]] || Spawns money in dead-end rooms.
| 6.2.1 || Spawn Extra Mobs|| The spawning of additional mobs outside of the base spawn steps.
|-
|-
| 6.1 || [[Due Spawn Step|DueSpawnStep<?, InvItem, MapEntrance>]] || Spawns items based on how far they are from the starting room.
| 7|| Debug Checks || Steps that check the dungeon for issues, throwing an error if one is found.<br>Useful for [[Stress Testing]].
|-
| 6.2 || [[Place Random Mobs Step|PlaceRandomMobsStep]] || Randomly places enemies on the map.
|-
| 7 || [[Detect Isolated Stairs Step|DetectIsolatedStairsStep]] || Testing step: Looks for a path from start to end and throws an error if none can be found.
|-
| 7 || [[Detect Tile Step|DetectTileStep]] || Testing step: Checks to see if a certain tile can be found on the map and throws an error if none can be found.
|}
|}


== Typical Priority Usages ==
[[Category:Dungeon Generation]]
The sections below go into more detail of what each priority is typically used for, as well as less commonly used steps used in those priority brackets.
 
=== Floor Data ===
 
Priority -6
 
Examples:
 
* MapDataStep
* MapEffectStep
* MapNameIDStep
* DefaultMapStatusStep
* MapTimeLimitStep
 
=== Grid Creation ===
 
Priority -5
 
Examples:
 
* InitGridPlanStep
 
=== Grid Path Generation ===
 
Priority -4
 
Examples:
 
* GridPathBranch
* GridPathCircle
* GridPathTwoSides
* GridPathGrid
* GridPathBeetle
* GridPathTiered
 
* SetGridDefaultsStep
* ConnectGridBranchStep
* CombineGridRoomStep
 
=== Room List Creation ===
 
Priority -3
 
Examples:
 
* InitFloorPlanStep
* DrawGridToFloorStep
 
=== Room List Generation ===
 
Priority -2
 
Examples:
 
* FloorPathBranch
 
=== Tiles Creation ===
 
Priority -1
 
Examples:
 
* InitTilesStep
* DrawFloorToTileStep
 
=== Tiles Generation ===
 
Priority 0
 
Examples:
 
* SpecificTilesStep
 
=== Spawn Tables ===
 
Priority 1
 
Examples:
 
* MoneySpawnStep
* ItemSpawnStep (Priority 1.1)
* MobSpawnStep (Priority 1.2)
* TileSpawnStep (Priority 1.3)
 
 
=== Exits ===
 
Priority 2
 
Examples:
 
* FloorStairsStep
* StairsStep
 
=== Water ===
 
Priority 3
 
Examples:
 
* PerlinWaterStep
* BlobWaterStep
 
=== Textures ===
 
Priority 4
 
Used to be here because textures were actually placed here, but now only assigns textures to the map itself and lets the map compute them after ALL steps are done.  Thus, this step is the least dependent on its current position in the steps.
 
Examples:
 
* MapTextureStep
* MapDictTextureStep
 
=== Tile Spawns ===
 
Priority 5
 
Examples:
 
* RandomSpawnStep
* DueSpawnStep
* TerminalSpawnStep
 
=== Spawns ===
 
Priority 6
 
Examples:
 
* All steps in Tile Spawns
* PlaceRandomMobsStep
* PlaceDisconnectedMobsStep
* PlaceNoLocMobsStep
 
=== Debug Checks ===
 
Priority 7
 
These gen steps are used to check the dungeon for issues, and throw an error if they're found.  Useful for [[Stress Testing Dungeons|stress testing]].
 
Examples:
 
* DetectIsolatedStairsStep
* DetectTileStep
 
[[Category:Modding Data]]

Latest revision as of 00:28, 17 August 2025

Floor generation is performed as a list of steps, which allows a developer to customize their floor layout at every part of the pipeline. This page covers the basics of what each step is responsible for and why it is needed.

For information on what steps are required to create a floor from scratch, see Creating Dungeons from Scratch.

Overview

A dungeon map can be generated without items, enemies, or traps. But at a bare minimum, a dungeon map must generate terrain (plus entrance/exit) in order to complete without errors. There are 4 main options on how to do this.

Type Example Description Usage
Grid of Rooms Generation Frameless Rooms generate inside of a grid with cells. Most dungeon floors
List of Rooms Generation Frameless Rooms generate freely, spreading out from defined halls and rooms. Uncommon, but used for some dungeon floors
Stairs Floor Generation Frameless Tiles are generated directly on a base of walls. Rare, primarily debugging
Load Generation Anything! Load a pre-made map. Secret rooms, final floor treasure rooms

To learn more about the technical details of how they generate, visit their pages.

About Steps

Floor generation is broken down into an ordered list of steps, each assigned a priority. The priority determines at what point in the generation process the step should be performed, with a lower number means a step will execute earlier. While these priority numbers do not need to be obeyed for modding, they are the numbers that base PMDO uses.

Priority becomes especially handy when using Zone Steps to plan out dungeon features across multiple floors, rather than a single one.

To view each step that exists and what they do, see Floor Generation Steps.

Priority Brackets

Each range of priority is generally used to perform different tasks. These are each bracket present in PMDO, and what they are generally used for.

Priority Bracket Purpose
-7 File Load Loading a pre-loaded map.
-6 Floor Data Setting the initial data of a floor.
-5 Grid Creation Initializing the grid for GridFloorGen.
-4 Grid Path Generation Generating the initial rooms and halls for GridFloorGen.
-4.1 Grid Special Generation Generates special rooms outside of the general generation for GridFloorGen.
-3 Room List Creation Initializing the floorpan for RoomFloorGen.
-2 Room List Generation Generating the rooms and halls for RoomFloorGen.
-2.1 Vault Pregen Generation prior to special gen for RoomFloorGen.
-2.2 Room List Special Generates special rooms for RoomFloorGen.
-2.5 Pre-Vault Clamp Clamping of the map for vaults.(unverified)
-1 Init Map Initialize the size of the map.
0 Draw Tiles Draw tiles to the actual map.
0.1 Unbreakable Layers Create the unbreakable border around the map borders.
0.2 Floor Extras 1 Add extra floor changes. This is one layer to perform them for priority reasons. Usually has vaults and barriers.
0.3 Floor Extras 2 Add extra floor changes. This is one layer to perform them for priority reasons. Usually has tunnels.
1 Spawn Tables Defining spawn tables for the floor.
2 Exits Placement of entrances and exists.
2.1 Save Variables Things that change depending on save variabes, such as rescues.
2.2 Sealed Detours Generation for sealed detours.
3 Extra Terrain The placement of extra terrain types, such as water and tall grass.
3.1 Drop Diagonal Uses DropDiagonalBlockStep on the extra terrain if needed.
3.2 Erase Isolated Uses EraseIsolatedStep on the extra terrain if needed.
4 Textures Assigns textures to the map.
At 4 because textures were formerly placed during this step, but are now placed after all steps are done.
4.1 Houses Placement of houses.
4.2 Shops Placement of shops.
5 Tile Spawns Spawning tiles, such as traps.
5.1 Compass Spawns The spawning of compass tiles specifically.
6 Spawn Money The spawning of money.
6.1 Spawn Items The spawning of items.
6.2 Spawn Extra Items The spawning of additional items with other steps.
6.2 Spawn Mobs The spawning of mobs.
6.2.1 Spawn Extra Mobs The spawning of additional mobs outside of the base spawn steps.
7 Debug Checks Steps that check the dungeon for issues, throwing an error if one is found.
Useful for Stress Testing.
Retrieved from "https://wiki.pmdo.pmdcollab.org/wiki/index.php?title=Floor_Generation_Overview&oldid=3647"