-------------------------------------------------------------------------------- Goals and Design Considerations -------------------------------------------------------------------------------- - Text based - Simple, easy to remember - Extensible - Support versioning - OS, game, and client agnostic -------------------------------------------------------------------------------- What Needs To Happen -------------------------------------------------------------------------------- Server Related: Protocol Identification Acknowledge client and server are talking the same Server identification Name, description Plugins/game types loaded and available Game types, versions Stats Games played, games currently going, bandwidth, memory usage Game Related Current games looking for another player Game's settings/parameters (clock, difficulty, time limit, etc) Join game Start game Set options of a game Begin game Both clients synced, set up, and ready to play Quit game With draw, lose, neither Game over Server determines one of the players has one, tells both, records it, etc -------------------------------------------------------------------------------- Command Reference -------------------------------------------------------------------------------- Formatting: - All commands are a single, uninterrupted sequence of characters. The end of the command is denoted by a space of end of line indicator. - Valid characters: ASCII values are [48,57] and [97,122] (ie A-Z and a-z) - Reasoning: Parsing and usage simplicity, locale independent plain text - Parameters are also space delimited sequence of characters. - They can, however, be enclosed in double quotes. - Any double quote not indicating beginning or ending of string must be escaped with a single backslash (\). - Valid characters: ASCII values are [33, 126] (A-z, a-z, and symbols) - Reasoning: Maximum flexibility for parameter names a values. - Whitespace denotes end of command and each following parameter - All commands, from client or from server) are on a single line - Lines are ended with either a and/or (ASCII 10 and/or 13) - Allows for pretty much any client to use \n and be "ok" - Note: Explicitly OK to send - Multiple commands can be sent in one request - Guaranteed to be processed in order received and one at a time. Example: command (optional parm1 | parm2 | ...) [required parm1 | parm2 | ...] Description of command and what it accomplishes. Server Commands and Response Commands: didcgaf didcgaf id servinfo gametypes typesupport hastype servresult desctype typeinfo stats servstats opengames lobby/lobbytype/lobbytypever joingame servresult creategame servresult ready servresult draw servresult quit servresult setopt servresult setgameopt servresult move servresult Server Command Descriptions: didcgaf [version] (user_agent_string) Protocol sync. user_agent_string is only informational (like HTTP's). id Server identification. gametypes Request a list of all supported game types. hastype [type] (version) Determine if server has support for specific game type and optional version. desctype [type] (version) Description of game type, optionally of a specific version. stats Any stats the server has available and is willing to share. opengames (type (version)) All open games the server has. If type sent, then just a list of ids. If no type sent, then a list of types and ids. joingame [gameid] Join a game that already exists on the server. creategame [type] (version) Create a new game on the server. Attempt to create a game on the server. If no version is provided, the newest one loaded on the server will be used. ready [yes | no] Change your ready status on the server. When a game is full and all players are ready, the game begins. draw Request from server and other player(s) that the game ends with no outcome. quit Immediately quits the game with the game being marked as a loss for you. setopt [name] [value] Attempt to set an option of the server. setgameopt [name] [value] Attempt to set an option of the game. Only valid to be sent by the creator of the game and between the successful call of creategame and before the receipt of the startgame command. move [move_information] Submit your move to the server and, if valid, all subsequent players. Contents of move_information is dependent on game type. clientresult [yes | no] [in_response_to] (additional_information) Confirms the client has accepted a command, such as another players move. Client Valid Commands and Responses didcgaf servinfo typesupport typeinfo servstats lobby lobbytype lobbytypever startgame movemade makemove move gameover playerjoined playerleft playerready servresult Client Commands didcgaf [version] (server_agent_string) Protocol sync. server_agent_string is only informational (like HTTP's). servinfo [name] [description] General server information. tyepsupport (type1) (version1) (type2) (version2) (...) (typeN) (versionN) List game types names and versions. typeinfo [type] [version] [description] (...) Game type name, version, and description. If in response to a type request where no version was sent, multiple name/version/descriptions can be returned as the server may support multiple versions loaded at once. servstats (key1) (val1) (key2) (val2) (...) (keyN) (valN) Any number, including zero, of keys and values. Absolutely no requirement on contents and is purely informational. This MUST, however, be sent in response to the stats command (even if it it will be empty). lobby [count] (type1) (version1) (gameid1) (...) (typeN) (versionN) (gameidN) A list of all open games on the server. Sent in response to an opengames command that had no type or version. lobbytype [count] [type] (version1) (gameid1) (...) (versionN) (gameidN) List of all open games on the server of a specific type. Sent in response to an opengames command that had a type but no version. lobbytypever [count] [type] [version] (gameid1) (...) (gameidN) List of all open games on the server of a specific type. Sent in response to an opengames command that had a type but no version. startgame Once all players have their ready status as yes, the server begins the game by sending this to all players. movemade [player_number] [move_string] Sent when another player has successfully made a move. move_string is dependent on the game type. Moves are validated server side and cannot be contested by other players. makemove Request a move from the receiving player. gameover [winning_player_number] Sent two all players when the game is over. If the game has ended in a draw, the player number will be 0. playerjoined [player_number] Sent when a new player joins a game to all existed players and joining player receives one for each existing player. playerleft [player_number] [reason] Sent to all remaining players when a player leaves the game (quit, forfeit, disconnect, etc). playerready [player_number] [yes | no] Sent to all other players in the game whenever a player changes their ready status. servresult [yes | no] [in_response_to] (additional_information) The result of a request on the client side that can be answered as yes/no. The second parameter, in_response_to, contains the command being responded to for assisting clients that may be making a multiple requests before receiving all responses. The last parameter can contain any additional information, such as an error message or description.