node-ps-client v0.3.1

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.

Installation

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

Usage

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

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 (sim.smogon.com)
• 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 https://play.pokemonshowdown.com/~~showdown/action.php
• 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

Example:

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);
});

Methods

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
• Client.pm(to, message) - send a private message
• Client.joinRooms(rooms) - joins rooms (rooms = array of rooms ids)
• Client.leaveRooms(room, data, delay) - leaves rooms

Events

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
});

Credits

• Ecuacion (Owner)

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

• Quinella, Morfent and TalkTakesTime developers of Pokemon-Showdown-Bot (https://github.com/TalkTakesTime/Pokemon-Showdown-Bot)
• Guangcong Luo and other contributors of Pokemon Showdown