System Overview
At the highest level, Pokemon Showdown is split into three major components that communicate directly with each other:Game Server
Handles chat, matchmaking, and battle simulation
Client
Web interface for users to battle
Login Server
Manages authentication and databases
Component Architecture
Game Server
The game server is written in TypeScript and runs on Node.js. It’s the core of the Pokemon Showdown system.Socket Management
server/sockets.ts sets up a SockJS (abstracted WebSocket) server to accept connections from clients.Battle Simulation
TheRooms system includes support for battle rooms, which connect to the game simulator. All game simulation code lives in the sim/ directory.
The simulator can be used as a standalone library via npm:
npm install pokemon-showdownClient
The client is built with a mix of TypeScript and JavaScript, using a mostly hand-rolled framework built on Backbone. Key Details:- Entry point:
index.template.html - Main logic:
js/client.js - Architecture: Legacy design with multiple JS files (pre-dates modern bundlers)
- Migration status: Rewrite to Preact is in progress but stalled
Login Server
The login server handles authentication and database operations. It’s written in TypeScript. Architecture:- Entry point:
server.ts - MySQL InnoDB database: Users, ladder, and most data
- Postgres (Cockroach) database: Replays
- Migration: Replacing legacy PHP code from the client (halfway complete)
Communication Flow
Here’s how the components interact when a user plays:Initial Connection
User visits
https://play.pokemonshowdown.com/, served by Apache (static files + legacy PHP).Authentication
Browser communicates with Login Server at
https://play.pokemonshowdown.com/api/ for authentication and database operations.Game Connection
Browser connects to Game Server via SockJS for chat rooms, matchmaking, and battles.
Technology Stack
Game Server
- Runtime: Node.js v16+
- Language: TypeScript
- WebSockets: SockJS
- Simulation: Custom battle engine
Client
- Framework: Backbone (migrating to Preact)
- Languages: TypeScript + JavaScript
- Server: Apache
- Legacy: PHP (being replaced)
Login Server
- Language: TypeScript
- Databases: MySQL InnoDB, Postgres
- Purpose: Auth + data persistence
Simulator
- Language: TypeScript
- Generations: 1-9 support
- Formats: Singles, doubles, triples
- API: Stream-based
Core Modules
The game server is organized into several key modules:| Module | Location | Purpose |
|---|---|---|
| Sockets | server/sockets.ts | WebSocket connection management |
| Users | server/users.ts | User session and authentication |
| Rooms | server/rooms.ts | Chat and battle room logic |
| Chat | server/chat.ts | Command processing and messaging |
| Simulator | sim/ | Battle engine and game mechanics |
| Dex | sim/dex.ts | Pokemon data and Pokedex |
| Teams | sim/teams.ts | Team validation and generation |
Battle Simulator Architecture
The simulator implements anObjectReadWriteStream pattern:
- Write: Player choices (strings)
- Read: Protocol messages (strings)
Simulator Components
Battle Stream
Core communication layer using streams
Battle Engine
Game logic, moves, abilities, items
Dex
Pokemon species, moves, abilities data
Team Validator
Format rules and team validation
Running Your Own Server
The game server can be run independently for hosting custom communities:Default port is 8000. Visit your server at
http://localhost:8000 for local testing.Repository Links
Server
Game server repository
Client
Client repository
Login Server
Login server repository
Design Philosophy
Modularity
Clear separation between server, client, and auth
Extensibility
Custom game modes and formats supported
Streams
Stream-based architecture for battle simulation
TypeScript
Fully typed API with comprehensive definitions
Next Steps
Battle Simulator
Learn the simulator API in detail
Protocol
Understand the communication protocol
Running a Server
Host your own Pokemon Showdown server
Contributing
Contribute to the project
