Communication Overview

All communication is performed over TCP Sockets using UTF-8 encoded JSON messages.

Each JSON message must be preceded by sending a two-byte header indicating the length of the JSON message in bytes. (N.B. For UTF-8 strings, that's may not be the same as the string length.)

The server starts first and listens for connections on a particular port. Each client that connects the server (with a new TCP Socket) gets a new reader thread that listens for client-to-server communication.

The first command sent must be {"command":"start_game", "gametype":"com.foo.bar", "nick":"My Unique Name", ... }; the server cannot add the client to a game until it knows what type of game it wants to play, and it uses this opportunity to require a nice identifier for reporting. The server creates adds the player to a game-in-waiting (creating a game if necessary). If the game has enough players, the server asks the game to run itself in a new thread.

• When starting a new game clients may additionally specify "min_players":4 for the number of players to wait for before starting a game, and "rounds":10 to specify how many games in a row to play.

After sending this required message the client can send whatever it wants whenever it wants. As messages come in the server passes them on to the game, which asynchronously puts them into message queues per client. The game waits until each client's turn to process all "valid" messages. (More on that below.)

At the start of each client's turn the game will send {"command":"move", "state":xxx} to the client, where xxx is whatever the game chooses to send along as the current game state for that player. If the message queue for the client is empty, the server will wait quietly (and indefinitely) until at least one message comes in. The current logic here needs more robustness. The game will then keep processing messages from the queue until they are gone, or it hits an invalid message. (For example, the player has sent two moves, but the game only allows one move per turn.)

The messages that a client needs to send depends on the game; the only generally recognized message is {"command":"quit"}, though it is suggested that all games implement a move by the client as {"command":"move", ...}.

When a game is over the game will send each client the message {"command":"gameover", "winner":"nickname of winner"}. At this point the reader thread on the server will close down along with the associated socket. If the client wishes to play another game, it must reconnect with a new socket and start over at start_game.