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:

pbTrainerBattle(:YOUNGSTER,"Ben",_I("Aww, I lost."))
pbDoubleTrainerBattle(:YOUNGSTER,"Ben",0,_I("Aww, I lost."),:LASS,"Alice",0,_I("I also lost!"))

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 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, the terrain tag of the tile being stood on, whether the player is surfing, and so on.

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. (Note that not all defined environments are accessible by default; you would need to add your own code to be able to use them.)

The environment is used to decide on the appearance of the battle's background. 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 various elements in the battle screen are listed in the script section PokeBattle_SceneConstants. Note that many of these positions are relative to each other; it is recommended that you leave them that way.

The bar at the bottom of the screen in battle can be in one of four 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), 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_Scene. There is more code in class CommandMenuButtons that displays the buttons. The control of the cursor is done in def pbCommandMenuEx.

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.

There is also def pbSafariCommandMenu, which decides on the commands available in a Safari Zone battle. Similarly, def pbCommandMenu in the script section PBattle_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_Scene. There is more code in class FightMenuButtons that displays the visual elements of the menu. The control of the cursor is done in def pbFightMenu.

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

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.

The appearance of a data box is defined in class PokemonDataBox in the script section PokeBattle_Scene. There is a separate class just above that code for the data box used in Safari Zone battles.

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