Essentials Docs Wiki

An event describing a wild battle with a Deoxys.

This page describes how to begin a wild Pokémon encounter on demand. These are typically used for non-roaming legendary encounters, and for any other Pokémon you battle after interacting with it in the overworld (e.g. Voltorb that look like item balls).

Wild battles caused by an event

Event encounters are typically those where the Pokémon to be battled appears as a sprite in the overworld, and interacting with that sprite leads to a wild encounter with that Pokémon. It can also be used to set up traps (whose events will have a blank graphic and will activate upon Player Touch).

The main part of the event is the following line of code:

WildBattle.start(:species, level)

The two parameters here are the ID of the species to be encountered (note the colon in front of it), and its level. The species ID can be a form's ID, e.g. :DEOXYS_1.

Instead of two parameters for the Pokémon (species and level), you can instead generate a Pokémon beforehand using, level) and make modifications to it, and then pass it as a single parameter to WildBattle.start.

The event typically consists of two pages:

  • Page 1 - Contains a call to WildBattle.start.
  • Page 2 - Blank, and depends on the event's Self Switch A being ON.

In most cases, the encounter can only be done once, which means that after the battle, regardless of the outcome, the event should go to page 2. Simply set the event's Self Switch A to ON immediately after the battle.

If the event Pokémon will only disappear because of certain battle outcomes (e.g. because of a win, capture or flee, but not because of a loss), then you will need to check the specific outcome of the battle. This will be in Game Variable 1 by default, although you can make it go into a different Game Variable using the script setBattleRule("outcome", 42) (Game Variable 42 in this example) before the battle is started. After the call to WildBattle.start, instead of simply setting the event's Self Switch A, you should create one or more Conditional Branches which check the outcome value and do things accordingly. Possible outcome values are:

  • 0 - Undecided or aborted
  • 1 - Player won (the wild Pokémon fainted)
  • 2 - Player lost
  • 3 - Player or wild Pokémon ran from battle
  • 4 - Wild Pokémon was caught
  • 5 - Draw

Battles against multiple wild Pokémon

Event encounters against two or three wild Pokémon are set up in the same way as single event encounters. Simply add the extra Pokémon as arguments to the call to WildBattle.start as follows:

WildBattle.start(:species1, level1, :species2, level2)
WildBattle.start(:species1, level1, :species2, level2, :species3, level3)
WildBattle.start(pkmn1, :species2, level2)
WildBattle.start(:species1, level1, pkmn2, :species3, level3)

As shown, you can mix and match whether a Pokémon is given to WildBattle.start as a species/level pair of arguments or as a single pre-generated Pokémon (see an example below of pre-generating a Pokémon). WildBattle.start can accept any number of Pokémon as arguments, but the battle scripts are only coded to work properly with a maximum of 3 wild Pokémon.

By default, the number of Pokémon that the player will send out at once is the same as the number of wild Pokémon, or will be as many as possible if the player has fewer Pokémon than that. You may instead want to use pbCanDoubleBattle? or pbCanTripleBattle? in a Conditional Branch at the top of the event page to check if the player has the matching number Pokémon for each size of battle, and not allow the battle if they don't.

You can use setBattleRule("1v2") or similar to set the battle to a particular maximum size (in this case, 1 player's Pokémon versus 2 opposing Pokémon). This should be used in conjunction with the code/Conditional Branch mentioned in the previous paragraph, as wild battles will still resize themselves according to how many Pokémon the player can use - this battle rule just sets the maximum size.


WildBattle.start(:KECLEON, 20)

This triggers an encounter with a Level 20 Kecleon.

WildBattle.start(:PIKACHU, 21, :CLEFAIRY, 17)

This triggers a double wild encounter with a Level 21 Pikachu and a Level 17 Clefairy.

setBattleRule("outcome", 42)
WildBattle.start(:MEWTWO, 70)

This triggers an encounter with a Level 70 Mewtwo. The outcome of the battle is stored in Game Variable 42, and the player cannot run from the battle. If the player loses the battle against Mewtwo, their party will be fully healed instead of them blacking out. See the page Battles for a list of all battle rules.

pkmn =, 70)
pkmn.ability_index = 2   # Gives the first Hidden Ability

This generates a Level 70 Mewtwo in advance and modifies it (makes it shiny, teaches it the move Psycho Cut, and makes it have its first Hidden Ability), and then triggers a battle against it. If you do this, bear in mind that pkmn will only exist in the Script event command it is generated in - you cannot generate a Pokémon in a Script command and then use it in a Conditional Branch or a later Script command.

Modifying the Pokémon

Main article: Editing a Pokémon

It is possible to modify many attributes of a wild Pokémon encountered via an event (e.g. make it shiny, choose its gender, change its stats/moveset/etc.). The method described below is the best way of editing a wild Pokémon encountered in an event encounter.

Firstly, define a Game Switch that will cause one of these modifications (e.g. making the Pokémon shiny). Then, in the script section Overworld_EncounterModifiers, you will find (something similar to) the following:

EventHandlers.add(:on_wild_pokemon_created, :make_shiny_switch,
  proc { |pkmn|
    pkmn.shiny = true if $game_switches[31]

This code will take the Pokémon generated at the start of any wild encounter and allow its attributes to be edited. In this example, the Pokémon is made shiny if Game Switch 31 is ON. For event encounters, it is simplest to allow an edit to be made only if a certain Game Switch is ON, because you can easily toggle it ON and OFF in the same event that triggers the battle.

make_shiny_switch, which is highlighted in yellow, is the "name" of this particular piece of code. Each piece of code must have a unique name, so if you copy this code to add your own, remember to rename your copy.

Once you have written your own version of the code above, in the event that triggers the battle, turn the Game Switch you have chosen ON immediately before the call to WildBattle.start and OFF immediately afterwards, like so:

@>Control Switches: [0031: Shiny wild Pokémon] = ON
@>Script: WildBattle.start(:GYARADOS, 30)
@>Control Switches: [0031: Shiny wild Pokémon] = OFF

It is important that the Game Switch be turned OFF again immediately afterwards, because if it isn't, all future wild encounters will also be shiny (or have whatever edited attributes you chose).


  • You can combine an event encounter with a time-sensitive event, in order to have a Pokémon that only appears at certain times.
    • Alternatively, the Pokémon could return some time after it was battled, ready for re-battling. Typically, this would only be done if the battle was lost or fled from (and not if the Pokémon was defeated or captured) - take advantage of the battle's outcome being stored in a Game Variable in order to achieve this. Entering the Hall of Fame is a typical trigger point for making such Pokémon reappear.
  • Set traps for the player by springing wild Pokémon encounters on them in specific places (an example in the games is the Team Rocket HQ under Johto's Mahogany Town). Simply don't give the event a sprite, and have it trigger when stepped on rather than interacted with.
  • You could make the Pokémon begin roaming if the battle is lost or fled.
  • You can use various battle rules to modify the battle, from setting a default terrain to disabling Exp gain/Poké Ball use. A few are shown above.
    • You can invent new battle rules, e.g. switching is forbidden, or the weather randomly changes every turn. In this way, you can customise certain wild encounters to make them unique/harder.
  • Have the Pokémon drop something if it is defeated. Edit page 2 of the event accordingly to turn the event into an item ball.
  • Allow the battle to take place only if the player has a certain Key Item (e.g. the Devon Scope for invisible Kecleon), and have the event be unresponsive and simply block the player's progress otherwise.