Skip to main content

Overview

The Battle class is the core of Pokemon Showdown’s battle simulation engine. It manages the battle state, processes actions, and handles all battle mechanics.
import { Battle } from 'pokemon-showdown';

const battle = new Battle();

Constructor

new Battle(options?: BattleOptions)
options
object
Battle configuration options

Key Properties

turn
number
Current turn number
p1
Side
Player 1’s side
p2
Side
Player 2’s side
field
Field
The battle field state
queue
BattleQueue
The action queue
format
Format
The battle format rules
dex
ModdedDex
The data access layer for this format
prng
PRNG
The pseudorandom number generator
ended
boolean
Whether the battle has ended
winner
SideID | ''
The winning side ID, or empty string if no winner

Core Methods

setPlayer()

Set up a player and their team.
battle.setPlayer('p1', {
  name: 'Alice',
  team: Teams.pack(teamData)
});
playerid
'p1' | 'p2' | 'p3' | 'p4'
required
Player identifier
options
object
required

choose()

Make a choice for a player.
battle.choose('p1', 'move 1');
battle.choose('p2', 'switch 3');
playerid
SideID
required
Player making the choice
choice
string
required
The choice string (e.g., “move 1”, “switch 2”)

start()

Start the battle.
battle.start();

destroy()

Clean up the battle and free resources.
battle.destroy();

Battle State Methods

makeChoices()

Process choices for all players simultaneously.
battle.makeChoices('move 1', 'move 2');

commitChoices()

Commit and execute the queued choices.

clearChoice()

Clear a player’s pending choice.
battle.clearChoice('p1');

setTurn()

Advance to the next turn.
battle.setTurn(battle.turn + 1);

Message Methods

add()

Add a message to the battle log.
battle.add('-damage', pokemon, pokemon.getHealth());

addSplit()

Add a message with public and private variants.
battle.addSplit('p1', ['-damage', pokemon, pokemon.getHealth()]);

hint()

Add a hint message for debugging.
battle.hint("This move failed because...");

Damage Calculation

getDamage()

Calculate damage from an attack.
const damage = battle.getDamage(
  attacker,
  defender,
  move,
  suppressMessages
);
attacker
Pokemon
required
The attacking Pokemon
defender
Pokemon
required
The defending Pokemon
move
Move | ActiveMove
required
The move being used
suppressMessages
boolean
Whether to suppress damage messages
return
number | false | undefined
Damage amount, false if attack fails, undefined for special handling

Utility Methods

randomChance()

Test for a random chance.
if (battle.randomChance(1, 10)) {
  // 10% chance
}

sample()

Randomly select from an array.
const move = battle.sample(pokemon.moves);

random()

Generate a random integer.
const damage = battle.random(85, 101); // 85-100 inclusive

Example Usage

import { Battle, Teams } from 'pokemon-showdown';

// Create battle
const battle = new Battle({
  formatid: 'gen9ou',
  seed: [1, 2, 3, 4] // Optional seed for reproducibility
});

// Set up players
battle.setPlayer('p1', {
  name: 'Alice',
  team: Teams.pack([
    {species: 'Pikachu', moves: ['thunderbolt', 'quickattack'], level: 50},
    // ... more Pokemon
  ])
});

battle.setPlayer('p2', {
  name: 'Bob',
  team: Teams.pack([/* team data */])
});

// Start battle
battle.start();

// Make choices each turn
battle.choose('p1', 'move 1');
battle.choose('p2', 'move 1');

// Battle continues until ended
while (!battle.ended) {
  // Handle choice requests and make choices
}

console.log(`Winner: ${battle.winner}`);

// Clean up
battle.destroy();

BattleStream

Stream interface for battles

Pokemon

Pokemon class

Side

Side class

Simulator Usage

Using the simulator

Build docs developers (and LLMs) love