Essentials Docs Wiki

This Pikachu has the ability "Static", which may paralyze a Pokémon that hits it.

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", 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. See the page List of abilities for all the abilities currently coded in Essentials.

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 extracted from the scripts and placed in an ability handler. Other ability effects are just needed for a simple check and aren't worth extracting, either because the check is so simple already, or because the effect is obviously unique and no other ability would ever need to trigger at the same time. Either way, there's no point in adding a trigger point for an ability handler in its place.

The existence of ability handlers means an ability's effect (if it can be put into one or more handlers) 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.

If the Pokémon's personal ID is even, it will have the first normal ability available to its species. If its personal ID is odd, it will have the second normal ability. Obviously this only applies if there are two normal abilities to choose from; if there is just one defined normal ability, the Pokémon will always have that (or no ability if none are defined).

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.

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.).

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.