Tic-tac-toe Protocol (TTTP) Version 0.0.1 2005-11-05 Carl Worth Richard Worth Kevin Worth carl@theworths.org richard@theworths.org kevin@theworths.org Introduction TTTP is a network protocol for playing the game tic-tac-toe. It permits a single server to host multiple games with named participants. The protocol is designed so that people can play using only telnet, but it is expected that graphical interfaces will be able to drive the protocol as well. TTTP borrows heavily from RRGP (Ricochet Robot Game Protocol) by Keith Packard and indirectly from other network protocols like SMTP using a synchronous command interface. Document Conventions All commands include a response (yeah, synchronous protocols are bad. tough) -> is one of: ERROR 1. Requests 1.1. Connection setup The TTTP server has no well defined port; agreement on which port to use must be done through some external mechanism. Once connected, the client must identify itself: HELO -> HELO Possible errors: INVALID_NAME 1.2. Global commands 1.2.1. Listing available users WHO -> WHO ... Lists connected users. Possible errors: NO_NAME_SET 1.2.2. STATISTICS STATISTICS -> STATISTICS " TICTACTOE WINS " Lists the statistics for the specified user. Possible errors: NO_NAME_SET, NO_USER 1.2.3. Message MESSAGE -> MESSAGE Sends a message to all connected users. The text must be a single token. Use a quoted-string to include spaces in the message text. Possible errors: NO_NAME_SET 1.2.4. Help HELP { } -> HELP { } " " Displays help. If is provided, displays more detailed help on a specific command, otherwise displays an overview of all commands. 1.2.5. Quit QUIT -> QUIT Disconnects the client from the server. 1.2.6. Version VERSION -> VERSION Negotiates version number between client and server. The server will respond with a version no higher than the client version number, but it may be lower. Version numbers are integers. This document describes protocol version 1. 1.3. Game management commands 1.3.1. Inviting a player to play a game INVITE -> INVITE Possible errors: NO_USER, BUSY, NO_NAME_SET 1.3.2. Accepting an invitation ACCEPT -> ACCEPT Possible errors: NO_USER, NO_NAME_SET 1.3.3. Retracting an invitiation RETRACT -> RETRACT Possible errors: NO_USER, NO_NAME_SET 1.3.3. Declining an invitation DECLINE -> DECLINE Possible errors: NO_USER, NO_NAME_SET 1.4. In-game commands is a game id generated by the server and first returned in NOTICE NEWGAME 1.4.1. Get the game contents SHOW -> SHOW is a quoted multi-line string containing an diagram of the tic-tac-toe board, which is a 3x3 array of cells: c|c|c c|c|c c|c|c c = '_' for empty or 'X' or 'O' for a played space For example: SHOW " _|X|O _|X|_ X|O|O" Possible errors: NO_NAME_SET, NO_GAME, NOT_IN_GAME 1.4.2. Part PART -> PART Departs the specified game Possible errors: NO_NAME_SET, NO_GAME, NOT_IN_GAME 1.4.3. Making a move MOVE -> MOVE indicates a number in the tic-tac-toe grid as follows: 0|1|2 3|4|5 6|7|8 Possible errors: NO_NAME_SET, NO_GAME, NOT_IN_GAME, NOT_YOUR_MOVE, NOT_GRID 2. Asynchronous notification. The server will send notices to each user in a game whenever there is a move. It will also send notices to every connected client when additional people join or new games are started. These are of the form: NOTICE Game-specific notices are sent to users involved in the related game, other notices are sent to all users. Note that even the user originating the notice receives a copy. 2.1. Global notices These notices are sent to all connected clients 2.1.1. New users NOTICE USER 2.1.2. Disconnected user NOTICE QUIT 2.1.3. Game invitation 2.1.3.1. Invitation is made NOTICE INVITE 2.1.3.2. Invitation is accepted NOTICE ACCEPT 2.1.3.3. Invitation is retracted NOTICE RETRACT 2.1.3.4. Invitation is declined NOTICE DECLINE The first username listed is the one performing the action. 2.1.4. New games NOTICE NEWGAME The first username listed will go first. 2.1.5. Terminated games NOTICE DISPOSE 2.1.6. Message NOTICE MESSAGE where is a quoted-string. Quotes escaped with '\"' 2.2. Game notices These notices are sent to all players and watchers in the affected game. is a game id generated by the server and first returned in NOTICE NEWGAME 2.2.1. Global game notices 2.2.1.1. Game over, and winner NOTICE GAMEOVER is either WON in which case indicates the winner or CATSGAME in which case is "". 2.2.2. Move notices 2.2.2.1. Move NOTICE MOVE 3. Errors The following error codes may be returned. 3.1. Connection setup errors These errors occur during connection setup. 3.1.1. No name set ERROR NO_NAME_SET 'helo' must be sent before any command other than 'help', 'version', 'quit'. Possibly returned by: WHO MESSAGE INVITE ACCEPT SHOW PART MOVE 3.1.2. Invalid name ERROR INVALID_NAME All names must be of non-zero length and must be unique. Possibly returned by: HELO 3.2. Command format errors Errors caused by ill-formed commands 3.2.1. Command ERROR COMMAND An invalid command was specified 3.2.2. Syntax ERROR SYNTAX A syntax error was detected 3.2.3. Not number ERROR NOT_NUMBER A non-numeric value was supplied where a number was required 3.2.4. Not a grid number ERROR NOT_GRID The number specified in the command was not a valid grid number 3.3. Global command errors. There are no errors from any of the global commands 3.4. Game management errors. Errors from game management commands 3.4.1. No such game ERROR NO_GAME A game name was provided that does not exist. 3.5. User information errors 3.5.1. No such user ERROR NO_USER A user name was provided that does not exist. 3.6. In-game errors 3.6.1. Global game errors 3.6.1.1. Not in game ERROR NOT_IN_GAME A game playing command was made, but the user is not a particpant of any game. Possibly returned by: MOVE 3.6.1.2. Not playing ERROR NOT_PLAYING A command was executed by a watching user that is permitted only to players 3.6.2. Moving errors 3.6.2.1. Not your turn ERROR NOT_YOUR_TURN A move was submitted during the other player's turn Possibly returned by: MOVE