Understanding Procedural Dungeon Generation in Unity

There are two ways of building dungeons in your game. The first one is to manually create the dungeon rooms and connect them through the dungeon. The advantage of doing this is that you can manually select what will be in each room of the dungeon.

The second option is to procedurally generate the dungeon rooms. In this way, you don’t have so much control of what is in each room, but you increase the unpredictability of your game, since each dungeon might be different.

In this tutorial, I’m going to show how you can use Unity to procedurally generate a dungeon. We are going to use Unity’s tilemap functionalities to generate multiple rooms and pseudo-randomly connect them. Then we are going to build a demo where you can try multiple configurations of number of rooms, enemies and obstacles inside each room.

To read this tutorial, it is important that you’re familiar with the following concepts:

  • C# programming and object-oriented concepts
  • Basic Unity concepts, such as Sprites, Scenes and Prefabs

Source Code files

You can download the tutorial source code files here.

Creating the tiled maps

The first thing we need to do is creating the tilemaps for the dungeon rooms. Then, we can just load those tilempas later after generating the dungeon.

Unity provides tilemap generation features, so we are going to use them. First, download the sprites for this tutorial and we are going to configure the “terrains” sprite to be used for tilemaps. You need to do two things: (1) setting the Pixels Per Unit to 40 to make sure the tiles will appear in the right size; (2) changing the Sprite Mode to Multiple, and then slicing it to be separated into individual tiles.

Now, right click on the Object Hierarchy tab, and select 2D object -> Tilemap. You also need to open the Tile Palette window (Window -> 2D -> Tile Palette). We need to create a new tile palette with the “terrains” tileset Unity will ask where you wish to save the palette, I suggest saving it in a separate folder called Tile Palettes. After creating the tile palette, drag and drop the tileset to the Tile Palette window.

Now, we can start creating our room tilemap using this tile palette. Select the brush tool and paint the tilemap with the tiles you wish. In the end, you should have something like this:

The next step is making the walls in the room collidable, while the floor tiles are not. In order to do so, select the Tilemap object and add a Tilemap Collider 2D. However, this will make all tiles collidable. To make the floor tiles not collidable, select the floor tile in the Tile Palettes folder and change the Collider Type to None.

Player and door prefabs

We created the room for our dungeon, but we still need a player to move in the dungeon, and door to navigate through rooms.

Let’s start by creating the Player. First, select the “player” sprite in the Sprites folder, change the Pixels Per Unit to 30, the Sprite Mode to multiple and slice the prefab. Then, create a new GameObject called player from this sprite, and add a Box Collider 2D and a Rigidbody 2D to this object. Notice that we need to do some changes in the components. First, we don’t want the player to rotate when colliding with things, so we check the Freeze Rotation box of Rigidbody 2D. Also, we need to reduce the size of the collider a little bit, so that the Player can walk through the doors. We do so by changing the size of the Box Collider 2D. You also need to create a Tag called “Player”, and assign it to this object.

Also, since this is a top-view game, we don’t want any gravity force. We can disable gravity in Edit -> Project Settings -> Physics2D and changing the gravity in the Y axis to 0.

Now, create a new script called PlayerMovement and add it to the Player object. This script will be very simple as the only thing we need is being able to move the Player. So, it needs a speed attribute as a SerializeField and we implement the FixedUpdate method to move the player. In order to do so, it gets the values of the Horizontal and Vertical input and update the velocity accordingly.

Now that we have the Player object, let’s create the Door prefab as well. So, create a new GameObject called Door. This object will not have a sprite, it will only be an invisible collidable sprite. In order to do so, you need to add a Box Collider 2D and a Rigidbody 2D to the Door. For the Rigidbody 2D, you need to set the Body Type to static. This will make sure the Door will be immovable while still colliding with the Player.

After creating the Door object, let’s create a new script called EnterDoor and add it to the Door object. For now, when the Player touches the door we are only going to restart the game. Later on, we are going to use it to navigate through the Dungeon rooms. Either way, the collision between the Door and Player will be detected by implementing the OnCollisionEnter2D method. In this method, we are going to check if the collision was with the Player. If so, we start the Demo Scene again. Notice that you need to add the SceneManagement namespace to restart the Scene.

Now, to test it, save the Scene as Demo and you can try playing the game. By now, you should be able to move the player and restart the game when touching the Door.

The dungeon generation algorithm

Now that we have the basic objects to our game (Player and Door), let’s implement the dungeon generation algorithm. In order to do so, strat by creating an empty object called Dungeon and attach a script called DungeonGeneration to it.

The algorithm to generate the dungeon room is as follows:

  1. Create a empty grid where the rooms will be saved.
  2. Create an initial room and save it in a rooms_to_create list.
  3. While the number of rooms is less than a desired number “n”, repeat:
    1. Pick the first room in the rooms_to_create list
    2. Add the room to the grid in the correspondent location
    3. Create a random number of neighbors and add them to rooms_to_create
  4. Connect the neighbor rooms.

This algorithm is implemented in the GenerateDungeon method below. Notice that the first room coordinate is generated in the middle of the grid. Also, the dungeon grid is initialized with three times the number of rooms on each axis. This way, we can make sure that all rooms fit into the grid. Then, the first loop creates the rooms using the steps described above. All the created rooms are stored in a list called “createdRooms”. When all the rooms have been created, it iterates through this list connecting the neighbor rooms. This is done, by iterating through the neighbor coordinates of each room and checking if there is a room in the grid for this coordinate. If so, the algorithm connects both rooms. In the end, we guarantee the desired number of rooms in the dungeon, and we ensure that all rooms are connected, since they are always connected as neighbors of a previous room.

You may have noticed we are using a Room class to create the dungeon grid. Also, we add the neighbors of a room to the “rooms_to_create” list using a method called AddNeighbors, so we need to implement it. This method starts by checking what neighbor coordinates are actually available to be selected as having rooms. A coordinate is available only if there is not any other room occupying its place. After finding the available coordinates, a random number of them is selected to be added to “rooms_to_create”. For each room to be created, one of the neighbors is selected randomly.

Now let’s create the Room class. Notice that this is not a MonoBehaviour, but simply a regular class. So, we need to create its constructor and the methods used in the DungeonGeneration script (NeighborCoordinates and Connect).

First, the constructor is simple, it only needs to initialize the room coordinate and a dictionary with neighbors information. We are going to use a dictionary instead of a list, because we want to associate each neighbor to its direction as well.

The NeighborCoordinates method will return the coordinates of all neighbors of the current room. Each room has a neighbor in each one of the four directions: North, East, South and West. This order is important, since it will be necessary to instantiate the Rooms in the game later.

Finally, the Connect method will check what is the direction of the room and add it alongside its direction in the neighbors dictionary.

In order to test if the dungeon is being generated correctly, we are going to implement a PrintGrid method that will show the room grid as a string.

Now, back to the DungeonGeneration script, we call the GenerateDungeon method in its Start method. After creating the dungeon we print it for testing.

By now, you can try running the game with a given number of parameters and checking if it is working correctly.

Navigating through rooms

Now that we are generating the dungeon grid, we need to actually instantiate the room tilemaps in the game. First, we need to create tilemaps for all the possible rooms. Let’s start by saving the room we already have in a folder called Resources. It is very important that it is in the Resources folder, since we need that to instantiate the rooms in runtime.

Now we need to do the same for all rooms. For this, I recommend you download the tutorial source code and copy the rooms from the Resources folder, because it may take some time to make all of them. You need a room for each possible neighborhood configuration, so there are a total of 15 possible rooms. The room names should follow the pattern “Room_NESW”, where “NESW” represents the neighbors of this room (North, East, South, West).

This way, we can add a method in the Room class called PrefabName which returns the name of the Room Prefab of the current room. Notice that, since the NeighborCoordinates method returns the neighbors in the correct order, the name returned by PrefabName matches the name of the prefab we want to instantiate.

Finally, we update the Start method of DungeonGeneration to instantiate this room prefab. After generating the dungeon, it returns the initial room. Then, it loads the prefab from the Resources folder and instantiates the prefab.

By now, you can try playing the game again and checking if it is instantiating the correct room. Try playing the game multiple times to see if the initial room is changing.

Now that we can instantiate a Room Prefab from its name, we can make the doors navigate through rooms. We are going to do that by restarting the Demo Scene with another room as the current one. However, we don’t want the dungeon to be generated again. So, we need to make the Dungeon object a persistent one. This way, we can make sure we have always the same dungeon.

We do that in the Awake method by calling DontDestroyOnLoad. This way, the Dungeon object will not be destroyed when we restart the scene. However, Unity will still create a new Dungeon object every time the scene is started. So, we are going to save the first DungeonGeneration instance in a static attribute. This will be set in the Awake method for the first time it is called. We are also going to generate the dungeon in this method. If the instance has already been set, we are only going to instantiate the current room prefab and we are going to delete the newly created Dungeon object.

Now, let’s update the EnterDoor script to restart the demo scene with a new current room. For that, we need to save the direction of the door in the script. Then, in the OnCollisionEnter2D method, we get the next room from acessing the neighbors dictionary for the desired direction in the current room. After identifying the next room, we change the current room in the dungeon and restart the demo scene.

We still need to implement the CurrentRoom and MoveToRoom methods in the DungeonGeneration script, as well as the neighbor getter in the Room object.

Finally, set the direction values of the doors for all rooms. Then, you can try running your game again. By now, you should be able to move between rooms.

Adding obstacles

It’s time to add other elements in our dungeon, starting with the obstacles. The obstacles will be tiles we are going to set in some specific parts of the room. For each room, the number of obstacles and their positions will be randomly chosen.

Let’s start by writing a PopulateObstacles method in the Room class. This method will receive as parameters the number of obstacles and the possible obstacle sizes. Notice that the sizes are a Vector2int, which specifies the dimensions in X and Y coordinates.

For each obstacle to be created, this method chooses a random size among the possible ones and look for a free region on the room with this size. In order to keep track of what coordinates are free in the room, we are going to use a string matrix called population. After choosing the region of the obstacle, we update the population matrix.

Now we need to implement the FindFreeRegion method. Basically, this method consists on a loop that looks for random regions until it finds one that is available. In each iteration of the loop, it generates a random center tile between tiles 2 and 15 in the x coordinate and between tiles 2 and 7 in the y coordinate. We are using those coordinates so that the obstacles are not above the walls of our room. After doing that, it calculates the coordinates of the rest of the obstacle, based on its size. Finally, it checks if the region is free in the while loop. If it is not, it iterates again to find another region, until finding a free one.

The IsFree method, by its turn, simply iterates through all coordinates of the region and checks if the population matrix is free for all of them.

Now, we need to properly call the PopulateObstacles method for each room. We are going to do that after connecting the rooms. Also, after instantiating the room prefab, we need to actually add the obstacle tiles in the tilemap. So, we update the Awake and Start methods accordingly.

We still need to implement the AddPopulationToTilemap method. This method will iterate through all the coordinates in the population matrix and check if it is an obstacle. If so, we set the tile on that coordinate to be an obstacle. Notice that we need to set the tile on coordinate (xIndex – 9, yIndex – 5). That’s because in our population matrix, the (0, 0) index is the lower left corner, while in the tilemap, (0, 0) is actually the center of the map.

Now, update the Dungeon object to set the values for the new attributes, such as the possible obstacle sizes and the obstacle tile. Then, you can try playing the game to see if it is correctly creating the obstacles.

Adding enemies

Adding enemies will be very similar to adding obstacles, except the enemies will be prefabs instead of tiles, and their size will be always of one tile.

Let’s start by adding a PopulatePrefabs method, which will add the enemies to the game given their prefabs. This method will iterate through the number of desired prefabs and, for each one, it will pick a random prefab among the possible ones, find a free region of size one and add it to the population matrix. In the population matrix we are going to use the prefab name to identify it. Later we are going to need to instantiate the prefab from its name. So, we are going to use a dictionary (initialized in the constructor) called name2Prefab. This dictionary will be indexed by the prefab name and it will return its Prefab.

This way, we can update the AddPopulationToTilemap to add the prefabs in the map as well. When the coordinate is not an obstacle, but it is also not empty and it is not the player, that means we need to instantiate a prefab for it. We instantiate the prefab by acessing the name2Prefab dictionary.

Then, we can call the PopulatePrefabs method from GenerateDungeon, right after adding the obstacles.

We still need to create the enemy prefab, in order to set the possible enemies in the DungeonGeneration script. First, we need to change the Enemy sprite Pixels Per Unit to 40, so that it is not too big in our map. Now, create a new GameObject from the Enemy sprite, and add a BoxCollider2D to it (you need to set the collider as a trigger). Finally, set the Enemy tag to be “Enemy” and save it as a Prefab.

Now, you can update the Dungeon object to add the number of enemies and enemy prefabs to the DungeonGeneration script. Then, you can try playing the game to check if the enemies are being created.

Adding the goal

We have enemies, but we still need a way to clear our game. What we are going to do in this demo is adding a Goal object, which will always be in the furthest room from the start, and must be found by the player. When the player touches the Goal, they should finish the game.

Let’s start by creating the Goal prefab. We are going to use the Portal sprite for that. So, change the Pixels Per Unit of this sprite to 30, and create a new GameObject from it. As we did with the enemies, we need to add a BoxCollider2D to this object, and set it as a trigger. Finally, save it as a Prefab.

Now, let’s change the DungeonGeneration script to create the Goal inside the furthest room. First, we need to find the furthest room. We do that when iterating through the createdRooms to populate them. For each room, we calculate its distance to the initial one, and save which is the final room. Then, outside this loop, we call PopulatePrefabs again for the final room, but now we are using the Goal prefab instead of the Enemy one, and we only need one Goal object inside the room.

Now, let’s add a new script to the Goal prefab called ReachGoal. In this script, we are only going to implement the OnTriggerEnter2D method and, when the player collides with the goal, we are going to call a method called ResetDungeon inside DungeonGeneration, besides restarting the Demo scene.

Finally, the ResetDungeon method will simply generate the dungeon again.

Now, set the Goal prefab value in the DungeonGeneration script and try playing the game again. By now, you should be able to find the Goal in the dungeon and restart the Demo.

Finishing the demo

The last thing we are going to do is allowing the player to leave a room or the dungeon only when all enemies in that room have been defeated. This is actually very simple to do, but first we need a way to defeat the enemies.

So, let’s add a new script called KillEnemy to the Enemy prefab. In this script we implement the OnTriggerEnter2D method. Since this is just a demo, the enemy will be automatically destroyed when the Player touches it.

Now, we need to update the EnterDoor and ReachGoal scripts to check the number of remaining enemies before leaving the room or the dunteon. Let’s start by the EnterDoor script. Inside the OnCollisionEnter2D method we are going to find the objects with the “Enemy” tag. This will return an array of GameObjects, and if this array length is 0, this means that all enemies have been defeated. If so, we execute the code we already had. Otherwise, we do nothing.

Then we do the same checking inside the ReachGoal script, which means we only restart the dungeon if there are no enemies left inside this room.

Now try playing the game again, and you should only be able to leave a room or restart the dungeon once you have killed all the enemies in that room.

And that concludes this tutorial on Procedural Dungeon Generation using Unity. I hope you enjoyed this tutorial, and if you have any questions, please let me know in the comments section.

Published by

Renan Oliveira

Renan is a computer science master student and game enthusiast. His interest in game development started a few years ago with a 2D game engine course, which resulted in a small 2D engine and game. He started working with Javascript and Phaser with the Zenva Game Development Course. Currently, he is working in his own game.

Share this article

Leave a Reply