describe the hunt client-server protocol. reviewed by pjanzen@

1 files changed, 272 insertions, 0 deletions

diff --git a/games/hunt/README.protocol b/games/hunt/README.protocol
new file mode 100644
index 00000000000..b60b5466f95
--- /dev/null
+++ b/games/hunt/README.protocol
@@ -0,0 +1,272 @@
+
+THE HUNT PROTOCOL
+=================
+
+These are some notes on the traditional INET protocol between hunt(6) and 
+huntd(6) as divined from the source code.
+
+(In the original hunt, AF_UNIX sockets were used, but they are not 
+considered here.)
+
+The game of hunt is played with one server and several clients. The clients
+act as dumb 'graphics' clients in that they mostly only ever relay the
+user's keystrokes to the server, and the server usually only ever sends
+screen-drawing commands to the client. ie, the server does all the work.
+
+The game server (huntd) listens on three different network ports which 
+I'll refer to as W, S and P, described as follows:
+
+	W	well known UDP port (26740, or 'udp/hunt' in netdb)
+	S	statistics TCP port
+	P	game play TCP port
+
+The protocol on each port is different and are described separately in
+the following sections.
+
+Lines starting with "C:" and "S:" will indicate messages sent from the 
+client (hunt) or server (huntd) respectively.
+
+W - well known port
+-------------------
+	This server port is used only to query simple information about the 
+	game such as the port numbers of the other two ports (S and P),
+	and to find out how many players are still in the game.
+
+	All datagrams sent to (and possibly from) this UDP port consist of 
+	a single unsigned 16-bit integer, encoded in network byte order.
+
+	Server response datagrams should be sent to the source address
+	of the client request datagrams.
+
+	It is not useful to run multiple hunt servers on the one host
+	interface, each of which perhaps listen to the well known port and
+	respond appropriately. This is because clients will not be able to
+	disambiguate which game is which.
+
+	It is reasonable (and expected) to have servers listen to a 
+	broadcast or multicast network address and respond, since the
+	clients can extract a particular server's network address from
+	the reply packet's source field.
+
+    Player port request
+
+	A client requests the game play port P with the C_PLAYER message.
+	This is useful for clients broadcasting for any available games. eg:
+		
+		C: {uint16: 0 (C_PLAYER)}
+		S: {uint16: P (TCP port number for the game play port)}
+
+	The TCP address of the game play port should be formed from the
+	transmitted port number and the source address as received by
+	the client.
+
+    Monitor port request
+
+	A client can request the game play port P with the C_MONITOR message.
+	However, the server will NOT reply if there are no players in
+	the game. This is useful for broadcasting for 'active' games. eg:
+
+		C: {uint16: 1 (C_MONITOR)}
+		S: {uint16: P (TCP port number for the game play port)}
+
+    Message port request
+
+	If the server receives the C_MESSAGE message it will
+	respond with the number of players currently in its game, unless
+	there are 0 players, in which case it remains silent. This
+	is used when a player wishes to send a text message to all other
+	players, but doesn't want to connect if the game is over. eg:
+
+		C: {uint16: 2 (C_MESSAGE)}
+		S: {uint16: n (positive number of players)}
+
+    Statistics port request
+
+	The server's statistics port is queried with the C_SCORES message.
+	eg:
+
+		C: {uint16: 3 (C_SCORES)}
+		S: {uint16: S (TCP port number for the statistics port)}
+
+
+S - statistics port
+-------------------
+	The statistics port accepts a TCP connection, and keeps
+	it alive for long enough to send a text stream to the client.
+	This text consists of the game statistics. Lines in the
+	text message are terminated with the \n (LF) character. 
+
+		C: <connect>
+		S: <accept>
+		S: {char[]: lines of text, each terminated with <LF>}
+		S: <close>
+
+	The client is not to send any data to the server with this
+	connection.
+
+P - game play port
+------------------
+	This port provides the TCP channel for the main game play between
+	the client and the server.
+
+	All integers are unsigned, 32-bit and in network byte order.
+	All fixed sized octet strings are ASCII encoded, NUL terminated.
+
+    Initial connection
+
+	The initial setup protocol between the client and server is as follows.
+	The client sends some of its own details, and then the server replies
+	with the version number of the server (currently (uint32)-1).
+
+		C: <connect>
+		S: <accept>
+		C: {uint32:   uid}
+		C: {char[20]: name}
+		C: {char[1]:  team}
+		C: {uint32:   'enter status'}
+		C: {char[20]: ttyname}
+		C: {uint32:   'connect mode'}
+		S: {uint32:   server version (-1)}
+
+	If the 'connect mode' is C_MESSAGE (2) then the server will wait
+	for a single packet (no longer than 1024 bytes) containing
+	a text message to be displayed to all players. (The message is not
+	nul-terminated.)
+
+		C: {char[]:	client's witty message of abuse}
+		S: <close>
+
+	The only other valid 'connect mode's are C_MONITOR and C_PLAYER.
+	The server will attempt to allocate a slot for the client. 
+	If allocation fails, the server will reply immediately with 
+	"Too many monitors\n" or "Too many players\n', e.g.:
+
+		S: Too many players<LF>
+		S: <close>
+
+	The 'enter status' integer is one of the following:
+
+		1 (Q_CLOAK)	the player wishes to enter cloaked
+		2 (Q_FLY)	the player wishes to enter flying
+		3 (Q_SCAN)	the player wishes to enter scanning
+
+	Any other value indicates that the player wishes to enter in
+	'normal' mode.
+
+	A team value of 32 (space character) means no team, otherwise
+	it is the ASCII value of a team's symbol.
+
+	On successful allocation, the server will immediately enter the 
+	following phase of the protocol.
+
+    Game play protocol
+
+	The client provides a thin 'graphical' client to the server, and
+	only ever relays keystrokes typed by the user:
+
+		C: {char[]:	user keystrokes}
+
+	Each character must be sent by the client as soon as it is typed.
+
+
+	The server only ever sends screen drawing commands to the client.
+	The server assumes the initial state of the client is a clear
+	80x24 screen with the cursor at the top left (position y=0, x=0)
+
+	    Literal character	225 (ADDCH)
+
+		S: {uint8: 225} {uint8: c}
+
+		The client must draw the character with ASCII value c
+		at the cursor position, then advance the cursor to the right.
+		If the cursor goes past the rightmost column of the screen,
+		it wraps, moving to the first column of the next line down.
+		The cursor should never be advanced past the bottom row.
+
+		(ADDCH is provided as an escape prefix.)
+
+	    Cursor motion	237 (MOVE)
+
+		S: {uint8: 237} {uint8: y} {uint8: x}
+
+		The client must move its cursor to the absolute screen
+		location y, x, where y=0 is the top of the screen and
+		x=0 is the left of the screen.
+
+	    Refresh screen	242 (REFRESH)
+
+		S: {uint8: 242}
+
+		This indicates to the client that a burst of screen
+		drawing has ended. Typically the client will flush its
+		own drawing output so that the user can see the results.
+
+		Refreshing is the only time that the client must
+		ensure that the user can see the current screen. (This
+		is intended for use with curses' refresh() function.)
+
+	    Clear to end of line 227 (CLRTOEOL)
+
+		S: {uint8: 227}
+
+		The client must replace all columns underneath and
+		to the right of the cursor (on the one row) with 
+		space characters. The cursor must not move.
+
+	    End game		229 (ENDWIN)
+
+		S: {uint8: 229} {uint8: 32}
+		S,C: <close>
+
+		S: {uint8: 229} {uint8: 236}
+		S,C: <close>
+
+		The client and server must immediately close the connection.
+		The client should also refresh the screen.
+		If the second octet is 236 (LAST_PLAYER), then 
+		the client should give the user an opportunity to quickly 
+		re-enter the game. Otherwise the client should quit.
+
+	    Clear screen	195 (CLEAR)
+
+		S: {uint8: 195}
+
+		The client must erase all characters from the screen
+		and move the cursor to the top left (x=0, y=0).
+
+	    Redraw screen	210 (REDRAW)
+
+		S: {uint8: 210}
+
+		The client should attempt to re-draw its screen.
+
+	    Audible bell	226 (BELL)
+
+		S: {uint8: 226}
+
+		The client should generate a short audible tone for
+		the user.
+
+	    Server ready	231 (READY)
+
+		S: {uint8: 231} {uint8: n}
+
+		The client must refresh its screen.
+
+		The server indicates to the client that it has
+		processed n of its characters in order, and is ready
+		for more commands. This permits the client to 
+		synchronise user actions with server responses if need be.
+
+	    Characters other than the above.
+
+		S: {uint8: c}
+
+		The client must draw the character with ASCII value c
+		in the same way as if it were preceded with ADDCH
+		(see above).
+
+
+David Leonard, 1999.
+
+$OpenBSD: README.protocol,v 1.1 1999/12/12 14:51:03 d Exp $