157 lines
No EOL
3.7 KiB
Text
157 lines
No EOL
3.7 KiB
Text
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. |