Leahnaya/pokemon-showdown
1
0
Fork 0
mirror of https://github.com/smogon/pokemon-showdown.git synced 2026-05-09 04:23:45 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity
ab0a5fdae2
pokemon-showdown/protocol-doc.md
Kevin Lau 7f83848a71 Document |win| and |tie| messages
2015-01-20 11:10:07 -08:00

486 lines
16 KiB
Markdown
Raw Blame History

Protocol
========
Pokemon Showdown's protocol is relatively simple.
Pokemon Showdown is implemented in SockJS. SockJS is a compatibility
layer over raw WebSocket, so you can actually connect to Pokemon
Showdown directly using WebSocket:
ws://sim.smogon.com:8000/showdown/websocket
or
wss://sim.smogon.com/showdown/websocket
Client-to-server messages
-------------------------
Messages from the user to the server are in the form:
ROOMID|TEXT
`ROOMID` can optionally be left blank if it's the lobby, or if the room
is irrelevant (for instance, if `TEXT` is a command like
`/join lobby` where it doesn't matter what room it's sent from, you can
just send `|/join lobby`.)
`TEXT` can contain newlines, in which case it'll be treated the same
way as if each line were sent to the room separately.
A partial list of available commands can be found with `/help`.
To log in, look at the documentation for the `|challstr|` server message.
Server-to-client messages
-------------------------
Messages from the server to the user are in the form:
>ROOMID
MESSAGE
MESSAGE
MESSAGE
...
`>ROOMID` and the newline after it can be omitted if the room is lobby
or global. `MESSAGE` cannot start with `>`, so it's unambiguous whether
or not `>ROOMID` has been omitted.
As for the payload: it's made of any number of blocks of data
separated by newlines; empty lines should be ignored. In particular,
it should be treated the same way whether or not it ends in a
newline, and if the payload is empty, the entire message should be ignored.
If `MESSAGE` doesn't start with `|`, it should be shown directly in the
room's log. Otherwise, it will be in the form:
|TYPE|DATA
For example:
|j| Some dude
|c|@Moderator|hi!
|c| Some dude|you suck and i hate you!
Some dude was banned by Moderator.
|l| Some dude
|b|battle-ou-12| Cool guy|@Moderator
This might be displayed as:
Some dude joined.
@Moderator: hi!
Some dude: you suck and i hate you!
Some dude was banned by Moderator.
Some dude left.
OU battle started between Cool guy and Moderator
For bandwidth reasons, there are five message types: `chat`, `join`, `leave`,
`name`, and `battle`, which are sometimes abbreviated to `c`, `j`, `l`, `n`,
and `b` respectively. All other message types are written out in full so they
should be easy to understand.
Four of these can be uppercase: `J`, `L`, `N`, and `B`, which are
the equivalent of their lowercase versions, but are recommended not to be
displayed inline because they happen too often. For instance, the main server
gets around 5 joins/leaves a second, and showing that inline with chat would
make it near-impossible to chat.
Some outgoing message types
---------------------------
`USER` = a user, the first character being their rank (users with no rank are
represented by a space), and the rest of the string being their username.
####Room initialization
`|init|ROOMTYPE`
> The first message received from a room when you join it. `ROOMTYPE` is
> one of: `chat` or `battle`
`|users|USERLIST`
> `USERLIST` is a comma-separated list of `USER`s, sent from chat rooms when
> they're joined.
####Room messages
`||MESSAGE` or `MESSAGE`
> We received a message `MESSAGE`, which should be displayed directly in
> the room's log.
`|html|HTML`
> We received an HTML message, which should be sanitized and displayed
> directly in the room's log.
`|join|USER` or `|j|USER`
> `USER` joined the room.
`|leave|USER` or `|l|USER`
> `USER` left the room.
`|name|USER|OLDID` or `|n|USER|OLDID`
> A user changed name to `USER`, and their previous userid was `OLDID`.
`|chat|USER|MESSAGE` or `|c|USER|MESSAGE`
> `USER` said `MESSAGE`. Note that `MESSAGE` can contain `|` characters,
> so you can't just split by `|` and take the fourth string.
`|:|TIMESTAMP`
`|c:|TIMESTAMP|USER|MESSAGE`
> `c:` is pretty much the same as `c`, but also comes with a UNIX timestamp;
> (the number of seconds since 1970). This is used for accurate timestamps
> in chat logs.
>
> `:` is the current time according to the server, so that times can be
> adjusted and reported in the local time in the case of a discrepancy.
>
> The exact fate of this command is uncertain - it may or may not be
> replaced with a more generalized way to transmit timestamps at some point.
`|battle|ROOMID|USER1|USER2` or `|b|ROOMID|USER1|USER2`
> A battle started between `USER1` and `USER2`, and the battle room has
> ID `ROOMID`.
####Battle messages
`|player|PLAYER|USERNAME|AVATAR`
> Appears when you join a battle room. `PLAYER` denotes which player it is
> (`p1` or `p2`) and `USERNAME` is the username. `AVATAR` is the player's
> avatar identifier (usually a number, but other values can be used for
> custom avatars).
|gametype|GAMETYPE
|gen|GENNUM
|tier|TIERNAME
|rated
|rule|RULE: DESCRIPTION
> Additional details when you join a battle room. `GAMETYPE` is one of
> `singles`, `doubles`, or `triples`; `GENNUM` denotes the generation of
> Pokemon being played; `tier` is the format; and `rule` appears multiple
> times, once for each clause in effect. `rated` only appears if the battle
> is rated.
|clearpoke
|poke|PLAYER|SPECIES
|poke|PLAYER|SPECIES
...
|teampreview
> These messages appear if you're playing a format that uses team previews.
> `PLAYER` is the player ID (see `|player|`) and `SPECIES` is the
> species of the Pokemon. `teampreview` commonly appears after `rule`
> tags instead of after the Pokemon in the team preview.
`|request|REQUEST`
> Gives a JSON object containing a request for a decision (to move or
> switch). To assist in your decision, `REQUEST.active` has information
> about your active Pokemon, and `REQUEST.side` has information about your
> your team as a whole.
`|inactive|MESSAGE` or `|inactiveoff|MESSAGE`
> A message related to the battle timer has been sent. The official client
> displays these messages in red.
>
> `inactive` means that the timer is on at the time the message was sent,
> while `inactiveoff` means that the timer is off.
`|start`
> Indicates that the game has started.
`|win|USER`
> `USER` has won the battle.
`|tie`
> The battle has ended in a tie.
**Major actions**
In battle, most Pokemon actions come in the form `|ACTION|POKEMON|DETAILS`
followed by a few messages detailing what happens after the action occurs.
A Pokemon is always identified in the form `POSITION: NAME`. `POSITION` is
the spot that the Pokemon is in: it consists of the `PLAYER` of the player
(see `|player|`), followed by a letter indicating the given Pokemon's
position, counting from `a`.
In doubles and triples battles, `a` will refer to the leftmost Pokemon
on one team and the rightmost Pokemon on the other (so `p1a` faces `p2c`,
etc). `NAME` is the nickname of the Pokemon performing the action.
`|move|POKEMON|MOVE|TARGET`
> The specified Pokemon has used move `MOVE` at `TARGET`. If a move has
> multiple targets or no target, `TARGET` should be ignored. If a move
> targets a side, `TARGET` will be a (possibly fainted) pokemon on that
> side.
>
> `move` can be tagged with `|[miss]` to indicate that the move missed.
`|switch|POKEMON|SPECIES|HP STATUS` or `|drag|POKEMON|SPECIES|HP STATUS`
> A Pokemon identified by `POKEMON` has switched in (the old Pokemon, if
> still there, is switched out).
>
> The new Pokemon has species `SPECIES`, HP `HP`, and status `STATUS`. `HP`
> is specified as a fraction; if it is your own Pokemon then it will be
> `CURRENT/MAX`, if not, it will be `/100` if HP Percentage Mod is in effect
> and `/48` otherwise. `STATUS` can be left blank, or it can be `slp`,
> `par`, etc.
>
> `switch` means it was intentional, while `drag` means it was unintentional
> (forced by Whirlwind, Roar, etc).
`|detailschange|POKEMON|FORME|HP STATUS` or
`|detailschange|POKEMON|FORME, GENDER|HP STATUS` or
`|-formechange|POKEMON|FORME|HP STATUS`
> The specified Pokemon has changed formes (via Mega Evolution, ability, etc.)
> to `FORME`. If the forme change cannot be reverted (Mega Evolution or a
> Shaymin-Sky that is frozen), then `detailschange` will appear; otherwise,
> the client will send `-formechange`. `GENDER` can appear in `detailschange`
> if the transforming Pokemon has a gender, displayed as `M` or `F`
> for male and female, respectively.
`|cant|POKEMON|REASON` or `|cant|POKEMON|REASON|MOVE`
> The Pokemon `POKEMON` could not perform a move because of the indicated
> `REASON` (such as paralysis, Disable, etc). Sometimes, the move it was
> trying to use is given.
`|faint|POKEMON`
> The Pokemon `POKEMON` has fainted.
**Minor actions**
Minor actions are less important than major actions. In the official client,
they're usually displayed in small font if they have a message. Pretty much
anything that happens in a battle other than a switch or the fact that a move
was used is a minor action. So yes, the effects of a move such as damage or
stat boosts are minor actions.
Minor actions often come with tags such as `|[from] EFFECT|[of] SOURCE`.
`EFFECT` will be an effect (move, ability, item, status, etc), and `SOURCE`
will be a Pokemon. These can affect the message or animation displayed, but
do not affect anything else. Other tags include `|[still]` (suppress
animation) and `|[silent]` (suppress message).
`|-fail|POKEMON|ACTION`
> The specified `ACTION` has failed against the `POKEMON` targetted. The `ACTION`
> in question can be a move that fails, or a stat drop blocked by an ability
> like Hyper Cutter, in which case `ACTION` will be `unboost|STAT`, where `STAT`
> indicates where the ability prevents stat drops. (For abilities that block all
> stat drops, like Clear Body, `|STAT` does not appear.)
`|-damage|POKEMON|HP STATUS`
> The specified Pokemon `POKEMON` has taken damage, and is now at
> `HP STATUS` (see `|switch|` for details).
>
> If `HP` is 0, `STATUS` should be ignored. The current behavior is for
> `STATUS` to be `fnt`, but this may change and should not be relied upon.
`|-heal|POKEMON|HP STATUS`
> Same as `-damage`, but the Pokemon has healed damage instead.
`|-status|POKEMON|STATUS`
> The Pokemon `POKEMON` has been inflicted with `STATUS`.
`|-curestatus|POKEMON|STATUS`
> The Pokemon `POKEMON` has recovered from `STATUS`.
`|-cureteam|POKEMON`
> The Pokemon `POKEMON` has used a move that cures its team of status effects,
> like Heal Bell.
`|-boost|POKEMON|STAT|AMOUNT`
> The specified Pokemon `POKEMON` has gained `AMOUNT` in `STAT`, using the
> standard rules for Pokemon stat changes in-battle. `STAT` is a standard
> three-letter abbreviation fot the stat in question, so Speed will be `spe`,
> Special Defense will be `spd`, etc.
`|-unboost|POKEMON|STAT|AMOUNT`
> Same as `-boost`, but for negative stat changes instead.
`|-weather|WEATHER`
> Indicates the weather that is currently in effect. If `|[upkeep]` is present,
> it means that `WEATHER` was active previously and is still in effect that
> turn. Otherwise, it means that the weather has changed due to a move or ability,
> or has expired, in which case `WEATHER` will be `none`.
`|-crit|POKEMON`
> A move has dealt a critical hit against the `POKEMON`.
`|-supereffective|POKEMON`
> A move was super effective against the `POKEMON`.
`|-resisted|POKEMON`
> A move was not very effective against the `POKEMON`.
`|-immune|POKEMON`
> The `POKEMON` was immune to a move.
`|-item|POKEMON|ITEM`
> The `ITEM` held by the `POKEMON` has been changed or revealed due to a move or
> ability. In addition, Air Balloon reveals itself when the Pokemon holding it
> switches in, so it will also cause this message to appear.
`|-enditem|POKEMON|ITEM`
> The `ITEM` held by `POKEMON` has been destroyed, and it now holds no item. This can
> be because of an item's own effects (consumed Berries, Air Balloon), or by a move or
> ability, like Knock Off. If a berry is consumed, it also has an additional modifier
> `|[eat]` to indicate that it was consumed. This message does not appear if the item's
> ownership was changed (with a move or ability like Thief or Trick), even if the move
> or ability would result in a Pokemon without an item.
`|-ability|POKEMON|ABILITY`
> The `ABILITY` of the `POKEMON` has been changed or revealed due to a move or ability.
> This also includes abilities that reveal themselves upon switch-in, like Mold Breaker.
> The only move tha does not trigger this message is Skill Swap, so that if you use Skill
> Swap between teammates in a doubles or triples battle, the abilities of the two Pokemon
> are not revealed to the opponent, similar to its behavior in game.
`|-endability|POKEMON`
> The `POKEMON` has had its ability surpressed, either by a move like Gastro Acid, or
> by the effects of Mummy.
`|-transform|POKEMON|SPECIES`
> The Pokemon `POKEMON` has transformed into `SPECIES` by the effect of Transform
> or the ability Imposter.
`|-activate|EFFECT`
> A miscellaneous effect has activated. This is triggered whenever an effect could
> not be better described by one of the other minor messages: for example, healing
> abilities like Water Absorb simply use `-heal`, and items that are consumed upon
> use have the `-enditem` message instead.
`|-hint|MESSAGE`
> Displays a message in parentheses to the client. Hint messages appear to explain and
> clarify why certain actions, such as Fake Out and Mat Block failing, have occurred,
> when there would normally be no in-game messages.
`|-message|MESSAGE`
> Displays a miscellaneous message to the client. These messages are primarily used
> for messages from game mods that aren't supported by the client, like rule clauses
> such as Sleep Clause, or other metagames with custom messages for specific scenarios.
> It is also used in triples battles for the automatic centering of Pokemon when only
> one remains on each side.
I'll document all the message types eventually, but for now this should be
enough to get you started. You can watch the data sent and received from
the server on a regular connection, or look at the client source code
for a full list of message types.
####Global messages
`|popup|MESSAGE`
> Show the user a popup containing `MESSAGE`. `||` denotes a newline in
> the popup.
`|pm|SENDER|RECEIVER|MESSAGE`
> A PM was sent from `SENDER` to `RECEIVER` containing the message
> `MESSAGE`.
`|usercount|USERCOUNT`
> `USERCOUNT` is the number of users on the server.
`|nametaken|USERNAME|MESSAGE`
> You tried to change your username to `USERNAME` but it failed for the
> reason described in `MESSAGE`.
`|challstr|KEYID|CHALLENGE`
> You just connected to the server, and we're giving you some information you'll need to log in.
>
> If you're already logged in and have session cookies, you can make an HTTP GET request to
> `http://play.pokemonshowdown.com/action.php?act=upkeep&challengekeyid=KEYID&challenge=CHALLENGE`
>
> Otherwise, you'll need to make an HTTP POST request to `http://play.pokemonshowdown.com/action.php`
> with the data `act=login&name=USERNAME&pass=PASSWORD&challengekeyid=KEYID&challenge=CHALLENGE`
>
> `USERNAME` is your username and `PASSWORD` is your password, and `KEYID` and
> `CHALLENGE` are the values you got from `|challstr|`. (Also feel free to make
> the request to `https://` if your client supports it.)
>
> Either way, the response will start with `]` and be followed by a JSON
> object which we'll call `data`.
>
> Finish logging in (or renaming) by sending: `/trn USERNAME,0,ASSERTION`
> where `USERNAME` is your desired username and `ASSERTION` is `data.assertion`.
`|updateuser|USERNAME|NAMED|AVATAR`
> Your name or avatar was successfully changed. Your username is now `USERNAME`.
> `NAMED` will be `0` if you are a guest or `1` otherwise. And your avatar is
> now `AVATAR`.
`|formats|FORMATSLIST`
> This server supports the formats specified in `FORMATSLIST`. `FORMATSLIST`
> is a `|`-separated list of `FORMAT`s. `FORMAT` is a format name with one or
> more of these suffixes: `,#` if the format uses random teams, `,,` if the
> format is only available for searching, and `,` if the format is only
> available for challenging.
> Sections are separated by two vertical bars with the number of the column of
> that section prefixed by `,` in it. After that follows the name of the
> section and another vertical bar.
`|updatesearch|JSON`
> `JSON` is a JSON object representing the current state of what battles the
> user is currently searching for.
`|updatechallenges|JSON`
> `JSON` is a JSON object representing the current state of who the user
> is challenging and who is challenging the user.
`|queryresponse|QUERYTYPE|JSON`
> `JSON` is a JSON object representing containing the data that was requested
> with `/query QUERYTYPE` or `/query QUERYTYPE DETAILS`.
>
> Possible queries include `/query roomlist` and `/query userdetails USERNAME`.
Reference in New Issue View Git Blame Copy Permalink