Give a Pokémon to the player

This section will be archived when Pokémon Studio v3.0 is released

Pokémon Studio v3.0 will move away from RPG Maker. When that release ships, this RPG Maker XP section will be archived: the pages will remain available as reference but will no longer be updated.

PSDK can hand a Pokémon to the player straight from an event: a polished gift with its jingle and nickname prompt, a silent addition that slips into the PC when the team is full, an egg, or a fully configured Pokémon with its form, gender and held item set in advance. This guide covers the commands that give a Pokémon, where each one puts it, and the switch you read to know whether it reached the party or the PC.

These are all Interpreter methods: you call them from an event's Script command, without any prefix. RPG Maker XP has no built-in "give a Pokémon" event command, so everything here goes through Script. The Pokémon is named by its db_symbol (:pikachu, :eevee) or its numeric ID, exactly as it appears in the creatures database.

A complete gift

When the player should notice receiving a Pokémon, the professor handing over a starter, an NPC giving away an Eevee, reach for receive_pokemon_sequence. It is the full presentation: it adds the Pokémon, plays the reception jingle, shows the "received a Pokémon" message, then asks the player whether to give it a nickname.

receive_pokemon_sequence(pokemon_or_id, level = 5, shiny = false)

• pokemon_or_id — the Pokémon, as a db_symbol (:eevee) or numeric ID.
• level — its level. Optional, defaults to 5.
• shiny — its shiny status. Optional, defaults to false (see Shiny below).

A single Script command gives a level 5 Eevee with the whole ceremony:

receive_pokemon_sequence(:eevee, 5)

If the team is already full, the Pokémon lands in the PC and the player is told so. The command never deletes the event, so an NPC handing over the gift stays on the map. It returns the PFM::Pokemon it created, or nil if it could not be placed. This sequence is built on add_pokemon, described next, with all the messaging added on top.

Add a Pokémon silently

add_pokemon is the primitive underneath: it puts the Pokémon in the team with no message and no sound, useful as a side effect of another event when the player does not need a cutscene.

add_pokemon(pokemon_or_id, level = 5, shiny = false)

• pokemon_or_id — the Pokémon, as a db_symbol, a numeric ID, or a PFM::Pokemon object you built yourself.
• level — its level. Optional, defaults to 5. Ignored when you pass a ready-made PFM::Pokemon.
• shiny — its shiny status. Optional, defaults to false.

add_pokemon(:pikachu, 12)

This quietly adds a level 12 Pikachu to the party. If the party already holds six Pokémon, it goes to the current PC box instead — the addition never fails for lack of room. The method returns the Pokémon (or nil if it could be placed neither in the party nor in the PC).

Know where it landed

Because add_pokemon may divert to the PC, PSDK records the destination in a game switch you can test right after the call:

Switch	ID	Meaning
SYS_Stored	9	true = the Pokémon went to the PC box; false = it joined the party

Read switch 9 in a Conditional Branch to react, for example to tell the player their new Pokémon is waiting in the PC. receive_pokemon_sequence already reads it for you to show the "sent to Box" message, so you only need this when you call add_pokemon directly.

Shiny

The shiny argument, shared by add_pokemon, store_pokemon, receive_pokemon_sequence and add_rename_pokemon, takes more than a boolean:

• false — normal odds, the game's configured shiny rate. This is the default.
• true — always shiny.
• 0 — never shiny.
• any integer n greater than 0 — a 1 / n chance (so 8 means one in eight).

add_pokemon(:gyarados, 30, true)

That guarantees a shiny Gyarados.

Store directly in the PC

When the Pokémon should go straight to a box, never to the party even when there is room, use store_pokemon:

store_pokemon(pokemon_or_id, level = 5, shiny = false)

The arguments are identical to add_pokemon, but the destination is always the current PC box. It sets switch 9 (SYS_Stored) to true and returns the Pokémon.

store_pokemon(:magikarp, 5)

This is the command for a reward you want waiting in the box rather than forced into the active team.

Configure the Pokémon

The forms above always generate a plain Pokémon. When you need control over its form, gender, held item, nature or moves, describe it with a hash and pass it to add_specific_pokemon:

add_specific_pokemon(hash)

The hash is handed to PFM::Pokemon.generate_from_hash, the same builder used in the wild battle guide. For example, an Alolan Meowth (its form index is 1):

add_specific_pokemon(id: :meowth, level: 5, form: 1)

The most common keys are:

• id — db_symbol or numeric ID of the Pokémon. Required.
• level — its level.
• shiny / no_shiny — force or forbid the shiny appearance.
• form — the form index (-1 lets PSDK pick automatically).
• gender — 0 genderless, 1 male, 2 female.
• item — the db_symbol of a held item (:leftovers).
• nature, stats (IVs), bonus (EVs), moves, ball — and the other attributes a Pokémon can carry. The wild battle guide lists them in full.

Like add_pokemon, it adds to the party or diverts to the PC when the team is full, and returns the Pokémon.

Let the player name it

Two commands cover nicknaming.

add_rename_pokemon gives a Pokémon and immediately opens the naming screen:

add_rename_pokemon(pokemon_or_id, level = 5, shiny = false, num_char = 12)

The first three arguments match add_pokemon; num_char caps the nickname length, defaulting to 12 characters.

add_rename_pokemon(:pikachu, 10)

It adds the Pokémon, then, only if it was placed successfully, opens the rename dialog. Unlike receive_pokemon_sequence it shows no message and plays no jingle, just the naming screen.

rename_pokemon renames a Pokémon the player already owns:

rename_pokemon(index_or_pokemon, num_char = 12)

• index_or_pokemon — the party slot (0 for the first Pokémon, up to 5), or a PFM::Pokemon object.
• num_char — the character limit. Optional, defaults to 12.

To rename the lead Pokémon:

rename_pokemon(0)

Pass an object when you kept the return value of an earlier command, which lets you rename a Pokémon that may have gone to the PC:

meowth = add_specific_pokemon(id: :meowth, level: 5, form: 1)
rename_pokemon(meowth) if meowth

The if meowth guard skips the rename when the Pokémon could not be placed.

Give an egg

add_egg hands the player an egg rather than a hatched Pokémon:

add_egg(id, egg_how_obtained = :received)

• id — the species, as a db_symbol or numeric ID; or a hash (same keys as add_specific_pokemon) for a configured egg.
• egg_how_obtained — where the egg came from. This only affects the Pokémon's memo text: :received (the default, an egg handed over, for instance at a Day Care) or :found (an egg picked up, for instance on the map).

A Pichu egg received from an NPC:

add_egg(:pichu)

An egg found on the ground:

add_egg(:growlithe, :found)

A configured egg, via a hash:

add_egg({ id: :charmander, nature: :bold, form: 0 })

Eggs are created at level 1 and, like add_pokemon, go to the party or to the PC when the team is full.

Take a Pokémon back

The mirror operation removes a Pokémon from the party. Neither command shows a message, and both act on the party only.

withdraw_pokemon removes by species:

withdraw_pokemon(id, counter = 1)

• id — the species to remove, as a db_symbol or numeric ID.
• counter — how many to remove. Optional, defaults to 1.

withdraw_pokemon(:pikachu)

This removes the first Pikachu in the party. withdraw_pokemon_at removes by position instead:

withdraw_pokemon_at(index)

withdraw_pokemon_at(0)

This removes the lead Pokémon, whatever its species.

French aliases

PSDK was built by a French-speaking team, so every command above also answers to a French alias. Both names are the exact same method, use whichever reads better to you:

English name	French alias
add_pokemon	ajouter_pokemon, ajouter_stocker_pokemon
store_pokemon	stocker_pokemon
add_specific_pokemon	ajouter_pokemon_param
add_rename_pokemon	ajouter_renommer_pokemon
rename_pokemon	renommer_pokemon
add_egg	ajouter_oeuf
withdraw_pokemon	retirer_pokemon
withdraw_pokemon_at	retirer_pokemon_index

receive_pokemon_sequence has no French alias; use its English name in either locale.

Conclusion

• Use receive_pokemon_sequence for a gift the player should notice: it shows the message and jingle and offers a nickname, exactly like receiving a starter.
• add_pokemon is the silent primitive underneath: it adds to the party, or to the PC when the team is full, and sets switch 9 (SYS_Stored) so you know where it landed.
• store_pokemon always sends the Pokémon to the PC; add_specific_pokemon builds it from a hash (form, gender, held item, and so on).
• add_rename_pokemon and rename_pokemon open the naming screen; add_egg gives an egg, :received or :found.
• withdraw_pokemon and withdraw_pokemon_at take a Pokémon back out of the party, and every command has a French alias.