Kaiepi/ps-bot-faq.md Secret

## ps-bot-faq.md

      
    Raw
  

              ps-bot-faq.md
            
          
    Pokémon Showdown Bot F.A.Q.

What is a bot?

A bot is nothing more than a client for a Pokémon Showdown server. When you visit play.pokemonshowdown.com, you are using a client.
What language should I write my bot in?

Any language that has a WebSocket client library can be used.
Are there any references I can use to help me write my bot?

/rfaq bots includes a list of repositories for bots users in Bot Development have written. Node.js, Python, Lua, Rust, and Raku are among the languages some have been written in.
What do I need to do to write a bot?

A bot must do two things at minimum:

establish a connection with a Pokémon Showdown server
be able to understand and communicate with the server using Pokémon Showdown's protocol

Some of Pokémon Showdown's protocol is documented in PROTOCOL.md, but not all of it. I recommend opening up your browser's console (F12) to see exactly what messages the server sends and when. You may also need to inspect what the HTTP requests for connecting to the server look like if you're, say, writing a bot for a server other than sim2.psim.us (main). This can be done by clicking on the Network tab in the browser console.
It's important to note that the order messages get sent in isn't guaranteed to be the same every time. For instance, sometimes you will receive your own join message after joining a room, sometimes you won't. Your bot needs to be robust enough to handle such inconsistencies.
How do I make my bot log in?

After connecting to the server, it will send a |challstr| message containing a nonce. From here, there are two different ways to select an account. These will be explained separately.
How do I make my bot log in to an unregistered account?

Make a GET request to https://play.pokemonshowdown.com/~~showdown/action.php. The following parameters must be included in the URL:

act: must be getassertion
userid: must be the user ID you want to use
challstr: the nonce you received from the server

For example, here's the HTTP request for a GET request to attempt to use "morfent" as a username:
GET /~~showdown/action.php?act=getassertion&userid=morfent&challstr=4|... HTTP/1.1
Host: play.pokemonshowdown.com

The server will return what's called an assertion as a response. The following are considered errors:

if the assertion is just ";", this indicates that the username given is registered
if the assertion begins with ";;", this indicates any other type of error occurred while logging in

What to do with the assertion will be explained later.
How do I make my bot log in to a registered account?

Make a POST request to https://pokemonshowdown.com/~~showdown/action.php. A Content-Type header must be specified as being application/x-www-form-urlencoded; encoding=UTF-8. The body of the request must be a JSON object containing the following keys:

act: must be "login"
name: the username wanted
pass: the password wanted
challstr: the nonce received from the server

For example, here's an HTTP request to log in as "bongsniffer69" (note: lacks a real nonce):
POST /~~showdown/action.php HTTP/1.1
Host: play.pokemonshowdown.com
Content-Type: application/x-www-form-urlencoded; encoding=UTF-8

act=login&name=bongsniffer69&pass=notmyrealpasswordlol&challstr=4%7C...

The server will return what's called an assertion as a response. It is another JSON object prefixed with "]". Most of the metadata included isn't important; here's all you need to care about, given a variable data containing the JSON object:

if data.curuser.loggedin is false, either the username, password, or challstr was incorrect
if data.assertion starts with ";;", any other type of error occurred while logging in

Keep data.assertion and ignore the rest of the metadata. What you do with the assertion will be explained later.
OK, I have an assertion, now what do I do with it?

Send a /trn message to the global room. /trn takes three parameters, separated by commas:

a username
an avatar
an assertion

For example:
|/trn Morfent,128,4|...

Where should I host my bot?

I heavily recommend shelling out the money for a VPS to host your bot on. DigitalOcean and Vultr have $5 monthly VPSes that are perfectly capable of running a bot, and you have plenty of freedom when it comes to what you're capable of running on the VPS. glitch.me is a free option, but it is not a VPS and is heavily restricted in comparison.
WTF? Why is my bot locked?

Pokémon Showdown automatically locks users on hosts configured as untrustworthy proxies. This happens to include popular VPS options and glitch.me. Ask an RO to unlock your bot and make it a trusted user so it doesn't get locked again.