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:

Property	Description	Necessary?
:id	The ID of the encounter type, as a symbol.	Yes
: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.	No (default is :none)
:trigger_chance	This is the percentage chance that an encounter using this encounter method will happen when prompted (e.g. upon taking a step, upon using Rock Smash). It is used as the default step chance when creating a new set of wild encounters in the Debug mode feature "Edit Wild Encounters", but 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).	No (default is 0)

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 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.
• 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.

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 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, each "base type"'s set of time-related encounter methods need to be named a particular way. If you create a new encounter method and want to make use of this script, you will need to be careful with how you name them. Note that you do not need 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 (e.g. the Old Rod only ever triggers the :OldRod encounter method), although Headbutt has two encounter methods to choose between, and Rock Smash has a percentage chance of trying to trigger a wild encounter. This is not worth documenting.