Abilities

*For how to add a new ability to your game, see Defining an ability.*
*For a list of abilities in Essentials, see List of abilities.*
*For how to make a Pokémon have a specific ability, see Editing a Pokémon.*
*For giving an NPC trainer's Pokémon a specific ability, see Defining a trainer.*
This page describes **how abilities work in Essentials**.

## Defining an ability

*Main article: Defining an ability*
An ability begins with its definition. This means that is is listed in the PBS file "abilities.txt", or a PBS file named "abilities\_XYZ.txt" (where "XYZ" is any text), so that it can be recognised by the game as an ability. This alone does not give the ability an effect, but you *must* start by defining it before you can use it.

## Ability effects

An ability is a special effect that the bearer (a Pokémon with that ability) has access to. The vast majority of abilities have unique effects, although there are some which do the same things and just have different names.

There is a wide variety of effects an ability can have, from changing stats to inflicting status problems to powering up attacks to preventing escape, and so on. They can be continuous effects, or occur at certain trigger moments (such as when a Pokémon enters battle or at the end of a battle round), or only apply while a certain condition is true, or they can have an effect outside of battle. They can even do a combination of these.

As an ability can be so varied in what it does, it is very difficult (if not impossible) to generally describe how to code an ability effect. The best advice is to find an existing ability which does something similar to the new ability you want to create, and copy that and tweak it.

Many abilities are written in the script section **Battle\_AbilityEffects**. This script section contains "handlers" for these abilities, which are bits of code that are triggered at the appropriate times (the name of the handler, e.g. "DamageCalcFromTarget", suggests when it would trigger). An ability may have multiple handlers for different parts of their effects, e.g. Dry Skin heals the bearer when hit by a Water-type move, makes the bearer weaker to Fire-type moves, and either heals or hurts the bearer at the end of each round depending on the weather - these are three separate handlers.

Some ability effects are more convoluted and cannot simply be written into a self-enclosed handler, or it isn't worth doing so. These ability effects will remain in various places throughout the scripts where they are needed.

The code for an ability handler can be written anywhere in the scripts - they don't have to be written alongside the existing ones. In other words, you can make a new script section for your custom abilities' code, which makes it easier to keep track of your changes.

## Assigning an ability to a Pokémon species

*Main article: Defining a species*
Once an ability is defined, you can let one or more Pokémon species have access to it. An ability can be assigned to a species either as a normal ability or as a hidden ability - these are accessible in different ways.

It is possible for an individual Pokémon to be given any ability, even one that is not naturally available to it (as a normal or hidden ability). However, if it changes species or form, it will lose the given ability and revert to whichever natural ability it would have instead. See the page Editing a Pokémon for more information.

### Normal abilities

A Pokémon species can have access to 0, 1 or 2 different abilities as normal abilities. When a Pokémon of that species is generated (e.g. via a wild encounter or as a gift like a starter Pokémon), its ability will be randomly chosen from all the normal abilities available to that species. Each normal ability has an equal chance of being chosen - the choice depends on the value of the Pokémon's personal ID, which is random.

You can use one of the following lines of code to force a particular Pokémon's ability to be, respectively, the first or second normal ability defined for its species:

```
pkmn.ability_index = 0
pkmn.ability_index = 1

```

where `pkmn` is the individual Pokémon whose ability you are changing. This sets the Pokémon's ability index, where the number is the ability slot you are forcing the Pokémon to use. Slots 0 and 1 are the normal abilities, and slots 2, 3, 4, etc. are the hidden abilities, in the order they are defined for the species. This will remain in effect even if the Pokémon changes species or form.

### Hidden abilities

In addition to normal abilities, a Pokémon species can also have access to any number of different abilities as hidden abilities. An individual Pokémon will never naturally be given one of its hidden abilities; you must use special code to force its ability to be a hidden one. Examples of the code that sets a Pokémon's ability to one of its hidden abilities are:

```
pkmn.ability_index = 2
pkmn.ability_index = 3
pkmn.ability_index = 4

```

where `pkmn` is the individual Pokémon whose ability you are changing. This sets the Pokémon's ability index, where the number is the ability slot you are forcing the Pokémon to use. Slots 0 and 1 are the normal abilities, and slots 2, 3, 4, etc. are the hidden abilities, in the order they are defined for the species (2 is the first hidden ability, 3 is the second hidden ability, etc.). This will remain in effect even if the Pokémon changes species or form.

If you set a Pokémon's ability index to use a particular hidden ability slot (i.e. the number is 2 or higher), but there is no defined hidden ability in that slot, then it will instead use the normal ability it would naturally have, as described above. It will *not* use a different hidden ability instead.