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 (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:

When it has been given, a message will say the player has received it, and then the player will be allowed to nickname it.
 `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.
 `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.shiny = true
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.shiny = true
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.