Defining a trainer

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 "trainertypes.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 "trainertypes.txt"

The PBS file "trainertypes.txt" lists all the defined trainer types in the game. Each line in this file is one separate trainer type.

Every line in this file follows the same format. Firstly, here are some examples:

1,POKEMONTRAINER_Leaf,Pokémon Trainer,60,,,,Female,,
7,BEAUTY,Beauty,56,,,,Female,,
18,HIKER,Hiker,32,,,,Male,,
51,COOLCOUPLE,Cool Couple,72,,,,Mixed,48,
59,LEADER_Brock,Gym Leader,100,gymleader,,,Male,,
71,CHAMPION,Champion,100,elite,,,Male,,

Each line is structured as follows, with commas separating each part:

Part Information Description
1 ID number This number must be different for each trainer type. It must be a whole number greater than 0. You can skip numbers (e.g. the sequence 23,24,25,197,198,199,... is allowed). The order in which trainer types are numbered is not important.

ID numbers are obsolete and not used for anything.

2 ID This must be different for each trainer type. This is how the scripts refer to the trainer type. Typically this is the same as the trainer type's name, but written in all capital letters and with no spaces or symbols. In the scripts, the ID is used as a symbol (i.e. with a colon in front of it, e.g. :HIKER). The ID is never seen by the player.
3 Name The name of the trainer type, as seen by the player. Multiple trainer types can have the same name, although they cannot share ID numbers or IDs.
4 Base money The 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). Must be a number greater than or equal to 0.

Optional. If undefined, the default is 30.

5 Battle BGM 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.

Optional. If undefined, the default BGM is used.

6 Victory ME The victory music that plays upon defeat of trainers of this type. The name of a music effect (ME) file in the folder "Audio/ME" (excluding its file extension).

Optional. If undefined, the default victory ME is used.

7 Intro ME The music that plays before the battle begins, while still talking to the trainer. The name of a music effect (ME) file in the folder "Audio/ME" (excluding its file extension).

Optional. If undefined, the default ME is used.

8 Gender The gender of all trainers of this type. Is one of:
  • Male
  • Female
  • Mixed (i.e. if the type shows a pair of trainers)

Optional. If undefined, the default is "Mixed".

9 Skill level The skill level of all trainers of this type, used for battle AI. Higher numbers represent higher skill levels. Must be a number greater than or equal to 0.

Optional. If undefined, the default is equal to the base money value.

10 Skill codes A text field which can be used to modify the AI behaviour of all trainers of this type. No such modifiers are defined by default, and there is no standard format. See the page Battle AI for more details.

Optional. If undefined, the default is blank.

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 "trainertypes.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 either the ID of the trainer type (e.g. "trainer_HIKER.png") or its ID number padded to 3 digits (e.g. "trainer_018.png").
  • In the "Graphics/Trainers" folder:
    • XXX.png - The trainer type's battle sprite. "XXX" is the ID of the trainer type (e.g. "HIKER.png").
    • XXX_back.png - The trainer type's back sprite, used in battle. "XXX" is the ID of the trainer type (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.

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
    Ability = 0
    IV = 20
Pokemon = ONIX,14
    Name = Rocky
    Gender = male
    Shiny = yes
    Moves = HEADSMASH,ROCKTHROW,RAGE,ROCKTOMB
    Ability = 0
    Item = SITRUSBERRY
    IV = 20
    Ball = 19
#-------------------------------
[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 can be written anywhere within the section (although traditionally they appear first). 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
Trainer type, trainer's name[, version 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.
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
Item The ID of this Pokémon's held item. Default is no held item.
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 for a wild Pokémon of the same species/level/form.

Ability Either "0" (first natural ability), "1" (second natural ability), or "2"+ (hidden abilities). Default is 0.
Gender Either "male" or "female". Default is the same as the trainer's gender, as defined in the PBS file "trainertypes.txt" for their trainer type (male if uncertain/mixed). If this Pokémon cannot legitimately be the gender set here, it will instead be the gender (or genderless) it can be.
Form This Pokémon's form number. Default is 0.
Shiny Is "yes" if this Pokémon is shiny. Default is "no" (which means it definitely won't be shiny).
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 order that main stats are defined. 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 (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 order that main stats are defined. 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 (HP's value).

Happiness This Pokémon's happiness. Is a value between 0 and 255. Default is 70.
Name This Pokémon's nickname. Up to 10 characters long. Default is no nickname.
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).
Ball A number referring to the type of Poké Ball this Pokémon is kept in. These numbers are written in the $BallTypes hash at the top of the script section BallHandlers_PokeBallEffects. Default is 0, which is a regular Poké Ball.

Note that both the number of lines per section (i.e. per trainer), and the number of lines describing individual Pokémon, will vary from trainer to trainer.

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