Evolution

*For defining evolutions for particular species, see Defining a species.*
This page describes Pokémon **evolution**. It details the different evolution methods available by default, and explains how to create new evolution methods.

## Evolution methods

A Pokémon can evolve in a variety of different ways, such as gaining a level or gaining a new owner, or if it just really likes you. Nearly all evolution methods that exist in the Pokémon games have been coded into Essentials. You can even invent a few new methods of your own.

The evolution paths for a species are listed in the PBS files "pokemon.txt" and "pokemon\_forms.txt" as a series of comma-separated triplets. Each triplet describes one evolution branch, and contains the following information:

1. The ID of the species to evolve into.
2. The name of the evolution method used.
3. A special parameter the evolution method may use, such as a level number or item's ID.

Each evolution method is checked in the order they are listed in the PBS file. If the Pokémon being checked can evolve through several different methods, and fulfils the criteria for more than one of them at the same time (e.g. Eevee can fulfil both happiness and location at the same time), it will evolve using the one that is listed first and ignore the others.

The code for all evolution methods is in the script section **Evolution**. The code is modular, however, and can be placed in another script section, e.g. to help you keep track of new things you've added. Note that some of the defined evolution methods are unused by default.

### Levelling-up evolution methods

Most evolution methods are checked when a Pokémon levels up. They have a `"level_up_proc"` defined. They are:

### Using an item evolution methods

These evolution methods are checked when an item (typically an evolution stone) is used on a Pokémon. They have a `"use_item_proc"` defined. Evolutions triggered this way cannot be cancelled. They are:

 ItemMale
 ItemFemale
 ItemDay
 ItemNight
 ItemHappiness

### Trade evolution methods

These evolution methods are checked when a Pokémon is received in a trade. They have an `"on_trade_proc"` defined. Evolutions triggered this way cannot be cancelled. They are:

### After every battle evolution methods

These evolution methods are checked after every battle (if the setting `CHECK_EVOLUTION_AFTER_ALL_BATTLES` is set to true) or after every battle the player wins/finishes by catching a Pokémon. They have an `"after_battle_proc"` defined. There is only one such evolution method, which is:

### Manually triggered evolution methods

These evolution methods are triggered manually, usually by an event. The trigger is calling the script `pbEvolutionEvent(number)`, where `number` is an identifying number for a particular triggering event (such as reading a scroll or walking under a bridge). The same number should not be used by multiple evolution methods of this kind.

By default, the numbers are:

* 1: Kubfu -> Urshifu (Kubfu's form should be manually set before calling `pbEvolutionEvent(1)` to ensure it evolves into the appropriate form of Urshifu)
* 2: Galarian Yamask -> Runerigus (uses "EventAfterDamageTaken")

They have an `"event_proc"` defined. They are:

 EventAfterDamageTaken

### Code run after evolution

Some evolution methods run additional code after they successfully evolve a Pokémon. This additional code is defined in an `"after_evolution_proc"`. After the evolution happens, every evolution path for the old species is checked, and the first one whose evolution method has an `"after_evolution_proc"` defined for it *and* that evolution path produces the new species will have that `"after_evolution_proc"` code run.

This additional code is usually to remove the Pokémon's held item if the evolution method involved it, but there is one evolution method which only has this additional code:

### Examples

```
Evolutions = IVYSAUR,Level,16

```

The evolution path of Bulbasaur. It has only one evolution method, which is evolving through level up at Level 16 (or higher) into Ivysaur.

```
Evolutions = TOGETIC,Happiness,

```

The evolution path of Togepi. It has only one evolution method, which is evolving when happy enough into Togetic. Note the comma at the end of this line - the third entry of this triplet is still included, even though it is blank. Every evolution path must be a triplet (i.e. contain two commas).

```
Evolutions = VAPOREON,Item,WATERSTONE,JOLTEON,Item,THUNDERSTONE,FLAREON,Item,FIRESTONE,LEAFEON,LocationFlag,MossRock,LEAFEON,Item,LEAFSTONE,GLACEON,LocationFlag,IceRock,GLACEON,Item,ICESTONE,SYLVEON,HappinessMoveType,FAIRY,ESPEON,HappinessDay,,UMBREON,HappinessNight,

```

The evolution paths of Eevee. It has ten evolution methods, as follows:

* Use a Water Stone on it to evolve into Vaporeon.
* Use a Thunder Stone on it to evolve into Jolteon.
* Use a Fire Stone on it to evolve into Flareon.
* Level up on a map whose metadata contains the "MossRock" flag to evolve into Leafeon.
* Use a Leaf Stone on it to evolve into Leafeon.
* Level up on a map whose metadata contains the "IceRock" flag to evolve into Glaceon.
* Use an Ice Stone on it to evolve into Glaceon.
* Level up when happy enough and knowing a Fairy-type move to evolve into Sylveon.
* Level up when happy enough during the day to evolve into Espeon.
* Level up when happy enough during the night to evolve into Umbreon.

Note the order in which these are listed. They are checked in order, so evolving into Leafeon/Glaceon takes priority over evolving into Sylveon, which in turn takes priority over evolving into Espeon/Umbreon. Note that evolving into Leafeon/Glaceon can be done in two different ways.

```
Evolutions = NINJASK,Ninjask,20,SHEDINJA,Shedinja,20

```

The evolution paths of Nincada. It uses the twin evolution methods of "Ninjask" and "Shedinja":

* "Ninjask" evolves the Nincada into a Ninjask at/above Level 20, just like "Level" does.
* "Shedinja" immediately duplicates the Ninjask (if there is an empty spot in the player's party and a spare Poké Ball), and turns the duplicate into a Shedinja.

Note that these methods are named after members of the Nincada family only because they are the only Pokémon that exhibit this behaviour. Fakemon can use these methods just as easily.

## Creating a new evolution method

The evolution methods are defined in the script section **Evolution**. Each one is registered in `GameData::Evolution`, and has multiple properties which are:

 :parameter
* Integer (a whole number 0 or greater; could be a level number, a map ID, a region number, etc.)
* String (a piece of text, usually the name of a flag defined in a PBS file)
* A GameData class written as a symbol, e.g. :Move, :Type, :Item, :Species, :Ability (other GameData classes can be used, but the in-game "pokemon.txt" editor will not allow you to choose a property from that GameData class for an evolution path for a species)

If undefined, then the parameter will be a number.
 :any\_level\_up
 :level\_up\_proc
 :use\_item\_proc
 :on\_trade\_proc
 :after\_battle\_proc
 :event\_proc
 :after\_evolution\_proc

Here are some examples:

```
GameData::Evolution.register({
  :id            => :Level,
  :parameter     => Integer,
    next pkmn.level >= parameter
  }
})

```

```
GameData::Evolution.register({
  :id            => :Happiness,
  :any_level_up  => true,   # Needs any level up
    next pkmn.happiness >= (Settings::APPLY_HAPPINESS_SOFT_CAP ? 160 : 220)
  }
})

```

```
GameData::Evolution.register({
  :id                   => :HoldItem,
  :parameter            => :Item,
  :any_level_up         => true,   # Needs any level up
    next pkmn.item == parameter
  },
    next false if evo_species != new_species || !pkmn.hasItem?(parameter)
    pkmn.item = nil   # Item is now consumed
    next true
  }
})

```

```
GameData::Evolution.register({
  :id            => :Item,
  :parameter     => :Item,
    next item == parameter
  }
})

```

```
GameData::Evolution.register({
  :id            => :TradeSpecies,
  :parameter     => :Species,
    next pkmn.species == parameter && !other_pkmn.hasItem?(:EVERSTONE)
  }
})

```

```
GameData::Evolution.register({
  :id                => :BattleDealCriticalHit,
  :parameter         => Integer,
    next $game_temp.party_critical_hits_dealt &&
         $game_temp.party_critical_hits_dealt[party_index] &&
         $game_temp.party_critical_hits_dealt[party_index] >= parameter
  }
})

```

```
GameData::Evolution.register({
  :id         => :Event,
  :parameter  => Integer,
    next value == parameter
  }
})

```

As mentioned above, this code is modular, which means you can write the code for your new evolution methods in a new script section to help keep track of content you have added.

## Possible new evolution methods

There is a great deal of flexibility in what an evolution method can be. You can check any aspect of the Pokémon wanting to evolve (`pkmn`), use any kind of GameData class to determine what the parameter represents (`parameter`), or refer to any recorded aspect in the game (e.g. weather, location). You can even keep track of additional factors, such as the number of critical hits dealt or amount of damage taken in a battle.

The exact code you'll need to use for your custom evolution method will obviously depend on what you want it to do. This wiki page cannot describe at a general level what to do; however, some ideas are:

* Create variants of existing methods, e.g. one that occurs if the Pokémon has a certain happiness value or *less* (i.e. the opposite of "Happiness").
* Merge two or more existing methods together into a new one. Remember that you only have one parameter to work with, though.
* Evolution that depends on the Pokémon's nature or form or total EVs, or if a given stat has risen above a particular value.
* Fusion evolution (e.g. for Magnemite/Slowpoke). Check that there is a Shellder in the party, and if so, delete it and evolve the levelled-up Slowpoke. The deletion would occur in an "after\_evolution\_proc".
* Change the Pokémon's form depending on how it evolves. This is done by setting the form as part of the check. This assumes the unevolved Pokémon doesn't have multiple forms, only the evolved species.
* Disable all evolutions for a time by inserting the line `return nil if $game_switches[42]` at the very beginning of `def check_evolution_internal` (in the script section **Pokemon**, next to similar lines for the Everstone and Battle Bond) and setting Game Switch 42 to ON whenever you want to forbid all evolutions. The number of the Game Switch you use may vary.

As well as creating new evolution methods, you could also/instead make a few changes to existing methods.

## Evolution screen

When a Pokémon evolves, it is displayed on screen with some messages ("What? Pikachu is evolving!", etc.). The player has the chance to cancel some evolutions by pressing a button during the animation.

The animation itself is described in `class PokemonEvolutionScene` in the script section **UI\_Evolution**. It shows the Pokémon's sprite fade to white, then grow bigger and smaller while alternating with the sprite of its evolved form, before the evolved form's sprite colours in.

The background used for the evolution screen is located in the "Graphics/UI" folder, and is called "evolution\_bg.png". This image will be tiled across the entire background. If there is no picture with this name, a blank white background will be shown instead.