What *is* hunt?

	Hunt is a multi-player search-and-destroy game that takes place
	in a maze.  The game may either be slow and strategic or fast
	and tactical, depending on how familiar the players are with the
	keyboard commands.

Distribution Policy:

	Hunt is part of the user-contributed software distributed by
	Berkeley in 4BSD.  The sources are copyrighted by the authors
	and the University of California.  You may redistribute freely
	as long as the copyright notices are retained.

Words of Warning:

	hunt uses the socket mechanism of 4BSD Unix, so if you are on
		System V (my sympathies), you're on your own.
	If your machine does not permit non-setuid-root processes to
		broadcast UDP packets, then hunt uses a *very* inefficient
		method for locating the hunt server: it sends a packet
		to every host on your network.  If your machine falls
		into this category, we strongly recommend that you use
		either standalone or inetd mode *and* start hunt by
		specifying the hunt server host.
	hunt can be configured to use Unix-domain sockets, but that
		code has not been tested in recent memory.  Also, since
		4.2BSD Unix-domain sockets are buggy, running hunt on
		4.2BSD with Unix-domain sockets will probably crash
		your system.  If you want to experiment, feel free to
		do so.  However, don't say I didn't warn you :-).
	hunt uses a fair amount of CPU time, both in user time (for
		computing interactions) and system time (for processing
		terminal interrupts).  We found that a VAX 750 can
		support about three users before the system is
		noticeably impacted.  The number goes up to about 8 or
		10 for a VAX 8650.  On a network of Sun 3/50's with the
		server running on a 3/280, things work much more
		smoothly as the computing load is distributed across
		many machines.
	hunt may be dangerous to your health.  "Arthritic pain" and
		"lack of circulation" in fingers have been reported by
		hunt abusers.  Hunt may also be addictive, and the
		withdrawal symptoms are not pretty :-)

Installation:

	1. Edit file "Makefile" and make sure the options selected are
		reasonable.  There are four "make" variables that you
		should check: GAME_PARAM, SYSCFLAGS, SYSLDFLAGS, and DEFS.
		GAME_PARAM controls what features of the game will be
		compiled in (e.g. reflecting walls).  The optional features
		are listed in comments above where GAME_PARAM is defined.
		If you want to try them, just add the ones you want to the
		GAME_PARAM definition.

		DEFS is where most system configuration is described.
		If your system is 4.3BSD, Sun, Ultrix, Convex, HPUX
		v6.0.1, or SGI, you're in luck.  We provide the
		appropriate definitions for these systems and you just
		need to select one of them (e.g. if you have an Ultrix
		system, just change the line
			DEFS=	$(GAME_PARAM) $(DEFS_43)
		to
			DEFS=	$(GAME_PARAM) $(DEFS_ULTRIX)
		).  If your system is *not* listed above, then you may
		need to do some experiments.  All of the options are
		documented in the Makefile, be brave.

		SYSCFLAGS and SYSLDFLAGS are used for "unusual" systems
		and you probably won't need to deal with it.  An
		example of an unusual system is the Silicon Graphics
		IRIS, which keeps the network socket code in a BSD
		emulation library that is in -lbsd.  Edit these only if
		you *know* your system is "different."

	2. Edit file "Makefile" and look at the "install:" target.  By
		default, files are installed in /usr/games,
		/usr/games/lib, and /usr/man/man6, which are "standard"
		locations for games.  If your system has a local games
		directory, you'll need to change these.
	3. Edit file "pathname.c" and make sure the file names and port
		numbers are reasonable.  You can ignore the first set
		of variables as they are used only for debugging
		purposes.  The second set is used in the installed
		version of hunt.  The important variables are "Driver"
		(where the server is kept), "Test_port" (the Internet
		UDP port number that new players should use to contact
		the server), and "Stat_file" (where scoring statistics
		and body counts are written).  The only tricky variable
		here is "Test_port".  The default value is chosen so
		that it is unlikely to conflict with other service port
		numbers, but you can change it if you want to.
	4. Type "make install", which will compile and install the
		programs and manual pages.  Now you're almost ready to
		go (see next section).  There may be some warnings during
		compilation.  Ignore them.

Setting up the network:

	Hunt may be set up in one of three modes: standalone, inetd, or
	nothing.  In "standalone" mode, there is always a hunt server
	running on a server machine.  All players who enter the game
	will be talking to this server.  This is the mode we use at
	UCSF.  The cost is one entry in the process table on the server
	machine.  In "inetd" mode, the server is started via inetd.
	Again, only one machine should be set up to answer game
	requests.  The cost is having to edit a few system files.  In
	"nothing" mode, no server is running when there is no one
	playing.  The first person to enter hunt will automatically
	start up a server on his machine.  This, of course, gives him
	an unfair advantage.  Also, there may be race conditions such
	that players end up in different games.  The choice of which
	mode to use depends on site configuration and politics.  We
	recommend using "standalone" mode because it is simple to set
	up and starts up rapidly.

	-----

	FOR STANDALONE MODE, put these lines in /etc/rc.local on the
	server machine.  THERE SHOULD ONLY BE ONE SERVER MACHINE!

	# start up the hunt daemon if present
	if [ -f /usr/games/lib/huntd ]; then
		/usr/games/lib/huntd -s & (echo -n ' huntd')	>/dev/console
	fi

	Also, you should start one up (on the off chance that you will
	want to test this mess :-) by typing "/usr/games/lib/hunt -s".

	-----

	FOR INETD MODE, then things get more complicated.  You need to
	edit both /etc/services and /etc/inetd.conf.  In /etc/services,
	add the line

	hunt		26740/udp

	26740 corresponds to the default "Test_port".  If you changed
	that variable, then you should put whatever value you used here
	as well.  In /etc/inetd.conf, add the line

	hunt	dgram	udp	wait	nobody	/usr/games/lib/huntd	huntd

	This works for 4.3BSD.  I don't remember the configuration file
	format for 4.2BSD inetd.

	See the huntd.6 manual page for more details.

	-----

	FOR NOTHING MODE, do nothing.

Testing:
	Now you are ready to test the code.  Type "/usr/games/hunt" or
	whatever you call the hunt executable.  You should be prompted
	for your name and team.  Then you should get the display of a
	maze.  At this point, you should read the manual page :-).

======

Hunt is not officially supported by anyone anywhere (that I know of);
however, bug reports will be read and bug fixes/enhancements may be
sent out at irregular intervals.  Send no flames, just money.  Happy
hunting.

					Conrad Huang
					conrad@cgl.ucsf.edu
					Greg Couch
					gregc@cgl.ucsf.edu
					October 17, 1988

P.S.  The authors of the game want to emphasize that this version of hunt
was started over eight years ago, and the programming style exhibited here
in no way reflects the current programming practices of the authors.

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 $