The Battle object

Abstract Battle

class poke_env.battle.abstract_battle.AbstractBattle(battle_tag: str, username: str, logger: Logger, save_replays: str | bool, gen: int)

Bases: ABC

MESSAGES_TO_IGNORE = {'', '-anim', '-block', '-burst', '-center', '-combine', '-crit', '-fail', '-fieldactivate', '-hint', '-hitcount', '-miss', '-notarget', '-nothing', '-ohko', '-resisted', '-supereffective', '-waiting', '-zbroken', 'J', 'L', 'askreg', 'badge', 'c', 'chat', 'crit', 'debug', 'deinit', 'gametype', 'hidelines', 'html', 'immune', 'inactiveoff', 'init', 'j', 'join', 'l', 'leave', 'n', 'name', 'rated', 'resisted', 'sentchoice', 'split', 'supereffective', 'teampreview', 'uhtml', 'upkeep', 'zbroken'}
abstract property active_pokemon: Any
abstract property all_active_pokemons: List[Pokemon | None]
apply_teambuilder_team(role: str, teambuilder_team: List[TeambuilderPokemon], teampreview_team: List[Pokemon])
abstract property available_moves: Any
abstract property available_switches: Any
property battle_tag: str
Returns:

The battle identifier.

Return type:

str

abstract property can_dynamax: Any
abstract property can_mega_evolve: Any
abstract property can_tera: Any
abstract property can_z_move: Any
abstractmethod clear_all_boosts()
property commanding: bool
Returns:

Whether commander is active with Dondozo and Tatsugiri on the field

Return type:

bool

property dynamax_turns_left: int | None
Returns:

How many turns of dynamax are left. None if dynamax is not active

Return type:

int, optional

abstractmethod end_illusion(pokemon_name: str, details: str)
end_turn(turn: int)
field_start(field_str: str)
property fields: Dict[Field, int]
Returns:

A Dict mapping fields to the turn they have been activated.

Return type:

Dict[Field, int]

property finished: bool
Returns:

A boolean indicating whether the battle is finished.

Return type:

Optional[bool]

abstract property force_switch: Any
property format: str | None
Returns:

The format of the battle, in accordance with Showdown protocol

Return type:

Optional[str]

property gen: int
Returns:

The generation of the battle; will be the parameter with which the the battle was initiated

Return type:

int

get_pokemon(identifier: str, force_self_team: bool = False, details: str = '', request: Dict[str, Any] | None = None) → Pokemon

Returns the Pokemon object corresponding to given identifier. Can force to return object from the player’s team if force_self_team is True. If the Pokemon object does not exist, it will be created. Details can be given, which is necessary to initialize alternate forms (eg. alolan pokemons) properly.

When the message says the pokemon is active we can check if this correct or Zoroark is playing tricks on us:

The way to check for a zoroark is seeing that the pokemon it is asking for isn’t currently active. For that we need to have the Pokemon instance of both the active and the believed active in the team. If we don’t we need to use the normal get_pokemon.

If both are the same, we can simply return either. If they are different, we need to check which one has illusion. If there is none, we log a warning, but this should never happen.

If the Pokémon with the Illusion is not active, the following has occurred:

  • For some reason or another in the current turn, our Zoroark has switched in.

  • The message from the switch in has made it so the illusion is the active Pokémon

  • Now the illusion has been broken, it says that the active is Zoroark, but in our battle it isn’t.

  • We need to return the Zoroark.

If it isn’t broken, the request for the next turn will tell us the Zoroark is active. However the messages that tell us the active Pokémon will be referring to the illusion, so we use: if believed_active._ability == “illusion”:

Parameters:

  • identifier (str) – The identifier to use to retrieve the pokemon.

  • force_self_team (bool) – Wheter to force returning a Pokemon from the player’s team. Defaults to False.

  • details (str, defaults to '') – Detailled information about the pokemon. Defaults to ‘’.

  • request (Dict, optional, defaults to None) – Detailled information about the pokemon from a request. Defaults to None.

Returns:

The corresponding pokemon object.

Return type:

Pokemon

Raises:

ValueError – If the team has too many pokemons, as determined by the teamsize component of battle initialisation.

abstract property grounded: Any
in_team_preview: bool
is_grounded(mon: Pokemon)
property last_request: Dict[str, Any]
The last request received from the server. This allows players to track

rqid and also maintain parallel battle copies for search/inference

Returns:

The last request.

Return type:

Dict[str, Any]

logger: Logger | None
property lost: bool | None
Returns:

If the battle is finished, a boolean indicating whether the battle is lost. Otherwise None.

Return type:

Optional[bool]

property max_team_size: int | None
Returns:

The maximum acceptable size of the team to return in teampreview, if applicable.

Return type:

int, optional

abstract property maybe_trapped: Any
abstract property opponent_active_pokemon: Any
property opponent_dynamax_turns_left: int | None
Returns:

How many turns of dynamax are left for the opponent’s pokemon. None if dynamax is not active

Return type:

int | None

property opponent_rating: int | None

Opponent’s rating after the end of the battle, if it was received.

Returns:

The opponent’s rating after the end of the battle.

Return type:

int, optional

property opponent_role: str | None
Returns:

Opponent’s role in given battle. p1/p2

Return type:

str, optional

property opponent_side_conditions: Dict[SideCondition, int]
Returns:

The opponent’s side conditions. Keys are SideCondition objects, values are:

  • the number of layers of the SideCondition if the side condition is

    stackable

  • the turn where the SideCondition was setup otherwise

Return type:

Dict[SideCondition, int]

property opponent_team: Dict[str, Pokemon]

During teampreview, keys are not definitive: please rely on values.

Returns:

The opponent’s team. Keys are identifiers, values are pokemon objects.

Return type:

Dict[str, Pokemon]

property opponent_used_dynamax: bool
Returns:

Whether or not opponent’s current active pokemon can dynamax

Return type:

bool

property opponent_used_mega_evolve: bool
Returns:

Whether or not opponent’s current active pokemon can mega-evolve

Return type:

bool

property opponent_used_tera: bool
Returns:

Whether or not opponent’s current active pokemon can terastallize

Return type:

bool

property opponent_used_z_move: bool
Returns:

Whether or not opponent’s current active pokemon can z-move

Return type:

bool

property opponent_username: str | None
Returns:

The opponent’s username, or None if unknown.

Return type:

str, optional.

parse_message(split_message: List[str])
abstractmethod parse_request(request: Dict[str, Any], strict_battle_tracking: bool = False)
property player_role: str | None
Returns:

Player’s role in given battle. p1/p2

Return type:

str, optional

property player_username: str
Returns:

The player’s username.

Return type:

str

property players: Tuple[str, str]
Returns:

The pair of players’ usernames.

Return type:

Tuple[str, str]

property rating: int | None

Player’s rating after the end of the battle, if it was received.

Returns:

The player’s rating after the end of the battle.

Return type:

int, optional

property reviving: bool
rules: List[str]
save_replay(file_path: str | Path) → Path

Writes this battle replay to a file.

Parameters:

file_path (str | pathlib.Path) – Path where replay html should be written.

Returns:

The written replay path.

Return type:

pathlib.Path

property side_conditions: Dict[SideCondition, int]
Returns:

The player’s side conditions. Keys are SideCondition objects, values are:

  • the number of layers of the side condition if the side condition is

    stackable

  • the turn where the SideCondition was setup otherwise

Return type:

Dict[SideCondition, int]

side_end(side: str, condition_str: str)
abstractmethod switch(pokemon_str: str, details: str, hp_status: str)
property team: Dict[str, Pokemon]
Returns:

The player’s team. Keys are identifiers, values are pokemon objects.

Return type:

Dict[str, Pokemon]

property team_size: int
Returns:

The number of Pokemon in the player’s team.

Return type:

int

property teambuilder_team: list[TeambuilderPokemon] | None
property teampreview: bool
Returns:

Wheter the battle is awaiting a teampreview order.

Return type:

bool

property teampreview_opponent_team: List[Pokemon]
Returns:

The opponent’s team during teampreview.

Return type:

List[Pokemon]

property teampreview_team: List[Pokemon]
Returns:

The player’s team during teampreview.

Return type:

List[Pokemon]

tied()
abstract property trapped: Any
property turn: int
Returns:

The current battle turn.

Return type:

int

property used_dynamax: bool
Returns:

Whether or not the current active pokemon can dynamax

Return type:

bool

property used_mega_evolve: bool
Returns:

Whether or not the current active pokemon can mega evolve.

Return type:

bool

property used_tera: bool
Returns:

Whether or not the current active pokemon can terastallize

Return type:

bool

property used_z_move: bool
Returns:

Whether or not the current active pokemon can z-move.

Return type:

bool

abstract property valid_orders: Any
property wait: bool
Returns:

If True, the battle does not currently need an action from the player.

Return type:

bool

property weather: Dict[Weather, int]
Returns:

A Dict mapping the battle’s weather (if any) to its starting turn

Return type:

Dict[Weather, int]

property won: bool | None
Returns:

If the battle is finished, a boolean indicating whether the battle is won. Otherwise None.

Return type:

Optional[bool]

won_by(player_name: str)

Battle

class poke_env.battle.battle.Battle(battle_tag: str, username: str, logger: Logger, gen: int, save_replays: str | bool = False)

Bases: AbstractBattle

property active_pokemon: Pokemon | None
Returns:

The active pokemon

Return type:

Optional[Pokemon]

property all_active_pokemons: List[Pokemon | None]
Returns:

A list containing all active pokemons and/or Nones.

Return type:

List[Optional[Pokemon]]

property available_moves: List[Move]
Returns:

The list of moves the player can use during the current move request.

Return type:

List[Move]

property available_switches: List[Pokemon]
Returns:

The list of switches the player can do during the current move request.

Return type:

List[Pokemon]

property can_dynamax: bool
Returns:

Whether or not the current active pokemon can dynamax

Return type:

bool

property can_mega_evolve: bool
Returns:

Whether or not the current active pokemon can mega evolve.

Return type:

bool

property can_tera: bool
Returns:

Whether or not the current active pokemon can terastallize

Return type:

bool

property can_z_move: bool
Returns:

Whether or not the current active pokemon can z-move.

Return type:

bool

clear_all_boosts()
end_illusion(pokemon_name: str, details: str)
property force_switch: bool
Returns:

A boolean indicating whether the active pokemon is forced to switch out.

Return type:

Optional[bool]

property grounded: bool
Returns:

A boolean indicating whether the active pokemon is grounded

Return type:

bool

in_team_preview: bool
logger: Logger | None
property maybe_trapped: bool
Returns:

A boolean indicating whether the active pokemon is maybe trapped by the opponent.

Return type:

bool

property opponent_active_pokemon: Pokemon | None
Returns:

The opponent active pokemon

Return type:

Pokemon

parse_request(request: Dict[str, Any], strict_battle_tracking: bool = False)

Update the object from a request. The player’s pokemon are all updated, as well as available moves, switches and other related information (z move, mega evolution, forced switch…).

Parameters:

request (dict) – Parsed JSON request object.

rules: List[str]
switch(pokemon_str: str, details: str, hp_status: str)
property trapped: bool
Returns:

A boolean indicating whether the active pokemon is trapped, either by the opponent or as a side effect of one your moves.

Return type:

bool

property valid_orders: List[SingleBattleOrder]

Double Battle

class poke_env.battle.double_battle.DoubleBattle(battle_tag: str, username: str, logger: Logger, gen: int, save_replays: str | bool = False)

Bases: AbstractBattle

EMPTY_TARGET_POSITION = 0
OPPONENT_1_POSITION = 1
OPPONENT_2_POSITION = 2
POKEMON_1_POSITION = -1
POKEMON_2_POSITION = -2
property active_pokemon: List[Pokemon | None]
Returns:

The active pokemon, always at least one is not None

Return type:

List[Optional[Pokemon]]

property all_active_pokemons: List[Pokemon | None]
Returns:

A list containing all active pokemons and/or Nones.

Return type:

List[Optional[Pokemon]]

property available_moves: List[List[Move]]
Returns:

A list of two lists of moves the player can use during the current move request for each Pokemon.

Return type:

List[List[Move]]

property available_switches: List[List[Pokemon]]
Returns:

The list of two lists of switches the player can do during the current move request for each active pokemon

Return type:

List[List[Pokemon]]

property can_dynamax: List[bool]
Returns:

Whether or not the current active pokemon can dynamax

Return type:

List[bool]

property can_mega_evolve: List[bool]
Returns:

Whether or not either current active pokemon can mega evolve.

Return type:

List[bool]

property can_tera: List[bool]
Returns:

Whether or not the current active pokemon can terastallize. If yes, will be a PokemonType.

Return type:

List[Union[bool, PokemonType]]

property can_z_move: List[bool]
Returns:

Whether or not the current active pokemon can z-move.

Return type:

List[bool]

clear_all_boosts()
end_illusion(pokemon_name: str, details: str)
property force_switch: List[bool]
Returns:

A boolean indicating whether the active pokemon is forced to switch out.

Return type:

List[bool]

get_possible_showdown_targets(move: Move, pokemon: Pokemon, dynamax: bool = False) → List[int]

Given move of an ALLY Pokemon, returns a list of possible Pokemon Showdown targets for it. This is smart enough so that it figures whether the Pokemon is already dynamaxed.

Parameters:

  • move (Move) – Move instance for which possible targets should be returned

  • pokemon (Pokemon) – The ally using the move.

  • dynamax – whether given move also STARTS dynamax for its user

Returns:

a list of integers indicating Pokemon Showdown targets: -1, -2, 1, 2 or self.EMPTY_TARGET_POSITION that indicates “no target”

Return type:

List[int]

property grounded: List[bool]
Returns:

A boolean indicating whether the active pokemon are grounded

Return type:

List[bool]

in_team_preview: bool
logger: Logger | None
property maybe_trapped: List[bool]
Returns:

A boolean indicating whether either active pokemon is maybe trapped by the opponent.

Return type:

List[bool]

property opponent_active_pokemon: List[Pokemon | None]
Returns:

The opponent active pokemon, always at least one is not None

Return type:

List[Optional[Pokemon]]

parse_request(request: Dict[str, Any], strict_battle_tracking: bool = False)

Update the object from a request. The player’s pokemon are all updated, as well as available moves, switches and other related information (z move, mega evolution, forced switch…).

Parameters:

request (dict) – Parsed JSON request object.

property reviving: bool
Returns:

Whether or not any of the player’s Pokemon is reviving.

Return type:

bool

rules: List[str]
switch(pokemon_str: str, details: str, hp_status: str)
to_showdown_target(move: Move, target_mon: Pokemon | None) → int

Returns the correct Showdown target of the Pokemon to be targeted. It will return 0 if no target is needed or if the target_mon is not an active pokemon; this is meaningless in showdown

Parameters:

  • move (Move) – the move to be used against the target_mon

  • target_mon (as implemented in poke-env) – the Pokemon that is to be targeted

Returns:

The corresponding showdown target if needed, otherwise 0

Return type:

int

property trapped: List[bool]
Returns:

A boolean indicating whether either active pokemon is trapped by the opponent.

Return type:

List[bool]

property valid_orders: List[List[SingleBattleOrder]]

Target

This module defines the Target class, which represents the types of targets a move can have

class poke_env.battle.target.Target(value)

Bases: Enum

Enumeration, representing targets for each move in a battle.

ADJACENT_ALLY = 1
ADJACENT_ALLY_OR_SELF = 2
ADJACENT_FOE = 3
ALL = 4
ALLIES = 7
ALLY_SIDE = 8
ALLY_TEAM = 9
ALL_ADJACENT = 5
ALL_ADJACENT_FOES = 6
ANY = 10
FOE_SIDE = 11
NORMAL = 12
RANDOM_NORMAL = 13
SCRIPTED = 14
SELF = 15
static from_showdown_message(message: str)

Returns the Target object corresponding to the message.

Parameters:

message (str) – The message to convert.

Returns:

The corresponding Target object.

Return type:

Target