Essentials Docs Wiki
For how to define the information shown in the Town Map, see Region map.
For the places the player walks around in, see Maps.

This page describes how to separate a game into several distinct regions, and how to create a Regional/National Pokédex.

Multiple regions

A region is an area that contains a number of distinct locations. The Town Map shows the region and all the locations within it. Two regions are therefore distinctly separate from each other, although maps belonging to each region can connect to each other to allow easy movement from one region to the other.

Different regions may contain different wild Pokémon, and consequently have their own Regional Pokédex list.

To set up a new region in a game, the following should be done:

  • Create a region map picture (shown in the Town Map) and fill it with information points.
  • Assign maps to that region.
  • Create a Regional Pokédex _optional).

Defining a region

Main article: Region map

The PBS file "town_map.txt" defines the region map for each region, as well as filling in the squares of that map with information (such as the location's name as seen in the Town Map). Each region has its own section, beginning with a number in square brackets (the region's ID number). For example:

Name = Kanto
Filename = kantomap.png
Point = 10,5,Pallet Town,,17,9,8,
Point = 6,4,Route 1,,,,,
Point = 6,5,Viridian Forest,,,,,
Name = Johto
Filename = johtomap.png
Point = 11,5,New Bark Town,,42,9,8,
Point = 10,4,Route 29,,,,,
Point = 7,5,Dark Cave,,,,,

The numbering of regions should start at 0 and count upwards, without skipping numbers. There is no (practical) limit to the number of regions a game can have, although it would be very unusual to have many of them.

Adding game maps to a region

Main article: Map metadata

The PBS file "map_metadata.txt" lists each map in the game, along with various map metadata relating to each map.

When considering multiple regions, the "MapPosition" metadata is the important one. It contains three numbers: a region ID number, followed by the X and Y coordinates of that map's position in the Town Map of that region. There are no other differences between maps in different regions.

Note that all maps must be assigned to a region, including building interiors. This is because when the Town Map is viewed, the region map shown depends on the "MapPosition" metadata of the map the player is currently on, and if there is none set, there can be an error.

Regional Pokédexes

There are two basic types of Pokédex list: the National Dex and the Regional Dex. The National Dex is simply a list of all species defined in the PBS file "pokemon.txt" (in the order they are defined).

Regional Dexes are defined in the PBS file "regional_dexes.txt". Each section is one separate Regional Dex list, where a section begins with a Regional Dex ID number in square brackets. The rest of the section is a list of the species in that Regional Dex, in the order they will appear in it. The Debug feature "Edit Regional Dexes" can create and edit Regional Dex lists.



Note that multiple species can be listed on the same line, and also that there can be multiple lines for species in each section. There is no difference between these two approaches, and both are supported just because the developer may find it convenient to group certain species in the same line. When using the Debug feature "Edit Regional Dexes", it will rewrite the PBS file "regional_dexes.txt", and it will do so by putting species in the same evolutionary family in the same line and have separate lines for different families (this will not alter the order of the species).

It is important to note that the ID numbers of Regional Dexes may or may not correspond to region numbers as defined above. This depends on the setting USE_CURRENT_REGION_DEX. See below for more information.

Regional Dex settings

In the script section Settings are the following settings:

# Whether the Pokédex list shown is the one for the player's current region
# (true), or whether a menu pops up for the player to manually choose which
# Dex list to view if more than one is available (false).

# The names of the Pokédex lists, in the order they are defined in the PBS
# file "regional_dexes.txt". The last name is for the National Dex and is
# added onto the end of this array (remember that you don't need to use it).
# This array's order is also the order of $player.pokedex.unlocked_dexes,
# which records which Dexes have been unlocked (the first is unlocked by
# default). If an entry is just a name, then the region map shown in the Area
# page while viewing that Dex list will be the region map of the region the
# player is currently in. The National Dex entry should always behave like
# this. If an entry is of the form [name, number], then the number is a region
# number, and that region's map will appear in the Area page while viewing
# that Dex list, no matter which region the player is currently in.
def self.pokedex_names
  return [
    [_INTL("Kanto Pokédex"), 0],
    [_INTL("Johto Pokédex"), 1],
    _INTL("National Pokédex")

# Whether all forms of a given species will be immediately available to view
# in the Pokédex so long as that species has been seen at all (true), or
# whether each form needs to be seen specifically before that form appears in
# the Pokédex (false).

# An array of numbers, where each number is that of a Dex list (in the same
# order as above, except the National Dex is -1). All Dex lists included here
# will begin their numbering at 0 rather than 1 (e.g. Victini in Unova's Dex).

Pokédex contents depend on location


The Regional Dex shown when the Pokédex is opened will correspond exactly to the region the player is in (e.g. the first Regional Dex for the first region, the second for the second, etc.).

If there is no Regional Dex corresponding to the current region (e.g. the player is in the fourth region, but only three Regional Dexes have been defined), then the National Dex will be shown instead. If the map the player is currently in is not associated with a region (i.e. its "MapPosition" map metadata is not set), then the National Dex will be shown.

Usually the National Dex will never be shown. There will never be an option to choose which Dex list to view.

The array of Dex names in def self.pokedex_names is unused.

Pokédex contents do not depend on location


The player manually chooses which Dex list to view when using the Pokédex. However, they can only choose from the Dex lists that have been unlocked and are not empty. If there is only one such Dex list, that one is shown automatically when the Pokédex is opened.

The array of Dex names in def self.pokedex_names is used. If a Regional Dex is defined here with a region number, but there is no corresponding region of that number, the Town Map graphic shown will be that of the region the player is currently in instead.

An array in $player.pokedex called unlocked_dexes records which Dex lists have been unlocked. This array is not directly accessible by code. The size of this array depends on how many Regional Dexes are defined in the PBS file "regional_dexes.txt" when the game is started - adding more Regional Dexes afterwards but still using an older save file will cause problems.

The first Regional Dex is automatically unlocked at the start of the game, but the rest are locked and will need to be unlocked manually later on. To unlock a Dex, use the following code:


The number is the number of the Regional Dex list to unlock, but -1 corresponds to the National Dex instead.

Similarly, you can lock a Dex as follows:


The only way in which a Regional Dex corresponds to an actual region, when USE_CURRENT_REGION_DEX is FALSE, is when the numbers in the Pokédex names array determine the region map to show when looking at a species' area map.

Regional Pokémon storage

Essentials contains scripts for regional Pokémon storage, which is a way of separating Pokémon caught in different regions so that a Pokémon caught in one region cannot be used in another region.

However, this is not currently enabled and is not documented here.


  • You can use the multiple regions feature in a number of ways, e.g.
    • Have one Dex list per region. This is the typical use.
    • Johto "Old" and "New" styles (i.e. just rearrange the National Dex) - a Regional Dex doesn't need to contain fewer Pokémon than the National Dex.
    • Characteristic-based Dex lists (e.g. "common"/"legendary", habitats, type-ordered). Having one Dex list per characteristic may lead to having lots of Dex lists.
  • You don't need to have the National Dex in your game at all. Even if it appears in the Pokédex names array (which it doesn't have to), you may simply never use/unlock it.
  • To easily remove Regional Dexes, you can use the Debug feature "Edit Regional Dexes" to delete the Regional Dexes you want. Remember to start a new save file afterwards rather than loading a saved game.