SS Protocol Definition
June '01

Raison d'Etre

    This protocol was created to standardize communication between a NOOGA gameserver and all its possible clients when playing Dots. It says how information such as the scores, player numbers/names, and the board should be transmitted.

SENDING/RECEIVE

    Every SS transaction begins with either the string "SENDING" or "RECEIVE." These are used to tell the recipient that information is forthcoming, or information is expected to be sent back. If a transaction begins with "SENDING" then it is expected to be one-way, with no response from the recipient required. If the transaction begins with "RECIEVE" then a response containing the desired information is anticipated.
    Both of these (SENDING and RECEIVE) will be immediately followed by an elaboration of the information that is either forthcoming or desired. This elaboration also comes in the form of a simple string (ex. "updateBoard"). These string elaborations follow a naming convention similar to that of java in that the first letter is lowercase, while all letter beginning other words are uppercase.
 

Sending Information:

--The Board:
    The board in NOOGADots is represented by a matrix of ints, which show the status (drawn or not) of all the possible lines on the dots board. Accompanying this matrix is an array of ints which contain information about which players "own" (have completed) which squares.
    To send the board the initiator would begin be sending the string "SENDING" to signal that information will be forthcoming and none expected in return. The next string to follow is the elaboration of the information that is going to be sent, in this case its "updateBoard."
Now that the recipient knows that it's board information which is being sent, the size of the board follows. This size is the length of one-dimension of the board: 7 for a 7x7 dots board.
With knowledge of the size of the board the recipient knows how many characters to expect for the actual grid information on the board (49 for a 7x7 board). This grid information is send on a char per line basis. The ints from the board matrix are cast as chars for simplification of sending - this avoids having to send spaces or other number delimiters.
    To finalize the sending of the board grid information a separator is sent, by default this is a blank line. This separator follows the completetion of all the segments of updateBoard (grid information, owned squares, player number, and if the current player should recieve another turn).
    After the matrix information of the board has been sent, the sender follows with the string "ownedSquares" to inform the recipient that it is now going to send the information about the ownership of the squares. This allows to recipient to make sure it has gotten the right number of ints for it's matrix. The ownership squares is not preceeded by a size. It is sent in the game way as the grid information, ints cast as chars.
    Once the owned squars information is sent, it is followed by the separator, and then by the elaboration "numPlayers." This informs the recipient that an int (send as a string), representing the number of active players, will be sent.
    This number is again followed by the separator, and another elaboration - "again." This is used to inform that the current player should recieve another turn. It is followed either by the string "true" or "false" to show that the player should or should not, respectively, get another turn.
    The again elaboration is the last bit of information which is passed in under the update board call. To signify the completion of the transaction an EOT character is sent: a '.' (period) on a line by itself.

--A turn
    To inform a specific client that it is their turn to make a move, the server begins with the usual "SENDING" to show that it will be sending information with no repsonse expected. This is followed by the string "doTurn."
    This elaboration is unique in that it is not followed by an EOT. It should be immediately followed by an updateBoard elaboration, which in turn will send an EOT.

--Player Names
    ---Sending

    The sending of player names begins with the server issuing the "SENDING" string to the client. This is then followed by the elaboration: "playerNames." Directly after the elaboration, the number of player names that are coming is send in string format (ie "4"). A corresponding number of player names in string format are to follow. This list is terminated by the EOT character.

    ---Receiving

    To get the player name from a specific client, the server issues the "RECEIVE" keyword, followed by the "playerName" elaboration. The expected response is the players name in String format. The repsonse is terminated by an EOT character.

--Messages

    To send a text message to a client the server begins with the usual "SENDING" string followed by the elaboration "message." This is followed by a String message, and the EOT character. There is not standard for these messages, they are simply intended to provide the player with useful information.

--"Tick" (passage of gametime)

    To alert the client as to the passage of gametime the server passes the client the established "SENDING" string followed by the elaboration "tick." The tick elaboration is then followed by an int, sent as a string, which represents the time that the server understands to be remaining in the game. This is terminated by an EOT character.

--GameType

    A request for the game type is begun with the "RECIEVE" keyword and followed by the "gameType" elaboration. The intiator then expects to receive the game type of the client in string format, followed by an EOT.

--Setting the Player number

    To set the unique player number of a client, the server sends out a "SENDING" keyword followed by teh "playerNumber" elaboration. Then comes that player's unique player number in string format. This is terminated by an EOT.

--Has joined

    To query if a certain player has committed to a game the server issues the "RECEIVE" keyword followed by the "hasJoined" elaboration. If the response String is equals to "true" then the player is considered to be ready to enter a game. Any other response string is considered to signal an unready status.