Skip to main content
Battle rooms use a specialized protocol for communicating game state, moves, switches, and other battle events. This page documents the battle-specific message types.

​
Battle Initialization

The beginning of a battle includes player information, team preview, and game rules.

​
Example Battle Start

|player|p1|Anonycat|60|1200
|player|p2|Anonybird|113|1300
|teamsize|p1|4
|teamsize|p2|5
|gametype|doubles
|gen|7
|tier|[Gen 7] Doubles Ubers
|rule|Species Clause: Limit one of each Pokémon
|rule|OHKO Clause: OHKO moves are banned
|rule|Moody Clause: Moody is banned
|rule|Evasion Abilities Clause: Evasion abilities are banned
|rule|Evasion Moves Clause: Evasion moves are banned
|rule|Endless Battle Clause: Forcing endless battles is banned
|rule|HP Percentage Mod: HP is shown in percentages
|clearpoke
|poke|p1|Pikachu, L59, F|item
|poke|p1|Kecleon, M|item
|poke|p1|Jynx, F|item
|poke|p1|Mewtwo|item
|poke|p2|Hoopa-Unbound|
|poke|p2|Smeargle, L1, F|item
|poke|p2|Forretress, L31, F|
|poke|p2|Groudon, L60|item
|poke|p2|Feebas, L1, M|
|teampreview
|
|start

​
Player

|player|PLAYER|USERNAME|AVATAR|RATING
  • PLAYER - p1, p2 (or p3, p4 in 4-player battles)
  • USERNAME - Player’s username
  • AVATAR - Avatar identifier (usually a number)
  • RATING - Elo rating (only in rated battles, otherwise blank)

​
Team Size

|teamsize|PLAYER|NUMBER
Indicates the number of Pokémon the player starts with.

​
Game Type

|gametype|GAMETYPE
GAMETYPE is one of:
  • singles
  • doubles
  • triples
  • multi
  • freeforall

​
Generation

|gen|GENNUM
Generation number from 1 to 9.
Stadium counts as its respective gen, Let’s Go counts as 7, and modded formats use their base gen.

​
Tier

|tier|FORMATNAME
The name of the format being played.

​
Rated

|rated
Present if the game affects ladder rating. 
|rated|MESSAGE
Present if the game is official (like tournament games).

​
Rule

|rule|RULE: DESCRIPTION
Appears multiple times, once for each active rule.

​
Team Preview

​
Clear Poke

|clearpoke
Marks the start of Team Preview.

​
Poke

|poke|PLAYER|DETAILS|ITEM
Declares a Pokémon for Team Preview.
  • PLAYER - Player ID (p1, p2, etc.)
  • DETAILS - Pokémon description (see “Identifying Pokémon” below)
  • ITEM - item if holding an item, blank otherwise
Forme and shininess are hidden in Team Preview, unlike in |switch| messages.

​
Team Preview End

|teampreview
Marks the end of Team Preview data.

​
Start

|start
Indicates the battle has started.

​
Identifying Pokémon

​
Pokémon ID Format

Pokémon are identified by POSITION: NAME:
  • POSITION = Player (p1, p2) + position letter (a in singles)
  • NAME = Nickname (or species if no nickname)
Examples:
  • p1a: Sparky - Pokémon in player 1’s active slot named Sparky
  • p1: Dragonite - Inactive Dragonite (no position letter)

​
Position Layout

Doubles (Player 1’s perspective): 
p2b p2a
p1a p1b
Doubles (Player 2’s perspective): 
p1b p1a
p2a p2b
Multi (Player 1’s perspective): 
p4b p2a
p1a p3b

​
Details String

DETAILS is comma-separated information:
  • SPECIES - Always present
  • , L## - If not level 100
  • , M - If male
  • , F - If female
  • , shiny - If shiny
  • , tera:TYPE - If Terastallized (Gen 9)
Examples:
  • Deoxys-Speed - Level 100 genderless non-shiny
  • Sawsbuck, L50, F, shiny - Level 50 shiny female
  • Arceus-* - Arceus in Team Preview (forme hidden)

​
Battle Progress

​
Spacer

|
Clears the message bar and adds a spacer to battle history.

​
Request

|request|REQUEST
JSON object requesting a choice (move or switch). See Choice Requests for details.

​
Inactive Timer

|inactive|MESSAGE
Timer-related message (displayed in red). Timer is currently on. 
|inactiveoff|MESSAGE
Timer-related message. Timer is currently off.

​
Upkeep

|upkeep
Signals the upkeep phase where field condition timers are updated.

​
Turn

|turn|NUMBER
It is now turn NUMBER.

​
Win

|win|USER
USER won the battle.

​
Tie

|tie
The battle ended in a tie.

​
Timestamp

|t:|TIMESTAMP
UNIX timestamp for determining when events occurred.

​
Major Actions

Major actions represent significant battle events like moves, switches, and fainting.

​
Move

|move|POKEMON|MOVE|TARGET
The specified Pokémon used MOVE at TARGET.
For moves with multiple targets or no target, TARGET should be ignored.
Tags:
  • |[miss] - The move missed
  • |[still] - Suppress animation
  • |[anim] MOVE2 - Use animation of MOVE2 instead
Example: 
|move|p1a: Pikachu|Thunderbolt|p2a: Charizard

​
Switch

|switch|POKEMON|DETAILS|HP STATUS
A Pokémon switched in (intentional). 
|drag|POKEMON|DETAILS|HP STATUS
A Pokémon was forced to switch (Whirlwind, Roar, etc.).
  • POKEMON|DETAILS - Identifies the Pokémon
  • HP - Current HP as fraction (CURRENT/MAX for your Pokémon, /100 or /48 for opponent)
  • STATUS - Status condition (slp, par, etc.) or blank
Example: 
|switch|p1a: Garchomp|Garchomp, L78, M|248/248

​
Forme Change

|detailschange|POKEMON|DETAILS|HP STATUS
Permanent forme change (Mega Evolution, frozen Shaymin-Sky). 
|-formechange|POKEMON|SPECIES|HP STATUS
Temporary forme change.

​
Replace

|replace|POKEMON|DETAILS|HP STATUS
Illusion ended for the specified Pokémon.
POKEMON uses the NEW Pokémon ID (Zoroark’s nickname). Everything you knew about the previous Pokémon is wrong.

​
Swap

|swap|POKEMON|POSITION
Moves active POKEMON to POSITION (0-indexed from left).

​
Can’t

|cant|POKEMON|REASON

|cant|POKEMON|REASON|MOVE
Pokémon couldn’t perform a move due to REASON (paralysis, Disable, etc.).

​
Faint

|faint|POKEMON
The Pokémon fainted.

​
Minor Actions

Minor actions represent smaller battle events like damage, healing, and status changes.
Minor actions are usually displayed in small font in the official client.

​
Fail

|-fail|POKEMON|ACTION
The ACTION failed against POKEMON due to its own mechanics.

​
Block

|-block|POKEMON|EFFECT|MOVE|ATTACKER
An effect targeting POKEMON was blocked by EFFECT.
|[of]SOURCE may note the owner of EFFECT (e.g., ally with Aroma Veil).

​
Miss

|-miss|SOURCE|TARGET
Move used by SOURCE missed TARGET.

​
Damage

|-damage|POKEMON|HP STATUS
Pokémon took damage and is now at HP STATUS.
If HP is 0, STATUS should be ignored (currently fnt but may change).

​
Heal

|-heal|POKEMON|HP STATUS
Same as -damage, but for healing.

​
Set HP

|-sethp|POKEMON|HP
Pokémon now has HP hit points.

​
Status

|-status|POKEMON|STATUS
Pokémon was inflicted with STATUS. 
|-curestatus|POKEMON|STATUS
Pokémon recovered from STATUS. 
|-cureteam|POKEMON
Pokémon used a move that cures its team (Heal Bell, Aromatherapy).

​
Stat Changes

​
Boost

|-boost|POKEMON|STAT|AMOUNT
Pokémon gained AMOUNT stages in STAT. STAT abbreviations:
  • atk - Attack
  • def - Defense
  • spa - Special Attack
  • spd - Special Defense
  • spe - Speed
  • accuracy - Accuracy
  • evasion - Evasion

​
Unboost

|-unboost|POKEMON|STAT|AMOUNT
Same as -boost, but for negative stat changes.

​
Set Boost

|-setboost|POKEMON|STAT|AMOUNT
STAT is set to AMOUNT (Anger Point, Belly Drum).

​
Swap Boosts

|-swapboost|SOURCE|TARGET|STATS
Swaps boosts in STATS between SOURCE and TARGET. STATS is comma-separated list (e.g., atk,def,spe).

​
Other Boost Operations

|-invertboost|POKEMON
Invert all boosts (Topsy-Turvy). 
|-clearboost|POKEMON
Clear all boosts (Clear Smog). 
|-clearallboost
Clear all boosts from all Pokémon (Haze). 
|-clearpositiveboost|TARGET|POKEMON|EFFECT
Clear positive boosts (Spectral Thief). 
|-clearnegativeboost|POKEMON
Clear negative boosts (Z-move effect). 
|-copyboost|SOURCE|TARGET
Copy boosts from SOURCE to TARGET (Psych Up).

​
Field Conditions

​
Weather

|-weather|WEATHER
Indicates current weather.
|[upkeep] means weather was active previously and continues. Otherwise, weather just changed or expired (none).

​
Field Start/End

|-fieldstart|CONDITION
Field condition started (Trick Room, Grassy Terrain). 
|-fieldend|CONDITION
Field condition ended.

​
Side Conditions

|-sidestart|SIDE|CONDITION
Side condition started (Tailwind, Stealth Rock, Reflect). 
|-sideend|SIDE|CONDITION
Side condition ended. 
|-swapsideconditions
Side conditions swapped (Court Change).

​
Volatile Status

​
Start

|-start|POKEMON|EFFECT
Volatile status inflicted (confusion, Taunt, Substitute).

​
End

|-end|POKEMON|EFFECT
Volatile status from EFFECT ended.

​
Battle Effectiveness

|-crit|POKEMON
Critical hit against POKEMON. 
|-supereffective|POKEMON
Super effective against POKEMON. 
|-resisted|POKEMON
Not very effective against POKEMON. 
|-immune|POKEMON
POKEMON was immune.

​
Items

​
Item Revealed

|-item|POKEMON|ITEM|[from]EFFECT
Item changed or revealed due to move/ability. 
|-item|POKEMON|ITEM
Item announced on switch-in (Air Balloon).

​
End Item

|-enditem|POKEMON|ITEM|[from]EFFECT
Item destroyed by move/ability (Knock Off).
|[silent] if ownership changed (Thief, Trick).
|-enditem|POKEMON|ITEM
Item consumed (Berry, Air Balloon).
Berries include |[eat] modifier.

​
Abilities

​
Ability Revealed

|-ability|POKEMON|ABILITY|[from]EFFECT
Ability changed due to move/ability.
Skill Swap doesn’t send this to avoid revealing allies’ abilities in Double/Triple battles.
|-ability|POKEMON|ABILITY
Ability announced on switch-in with long-term effect (Mold Breaker, Neutralizing Gas).

​
End Ability

|-endability|POKEMON
Ability suppressed by Gastro Acid.

​
Transformations

​
Transform

|-transform|POKEMON|SPECIES
Pokémon transformed into SPECIES (Transform move or Imposter).

​
Mega Evolution

|-mega|POKEMON|MEGASTONE
Pokémon Mega Evolved using MEGASTONE.

​
Primal Reversion

|-primal|POKEMON
Pokémon reverted to primal forme.

​
Ultra Burst

|-burst|POKEMON|SPECIES|ITEM
Pokémon Ultra Burst into SPECIES using ITEM.

​
Z-Move

|-zpower|POKEMON
Pokémon used Z-move version of its move. 
|-zbroken|POKEMON
Z-move broke through Protect and hit POKEMON.

​
Miscellaneous

​
Activate

|-activate|EFFECT
Miscellaneous effect activated (for effects without better descriptors).

​
Hint

|-hint|MESSAGE
Displays MESSAGE in parentheses to explain why certain actions occurred.

​
Center

|-center
In Triple Battles, Pokémon automatically centered when only one remains per side.

​
Message

|-message|MESSAGE
Miscellaneous message (primarily for custom mods and rule clauses).

​
Combine

|-combine
Move combined with another (Fire Pledge + Grass Pledge).

​
Waiting

|-waiting|SOURCE|TARGET
SOURCE is waiting for TARGET (Pledge moves).

​
Prepare

|-prepare|ATTACKER|MOVE

|-prepare|ATTACKER|MOVE|DEFENDER
Pokémon preparing to use charge move (Dig, Fly, Sky Drop).

​
Must Recharge

|-mustrecharge|POKEMON
Pokémon must recharge (Hyper Beam).

​
Hit Count

|-hitcount|POKEMON|NUM
Multi-hit move hit NUM times.

​
Single Move

|-singlemove|POKEMON|MOVE
Temporary effect lasting the duration of move (Grudge, Destiny Bond).

​
Single Turn

|-singleturn|POKEMON|MOVE
Temporary effect lasting the duration of turn (Protect, Focus Punch, Roost).

​
Next Steps

Choice Requests

Learn how to respond to battle requests

Client-Server Messages

Review non-battle protocol messages

Build docs developers (and LLMs) love

Get started for freeTalk to us