1. Abstract

The Cockatrice protocol is a client/server protocol intended for communication between
a card game client and a suitable server. It is designed with the goal in mind to make
playing card games, such as Magic the Gathering, over a network easy while eliminating
the possibility of unfair play. Because of that, the server stores all hidden information
and transmits pieces of it to clients only when necessary.

2. Protocol structure

All communication is done over a TCP/IP connection. The protocol is text based.
Strings are encoded in UTF-8 and have UNIX-style line endings (\n).

There are four distinct types of messages:
	- Command (section 3)
	- Response (section 4)
	- Event (section 5)
	- List (section 6)

3. Commands

A command can only be sent from client to server and has the following structure:
	{ID}|{command}|{parameter1}|{parameter2}...
"ID" is an arbitrary number to be chosen uniquely for each command.
"command" is a command identifier (see section 3).
It depends on the command identifier what has to be passed as parameters.

3.1 ping

Flags:
	none
Parameters:
	none
Valid response codes:
	ok

No effect.

3.2 login

Flags:
	none
Parameters:
	User name (string)
	Password (string)
Valid response codes:
	ok
	password

If the supplied credentials are correct, "ok" is returned and the connection state
is set to authenticated. (The server is not required to actually check the validity
of the credentials.)
Otherwise, "password" is returned.

3.3 list_games

Flags:
	login needed
Parameters:
	none
Valid response codes:
	ok

If the connection state is unauthenticated, "login_needed" is returned.
Otherwise, "ok" is returned and for each game currently, a list_games event XXX is
sent to the client. The "accepts game list changes" flag of the connection is set.

3.4 create_game

Flags:
	login needed
Parameters:
	Description (string)
	Password (string)
	Number of players (int)
Valid response codes:
	ok

A game with the given parameters is created. The client is set as creator of the
game and joins it automatically. The "accepts game list changes" flag of the connection
is unset.

3.5 join_game

Flags:
	login needed
Parameters:
	Game ID (int)
	Password (string)
Valid response codes:
	ok
	password

If the password for the given game is correct, the client leaves the current game
(if any) and joins the given game. The "accepts game list changes" flag of the connection
is unset.

3.6 leave_game

Flags:
	login needed
	game needed
Parameters:
	none
Valid response codes:
	ok
	
The client leaves the current game.

3.7 list_players

Flags:
	login needed
	game needed
Parameters:
	none


3.8 say
3.9 submit_deck
3.10 ready_start
3.11 shuffle
3.12 draw_cards
3.13 reveal_card
3.14 move_card
3.15 create_token
3.16 set_card_attr
3.17 inc_counter
3.18 add_counter
3.19 set_counter
3.20 del_counter
3.21 list_counters
3.22 list_zones
3.23 dump_zone
3.24 roll_dice
3.25 set_active_player
3.26 set_active_phase

4. Responses

After processing any command, the server sends a response to the client, indicating
whether the command was understood and valid.
A response can only be sent from server to client and has the following structure:
	resp|{ID}|{resp-code}

{ID} is the identifier belonging to the command in question.
{resp-code} contains information about the processing of the command. It can have the
following values:
	ok		(Success)
	login_needed	(Error: Command requires login)
	syntax		(Error: Invalid command or parameters)
	context		(Error: Command cannot be applied here)
	password	(Error: Wrong login data)

The response code "syntax" is valid as a response to any command and is
hence not explicitly listed in section 3. The response code "login_needed" applies
to all commands with the "login needed" flag.