Skip to main content

​
Choose Your Path

Pokemon Showdown can be used in several ways. Choose the path that fits your needs:

Use the API

Integrate battle simulation into your application

Host a Server

Run your own Pokemon Showdown community

Use CLI Tools

Simulate battles from the command line

Contribute

Contribute to Pokemon Showdown development

​
Using the API

Get started with the Pokemon Showdown simulator API in your Node.js application.
1

Install the Package

Install Pokemon Showdown via npm:
npm install pokemon-showdown
2

Import and Create a Battle

Create your first battle simulation:
import { BattleStream } from 'pokemon-showdown';

const stream = new BattleStream();

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

// Start a random battle
stream.write('>start {"formatid":"gen9randombattle"}');
stream.write('>player p1 {"name":"Alice"}');
stream.write('>player p2 {"name":"Bob"}');
3

Make Battle Choices

After receiving choice requests, make moves:
// Players make choices each turn
stream.write('>p1 move 1');
stream.write('>p2 move 1');

// Or switch Pokemon
stream.write('>p1 switch 2');

​
Next Steps for API Users

Battle Simulator

Learn about the simulator API

BattleStream API

Complete BattleStream reference

Teams

Working with teams

Pokedex API

Access Pokemon data

​
Hosting a Server

Run your own Pokemon Showdown server for your community.
1

Install Node.js

Pokemon Showdown requires Node.js v16 or later:
# Check your Node.js version
node --version
If you need to upgrade Node.js:
npm install --global n
n latest
2

Clone the Repository

Get the Pokemon Showdown server code:
git clone https://github.com/smogon/pokemon-showdown.git
cd pokemon-showdown
3

Start the Server

Run the server:
./pokemon-showdown
# Or on Windows: node pokemon-showdown
The server will build automatically and start on port 8000.
4

Access Your Server

Visit your server in a web browser:
http://localhost:8000
You’ll be redirected to the Pokemon Showdown client interface.
5

Set Up an Admin Account

Create a config/usergroups.csv file:
YourUsername,~
Replace YourUsername with your registered Pokemon Showdown username.

​
Next Steps for Server Hosts

Configuration

Configure your server

Administration

Manage users and rooms

Security

Secure your server

Custom Formats

Create custom battle formats

​
Command-Line Tools

Use Pokemon Showdown’s CLI tools for automation and scripting.
1

Install or Clone

Either install via npm or clone the repository:
npm install pokemon-showdown
2

Generate a Random Team

Create a random team for testing:
./pokemon-showdown generate-team gen9ou
3

Simulate a Battle

Run a battle simulation:
echo '>start {"formatid":"gen9randombattle"}
>player p1 {"name":"Alice"}
>player p2 {"name":"Bob"}' | ./pokemon-showdown simulate-battle
4

Validate Teams

Check if a team is legal for a format:
cat team.txt | ./pokemon-showdown validate-team gen9ou

​
Next Steps for CLI Users

CLI Overview

Learn all CLI commands

Simulate Battle

Advanced battle simulation

Team Commands

Team management commands

Protocol

Understand the battle protocol

​
Learn More

Architecture

Understand how Pokemon Showdown works

Battle Protocol

Learn the battle message protocol

Contributing

Contribute to the project
Need help? Check out the GitHub repository or visit the Smogon Forums.

Build docs developers (and LLMs) love

Get started for freeTalk to us