The player object and related subclasses

Player

This module defines a base class for players.

class poke_env.player.player.Player(account_configuration: AccountConfiguration | None = None, *, avatar: str | None = None, battle_format: str = 'gen9randombattle', log_level: int | None = None, max_concurrent_battles: int = 1, accept_open_team_sheet: bool = False, save_replays: bool | str = False, server_configuration: ServerConfiguration = ('ws://localhost:8000/showdown/websocket', 'https: //play.pokemonshowdown.com/action.php?'), start_timer_on_battle_start: bool = False, start_listening: bool = True, open_timeout: float | None = 10.0, ping_interval: float | None = 20.0, ping_timeout: float | None = 20.0, loop: AbstractEventLoop = <_UnixSelectorEventLoop running=True closed=False debug=False>, team: str | Teambuilder | None = None, strict_battle_tracking: bool = False)

Bases: ABC

Base class for players.

DEFAULT_CHOICE_CHANCE = 0.001

MESSAGES_TO_IGNORE = {'expire', 't:', 'uhtmlchange'}

async accept_challenges(opponent: str | List[str] | None, n_challenges: int, packed_team: str | None = None)

Let the player wait for challenges from opponent, and accept them.

If opponent is None, every challenge will be accepted. If opponent if a string, all challenges from player with that name will be accepted. If opponent is a list all challenges originating from players whose name is in the list will be accepted.

Up to n_challenges challenges will be accepted, after what the function will wait for these battles to finish, and then return.

Parameters:

• opponent (None, str or list of str) – Players from which challenges will be accepted.

• n_challenges (int) – Number of challenges that will be accepted

Packed_team:

Team to use. Defaults to generating a team with the agent’s teambuilder.

property accept_open_team_sheet: bool

async battle_against(*opponents: Player, n_battles: int = 1)

Make the player play n_battles against the given opponents.

This function is a wrapper around send_challenges and accept_challenges.

Parameters:

• opponents (Player) – The opponents to play against.

• n_battles (int) – The number of games to play. Defaults to 1.

property battles: Dict[str, AbstractBattle]

static choose_default_move() → DefaultBattleOrder

Returns showdown’s default move order.

This order will result in the first legal order - according to showdown’s ordering - being chosen.

abstractmethod choose_move(battle: AbstractBattle) → BattleOrder | Awaitable[BattleOrder]

Abstract method to choose a move in a battle.

Parameters:

battle (AbstractBattle) – The battle.

Returns:

The move order, or an awaitable resolving to one.

Return type:

BattleOrder or Awaitable[BattleOrder]

static choose_random_doubles_move(battle: DoubleBattle) → DoubleBattleOrder

static choose_random_move(battle: AbstractBattle) → BattleOrder

Returns a random legal move from battle.

Parameters:

battle (AbstractBattle) – The battle in which to move.

Returns:

Move order

Return type:

str

static choose_random_singles_move(battle: Battle) → SingleBattleOrder

static create_order(order: Move | Pokemon, mega: bool = False, z_move: bool = False, dynamax: bool = False, terastallize: bool = False, move_target: int = 0) → SingleBattleOrder

Formats an move order corresponding to the provided pokemon or move.

Parameters:

• order (Move or Pokemon) – Move to make or Pokemon to switch to.

• mega (bool) – Whether to mega evolve the pokemon, if a move is chosen.

• z_move (bool) – Whether to make a zmove, if a move is chosen.

• dynamax (bool) – Whether to dynamax, if a move is chosen.

• terastallize (bool) – Whether to terastallize, if a move is chosen.

• move_target (int) – Target Pokemon slot of a given move

Returns:

Formatted move order

Return type:

str

property format: str

property format_is_doubles: bool

get_next_team() → str | None

async ladder(n_games: int)

Make the player play games on the ladder.

n_games defines how many battles will be played.

Parameters:

n_games (int) – Number of battles that will be played

property logger: Logger

property n_finished_battles: int

property n_lost_battles: int

property n_tied_battles: int

property n_won_battles: int

random_teampreview(battle: AbstractBattle) → str

Returns a random valid teampreview order for the given battle.

Parameters:

battle (AbstractBattle) – The battle.

Returns:

The random teampreview order.

Return type:

str

reset_battles()

Resets the player’s inner battle tracker.

save_replay(battle_tag: str, file_path: str | Path) → Path

Saves replay html for a known battle.

Parameters:

• battle_tag (str) – The battle tag to export (with or without leading ‘>’).

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

Returns:

The written replay path.

Return type:

pathlib.Path

Raises:

KeyError – If battle_tag does not correspond to a known battle.

async send_challenges(opponent: str, n_challenges: int, to_wait: Event | None = None)

Make the player send challenges to opponent.

opponent must be a string, corresponding to the name of the player to challenge.

n_challenges defines how many challenges will be sent.

to_wait is an optional event that can be set, in which case it will be waited before launching challenges.

Parameters:

• opponent (str) – Player username to challenge.

• n_challenges (int) – Number of battles that will be started

• to_wait (Event, optional.) – Optional event to wait before launching challenges.

teampreview(battle: AbstractBattle) → str | Awaitable[str]

Returns a teampreview order for the given battle.

This order must be of the form /team TEAM, where TEAM is a string defining the team chosen by the player. Multiple formats are supported, among which ‘3461’ and ‘3, 4, 6, 1’ are correct and indicate leading with pokemon 3, with pokemons 4, 6 and 1 in the back in single battles or leading with pokemons 3 and 4 with pokemons 6 and 1 in the back in double battles.

Please refer to Pokemon Showdown’s protocol documentation for more information.

IMPORTANT: If overwriting this method, make sure to mark Pokemon selected in teampreview as such by setting their _selected_in_teampreview attribute to True. See random_teampreview implementation for an example.

Parameters:

battle (AbstractBattle) – The battle.

Returns:

The teampreview order.

Return type:

str

update_team(team: Teambuilder | str)

Updates the team used by the player.

Parameters:

team (str or Teambuilder) – The new team to use.

property username: str

property win_rate: float

Baselines

class poke_env.player.baselines.MaxBasePowerPlayer(account_configuration: AccountConfiguration | None = None, *, avatar: str | None = None, battle_format: str = 'gen9randombattle', log_level: int | None = None, max_concurrent_battles: int = 1, accept_open_team_sheet: bool = False, save_replays: bool | str = False, server_configuration: ServerConfiguration = ('ws://localhost:8000/showdown/websocket', 'https: //play.pokemonshowdown.com/action.php?'), start_timer_on_battle_start: bool = False, start_listening: bool = True, open_timeout: float | None = 10.0, ping_interval: float | None = 20.0, ping_timeout: float | None = 20.0, loop: AbstractEventLoop = <_UnixSelectorEventLoop running=True closed=False debug=False>, team: str | Teambuilder | None = None, strict_battle_tracking: bool = False)

Bases: Player

static choose_doubles_move(battle: DoubleBattle)

choose_move(battle: AbstractBattle)

Abstract method to choose a move in a battle.

Parameters:

battle (AbstractBattle) – The battle.

Returns:

The move order, or an awaitable resolving to one.

Return type:

BattleOrder or Awaitable[BattleOrder]

static choose_singles_move(battle: AbstractBattle)

class poke_env.player.baselines.PseudoBattle(battle: DoubleBattle, active_id: int, opp_id: int)

Bases: Battle

property active_pokemon

Returns:

The active pokemon

Return type:

Optional[Pokemon]

in_team_preview: bool

logger: Logger | None

property opponent_active_pokemon

Returns:

The opponent active pokemon

Return type:

Pokemon

rules: List[str]

class poke_env.player.baselines.RandomPlayer(account_configuration: AccountConfiguration | None = None, *, avatar: str | None = None, battle_format: str = 'gen9randombattle', log_level: int | None = None, max_concurrent_battles: int = 1, accept_open_team_sheet: bool = False, save_replays: bool | str = False, server_configuration: ServerConfiguration = ('ws://localhost:8000/showdown/websocket', 'https: //play.pokemonshowdown.com/action.php?'), start_timer_on_battle_start: bool = False, start_listening: bool = True, open_timeout: float | None = 10.0, ping_interval: float | None = 20.0, ping_timeout: float | None = 20.0, loop: AbstractEventLoop = <_UnixSelectorEventLoop running=True closed=False debug=False>, team: str | Teambuilder | None = None, strict_battle_tracking: bool = False)

Bases: Player

choose_move(battle: AbstractBattle) → BattleOrder

Abstract method to choose a move in a battle.

Parameters:

battle (AbstractBattle) – The battle.

Returns:

The move order, or an awaitable resolving to one.

Return type:

BattleOrder or Awaitable[BattleOrder]

class poke_env.player.baselines.SimpleHeuristicsPlayer(account_configuration: AccountConfiguration | None = None, *, avatar: str | None = None, battle_format: str = 'gen9randombattle', log_level: int | None = None, max_concurrent_battles: int = 1, accept_open_team_sheet: bool = False, save_replays: bool | str = False, server_configuration: ServerConfiguration = ('ws://localhost:8000/showdown/websocket', 'https: //play.pokemonshowdown.com/action.php?'), start_timer_on_battle_start: bool = False, start_listening: bool = True, open_timeout: float | None = 10.0, ping_interval: float | None = 20.0, ping_timeout: float | None = 20.0, loop: AbstractEventLoop = <_UnixSelectorEventLoop running=True closed=False debug=False>, team: str | Teambuilder | None = None, strict_battle_tracking: bool = False)

Bases: Player

ANTI_HAZARDS_MOVES = {'defog', 'rapidspin'}

ENTRY_HAZARDS = {'spikes': SideCondition.SPIKES, 'stealhrock': SideCondition.STEALTH_ROCK, 'stickyweb': SideCondition.STICKY_WEB, 'toxicspikes': SideCondition.TOXIC_SPIKES}

HP_FRACTION_COEFICIENT = 0.4

SPEED_TIER_COEFICIENT = 0.1

SWITCH_OUT_MATCHUP_THRESHOLD = -2

choose_move(battle: AbstractBattle)

Abstract method to choose a move in a battle.

Parameters:

battle (AbstractBattle) – The battle.

Returns:

The move order, or an awaitable resolving to one.

Return type:

BattleOrder or Awaitable[BattleOrder]

static choose_singles_move(battle: Battle) → Tuple[SingleBattleOrder, float]

static get_double_target_multiplier(battle: DoubleBattle, order: SingleBattleOrder)

Battle orders

class poke_env.player.battle_order.BattleOrder

Bases: object

abstract property message: str

class poke_env.player.battle_order.DefaultBattleOrder

Bases: SingleBattleOrder

class poke_env.player.battle_order.DoubleBattleOrder(first_order: 'SingleBattleOrder' = <factory>, second_order: 'SingleBattleOrder' = <factory>)

Bases: BattleOrder

first_order: SingleBattleOrder

static join_orders(first_orders: List[SingleBattleOrder], second_orders: List[SingleBattleOrder]) → List[DoubleBattleOrder]

property message: str

second_order: SingleBattleOrder

class poke_env.player.battle_order.ForfeitBattleOrder

Bases: BattleOrder

property message: str

class poke_env.player.battle_order.PassBattleOrder

Bases: SingleBattleOrder

class poke_env.player.battle_order.SingleBattleOrder(order: 'Union[Move, Pokemon, str]', mega: 'bool' = False, z_move: 'bool' = False, dynamax: 'bool' = False, terastallize: 'bool' = False, move_target: 'int' = 0)

Bases: BattleOrder

dynamax: bool = False

mega: bool = False

property message: str

move_target: int = 0

order: Move | Pokemon | str

terastallize: bool = False

z_move: bool = False

Utilities

This module contains utility functions and objects related to Player classes.

poke_env.player.utils.background_cross_evaluate(players: List[Player], n_challenges: int) → Future[Dict[str, Dict[str, float | None]]]

poke_env.player.utils.background_evaluate_player(player: Player, n_battles: int = 1000, n_placement_battles: int = 30) → Future[Tuple[float, Tuple[float, float]]]

async poke_env.player.utils.cross_evaluate(players: List[Player], n_challenges: int) → Dict[str, Dict[str, float | None]]

async poke_env.player.utils.evaluate_player(player: Player, n_battles: int = 1000, n_placement_battles: int = 30) → Tuple[float, Tuple[float, float]]

Estimate player strength.

This functions calculates an estimate of a player’s strength, measured as its expected performance against a random opponent in a gen 8 random battle. The returned number can be interpreted as follows: a strength of k means that the probability of the player winning a gen 8 random battle against a random player is k times higher than the probability of the random player winning.

The function returns a tuple containing the best guess based on the played games as well as a tuple describing a 95% confidence interval for that estimated strength.

The actual evaluation can be performed against any baseline player for which an accurate strength estimate is available. This baseline is determined at the start of the process, by playing a limited number of placement battles and choosing the opponent closest to the player in terms of performance.

Parameters:

• player (Player) – The player to evaluate.

• n_battles (int) – The total number of battle to perform, including placement battles.

• n_placement_battles (int) – Number of placement battles to perform per baseline player.

Raises:

ValueError if the results are too extreme to be interpreted.

Raises:

AssertionError if the player is not configured to play gen8battles or the selected number of games to play it too small.

Returns:

A tuple containing the estimated player strength and a 95% confidence interval

Return type:

tuple of float and tuple of floats