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:

pbWildBattle(: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.

The event typically consists of two pages:

  • Page 1 - Contains a call to pbWildBattle.
  • 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 case) before the battle is started. After the call to pbWildBattle, 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. The only difference is the code used to start the battle:

pbDoubleWildBattle(:species1, level1, :species2, level2)
pbTripleWildBattle(:species1, level1, :species2, level2, :species3, level3)

These work in the same way as pbWildBattle, except a second (and third) species/level are also defined.

By default, the number of Pokémon that the player will send out will match 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? 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 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.


pbWildBattle(:KECLEON, 20)

This triggers an encounter with a Level 20 Kecleon.

pbDoubleWildBattle(:PIKACHU, 21, :CLEFAIRY, 17)

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

setBattleRule("outcome", 42)
pbWildBattle(: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.

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:

Events.onWildPokemonCreate += proc { |sender, e|
  pkmn = e[0]
  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.

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 pbWildBattle and OFF immediately afterwards, like so:

@>Control Switches: [0031: Shiny wild Pokémon] = ON
@>Script: pbWildBattle(: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.
  • 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. A few are shown above.
    • You can invent new battle rules, e.g. all Poké Balls used will always fail, 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.