hunt/README.protocol

   1
   2 THE HUNT PROTOCOL
   3 =================
   4
   5 These are some notes on the traditional INET protocol between hunt(6) and
   6 huntd(6) as divined from the source code.
   7
   8 (In the original hunt, AF_UNIX sockets were used, but they are not
   9 considered here.)
  10
  11 The game of hunt is played with one server and several clients. The clients
  12 act as dumb 'graphics' clients in that they mostly only ever relay the
  13 user's keystrokes to the server, and the server usually only ever sends
  14 screen-drawing commands to the client. ie, the server does all the work.
  15
  16 The game server (huntd) listens on three different network ports which
  17 I'll refer to as W, S and P, described as follows:
  18
  19         W       well known UDP port (26740, or 'udp/hunt' in netdb)
  20         S       statistics TCP port
  21         P       game play TCP port
  22
  23 The protocol on each port is different and are described separately in
  24 the following sections.
  25
  26 Lines starting with "C:" and "S:" will indicate messages sent from the
  27 client (hunt) or server (huntd) respectively.
  28
  29 W - well known port
  30 -------------------
  31         This server port is used only to query simple information about the
  32         game such as the port numbers of the other two ports (S and P),
  33         and to find out how many players are still in the game.
  34
  35         All datagrams sent to (and possibly from) this UDP port consist of
  36         a single unsigned 16-bit integer, encoded in network byte order.
  37
  38         Server response datagrams should be sent to the source address
  39         of the client request datagrams.
  40
  41         It is not useful to run multiple hunt servers on the one host
  42         interface, each of which perhaps listen to the well known port and
  43         respond appropriately. This is because clients will not be able to
  44         disambiguate which game is which.
  45
  46         It is reasonable (and expected) to have servers listen to a
  47         broadcast or multicast network address and respond, since the
  48         clients can extract a particular server's network address from
  49         the reply packet's source field.
  50
  51     Player port request
  52
  53         A client requests the game play port P with the C_PLAYER message.
  54         This is useful for clients broadcasting for any available games. eg:
  55
  56                 C: {uint16: 0 (C_PLAYER)}
  57                 S: {uint16: P (TCP port number for the game play port)}
  58
  59         The TCP address of the game play port should be formed from the
  60         transmitted port number and the source address as received by
  61         the client.
  62
  63     Monitor port request
  64
  65         A client can request the game play port P with the C_MONITOR message.
  66         However, the server will NOT reply if there are no players in
  67         the game. This is useful for broadcasting for 'active' games. eg:
  68
  69                 C: {uint16: 1 (C_MONITOR)}
  70                 S: {uint16: P (TCP port number for the game play port)}
  71
  72     Message port request
  73
  74         If the server receives the C_MESSAGE message it will
  75         respond with the number of players currently in its game, unless
  76         there are 0 players, in which case it remains silent. This
  77         is used when a player wishes to send a text message to all other
  78         players, but doesn't want to connect if the game is over. eg:
  79
  80                 C: {uint16: 2 (C_MESSAGE)}
  81                 S: {uint16: n (positive number of players)}
  82
  83     Statistics port request
  84
  85         The server's statistics port is queried with the C_SCORES message.
  86         eg:
  87
  88                 C: {uint16: 3 (C_SCORES)}
  89                 S: {uint16: S (TCP port number for the statistics port)}
  90
  91
  92 S - statistics port
  93 -------------------
  94         The statistics port accepts a TCP connection, and keeps
  95         it alive for long enough to send a text stream to the client.
  96         This text consists of the game statistics. Lines in the
  97         text message are terminated with the \n (LF) character.
  98
  99                 C: <connect>
 100                 S: <accept>
 101                 S: {char[]: lines of text, each terminated with <LF>}
 102                 S: <close>
 103
 104         The client is not to send any data to the server with this
 105         connection.
 106
 107 P - game play port
 108 ------------------
 109         This port provides the TCP channel for the main game play between
 110         the client and the server.
 111
 112         All integers are unsigned, 32-bit and in network byte order.
 113         All fixed sized octet strings are ASCII encoded, NUL terminated.
 114
 115     Initial connection
 116
 117         The initial setup protocol between the client and server is as follows.
 118         The client sends some of its own details, and then the server replies
 119         with the version number of the server (currently (uint32)-1).
 120
 121                 C: <connect>
 122                 S: <accept>
 123                 C: {uint32:   uid}
 124                 C: {char[20]: name}
 125                 C: {char[1]:  team}
 126                 C: {uint32:   'enter status'}
 127                 C: {char[20]: ttyname}
 128                 C: {uint32:   'connect mode'}
 129                 S: {uint32:   server version (-1)}
 130
 131         If the 'connect mode' is C_MESSAGE (2) then the server will wait
 132         for a single packet (no longer than 1024 bytes) containing
 133         a text message to be displayed to all players. (The message is not
 134         nul-terminated.)
 135
 136                 C: {char[]:     client's witty message of abuse}
 137                 S: <close>
 138
 139         The only other valid 'connect mode's are C_MONITOR and C_PLAYER.
 140         The server will attempt to allocate a slot for the client.
 141         If allocation fails, the server will reply immediately with
 142         "Too many monitors\n" or "Too many players\n', e.g.:
 143
 144                 S: Too many players<LF>
 145                 S: <close>
 146
 147         The 'enter status' integer is one of the following:
 148
 149                 1 (Q_CLOAK)     the player wishes to enter cloaked
 150                 2 (Q_FLY)       the player wishes to enter flying
 151                 3 (Q_SCAN)      the player wishes to enter scanning
 152
 153         Any other value indicates that the player wishes to enter in
 154         'normal' mode.
 155
 156         A team value of 32 (space character) means no team, otherwise
 157         it is the ASCII value of a team's symbol.
 158
 159         On successful allocation, the server will immediately enter the
 160         following phase of the protocol.
 161
 162     Game play protocol
 163
 164         The client provides a thin 'graphical' client to the server, and
 165         only ever relays keystrokes typed by the user:
 166
 167                 C: {char[]:     user keystrokes}
 168
 169         Each character must be sent by the client as soon as it is typed.
 170
 171
 172         The server only ever sends screen drawing commands to the client.
 173         The server assumes the initial state of the client is a clear
 174         80x24 screen with the cursor at the top left (position y=0, x=0)
 175
 176             Literal character   225 (ADDCH)
 177
 178                 S: {uint8: 225} {uint8: c}
 179
 180                 The client must draw the character with ASCII value c
 181                 at the cursor position, then advance the cursor to the right.
 182                 If the cursor goes past the rightmost column of the screen,
 183                 it wraps, moving to the first column of the next line down.
 184                 The cursor should never be advanced past the bottom row.
 185
 186                 (ADDCH is provided as an escape prefix.)
 187
 188             Cursor motion       237 (MOVE)
 189
 190                 S: {uint8: 237} {uint8: y} {uint8: x}
 191
 192                 The client must move its cursor to the absolute screen
 193                 location y, x, where y=0 is the top of the screen and
 194                 x=0 is the left of the screen.
 195
 196             Refresh screen      242 (REFRESH)
 197
 198                 S: {uint8: 242}
 199
 200                 This indicates to the client that a burst of screen
 201                 drawing has ended. Typically the client will flush its
 202                 own drawing output so that the user can see the results.
 203
 204                 Refreshing is the only time that the client must
 205                 ensure that the user can see the current screen. (This
 206                 is intended for use with curses' refresh() function.)
 207
 208             Clear to end of line 227 (CLRTOEOL)
 209
 210                 S: {uint8: 227}
 211
 212                 The client must replace all columns underneath and
 213                 to the right of the cursor (on the one row) with
 214                 space characters. The cursor must not move.
 215
 216             End game            229 (ENDWIN)
 217
 218                 S: {uint8: 229} {uint8: 32}
 219                 S,C: <close>
 220
 221                 S: {uint8: 229} {uint8: 236}
 222                 S,C: <close>
 223
 224                 The client and server must immediately close the connection.
 225                 The client should also refresh the screen.
 226                 If the second octet is 236 (LAST_PLAYER), then
 227                 the client should give the user an opportunity to quickly
 228                 re-enter the game. Otherwise the client should quit.
 229
 230             Clear screen        195 (CLEAR)
 231
 232                 S: {uint8: 195}
 233
 234                 The client must erase all characters from the screen
 235                 and move the cursor to the top left (x=0, y=0).
 236
 237             Redraw screen       210 (REDRAW)
 238
 239                 S: {uint8: 210}
 240
 241                 The client should attempt to re-draw its screen.
 242
 243             Audible bell        226 (BELL)
 244
 245                 S: {uint8: 226}
 246
 247                 The client should generate a short audible tone for
 248                 the user.
 249
 250             Server ready        231 (READY)
 251
 252                 S: {uint8: 231} {uint8: n}
 253
 254                 The client must refresh its screen.
 255
 256                 The server indicates to the client that it has
 257                 processed n of its characters in order, and is ready
 258                 for more commands. This permits the client to
 259                 synchronise user actions with server responses if need be.
 260
 261             Characters other than the above.
 262
 263                 S: {uint8: c}
 264
 265                 The client must draw the character with ASCII value c
 266                 in the same way as if it were preceded with ADDCH
 267                 (see above).
 268
 269
 270 David Leonard, 1999.
 271
 272 $OpenBSD: README.protocol,v 1.1 1999/12/12 14:51:03 d Exp $