README

************************************************************************
* README: Rog-O-Matic XIV (CMU) Tue Jan 29 15:02:02 1985 - mlm
* Copyright (C) 1985 by A. Appel, G. Jacobson, L. Hamey, and M. Mauldin
************************************************************************

* Here is Rog-O-Matic XIV, the automatic Rogue player for the eighties! *

1.0 UNPACKING:

Rog-O-Matic is shipped as a collection of shell archives.  Run the
distribution files through the shell (e.g. "sh rgm14.01"), and the
individual source files will be created.  Rog-O-Matic is stored on the
General Purpose Vax at Carnegie-Mellon University, and may be retrieved via
FTP using the following file name:

		mlm/rgm/rgm14.xx @ CMU-CS-G		(xx = 01,02,...)

The file

		mlm/rgm/Instructions @ CMU-CS-G

contains instructions and pointers to files for this public directory.
For FTP access, the username is 'ftpguest' and the password is 'cmunix'.

2.0 INSTRUCTIONS FOR USE:

Tear along the dotted line and put all files into a directory. You should
have the following files:

	Bugreport     findscore.c   main.c        rogomatic.6   survival.c
	README        gene.c        makefile      rooms.c       tactics.c
	arms.c        globals.h     mess.c        rplot         termtokens.h
	command.c     histplot.c    monsters.c    scorefile.c   things.c
	database.c    install.h     pack.c        search.c      titlepage.c
	datesub.l     io.c          rand.c        setup.c       types.h
	debug.c       learn.c       replay.c      stats.c       utility.c
	explore.c     ltm.c         rgmplot.c     strategy.c    worth.c

Bugreport contains descriptions of any known bugs and patches to fix them.
Main.c is the main file of Rog-O-Matic, and contains descriptions of all
other files.  Install.h contains the installation dependent preprocessor
variables. 

Edit "install.h" to set up various log files and directories, and then
create the RGMDIR directory, making certain that it is publicly readable
and writable.  After that, the 'make' command will build your own
personalized automatic Rogue playing system!

The preprocessor variables defined are:

BEST:           The compile time copy of the best current score. 
		Now 43,402 (against 3.6) and 7935 (against 5.2),
		and 11,316, total winner (against Rogue 5.3).
BOGUS:          The highest score to be considered "reasonable" by
                Rog-O-Matic. Rog-O-Matic will only try to beat non-bogus
                scores. Currently set at 50,000.
ERRORLOG:	A fully qualified filename to which snapshots of game
		positions are appended when severe or fatal bugs/
                inconsistencies are found.
LOCKFILE:	A file name in in the /tmp directory used to serialize
		accesses to the score file.
MAXLOCK:	A number of seconds after which to ignore the lock file.
		Usually 3 minutes (120 seconds).
NEWROGUE:	On systems where the default Rogue is 3.6, this is the
		name of the Rogue 5.2 or Rogue 5.3 file.
PLAYER:         This is the file name of the player program, which is
                execl'ed by the rogomatic program. It should be fully
                qualified.
RGMDIR:		The name of the directory where the Rog-O-Matic gene pool,
		long term memory, and score files are kept.  It must be 
		publicly readable and writeable.  This directory must
		be created by hand.
ROGUE:          This is the file name of the Rogue game. Usually this is
                /usr/games/rogue.
ROGUELOG:       When the game logging (or "echoing") is enabled, a
		complete transcript of the game is written to this
		file.  If the program finishes normally, this file
		will be renamed to <killer>.<level>.<score>, and can 
		either be examined by "cat"ing it or replayed using the
		"-p" option of rogomatic. This should be an unqualified
		file name.
SNAPSHOT:	An unqualified file name where game snapshots are put.
		The 'snapshot' command appends game photos to this file
		in the user's directory.

After "make"ing, you should have the following programs:

        rogomatic  player  datesub  rgmplot  histplot gene

and the shell script:

        rplot


These should be put into the games directory, in such a way that the player
program has the same name as that specified by the PLAYER variable in
install. Otherwise, you will have to "cd" to the directory containing
Rogomatic to play.

3.0 DESCRIPTIONS OF THE PROGRAMS AND COMMANDS.

3.1 ROGOMATIC

    The files "rogomatic" and "player" contain the basic Rog-O-Matic.
    Rogomatic parses the arguments and forks and execs Rogue and Player.
    For more information about the "rogomatic" command, see rogomatic.6.

3.2 RPLOT

    "rplot" prints a scatter plot of the rogomatic score file. Options
    allow for inclusion of scores obtained by cheating and addition of
    a rolling average to the plot.  "rplot" uses the rgmplot program.

3.3 HISTPLOT

    "histplot" reads the scorefile and produces a histogram of either
    final score or level reached, depending on the option set.  The
    histogram plots the killing monster for each game.

3.4 GENE

    "gene" summarizes the current gene pool.

4.0 MORE ABOUT FILES

   For those perusing the source, the following files are in the
source.  The notes indicate how important an understanding of that file
is to understanding the strategy Rogomatic uses, and whether that file
contains system code, strategy code, or utility code.

	Importance:	0..9  (9 must read, 0 never look at it)

	Classes:	(strat) = strategy,
			(tact)  = tactics,
			(mech)  = mechanics,
			(util)  = utility

       Importance	File		
       Class:	  	Name:		Description:

 	9 (mech)	install.h:	Must edit to run Rogomatic
	9 (mech)	main.c:		Main file, references everything else
	9 (strat)	strategy.c:	Top level strategy
	8 (strat,tact)	tactics.c:	More insteresting production rules
	7 (mech)	globals.h:	Description of globals
	7 (mech)	types.h:	More description of globals
	7 (mech)	setup.c:	Main program, forks & execs Rogue, Rgm
	7 (tact)	arms.c:		Rules: worth of armor, weapons, rings
	7 (tact)	worth.c:	Rules about worth of objects
	6 (mech)	mess.c:		Handles message from Rogue
	6 (strat,mech)	explore.c:	Defines exploration strategy
	5 (mech)	rooms.c:	Builds terrain map
	4 (mech)	io.c:		Handles communications from Rogue
	4 (mech)	search.c:	Does path planning
	4 (mech)	things.c:	Handles objects in pack
	3 (mech)	command.c:	Sends commands to Rogue
	3 (tact,mech)	survival.c:	Code for running away from monsters
	2 (mech)	scorefile.c:	Handles Rogomatic scoreboard
	2 (util)	database.c:	Remembers objects and their names
	2 (util)	findscore.c:	Reads Rogue scoreboard
	1 (mech)	monsters.c:	Keeps track of monsters on level
	1 (util)	debug.c:	Debugging handler (error logger)
	0 (mech)	replay.c:	Finds levels in log files
	0 (mech)	termtokens.h:	Contains definitions for terminal
	0 (mech)	titlepage.c:	Prints animated copyright notice
	0 (util)	histplot.c:	Plots histograms of Rgm performance
	0 (mech)	rgmplot.c:	Plots Rgm performance over time
	0 (util)	utility.c:	Contains CMU specific system functions

5.0 NET ADDRESS

Questions, comments, gripes, and ephemera to

        Michael.Mauldin@CMU-CS-A.ARPA

	Michael Mauldin (Fuzzy)		(412) 578-3065
	Department of Computer Science
	Carnegie-Mellon University
	Pittsburgh, PA  15213

6.0 MORE INFORMATION

    Copies of CMU Technical Report CMU-CS-83-144, "ROG-O-MATIC:
    A Belligerent Expert System" may be obtained by sending mail
    to Michael Mauldin at the above addresses.  Since these will
    be sent by US Post, you must include your US Mail address.

    ROG-O-MATIC: A Belligerent Expert System    (CMU-CS-83-144)   ABSTRACT

   "Rog-O-Matic  is  an  unusual combination of algorithmic and production
    systems programming techniques which cooperate to  explore  a  hostile
    environment. This environment is the computer game Rogue, which offers
    several  advantages  for  studying  exploration  tasks.    This  paper
    presents the major features of the Rog-O-Matic system,  the  types  of
    knowledge  sources  and  rules  used  to  control the exploration, and
    compares the performance of the system with human Rogue players."

    An  abbreviated  but more recent version of this paper appeared in the
    conference proceedings of CSCSI in May of 1984.
    
    A short reference to  Rog-O-Matic  also appeared in the  February 1985
    Computer Recreations column of Scientific American, page 18-21.

---end of Rog-O-Matic XIV description---