Battles

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

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 two main scripts you can use to make different kinds of battles happen. These are:

```
WildBattle.start(:PIKACHU, 42)
WildBattle.start(:PIKACHU, 42, :IVYSAUR, 17)
WildBattle.start(:PIKACHU, 42, :IVYSAUR, 17, :GEODUDE, 25)
TrainerBattle.start(:YOUNGSTER, "Ben")
TrainerBattle.start(:YOUNGSTER, "Ben", :LASS, "Alice")
TrainerBattle.start(:YOUNGSTER, "Ben", :LASS, "Alice", :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 include changing the size of the battle (e.g. double instead of single), preventing escape from a wild Pokémon, or 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:

These rules are all defined at the top of the script section **Overworld\_BattleStarting**, and are applied a little further down in `def prepare_battle`. 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 **Overworld\_BattleIntroAnim**.

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 `SpecialBattleIntroAnimations.register` which will override the regular battle transition if it meets some condition. There are several examples of these overrides, namely ones to be used when battling certain trainer types. Each registered override has a priority value, and ones with higher values try to trigger first. 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 **Overworld\_BattleStarting**. The possible environments are defined in the script section **Environment**.

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 main elements of the battle screen are in the script sections **Battle\_Scene\_Objects** and **Battle\_Scene\_Menus**. They are all set up at the start of battle by `def pbInitSprites` in the script section **Scene\_Initialize**.

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 Battle::Scene::CommandMenu` in the script section **Battle\_Scene\_Menus**. The control of the cursor is done in `def pbCommandMenuEx` in the script section **Scene\_ChooseCommands**.

If an elemental type with an ID 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\_ChooseCommands**.

There is also `def pbSafariCommandMenu` in the script section **SafariBattle**, which decides on the commands available in a Safari Zone battle. Similarly, `def pbCommandMenu` in the script section **BugContestBattle** 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 the outcome of the battle when you do so.

### Fight menu

The fight menu's code is in `class Battle::Scene::FightMenu` in the script section **Battle\_Scene\_Menus**. The control of the cursor is done in `def pbFightMenu` in the script section **Scene\_ChooseCommands**.

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 Battle::Scene::TargetMenu` in the script section **Battle\_Scene\_Menus**. The control of the cursor is done in `def pbChooseTarget` in the script section **Scene\_ChooseCommands**.

### 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 Battle::Scene::PokemonDataBox` in the script section **Battle\_Scene\_Objects**. There is a separate class in the script section **SafariBattle** for the data box used for the player in Safari Zone battles.