Essentials Docs Wiki
Advertisement
For changing the properties of a given Pokémon, see Editing a Pokémon.

This page describes how to manipulate Pokémon during the game. This includes how to give/take Pokémon, choose a Pokémon from the player's party, decide whether a certain species has been seen/captured, and so forth.

Adding a Pokémon

There are four ways to easily give the player a Pokémon (and one way to give them an egg), all of which will treat the Pokémon as originally belonging to the player. These are as follows:

Function What it does
pbAddPokemon(:PIKACHU, 20) Adds the Pokémon to the player's party (if there is a space). If the player's party is full, the Pokémon is stored in the PC instead. If there is no possible place for the Pokémon to go, this function will return a message saying that there is no space.

When it has been given, a message will say the player has received it, and then the player will be allowed to nickname it.

Instead of giving this method a species and level, you can instead pre-generate a Pokémon and pass that as this method's argument instead.

pbAddPokemonSilent(:PIKACHU, 20) Same as pbAddPokemon, except it does not display any messages at all and does not allow nicknaming.
pbAddToParty(:PIKACHU, 20) Adds the Pokémon to the player's party (if there is a space). If the player's party is full, this function will return a message saying that there is no space.

When it has been given, a message will say the player has received it, and then the player will be allowed to nickname it.

Instead of giving this method a species and level, you can instead pre-generate a Pokémon and pass that as this method's argument instead. However, since this method always adds the Pokémon to the end of the party, $player.last_party will be the Pokémon, so you will be able to modify it after adding it instead of before.

pbAddToPartySilent(:PIKACHU, 20) Same as pbAddToParty, except it does not display any messages at all and does not allow nicknaming.
pbGenerateEgg(:TOGEPI) Adds an egg to the player's party (if there is a space). It does not display any messages at all and does not allow nicknaming.

Instead of giving this method a species, you can instead pre-generate a Pokémon and pass that as this method's argument instead. Its nickname will be changed to "Egg" and the number of steps required for it to hatch will be reset. However, since this method always adds the egg to the end of the party, $player.last_party will be the egg, so you will be able to modify it after adding it instead of before.

All five methods above will return TRUE if the Pokémon/egg was added, and FALSE if it was not. This means it can be used as the statement in a Conditional Branch, e.g.

@>Conditional Branch: Script: pbAddPokemon(:EEVEE, 25)
  @>Text: Pokémon was received...
  @>
 : Else
  @>Text: Sorry, you have no room...
  @>
 : Branch End
@>

The Conditional Branch allows for additional messages, such as "I hope you treat Eevee well" or "Oh, that's too bad.".

Alternatively, you can define a Pokémon beforehand, and then add it using the same methods above, like so:

pkmn = Pokemon.new(:MAGIKARP, 10)
pkmn.makeShiny
pbAddPokemon(pkmn)

This allows you to modify the Pokémon before giving it to the player. See Editing a Pokémon for how it can be modified.

Adding a gift Pokémon

A gift Pokémon is one which originally belonged to an NPC rather than the player, and is thus a foreign Pokémon once the player has it (foreign Pokémon gain Exp faster, can disobey the player's orders depending on its level, and cannot change its nickname).

Obtaining a gift Pokémon is not the same as trading, as the player doesn't have to swap one of their Pokémon for the gift Pokémon. It is also different to finding a Pokémon in an item ball, as that would make the player its original owner and would use pbAddToParty as described above.

To give the player a gift Pokémon, use the following script:

pbAddForeignPokemon(:SHUCKLE, 20, _I("Kirk"), _I("Shuckie"), 0)

This method can only add a Pokémon to the player's party (the Pokémon cannot be sent to Pokémon storage if their party is full). This example gives the player a Level 20 Shuckle. "Shuckie" is the Pokémon's nickname (optional). "Kirk" and "0" are the original trainer's name and gender (0=male, 1=female, 2=unknown) respectively, where the trainer's name is required and their gender is optional (default is male).

If the player's party is full, this function will return FALSE without any messages. Therefore, you should use it as the statement in a Conditional Branch (see above), so that a failure to add the Pokémon can be mentioned (e.g. with the message "Oh, your party is full.").

Alternatively, you can define a Pokémon beforehand and then add it, like so:

pkmn = Pokemon.new(:MAGIKARP, 10)
pkmn.makeShiny
pbAddForeignPokemon(pkmn)

This allows you to edit the Pokémon before giving it to the player, e.g. giving it specific original trainer information. Although, since this function can only add a Pokémon to the player's party, it will be readily accessible as $player.last_party, so you can edit the Pokémon after obtaining it instead. See the page Editing a Pokémon for how to edit a Pokémon's properties.

When the Pokémon is added, the player will not be allowed to rename it. A random original trainer ID number (different to the player's trainer ID) will be generated for the Pokémon. If the Pokémon is added, a message will say so.

Demo party

The "Give Demo Party" function in the Debug menu will generate a full party of Pokémon (all at level 20), as follows:

  • Pikachu
  • Pidgeotto (knows Fly)
  • Kadabra (knows Flash and Teleport)
  • Gyarados (knows Surf, Dive and Waterfall)
  • Diglett (knows Dig, Cut, Headbutt and Rock Smash)
  • Chansey (knows Soft-Boiled, Strength and Sweet Scent)

Between them, they will know all the moves usable out of battle (except for Milk Drink, which works the same as Soft-Boiled).

Deleting a Pokémon in the party

To permanently remove a Pokémon from the player's party, use the following script:

$player.remove_pokemon_at_index(index)

"index" is the position of the Pokémon in the party (first place is 0, second place is 1, etc.). This script cannot delete the Pokémon if it is the player's only able Pokémon (i.e. unfainted and not an egg). The method does not display any messages. It returns TRUE if the Pokémon was deleted and FALSE if it was not.

Note that, after the Pokémon is deleted, any Pokémon lower down in the party list are bumped up to fill the gap. Keep this in mind if you intend to delete multiple Pokémon at once - to be safe, you should always delete Pokémon in reverse order (i.e. starting from the bottom of the party).

A less safe way to remove a Pokémon is to use the following script:

$player.party.delete_at(index)

"index" is as above. This does the same thing as $player.remove_pokemon_at_index, except that it can delete the player's last able Pokémon.

Checking for Pokémon

To see if the player has a Pokémon of a certain species in their party, use $player.has_species?(:CELEBI) (replacing the species name with the one you're checking for). Note that this ignores eggs.

@>Conditional Branch: Script: $player.has_species?(:CELEBI)
  @>Text: There is a Celebi in the party.
 : Else
  @>Text: There are no Celebi in the party.
 : Branch End

You can also check whether a specific form of a Pokémon is in the player's party, using $player.has_species?(:UNOWN, 17).

To see if the first Pokémon in the player's party is of a certain species, use the following instead:

@>Conditional Branch: Script: $player.first_pokemon.isSpecies?(:CELEBI)
  @>Text: The first Pokémon in the party is a Celebi.
 : Else
  @>Text: The first Pokémon in the party is not a Celebi.
 : Branch End

Note that $player.first_pokemon is specifically the first Pokémon in the player's party, i.e. it ignores eggs. The first unfainted Pokémon in the player's party will be $player.first_able_pokemon.

To see if the player has a fatefully encountered Pokémon of a certain species in their party, use $player.has_fateful_species?(:CELEBI) in the same way as above.

Choosing a Pokémon

To make the player choose one of the Pokémon in their party for whatever reason, use the following script:

pbChoosePokemon(var1, var2)

This opens the party screen and the player chooses one of the Pokémon therein. The two arguments are as follows:

  • "var1" is the Game Variable in which to store the party index of the chosen Pokémon. The number stored will be between 0 and 5 inclusive, or is -1 if no Pokémon was chosen. Traditionally Game Variable 1 is used for this.
  • "var2" is the Game Variable in which to store the name of the chosen Pokémon. Traditionally Game Variable 3 is used for this.

There are three possible outcomes of pbChoosePokemon: a Pokémon was chosen, an egg was chosen, or nothing was chosen (i.e. the choice was cancelled).

@>Script: pbChoosePokemon(1, 3)
@>Conditional Branch: Variable [0001] < 0
  @>Text: You cancelled the choice.
  @>Jump To Label: Done
 : Branch End
@>Conditional Branch: pbGetPokemon(1).egg?      
  @>Text: You chose an egg.
  @>Jump To Label: Done
 : Branch End
@>Text: You chose a \v[3].                      
@>Script: pbSet(2, pbGetPokemon(1).level)        
@>Text: It's at level \v[2].
@>Label: Done

This is an example of how to use pbChoosePokemon. It also shows how the chosen Pokémon can be retrieved and information queried from it.

There are two related scripts (both of which have the same two arguments as above):

  • pbChooseNonEggPokemon - Only allows the player to choose a Pokémon, not an egg (the Pokémon may be fainted).
  • pbChooseAblePokemon - Only allows the player to choose a Pokémon that is not fainted and is not an egg.

There are two further Pokémon-choosing methods, which are used to choose a Pokémon to trade away. They cannot choose an egg, a Shadow Pokémon or a Pokémon whose cannot_trade property is TRUE. They are:

  • pbChoosePokemonForTrade(var1, var2, species) - var1 and var2 are as above, and species is the species of the Pokémon that the player will trade away. This is a simplified version of pbChooseTradablePokemon.
  • pbChooseTradablePokemon(var1, var2, eligible_proc) - var1 and var2 are as above, and eligible_proc is a proc that determines whether a Pokémon is eligible to be chosen. See the page Trading Pokémon for more information.

Other scripts

Script What it does
$player.all_fainted? Returns TRUE if the player has no able Pokémon left in their party, and FALSE otherwise.
$player.has_other_able_pokemon?(0) Ignoring the Pokémon in the given party index, returns TRUE if the player has any able Pokémon, and FALSE if they don't.
$player.party_count Returns the number of Pokémon and eggs in the player's party (unfainted and fainted).
$player.pokemon_count Returns the number of Pokémon in the player's party (unfainted and fainted).
$player.able_pokemon_count Returns the number of able Pokémon in the player's party (unfainted only).
$player.heal_party Fully heals all Pokémon in the player's party. The event command "Recover All" has the same function.
$player.has_pokemon_of_type??(:FIRE) Returns TRUE if any Pokémon in the party (ignoring eggs) is at least partially the type specified, and FALSE otherwise.
$player.get_pokemon_with_move(:TACKLE) Returns the first Pokémon in the party that knows the given move (ignoring eggs). Returns nil if none know the move. Used to determine whether a move can be used outside battle.
pbBalancedLevel($player.pokemon_party) Returns the weighted mean of the levels of all Pokémon in the player's party (ignoring eggs), plus 2. Can be used to modify the levels of wild Pokémon to keep them challenging.
pbSize(pkmn) Using the personal ID and IVs of the given Pokémon (called pkmn here), calculates and returns a number which represents the Pokémon's size in millimetres. A Fishing Guru at the Lake of Rage in Johto measures Magikarp this way.
pkmn.numMoves Returns the number of moves known by the given Pokémon (called pkmn here).
pkmn.hasMove?(:TACKLE) Returns TRUE if the given Pokémon (called pkmn here) knows the given move, and FALSE if it doesn't.
pbHasEgg?(:TOGEPI) Returns TRUE if the given species can be legitimately found as an Egg, and FALSE otherwise. This includes Pokémon like Roselia (even though it is an evolved Pokémon, as it can be bred without the required Incense item), and Manaphy (even though it cannot be the result of breeding).
pbGetRegionalNumber(1, :BULBASAUR) For the given Pokémon species, returns its Regional Dex number from the given Regional Dex (1 in this example is the second Regional Dex). Returns 0 if the given species does not appear in that Regional Dex.
$player.seen?(:BULBASAUR) Returns TRUE if the given Pokémon species has been seen, and FALSE if not.
$player.owned?(:BULBASAUR) Returns TRUE if the given Pokémon species has been owned, and FALSE if not.
$player.pokedex.seen_forms_count(:UNOWN) Returns the number of forms of the given Pokémon species that have been seen. This does not include genders, even if the species has gender differences.
Advertisement