1 Tic-tac-toe Protocol (TTTP)
5 Carl Worth Richard Worth Kevin Worth
6 carl@theworths.org richard@theworths.org kevin@theworths.org
10 TTTP is a network protocol for playing the game tic-tac-toe. It permits
11 a single server to host multiple games with named participants. The
12 protocol is designed so that people can play using only telnet, but it is
13 expected that graphical interfaces will be able to drive the protocol as
16 TTTP borrows heavily from RRGP (Ricochet Robot Game Protocol) by Keith
17 Packard and indirectly from other network protocols like SMTP using a
18 synchronous command interface.
22 All commands include a response (yeah, synchronous protocols are
40 The TTTP server has no well defined port; agreement on which port to
41 use must be done through some external mechanism. Once connected,
42 the client must identify itself:
48 HELO <username> <server-addr> <server-port>
50 Possible errors: INVALID_NAME
54 1.2.1. Listing available users
60 WHO <username1> <username2> ...
62 Lists connected users.
64 Possible errors: NO_NAME_SET
72 STATISTICS <username> "
76 Lists the statistics for the specified user.
78 Possible errors: NO_NAME_SET, NO_USER
88 Sends a message to all connected users. The text must be a
89 single token. Use a quoted-string to include spaces in the
92 Possible errors: NO_NAME_SET
101 <overview or detailed help>
104 Displays help. If <command> is provided, displays more
105 detailed help on a specific command, otherwise displays an
106 overview of all commands.
116 Disconnects the client from the server.
120 VERSION <client-version-number>
124 VERSION <server-version-number>
126 Negotiates version number between client and server. The server
127 will respond with a version no higher than the client version
128 number, but it may be lower. Version numbers are integers.
130 This document describes protocol version 1.
132 1.3. Game management commands
134 1.3.1. Inviting a player to play a game
142 Possible errors: NO_NAME_SET, NO_USER, BUSY
144 1.3.2. Accepting an invitation
152 Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
154 1.3.3. Retracting an invitiation
162 Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
164 1.3.3. Declining an invitation
172 Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
174 1.4. In-game commands
176 <game> is a game id generated by the server and first returned in
179 1.4.1. Get the game contents
185 SHOW <game> <game-board>
187 <game-board> is a quoted multi-line string containing an
188 diagram of the tic-tac-toe board, which is a 3x3 array of
195 c = '_' for empty or 'X' or 'O' for a played space
204 Possible errors: NO_NAME_SET, NO_GAME
214 Departs the specified game
216 Possible errors: NO_NAME_SET, NO_GAME
226 <number> indicates a number in the tic-tac-toe grid as
233 Possible errors: NO_NAME_SET, NO_GAME, NOT_PLAYING,
234 NOT_YOUR_MOVE, NOT_GRID, NOT_VALID_MOVE
236 2. Asynchronous notification.
238 The server will send notices to each user in a game whenever
239 there is a move. It will also send notices to every connected
240 client when additional people join or new games are
241 started. These are of the form:
243 NOTICE <notice-code> <args>
245 Game-specific notices are sent to users involved in the related
246 game, other notices are sent to all users. Note that even the user
247 originating the notice receives a copy.
251 These notices are sent to all connected clients
255 NOTICE USER <username>
257 2.1.2. Disconnected user
259 NOTICE QUIT <username>
261 2.1.3. Game invitation
263 2.1.3.1. Invitation is made
265 NOTICE INVITE <username1> <username2>
267 2.1.3.2. Invitation is accepted
269 NOTICE ACCEPT <username2> <username1>
271 2.1.3.3. Invitation is retracted
273 NOTICE RETRACT <username1> <username2>
275 2.1.3.4. Invitation is declined
277 NOTICE DECLINE <username2> <username1>
279 The first username listed is the one performing the action.
283 NOTICE NEWGAME <game> <username> <username>
285 The first username listed will go first.
287 2.1.5. Terminated games
289 NOTICE DISPOSE <game>
293 NOTICE MESSAGE <username> <text>
295 where <text> is a quoted-string. Quotes escaped with '\"'
299 These notices are sent to all players and watchers in
302 <game> is a game id generated by the server and first returned in
305 2.2.1. Global game notices
307 2.2.1.1. Game over, and winner
309 NOTICE GAMEOVER <game> <outcome> <username>
311 <outcome> is either WON in which case <username> indicates
312 the winner or CATSGAME in which case <username> is "".
318 NOTICE MOVE <game> <username> <number>
322 The following error codes may be returned.
324 3.1. Connection setup errors
326 These errors occur during connection setup.
332 'helo' must be sent before any command other than 'help',
335 Possibly returned by: WHO, STATISTICS, MESSAGE, INVITE,
336 ACCEPT, RETRACT, DECLINE, SHOW, PART, MOVE
342 All names must be of non-zero length and must be unique,
343 though case-insensitive.
345 Possibly returned by: HELO
347 3.2. Command format errors
349 Errors caused by ill-formed commands
355 An invalid command was specified.
361 A syntax error was detected.
367 A non-numeric value was supplied where a number was required.
369 Possibly returned by: MOVE
371 3.2.4. Not a grid number
375 The number specified in the command was not a valid grid
378 Possibly returned by: MOVE
380 3.3. Global command errors.
382 There are no global command errors from any of the global
385 3.4. Game management errors.
387 Errors from game management commands
389 3.4.1. No invitiation from/for specified user
393 An invitiation action was attempted where no invitation
396 Possibly returned by: ACCEPT, RETRACT, DECLINE
402 A game id was provided that does not exist.
404 Possibly returned by: SHOW, PART, MOVE
406 3.5. User information errors
412 A user name was provided that does not exist.
414 Possibly returned by: STATISTICS, INVITE, ACCEPT, RETRACT,
419 3.6.1. Global game errors
425 A command was executed by a watching user that is
426 permitted only to players.
428 Possibly returned by: MOVE
432 3.6.2.1. Not your turn
436 A move was submitted during the other player's turn.
438 Possibly returned by: MOVE
440 3.6.2.2. Not a valid move
444 A move was submitted for a cell that is occupied.
446 Possibly returned by: MOVE