Initial revision
authorEric S. Raymond <esr@thyrsus.com>
Thu, 1 Dec 1994 16:07:03 +0000 (16:07 +0000)
committerEric S. Raymond <esr@thyrsus.com>
Thu, 1 Dec 1994 16:07:03 +0000 (16:07 +0000)
README [new file with mode: 0644]

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..5c2deba
--- /dev/null
+++ b/README
@@ -0,0 +1,147 @@
+/* %W% %G% %U% - (c) Copyright 1987, 1988 Chuck Simmons */
+
+/*
+ *    Copyright (C) 1987, 1988 Chuck Simmons
+ * 
+ * See the file COPYING, distributed with empire, for restriction
+ * and warranty information.
+ */
+
+C Empire Sources
+
+History
+
+       Apparently, this game was originally written outside of Digital,
+       probably at a university.  The game was ported to DEC's VAX/VMS
+       from the TOPS-10/20 FORTRAN sources available around fall 1979.
+       Ed James got hold of the sources at Berkeley and converted
+       portions of the code to C, mostly to use curses for the screen
+       handling.  He published his modified sources on the net in
+       December 1986.  Because this game ran on VMS machines for so
+        long, a previous version is known as VMS Empire.
+
+       In early 1987 I reverse engineered the program and wrote a
+       version completely written in C.  In doing this, I used lots
+       of structures and defined constants, and I attempted to make
+       the code flexible and easy to modify.  The algorithms used
+       in this C version are completely new, the names of the commands
+       have been changed to be more mnemonic, and new commands have
+       been implemented.  Only the format of the display is the same.
+        I suspect that many of my changes are slower and less
+        intelligently implemented than the originals.  Also, I have
+       not implemented some of the original functionality.
+       However, my hope is that the commented C sources I have written
+       will prove far easier to modify and enhance than the original
+        FORTRAN sources.  If you make changes for the better, by
+        all means send Ed James and I a copy.
+
+       The basic game has been heavily modified.  I've changed the
+       types of objects built, modified the parameters on others,
+       and added lots of new kinds of movement functions.  Read
+       the man page for a complete description.
+
+       The file 'bugs' contains lots of ideas for enhancements,
+       and describes the bugs I haven't been able to find.
+
+Organization
+
+        I have attempted to organize the sources into relatively few
+        coherent pieces.  The pieces are:
+
+        empire.h   -- definitions of data structures
+        extern.h   -- definitions of global variables
+        data.c     -- constant data
+       main.c     -- option parsing
+        empire.c   -- main program loop and outermost command handler
+        usermove.c -- move the user's pieces
+        compmove.c -- move the computer's pieces
+        edit.c     -- handle the user's edit mode commands
+        game.c     -- saving, restoring, and initializing the game board
+        display.c  -- update the screen
+       term.c     -- deal with information area of screen
+        math.c     -- mathematical routines
+        object.c   -- routines for manipulating objects
+       attack.c   -- handle attacks between pieces
+       map.c      -- find paths for moving pieces
+       util.c     -- miscellaneous routines, especially I/O.
+
+Debugging notes
+
+       From command mode, there are two special commands that
+       can be used to turn debugging mode on or off.  "++" turns
+       debugging mode on.  "+-" turns debugging mode off.
+
+       When debugging mode is turned on, the following commands are
+       available:
+
+       "#" -- display a sector of the computer's map.
+
+       "%" -- enter "movie" mode.  The computer continuously makes
+              moves, and the computer's map is shown on the screen.
+              This is useful for debugging the algorithm used by the
+              computer when it makes a move.  Don't confuse this
+              with saving a movie and replaying it.
+
+       "@" -- enable/disable "trace pathmap" mode.  If this command
+              is followed by a "+", trace pathmap mode is enabled.
+              If this command is followed by a "-", trace pathmap
+              mode is disabled.  In this mode, every time a "pathmap"
+              is created, it is displayed.  This is useful for
+              debugging the subroutines that search for an optimal
+              path along which to move a piece.
+
+       "$" -- enable/disable "print_debug".  This command is also
+              followed by either a "+" or "-".  In this mode,
+              various messages will be printed out at times which
+              may indicate that something is being done non-optimally.
+
+       "&" -- enable/disable "print_vmap".  This command is followed
+              by a char that specifies the type of vmap to be
+              displayed.  Values are
+
+               "a" -- army load maps
+               "l" -- transport load maps
+               "u" -- transport unload maps
+               "s" -- ship maps
+               "i" -- pruned explore map
+
+              Any other character disables the printing of vmaps.
+
+       The program will not provide any prompts for the debugging
+       commands.  If you make a mistake, the computer just beeps.
+
+       You can also replay a saved movie with the normal "W" command
+       when debugging mode is turned on.
+
+       Also, the -DDEBUG flag can be turned on to cause consistency
+       checking to be performed frequently on the internal database.
+       This consistency checking is fairly exhaustive and checks for
+       all sorts of screwed up pointers.  My measurements suggest
+       that consistency checking causes the program to run half
+       as fast.
+
+Final Notes
+
+       Unfortunately, I have a rather powerful mainframe at my
+       disposal which is somewhere between 10 and 40 times as
+       fast as a 68020 based computer.  This means I can afford
+       to use extremely inefficient algorithms.  I suspect that
+       running this program on a smaller machine, such as a Sun
+       workstation or Vax will not be overly rewarding.  In particular,
+       the computer will take a very long time to move its pieces,
+       and it may not be desirable to save the game after every move.
+       (You mean your system doesn't write out 1/2 megabyte files in a
+       few milliseconds?)  This second problem is easily fixed, but
+       I don't yet have any good ideas for fixing the first problem.
+
+       The size of a saved file can be easily tuned by reducing the
+       LIST_SIZE constant in empire.h.  The only current simple tweak
+       for making the computer move faster is to reduce the size
+       of a map.
+
+Chuck Simmons
+amdahl!chuck
+
+Ed James
+edjames@ic.berkeley.edu
+ucbvax!edjames