The Core Protocol
All communications are sent as Java Objects using the standard Object{Input,Output}Stream method.
All objects sent must descend from nudoku.common.Packet
The client can be modeled as a simple state machine.
The communication is mostly asynchronous, though some state transitions require waiting for an acknowledgement.
The states are:
- CONNECTING
- The client is establishing a connection with the server. It has sent an initial Connect and is awaiting a response. When it receives a Connect back from the server it goes into the CONNECTED state.
- CONNECTED
- The client is connected, but not in a game. The server will periodically send a GameList. Sending a Join to the server will put the client into the JOINING state.
- JOINING
- The client is attempting to join a game. It may still receive Chatter packets from other players in the Lobby. Upon receipt of a JoinAck, it will move either into the BEFORE_GAME or CONNECTED state depending on the contents of the packet.
- BEFORE_GAME
- The client is awaiting the start of a game. Upon receipt of a GameStart packet, it will move into IN_GAME. The client may at this time send a Leave packet to return to the CONNECTED state.
- IN_GAME
- The game has started. The client may send Guess packets with no side-effect (besides perhaps ending the game). It may also send a Leave packet to return to CONNECTED. The server may at any time send ScoreBoardEntry? packets to inform the client of additions to the scoreboard. If a ScoreBoardEntry? packet is received containing the client's playername, the client should take it as implicit that the player has found the solution and act accordingly (the specific behaviour is left up to the UI implementor). Upon receipt of a GameOver packet it will move to AFTER_GAME.
- AFTER_GAME
- The game has finished. The client may remain in this state for as long as the user wishes, allowing them to examine the solution and the scoreboard. Sending a Leave puts the client back into the CONNECTED state.
There are two Packet types which can be sent in any state except CONNECTING. The Quit packet signals that the connections is over and the Chatter packet allows for conversation between players. The Chatter packet can be received at any time it can be sent. Any Chatter packets sent will be distributed according to the game joined, or to other players unjoined if not in a game.
If at any time the connection dies, the client is expected to either exit or to go back to the CONNECTING state. The server will not remember the player's name or any game state for that player.
Due to temporary mismatches between the client's state and the server's model of that state, the server may send packets which are inappropriate to the current state. In all cases, these can be safely discarded. eg. ScoreBoardEntry? after the client has sent a Leave packet. I believe I have avoided all possible races, as long as the client is careful to ignore inappropriate packets.
It might be worth mentioning that from the client's perspective, there is no difference between joining a game before it starts and joining a started game. The server takes care of ensuring that the client receives the right Packets in the right order.
There is an extension to this protocol for the Observer/Projector client. See ObserverProtocol.
