Manipulating Pokémon

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, 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. When it has been given, a message will say the player has received it, and then the player will be allowed to nickname it. If there is no possible place for the Pokémon to go, this function will return a message saying that there is no space.
pbAddPokemonSilent(:PIKACHU,20)	Same as above, 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.
pbAddToPartySilent(:PIKACHU,20)	Same as above, except it does not display any messages at all and does not allow nicknaming.

All four methods above will return TRUE if the Pokémon 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 = pbGenPkmn(:MAGIKARP,10)
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.

Each of the four methods listed above have an extra parameter at the end, which determines whether to record the newly-added Pokémon's form in the Pokédex (in addition to seeing/owning it at all). This parameter is TRUE by default, i.e. the form is recorded by default. You should never need to set this to FALSE, but the option is there.

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)

"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). "Shuckie" is the Pokémon's nickname (optional).

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 = pbGenPkmn(:MAGIKARP,10)
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 $Trainer.lastParty, so you can edit the Pokémon after obtaining it instead. See 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 (unless it has already been changed before adding it). If the Pokémon is added, a message will say so.

This method has an extra parameter at the end, which determines whether to record the newly-added Pokémon's form in the Pokédex (in addition to seeing/owning it at all). This parameter is TRUE by default, i.e. the form is recorded by default. You should never need to set this to FALSE, but the option is there.

Demo party

The def pbCreatePokemon in the script section Debug_Actions can be used to give the player a full party of Pokémon (all at level 20), as follows:

• Pikachu
• Pidgeotto
• Kadabra
• Gyarados
• Diglett
• Chansey

Between them, they will know all the moves usable out of battle (except for Milk Drink).

This script exists for demonstration purposes only, and should not be used in any game.

Deleting a Pokémon in the party

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

pbRemovePokemonAt(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 (and thus should be used as the argument of a Conditional Branch).

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:

$Trainer.party.delete_at(index)

"index" is as above. This does the same thing as pbRemovePokemonAt, 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 pbHasSpecies?(:CELEBI) (replacing the species name with the one you're checking for). Note that this ignores Eggs.

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

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

@>Conditional Branch: Script: isConst?($Trainer.firstPokemon.species,PBSpecies,: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 $Trainer.firstPokemon 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 $Trainer.firstAblePokemon.

To see if the player has a fatefully encountered Pokémon of a certain species in their party, use pbHasFatefulSpecies?(: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 (or nickname, if it has one) 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.
• pbChooseTradablePokemon - Only allows the player to choose a Pokémon that is not an egg and is not a Shadow Pokémon.

Other scripts

Script	What it does
pbAllFainted	Returns TRUE if the player has no able Pokémon left in their party, and FALSE otherwise.
pbCheckAble(0)	Ignoring the Pokémon with the party index given, returns TRUE if the player has any able Pokémon, and FALSE if they don't.
$Trainer.partyCount	Returns the number of Pokémon and eggs in the player's party (unfainted and fainted).
$Trainer.pokemonCount	Returns the number of Pokémon in the player's party (unfainted and fainted).
$Trainer.ablePokemonCount	Returns the number of able Pokémon in the player's party (unfainted only).
pbHealAll	Fully heals all Pokémon in the player's party. The event command "Recover All" has the same function.
pbHasType?(:FIRE)	Returns TRUE if any Pokémon in the party (ignoring Eggs) is at least partially the type specified, and FALSE otherwise.
pbCheckMove(:TACKLE)	Returns the party index number of 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($Trainer.pokemonParty)	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 mm. 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,PBSpecies::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.
pbGetNationalNumber(1,135)	Returns the National Dex number of the Pokémon species which has the given Regional Dex number (135) in the given Regional Dex (1).
$Trainer.hasSeen?(:BULBASAUR)	Returns TRUE if the given Pokémon species has been seen, and FALSE if not.
$Trainer.hasOwned?(:BULBASAUR)	Returns TRUE if the given Pokémon species has been owned, and FALSE if not.
$Trainer.numFormsSeen[PBSpecies::BULBASAUR]	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.