git.cworth.org Git - ttt/blob - PROTOCOL

   1                      Tic-tac-toe Protocol (TTTP)
   2                            Version 0.0.1
   3                              2005-11-05
   4
   5        Carl Worth           Richard Worth           Kevin Worth
   6    carl@theworths.org   richard@theworths.org   kevin@theworths.org
   7
   8 Introduction
   9
  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
  14 well.
  15
  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.
  19
  20 Document Conventions
  21
  22         All commands include a response (yeah, synchronous protocols are
  23         bad.  tough)
  24
  25         <command> <args>
  26
  27         ->
  28
  29         <response>
  30
  31         <response> is one of:
  32
  33         <command> <args>
  34         ERROR <message>
  35
  36 1. Requests
  37
  38 1.1 Connection setup
  39
  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:
  43
  44     HELO <username>
  45
  46     ->
  47
  48     HELO <username> <server-addr> <server-port>
  49
  50     Possible errors: INVALIDNAME
  51
  52 1.2. Global commands
  53
  54     1.2.1 Listing available users
  55
  56         WHO
  57
  58         ->
  59
  60         WHO <username1> <games1> <username2> <games2> ...
  61
  62         lists connected users and the number of games they've won.
  63
  64     1.2.2. Message
  65
  66         MESSAGE <text>
  67
  68         ->
  69
  70         MESSAGE
  71
  72     1.2.3. Help
  73
  74         HELP { <command> }
  75
  76         Displays help.  If <command> is provided, displays more
  77         detailed help on a specific command, otherwise displays an
  78         overview of all commands.
  79
  80     1.2.4. Quit
  81
  82         QUIT
  83
  84         ->
  85
  86         QUIT
  87
  88     1.2.5. Version
  89
  90         VERSION <client-version-number>
  91
  92         ->
  93
  94         VERSION <server-version-number>
  95
  96         Negotiates version number between client and server.  The server
  97         will respond with a version no higher than the client version
  98         number, but it may be lower.  Version numbers are integers.
  99
 100         This document describes protocol version 1.
 101
 102 1.3. Game management commands
 103
 104     1.3.1. Inviting a player to play a game
 105
 106         INVITE <username>
 107
 108         ->
 109
 110         INVITE
 111
 112         Possible errors: NOUSER, BUSY
 113
 114     1.3.2. Accepting an invitation
 115
 116         ACCEPT <username>
 117
 118         ->
 119
 120         ACCEPT
 121
 122 1.4. In-game commands
 123
 124     1.4.1. Get the game contents
 125
 126         SHOW
 127
 128         ->
 129
 130         SHOW <game-board>
 131
 132         <game-board> is a quoted multi-line string containing an
 133         diagram of the tic-tac-toe board, which is a 3x3 array of
 134         cells:
 135
 136         c|c|c
 137         c|c|c
 138         c|c|c
 139
 140         c = '_' for empty or 'X' or 'O' for a played space
 141
 142         For example:
 143
 144         SHOW "
 145         _|X|O
 146         _|X|_
 147         X|O|O"
 148
 149         Possible errors: NOTINGAME
 150
 151     1.4.2. Part
 152
 153         PART
 154
 155         ->
 156
 157         PART
 158
 159         Departs the current game
 160
 161         Possible errors: NOTINGAME
 162
 163     1.4.3. Making a move
 164
 165         MOVE <number>
 166
 167         ->
 168
 169         MOVE
 170
 171         <number> indicates a number in the tic-tac-toe grid as
 172         follows:
 173
 174         1|2|3
 175         4|5|6
 176         7|8|9
 177
 178         Possible errors: NOTINGAME, NOTYOURMOVE, NOTGRID
 179
 180 2. Asynchronous notification.
 181
 182     The server will send notices to each user in a game whenever
 183     there is a move. It will also send notices to every connected
 184     client when additional people join or new games are
 185     started. These are of the form:
 186
 187         NOTICE <notice-code> <args>
 188
 189     Game-specific notices are sent to users involved in the related
 190     game, other notices are sent to all users.  Note that even the user
 191     originating the notice receives a copy.
 192
 193 2.1. Global notices
 194
 195     These notices are sent to all connected clients
 196
 197     2.1.1. New users
 198
 199         NOTICE USER <username>
 200
 201     2.1.2. Disconnected user
 202
 203         NOTICE QUIT <username>
 204
 205     2.1.3. Game invitation
 206
 207         NOTICE INVITE <username>
 208
 209     2.1.4. Terminated games
 210
 211         NOTICE DISPOSE <game>
 212
 213     2.1.5. Message
 214
 215         NOTICE MESSAGE <username> <text>
 216
 217 2.2. Game notices
 218
 219     These notices are sent to all players and watchers in
 220     the affected game
 221
 222     2.2.1. Global game notices
 223
 224         2.2.1.1. New game begins
 225
 226             NOTICE NEWGAME <username> <username>
 227
 228             The first username listed will go first
 229
 230         2.2.1.2. Game over, and winner
 231
 232             NOTICE GAMEOVER <outcome> <username>
 233
 234             <outcame> is either WON in which case <username> indicates
 235             the winner or CATSGAME in which case <username> is "".
 236
 237     2.2.2. Move notices
 238
 239         2.2.2.1. Move
 240
 241             NOTICE MOVE <username> <number>
 242
 243 3. Errors
 244
 245     The following error codes may be returned.
 246
 247 3.1. Connection setup errors
 248
 249     These errors occur during connection setup.
 250
 251     3.1.1. No name set
 252
 253         ERROR NONAMESET
 254
 255         'helo' must be sent before any command other than 'quit'.
 256
 257     3.1.2. Invalid name
 258
 259         ERROR INVALIDNAME
 260
 261         All names must be of non-zero length and must be unique.
 262
 263         Possibly returned by: HELO
 264
 265 3.2. Command format errors
 266
 267     Errors caused by ill-formed commands
 268
 269     3.2.1. Command
 270
 271         ERROR COMMAND
 272
 273         An invalid command was specified
 274
 275     3.2.2. Syntax
 276
 277         ERROR SYNTAX
 278
 279         A syntax error was detected
 280
 281     3.2.3. Not number
 282
 283         ERROR NOTNUMBER
 284
 285         A non-numeric value was supplied where a number was required
 286
 287     3.2.4. Not a grid number
 288
 289         ERROR NOTGRID
 290
 291         The number specified in the command was not a valid grid number
 292
 293 3.3. Global command errors.
 294
 295     There are no errors from any of the global commands
 296
 297 3.4. Game management errors.
 298
 299     Errors from game management commands
 300
 301     3.4.1. No such game
 302
 303         ERROR NOGAME
 304
 305         A game name was provided that does not exist.
 306
 307 3.5. User information errors
 308
 309     3.5.1. No such user
 310
 311         ERROR NOUSER
 312
 313         A user name was provided that does not exist.
 314
 315 3.6. In-game errors
 316
 317     3.6.1. Global game errors
 318
 319         3.6.1.1. Not in game
 320
 321             ERROR NOTINGAME
 322
 323             A game playing command was made, but the user is not a
 324             particpant of any game.
 325
 326             Possibly returned by: MOVE
 327
 328         3.6.1.2. Not playing
 329
 330             ERROR NOTPLAYING
 331
 332             A command was executed by a watching user that is
 333             permitted only to players
 334
 335     3.6.2. Moving errors
 336
 337         3.6.2.1. Not your turn
 338
 339             ERROR NOTYOURTURN
 340
 341             A move was submitted during the other player's turn
 342
 343             Possibly returned by: MOVE