1 2THE HUNT PROTOCOL 3================= 4 5These are some notes on the traditional INET protocol between hunt(6) and 6huntd(6) as divined from the source code. 7 8(In the original hunt, AF_UNIX sockets were used, but they are not 9considered here.) 10 11The game of hunt is played with one server and several clients. The clients 12act as dumb 'graphics' clients in that they mostly only ever relay the 13user's keystrokes to the server, and the server usually only ever sends 14screen-drawing commands to the client. ie, the server does all the work. 15 16The game server (huntd) listens on three different network ports which 17I'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 23The protocol on each port is different and are described separately in 24the following sections. 25 26Lines starting with "C:" and "S:" will indicate messages sent from the 27client (hunt) or server (huntd) respectively. 28 29W - 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 92S - 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 107P - 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 270David Leonard, 1999. 271 272$OpenBSD: README.protocol,v 1.1 1999/12/12 14:51:03 d Exp $ 273$DragonFly: src/games/hunt/README.protocol,v 1.1 2008/09/02 21:50:18 dillon Exp $ 274