Defining a trainer

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 "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.
2	Internal name	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. The internal name is never seen by the player.
3	Display name	The name of the trainer type, as seen by the player. Multiple trainer types can have the same display name, although they cannot share ID numbers or internal names.
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 name of a background music (BGM) file in the folder "Audio/BGM" (excluding its file extension). The music that plays during battles against trainers of this type. Typically only defined for Gym Leaders, Elite Four members and rivals. Optional. If undefined, the default BGM is used.
6	Victory ME	The name of a music effect (ME) file in the folder "Audio/ME" (excluding its file extension). The victory music that plays upon defeat of trainers of this type. Optional. If undefined, the default victory ME is used.
7	Intro ME	The name of a music effect (ME) file in the folder "Audio/ME" (excluding its file extension). The music that plays before the battle begins, while still talking to the trainer. 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:
  • trcharXXX.png - The trainer type's overworld charset. "XXX" is either the internal name of the trainer type or its ID number padded to 3 digits (e.g. "trchar018.png" is for the Hiker trainer type).
• In the "Graphics/Trainers" folder:
  • trainerXXX.png - The trainer type's battle sprite. "XXX" is as above.
  • trbackXXX.png - The trainer type's back sprite, used in battle. "XXX" is as above.

Only certain trainer types will also 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 contained within 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 contained within square brackets, has the trainer type's internal name for that trainer, 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 go at the top). 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: The internal name of the trainer type. This trainer's name. 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 internal names 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: The internal name of a Pokémon species. 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. The available properties are as follows:

Property	Description
Item	The internal name of this Pokémon's held item. Default is no held item.
Moves	The internal names 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" through "5" (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). 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 internal name 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 IV numbers are written in the order: 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 EV numbers are written in the order: 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.
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 PokeBall_CatchEffects. 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.