Essentials Docs Wiki
Advertisement
For the main page about trainers, see Trainers.

This page describes how to define a trainer. This includes both trainer types and individual trainers.

Defining a trainer type

Every trainer in the game, including the player, has a trainer type. The trainer type defines various pieces of information that are common to all trainers of that type - this includes their title (e.g. Bug Catcher, Hiker, Gym Leader), appearance (i.e. sprite), the amount of money gained from defeating them, and associated battle music.

A trainer type begins with its definition. This means that it is listed in the PBS file "trainer_types.txt", so that it can be recognised by the game as a trainer type.

In addition to this, a trainer type will require a number of graphics files depicting that trainer type in different ways. See below for more information.

PBS file "trainer_types.txt"

The PBS file "trainer_types.txt" lists all the defined trainer types in the game. Each section in this file is one separate trainer type, where a section begins with a line containing an ID in square brackets and ends when the next section begins. Each line in a section is one separate piece of information about that trainer type.

Aside from the ID line, every line in a section follows the format:

XXX = YYY

where XXX is a property and YYY is the value or values associated with it (the spaces are optional). For example:

[POKEMONTRAINER_Red]
Name = Pokémon Trainer
Gender = Male
BaseMoney = 60
#-------------------------------
[SISANDBRO]
Name = Sis and Bro
Gender = Unknown
BaseMoney = 16
SkillLevel = 48
#-------------------------------
[LEADER_Misty]
Name = Gym Leader
Gender = Female
BaseMoney = 100
BattleBGM = Battle Gym Leader
VictoryBGM = Battle victory leader

All pieces of information are optional, but will have default values if they are not defined. The order of the lines does not matter, except for the ID line in square brackets which must be first.

Data Description Default value
[ID] This is how the scripts refer to the trainer type. Each trainer type must have a different ID. Typically this is the same as the trainer type's name, but written in all capital letters and with no spaces or special characters. In the scripts, the ID is used as a symbol (i.e. with a colon in front of it, e.g. :SISANDBRO). The ID is never seen by the player.

This line must come first in a section, because, as mentioned above, this line defines when a new section begins.

n/a
Name The name of the trainer type, as seen by the player. Multiple trainer types can have the same name, although they cannot share an ID. "Unnamed"
Gender The gender of all trainers of this type. Is one of:
  • Male
  • Female
  • Unknown (e.g. if the type contains both a male and female trainer)
Unknown
BaseMoney The base amount of money earned from defeating a trainer of this type. The base money value is multiplied by the highest Level among all the trainer's Pokémon to produce the actual amount of money gained (assuming no other modifiers). Is 0 or a positive number. 30
SkillLevel The skill level of all trainers of this type, used for battle AI. Higher numbers represent higher skill levels. Is 0 or a positive number. By default, the highest value that makes a difference to the AI is 100. Same as BaseMoney
Flags Comma-separated labels applied to the trainer type which can be used to make it behave differently. There are no existing flags. none
IntroBGM The music that plays before the battle begins, while still talking to the trainer. The name of a background music (BGM) file in the folder "Audio/BGM" (excluding its file extension). none
BattleBGM The music that plays during battles against trainers of this type. Is the name of a background music (BGM) file in the folder "Audio/BGM" (excluding its file extension). Typically only defined for Gym Leaders, Elite Four members and rivals. none
VictoryBGM The victory music that plays upon defeat of trainers of this type. The name of a background music (BGM) file in the folder "Audio/BGM" (excluding its file extension). none

There is no difference between a trainer type used by many trainers (e.g. Bug Catcher), and a trainer type unique to just one NPC (e.g. Gym Leaders). They are all defined in exactly the same way.

It is important to note that the player also has a trainer type, and it is defined in exactly the same way as any other trainer type. Player characters are defined in the PBS file "metadata.txt" to have trainer types. They do not need to be the first trainer types defined in the PBS file "trainer_types.txt", although it may help developers to keep track of them if they are.

Trainer type graphics

Each trainer type must have the following graphics:

  • In the "Graphics/Characters" folder:
    • trainer_XXX.png - The trainer type's overworld charset. "XXX" is the trainer type's ID (e.g. "trainer_HIKER.png").
  • In the "Graphics/Trainers" folder:
    • XXX.png - The trainer type's battle sprite. "XXX" is the trainer type's ID (e.g. "HIKER.png").
    • XXX_back.png - The trainer type's back sprite, used in battle. "XXX" is the trainer type's ID (e.g. "HIKER_back.png").

The overworld charset only needs to follow the above naming convention if a trainer of that type can be registered in the Phone (it is shown in the Phone's screen), appears in a Battle Frontier facility as an opponent, or if using event comments to generate a trainer event. However, you might as well follow this convention for all trainer types.

Only certain trainer types will require back sprites. These include all trainer types which are used by player characters, as well as all trainer types of NPC trainers who team up with the player and fight alongside them (i.e. partner trainers).

The back sprite can either be a square picture (e.g. 128x128 pixels), or it can contain 5 such square pictures arranged horizontally (e.g. 640x128 pixels). If the latter, the first frame will be the regular back sprite and the next four frames will depict a throwing animation in order.

Defining an individual trainer

An individual trainer begins with its definition. This means that it is listed in the PBS file "trainers.txt", so that it can be recognised by the game as an individual trainer.

PBS file "trainers.txt"

The PBS file "trainers.txt" lists all the defined individual trainers in the game. Each section in this file is one separate individual trainer, where a section begins with a line surrounded by square brackets and ends when the next section begins. Each line in a section is one separate piece of information about that trainer or one of their Pokémon.

The section's "header", the line surrounded by square brackets, has a trainer type's ID, followed by a comma and then the name of the individual trainer. If the trainer requires a version number to differentiate it from other trainers with the same type/name (see below), that version number is also included here after another comma.

The rest of the lines in each section are written in the format XXX = YYY, where XXX is a property and YYY is the value or values associated with it (the spaces are optional).

Some lines may be indented, but this makes no difference and is just done to make things more legible. Any line beginning with a # (including the lines separating one trainer from the next) are comment lines and are not compiled; again, they are just there to make things more legible.

Here are some examples of defined trainers:

[CAMPER,Liam]
LoseText = A very good battle, indeed!
Pokemon = DIGLETT,10
Pokemon = BONSLY,11
#-------------------------------
[LEADER_Brock,Brock]
Items = FULLRESTORE,FULLRESTORE
LoseText = Very good.
Pokemon = GEODUDE,12
    Gender = male
    Moves = DEFENSECURL,HEADSMASH,ROCKPOLISH,ROCKTHROW
    AbilityIndex = 0
    IV = 20,20,20,20,20,20
Pokemon = ONIX,14
    Name = Rocky
    Gender = male
    Shiny = yes
    Moves = HEADSMASH,ROCKTHROW,RAGE,ROCKTOMB
    AbilityIndex = 0
    Item = SITRUSBERRY
    IV = 20,20,20,20,20,20
    Ball = HEAVYBALL
#-------------------------------
[TEAMROCKET_M,Grunt,1]
LoseText = You're too good for me!
Pokemon = WEEPINBELL,21
    Shadow = yes

The order in which these properties are written matters to some extent. Some properties relate to the trainer themselves and must be written before the first Pokémon line for that trainer. Other properties relate to an individual Pokémon owned by the trainer, and relate to the most recently defined Pokémon written above those properties.

The properties relating to the trainer are:

Property Description
[TRAINERTYPE,Name]
[TRAINERTYPE,Name,number]
This is the section "header", written in square brackets (rather than in the format XXX = YYY). There are either two or three parts to this line, separated by commas:
  1. The ID of the trainer type.
  2. This trainer's name.
  3. Optional. A version number to distinguish this trainer from other trainers with the same trainer type and name, when a battle against them is called. Default is 0.

Version numbers are useful for rematches, where they represent different versions of the same trainer changing over time. They are also useful for creating groups of "Grunts" (multiple separate trainers with the same name and appearance, e.g. "Team Rocket Grunt", where "Team Rocket" is the trainer type and "Grunt" is the name). Note that there are rules placed on how you use version numbers for rematch trainers.

Items Optional. The IDs of one or more items that this trainer is able to use in battle, separated by commas. If the trainer is able to Mega Evolve, a Mega Ring item should be listed here.
LoseText The in-battle text that appears when this trainer is defeated.
Pokemon There are two parts to this line, which are separated by a comma:
  1. The ID of a Pokémon species.
  2. A level number.

A trainer can have multiple Pokémon - simply have multiple "Pokemon = YYY" lines.

The properties which are specific to a single Pokémon are typically indented to make it easier to see which Pokémon they apply to (the most recently defined one). Indentation is not necessary, though. They can be written in any order within the space after the "Pokemon = YYY" line they apply to.

All of the properties below are optional. The available properties are as follows:

Property Description
Name This Pokémon's nickname. Up to 10 characters long. Default is no nickname.
Form This Pokémon's form number. Default is 0.
Gender Either "male" or "female". Default is the same as the trainer's gender, as defined in the PBS file "trainer_types.txt" for their trainer type (male if unknown). If this Pokémon cannot legitimately be the gender set here, it will instead be the gender (or genderless) it can be.
Shiny Is "yes" if this Pokémon is shiny. Default is "no" (which means it definitely won't be shiny).
SuperShiny Is "yes" if this Pokémon is super shiny. Super shininess takes priority over regular shininess. Default is "no" (which means it definitely won't be super shiny).
Shadow Is "yes" if this Pokémon is a Shadow Pokémon. Default is "no" (which means it definitely won't be a Shadow Pokémon).
Moves The IDs of this Pokémon's moves, separated by commas.

If at least one move is defined here, then this Pokémon's moveset will consist solely of those move(s), with gaps for undefined move slots. If no moves are defined, then this Pokémon's moveset will be the same as that of a wild Pokémon of the same species/level/form.

Ability The ID of the ability this Pokémon has. Default is undefined, meaning the "AbilityIndex" property will be used to determine the Pokémon's ability. This can give the Pokémon any ability at all, but it will be lost if the Pokémon changes form or species, and the Pokémon will then determine its ability using the usual calculations instead.
AbilityIndex Either "0" (first natural ability), "1" (second natural ability), or "2"+ (hidden abilities). Default is 0.

Unlike the "Ability" property, "AbilityIndex" will not be lost if the Pokémon changes form or species.

Item The ID of this Pokémon's held item. Default is no held item.
Nature The ID of this Pokémon's nature. If undefined, the nature depends on this Pokémon's species and the trainer's type (both of which are consistent no matter how many times you battle the trainer, meaning this Pokémon's nature cannot randomly change between battles).
IV This Pokémon's IV value(s). Is one to six numbers, each of which is between 0 and 31, which are separated by commas. Default is this Pokémon's level divided by 2 (rounded down), up to a maximum of 31 (i.e. the maximum number of IVs a stat can have).

The order of these numbers corresponds to the pbs_order of the main stats. By default, the order is: HP, Attack, Defense, Speed, Special Attack, Special Defense. If there is no number for a stat, it will use the first number given here (HP's value).

EV This Pokémon's EV value(s). Is one to six numbers, each of which is between 0 and 252, which are separated by commas. Default is this Pokémon's level multiplied by 1.5 (rounded down), up to a maximum of 85 (510/6, i.e. the maximum number of EVs a Pokémon can have, divided equally between its six stats).

The order of these numbers corresponds to the pbs_order of the main stats. By default, the order is: HP, Attack, Defense, Speed, Special Attack, Special Defense. If there is no number for a stat, it will use the first number given here (HP's value).

Happiness This Pokémon's happiness. Is a value between 0 and 255. Default is 70.
Ball The ID of the Poké Ball item this Pokémon is kept in. Default is a regular Poké Ball.
Advertisement