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