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