Essentials Docs Wiki
For having wild Pokémon encounters occur anywhere within a map, see Wild encounters.

An example of a dungeon map.

This page describes how to use randomly-generated dungeons.

What are dungeons?

A dungeon map is a collection of small rooms and connecting corridors, with one entrance and exit. They typically take the form of cave systems. Dungeon maps feature heavily in the Mystery Dungeon set of Pokémon games.

The layout of a dungeon map is randomly generated every time it is entered. The same dungeon map will never have the same layout in successive visits.

One drawback with dungeons is that they are quite plain, as by default they only use up to three different textures (floor, wall, void), and the only decorations are events.

Dungeon generation

The dungeon generation code is all in the script section Overworld_RandomDungeons. It follows these main steps in order:

  1. Use the size of the map to determine how many cells it contains.
  2. Generate connections between the cells.
  3. Generate corridors and rooms.
  4. Add walls.
  5. Turn the layout into map data.
  6. Distribute events.
  7. Choose where the player enters the map.

1. Calculate the cells

The map is divided up into cells, each of the same width and height. There is buffer space around the edges of the map, to ensure the player cannot get close enough to the edges to see the blackness beyond the map. This buffer space is defined in class Dungeon as the constants BUFFER_X and BUFFER_Y.

After subtracting the buffer distances from the map's width and height, the remaining sizes are divided by DungeonMaze::CELL_WIDTH and DungeonMaze::CELL_HEIGHT (rounded down). These two values are the size of a cell, and are both 13 tiles by default. Since the number of cells in each direction must be a whole number (hence the divisions are rounded down), the exact size of a map will not affect the dungeon's generation. Instead, there are ranges of map widths and heights corresponding to different numbers of cells. By default, these ranges are:

  • Width:
    • 20 to 41 tiles: 1 cell across
    • 42 to 54 tiles: 2 cells across
    • 55 to 67 tiles: 3 cells across
    • 68 to 80 tiles: 4 cells across
    • 81 to 93 tiles: 5 cells across
    • etc.
  • Height:
    • 15 to 37 tiles: 1 cell up/down
    • 38 to 50 tiles: 2 cells up/down
    • 51 to 63 tiles: 3 cells up/down
    • 64 to 76 tiles: 4 cells up/down
    • 77 to 89 tiles: 5 cells up/down
    • etc.

If the map is 1x1 cell in size (i.e. 41x37 tiles or smaller), then it will consist of a single room that is as large as possible. This room can be larger than any room generated in larger dungeon maps.

2. Generate cell connections

The generator chooses a random cell (hereafter referred to as a node) to start at.

The starting node is marked as "visited". Each of the four cardinal directions is randomly chosen in turn. For each one, if there is an unvisited node in that direction from the starting one, the two nodes are marked as linked, and then the same process described in this paragraph is repeated but with the new node as the starting node. If there are no unvisited nodes next to the starting node, the generator moves back to the previous node and continues checking each of its directions in turn.

In short, this is a depth-first recursive algorithm. It results in every cell in the map being connected to at least one other cell, where every cell can be reached from any other cell. There will not be any loops; every pair of rooms will have exactly one way to travel between them.

3. Generate corridors and rooms

For each cell, a corridor is drawn depending on how the cell connects to its neighbours.

Then, for each cell, there is a 70% chance that a room will be drawn in it. The room will be a rectangle of a random size, 5-11 tiles wide and 4-10 tiles tall. It is positioned randomly within the cell (which is 13x13 tiles). The room size limits are defined as several constants in module DungeonMaze.

It is possible for no rooms to be generated. In this case, the dungeon will be a single room that is as large as possible.

4. Generate walls

The northern edges of all corridors and rooms which are empty tiles will have wall tiles drawn in them. The walls are two tiles high.

The dungeon generator algorithms are designed to ensure that walls can always be drawn on the northern edges of corridors and rooms. They will not overlap a floor tile.

5. Use the tileset to draw the map

Thus far, tiles in the map have only been designated as room floor, corridor floor, wall or void. This step turns these designations into tileset tile numbers and creates proper map data that can be used.

6. Randomize event locations

For each event in turn, a random location within a room (not a corridor) is chosen to place it in. An event cannot be placed in the same location as or directly adjacent to another event.

7. Choose a random entry point

The dungeon generator is run when the map is loaded. This means that the player is transferring into the map. This step chooses a valid location to transfer to. Again, this location will be in a room (not a corridor) and cannot be on or directly adjacent to an event.

Setting up a dungeon map

To create a dungeon map, simply create a blank map and set its "Dungeon" map metadata to TRUE. Whenever that map is entered, its layout will be randomly generated. The dungeon will fill the entire map, so change the size of the map to make the dungeon bigger or smaller (see above for which sizes correspond to which extents of dungeon).

You will also need to make sure the dungeon map uses the proper graphics. Dungeon maps are drawn using the first 3 definable autotiles of the tileset used by that map, in the following order:

  1. The area surrounding the map, usually blackness. Unpassable.
  2. Floor. Passable.
  3. Wall. Unpassable.

You should use a separate tileset just for dungeons, set up with appropriate autotiles.

It should go without saying that dungeon maps should not be directly connected to any other map.

Filling up the dungeon

You can place events anywhere on the map. The game will place them randomly on the dungeon floor when it generates the dungeon.

One vital event you must include is one that moves the player to a new map; this is the only way the player will be able to leave the dungeon (assuming they don't have an Escape Rope or other special means of escape that is usable in the map).

Other events you may include are item ballstrainers and Pokémon set to wander around (and which trigger a battle with that Pokémon).

You can also define "Cave" wild encounters as you can for any other cave.


  • The minimum recommended size for a dungeon is 68x64 tiles. This allows for 4x4 separate chambers all connected with corridors.
  • Modify the dungeon generator to make the dungeons look better, e.g. to use more graphics from the tileset such as random rock formations, pools of water, etc.
  • To keep a dungeon useful as a training area, you can modify the wild Pokémon's levels so that they are based on the levels of the Pokémon in the player's party. The dungeon in the example maps does this with code in the script section Overworld_EncounterModifiers.
  • Dungeons don't need to be just caves. Experiment with other environments, e.g. pyramid interior, deep forest, ocean reef.
  • A dungeon map will only randomly create itself when entered from another map. It will not change its layout if you transfer to a different part of the map while you are already in it. To create a location with multiple dungeon floors, you can use two dungeon maps and alternate between them as the player progresses through the floors (keeping track of which floor the player is currently on with a Game Variable by adding 1 to it each time they change maps).