Essentials Docs Wiki
For how to define a Pokémon species, see Defining a species.
For how to change a property of an individual Pokémon, see Editing a Pokémon.
For adding, removing, counting and choosing Pokémon in the party, see Manipulating Pokémon.
For Pokémon before they're hatched, see Eggs.

This page describes how Pokémon work in-game. This includes the properties an individual Pokémon has, along with other general information about them.

A Pokémon's attributes

Each individual Pokémon in the game has a number of attributes. Together, these attributes define that specific Pokémon.

The term "pkmn" in the examples below should be replaced with the Pokémon to be modified (e.g. $[0] is the first Pokémon in the player's party) - see Manipulating Pokémon for ways to refer to individual Pokémon.

Attribute Description
species The Pokemon's species.
name The Pokemon's nickname, which is the Pokémon's species name if it doesn't have a custom nickname.
level The Pokémon's current level. Depends on the attribute "exp".
exp The Pokémon's Experience Points. The attribute "level" depends on this.
types An array containing the Pokemon's type(s). Depends on the types as defined for the Pokémon's species in the PBS file "pokemon.txt" or "pokemon_forms.txt".

The array will only have one type in it if the Pokémon only has one type.

ability The GameData::Ability object of the Pokemon's ability. ability_id returns the ID of that ability. Depends on the attribute "ability_index" if defined, or the attribute "personalID" if not.
ability_index If defined, forces the Pokémon's ability to be the first natural (0), second natural (1) or hidden (2+) ability available to its species. It is not possible to give the Pokémon any ability other than those defined in the PBS file "pokemon.txt" for its species (or "pokemon_forms.txt" for its species and form).
gender The Pokémon's gender. Is either 0 (male), 1 (female) or 2 (genderless). Depends on the attribute "personalID", but can be set to a specific value with pkmn.makeMale or pkmn.makeFemale. It cannot be set to a gender that the Pokémon cannot have.
nature The GameData::Ability object of the Pokémon's nature. nature_id returns the ID of that nature. Depends on the attribute "personalID", but can be set to a specific nature ID.
Whether the Pokémon is shiny, and whether the Pokémon is super shiny. Depends on the attribute "personalID" but can each be set to a specific value with pkmn.shiny = true/false and pkmn.super_shiny = true/false.
form The Pokémon's form. 0 is the default form, and Pokémon with form 0 are as defined in the PBS file "pokemon.txt". See Forms for more information.
hp The Pokémon's current HP.
In order:
  • The current maximum HP amount the Pokémon can have
  • The Pokémon's Attack stat
  • The Pokémon's Defense stat
  • The Pokémon's Special Attack stat
  • The Pokémon's Special Defense stat
  • The Pokémon's Speed stat

All of these are calculated depending on the Pokémon's species, level, IVs, EVs and nature.

happiness The Pokémon's happiness. Is a number between 0 and 255 inclusive.
status The Pokémon's status. One of:
  • :NONE (healthy)
  • :SLEEP
  • :BURN
statusCount Is 0, except if the Pokémon is:
  • Asleep - Is the number of rounds the Pokémon will remain asleep. This number is set when the Pokémon is made to fall asleep.
  • Badly poisoned - If the Pokémon is poisoned and this is "1", the Pokémon is badly poisoned instead (which affects how much poison damage it takes in battle). When the Pokémon leaves battle while badly poisoned, this value is set to 0 and it becomes regular poisoned (even in later battles).
steps_to_hatch Used for Pokémon eggs. Is the number of steps until the egg hatches. If it is 0, it is a Pokémon. The code pkmn.egg? will return whether pkmn is an egg (it is an egg if "steps_to_hatch" is a positive number).

This is the only way in which eggs are different to Pokémon.

moves An array of moves known by the Pokémon. Each move has the following attributes:
  • id - The ID of the move, e.g. :TACKLE.
  • pp - The remaining PP of the move.
  • ppup - The number of boosts to the maximum PP this move has had. One boost will add 20% of the original maximum PP, and item effects limit the maximum number of allowed boosts to 3 (there is no inherent limit on the number of boosts allowed).
  • total_pp - The maximum PP of this move. Is calculated from data in the PBS file "moves.txt" and the "ppup" attribute.

All other attributes of the move are drawn directly from data compiled from the PBS file "moves.txt".

poke_ball The ID of the Poké Ball item that the Pokémon is in (default is :POKEBALL).
item The GameData::Ability object of the Pokemon's held item (or nil if there is no held item). item_id returns the ID of that item.
mail If the Pokémon's item is not a mail item, this attribute is nil. If it is a mail item, then this attribute is a Mail object which has several attributes:
  • item - Is the ID of the Pokémon's held mail item. This determines the mail's background image.
  • message - The mail's message.
  • sender - The name of the mail's sender.
  • poke1, poke2, poke3 - Each is an array containing species/form/gender/etc. information about a Pokémon whose icon will appear on the mail. The numbers determine the order in which they are shown.
ev A hash of the Effort Values this Pokémon has. It has values for each of the following keys:
  1. :HP
  2. :ATTACK
  6. :SPEED

These can each be between 0 and EV_STAT_LIMIT (252) inclusive. They are all 0 when the Pokémon is created.

iv A hash of the Individual Values this Pokémon has. It has values for each of the following keys:
  1. :HP
  2. :ATTACK
  6. :SPEED

These can each be between 0 and IV_STAT_LIMIT (31) inclusive. They are set randomly when the Pokémon is created.

pokerus Is a number between 0 and 255 which describes the Pokérus infection state of this Pokémon. It contains both the strain of the virus and the remaining infection time in days. As a rough explanation:
  • 0 - The Pokémon does not have Pokérus, and has never had it.
  • >15, has a remainder when divided by 16 - The Pokémon has Pokérus and is infectious. The remainder is the number of days remaining for it to be infectious.
  • >15, has no remainder when divided by 16 - The Pokémon has had Pokérus in the past, and is no longer infectious.
fused Another Pokémon which has been fused with this Pokémon (or nil if there is none). It is a Pokémon itself. Currently only used by Kyurem, Necrozma and Calyrex to record the Pokémon they have fused with.
The Pokémon's contest stats.

They currently do nothing in Essentials (except for "beauty" which is involved in the evolution method "Feebas", although there is no existing way to change its value).

markings An array of the Pokémon's markings. See the page Editing a Pokémon for a more detailed description of its contents.
ribbons An array of the Pokémon's ribbons. Each element of the array is the ID of a ribbon that the Pokémon has.
personalID The Pokémon's personal ID number. A 32-bit number (i.e. a number between 0 and 4,294,967,295), which is randomly generated when the Pokémon is created. The last two octets of the binary version of the ID number (a number between 0 and 65535) is displayed in a Pokémon summary screen, and is given by pkmn.publicID.

Determines the Pokémon's gender, ability, nature and shininess. It also determines where Spinda's spots are, and is used in the evolution methods "Silcoon" and "Cascoon".

owner An instance of Pokemon::Owner, which contains information about the Pokémon's original trainer:
  • - The trainer's full ID number (a 32-bit number). The last two octets of the binary version of the ID number (a number between 0 and 65535) is displayed in a Pokémon summary screen.
  • - The trainer's name. Displayed in a Pokémon summary screen
  • owner.gender - The trainer's gender. Is either 0 (male), 1 (female), 2 (mixed) or 3 (unknown). Only used to colour in some text in a Pokémon summary screen.
  • owner.language - The trainer's language.

Use pkmn.foreign? to determine whether the Pokémon was originally owned by the player (or pkmn.foreign?(trainer) to determine whether it was originally owned by the given trainer). Returns TRUE if either "trainerID" or "ot" do not match the trainer's (i.e. pkmn is foreign to the trainer), and FALSE if they both match (i.e. the trainer is the original owner).

The method, map ID and Level at which the Pokémon was obtained, and the map the Pokémon hatched from an egg on. "obtain_method" is either nil, 0 (met), 1 (egg received), 2 (traded) or 4 (fateful encounter).

The first three of these attributes are set when the Pokémon is generated, and again (except for "obtain_method") when an egg hatches.

pkmn.timeReceived returns the time and date the Pokémon was met (in seconds since the Unix epoch). Similarly, pkmn.timeEggHatched returns the time/date the Pokémon hatched.

obtain_text If this is a string of text, that text will be shown instead of the name of the "obtain_map" in the summary screens.

Any egg obtained from the Day Care will have this set to "Day-Care Couple".

language The Pokémon's language. Is one of the following:
  • 0 - Unknown
  • 1 - Japanese
  • 2 - English (default)
  • 3 - French
  • 4 - Italian
  • 5 - German
  • 7 - Spanish
  • 8 - Korean

Pokémon that the player catches will have the same language as the player.

There are also two functions that affect Pokémon, as follows:

Function What it does
pkmn.heal Fully heals the Pokémon. Restores the HP to full, the status to normal, and the PP of all moves to full.
pkmn.calc_stats Recalculates the Pokémon's stats (total HP, Attack, Defense, etc.).

Used when creating a Pokémon or egg, when an egg hatches, when a Pokémon's level/species/nature/gender/shininess changes, when an EV-modifying item is used, and when a Pokémon's form changes.

Level limit

The maximum level a Pokémon can attain is defined in the setting MAXIMUM_LEVEL (default 100).

In the script section GrowthRate, each growth rate is defined with an array containing all of its the "Exp per level" numbers. These numbers only go up to level 100. There is an Exp formula also defined for the growth rate which is used to calculate "Exp per level" numbers for levels which are not covered by this array. Each growth rate has a different set of numbers and a different formula.

The same script section also contains def self.max_level, which returns the highest possible level when the method is called. All checks of the maximum level in the game use this method rather than directly looking at the value of the setting MAXIMUM_LEVEL. This allows you to modify this method to add temporary level caps which you can change throughout your game.


Pokérus is a virus that can rarely be contracted by a Pokémon. While it is infected, a Pokémon will receive more EVs from battle than usual. A Pokémon will be infectious for a while after contracting Pokérus, but will still receive the effect of it forever after.

The attribute which records a Pokémon's Pokérus is described above. It works the same as in the official games.

Only wild Pokémon or eggs from the Day Care may be generated with Pokérus. The chance of this is defined by the setting POKERUS_CHANCE (default 3/65536).

After any battle, an uninfected Pokémon in the player's party will have a 33% chance of catching Pokérus from each infected Pokémon directly next to it.