Skip to main content
Pokémon Showdown’s battle simulator is the core engine that powers all battle calculations and game mechanics. The simulator provides a Node.js API for running battles programmatically.

​
Installation

Install the Pokemon Showdown package from npm: 
npm install pokemon-showdown

​
Key Features

Stream-Based API

The simulator uses an ObjectReadWriteStream architecture for battle I/O

Multiple Formats

Support for all official Pokemon formats including Random Battles, OU, Ubers, and VGC

Team Management

Generate, validate, and convert teams between multiple formats

Language Agnostic

Access via Node.js API or command-line interface for any programming language

​
Architecture

The battle simulator is implemented as an ObjectReadWriteStream where:
  • Write: Player choices (strings) are written to the stream
  • Read: Protocol messages (strings) are read from the stream

​
Core Components

1

BattleStream

The main stream interface that accepts commands and outputs battle messages
2

Battle

The internal battle state engine that processes moves, calculates damage, and applies game mechanics
3

Teams

Team parsing, validation, and generation utilities
4

Dex

The data layer providing access to Pokemon, moves, abilities, items, and formats

​
Quick Example

Here’s a minimal example of starting a battle: 
const Sim = require('pokemon-showdown');
const stream = new Sim.BattleStream();

(async () => {
    for await (const output of stream) {
        console.log(output);
    }
})();

stream.write(`>start {"formatid":"gen9randombattle"}`);
stream.write(`>player p1 {"name":"Alice"}`);
stream.write(`>player p2 {"name":"Bob"}`);
In random formats like gen9randombattle, teams are automatically generated if not provided.

​
Message Protocol

All messages written to the simulator start with > followed by a command:
  • >start OPTIONS - Initialize a battle with format options
  • >player PLAYERID OPTIONS - Set player information
  • >p1 CHOICE / >p2 CHOICE - Submit player choices
Messages read from the simulator follow the SIM-PROTOCOL format.

​
Use Cases

​
Battle Simulation

Run automated battles for testing, AI development, or analytics.

​
Team Building Tools

Validate team legality and convert between team formats.

​
Bot Development

Create bots that can play Pokemon Showdown battles programmatically.

​
Research & Analytics

Analyze battle mechanics, test strategies, and gather statistics.

​
Command-Line Interface

For non-JavaScript languages, the simulator is accessible via standard I/O: 
echo '>start {"formatid":"gen7randombattle"}
>player p1 {"name":"Alice"}
>player p2 {"name":"Bob"}' | ./pokemon-showdown simulate-battle
Remember to add \n after each message when using standard I/O, as each battle requires a separate subprocess.

​
Next Steps

Usage Guide

Learn how to use the simulator API in detail

BattleStream API

Explore the BattleStream interface and player streams

Team Formats

Understand team formats and conversions

Battle Formats

Browse available battle formats

Build docs developers (and LLMs) love

Get started for freeTalk to us