node-ps-client


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:
`js
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:
`js
Client.on('eventname', function (args) {
//do stuff
});
`

In order to send data to server, you can send method:
`js
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:
`js
Client.rename('New Nick', 'password');
`


Options
-----------

Options are passed on client construction in an object, example:
`js
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:
`js
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
`js
Client.on('connect', function (connection) {
//do stuff
});
`

Event: disconnect - on connection error or closure
`js
Client.on('disconnect', function (err) {
//do stuff
});
`

Event: message - when a message is received from the server
`js
Client.on('message', function (message) {
//do stuff
});
`

Event: send - on sending data
`js
Client.on('send', function (data) {
//do stuff
});
`

Event: sendfailure - on sending error
`js
Client.on('sendfailure', function (err) {
//do stuff
});
`

Event: rename - on rename success
`js
Client.on('rename', function (name, named, avatar) {
//do stuff
});
`

Event: renamefailure - on rename error
`js
Client.on('renamefailure', function (err) {
//do stuff
});
`

Event: challstr - on challstr receive
`js
Client.on('challstr', function (challstr) {
//do stuff
});
`

Event: formats - on formats list receive
`js
Client.on('formats', function (formats) {
//do stuff
});
`

Event: joinroom - on room joining
`js
Client.on('joinroom', function (room, type) {
//do stuff
});
`

Event: leaveroom - on room leaving
`js
Client.on('leaveroom', function (room) {
//do stuff
});
`

Event: joinfailure - on join error or access denied
`js
Client.on('joinfailure', function (room, errType, errData) {
//do stuff
});
`

Event: intro - on room intro message (not real time message)
`js
Client.on('intro', function (type, room, ...) {
//do stuff
});
`

Event: chat - on chat messages (not self messages)
`js
Client.on('chat', function (room, time, by, message) {
//do stuff
});
`

Event: chatsucess - on self chat messages
`js
Client.on('chatsucess', function (room, time, message) {
//do stuff
});
`

Event: pm - on private message
`js
Client.on('pm', function (by, message) {
//do stuff
});
`

Event: pmsucess - on pm sent confirmation
`js
Client.on('pmsucess', function (to, message) {
//do stuff
});
`

Event: userjoin - when an user joins a room
`js
Client.on('userjoin', function (room, user) {
//do stuff
});
`

Event: userleave - when an user leaves a room
`js
Client.on('userleave', function (room, user) {
//do stuff
});
`

Event: userrename - when an users changes its identity
`js
Client.on('userrename', function (room, oldName, newName) {
//do stuff
});
`

Event: queryresponse - when a query response is received
`js
Client.on('queryresponse', function (data) {
//do stuff
});
`

Event: popup - on popup received
`js
Client.on('popup', function (data) {
//do stuff
});
`

Event: raw - on raw, html or no label message received
`js
Client.on('raw', function (room, raw) {
//do stuff
});
`

Event: line - single message (only one line)
`js
Client.on('line', function (room, message, isIntro, splittedLine) {
//do stuff
});
`

Event: major - on major (labeled messages)
`js
Client.on('major', function (room, major, message, isIntro) {
//do stuff
});
`

Event: minor - on minor message (some battle messages)
`js
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