For how to set up wild encounters on maps, see Wild encounters.
For triggering an encounter with a specific wild Pokémon, see Event encounters.

This page describes how to create new wild encounter methods. An explanation of what an encounter method is can be found on the Wild encounters page.

There are two steps to adding a new encounter method:

  1. Defining it (getting the game to recognise it as an encounter method).
  2. Making it work (changing which list of wild encounters to use depending on the new encounter method).

This page will add LandAfternoon as an example. Additional code required to add this encounter method will be highlighted.

Defining an encounter method

All encounter methods are defined at the top of the script section PField_Encounters, in module EncounterTypes. Additional information needs to be added to this module in order to define a new encounter method.

There are five sets of data in the module.

Internal names and IDs

The first set of data is a group of internal names for the encounter methods, as well as an ID number for each of them. Each encounter method needs a unique ID number. It is more convenient to not skip numbers. The internal name is how they are referred to in the scripts, e.g. EncounterTypes::RockSmash.

It is simple to add another encounter method here:

Land          = 0
Cave          = 1
Water         = 2
RockSmash     = 3
OldRod        = 4
GoodRod       = 5
SuperRod      = 6
HeadbuttLow   = 7
HeadbuttHigh  = 8
LandMorning   = 9
LandDay       = 10
LandNight     = 11
BugContest    = 12
LandAfternoon = 13

Display names

The Names array contains the names of the encounter methods. These names are used in the PBS file "encounters.txt". For convenience, these names are identical to the internal names above.

Names = [

Data slots and relative probabilities

The EnctypeChances array contains an array of numbers for each encounter method. These numbers define how many data slots each encounter method has (how many numbers are in each array) as well as the relative probability of choosing each data slot (the value of each number).

For example, the first entry of this array is for the "Land" encounter method. It contains 12 numbers, which means that it has 12 data slots. The first number is 20, and the last number is 1; this means that the first encounter slot is 20 times as likely to be chosen as the last encounter slot.

For convenience, the numbers for each existing encounter method add up to 100, so that a number is also a percentage (which is easy to understand). However, the numbers don't have to add up to 100; an encounter method's array could be [1,1,1], which would mean three data slots of equal probability (33.3% each).

EnctypeChances = [

Default encounter densities

The EnctypeDensities array contains the default encounter density values for each encounter method (one number each). An encounter density is the probability of generating an encounter at all of that encounter method - with no modifications, the probability is the encounter density divided by 180.

A higher number means encounters are more likely to happen. For example, "Land" has an encounter density of 25, while "Cave" is only 10. This makes the encounter rate fairer, as "Land" encounters occur only in tall grass (there are tiles you can walk on which aren't tall grass), whereas "Cave" encounters can occur on every single step in a cave.

Not all encounter methods require an encounter density. Typically only encounter methods used due to moving around use them, whereas triggered encounters such as fishing or using Rock Smash do not. Give the encounter methods that don't need an encounter density a value of 0 here.

On top of all that, these values are only used if a map doesn't define its own encounter densities in the PBS file "encounters.txt". If it does, then all "Land"-type encounter methods use the same defined number, all "Cave"-type encounter methods will use one other defined number, and all "Water"-type encounter methods will use the third defined number.

EnctypeDensities = [25,10,10,0,0,0,0,0,0,25,25,25,25,25]

Encounter method types

Following on from above, if a map defines its own encounter densities, it will need to know which encounter methods are "Land"-type", which are "Cave"-type and which are "Water"-type. That is the purpose of the EnctypeCompileDens array.

Each encounter method is defined as "Land"-type (1), "Cave"-type (2) or "Water"-type (3), or 0 if it doesn't need a type (i.e. its default encounter density is 0).

If you want to have a fourth (or fifth, etc.) type of encounter method, you can use 4 and so on here and the code will automatically support it. Remember to ensure that any map in the PBS file "encounters.txt" which defines its own encounter densities has the appropriate number of encounter density values.

EnctypeCompileDens = [1,2,3,0,0,0,0,0,0,1,1,1,1,1]

Mutually exclusive encounter methods

Some encounter methods have restrictions on how and when they can be used. The only example of this in Essentials is that the "Cave" encounter method cannot be used in the same map as a "Land"-type encounter method (and vice versa).

This mutual exclusivity is defined in def pbCompileEncounters in the script section Compiler:

if thisenc && (thisenc[1][EncounterTypes::Land] ||
               thisenc[1][EncounterTypes::LandMorning] ||
               thisenc[1][EncounterTypes::LandDay] ||
               thisenc[1][EncounterTypes::LandNight] ||
               thisenc[1][EncounterTypes::BugContest] ||
               thisenc[1][EncounterTypes::LandEvening]) &&
  raise _INTL("Can't define both Land and Cave encounters in the same area (map ID {1})",mapid)

This code checks whether any map has both the "Cave" encounter method and any of the encounter methods used for tall grass. If so, produces an error message.

There is similar code in def pbNewEncounterType in the script section Editor_Screens. In this case, it prevents the user from using the "Set Encounters" debug option to define a map with both incompatible encounter methods.

If a new encounter method you are adding is incompatible with one or more other encounter methods, you should add code like this to make sure a map can't be defined with both encounter methods.

Making the encounter method work

Once the encounter method is properly defined, you then need to alter the scripts to make them use it where appropriate. This may not be straightforward to do, depending on when exactly it should be used.

There are two possible ways to use an encounter method to trigger a wild encounter:

  • Taking a step: The game decides which encounter method needs to be used (via def pbEncounterType). This decision can depend on a variety of factors, such as which encounter methods are used by the current map, whether something special is happening (e.g. the player is surfing, there is a Bug Catching Contest in progress), and/or the time of day. You can add your own factors too.
  • Triggering an encounter: The thing that triggered the encounter will set the encounter method to use. This can be done by using an item (e.g. fishing rods) or by using moves outside battle (e.g. Rock Smash, Headbutt).

Other situations are also possible, but the above are the only things that matter to the encounter methods in Essentials.

The advice when adding a new encounter method is to find an existing encounter method that works similarly to the way you want your new one to work, and copy it.

"Taking a step"-type encounter methods

The game decides which encounter method needs to be used. It makes this decision in def pbEncounterType, in the script section PField_Encounters.

def pbEncounterType
  if $PokemonGlobal && $PokemonGlobal.surfing
    return EncounterTypes::Water
  elsif self.isCave?
    return EncounterTypes::Cave
  elsif self.isGrass?
    time = pbGetTimeNow
    enctype = EncounterTypes::Land
    enctype = EncounterTypes::LandNight if self.hasEncounter?(EncounterTypes::LandNight) && PBDayNight.isNight?(time)
    enctype = EncounterTypes::LandDay if self.hasEncounter?(EncounterTypes::LandDay) && PBDayNight.isDay?(time)
    enctype = EncounterTypes::LandMorning if self.hasEncounter?(EncounterTypes::LandMorning) && PBDayNight.isMorning?(time)
    if pbInBugContest? && self.hasEncounter?(EncounterTypes::BugContest)
      enctype = EncounterTypes::BugContest
    return enctype
  return -1

The purpose of this method is to decide on the encounter method to check. The encounter method returned by this code is the only encounter method attempted. There are three main sections to this method:

  • Encounters if the player is surfing ("Water"-type).
  • Encounters if the current map has defined "Cave"-type encounters (as determined by def isCave? in the same script section).
  • Encounters if the current map has defined "Land"-type encounters (as determined by def isGrass? in the same script section).

As you can see, priority is given to the "Water" encounter method, as the first step is checking whether the player is surfing. If they are, it doesn't matter whether the player is in a cave or outside or elsewhere, as the encounter method chosen will be "Water".

Otherwise, this code chooses either "Cave" (if that encounter method is used by the current map) or one of the tall grass-based encounter methods (if any of them are used by the current map). Remember that "Cave" and tall grass-based encounter methods are mutually exclusive.

When adding your own encounter method, you should bear in mind whether it or another encounter method should take priority if both are possible with the same step. For example, both "Land" and "LandNight" could be possible at the same time (if you were playing at night), but the code is written to make "LandNight" take priority (if the current map uses "LandNight"). Similarly, while surfing, the map could also use the "Cave" encounter method, but it is "Water" which is chosen.

You can include pretty much whatever code you want here, to help decide which encounter method should be checked. The possibilities are endless.

Note that the code above does not perform checks such as whether the player is on a grass tile. This is done later, by def isEncounterPossibleHere?.

"Triggering"-type encounter methods

These kinds of wild encounters are currently only possible by either using an item (a fishing rod) or by a move outside of battle (Rock Smash or Headbutt). In all cases, these call def pbEncounter with a parameter that is the encounter method they want to use. This is how they determine which encounter method to use.

Community content is available under CC-BY-SA unless otherwise noted.