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.
Any language that has a WebSocket client library can be used.
/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.
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.
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.
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.
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.loggedinisfalse, either the username, password, or challstr was incorrect - if
data.assertionstarts 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.
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|...
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.
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.
I don't know if this page is still up to date, but sending
curl -XPOST https://play.pokemonshowdown.com/~~showdown/action.php -d '{"act": "login", "name": "*****", "pass": "*****", "challstr": "4|....."}' -H "Content-Type: application/x-www-form-urlencoded; encoding=UTF-8"results inaction not found - make sure your request data includes act=something. Did I mess up somewhere?