Pokémon Essentials Wiki

Item effects

226pages on
this wiki
Add New Page
Talk10 Share

This article describes how item effects are defined.

See also


  • This article describes how items themselves are defined.

Ways to use an item

Most items have an effect. A Potion will restore up to 20HP, for instance. These effects are all written in the scripts, in up to several different places depending on the kind of item and how it is used (e.g. from the Bag, in battle, as a registered item, etc.). This section of the article describes the different ways an item can be actively used, and how to set up general item effects in each case. See below for passive effects (e.g. held items), Poké Ball effects and so forth.

The script section PokemonItemEffects contains all the item effects for items that are actively used. As there are several different ways an item can be used, there are several different handlers, one for each way. There are six such handlers:

Handler Description
UseFromBag For when the item is being used from the Bag, but not on a chosen Pokémon. Typically used for Escape Rope, Repels, all Key Items and a few others.

Returns one of the following numbers:

  • 0 if the item was not used.
  • 1 - The item was used, and the Bag screen stays open.
  • 2 - The item was used, and the Bag screen is closed.
  • 3 - The item was used, and it was consumed.
  • 4 - The item was used, it was consumed, and the Bag screen is closed.
UseOnPokemon For when the item is to be used on one particular Pokémon in your party (which the player chooses). This includes Potions, Revives, Ethers, evolution stones, etc.

Returns TRUE if the item was used, and FALSE if it wasn't.

UseInField For when the item needs to close the Bag screen in order to be used, or if it is being used in the field as a registered item. For Escape Rope and all appropriate Key Items. Key Items that do not have this handler cannot be registered.
BattleUseOnPokemon For when the item is to be used on one particular Pokémon in your party (which the player chooses) during battle. Is for nearly all items that also have a UseOnPokemon handler (except ones that can't be used in battle, obviously), and also for items that affect attraction/confusion (which are in-battle-only statuses).

Returns TRUE if the item was used, and FALSE if it wasn't.

BattleUseOnBattler For when the item is to be used on a Pokémon that is currently in battle (which you choose). For X Attack et al and all Poké Balls (to decide if it can be used).

Returns TRUE if the item was used, and FALSE if it wasn't.

UseInBattle For when the item is being used in battle, but not on a Pokémon you choose. For Poké Doll (automatic escape from battle), Poké Flute (affects all battlers) and all Poké Balls (to start the capture process).

Many items can be used in more than one of the situations described above. The new item's effect must be written separately for each handler (e.g. Potion has a defined effect both for UseOnPokemon and BattleUseOnPokemon). Many items will have the exact same effect for each of its handlers, but some do not (e.g. Old Rod, other Key Items). If in doubt, look at existing items that have similar effects to your new item to decide which handlers you need, and what each handler should do.

Notice that whenever an item is referred to, it is preceded by a colon (:). This colon is important.


   next pbHPItem(pokemon,20,scene)

This describes what a Potion does. This particular example is the UseOnPokemon handler; there is also a BattlerUseOnPokemon handler for the Potion, which has an identical effect to this one.

It calls the def pbHPItem, which changes the HP of a single Pokémon, and tells it to add 20. That def will add as much HP as possible, up to that value.

   if pokemon.hp<=0 || pokemon.status!=PBStatuses::POISON
     scene.pbDisplay(_INTL("It won't have any effect."))
     next false
     scene.pbDisplay(_INTL("{1} was cured of its poisoning.",
     next true

This describes what an Antidote does (heals poison). This particular example is the UseOnPokemon handler; there is also a BattleUseOnPokemon handler for the Antidote, which has an identical effect to this one.


This line copies the UseOnPokemon handler effect of Antidote and gives it to Pecha Berry. The BattleUseOnPokemon handler effect must be copied separately (but in the same way - only the handler's name is different).

   if (pokemon.isShadow? rescue false)
     scene.pbDisplay(_INTL("It won't have any effect."))
     next false
   if newspecies<=0
     scene.pbDisplay(_INTL("It won't have any effect."))
     next false
     next true


This code describes what an evolution stone does. It only has the UseOnPokemon handler. The def pbCheckEvolution checks whether the stone being used will work or not, and returns a value for "newspecies" (either the ID number of the evolved species if it can be used, or 0 if it can't). The effect then carries out depending on this value.

The Fire Stone's handler is then copied to all the other evolution stones at once. There is no difference here between different stones - the actual check to see which Pokémon they can be used on is done in pbCheckEvolution. Note that an item's handler can be copied to several other items at once.

   if (pbIsWaterTag?(terrain) && !$PokemonGlobal.surfing && notCliff) ||
      (pbIsWaterTag?(terrain) && $PokemonGlobal.surfing)
     next 2
     Kernel.pbMessage(_INTL("Can't use that here."))
     next 0
   if !pbIsWaterTag?(terrain) || (!notCliff && !$PokemonGlobal.surfing)
     Kernel.pbMessage(_INTL("Can't use that here."))
   if pbFishing(encounter)

These are the two handlers for the Old Rod. Note that they are different. The first one does a check for whether it can be used - if successful (i.e. when used while facing water, but not off a clifftop), all it does is "next 2", which means that the Bag screen should be closed and the UseInField handler for that item should be run. If the Old Rod cannot be used, the Bag screen is not closed in the first place.

If the Old Rod has been registered and is being used that way, it performs the UseInField handler effect immediately instead. The UseInField handler is the one that actually describes what the Old Rod does.

Note that some items which have a UseInField handler counterpart will NOT simply "next 2" in its UseFromBag handler effect (e.g. Town Map, Coin Case), even if it can be used. Those items are typically Key Items (i.e. they can be registered, hence needing the UseInField handler), but they do not need to close the Bag screen in order to do something. In this case, the two handlers are simply identical.

Poké Balls

Poké Balls can have several different effects, from changing the likelihood of capturing a Pokémon to making the captured Pokémon happier. These effects are not defined in the same place as above, but in the script section PokemonBalls.

Firstly, a new Poké Ball item needs to be added to the list present in the script section PokemonBalls.

Next, if your new Poké Ball item behaves differently to a regular Poké Ball, you will need to add a new handler to explain what it does. The possible handlers are as follows:

Handler Description
IsUnconditional If present, it will always be called as soon as the wild Pokémon has been absorbed into the Poké Ball. If this handler returns TRUE, then the capture is successful, regardless of anything else. By default, only the Master Ball has this handler (and it always returns TRUE).
ModifyCatchRate Changes the catch rate of the Poké Ball. This change can depend on any factor of the Pokémon to be captured (e.g. level, weight, type), and/or on any condition of the battle (e.g. turn count, environment, time of day). Most Poké Balls have one of these handlers.
OnCatch Describes an effect that happens after a successful capture. The Heal Ball will heal the captured Pokémon, and the Friend Ball sets its happiness to 200.

If your Poké Ball will have other effects that apply after capture (e.g. doubles any future happiness gain), then you will need to modify other scripts to check what kind of Poké Ball the Pokémon is in, and perform the extra effects accordingly.


   next (catchRate*3/2).floor

A Great Ball is 1.5 times as effective as a regular Poké Ball. This code reflects this by multiplying "catchRate" by 3/2. As "catchRate" should always be a whole number, the equation is "floored", meaning that the result (the new "catchRate") is rounded down to the next lowest whole number.

   catchRate=(catchRate*7/2).floor if battle.environment==PBEnvironment::Underwater
   next catchRate

A Dive Ball is 3.5 times as effective as a regular Poké Ball, but only if used while underwater. It has the same effectiveness as a regular Poké Ball if it is used above water.

   next true

The Master Ball will always capture a Pokémon. Because an IsUnconditional handler is always called as soon as a Pokémon is absorbed into a Poké Ball, and because this handler always returns TRUE, the capture will always be successful.


The Friend Ball doesn't change the capture rate, but it does change the happiness of the captured Pokémon upon capture. This is the code that does it. Any other effects that occur upon successfully capturing a Pokémon (these effects usually only affect the captured Pokémon) can use this handler (e.g. the Heal Ball restoring the captured Pokémon to full health).

TMs and HMs

Main article: Learning moves

TMs and HMs are also used in a different way to the methods mentioned above. All TMs and HMs work in exactly the same way, with the one exception being that a TM will be consumed after use (unless TMs are set to be infinite use).

The article Learning moves contains more information about how a move is taught. The only requirement for creating a TM or HM item is to define it as one.


Mail items cannot be used like other items, but instead can be read. Reading a mail item from the Bag will simply show the blank mail, while reading a mail item being held by a Pokémon will show the mail and its message.

When a mail item is given to a Pokémon to hold, the player can enter a message. It is automatically signed with the player's name. If the mail is defined as one which shows Pokémon on it, then the holder and the next two Pokémon currently in the player's party will appear as icons on the mail, in order of right to left.

A mail's message (and details of the Pokémon to show on it) are saved as a property of the Pokémon holding the mail. See the article Editing a Pokémon for an explanation of how to set the message, sender's name and icons for a held mail item.

The only requirement for creating a mail item is to define it as one.

Held items

Some items have effects if they are held by a Pokémon, such as making certain types of moves stronger in battle, giving more experience or making a particular weather move last longer. As there are many different kinds of effects a held item can have, they cannot all be detailed here. Instead, this section has an overview of some of the different kinds of held items.

Move power-altering items

These include Miracle Seed (Grass), Charcoal (Fire) and Mystic Water (Water) items, along with the various Plates, Thick Club, Sea Incense and so forth. These are all items that, when held, will alter the power of a damaging move.

In the script section PokeBattle_Move, there is a long def called pbCalcDamage. It contains all the calculations that affect the power of a move, and amongst those calculations are those that involve held items.

Note that many of these calculations affect only Attack or Special Attack, not both.

Triggered effect items

The script section PokeBattle_Battler contains the def pbBerryCureCheck, which checks whether a Pokémon can automatically use (usually consume) its held item in order to gain its effect. The def's name comes from the fact that the majority of consumable held items are berries, although it also covers the White Herb, Mental Herb, Leftovers and Black Sludge (the latter two aren't consumed, but still included here as their effects are triggered).

If your held item can be used during battle to give an effect, add some code in here. Note that most existing items have restrictions on when they can be used (e.g. a status-curing item can only be used when the Pokémon has that status, or a HP-restoring item can only be used when the Pokémon has low HP).

Other held item effects

There are other effects which held items can have. Below are two tables that list where to find some effects that can be modified depending on a held item's presence. Many of them will already contain at least one example of an existing held item's effect.

The following effects occur in battle:

What is affected Which script contains the effect
Accuracy and evasion PokeBattle_Move, pbAccuracyCheck
Chance of flinching PokeBattle_Battler, pbProcessMoveAgainstTarget
Critical hit ratio PokeBattle_Move, pbIsCritical?
Exp and EVs gained from knocking out a Pokémon PokeBattle_Battle, pbGainEXP
Fleeing from battle PokeBattle_Battle, pbCanRun?, pbRun
Money gained from trainer battles PokeBattle_Battle, pbEndOfBattle
Priority of a move PokeBattle_Battle, pbPriority
Speed PokeBattle_Battler, pbSpeed
Type effectiveness of a move PokeBattle_Move, pbTypeModifier
Which moves the holder can use PokeBattle_Battle, pbCanChooseMove?

The following effects occur outside of battle:

What is affected Which script contains the effect
Breeding (with Incense) PokemonDayCare, pbDayCareGenerateEgg
Encounter rate of wild Pokémon PokemonEncounters, pbGenerateEncounter
Evolution (specifically Everstone) PokemonEvolution, pbCheckEvolutionEx
Happiness gain PokeBattle_Pokemon, changeHappiness

Special item effects

There are some items, usually Key Items, that have unique or significant effects when used. These include:

It is best to look at the scripts directly to see how these items work.

In general, any other Key Items are used passively. That is, an event will check to see if the player has a particular Key Item (e.g. Key Card), rather than the player having to actively use that item. Checks like this are described in the article Manipulating items.

Use by enemy trainers

Main article: Battle AI

Some items can be used by enemy trainers during battle. The effects of those items are defined in the script section PokeBattle_Battle in the defs pbEnemyItemToUse and pbEnemyUseItem. The effect of an item here should be the same as when the player uses the same item, for fairness.

This is a complicated topic, and unnecessary for most users. You should not attempt to modify the AI unless you have decent scripting knowledge.

Related tutorials

Ad blocker interference detected!

Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.