Essentials Docs Wiki
For creating new Pokémon species, see Defining a species.
For information on how Mega Evolution works, see Mega Evolution.
For information on how shiny Pokémon behave, see Shiny Pokémon.

This page describes how Pokémon forms are defined and how they work. This includes proper alternate forms (e.g. Deoxys), and also gender differences (e.g. Meowstic).

What is a form?

A Pokémon form is a particular set of properties for a given species. Properties include base stats, types, possible abilities, height, Pokédex entry, battle sprite positioning, name of the form, and so on. This covers most of the properties that are defined in the PBS file "pokemon.txt".

A given species can have multiple forms, each of which have different sets of properties. They may differ in just one aspect (e.g. the only difference between the Unown forms are the names of those forms), or they may differ in many ways (e.g. Mega Evolutions can have differing stats/types/height/weight/abilities/etc.).

Different forms of a species tend to look different to each other. In other words, they have different sprites and icons. With the exceptions of cosmetic gender differences (see below) and shininess, if you want one Pokémon to look different to another Pokémon of the same species, it will need to be an alternate form of that species. It is explained below how these sprites and icons are named to allow them to represent different forms.

Every species has at least one form. The base form (also known as form 0) is defined in the PBS file "pokemon.txt", and alternate forms are defined in the PBS file "pokemonforms.txt". Each alternate form has its own number, usually starting at 1 and going upwards, although any positive whole number will suffice.

Cosmetic gender differences

A number of species look different depending on whether a Pokémon of those species is male or female. There are no other differences between them, and the differences are purely cosmetic. In this case, the two appearances do not need to be treated as separate forms; there is a special feature that allows cosmetic gender differences to exist without the use of forms.

If a species looks different depending on its gender and also has other differences (e.g. Meowstic has different hidden abilities and movesets), it will need to be split into two separate forms (the base form with a form name of "Male" and an alternate form with a form name of "Female"). The gender differences in this case are not purely cosmetic.

Defining an alternate form

A Pokémon's base form is defined in the PBS file "pokemon.txt", while its alternate forms are defined in the PBS file "pokemonforms.txt". Alternate forms will inherit the properties of the base form, except ones that are defined in "pokemonforms.txt" for that form. The PBS file "pokemonforms.txt" therefore only needs to list the differences between each form of a species compared to its base form.

With a few exceptions (see below), anything defined about a species in the PBS file "pokemon.txt" can be overridden for an alternate form of that species.

The PBS file "pokemonforms.txt" is laid out in nearly the same way as "pokemon.txt". It has a number of sections, each beginning with something in square brackets followed by any number of lines in the form XXX = YYY. The latter are exactly the same as in "pokemon.txt". Any line beginning with a # (including the lines separating one form from the next) are comment lines and are not compiled; they are just there to make things more legible and are not required.

The sections names (the text in square brackets) are comprised of two parts: a species internal name and a form number. They are separated by a comma, a hyphen or a space.

Here are some examples of form definitions:

FormName = Spiky-Eared
BattlerEnemyX = 3
Evolutions = PIKACHU,None,
FormName = Q
FormName = Rainy Form
Type1 = WATER
Color = Blue
Pokedex = This is the form Castform takes when soaked with rain. When its body is compressed, water will  seep out as if from a sponge.
BattlerEnemyX = 0
BattlerShadowSize = 2

Remember that form 0 is the base form that is defined in "pokemon.txt", so a form number of 0 cannot be used in "pokemonforms.txt".

Definable properties

Most properties that are defined in the PBS file "pokemon.txt" can also be defined for a form in "pokemonforms.txt". All of these properties are optional for a form. If a property is not defined for a form, that form will inherit the property from the base form in "pokemon.txt". See Defining a species for a more detailed description of each property.

The table below lists the properties that can be defined for a form:

Property Notes
If Type1 is defined, then this form will not inherit either type of the base form. Even if Type2 of this form is the same as Type2 of the base form, it will need to be defined for this form as well, because Type2 will not be inherited. If Type2 is not defined for this form, then this form will just have a single type (Type1).

If Type1 is not defined but Type2 is, then this form will inherit the Type1 of the base form. However, there is no harm in defining Type1 as well for this form, even if it will be the same as the base form's.

BaseStats All six stats must be defined if any are, even if some are the same as the base form's.
BaseEXP -
EffortPoints All six EV stats must be defined if any are, even if some are the same as the base form's.
Rareness -
Happiness -
If either of these properties is blank, it will inherit from the base form even if the other property is defined for this form.
Moves The entire moveset must be defined here if it is at all different to that of the base form's.
TutorMoves The entire set of TM/tutor moves must be defined here if it is at all different to that of the base form's.
EggMoves The entire set of egg moves must be defined here if it is at all different to that of the base form's.

Species with different egg moves depending on their form should not be able to change their form at all. The breeding code does not support that.

Compatibility Generally used to put a certain form in the Undiscovered egg group, i.e. making that form unable to breed.
StepsToHatch -
Height -
Weight -
Color -
Shape -
Habitat -
Kind -
Pokedex -
FormName If this is blank, then this form will not appear in the Pokédex.

If you have a species which has gender differences in an alternate form, you should define them as two separate forms instead. Only one version of each alternate form will appear in the Pokédex.

Generation -
All three of these properties must be defined if any are different to the base form's. If one of these properties is left blank, it will not inherit from the base form, but will instead be treated as empty.
Evolutions These may change how a Pokémon evolves (e.g. Alolan Vulpix using an Ice Stone rather than a Fire Stone), change what it evolves into (e.g. Galarian Yamask evolving into Runerigus rather than Cofagrigus), or remove evolution paths (e.g. Spiky-Eared Pichu cannot evolve, which means it evolves using the evolution method "None"; the species it mentions that it evolves into is irrelevant).

In addition to the above, there are also some properties exclusive to alternate forms which can also be defined. These properties are mostly relevant to Mega Evolution forms.

Property Description
MegaStone The internal name of an item which needs to be held to allow the holder to Mega Evolve into this form.

These items cannot be dropped or otherwise lost in battle if held by a Pokémon that can make use of them.

MegaMove The internal name of a move which needs to be known by a Pokémon to allow that Pokémon to Mega Evolve into this form. This typically only applies to Rayquaza (whose move is Dragon Ascent).
MegaMessage A number which indicates the message that is shown when a Pokémon is Mega Evolving into this form. The messages themselves are hardcoded in def pbMegaEvolve in the script section Battle_Action_Other. If undefined, this is 0. This typically only applies to Rayquaza (which uses message 1).
  • 0 = "{Pokémon}'s {Mega Stone} is reacting to {Player}'s {Mega Ring}!"
  • 1 = "{Player}'s fervent wish has reached {Pokémon}!"
UnmegaForm A Pokémon of this Mega Evolved form reverts to its unmega form at the end of battle. If undefined, this is 0.
PokedexForm Used instead of the "FormName" property. When a Pokémon of this form is being registered as seen in the Pokédex, the form number given by this property is what will be registered instead of this Pokémon's actual form. This only applies if this property is greater than 0. If undefined, this is 0.

This is used by duplicate forms which are needed to make other code work. For example, Zygarde has two "Complete Forme" forms defined, because it can turn into Complete Form from two other forms and needs to remember which of those forms (10% and 50%) it originally was. Having two Complete Formes is the most convenient way to remember this. One of those Complete Forms can be registered in the Pokédex, while the other one uses this property to point to the first Complete Form, ensuring that only one Complete Forme can be registered as seen no matter which of the two was actually seen (because they're both treated the same from the player's perspective).

Undefinable properties

The following properties cannot be defined for an alternate form, even though they can be defined in "pokemon.txt". The reasons for why they are disabled vary.

Property Why not?
Name The species name is for the species as a whole, not for individual forms.
InternalName The internal name is for the species as a whole, not for individual forms.
GenderRate There can be a clash between having a form-specific gender rate and forms which depend on the Pokémon's gender (e.g. Meowstic).
GrowthRate If a Pokémon's form changes, this property being form-specific will change the Pokémon's level (because the same number of Exp Points corresponds to different levels using different growth rates), which is not desirable.
Incense Difficulties ensuring that breeding will produce the correct offspring.

Defining move compatibilities

The PBS file "tm.txt" lists all the TM and Move Tutor compatibilities. Each form of a species must be listed in this file separately; the base form's compatibilities are not ever inherited.

Each alternate form is given its own internal name, which is the internal name of the species followed by an underscore followed by its form number. For example, PICHU_1, UNOWN_16, CASTFORM_2. These should be written in "tm.txt" alongside the species internal names.

Choosing the form to use

A Pokémon's form is the value of pkmn.form. If this value does not correspond to a defined alternate form, then the Pokémon will use the base form's properties instead. If there are no sprites/icons/cries for a form of this value, then the base form's sprites/icons/cries will be used instead. The Pokémon will still technically be an alternate form, albeit one that doesn't have any form-specific properties and/or sprites/icons/cries.

By default, a Pokémon will be form 0. For some species with alternate forms, each Pokémon can have a different form depending on various factors, such as location (Shellos), held item (Arceus), moves known (Keldeo) or just a random choice (Unown).

The script section FormHandlers contains code that makes the decision for each Pokémon of which form it should have. These are:

Proc Description
getForm Checked whenever the game looks at the Pokémon; this procedure determines which form it should be. The form can depend on anything, such as location, held item or time.

Used for species which can change their forms automatically depending on various external factors, such as what its held item is.

getFormOnCreation Checked when the Pokémon is first created, and determines which form it should be (at least initially). The form can depend on anything, such as location, the type of terrain nearby, or a random choice.

Used for species which cannot change forms, and which appear in the wild in multiple forms. Should not be used in conjunction with "getForm", because the latter will just immediately override whatever this proc calculates.

getFormOnEnteringBattle Checked when the Pokémon is sent into battle, and determines which form the Pokémon should be changed to. For example, Kyurem and Xerneas have charged-up appearances only while in battle, and wild Minior always appear in Meteor Form.
getFormOnLeavingBattle Checked when the Pokémon comes out of battle, both when it is switched out and at the end of the battle, and determines which form the Pokémon should be changed to. Numerous Pokémon have form changes that only apply while in battle and which should be reset upon leaving battle.
onSetForm This doesn't change the Pokémon's form.

Checked when the Pokémon's form has been changed (by one of the above procedures, or through Debug mode), and does further things. For example, Rotom tries to learn a form-specific moves when it adopts a new form, and Furfrou/Hoopa remember when their form was changed because they revert back to their base form after a certain amount of time.

There are also some procedures used solely for Mega Evolutions, which are not listed here.

Some species can change their forms, but only due to an outside influence (e.g. Deoxys changes when inspecting certain meteorites). These species do not need to use any of the procedures listed above.

Graphics and audio

Sprites and icons

Pokémon sprites are stored in the folder "Graphics/Battlers", and Pokémon icons are stored in the folder "Graphics/Icons".

Whenever a Pokémon's sprite or icon is displayed, one of a variety of methods are called that decides which file to use as that sprite/icon. These methods are in the script section PSystem_FileUtilities. These methods check several properties of the Pokémon they are finding a sprite/icon for, to make sure they return the most appropriate graphic.

The filenames for Pokémon sprites are constructed from one or more elements in the following order:

  • XXX - the internal name of the species, or its ID number padded to 3 digits (always present)
  • _female - if female (for cosmetic gender differences)
  • _1 - if an alternate form (the number is the form number)
  • _shadow - if a Shadow Pokémon

You do not need a file for every combination of the above elements. Essentials checks through each relevant permutation of elements in order until it finds the most appropriate one which exists as a file.

For example, the back sprite of a female shiny East Sea Gastrodon would be "GASTRODON_female_1" in the folder "Back shiny". However, Gastrodon does not have gender differences, so there would be no file with this name. Upon ignoring the gender, the new filename "GASTRODON_1" is generated. This matches a file that exists, so that file is used as the sprite.

There are plenty of examples in Essentials of how the sprites and icons are named. If you are unsure about file naming, look at those.


Pokémon cries are stored in the folder "Audio/SE/Cries". Their filenames include fewer elements than sprites/icons, but are still constructed in the same way:

  • XXX - the internal name of the species, or its ID number padded to 3 digits (always present)
  • "Cry" - this is text (always present)
  • _1 - if an alternate form (the number is the form number)

For example, Sky Forme Shaymin's cry has a filename of "492Cry_1".

Important note!

Files for the base form (0) should not have a form part of "_0" in them. Simply omit that element when naming the files. For example, Gastrodon would have front sprite files named "GASTRODON.png" and "GASTRODON_1.png" only (the default form West Sea and the alternate form East Sea respectively).