Trainers

*For how to create trainer data, see Defining a trainer.*
This page describes how to **set up trainer events in the game**.

## Setting up a trainer event

An NPC trainer is an event with certain event commands that cause a battle to occur against that trainer. While it is possible to construct a trainer event manually, Essentials is able to generate a basic trainer event from just a few comments written in that event, which are designed to be easier to create and edit.

Turning comments into a trainer event occurs when compiling the game, and this process erases anything else in the event at that time. Note that, after you compile your game, you will need to close and restart RPG Maker XP to see the changes in the events.

By default, these comments are also erased by the Compiler when the event is rewritten. If you want to keep the comments, look in `def convert_to_trainer_event` for the line `rewriteComments = false` and change it to `true` instead. Be aware that any event with these comments in it will be rewritten when compiling the game, undoing any changes you might make to the proper event commands.

The available comments are as follows:

## Trainer behaviour

Since all NPC trainers are events, they can be manipulated in many of the ways that other events can be. They can be made to randomly turn on the spot, or roam around, or walk in a specific pattern. They can be made to only battle the player during a certain time of day (e.g. police officers at night), or after a certain point in the game, or to walk off after the battle is over. There are a wide range of possibilities, and all of them can be achieved through event manipulation (this is all standard RPG Maker functionality and will not be explained here).

An NPC trainer is typically able to see a number of tiles in front of itself, and when the player enters that range, the NPC will stop them and approach and start a battle. To make an event do this, put the phrase "Trainer(X)" in its name, where "X" is the number of tiles the trainer can "see" in front of it. You will also need to set the event to trigger on Event Touch.

## Structure of trainer events

A basic trainer event has two pages to it, as described below. More complex trainer events can be created, by using more of the comments listed above or by editing the trainer event yourself (remember to delete the special comments described above if you want to edit the event manually).

### Page 1

The first page contains something like the following:

```
@>Script: pbTrainerIntro(:CAMPER)
@>Script: pbNoticePlayer(get_self)
@>Text: Battle me now!
@>Conditional Branch: Script: TrainerBattle.start(:CAMPER, "Dave")
  @>Control Self Switch: A =ON
  @>
 : Branch End
@>Script: pbTrainerEnd

```

`pbTrainerIntro` will play the intro BGM specific to the trainer type given. If that trainer type doesn't have an intro BGM specific to itself, it won't play anything. It also freezes all events on the map, so that nothing interrupts the battle (e.g. a free-roaming trainer happening to come across the player).

`pbNoticePlayer` is the script used to make the player turn to face the trainer, and make the trainer exclaim and walk up to the player. Noticing the player from a distance in the first place (and thus starting this event up) is due to the event having "Trainer(X)" in its name as described above. Note that this script can be used for non-trainer NPCs as well; it itself has nothing to do with battling (it is just commonly associated with them).

If you intend to use move routes after the battle concludes (e.g. to have a trainer who is blocking a doorway move aside after being beaten), you must refresh their position manually by using the script:

```
@>Script: $PokemonMap.addMovedEvent(get_self)

```

Otherwise if the game is saved and reloaded without first leaving the map, the NPC trainer will return to the position they were in after they moved towards the player because of `pbNoticePlayer`, which could potentially lead to unintentional blocking of paths.

The battle itself is caused by a line of code within a Conditional Branch. If the battle is won, then the contents of the Conditional Branch will be carried out (this could be a few more text messages, awarding a Gym Badge if the trainer was a Gym Leader, etc.). The Conditional Branch *must* contain a command to set the event's Self Switch A to ON, so that when the trainer is interacted with again after beating them, the battle will not occur again.

`TrainerBattle.start` takes any number of combinations of arguments, where each combination describes a single trainer. The possible combinations are:

* Trainer type, trainer name.
* Trainer type, trainer name, version number.
* An `NPCTrainer` object.

For example:

```
TrainerBattle.start(:CAMPER, "Dave")
TrainerBattle.start(:HIKER, "Ford", 42)
TrainerBattle.start(:CAMPER, "Dave", :HIKER, "Ford", 42)
TrainerBattle.start(:HIKER, "Ford", 42, :CAMPER, "Dave")
trainer = GameData::Trainer.get(:HIKER, "Ford", 42).to_trainer
trainer.items.push(:FULLRESTORE)
TrainerBattle.start(trainer)
TrainerBattle.start(trainer, :CAMPER, "Dave")

```

Finally, `pbTrainerEnd` unfreezes all events on the map.

### Page 2

The second page of the trainer event requires Self Switch A to be ON, and simply contains a text message, saying whatever the trainer will say when interacted with again after they have been defeated.

## Double battles

You can have double battles against any of the following:

* One trainer.
* Two NPCs treated as a single trainer (which has a trainer type that depicts two people, e.g. "Sis and Bro").
* Two separate trainers who are partnered.
* Two unrelated trainers that just happen to spot you at the same time.

Note that the second and third types are different to each other: the second is set up as a single trainer, while the third is two separate trainers but who are always battled together.

The third and fourth types are also different to each other: the third is always a double battle regardless of which NPC is spoken to, but with the fourth you could potentially battle each of the two trainers separately.

### Against one trainer, or two NPCs treated as a single trainer

These are both single trainers, except that the "two NPCs" version has a trainer type that depicts two NPCs.

Before starting the battle, you must check that the player is able to participate in a double battle (either by having 2+ able Pokémon in their party, or by having a partner trainer). This check is done in the trainer event before starting the battle, as a Conditional Branch which looks like:

```
@>Conditional Branch: Script: !pbCanDoubleBattle?
  @>Text: You don't have at least 2 usable Pokémon!
  @>Exit Event Processing
  @>
 : Branch End

```

Note that the event must exit event processing at the end of this Conditional Branch, which means that anything below that line will not be carried out.

To have a double battle against a single trainer or paired trainers, include the "DoubleBattle" comment in the trainer event. This adds a Script command to the event that sets the appropriate battle rule.

For the "two NPCs" version of this kind of double battle, there will be two NPC events standing next to each other, and you will have spoken to one of them to start the battle. It is possible to then talk to the other NPC, which could also start the same battle again; to prevent this, you will need to set the other event's Self Switch A to ON at the same time you set the interacted event's Self Switch A. To do this, include the code `pbSetSelfSwitch(*event*, *switch*, *state*)` in the event, where "event" is the ID number of the other NPC event, "switch" is the Self Switch's letter you wish to set (in quote marks, usually "A"), and "state" is TRUE or FALSE, e.g.

```
@Script: pbSetSelfSwitch(42, "A", true)

```

Each of the two NPC events should be identical, except for this additional line which will reference the other event's ID number.

### Against two separate partnered trainers

These are two separate trainers who always battle together. For fairness, each of these two trainers should have three or fewer Pokémon (but this isn't mandatory).

Before starting the battle, you must check that the player is able to participate in a double battle (either by having 2+ able Pokémon in their party, or by having a partner trainer). This check is done in the trainer event before starting the battle, as a Conditional Branch which looks like:

```
@>Conditional Branch: Script: !pbCanDoubleBattle?
  @>Text: You don't have at least 2 usable Pokémon!
  @>Exit Event Processing
  @>
 : Branch End

```

Note that the event must exit event processing at the end of this Conditional Branch, which means that anything below that line will not be carried out.

As described above, `TrainerBattle.start` can accept any number of trainers to battle against. You will simply need to include the appropriate arguments for both trainers to be battled against here.

For example:

```
@>Conditional Branch: Script: TrainerBattle.start(:CAMPER, "Dave", :HIKER, "Zaphod", 42)
  @>Control Self Switch: A =ON
  @>
 : Branch End

```

There will be two NPC events standing next to each other, and you will have spoken to one of them to start the battle. It is possible to then talk to the other NPC, which could also start the same battle again; to prevent this, you will need to set the other event's Self Switch A to ON at the same time you set the interacted event's Self Switch A. To do this, include the code `pbSetSelfSwitch(*event*, *switch*, *state*)` in the event, where "event" is the ID number of the other NPC event, "switch" is the Self Switch's letter you wish to set (in quote marks, usually "A"), and "state" is TRUE or FALSE, e.g.

```
@Script: pbSetSelfSwitch(42, "A", true)

```

Each of the two NPC events should be identical, except for this additional line which will reference the other event's ID number.

### Against two unrelated trainers

This is when two completely unrelated trainers just happen to spot the player walking in front of them at the same time. Each of these trainers can be battled separately, and will be regular single battles in that case. The total number of Pokémon between them should be 6 or fewer, for fairness.

In turn, each of the two trainers will approach the player and talk to them. The order they do this in depends on the IDs of those events (e.g. event 16 will move before event 17). Then a double battle against both separate trainers will occur (if the player is able to participate in a double battle).

If the player only has 1 usable Pokémon and no partner trainer, then the two trainers will be battled one at a time, with the second not approaching the player until the first has been defeated.

In the unlikely event that three trainers happen to spot the player at the same time, the first will be a single battle, and then the other two will be a double battle together (if possible). For example, if the events of these trainers are numbered 7, 8 and 9, then 7 will be a single battle, followed by 8 and 9 pairing up in a double battle.

## Animation when entering battle

A transition is a way of making the screen turn black, in order to start a battle. There are a number of transitions in Essentials, which are designed like the ones from Pokémon HGSS and used in the same way.

In addition to the generic transition animations, there are a number of transition animations for particular NPCs. These are all triggered by code in the script section **Overworld\_BattleIntroAnim**, although the code for the animations themselves is (usually) in the script section **Transitions**. These animations are:

 "vs\_elite\_four\_animation"
This animation also shows the player, so in the folder "Graphics/Transitions" there will need to be a graphic named "vsE4\_TRAINERTYPE.png" for the player's trainer type. For a particular player outfit, the graphic's name will be "vsE4\_TRAINERTYPE\_2.png", where "2" is the outfit number.
 "vs\_admin\_animation"
This animation takes priority over "rocket\_grunt\_animation", so if the battle is against both a Team Rocket Admin and a Team Rocket Grunt, this animation will be shown.
 "alternate\_vs\_trainer\_animation"
This animation also shows the player, so in the folder "Graphics/Transitions" there will need to be graphics named "vsTrainer\_TRAINERTYPE.png" and "vsBar\_TRAINERTYPE.png" for the player's trainer type. For a particular outfit, the graphicss names will be "vsTrainer\_TRAINERTYPE\_2.png" and "vsBar\_TRAINERTYPE\_2.png", where "2" is the outfit number.
 "rocket\_grunt\_animation"

In all of these cases, "TRAINERTYPE" is the ID of the trainer type of the trainer being battled.