Manipulating Pokémon

Template:For
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:

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