# smogon/pokemon-showdown: the server and simulator behind Pokémon Showdown

> The repository is not the website people play on. It is the MIT-licensed TypeScript battle simulator, command-line tool and game server that the site runs on, and this article covers what it does, how to install it, and where it stops being the right tool.

**smogon/pokemon-showdown** — Pok mon battle simulator. [sim/SIM-PROTOCOL.md][5] - The part of the protocol used for battles and battle messages.

- Repository: https://github.com/smogon/pokemon-showdown
- Website: https://pokemonshowdown.com
- Stars: 5,910 · Forks: 3,538
- Language: TypeScript
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/smogon-pokemon-showdown

## What the smogon/pokemon-showdown repository actually contains

The README opens by listing five different things under one name, and that list is the fastest way to understand the scope. Pokémon Showdown is a website at pokemonshowdown.com, a JavaScript library for simulating battles and reading Pokédex data, a set of command-line tools for simulating battles from non-JavaScript programs, a web API used by the website, and a game server for hosting your own community and game modes. This repository is the server and the simulator. The client is a separate repository, pokemon-showdown-client, and the Pokédex data lives in a third, Pokemon-Showdown-Dex.

That split matters because most people searching for Pokémon Showdown want the website or an app, and neither is here. What is here is the part that decides whether Hydro Pump hits, how much damage it deals, and what the resulting battle log looks like. The README states that it simulates singles, doubles and triples battles across Generations 1 through 9. The audience is therefore narrower than the brand suggests: bot authors, researchers who want reproducible battle outcomes, format designers, and anyone hosting a private ladder.

The licence is MIT, stated in the README and shipped as a LICENSE file at the repository root. That is permissive and unusual for a project built on a commercial game property, which is worth noting without drawing conclusions the repository itself does not draw.

## How the simulator, the protocol and the server fit together

The repository root points at ARCHITECTURE.md for a high-level overview, and the documentation set separates two protocols. PROTOCOL.md describes how the client and server communicate with each other. sim/SIM-PROTOCOL.md describes the part of the protocol used for battles and battle messages. That distinction is the core of the design: the simulator emits a stream of text messages describing what happened, and the server relays those messages to clients.

The package.json confirms the shape of the code. The main entry is dist/sim/index.js with types at dist/sim/index.d.ts, so the simulator is compiled to JavaScript and consumed as a library. The build script runs node build, and the build-npm script additionally emits declarations from sim/global-types.ts and sim/index.ts. The runtime dependencies are small: esbuild, mysql2, preact, preact-render-to-string, sockjs and ts-chacha20. Everything else, including better-sqlite3, pg, sqlite, nodemailer and githubhook, is an optional dependency, which tells you the server can run without most of its integrations.

Two details in that dependency list are more informative than the README. sockjs is the transport for the web client, and preact with preact-render-to-string is used for server-side rendering. ts-chacha20 is a cipher implementation, which fits a server that needs to generate verifiable randomness. The simulator itself has no database dependency, so embedding it in a bot or a test harness does not drag in MySQL or SQLite.

## Installing and running your first battle from the command line

The repository requires Node.js 22.18.0 or newer, per the engines field in package.json. COMMANDLINE.md documents the command-line tools, and the package scripts show how the project is built and started. The README does not give a single copy-paste install sequence, so the steps below follow the scripts in package.json rather than a documented quickstart.

Clone the repository and install dependencies with npm. The build script compiles the TypeScript sources.

```bash
npm install
npm run build
```

The start script is node pokemon-showdown start, so running the server is a single command.

```bash
npm start
```

For simulation rather than hosting, COMMANDLINE.md is the document to read, because the command-line tools are the path intended for use from non-JavaScript programs. The same file is linked from the README under that description. If you only want the battle logic inside a Node program, the package exposes dist/sim/index.js as its main entry after a build, and the README points at sim/README.md for library usage.

One practical constraint: the pretest script runs the linter before mocha, and posttest runs tsc. If you run npm test on a fresh checkout it will lint first, which can fail on formatting rather than on logic.

## Where the simulator is the wrong tool

The simulator is deterministic and text-driven, which is what makes it useful for bots and tests, and also what makes it a poor fit for anything that needs the presentation layer. If your goal is a graphical battle client, a mobile app, or a desktop download, this repository does not contain it. The README explicitly separates the client repository, and the related search terms around app downloads and mobile play point at a need this codebase does not satisfy on its own.

The second limitation is the data. The README credits DaWoblefet and Marty-D with game mechanics research, which is a hint about how the correctness of the simulator is maintained: it depends on people reading game behaviour and encoding it. A format that is not represented in the data directory will not work, regardless of what the simulator code supports. The README states Generations 1 through 9 are covered, but coverage of a generation is not the same as coverage of every community format.

Third, the server is not a small deployment. It pulls in optional dependencies for SQLite, Postgres, MySQL, mail and GitHub webhooks, and there is a config directory at the repository root. The README does not document a rollback procedure or a migration path between the server versions listed in the release history, and the gap between v0.11.9 in 2023 and v0.11.10 in 2025 suggests that upgrading across versions is not a routine, well-trodden path.

## How it compares with Pokémon Showdown's client repository

The most useful alternative to compare is not another battle engine but the sibling repository, smogon/pokemon-showdown-client. The README links it directly and describes this repository as the server repository, which is the cleanest statement of the difference in approach. The client repository owns the browser experience and, per the README, hosts WEB-API.md, the web API for the battling website. This repository owns the rules, the battle state machine and the server process.

If you want to modify how a battle looks, you work in the client. If you want to modify what happens in a battle, you work here. Running your own server without a client gives you a headless engine you can drive over the protocol; running the client without a server gives you an interface with nothing to connect to. The README also points at a Bot FAQ compiled by Kaiepi covering chatbots and battle bots, which is the closest thing to a guide for the third use case, a bot that speaks the protocol to a server.

The practical consequence is that a self-hosted setup is a two-repository project, not a one-repository project, and the documentation for the join between them is split across PROTOCOL.md here and WEB-API.md in the client repository.

## Maintenance, releases and what the version history implies

The repository is not archived, and the last push was on 2026-07-28, which is also the date of the v0.11.11 release. Before that, v0.11.10 was released on 2025-02-27 and v0.11.9 on 2023-04-14. Those gaps are long. A project that ships tagged releases roughly annually or less often is not one where you should expect a tagged release to track every change on master; the commit history on the default branch is the more current signal, and the tags are snapshots.

For upgrade cost, the engines field is the hard constraint: Node.js 22.18.0 or newer. That is a recent runtime requirement, so an older deployment environment will need a Node upgrade before anything else. The full-test script chains eslint with max-warnings 0, tsc, mocha with a timeout and forbid-only, and the npm type check, which means the project maintains a strict test and type gate. Passing that gate locally is a reasonable proxy for whether your change is compatible with the maintainers' expectations, and CONTRIBUTING.md is where the code standards are written down.

The MIT licence lets you use, modify and redistribute the code, including commercially, provided the licence notice is preserved. That is a statement about the repository's licence text, not about the Pokémon trademark, which the README does not address.

## Conclusion

Adopt it if you need a deterministic, scriptable Pokémon battle engine, a bot backend, or a self-hosted server for a private community, and you are willing to run Node.js 22.18.0 or newer. Do not adopt it if you wanted the public website, a mobile app, or a packaged desktop client: this repository is the server and simulator, and the client lives in a separate repository. Before committing, verify three things in the code you actually check out: that your Node version satisfies the engines field, which database backend your config selects, and whether the battle format you care about is implemented in the data directory.

## FAQ

### How does Pokémon Showdown work?

The README describes it as several things at once: a website, a JavaScript library for simulating battles and reading Pokédex data, command-line tools for simulating battles, a web API, and a game server. The simulator produces battle messages, and PROTOCOL.md and sim/SIM-PROTOCOL.md document how those messages move between client and server.

### Is Pokémon Showdown an official game?

The repository is the server for the Pokémon Showdown battle simulator, distributed under the MIT License with credits to its owner and staff. Nothing in the README claims affiliation with the Pokémon rights holders, and the README does not address trademark status.

### Is Pokémon Showdown free?

The server is distributed under the terms of the MIT License, which permits use, modification and redistribution. The README does not discuss pricing for the hosted website, so the licence is the only cost statement the repository makes.

### How do I install Pokémon Showdown?

The package requires Node.js 22.18.0 or newer per its engines field. Installing dependencies with npm install and building with npm run build compiles the TypeScript sources; npm start runs node pokemon-showdown start.

### How do I set up a Pokémon Showdown server?

The README lists a game server for hosting your own Pokémon Showdown community and game modes, and points at server/README.md for that. The start script is node pokemon-showdown start, and a config directory exists at the repository root.

## Sources

- [Official documentation](https://pokemonshowdown.com)
- [Official README](https://github.com/smogon/pokemon-showdown#readme)
- [Project repository](https://github.com/smogon/pokemon-showdown)
- [Release notes](https://github.com/smogon/pokemon-showdown/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/smogon-pokemon-showdown