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 <error-code>
  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: INVALID_NAME
  51
  52 1.2. Global commands
  53
  54     1.2.1. Listing available users
  55
  56         WHO
  57
  58         ->
  59
  60         WHO <username1> <username2> ...
  61
  62         Lists connected users.
  63
  64         Possible errors: NO_NAME_SET
  65
  66     1.2.2. STATISTICS
  67
  68         STATISTICS <username>
  69
  70         ->
  71
  72         STATISTICS <username> "
  73         TICTACTOE WINS <wins>
  74         "
  75
  76         Lists the statistics for the specified user.
  77
  78         Possible errors: NO_NAME_SET, NO_USER
  79
  80     1.2.3. Message
  81
  82         MESSAGE <text>
  83
  84         ->
  85
  86         MESSAGE
  87
  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
  90         message text.
  91
  92         Possible errors: NO_NAME_SET
  93
  94     1.2.4. Help
  95
  96         HELP { <command> }
  97
  98         ->
  99
 100         HELP { <command> } "
 101         <overview or detailed help>
 102         "
 103
 104         Displays help.  If <command> is provided, displays more
 105         detailed help on a specific command, otherwise displays an
 106         overview of all commands.
 107
 108     1.2.5. Quit
 109
 110         QUIT
 111
 112         ->
 113
 114         QUIT
 115
 116         Disconnects the client from the server.
 117
 118     1.2.6. Version
 119
 120         VERSION <client-version-number>
 121
 122         ->
 123
 124         VERSION <server-version-number>
 125
 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.
 129
 130         This document describes protocol version 1.
 131
 132 1.3. Game management commands
 133
 134     1.3.1. Inviting a player to play a game
 135
 136         INVITE <username>
 137
 138         ->
 139
 140         INVITE
 141
 142         Possible errors: NO_NAME_SET, NO_USER, BUSY
 143
 144     1.3.2. Accepting an invitation
 145
 146         ACCEPT <username>
 147
 148         ->
 149
 150         ACCEPT
 151
 152         Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
 153
 154     1.3.3. Retracting an invitiation
 155
 156         RETRACT <username>
 157
 158         ->
 159
 160         RETRACT
 161
 162         Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
 163
 164     1.3.3. Declining an invitation
 165
 166         DECLINE <username>
 167
 168         ->
 169
 170         DECLINE
 171
 172         Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
 173
 174 1.4. In-game commands
 175
 176     <game> is a game id generated by the server and first returned in
 177     NOTICE NEWGAME
 178
 179     1.4.1. Get the game contents
 180
 181         SHOW <game>
 182
 183         ->
 184
 185         SHOW <game> <game-board>
 186
 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
 189         cells:
 190
 191         c|c|c
 192         c|c|c
 193         c|c|c
 194
 195         c = '_' for empty or 'X' or 'O' for a played space
 196
 197         For example:
 198
 199         SHOW <game> "
 200         _|X|O
 201         _|X|_
 202         X|O|O"
 203
 204         Possible errors: NO_NAME_SET, NO_GAME
 205
 206     1.4.2. Part
 207
 208         PART <game>
 209
 210         ->
 211
 212         PART
 213
 214         Departs the specified game
 215
 216         Possible errors: NO_NAME_SET, NO_GAME
 217
 218     1.4.3. Making a move
 219
 220         MOVE <game> <number>
 221
 222         ->
 223
 224         MOVE
 225
 226         <number> indicates a number in the tic-tac-toe grid as
 227         follows:
 228
 229         0|1|2
 230         3|4|5
 231         6|7|8
 232
 233         Possible errors: NO_NAME_SET, NO_GAME, NOT_PLAYING,
 234         NOT_YOUR_MOVE, NOT_GRID, NOT_VALID_MOVE
 235
 236 2. Asynchronous notification.
 237
 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:
 242
 243         NOTICE <notice-code> <args>
 244
 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.
 248
 249 2.1. Global notices
 250
 251     These notices are sent to all connected clients
 252
 253     2.1.1. New users
 254
 255         NOTICE USER <username>
 256
 257     2.1.2. Disconnected user
 258
 259         NOTICE QUIT <username>
 260
 261     2.1.3. Game invitation
 262
 263         2.1.3.1. Invitation is made
 264
 265                 NOTICE INVITE <username1> <username2>
 266
 267         2.1.3.2. Invitation is accepted
 268
 269                 NOTICE ACCEPT <username2> <username1>
 270
 271         2.1.3.3. Invitation is retracted
 272
 273                 NOTICE RETRACT <username1> <username2>
 274
 275         2.1.3.4. Invitation is declined
 276
 277                 NOTICE DECLINE <username2> <username1>
 278
 279         The first username listed is the one performing the action.
 280
 281     2.1.4. New games
 282
 283         NOTICE NEWGAME <game> <username> <username>
 284
 285         The first username listed will go first.
 286
 287     2.1.5. Terminated games
 288
 289         NOTICE DISPOSE <game>
 290
 291     2.1.6. Message
 292
 293         NOTICE MESSAGE <username> <text>
 294
 295         where <text> is a quoted-string. Quotes escaped with '\"'
 296
 297 2.2. Game notices
 298
 299     These notices are sent to all players and watchers in
 300     the affected game.
 301
 302     <game> is a game id generated by the server and first returned in
 303     NOTICE NEWGAME
 304
 305     2.2.1. Global game notices
 306
 307         2.2.1.1. Game over, and winner
 308
 309             NOTICE GAMEOVER <game> <outcome> <username>
 310
 311             <outcome> is either WON in which case <username> indicates
 312             the winner or CATSGAME in which case <username> is "".
 313
 314     2.2.2. Move notices
 315
 316         2.2.2.1. Move
 317
 318             NOTICE MOVE <game> <username> <number>
 319
 320 3. Errors
 321
 322     The following error codes may be returned.
 323
 324 3.1. Connection setup errors
 325
 326     These errors occur during connection setup.
 327
 328     3.1.1. No name set
 329
 330         ERROR NO_NAME_SET
 331
 332         'helo' must be sent before any command other than 'help',
 333         'version', 'quit'.
 334
 335         Possibly returned by: WHO, STATISTICS, MESSAGE, INVITE,
 336         ACCEPT, RETRACT, DECLINE, SHOW, PART, MOVE
 337
 338     3.1.2. Invalid name
 339
 340         ERROR INVALID_NAME
 341
 342         All names must be of non-zero length and must be unique,
 343         though case-insensitive.
 344
 345         Possibly returned by: HELO
 346
 347 3.2. Command format errors
 348
 349     Errors caused by ill-formed commands
 350
 351     3.2.1. Command
 352
 353         ERROR COMMAND
 354
 355         An invalid command was specified.
 356
 357     3.2.2. Syntax
 358
 359         ERROR SYNTAX
 360
 361         A syntax error was detected.
 362
 363     3.2.3. Not number
 364
 365         ERROR NOT_NUMBER
 366
 367         A non-numeric value was supplied where a number was required.
 368
 369         Possibly returned by: MOVE
 370
 371     3.2.4. Not a grid number
 372
 373         ERROR NOT_GRID
 374
 375         The number specified in the command was not a valid grid
 376         number.
 377
 378         Possibly returned by: MOVE
 379
 380 3.3. Global command errors.
 381
 382     There are no global command errors from any of the global
 383     commands.
 384
 385 3.4. Game management errors.
 386
 387     Errors from game management commands
 388
 389     3.4.1. No invitiation from/for specified user
 390
 391         ERROR NO_INVITE
 392
 393         An invitiation action was attempted where no invitation
 394         exists.
 395
 396         Possibly returned by: ACCEPT, RETRACT, DECLINE
 397
 398     3.4.2. No such game
 399
 400         ERROR NO_GAME
 401
 402         A game id was provided that does not exist.
 403
 404         Possibly returned by: SHOW, PART, MOVE
 405
 406 3.5. User information errors
 407
 408     3.5.1. No such user
 409
 410         ERROR NO_USER
 411
 412         A user name was provided that does not exist.
 413
 414         Possibly returned by: STATISTICS, INVITE, ACCEPT, RETRACT,
 415         DECLINE
 416
 417 3.6. In-game errors
 418
 419     3.6.1. Global game errors
 420
 421         3.6.1.1. Not playing
 422
 423             ERROR NOT_PLAYING
 424
 425             A command was executed by a watching user that is
 426             permitted only to players.
 427
 428             Possibly returned by: MOVE
 429
 430     3.6.2. Moving errors
 431
 432         3.6.2.1. Not your turn
 433
 434             ERROR NOT_YOUR_TURN
 435
 436             A move was submitted during the other player's turn.
 437
 438             Possibly returned by: MOVE
 439
 440         3.6.2.2. Not a valid move
 441
 442             ERROR NOT_VALID_MOVE
 443
 444             A move was submitted for a cell that is occupied.
 445
 446             Possibly returned by: MOVE