The Showdown Battle Message

The BattleMessage object

The base class for all specific BattleMessage subclasses to be built from.

When parsing a string battle message, you should directly use this class's from_message function, which will auto-identify which subclass (if any) the given string belongs to.

Across all BattleMessages, you will be able to access both BMTYPE and BATTLE_MESSAGE, though you shouldn't need to access BATTLE_MESSAGE directly. (If you do, then we must be missing some data that exists in the raw string)

ATTRIBUTE	DESCRIPTION
BMTYPE	The message type of this battle message. Must be a vaild showdown battle message. TYPE: BMType
BATTLE_MESSAGE	The raw message line as sent from showdown. Shouldn't need to be used but worth keeping. TYPE: str
ERR_STATE	The error type of this battle message if it failed to parse TYPE: Optional[Literal['UNKNOWN_BMTYPE', 'MISSING_DICT_CLASS', 'IMPLEMENTATION_NOT_READY', 'PARSE_ERROR']]

from_message(battle_message) staticmethod

Create a specific BattleMessage object from a raw message.

For example, given a message '|faint|p2a: Umbreon', this will create a new BattleMessage_faint with fields extracted from the text properly.

BattleMessage Subclasses

Contains BaseModels for BattleMessage parsing and processing.

Remember to use BattleMessage.from_message directly, unless you are building test cases where you want to assert that a given message leads to a certain subclass of BattleMessage. from_message will auto-detect which BMType the given message corresponds to, and return the associated subclass (or an error detailing what went wrong) for you.

BattleMessage_player

Message containing player information.

ATTRIBUTE	DESCRIPTION
PLAYER	The player id of this player TYPE: str
USERNAME	The username of the player TYPE: str
AVATAR	Either a number id of the user's avatar or a custom value TYPE: Union[int, str]
RATING	The elo of the player in the current format, if applicable TYPE: Optional[int]

Use Case(s)

• To communicate player username/avatar/rating information.

Message Format(s)

• |player|PLAYER|USERNAME|AVATAR|RATING

Input Example(s)

• |player|p1|colress-gpt-test1|colress|1520
• |player|p2|colress-gpt-test2|265|1229

BattleMessage_teamsize

Message containing teamsize information.

ATTRIBUTE	DESCRIPTION
PLAYER	The player id of this player TYPE: str
NUMBER	The number of pokemon your opponent has. TYPE: int

Use Case(s)

• To communicate player team size.

Message Format(s)

• |teamsize|PLAYER|NUMBER

Input Example(s)

• |teamsize|p1|6

BattleMessage_gametype

Message containing gametype information.

ATTRIBUTE	DESCRIPTION
GAMETYPE	The gametype of this format TYPE: Literal['singles', 'doubles', 'triples', 'multi', 'freeforall']

Use Case(s)

• To communicate the game type (singles, doubles, triples, etc.)

Message Format(s)

• |gametype|GAMETYPE

Input Example(s)

• |gametype|singles

BattleMessage_gen

Message containing gen information.

ATTRIBUTE	DESCRIPTION
GENNUM	The integer generation number of this format TYPE: DexGen.ValueType

Use Case(s)

• To communicate the generation number.

Message Format(s)

• |gen|GENNUM

Input Example(s)

• |gen|5

BattleMessage_tier

Message containing format information.

ATTRIBUTE	DESCRIPTION
FORMATNAME	The game format of this match TYPE: str

Use Case(s)

• To communicate the format of this battle.

Message Format(s)

• |tier|FORMATNAME

Input Example(s)

• |tier|[Gen 5] Random Battle

BattleMessage_rated

Message containing rating information.

ATTRIBUTE	DESCRIPTION
MESSAGE	An optional message used in tournaments TYPE: Optional[str]

Use Case(s)

• To communicate any extra rules/clauses for this format.

Message Format(s)

• |rated|MESSAGE

Input Example(s)

• |rated|

BattleMessage_rule

Message containing extra rule information.

ATTRIBUTE	DESCRIPTION
RULE	The name of the rule TYPE: str
DESCRIPTION	A description of this rule TYPE: str

Use Case(s)

• To communicate any extra rules/clauses for this format.

Message Format(s)

• |rule|RULE: DESCRIPTION

Input Example(s)

• |rule|HP Percentage Mod: HP is shown in percentages

BattleMessage_clearpoke

Message containing a clearpoke notification.

Use Case(s)

• To signal that teampreview is starting.

Message Format(s)

• |clearpoke

Input Example(s)

• |clearpoke

BattleMessage_poke

Message containing base-forme-only information about a pokemon, presented in teampreview.

ATTRIBUTE	DESCRIPTION
PLAYER	The player id of this player TYPE: str
SPECIES	The forme-less species for this pokemon TYPE: DexPokemon.ValueType
LEVEL	The level of this pokemon TYPE: int
GENDER	The gender of this pokemon TYPE: Optional[Literal['M', 'F']]
SHINY	Whether the pokemon is shiny or not TYPE: bool
TERA	If this pokemon is teratyped, the string type of the new type. Else None. TYPE: Optional[DexType.ValueType]
HAS_ITEM	Whether or not the pokemon is holding an item TYPE: bool

Use Case(s)

• To communicate base-forme, simple pokemon information for teampreview

Message Format(s)

• |poke|PLAYER|DETAILS|ITEM

Input Example(s)

• |poke|p1|Metagross, L80|item

BattleMessage_start

Message signaling the start of a battle.

Use Case(s)

• To communicate that the battle has started (teampreview is over)

Message Format(s)

• |start

Input Example(s)

• |start

BattleMessage_teampreview

Message signaling to make a teampreview team-order decision.

Use Case(s)

• To communicate that the user needs to select a team-order.

Message Format(s)

• |teampreview

Input Example(s)

• |teampreview

BattleMessage_empty

Completely blank message.

Use Case(s)

• To separate sections in a battle log

Message Format(s)

• |

Input Example(s)

• |

BattleMessage_request

Message communicating options the user has in an upcoming choice.

ATTRIBUTE	DESCRIPTION
REQUEST_TYPE	Which type of request this request is between TEAMPREVIEW, ACTIVE, and FORCESWITCH TYPE: Literal['TEAMPREVIEW', 'ACTIVE', 'FORCESWITCH', 'WAIT']
USERNAME	The player's username TYPE: str
PLAYER	The player id of this player TYPE: str
RQID	The id number of this request, for the purpose of an undo function TYPE: Optional[int]
POKEMON	The pokemon details for each pokemon in this player's side TYPE: List[RequestPoke]
ACTIVE_OPTIONS	A list of actions available for each active pokemon. Will be None if switch/teampreview TYPE: Optional[List[ActiveOption]]
FORCESWITCH_SLOTS	A list of bool for each slot whether they are being forced to switch TYPE: Optional[List[bool]]

Use Case(s)

• To inform the user about their team so that a team-order decision can be made.
• To inform the user about their available moves/switches so that a standard decision can be made.
• To request the user to switch out a Pokemon due to a forced operation (fainted/forced out).
• To inform the user that their opponent is making a decision and that the user has to wait for them.

Message Format(s)

• |request|REQUEST_JSON

Input Example(s)

• See logs for examples, there are a lot of variations.

Tips

This does not necessarily mean it is time for the user to respond to a choice, as teampreview and move requests are sent before the details of the previous turn are sent, and thus you should wait until it is the correct time to send your decision.

For FORCESWITCH requests, however, a decision should be sent once you receive this message.

BattleMessage_inactive

Message communicating that the inactivity timer has been set.

ATTRIBUTE	DESCRIPTION
MESSAGE	A message related to the battle timer notification TYPE: str

Use Case(s)

• To signal that there is a time-limit for descisions to be made.

Message Format(s)

• |inactive|MESSAGE

Input Example(s)

• TODO

BattleMessage_inactiveoff

Message communicating that the inactivity timer has been turned off.

ATTRIBUTE	DESCRIPTION
MESSAGE	A message related to the battle timer notification TYPE: str

Use Case(s)

• To signal that there is no longer a time-limit for descisions to be made.

Message Format(s)

• |inactiveoff|MESSAGE

Input Example(s)

• TODO

BattleMessage_upkeep

Message communicating upkeep notice.

Use Case(s)

• To signal that the upkeep stage has happened

Message Format(s)

• |upkeep

Input Example(s)

• |upkeep

BattleMessage_turn

Message communicating that a turn has begun, and that move choices should be made.

ATTRIBUTE	DESCRIPTION
NUMBER	The current turn number TYPE: int

Use Case(s)

• To signal to the players to make a move.

Message Format(s)

• |turn|NUMBER

Input Example(s)

• |turn|2

BattleMessage_win

Message communicating that a player has won the battle.

ATTRIBUTE	DESCRIPTION
USERNAME	The username of the winning player TYPE: str

Use Case(s)

• To signal which player has won.

Message Format(s)

• |win|USER

Input Example(s)

• |win|colress-gpt-test2

BattleMessage_tie

Message communicating that neither player has won the battle.

Use Case(s)

• To signal the battle has ended in a tie

Message Format(s)

• |tie

Input Example(s)

• |tie

BattleMessage_expire

Message communicating that the battle has ended due to mutual inactivity.

Use Case(s)

• To signal the battle has ended due to mutual inactivity

Message Format(s)

• |expire|

Input Example(s)

• |expire|

BattleMessage_t

Message communicating the current timestamp.

ATTRIBUTE	DESCRIPTION
TIMESTAMP	The time of this turn as a datetime (conv from unix seconds) TYPE: datetime

Use Case(s)

• Gives current timestamp of this set of messages

Message Format(s)

• |t:|TIMESTAMP

Input Example(s)

• |t:|1696832299

BattleMessage_move

Message communicating that a pokemon successfully used a move.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon using the move TYPE: PokemonIdentifier
MOVE	The name of the move used TYPE: DexMove.ValueType
TARGET	The primary target of this move. This can be None when applicable TYPE: Optional[PokemonIdentifier]
EFFECT	An optional effect that the move is taken from (Magic bounce, Sleep Talk, etc) TYPE: Optional[Effect]

Use Case(s)

• Communicating which move was used, including source/target information.

Message Format(s)

• |move|POKEMON|MOVE|TARGET
• |move|POKEMON|MOVE|TARGET|[from]
• TODO: Add more

Input Example(s)

• |move|p1a: Sceptile|Acrobatics|p2a: Espeon
• |move|p1a: Kangaskhan|Fake Out||[still]
• TODO: Add more

BattleMessage_switch

Message communicating that a pokemon has switched in.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon swapping in, potentially replacing the slot TYPE: PokemonIdentifier
SPECIES	The species for this pokemon, including forme TYPE: DexPokemon.ValueType
LEVEL	The level of this pokemon TYPE: int
GENDER	The gender of this pokemon TYPE: Optional[Literal['M', 'F']]
SHINY	Whether the pokemon is shiny or not TYPE: bool
TERA	If this pokemon is teratyped, the string type of the new type. Else None. TYPE: Optional[str]
CUR_HP	The current HP of the pokemon TYPE: int
MAX_HP	The maximum HP of the pokemon TYPE: int
STATUS	The status of the pokemon. Can be None if there is no status TYPE: Optional[str]

Use Case(s)

• Communicating which pokemon switched in, as well as info about the pokemon.

Message Format(s)

• |switch|POKEMON|DETAILS|HP STATUS

Input Example(s)

• |switch|p2a: Toxicroak|Toxicroak, L81, F|100/100

BattleMessage_drag

Message communicating that a pokemon has switched in.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon being dragged in TYPE: PokemonIdentifier
SPECIES	The species for this pokemon, including forme TYPE: DexPokemon.ValueType
LEVEL	The level of this pokemon TYPE: int
GENDER	The gender of this pokemon TYPE: Optional[Literal['M', 'F']]
SHINY	Whether the pokemon is shiny or not TYPE: bool
TERA	If this pokemon is teratyped, the string type of the new type. Else None. TYPE: Optional[str]
CUR_HP	The current HP of the pokemon TYPE: int
MAX_HP	The maximum HP of the pokemon TYPE: int
STATUS	The status of the pokemon. Can be None if there is no status TYPE: Optional[str]

Use Case(s)

• Communicating which pokemon was dragged in, as well as info about the pokemon.

Message Format(s)

• |drag|POKEMON|DETAILS|HP STATUS

Input Example(s)

• TODO

BattleMessage_detailschange

Message communicating that a pokemon has changed formes in a permanent way.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon changing formes TYPE: PokemonIdentifier
SPECIES	The species for this pokemon, including forme TYPE: DexPokemon.ValueType
LEVEL	The level of this pokemon TYPE: int
GENDER	The gender of this pokemon TYPE: Optional[Literal['M', 'F']]
SHINY	Whether the pokemon is shiny or not TYPE: bool
TERA	If this pokemon is teratyped, the string type of the new type. Else None. TYPE: Optional[str]
CUR_HP	The current HP of the pokemon TYPE: Optional[str]
MAX_HP	The maximum HP of the pokemon TYPE: Optional[str]
STATUS	The status of the pokemon. Can be None if there is no status TYPE: Optional[str]

Use Case(s)

• Communicating that a certain pokemon changed forme.

Message Format(s)

• |detailschange|POKEMON|DETAILS

Input Example(s)

• TODO

BattleMessage_replace

Message communicating that a pokemon has been replaced (Zoroark illusion ability).

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon being revealed (Zoroark) TYPE: PokemonIdentifier
SPECIES	The species for this pokemon, including forme TYPE: DexPokemon.ValueType
LEVEL	The level of this pokemon TYPE: int
GENDER	The gender of this pokemon TYPE: Optional[Literal['M', 'F']]
SHINY	Whether the pokemon is shiny or not TYPE: bool
TERA	If this pokemon is teratyped, the string type of the new type. Else None. TYPE: Optional[str]
CUR_HP	The current HP of the pokemon TYPE: Optional[str]
MAX_HP	The maximum HP of the pokemon TYPE: Optional[str]
STATUS	The status of the pokemon. Can be None if there is no status TYPE: Optional[str]

Use Case(s)

• Communicating that a certain pokemon has been replaced.

Message Format(s)

• |replace|POKEMON|DETAILS

Input Example(s)

• TODO

BattleMessage_swap

Message communicating that a certain active slot has had its pokemon swapped with another.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon being swapped before swapping TYPE: PokemonIdentifier
POSITION	The slot that this Pokemon is being swapped to, as an integer TYPE: int
EFFECT	An optional effect explaining what caused the swapping TYPE: Optional[Effect]

Use Case(s)

• Communicating that two pokemon have swapped active slots.

Message Format(s)

• |swap|POKEMON|POSITION
• |swap|POKEMON|POSITION|[from]

Input Example(s)

• TODO

BattleMessage_cant

Message communicating that a pokemon was unable to do something.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that was unable to act TYPE: PokemonIdentifier
REASON	The reason that the pokemon was unable to do what it was trying to do TYPE: str
MOVE	The move being used that was unable to be used. None if not applicable TYPE: Optional[str]

Use Case(s)

• Communicating that a pokemon failed to do something, with the reason it failed.

Message Format(s)

• |cant|POKEMON|REASON|MOVE

Input Example(s)

• TODO

BattleMessage_faint

Message communicating that a pokemon has fainted.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that fainted TYPE: PokemonIdentifier

Use Case(s)

• Communicating that a pokemon fainted.

Message Format(s)

• |faint|POKEMON

Input Example(s)

• TODO

BattleMessage_fail

Message communicating that a pokemon has failed to do something.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that failed to do something TYPE: PokemonIdentifier
EFFECT	The effect causing/explaining the fail. Is Optional since sometimes it fails with no explanation TYPE: Optional[Effect]

Use Case(s)

• Communicating that a pokemon failed to do something
• Communicate what effect caused the failure
• Communicate if a status caused the failure.

Message Format(s)

• |-fail|POKEMON
• |-fail|POKEMON|EFFECT
• |-fail|POKEMON|STATUS

Input Example(s)

• TODO

BattleMessage_block

Message communicating that a pokemon has blocked an opposing action.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that was targeted but blocked something TYPE: PokemonIdentifier
EFFECT	The reason this was able to be blocked TYPE: Effect

Use Case(s)

• Communicating that a pokemon was able to block some other action.

Message Format(s)

• |-block|POKEMON|EFFECT

Input Example(s)

• TODO

BattleMessage_notarget

Message communicating that no target was available at move-use time.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that had no target available. TYPE: Optional[PokemonIdentifier]

Use Case(s)

• Communicating that a pokemon had no target available.

Message Format(s)

• |-notarget|POKEMON
• |-notarget

Input Example(s)

• TODO

BattleMessage_miss

Message communicating that a given source pokemon missed its action.

ATTRIBUTE	DESCRIPTION
SOURCE	The pokemon missing the attack TYPE: PokemonIdentifier
TARGET	The pokemon evading (If applicable, can be None) TYPE: Optional[PokemonIdentifier]

Use Case(s)

• Communicating that a pokemon missed.
• Communicating which pokemon was targeted but avoided the action.

Message Format(s)

• |-miss|SOURCE
• |-miss|SOURCE|TARGET

Input Example(s)

• TODO

BattleMessage_damage

Message communicating that a pokemon has taken damage.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon being hurt TYPE: PokemonIdentifier
CUR_HP	The current HP of the pokemon TYPE: int
MAX_HP	The maximum HP of the pokemon. None if the pokemon is fainted TYPE: Optional[int]
STATUS	The status of the pokemon. Can be None if there is no status TYPE: Optional[str]
EFFECT	The reason this damage was dealt, if not from a move TYPE: Optional[Effect]

Use Case(s)

• Communicating that a pokemon took damage in some way.

Message Format(s)

• |-damage|POKEMON|HP STATUS

Input Example(s)

• TODO

BattleMessage_heal

Message communicating that a pokemon has healed some health.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon being healed TYPE: PokemonIdentifier
CUR_HP	The current HP of the pokemon TYPE: int
MAX_HP	The maximum HP of the pokemon TYPE: int
STATUS	The status of the pokemon. Can be None if there is no status TYPE: Optional[str]
EFFECT	The reason this health was healed, if not from a move TYPE: Optional[Effect]

Use Case(s)

• Communicating that a pokemon healed in some way.

Message Format(s)

• |-heal|POKEMON|HP STATUS

Input Example(s)

• TODO

BattleMessage_sethp

Message communicating that a pokemon has an exact hp amount.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon getting the HP set TYPE: PokemonIdentifier
CUR_HP	The current HP of the pokemon TYPE: int
MAX_HP	The maximum HP of the pokemon TYPE: int
STATUS	The status of the pokemon. Can be None if there is no status TYPE: Optional[str]
EFFECT	The reason this health was healed TYPE: Optional[Effect]

Use Case(s)

• Communicating that a pokemon had its health directly set.

Message Format(s)

• |-sethp|POKEMON|HP STATUS|EFFECT

Input Example(s)

• TODO

BattleMessage_status

Message communicating that a pokemon has gained a status.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon gaining the status TYPE: PokemonIdentifier
STATUS	The status being gained TYPE: DexStatus.ValueType

Use Case(s)

• Communicating that a pokemon has gained a status condition.

Message Format(s)

• |-status|POKEMON|STATUS

Input Example(s)

• TODO

BattleMessage_curestatus

Message communicating that a pokemon has lost a status.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon losing the status TYPE: PokemonIdentifier
STATUS	The status being lost TYPE: DexStatus.ValueType

Use Case(s)

• Communicating that a pokemon has lost a status condition.

Message Format(s)

• |-curestatus|POKEMON|STATUS

Input Example(s)

• TODO

BattleMessage_cureteam

Message communicating that a team has been cured of all status conditions.

ATTRIBUTE	DESCRIPTION
EFFECT	The effect causing the team to be healed TYPE: Effect

Use Case(s)

• Communicating that all pokemon have been cured.

Message Format(s)

• |-cureteam|POKEMON|EFFECT

Input Example(s)

• TODO

BattleMessage_boost

Message communicating that a pokemon has gained some stat boost.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon getting the boost TYPE: PokemonIdentifier
STAT	Which stat is being boosted TYPE: PokeStat
AMOUNT	By how much this stat is being boosted, as an integer. Can be 0 if at cap TYPE: int

Use Case(s)

• Communicating that a pokemon received a single stat boost.

Message Format(s)

• |-boost|POKEMON|STAT|AMOUNT

Input Example(s)

• TODO

BattleMessage_unboost

Message communicating that a pokemon has had some stat lowered.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon getting the boost TYPE: PokemonIdentifier
STAT	Which stat is being boosted TYPE: PokeStat
AMOUNT	By how much this stat is being unboosted, as an integer. Can be 0 if at cap TYPE: int

Use Case(s)

• Communicating that a pokemon received a single stat unboost.

Message Format(s)

• |-unboost|POKEMON|STAT|AMOUNT

Input Example(s)

• TODO

BattleMessage_setboost

Message communicating that a pokemon has had some stat set to a certain boost value.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon getting the boost TYPE: PokemonIdentifier
STAT	Which stat is being boosted TYPE: PokeStat
AMOUNT	The new value being assigned for this stat boost TYPE: int

Use Case(s)

• Communicating that a pokemon received a set stat boost value.

Message Format(s)

• |-setboost|POKEMON|STAT|AMOUNT

Input Example(s)

• TODO

BattleMessage_swapboost

Message communicating that two specific pokemon have had their stat boosts switched.

Warning

Not yet implemented!

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon getting the boost TYPE: str

Use Case(s)

• Communicating that two pokemon have had their respective stat boosts swapped.

Message Format(s)

• |-swapboost|SOURCE|TARGET|STATS

Input Example(s)

• TODO

BattleMessage_invertboost

Message communicating that a pokemon has had its stat boosts inverted.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon getting the boost inverted TYPE: PokemonIdentifier

Use Case(s)

• Communicating that a pokemon has had its stat boosts inverted.

Message Format(s)

• |-invertboost|POKEMON

Input Example(s)

• TODO

BattleMessage_clearboost

Message communicating that a pokemon has had its stat boosts cleared.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that had its stat boosts cleared. TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has had its stat boosts cleared.

Message Format(s):

• |-clearboost|POKEMON

Input Example(s)

• |-clearboost|p1a: Pikachu

BattleMessage_clearallboost

Message communicating that all pokemon have had their stat boosts cleared.

Use Case(s):

• Communicating that all pokemon have had their stat boosts cleared.

Message Format(s):

• |-clearallboost

Input Example(s)

• |-clearallboost

BattleMessage_clearpositiveboost

Message communicating that a pokemon has had its positive stat boosts cleared.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that had its positive stat boosts cleared. TYPE: PokemonIdentifier
EFFECT	The effect causing this positive boost clearance TYPE: Effect

Use Case(s):

• Communicating that a pokemon has had its positive stat boosts cleared.

Message Format(s):

• |-clearpositiveboost|TARGET|EFF_SOURCE|EFFECT

Input Example(s)

• TODO

BattleMessage_clearnegativeboost

Message communicating that a pokemon has had its negative stat boosts cleared.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that had its negative stat boosts cleared. TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has had its negative stat boosts cleared.

Message Format(s):

• |-clearnegativeboost|POKEMON

Input Example(s)

• TODO

BattleMessage_copyboost

Message communicating that a pokemon has had its stat boosts copied.

Warning

Not yet implemented!

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that had its stat boosts copied. TYPE: str

Use Case(s):

• Communicating that a pokemon has had its stat boosts copied.

Message Format(s):

• |-copyboost|SOURCE|TARGET

Input Example(s)

• TODO

BattleMessage_weather

Message communicating that the weather has changed.

ATTRIBUTE	DESCRIPTION
WEATHER	The weather being set TYPE: DexWeather.ValueType

Use Case(s):

• Communicating that the weather has changed.

Message Format(s):

• |-weather|WEATHER|EFFECT

Input Example(s)

• TODO

BattleMessage_fieldstart

Message communicating that a field condition has started.

ATTRIBUTE	DESCRIPTION
EFFECT	The effect starting for the field. TYPE: Effect

Use Case(s):

• Communicating that a field condition has started.

Message Format(s):

• |-fieldstart|CONDITION

Input Example(s)

• TODO

BattleMessage_fieldend

Message communicating that a field condition has ended.

ATTRIBUTE	DESCRIPTION
EFFECT	The effect ending for the field. TYPE: Effect

Use Case(s):

• Communicating that a field condition has ended.

Message Format(s):

• |-fieldend|CONDITION

Input Example(s)

• TODO

BattleMessage_sidestart

Message communicating that a side condition has started.

ATTRIBUTE	DESCRIPTION
PLAYER	The player id of the impacted player TYPE: str
CONDITION	The field condition starting TYPE: str

Use Case(s):

• Communicating that a side condition has started.

Message Format(s):

• |-sidestart|SIDE|CONDITION

Input Example(s)

• TODO

BattleMessage_sideend

Message communicating that a side condition has ended.

ATTRIBUTE	DESCRIPTION
PLAYER	The player id of the impacted player TYPE: str
CONDITION	The field condition starting TYPE: str
EFFECT	The effect that is causing the conditon to end TYPE: Optional[Effect]

Use Case(s):

• Communicating that a side condition has ended.

Message Format(s):

• |-sideend|SIDE|CONDITION
• |-sideend|SIDE|CONDITION|[from]
• |-sideend|SIDE|CONDITION|[of]

Input Example(s)

• TODO

BattleMessage_swapsideconditions

Message communicating that a side condition has been swapped.

Use Case(s):

• Communicating that a side condition has been swapped.

Message Format(s):

• |-swapsideconditions

Input Example(s)

• TODO

BattleMessage_volstart

Message communicating that a volatile effect has started.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon this volatile effect is started for TYPE: PokemonIdentifier
EFFECT	The effect that caused this volatile status TYPE: Optional[Effect]

Use Case(s):

• Communicating that a volatile effect has started.

Message Format(s):

• |-start|POKEMON|VOLATILE
• |-start|POKEMON|MOVE
• |-start|POKEMON|MOVE|MOVE
• |-start|POKEMON|MOVE|[from]
• |-start|POKEMON|MOVE|[from]|[of]
• |-start|POKEMON|typechange|TYPE
• |-start|POKEMON|typechange|TYPE|[from]
• |-start|POKEMON|typechange|TYPE|[from]|[of]

Input Example(s)

• TODO

BattleMessage_volend

Message communicating that a volatile effect has ended.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon this volatile effect is ended for TYPE: PokemonIdentifier
EFFECT	The effect that caused this volatile status TYPE: Effect
SILENT	Whether this message is silent or not TYPE: bool

Use Case(s):

• Communicating that a volatile effect has ended.

Message Format(s):

• |-end|POKEMON|EFFECT

Input Example(s)

• TODO

BattleMessage_crit

Message communicating that a pokemon has had a critical hit.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that had a critical hit TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has had a critical hit.

Message Format(s):

• |-crit|POKEMON

Input Example(s)

• TODO

BattleMessage_supereffective

Message communicating that a pokemon has been hit super effectively.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that was hit super effectively TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has been hit super effectively.

Message Format(s):

• |-supereffective|POKEMON

Input Example(s)

• TODO

BattleMessage_resisted

Message communicating that a pokemon has resisted an attack.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that resisted the attack TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has resisted an attack.

Message Format(s):

• |-resisted|POKEMON

Input Example(s)

• TODO

BattleMessage_immune

Message communicating that a pokemon has been immune to an attack.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that was immune to the attack TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has been immune to an attack.

Message Format(s):

• |-immune|POKEMON

Input Example(s)

• TODO

BattleMessage_item

Message communicating that a pokemon has had its item revealed.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon whose item is revealed TYPE: PokemonIdentifier
ITEM	The item being revealed TYPE: DexItem.ValueType
EFFECT	The effect that revealed the item, if applicable. Not used when auto-revealed (air balloon) TYPE: Optional[Effect]

Use Case(s):

• Communicating that a pokemon has had its item revealed.

Message Format(s):

• |-item|POKEMON|ITEM
• |-item|POKEMON|ITEM|[from]EFFECT

Input Example(s)

• TODO

BattleMessage_enditem

Message communicating that a pokemon has had its item destroyed.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon whose item is destroyed TYPE: PokemonIdentifier
ITEM	The item being destroyed TYPE: DexItem.ValueType
EFFECT	The effect that destroyed the item, if applicable. TYPE: Optional[Effect]

Use Case(s):

• Communicating that a pokemon has had its item destroyed.

Message Format(s):

• |-enditem|POKEMON|ITEM
• |-enditem|POKEMON|ITEM|[from]EFFECT

Input Example(s)

• TODO

BattleMessage_ability

Message communicating that a pokemon has had its ability revealed.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon whose ability is revealed TYPE: PokemonIdentifier
ABILITY	The ability being revealed TYPE: DexAbility.ValueType
EFFECT	The effect that revealed the ability, if applicable. TYPE: Optional[Effect]

Use Case(s):

• Communicating that a pokemon has had its ability revealed.

Message Format(s):

• |-ability|POKEMON|ABILITY
• |-ability|POKEMON|ABILITY|[from] EFFECT
• |-ability|POKEMON|ABILITY|[from] EFFECT|[of] POKEMON

Input Example(s)

• TODO

BattleMessage_endability

Message communicating that a pokemon has had its ability suppressed.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon whose ability is suppressed TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has had its ability suppressed.

Message Format(s):

• |-endability|POKEMON

Input Example(s)

• TODO

BattleMessage_transform

Message communicating that a pokemon has transformed into another pokemon.

ATTRIBUTE	DESCRIPTION
SOURCE	The pokemon transforming TYPE: PokemonIdentifier
TARGET	The pokemon it's transforming into TYPE: PokemonIdentifier
EFFECT	The optional effect explaining the transformation TYPE: Optional[Effect]

Use Case(s):

• Communicating that a pokemon has transformed into another pokemon.

Message Format(s):

• |-transform|SOURCE|TARGET|
• |-transform|SOURCE|TARGET|[from]

Input Example(s)

• TODO

BattleMessage_mega

Message communicating that a pokemon has mega evolved.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that mega evolved TYPE: PokemonIdentifier
BASE_SPECIES	The base species of the pokemon that is mega evolving TYPE: DexPokemon.ValueType
MEGA_STONE	The mega stone that is being used TYPE: DexItem.ValueType

Use Case(s):

• Communicating that a pokemon has mega evolved.

Message Format(s):

• |-mega|POKEMON|BASE_SPECIES|MEGASTONE

Input Example(s)

• |-mega|p1a: Absol|Absol|Absolite

BattleMessage_primal

Message communicating that a pokemon has gone primal.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon going primal TYPE: PokemonIdentifier
ITEM	The held item that is being used TYPE: DexItem.ValueType

Use Case(s):

• Communicating that a pokemon has gone primal.

Message Format(s):

• |-primal|POKEMON|ITEM

Input Example(s)

• TODO

BattleMessage_burst

Message communicating that a pokemon has burst.

Warning

Not implemented yet.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that burst TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has burst.

Message Format(s):

• |-burst|POKEMON|SPECIES|ITEM

Input Example(s)

• TODO

BattleMessage_zpower

Message communicating that a pokemon has used a Z move.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon using the Z move TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon has used a Z move.

Message Format(s):

• |-zpower|POKEMON

Input Example(s)

• TODO

BattleMessage_zbroken

Message communicating that a pokemon's Z move is over.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon whose Z move is over TYPE: PokemonIdentifier

Use Case(s):

• Communicating that a pokemon's Z move is over.

Message Format(s):

• |-zbroken|POKEMON

Input Example(s)

• TODO

BattleMessage_activate

Message communicating that a pokemon has activated an effect.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon activating the effect TYPE: PokemonIdentifier
EFFECT	The effect being activated TYPE: Effect

Use Case(s):

• Communicating that a pokemon has activated an effect.

Message Format(s):

• |-activate|POKEMON|EFFECT
• |-activate|POKEMON|VOLATILE
• |-activate|POKEMON|MOVE|EFFECT
• |-activate|POKEMON|ABILITY|EFFECT
• |-activate|POKEMON|ITEM|EFFECT

Input Example(s)

• TODO

BattleMessage_hint

Message communicating that a hint has been sent to the player.

ATTRIBUTE	DESCRIPTION
MESSAGE	The message sent to you as a hint TYPE: str

Use Case(s):

• Communicating that a hint has been sent to the player.

Message Format(s):

• |-hint|MESSAGE

Input Example(s)

• TODO

BattleMessage_center

Message communicating that the pokemon in a triple battle have been centered.

Use Case(s):

• Communicating that the pokemon in a triple battle have been centered.

Message Format(s):

• |-center

Input Example(s)

• TODO

BattleMessage_message

Message communicating that a message has been sent.

ATTRIBUTE	DESCRIPTION
MESSAGE	The message sent as part of this notification TYPE: str

Use Case(s):

• Communicating that a message has been sent.

Message Format(s):

• |-message|MESSAGE

Input Example(s)

• TODO

BattleMessage_combine

Message communicating that two moves have been combined.

Use Case(s):

• Communicating that two moves have been combined.

Message Format(s):

• |-combine

Input Example(s)

• TODO

BattleMessage_waiting

Message communicating that a pokemon is waiting for the target.

Warning

Not implemented yet.

ATTRIBUTE	DESCRIPTION
POKEMON	The main pokemon identifier relevant TYPE: str

Use Case(s):

• Communicating that a pokemon is waiting for the target.

Message Format(s):

• |-waiting|SOURCE|TARGET

Input Example(s)

• TODO

BattleMessage_prepare

Message communicating that a pokemon is preparing a move.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon preparing the move TYPE: PokemonIdentifier
MOVE	The move being prepared TYPE: DexMove.ValueType

Use Case(s):

• Communicating that a pokemon is preparing a move.

Message Format(s):

• |-prepare|POKEMON|MOVE

Input Example(s)

• TODO

BattleMessage_mustrecharge

Message communicating that a pokemon must recharge.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon that must recharge TYPE: str

Use Case(s):

• Communicating that a pokemon must recharge.

Message Format(s):

• |-mustrecharge|POKEMON

Input Example(s)

• TODO

BattleMessage_nothing

Message communicating that nothing happened.

Use Case(s):

• Communicating that nothing happened.

Message Format(s):

• |-nothing

Input Example(s)

• |-nothing

BattleMessage_hitcount

Message communicating that a pokemon has been hit multiple times.

ATTRIBUTE	DESCRIPTION
POKEMON	The Pokemon being hit multiple times. Can be slotless TYPE: PokemonIdentifier
NUM	The number of hits as an integer TYPE: int

Use Case(s):

• Communicating that a pokemon has been hit multiple times.

Message Format(s):

• |-hitcount|POKEMON|NUM

Input Example(s)

• TODO

BattleMessage_singlemove

Message communicating that a pokemon has used a single move.

ATTRIBUTE	DESCRIPTION
POKEMON	The Pokemon using this single move TYPE: PokemonIdentifier
MOVE	The move being used TYPE: DexMove.ValueType

Use Case(s):

• TODO

Message Format(s):

• |-singlemove|POKEMON|MOVE

Input Example(s)

• TODO

BattleMessage_singleturn

Message communicating that a pokemon has used a single turn move.

ATTRIBUTE	DESCRIPTION
POKEMON	The Pokemon using this single move TYPE: PokemonIdentifier
MOVE	The move being used TYPE: DexMove.ValueType

Use Case(s):

• Communicating that a pokemon has used a single turn move.

Message Format(s):

• |-singleturn|POKEMON|MOVE

Input Example(s)

• TODO

BattleMessage_formechange

Message communicating that a pokemon has changed formes.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon changing formes in some temporary way TYPE: PokemonIdentifier
SPECIES	The species for this pokemon, including forme TYPE: DexPokemon.ValueType
EFFECT	Optionally, what caused the formechange TYPE: Optional[Effect]

Use Case(s):

• Communicating that a pokemon has changed formes.

Message Format(s):

• |-formechange|POKEMON|SPECIES

Input Example(s)

• TODO

BattleMessage_terastallize

Message communicating that a pokemon has terastallized.

ATTRIBUTE	DESCRIPTION
POKEMON	The pokemon doing the terastallization TYPE: PokemonIdentifier
TYPE	The type being terastallized TYPE: DexType.ValueType

Use Case(s):

• Communicating that a pokemon has terastallized.

Message Format(s):

• |terastallize|POKEMON|TYPE

Input Example(s)

• TODO

BattleMessage_fieldactivate

Message communicating that a field effect has been activated.

ATTRIBUTE	DESCRIPTION
EFFECT	The effect causing the field activation TYPE: Effect

Use Case(s):

• Communicating that a field effect has been activated.

Message Format(s):

• |-fieldactivate|EFFECT

Input Example(s)

• TODO

BattleMessage_error

Message communicating that an error has occurred.

ATTRIBUTE	DESCRIPTION
MESSAGE	The error message sent by showdown TYPE: str

Use Case(s):

• Communicating that an error has occurred.

Message Format(s):

• |error|MESSAGE

Input Example(s)

• TODO

BattleMessage_bigerror

Message communicating that a big error has occurred.

ATTRIBUTE	DESCRIPTION
MESSAGE	The error message sent by showdown TYPE: str

Use Case(s):

• Communicating that a big error has occurred.

Message Format(s):

• |bigerror|MESSAGE

Input Example(s)

• TODO

BattleMessage_init

Message communicating that a battle has been initialized.

Use Case(s):

• Communicating that a battle has been initialized.

Message Format(s):

• |init|battle

Input Example(s)

• |init|battle

BattleMessage_deinit

Message communicating that a battle has been deinitialized.

Use Case(s):

• Communicating that a battle has been deinitialized.

Message Format(s):

• |deinit

Input Example(s)

• |deinit

BattleMessage_title

Message communicating that a title has been sent for this battle.

ATTRIBUTE	DESCRIPTION
TITLE	The title of this match as shown on pokemon showdown TYPE: str

Use Case(s):

• Communicating that a title has been sent for this battle.

Message Format(s):

• |title|TITLE

Input Example(s)

• TODO

BattleMessage_join

Message communicating that a player has joined the battle.

ATTRIBUTE	DESCRIPTION
USERNAME	The username of the joining player TYPE: str

Use Case(s):

• Communicating that a player has joined the battle.

Message Format(s):

• |join|USERNAME

Input Example(s)

• TODO

BattleMessage_leave

Message communicating that a player has left the battle.

ATTRIBUTE	DESCRIPTION
USERNAME	The username of the leaving player TYPE: str

Use Case(s):

• Communicating that a player has left the battle.

Message Format(s):

• |leave|USERNAME

Input Example(s)

• TODO

BattleMessage_raw

Message communicating that a raw message has been sent.

ATTRIBUTE	DESCRIPTION
MESSAGE	The raw message from Showdown. Typically used for rating changes. TYPE: str

Use Case(s):

• Communicating that a raw message has been sent.

Message Format(s):

• |raw|MESSAGE

Input Example(s)

• TODO

BattleMessage_anim

Message communicating that an override animation has been sent.

Warning

This has not been fully implemented / tested on large data yet.

ATTRIBUTE	DESCRIPTION
SOURCE	The pokemon using the move TYPE: PokemonIdentifier
TARGET	The pokemon being targeted by the move. If there is no target then this will instead be slotless TYPE: PokemonIdentifier
MOVE	The move being used TYPE: DexMove.ValueType
NO_TARGET	Whether the move is labeled as notarget or not TYPE: bool

Use Case(s):

• Communicating that a move should use a different animation from typical.

Message Format(s):

• |-anim|SOURCE|MOVE|TARGET|[notarget]

Input Example(s)

• TODO

Message Utility Classes

Contains BaseModels for BattleMessage parsing and processing.

Remember to use BattleMessage.from_message directly, unless you are building test cases where you want to assert that a given message leads to a certain subclass of BattleMessage. from_message will auto-detect which BMType the given message corresponds to, and return the associated subclass (or an error detailing what went wrong) for you.

BMType

String-Enum for holding all unique categories of Showdown Battle Messages.

See https://github.com/smogon/pokemon-showdown/blob/master/sim/SIM-PROTOCOL.md for the full list of battle messages

PokeStat

Helper enum for identifying valid stats.

PokemonIdentifier

A BaseModel giving details about which Pokemon is being talked about.

Attributes:

Name	Type	Description
IDENTITY	str	The unique identifier for a pokemon. Looks like ARCANINE if the input is p1: Arcanine
PLAYER	str	The player this pokemon belongs to
SLOT	Optional[str]	Optionally, the slot this pokemon is in. Will be None if slot info isn't given in the message

from_ident_string(ident) staticmethod

Create a new PokemonIdentifier from an identifier string without slot information.

Parameters:

Name	Type	Description	Default
ident	str	An input string to extract field information from. Looks like "p1: Arcanine"	required

Returns:

Name	Type	Description
PokemonIdentifier	PokemonIdentifier	A newly created PokemonIdentifier object from this string

from_slot_string(slot) staticmethod

Create a new PokemonIdentifier from an identifier string with slot information.

Parameters:

Name	Type	Description	Default
slot	str	An input string to extract field information from. Looks like "p1a: Arcanine"	required

Returns:

Name	Type	Description
PokemonIdentifier	PokemonIdentifier	A newly created PokemonIdentifier object from this string

from_string(string) staticmethod

Auto-Create a new PokemonIdentifier based on which type of identity string is given.

Parameters:

Name	Type	Description	Default
string	str	An input string to extract field information from. Looks like "p1a: Arcanine"	required

Returns:

Name	Type	Description
PokemonIdentifier	PokemonIdentifier	A newly created PokemonIdentifier object from this string

EffectType

Helper class to identify which category of effect is being activated.

Effect

A helper class for many Battle Message types that rely on something happening to cause the message effect.

RequestPoke

A helper class to contain details about a pokemon held in the side data of a request.

Attributes:

Name	Type	Description
IDENT	PokemonIdentifier	The string pokemon identifier (without slot information)
SPECIES	DexPokemon.ValueType	The species for this pokemon, including forme
LEVEL	int	The level of this pokemon
GENDER	Optional[Literal['M', 'F']]	The gender of this pokemon
SHINY	bool	Whether the pokemon is shiny or not
TERA	Optional[DexType.ValueType]	If this pokemon is teratyped, the DexType of the new type. Else None.
CUR_HP	int	The current HP of the pokemon
MAX_HP	Optional[int]	The maximum HP of the pokemon, None if the pokemon is fainted
STATUS	Optional[DexStatus.ValueType]	The status of the pokemon. Can be None if there is no status
ACTIVE	bool	Whether the pokemon is active or not
STATS	Dict[PokeStat, int]	A dictionary of stat->values for each stat of this pokemon (before modifiers)
MOVES	List[DexMove.ValueType]	The list of moves this pokemon knows, without pp information
BASE_ABILITY	DexAbility.ValueType	The base ability of this pokemon, ignoring any ability switching shenanigans
ABILITY	Optional[DexAbility.ValueType]	The current ability of this pokemon. Only used in certain gens, can be None
ITEM	Optional[DexItem.ValueType]	The held item of this pokemon. None if no item is held
POKEBALL	str	Which pokeball this pokemon is contained in
COMMANDING	Optional[bool]	Tatsugiri commander mechanic. True if active, false if not, None if older gen
REVIVING	Optional[bool]	Revival Blessing flag (I think?)
TERATYPE	Optional[DexType.ValueType]	The type that this pokemon can teratype into
TERASTALLIZED	Optional[DexType.ValueType]	The type that this pokemon is teratyped into. None if not applicable

MoveData

A helper class to contain details about a move held in the active data for a request.

Attributes:

Name	Type	Description
NAME	str	The friendly name of the move
ID	DexMove.ValueType	The id of the move
CUR_PP	Optional[int]	The integer amount of times this move can still be used. None if Trapped
MAX_PP	Optional[int]	The integer amount of times this move can ever be used. None if Trapped
TARGET	Optional[DexMoveTarget.ValueType]	The targetting type of this move. None if Trapped
DISABLED	Optional[bool]	Whether this move is disabled or not. None if Trapped

ActiveOption

A helper class to contain details about all moves available for an active pokemon in a request.

Attributes:

Name	Type	Description
MOVES	List[MoveData]	A list of available moves for this slot
CAN_MEGA	bool	Whether the pokemon can mega evolve
CAN_ZMOVE	bool	Whether the pokemon can zmove with at least one move
CAN_DYNA	bool	Whether the pokemon can dynamax
CAN_TERA	bool	Whether the pokemon can teratype
TRAPPED	bool	Whether the user is trapped