Connecting¶

Steps¶

open the connection
  → say hello, with your protocol version
  → log in
  → play (send REQ, get RES and EVT)
  → connection ends
      → you get a short time to come back
      → come back in time, or you lose the match

• Your WebSocket or socket library opens the connection. The protocol starts after that, with your hello.
• REQ, RES and EVT are the tags that start each line.
• The commands page lists what you can send while you play.
• Connection ends? See Reconnecting.
• Leaving on purpose? See Disconnecting.

WebSocket or telnet?¶

Both use the same lines.

Say hello¶

• You talk first. When the connection is open, send session.hello with the protocol version your client uses.
• The server sends nothing before your hello.
• Any other request before it gives ERR HANDSHAKE_REQUIRED.

C: REQ <id> session.hello {"version": 1}
S: RES <id> OK

• OK means the server knows you are there and speaks your version.
• Connected with an account token in the address? Then the OK also carries your session token: RES <id> OK {"session_token": "<session_token>"}.

Wrong version? The server answers with a FATAL error and disconnects:

S: RES <id> ERR FATAL VERSION_MISMATCH {"reason": "<reason>"}

• The server will not switch versions for you. The <reason> names the version it uses.

Log in¶

You log in as a guest or with an account. Both ways give you a session token.

As a guest¶

Pick a name. On telnet and on WebSocket (connect to /ws), log in after your hello:

C: REQ <id> session.login {"player": "<name>"}
S: RES <id> OK {"session_token": "<session_token>"}

• Login failed? You get ERR AUTH_FAILED. You can try again.

With an account¶

First log in on the website. You get an account token.

WebSocket:

1. Connect to /ws?account_token=<account_token>.
2. Bad account token? The server refuses the connection with HTTP 401.
3. Say hello. The OK carries your session token. No session.login needed.
4. Your account is already logged in on another connection? The hello answers ERR AUTH_FAILED instead. To take over that session, reconnect with its session token.

Telnet has no address to put the token in, so log in with it after your hello:

C: REQ <id> session.login {"account_token": "<account_token>"}
S: RES <id> OK {"session_token": "<session_token>"}

• Bad account token on telnet? You get ERR AUTH_FAILED.
• Your player name is your account name.

Tokens¶

• Save the session token. You need it to reconnect.
• Keep your account token secret. It logs in as you.

Rules¶

• One login per name. If the name is already logged in, you get ERR AUTH_FAILED. The other connection stays logged in.
• Lost your connection? You keep your name, your lobby place and your matches for a short time. See Reconnecting. After that your name is free again and your session token stops working.
• One login per connection. Sending session.login or session.reconnect after you are logged in gives ERR AUTH_FAILED.

Is the connection alive?¶

Telnet: PING and PONG¶

S: PING
C: PONG

• If you get PING, answer PONG.
• Any line you send counts as an answer. A client that sends requests often is fine without PONG.
• You can send PING too. The server answers PONG.
• No answer in time counts as a lost connection. The server closes it. See Reconnecting.

WebSocket: ping frames¶

• The server sends WebSocket ping frames. Your WebSocket library answers them for you.
• Your library only answers while your program keeps reading messages. Keep reading.
• No PING/PONG lines on WebSocket.
• No answer counts as a lost connection. See Reconnecting.