Adding new encounter methods

*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).

## Defining an encounter method

All encounter methods are defined in the script section **EncounterType**. Each encounter method is registered in the Game Data separately; you can define additional encounter methods in any script section (you can put all your new ones in a new script section to keep track of the code changes you make).

Examples of definitions of encounter methods are:

```
GameData::EncounterType.register({
  :id             => :Land,
  :type           => :land,
  :trigger_chance => 21
})

```

```
GameData::EncounterType.register({
  :id             => :CaveNight,
  :type           => :cave,
  :trigger_chance => 5
})

```

```
GameData::EncounterType.register({
  :id             => :OldRod,
  :type           => :fishing
})

```

```
GameData::EncounterType.register({
  :id             => :RockSmash,
  :type           => :none,
  :trigger_chance => 50
})

```

The properties an encounter method can be given are as follows:

 `:type` | The category that this encounter type belongs to. Is one of `:land`, `:cave`, `:water`, `:fishing`, `:contest` or `:none`.
The type has several effects. `:land` is for encounter types that occur when moving in tall grass, roaming Pokémon can be made to appear only for certain types of encounter, the Poké Radar only works for `:land` encounter types, and so on.
 `:trigger_chance` | This is the default percentage chance that an encounter using this encounter method will happen when prompted (e.g. upon taking a step, upon using Rock Smash). When creating a new set of wild encounters in the Debug mode function "Edit Wild Encounters", their step chances are set to this value, but it can then be changed for any individual set. This value is not used by anything else.
For encounter methods that are prompted by taking a step (in tall grass, caves, surfing), this number also determines how many steps the player can take after a battle before another another encounter could happen (max. 8, but lower if this trigger chance is higher). Effects that alter the encounter rate also affect the number of "safe" steps (e.g. Cleanse Tag reduces the trigger chance and increases the number of "safe" steps).

All encounter methods are compatible with all other encounter methods. For example, a map could have both :Cave and :Land wild encounters defined, and the :Land encounters would be used if the player walks in tall grass, while the :Cave encounters would be used if the player walks anywhere else.

## Making the encounter method work

Once an encounter method is properly defined, scripts need to be altered to make use of it at the appropriate times. 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 (in `def encounter_type` in `class PokemonEncounters`). This decision can depend on a variety of factors, such as which encounter methods appear in the current map's set of encounters, whether something special is happening (e.g. the player is surfing, there is a Bug Catching Contest in progress), whether the player is standing in tall grass, and/or the time of day. You can add your own factors too.
* Direct triggering: A wild encounter is directly triggered by using an item (e.g. fishing rods) or by using moves outside battle (e.g. Rock Smash, Headbutt). The thing that triggered the wild encounter will determine the encounter method to use.

When making something that directly triggers a wild encounter, the advice is to copy an existing thing that works similarly.

### "Taking a step" encounter methods

The game decides which encounter method needs to be used in any given situation. It makes this decision in `def encounter_type` in `class PokemonEncounters`.

```
def encounter_type
  time = pbGetTimeNow
  ret = nil
  if $PokemonGlobal.surfing
    ret = find_valid_encounter_type_for_time(:Water, time)
  else   # Land/Cave (can have both in the same map)
    if has_land_encounters? && $game_map.terrain_tag($game_player.x, $game_player.y).land_wild_encounters
      ret = :BugContest if pbInBugContest? && has_encounter_type?(:BugContest)
      ret = find_valid_encounter_type_for_time(:Land, time) if !ret
    end
    if !ret && has_cave_encounters?
      ret = find_valid_encounter_type_for_time(:Cave, time)
    end
  end
  return ret
end

```

The encounter method returned by this code is the *only* encounter method attempted. It should always be successful in choosing a Pokémon to encounter via it, though.

The code `has_land_encounters?` and `has_cave_encounters?` check whether there are wild encounters of those types (see the `:type` property above) defined for the current map. There is also `has_water_encounters?`, which is currently unused.

Note the way in which this script is written. For example, if the player is surfing, it will *only* check for Water encounter methods, and it checks this first because the current map may also have cave-type encounters (triggered upon every step, even while surfing), but it is not appropriate to check for the :Cave encounter methods while surfing. Another example is the :BugContest encounter method, which is checked before the other :Land encounter methods (which are then skipped if the player is in a Bug Catching Contest and :BugContest encounters are defined for the current map).

After deciding whether the player is surfing, or the map has and land- or cave-type encounters defined, or whether the player is in a Bug Catching Contest, the above script calls `def find_valid_encounter_type_for_time` with an appropriate "base type" (`:Land`, `:Cave` or `:Water`) and the current time.

```
def find_valid_encounter_type_for_time(base_type, time)
  ret = nil
  if PBDayNight.isDay?(time)
    try_type = nil
    if PBDayNight.isMorning?(time)
      try_type = (base_type.to_s + "Morning").to_sym
    elsif PBDayNight.isAfternoon?(time)
      try_type = (base_type.to_s + "Afternoon").to_sym
    elsif PBDayNight.isEvening?(time)
      try_type = (base_type.to_s + "Evening").to_sym
    end
    ret = try_type if try_type && has_encounter_type?(try_type)
    if !ret
      try_type = (base_type.to_s + "Day").to_sym
      ret = try_type if has_encounter_type?(try_type)
    end
  else
    try_type = (base_type.to_s + "Night").to_sym
    ret = try_type if has_encounter_type?(try_type)
  end
  return ret if ret
  return (has_encounter_type?(base_type)) ? base_type : nil
end

```

This script determines the time of day and looks for time-appropriate encounters defined for the current map. If there are encounters defined for a checked encounter method, this script will return it. If not, it returns `nil`.

The encounter methods checked for by this script are the "base type" (`:Land`, `:Cave` or `:Water`) with a time period's word added onto the end (e.g. `:LandMorning`, `:LandDay`, `:LandNight`). Some time periods overlap (morning, afternoon and evening are all part of the daytime), so this script will check the shorter time periods (morning, afternoon, evening) before the longer time periods (day).

Because this script adds words onto the end of the "base type" to create new encounter methods to check for, there is a naming convention for time-related encounter methods (as explained in the paragraph above). If you create a new encounter method for a particular time of day and want to make use of this script, you will need to be careful with how you name it. Note that you don't have to create variants of your new encounter method for all these time periods, though; ones that do not exist will just not produce a result, and the script will move on to the next check.

Note that the scripts above do *not* check whether a wild encounter should be triggered. That is determined in `def encounter_possible_here?`. You should not need to change this script.

### "Direct triggering" 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, the effects of these items/moves is to determine which encounter method they want to trigger, and then call `def pbEncounter` with that encounter method.

The determination is typically very straightforward. The Old Rod, for example, only ever triggers the `:OldRod` encounter method. Headbutt has two encounter methods it could trigger (`:HeadbuttLow` and `:HeadbuttHigh`), which it chooses between with a calculation that involves the player's public ID and the coordinates of the tree being headbutted. Rock Smash uses `$PokemonEncounters.encounter_triggered?` to decide whether the smashing of a rock should result in a wild battle (this uses the trigger chance as described above).

To add a new encounter method that directly triggers a wild encounter, simply look at an existing example (i.e. an effect that calls `pbEncounter` and copy that.