Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


0.3.1 • Public • Published

Build Status npm Dependency Status devDependency Status License

Node-PS-Client is a Pokemon Showdown simplified client library written in JavaScript for Node.

This library is based on Pokemon Showdown Bot, merging all connection, data-receiving and data-sending functions in a single namespace, easing development of bots for Pokemon Showdown.


NPM Installation - To install use:

npm install node-ps-client

Minimized Version

Due to this library is in a single file, you can also install it just copying the file ./lib/node-ps-client.js Note: You must manually install dependencies to work


Creating a new client is as simple as this:

var pokemonShowdownClient = require('node-ps-client');
var Client = new pokemonShowdownClient(server, port, options);

In order to add events (for example if you want to listen for pms or chat messages) you can use on method:

Client.on('eventname', function (args) {
  //do stuff

In order to send data to server, you can send method:

Client.send(data, delay); 

data can be a string or an array. delay is using only when data is an array for sending it slowly

In order to log in a new usename, use rename method:

Client.rename('New Nick', 'password');


Options are passed on client construction in an object, example:

var pokemonShowdownClient = require('node-ps-client');
var conOptions = {
  server: 'localhost',
  port: 8000,
  serverid: 'localhost'
var Client = new pokemonShowdownClient(server, port, options);

Connection-Related Options

  • server: host of a Pokemon showdown server. For example, main server (
  • port: connection port. Pokemon Showdown Servers default port is 8000
  • serverid: server identification, using during the login process
  • secprotocols (Optional): secondary protocols for the connection. Pokemon showdow servers don't use them, no it's useless
  • connectionTimeout (Optional): If not false, forces connection closing if no messages are received in connectionTimeout value miliseconds
  • autoConnect (Optional): If true, connect to server just after object creation
  • autoReconnect (Optional): If true, try reconnect when connection is closed
  • autoReconnectDelay (Optional): Number of milliseconds for reconnect

Login-Related Options

  • loginServer: Login server url. For main server is
  • nickName (Optional): Auto login nickname
  • pass (Optional): Password for auto login nickname(if needed)
  • retryLogin (Optional): If not false, retry loging when failed in retryLogin value milliseconds

Other Options

  • autoJoin (Optional): An array of rooms names for joining after login
  • showErrors (Optional): If true write error messages on the console
  • debug (Optional): If true write debug messages on the console

Status properties

Overall Status

  • Client.status.connected - true if connected to server, false otherwise
  • Client.status.nickName - Actual nickname
  • Client.status.named - true if named, false if guest
  • Client.status.avatar - current avatar

Rooms Information

  • Client.rooms - object with all rooms where client is joined
  • Client.rooms['name'].title - title of the room
  • Client.rooms['name'].type - room type (chat or battle)
  • Client.rooms['name'].userCount - number of users
  • Client.rooms['name'].users - users object


var pokemonShowdownClient = require('node-ps-client');
var Client = new pokemonShowdownClient(server, port, options);
Client.on('joinroom', function (room) {
  console.log(Client.status.nickName + " joined " + room);


Connection Methods:

  • Client.connect() - connects to server
  • Client.disconnect() - closes the connection
  • Client.softDisconnect() - closes the connection and reconnects
  • Client.startConnectionTimeOut() - starts connection timer
  • Client.stopConnectionTimeOut() - stops connection timer

Login Methods:

  • Client.rename(nick, pass) - logins on an username

Sending Methods:

  • Client.send(data, delay) - send to server
  • Client.sendRoom(room, data, delay) - send data to a room
  • Client.say(room, message) - send a message to a room
  •, message) - send a private message
  • Client.joinRooms(rooms) - joins rooms (rooms = array of rooms ids)
  • Client.leaveRooms(room, data, delay) - leaves rooms


Event: connect - when client connects to server

Client.on('connect', function (connection) {
  //do stuff

Event: disconnect - on connection error or closure

Client.on('disconnect', function (err) {
  //do stuff

Event: message - when a message is received from the server

Client.on('message', function (message) {
  //do stuff

Event: send - on sending data

Client.on('send', function (data) {
  //do stuff

Event: sendfailure - on sending error

Client.on('sendfailure', function (err) {
  //do stuff

Event: rename - on rename success

Client.on('rename', function (name, named, avatar) {
  //do stuff

Event: renamefailure - on rename error

Client.on('renamefailure', function (err) {
  //do stuff

Event: challstr - on challstr receive

Client.on('challstr', function (challstr) {
  //do stuff

Event: formats - on formats list receive

Client.on('formats', function (formats) {
  //do stuff

Event: joinroom - on room joining

Client.on('joinroom', function (room, type) {
  //do stuff

Event: leaveroom - on room leaving

Client.on('leaveroom', function (room) {
  //do stuff

Event: joinfailure - on join error or access denied

Client.on('joinfailure', function (room, errType, errData) {
  //do stuff

Event: intro - on room intro message (not real time message)

Client.on('intro', function (type, room, ...) {
  //do stuff

Event: chat - on chat messages (not self messages)

Client.on('chat', function (room, time, by, message) {
  //do stuff

Event: chatsucess - on self chat messages

Client.on('chatsucess', function (room, time, message) {
  //do stuff

Event: pm - on private message

Client.on('pm', function (by, message) {
  //do stuff

Event: pmsucess - on pm sent confirmation

Client.on('pmsucess', function (to, message) {
  //do stuff

Event: userjoin - when an user joins a room

Client.on('userjoin', function (room, user) {
  //do stuff

Event: userleave - when an user leaves a room

Client.on('userleave', function (room, user) {
  //do stuff

Event: userrename - when an users changes its identity

Client.on('userrename', function (room, oldName, newName) {
  //do stuff

Event: queryresponse - when a query response is received

Client.on('queryresponse', function (data) {
  //do stuff

Event: popup - on popup received

Client.on('popup', function (data) {
  //do stuff

Event: raw - on raw, html or no label message received

Client.on('raw', function (room, raw) {
  //do stuff

Event: line - single message (only one line)

Client.on('line', function (room, message, isIntro, splittedLine) {
  //do stuff

Event: major - on major (labeled messages)

Client.on('major', function (room, major, message, isIntro) {
  //do stuff

Event: minor - on minor message (some battle messages)

Client.on('minor', function (room, minor, message, isIntro) {
  //do stuff


Part of this code is imported from other developments, so credits to:




npm i node-ps-client

Downloadsweekly downloads









last publish


  • avatar