Procedural Dungeon Generator

The foundation for this generator is based on the Tutorial series posted by Toadnet. To learn how to make a tile map dungeon generator from scratch I highly recommend supporting his channel.

This is the documentation for the full Procedural Dungeon Generator project. This project is under development and continues to receive new features and updates. For anyone interested in trying the generator before purchasing check out the free lite version HERE.

Features:

  • Scalable Grid based generation with modular tiles

  • Ability to adjust grid scale, room size, room complexity, and path complexity

  • Procedural key and lock distribution to influence progression

  • Supports multi story rooms for height variation (only generates corridors on 1 level)

  • Populates dungeon with room relevant assets

  • Easy to modify datatable for custom rooms, paths, and decoration control

Overview

This is a grid based dungeon generator that uses a 500x500x500 tileset consisting of walls, floors, ceilings, and inner/outer corners. On construct the generator uses these tiles to build multiple paths of rectangular rooms within set X and Y parameters, shapes them by randomly removing tiles, and connects them with corridors made of the same tileset. 

The size and number of the rooms, as well as the frequency of the tile culling for shaping can be controlled from the details panel. In addition to this base functionality this generator can build taller rooms up to a defined height, as well as assign each path or individual rooms a different themed tileset declared and organized in the DefaultRoomData datatable.

On runtime the dungeon is populated with elevators, doors, keys, lights, enemies, and multiple sizes of decoration blueprints procedurally placed to fill the floorspace of each room. The number of decorations, rooms they appear in, and rarity of spawning can be set along with each tileset in the datatable.

Initial Setup

To set up the dungeon first drop the dungeon blueprint into the level and check SpawnTiles under the Editor Tools. By default the dungeon spawns 5  branching rooms ending with a boss room.

Editor Tools:

  • Max Loops

    • When searching for a new seed, the dungeon loops through room layouts until a valid seed is found. For larger dungeons increase Max Loops to reduce the chance of failing to find a valid seed. 

  • New Seed

    • To generate a new random seed check the New Seed box.

  • Grid Scale 

    • This is the scale of the dungeon generator's grid. If you wish to use a grid other than 500x500 or different from the grid size of your tileset, adjust this parameter to scale the dungeon to the desired grid. All meshes and decorations will scale accordingly to fit within this new grid.

  • Model Scale

    • This is the scale of your desired static mesh tileset. The default tiles are built on a 500x500 grid. When choosing or importing a custom tileset enter the scale of your modular grid so the models can be scaled appropriately when choosing a grid scale for the generator. 

  • Spawn Tiles

    • Spawn tiles is true by default. Uncheck this box while you’re making changes to large dungeons so you don’t have to wait for the dungeon to rebuild itself with each change

  • Rooms (Uneditable info for Debugging)

    • This opens a dictionary of each room successfully spawned in the dungeon, with each key being a vector of the room’s location relative to the dungeon, and the value representing the extents of that room in tiles

  • Dead Ends (Uneditable info for Debugging)

    • This is an array of the locations relative to the dungeon where rooms attempted to spawn before failing out and being forced to branch off of another previous room

  • Path Lengths (Uneditable info for Debugging)

    • This is a dictionary showing each path and how many rooms  were spawned within it. 

Map Settings:

  • Generate on Runtime

    • This deactivates the generation on Construct and assigns a new random seed on begin play to generate different dungeons each time the level is loaded.

  • Seed

    • New or old seeds can also be set manually in the map settings. Dungeons will always generate the same when using the same seed and settings. 

  • Room Size

    • Rooms generate X and Y grids with each side ranging from Room Size Max to Min. The Boss room is the exception to these settings and always spawns with max X and Y size. Adjust these settings to control base size and range in size of all other rooms 

  • Room Count

    • By default the dungeon spawns 5 rooms ending with, and including the boss room. Adjust the room count to make the dungeon as long as you desire. The last room in the dungeon will always be the boss room as long as the dungeon is at least 2 rooms long.

  • Do Paths

    • Checking this changes the generation from spawning one long dungeon with the same tileset from beginning to end, to spawning multiple smaller paths each with their own themed tilesets, until the max room count is reached. 

  • Path Lengths

    • Similar to RoomCount, each path has a minimum and maximum number of rooms. When generating, each path is assigned a length between these values until the max room count has been reached, at which point the boss room will be spawned and the path will be cut off. 

  • Spawn Keys in Previous Path?

    • Checking this guarantees that when generating keys and locked doors, the key for each path will be placed in a random room along the previous path, controlling progression through the dungeon. If unchecked, the key for a new path will be spawned in any previous room of the dungeon allowing keys to be found out of order. The key will still always spawn before the first door that requires it.

  • Floor Culling

    • Floor culling removes grid spaces from all rooms, allowing for more unique and varied shapes. When culling each room the generator removes a random number of tiles between the Max and Min Floor Cull variables. Adjust these to control the amount of tiles that are removed from each room, or uncheck to only generate solid rectangular rooms.

  • Branching

    • Branching is checked by default and allows rooms to spawn off of any previous room in the dungeon, breaking up the flow and allowing multiple long side tracks and loops in one dungeon. If unchecked the dungeon generates linearly, occasionally only branching if a corridor happens to loop back through a previous room, or if a room is unable to be spawned off of a dead end. 

    • If branching is checked each new room in the dungeon will decide if it will continue off the last room or branch off of another, depending on the branching chance, with a chance of 1 being 100% and 0 generating a linear dungeon. 

    • If path generation is turned on, the first room of each new path will follow this logic and branch off of a previous room along the dungeon. Following rooms within a path generate linearly, only branching and creating another path if a dead end is created before the path is complete

  • Truncate Corridors

    • In larger dungeons corridors can overlap or intersect. Check this to cut overlapping corridors into one to avoid multiple loops back to the same rooms

  • Leveled

    • If Leveled is checked, the dungeon will be built with height variation between rooms. Each new room will be built either 1 tile below, one tile above, or at the same level of the previous room. Corridors are then be built between the two rooms at the height of the lowest room, with a staircase through the floor of the higher room. If a corridor passes through a previously built room any tile above the floor level, the dungeon will build a bridge through the room with doors on either side.

  • Varied Room Height

    • If allowed in the datatable, rooms will generate at with a random height between 0, being one tile tall, and the max room height set by the generator. Uncheck this to only generate rooms with a height of 1 tile. If a room type in the datatable is set to a locked room height each room of that type will ignore this setting and generate at the locked height, or the max room height of the dungeon.

  • Max Room Height

    • When building rooms with a height greater than one tile, the dungeon will randomly choose a height between 0 and this height. If a room type in the datatable is set to a locked room height that is higher than this number the rooms will be locked to this height.

  • Room Max

    • During generation the dungeon randomly assigns each room a type from all valid unique room types declared in the datatable until each specified type has reached its max room number. 

    • If a room theme is not set to be a path theme it is added to this dictionary of unique room types and by default generates once per dungeon. When adding new rooms to the datatable, adjust the max number of that room type you want to be able to appear. Depending on the size of the dungeon the max number is not guaranteed and it is possible to not generate any of a specific room, however in large dungeons this allows multiple rooms to get a chance of spawning and greater variation during gameplay

  • Remove Entrance Ceiling

    • Checking this removes the ceiling tile at 0,0,0 in the center of the first room, to create an entrance into the dungeon. This hole is stationary regardless of seed allowing for a consistent entrance for any dungeon.

  • Remove Entrance/Exit Walls

    • Checking these boxes creates an entrance and exit corridor leading into the first and last rooms respectively. When these are checked the generation adjusts to avoid cutting off the entrances, locking room spawning to a higher X value than the first room, and moving the Boss Room to the greatest X value of the dungeon on the opposite end

  • Data Table

    • This is the datatable used by the generator for constructing paths and themes. By default it is set to the default datatable DT_Default_RoomData. Switching this out allows you to generate multiple dungeons throughout your game, each with custom datatables based on the area or need of the level.

Custom Room Types

The base Generator comes with two room types, Default and Boss. Default rooms have a short and tall variant and make up the first room, and any other room in the dungeon that doesn’t have a unique type. The Boss Room always spawns as the last room in the dungeon and is by default is set to always be a tall room with max dimensions to allow space for a large arena.

Adding Custom Rooms:

  • To add a new room, open DT_Default_RoomData in the Data Folder

  • Select the Add Button at the top of the screen and name the new data row to the type of room you want to make

Adding Custom Meshes:

  • Add your desired meshes to the arrays for each room component: Ceilings, Floors, Walls, Door Frames, Inner Corner, Outer Corner, and Stairs
    Adding multiple meshes to the arrays increases the variation of the dungeon and rooms.
    For each room type all room components must be filled for the room to build correctly. If you don’t have custom meshes for each component just fill the component slot with a default mesh.

  • By default rooms generate with a height of 1 tile equal to the GridScale. If you want rooms to be taller check the AllowHieghtVariation box. If Varied room height is true the dungeon will randomly choose a height for each room between 1 tile and the max room height of the dungeon.

  • If you want the new room type to only generate as a specific height check the LockHeight variable and set the LockedHeight float to the desired height. If these variables are set each room of the selected type will generate at the locked height as long as it’s less than or equal to the max room height of the dungeon.

Adding Room Trims

  • The room trim is a material instance that is applied to the 01 material slot of dungeon walls and door frames to add an extra layer of detail that can distinguish similar looking rooms. If left blank the dungeon will spawn the wall mesh as is. 

Adding Decorations:

  • Decorations are room specific blueprints that are spawned after generation to populate and bring a dungeon to life. They are broken down into Doors, Wall decorations, and 3 sizes of floor decorations, being large, medium, and small.

  • To add a decoration add at least 1 item to the map of the decoration you want, and select your desired blueprint. 

  • Set the float to the right of the blueprint to control the likelihood of that decoration spawning on a tile, with 1 being 100%

  • Adding multiple items to each blueprint will increase the variety of decorations the player will encounter while exploring your dungeon

  • After the dungeon is built decorations are spawned, with doors spawning at every room and corridor intersection, wall decorations are randomly scattered on tiles adjacent to walls, and floor decorations fill all valid floor tiles in order starting with large, then medium, and finally small. 

  • Decorations can be any blueprint including enemies, interactables, or obstacles. 

  • The decoration offset is applied to the z transform of decorations when spawning. This can be used to ensure decorations spawn correctly on floors that have height variation or have a surface with a different height than the origin of the tile like the default boss room floors.

Path Settings

  • Each custom room type can be set as a unique room, such as a shop or event room, or can be set to generate as the theme of a full branching path. 

  • If CanBePathTheme is checked, this room theme will be applied as the default theme when generating a branching path and will no longer spawn if paths are turned off. Other unique rooms can still be spawned along this path.

  • Paths can be assigned custom key and door combinations that will spawn in place of each door of the path. Each key can be assigned multiple WallDoor actors and CeilingDoor actors. When constructing doors the dungeon will pick a random key from all keys listed here and place it in a previously generated room. It will then replace each door along this path with with a random door assigned to the key.
    (Note: The Defined keys must be able to interact and unlock all door blueprints assigned to them. If a door blueprint is not already set up to be unlocked by the selected key, the dungeon generator will not be able to connect them. This could lead to softlocks and dead ends.)

  • If the Path Key/Door dictionary is empty, the dungeon will randomly assign the path a key/door pair from any available combinations declared in the details panel of the dungeon, or fill each door with the default door blueprint of the theme.

Final Setup

  • Once all settings have been filled in Save the datatable and recompile the dungeon blueprint to update it with the new room type. 

  • Select the dungeon in the level and locate the Room Max setting in the Map Settings Section of the details Panel.
    Each room type that is not set as a path theme is considered a unique room type and is listed here, spawning once per dungeon by default

  • Locate your new room type and adjust the Room Max number to increase the number of times that room can spawn in your dungeon. 

Decorations

On Begin Play the dungeon is populated by all decoration and door blueprints. Doors are spawned in the door frames generated on construct, and the floorspace of each room is filled with varying sizes of decoration blueprints.

Doors: 

Doors spawn in the intersection of each room and a corridor. After building a corridor the generator will get the theme of the new room and loop through the list of associated default doors until one is allowed to spawn based on each of their spawn likelihood. If keydoors are available to spawn, the dungeon will always spawn a locked door before spawning the default door except in the default theme. Doors spawn in the center of the hall tile next to a room and must have a transform of 250 in the X direction within their blueprint to align correctly with the dungeon walls and door frames. 

Wall decorations:

Wall decorations spawn in the center of every tile adjacent to a wall, if allowed by their spawn likelihood, and are then rotated to align with the wall. To spawn decorations against the wall, the desired mesh must have a transform of 250 in the X direction within the blueprint

Floor Decorations:

Room floor tiles can be populated by any decoration blueprints from enemy spawners to traps and puzzles. Blueprint’s locations are decided by searching the grid for space and filling all available spaces in a room starting with large, then medium, and the rest with small decorations. 

Decorations may be any blueprint you desire but the three sizes must fit within the allowed grid size so they don't overlap or block doorways

Large decorations have a footprint of 2x2 tiles

Medium decorations have a footprint of 2x1 tiles

Small decorations have a footprint of 1x1 tile

While the dungeon layout is generated on construct, Decorations and Interactables are spawned on begin play using the Spawn Decorations function.

If a decoration blueprint needs extra setup on spawn or could benefit from the dungeon seed, open the spawn decorations function and navigate to the end of the sequence branch for the decoration size you want to reference. At the end of each branch there is a sequence node for execution, a reference to the actor that was just spawned, and a copy of the dungeon’s seed.

From this cast to the desired blueprint and call any function you require. 

Dungeon Paths

Dungeon paths can be turned on in the map settings of the details panel. If checked the dungeon will be broken into smaller sections ranging in length based on the min and max settings provided, and each with their own themed tileset, default and locked doors, and decoration blueprints. When starting a new path the dungeon generator will choose a new theme from all available room types with CanBePathTheme checked. 

Keys and Locks

If the selected theme has key/lock combinations set, the generator will randomly choose a key from that list and  place it in a previous room of the dungeon, then set all doors to one of the associated locked door blueprints. If the selected theme doesn’t contain any key/lock combination the generator will randomly choose from the list of Unassigned Key Locks. 

To add new keys and locks open the unassigned Key Locks tab and add a new entry. The left actor is the key blueprint that will be placed on a random tile of the dungeon before the first room of the path. The right actor is the door blueprint that requires the associated key to open and is placed on every open door tile within the path, overriding the default doors.

Keys and locks are both blank blueprint actors and can be set to anything from physical keys, to powerups, to enemies. 

Note: After spawning both actors the dungeon generator doesn’t keep track of if keys have been collected or not, so the two blueprints must be able to interact with each other and be unlocked independently or through a separate system.