Skip to content

Messages

What a line looks like

TAG [<id>] [<m>] command [data]

Parts in [ ] are not always there.

  • One line = one message.
  • Telnet: every line ends with a newline. A \r before the newline is fine. The server skips empty lines.
  • WebSocket: one WebSocket message = one line, with no newline in it. A message with a newline is a line the server can't read.
  • A line is at most 64 KB. A longer one gets session.error and the server disconnects you.

Tags

Tag Who sends it Means
REQ you "Please do this." (request). See Commands.
RES server "Here is my answer to your request." (response). OK, or an error.
EVT server "Something happened." (event). Not an answer to you.
PING you or server (telnet) "Are you still there?" See Telnet: PING and PONG.
PONG you or server (telnet) "Yes, I am here."

The parts

Example: REQ 7 m42 game.action {"type": "move", "move": 4}

Part When is it there? In the example
TAG always REQ
<id> on REQ and RES 7
<m> when the line is about one match m42
command always (not on PING/PONG) game.action
data depends on the command {"type": "move", "move": 4}
  • <id> and <m> never have a dot (.) in them.
  • command always has a dot: group.action, like game.action.

Placeholders

Every page uses these. Put in the real value.

  • Same placeholder in one example = same value.
  • Numbered (<id1>, <id2>, <other1>, <other2>) = different values.
Placeholder Means Who picks it
<id> Request ID. The answer has the same <id>. Use a new one for each request (count up: 1, 2, 3). you
<m> Match ID. The docs also call this the subject. server
<name> Your player name. You pick it when you log in. you
<other> Another player's name server
<session_token> Your session token. You get it when you log in. Save it to reconnect. server
<account_token> Your account token. You get it from the website. website
<game> tic-tac-toe, battleship or connect4 you
<move> Your move. What it looks like depends on the game. you
<CODE> Error code server
<reason> Error text for people server

How to parse a line

  1. The first word is the TAG.
  2. Look at the next words, one by one.
  3. Words without a dot come first: <id>, then <m>.
  4. The first word with a dot is the command.
  5. Everything after that is the data.

Data

Data is always one JSON object. Every value has a name, so there are no loose values.

Line Data
REQ <id> session.login {"player": "<name>"} {"player": "<name>"}
RES <id> OK {"session_token": "<session_token>"} {"session_token": "<session_token>"}
RES <id> ERR <CODE> {"reason": "<reason>"} {"reason": "<reason>"}
EVT <m> game.action {"type": "move", "player": "<other>", "move": <move>} {"type": "move", "player": "<other>", "move": <move>}

Rules:

  • The data comes last on the line.
  • Numbers have no quotes: {"move": 4}. Text has quotes: {"game": "connect4"}.
  • Write a quote inside text as \" and a newline as \n. A JSON library does this for you.
  • The order of the names doesn't matter.
  • Spaces between the parts of the JSON don't matter. The server leaves them out.
  • No data at all? Leave it off. REQ <id> lobby.ready is fine.
  • Data the server can't read as one JSON object counts as a line the server can't read.

Commands

  • Always lowercase.
  • Capitals matter: Game.Action does not work. Use game.action.
  • Groups: session.* (you), lobby.* (finding a match), game.* (playing).
  • Full list: Commands