Essentials Docs Wiki
Advertisement
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

A simple NPC trainer event created with comments.

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:

Comment What it means Required?
Battle: Battle me now! What the trainer says before starting the battle. This comment becomes a simple text event command which says "Battle me now!".

Use "\m" to split the comment's message up into separate text messages.

There can be more than one of these comments, and each one after the first is the introduction text for a different rematch battle (in order). Also, if there is more than one "Battle" comment, then the player will be asked to register the trainer in the phone after defeating them. You should have the same number of these comments as you do versions of the trainer (including the original), even if they are all the same phrase.

Yes
Type: CAMPER The ID of the trainer's type. Yes
Name: Dave The trainer's name. Yes
BattleID: 1 If there are multiple versions of this trainer, then this number is the one used to distinguish one version from the others.

This should only be used for isolated battles against the same trainer (e.g. the rival who shows up in different places) or a trainer with the same name as another (e.g. Team Rocket Grunts). For regular trainers that stay in the same place that you can rebattle, don't use this comment and instead just rely on using multiple "Battle" comments.

If this doesn't exist, this value will be 0.

No
DoubleBattle: yes Makes this battle a double battle.

If this doesn't exist, the battle will be a single battle (but could be a double battle if this trainer has 2 or more Pokémon and the player has a partner trainer).

No
Continue: yes Makes the player able to continue the game (with their party fully healed) if they lose the battle against this trainer, rather than blacking out and returning to a Poké Center. If this trainer has been set up with rematches by using multiple "Battle" comments, this continue effect will apply to all of those battles. No
EndIfSwitch: 42 If the Game Switch with this number is ON, the battle is treated as already over. Typically used for trainers in a Pokémon Gym, which are deactivated after beating the Leader regardless of whether they have been battled themselves. No
VanishIfSwitch: 42 If the Game Switch with this number is ON, the game won't show the event at all. This only updates during a map transfer; it will still be visible until then. No
Backdrop: mystic Sets the battle background for this battle. For this example, the background images will have filenames of "mystic_bg.png", "mystic_base0.png", "mystic_base1.png" and "mystic_message.png". No
Outcome: 42 The outcome of this battle will be stored in the Game Variable with this number. If this is not given, the outcome will be stored in Game Variable 1 by default.

The outcome of a battle is one of the following values:

  • 0 - Undecided or aborted
  • 1 - Player won
  • 2 - Player lost
  • 3 - Player or wild Pokémon ran from battle, or player forfeited the match
  • 5 - Draw
No
EndBattle: I'll train even harder! What the trainer says when you talk to them again after defeating them.

Use "\m" to split the text into individual messages.

There can be more than one of these comments, and each one after the first gives the after-battle text for a different rematch battle (in order). You should have as many of these comments as you do "Battle" comments; if there are more of these, the excess messages won't be used, and if there are fewer of these, the last one will be repeated for later rematches.

If this doesn't exist, the message will be "..." instead.

No
RegSpeech: Here's my number. What the trainer says when the player is asked to register the trainer's phone number. Yes if there are multiple "Battle" comments

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

The old Vs. animation.

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:

Animation Description Requirement
"vs_trainer_animation" The animation played when battling a Gym Leader or the rival. Single trainer battle, and the existence of files named "hgss_vs_TRAINERTYPE.png" and "hgss_vsBar_TRAINERTYPE.png" in the "Graphics/Transitions" folder.
"vs_elite_four_animation" The animation played when battling an Elite Four member or the Champion.

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.

Single trainer battle, and the existence of files named "vsE4_TRAINERTYPE.png" and "vsE4Bar_TRAINERTYPE.png" in the "Graphics/Transitions" folder.
"vs_admin_animation" The animation played when battling a high-ranking (and named) member of Team Rocket. If there are two high-ranking members of Team Rocket in the same battle, this animation will only show one of them.

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.

Any trainer battle, and the existence of a file named "rocket_TRAINERTYPE.png" in the "Graphics/Transitions" folder.
"alternate_vs_trainer_animation" This is the old Vs. animation (shown in the image on the right).

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.

Single trainer battle, and the existence of files named "vsTrainer_TRAINERTYPE.png" and "vsBar_TRAINERTYPE.png" in the "Graphics/Transitions" folder.
"rocket_grunt_animation" The animation played when battling a Team Rocket Grunt. There may be a non-Grunt opponent in that battle as well (e.g. a Scientist). Any trainer battle, and at least one opposing trainer has a trainer type of TEAMROCKET_M or TEAMROCKET_F.

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

Advertisement