For a description of what happens in a battle round, see Battle round.
For how computer-controlled Pokémon/trainers make decisions in battle, see Battle AI.
For how to make animations for moves and effects, see Attack animations.
For how a battle's background images and music are chosen, see Backgrounds and music.
For what happens at the end of a battle, see Ending a battle.
For how to repeatedly battle the same trainers, see Rematches.

A Pokémon battle.

This page describes Pokémon battles, and gives an overview of the scripts involved.

Causing a battle to happen

Main article: Event encounters
Main article: Trainers

There are several ways to cause a battle to happen. You could be walking around in tall grass and a wild battle spontaneously occurs, you could walk in front of (or talk to) a trainer and enter a battle against them, or a battle could be scripted to happen when something occurs (such as interacting with something in the overworld).

There are different scripts you can use to make different kinds of battles happen. These include:

pbWildBattle(:PIKACHU,42)
pbDoubleWildBattle(:PIKACHU,42,:IVYSAUR,17)
pbTripleWildBattle(:PIKACHU,42,:IVYSAUR,17,:GEODUDE:25)
pbTrainerBattle(:YOUNGSTER,"Ben")
pbDoubleTrainerBattle(:YOUNGSTER,"Ben",0,nil,:LASS,"Alice")
pbTripleTrainerBattle(:YOUNGSTER,"Ben",0,nil,:LASS,"Alice",0,nil,:CAMPER,"Carl")

These scripts are described in more detail on the Event encounters and Trainers pages.

The Pokémon encountered in a wild battle can depend on special conditions, e.g. Roaming Pokémon or forcing a wild Pokémon to be shiny. You can create your own special conditions; see the page Wild encounters for more details.

Battle rules

It is possible to apply one or more rules to a particular battle, which affect how parts of the battle work. This can range from changing the size of the battle (e.g. double instead of single) to preventing escape from a wild Pokémon to enabling battle animations regardless of what the player has set the "Battle Effects" option in the Options screen to.

To apply a battle rule, run the following line of code (usually in a Script event command in the event that triggers the battle) at some point prior to the method call that starts the battle:

setBattleRule("double")

This particular battle rule will make it a double battle (2v2) rather than a single battle (1v1). You can use this code multiple times, each with a different rule in it, to apply multiple rules to the same battle.

A battle rule applies only to the next battle that happens after it is set, and will be cleared afterwards. Battle rules can apply to both wild and trainer battles, although some may not have an effect after all.

The available battle rules are:

Rule Description
"single", "1v1", "1v2", "2v1", "1v3", "3v1", "double", "2v2", "2v3", "3v2", "triple", "3v3" These rules change the size of the battle. The first number is how many Pokémon are on the player's side of the battle, and the second number is how many Pokémon are on the foe's side. These are the total numbers and include a partner trainer's Pokémon as well as the Pokémon of all opposing trainers (e.g. if it is "2v2" and the player has a partner trainer and they are fighting two separate trainers, each trainer in the battle will have just one Pokémon in battle at once).
"canLose", "cannotLose" These rules determine what happens if the player loses the battle.

If it is "cannotLose", the player will black out and return to the last healing point (this is the default behaviour). If it is "canLose", the game will continue regardless and the player's Pokémon will be fully healed instead of blacking out.

"canRun", "cannotRun" These rules determine whether the player is allowed to run from the battle. It only applies to wild battles, because it is impossible to run from a trainer battle no matter what.
"noExp" If set, the player's Pokémon will not gain any Exp from the battle.
"noMoney" If set, the player will not gain any money from winning the battle (not even money from Pay Day), and will not lose any money if they lose the battle.
"switchStyle", "setStyle" These rules determine whether the player is asked if they want to switch Pokémon after they defeat an opposing Pokémon. Only applies to trainer battles, and only if there is only one Pokémon on the player's side.

These rules override the "Battle Style" option in the Options screen.

"anims", "noAnims" These rules determine whether all battle animations are played.

These rules override the "Battle Effects" option in the Options screen.

"terrain" Sets the default terrain effect of the battle. Normally there is no terrain effect. Setting this battle rule requires an additional parameter that states which terrain effect to apply, like so:
  • setBattleRule("terrain", :None)
  • setBattleRule("terrain", :Electric)
  • setBattleRule("terrain", :Grassy)
  • setBattleRule("terrain", :Misty)
  • setBattleRule("terrain", :Psychic)

The possible terrain effects are listed in the script section PBBattleTerrains.

"weather" Sets the default weather of the battle. Normally the weather is determined by the overworld weather. Setting this battle rule requires an additional parameter that states which weather to apply, like so:
  • setBattleRule("weather", :None)
  • setBattleRule("weather", :Sun)
  • setBattleRule("weather", :Rain)
  • setBattleRule("weather", :Sandstorm)
  • setBattleRule("weather", :Hail)
  • setBattleRule("weather", :HarshSun)
  • setBattleRule("weather", :HeavyRain)
  • setBattleRule("weather", :StrongWinds)
  • setBattleRule("weather", :ShadowSky)

The possible weathers are listed in the script section PBWeather.

"environment" Sets the default environment of the battle. Normally the environment is determined by metadata and terrain tags and some other factors (see below). Setting this battle rule requires an additional parameter that states which environment to apply, like so:
  • setBattleRule("environment", :None)
  • setBattleRule("environment", :Grass)
  • setBattleRule("environment", :MovingWater)
  • setBattleRule("environment", :Sand)
  • setBattleRule("environment", :Forest)
  • setBattleRule("environment", :UltraSpace)

The possible environments are listed in the script section PBEnvironment.

"backdrop" Sets the backdrop phrase used to determine which background graphics to use. Normally this is determined by metadata. Setting this battle rule requires an additional parameter that gives the phrase to use, like so:
  • setBattleRule("backdrop", "mystic")
  • setBattleRule("backdrop", "elite2")
  • setBattleRule("backdrop", "rocky")

For more information, see Backgrounds and music.

"base" Sets the base phrase used to determine which base graphics to use. Normally this is determined by the battle's environment. Setting this battle rule requires an additional parameter that gives the phrase to use, like so:
  • setBattleRule("base", "grass")
  • setBattleRule("base", "sand")
  • setBattleRule("base", "ice")

For more information, see Backgrounds and music.

"outcome" Sets which Game Variable the outcome of the battle will be saved in. By default the outcome is saved in Game Variable 1. Setting this battle rule requires an additional parameter that gives the number of the Game Variable to use, like so:
  • setBattleRule("outcome", 42)
"noPartner" If set, the partner trainer will not participate in the battle even if they normally would.

These rules are all defined at the top of the script section PField_Battle, and are applied a little further down in def pbPrepareBattle. Their actual effects are coded in various places depending on what they do.

Battle transition

When a battle occurs, the overworld need to fade to black before the battle starts. This fade to black can be a fancy animation, and is referred to as a battle transition. The main code for the battle transition is def pbBattleAnimation in the script section PField_Visuals.

The choice of which battle transition to display can depend on a variety of factors, such as the current location, what kind of battle it will be, and the time of day. If you prefer, though, you can make the choice depend on other factors too, and/or simply be random.

By default, all the regular battle transitions mimic the ones from Pokémon HeartGold and SoulSilver, in both their appearance and when they are chosen to be used. The names of these battle transitions are in the above-mentioned method, and the code for them (as well as for others) can be found in the script section Transitions.

It is also possible for battle transitions to use a grey-scale image from the "Graphics/Transitions" folder, as they do in RPG Maker XP by default. These images cover the entire screen, and describe which parts of them fade to black when (darker areas become black first). However, Essentials does not fully support these kinds of battle transitions, as they aren't coded to support different screen sizes (hence why they aren't used by default).

At certain times, you may want to use a special battle transition (e.g. a Vs. animation when facing important trainers). In this case, you should make use of def pbBattleAnimationOverride and the associated alias to play these special battle transitions (as well as making the decision that they should be used). The Vs. animation that comes with Essentials is an example of how to do this. See the page Trainers for more information.

Battle environment

A battle's environment is what kind of location the battle is taking place in. This can depend on various factors, including map metadata and the terrain tag of the tile being stood on (or the one being fished into).

The environment is chosen just before the start of a battle, by def pbGetEnvironment in the script section PField_Battles. The possible environments are defined in the script section PBEnvironment.

The environment plays a part in what the battle's background looks like. It also affects the effects of several moves, as well as the efficiency of the Dive Ball. It also affects the forms of Burmy and Wormadam.

The battle screen

The positions of some of the elements in the battle screen are listed in the script section PokeBattle_SceneConstants.

The bar at the bottom of the screen in battle can be in one of five states: showing the command menu (Fight/Bag/Pokémon/Run), showing the fight menu (the moves known by the Pokémon you're currently choosing an action for), choosing a target (for a move/Poké Ball), showing messages, or blank (typically the same as showing an empty message).

Command menu

The command menu's code is in class CommandMenuDisplay in the script section PokeBattle_SceneMenus. The control of the cursor is done in def pbCommandMenuEx in the script section Scene_Commands.

If a type with the internal name of SHADOW is defined, and the battle is against a trainer, the "Run" command will be replaced with the "Call" command. This is decided in def pbCommandMenu in the script section Scene_Commands.

There is also def pbSafariCommandMenu in the script section PokeBattle_SafariZone, which decides on the commands available in a Safari Zone battle. Similarly, def pbCommandMenu in the script section PokeBattle_BugContest decides on the commands available in a Bug Catching Contest battle.

Each unique command is assigned its own value, which is used to decide which button graphic to use for it.

You cannot run from trainer battles. However, if you are playing in Debug mode and you hold the Ctrl button when you select "Run", you will be able to do so. You can choose whether to treat the battle as a win or a loss for the player.

Fight menu

The fight menu's code is in class FightMenuDisplay in the script section PokeBattle_SceneMenus. The control of the cursor is done in def pbFightMenu in the script section Scene_Commands.

If the Pokémon you are currently choosing a command for is able to Mega Evolve, an extra icon will appear to indicate this. Rather than clicking on it, however, you will need to press the key indicated to register that you want the Pokémon to Mega Evolve. In Debug mode, holding the Ctrl button when opening the fight menu will bypass certain checks of whether the Pokémon can Mega Evolve, and make the Mega Evolve option appear despite any artificial restrictions (if Mega Evolution is literally impossible, such as the Pokémon not holding the appropriate item or not having a Mega Evolved form, you still won't get the Mega Evolve option).

If the Pokémon you are currently choosing a command for is able to swap its position with the Pokémon next to it (i.e. in a battle larger than 2v2 and you control both Pokémon involved), an extra icon will appear to indicate this. Rather than clicking on it, however, you will need to press the key indicated to choose that action. Shifting is done instead of using a move.

Targeting menu

The targeting menu's code is in class TargetMenuDisplay in the script section PokeBattle_SceneMenus. The control of the cursor is done in def pbChooseTarget in the script section Scene_Commands.

Data box

A data box is a panel floating on the screen which contains information about one of the active Pokémon. In a single battle, there will be two of them; in a double battle, there can be up to four, and so on.

The appearance of a data box is defined in class PokemonDataBox in the script section PokeBattle_SceneElements. There is a separate class in the script section PokeBattle_SafariZone for the data box used for the player in Safari Zone battles.

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