Fix the man page.
[vms-empire.git] / README
1 /* (c) Copyright 1987, 1988 Chuck Simmons */
2
3 /*
4  *    Copyright (C) 1987, 1988 Chuck Simmons
5  * 
6  * See the file COPYING, distributed with empire, for restriction
7  * and warranty information.
8  */
9
10 C Empire Sources
11
12 Eric S. Raymond colorized and speed-tuned this and added a
13 save-interval option.  Also, the victory-odds table in previous
14 versions was seriously buggy. The rest of this history is Chuck Simmons's
15 original notes.
16
17 History
18
19         Apparently, this game was originally written outside of Digital,
20         probably at a university.  The game was ported to DEC's VAX/VMS
21         from the TOPS-10/20 FORTRAN sources available around fall 1979.
22         Ed James got hold of the sources at Berkeley and converted
23         portions of the code to C, mostly to use curses for the screen
24         handling.  He published his modified sources on the net in
25         December 1986.  Because this game ran on VMS machines for so
26         long, a previous version is known as VMS Empire.
27
28         In early 1987 I reverse engineered the program and wrote a
29         version completely written in C.  In doing this, I used lots
30         of structures and defined constants, and I attempted to make
31         the code flexible and easy to modify.  The algorithms used
32         in this C version are completely new, the names of the commands
33         have been changed to be more mnemonic, and new commands have
34         been implemented.  Only the format of the display is the same.
35         I suspect that many of my changes are slower and less
36         intelligently implemented than the originals.  Also, I have
37         not implemented some of the original functionality.
38         However, my hope is that the commented C sources I have written
39         will prove far easier to modify and enhance than the original
40         FORTRAN sources.  If you make changes for the better, by
41         all means send Ed James and I a copy.
42
43         The basic game has been heavily modified.  I've changed the
44         types of objects built, modified the parameters on others,
45         and added lots of new kinds of movement functions.  Read
46         the man page for a complete description.
47
48         The file 'bugs' contains lots of ideas for enhancements,
49         and describes the bugs I haven't been able to find.
50
51 Organization
52
53         I have attempted to organize the sources into relatively few
54         coherent pieces.  The pieces are:
55
56         empire.h   -- definitions of data structures
57         extern.h   -- definitions of global variables
58         data.c     -- constant data
59         main.c     -- option parsing
60         empire.c   -- main program loop and outermost command handler
61         usermove.c -- move the user's pieces
62         compmove.c -- move the computer's pieces
63         edit.c     -- handle the user's edit mode commands
64         game.c     -- saving, restoring, and initializing the game board
65         display.c  -- update the screen
66         term.c     -- deal with information area of screen
67         math.c     -- mathematical routines
68         object.c   -- routines for manipulating objects
69         attack.c   -- handle attacks between pieces
70         map.c      -- find paths for moving pieces
71         util.c     -- miscellaneous routines, especially I/O.
72
73 Debugging notes
74
75         From command mode, there are two special commands that
76         can be used to turn debugging mode on or off.  "++" turns
77         debugging mode on.  "+-" turns debugging mode off.
78
79         When debugging mode is turned on, the following commands are
80         available:
81
82         "#" -- display a sector of the computer's map.
83
84         "%" -- enter "movie" mode.  The computer continuously makes
85                moves, and the computer's map is shown on the screen.
86                This is useful for debugging the algorithm used by the
87                computer when it makes a move.  Don't confuse this
88                with saving a movie and replaying it.
89
90         "@" -- enable/disable "trace pathmap" mode.  If this command
91                is followed by a "+", trace pathmap mode is enabled.
92                If this command is followed by a "-", trace pathmap
93                mode is disabled.  In this mode, every time a "pathmap"
94                is created, it is displayed.  This is useful for
95                debugging the subroutines that search for an optimal
96                path along which to move a piece.
97
98         "$" -- enable/disable "print_debug".  This command is also
99                followed by either a "+" or "-".  In this mode,
100                various messages will be printed out at times which
101                may indicate that something is being done non-optimally.
102
103         "&" -- enable/disable "print_vmap".  This command is followed
104                by a char that specifies the type of vmap to be
105                displayed.  Values are
106
107                 "a" -- army load maps
108                 "l" -- transport load maps
109                 "u" -- transport unload maps
110                 "s" -- ship maps
111                 "i" -- pruned explore map
112
113                Any other character disables the printing of vmaps.
114
115         The program will not provide any prompts for the debugging
116         commands.  If you make a mistake, the computer just beeps.
117
118         You can also replay a saved movie with the normal "W" command
119         when debugging mode is turned on.
120
121         Also, the -DDEBUG flag can be turned on to cause consistency
122         checking to be performed frequently on the internal database.
123         This consistency checking is fairly exhaustive and checks for
124         all sorts of screwed up pointers.  My measurements suggest
125         that consistency checking causes the program to run half
126         as fast.
127
128 Final Notes
129
130         Unfortunately, I have a rather powerful mainframe at my
131         disposal which is somewhere between 10 and 40 times as
132         fast as a 68020 based computer.  This means I can afford
133         to use extremely inefficient algorithms.  I suspect that
134         running this program on a smaller machine, such as a Sun
135         workstation or Vax will not be overly rewarding.  In particular,
136         the computer will take a very long time to move its pieces,
137         and it may not be desirable to save the game after every move.
138         (You mean your system doesn't write out 1/2 megabyte files in a
139         few milliseconds?)  This second problem is easily fixed, but
140         I don't yet have any good ideas for fixing the first problem.
141
142         The size of a saved file can be easily tuned by reducing the
143         LIST_SIZE constant in empire.h.  The only current simple tweak
144         for making the computer move faster is to reduce the size
145         of a map.
146
147 Chuck Simmons
148 amdahl!chuck
149
150 Ed James
151 edjames@ic.berkeley.edu
152 ucbvax!edjames
153
154         My changes enable color on machines with terminfo color support, for
155         a dramatic improvement in appearance and readability of the display.
156         Color support, if present, will be auto-detected at compilation time.
157
158         They also implement and document a `save-interval' option, addressing
159         one of the misfeatures noted in the bugs file.
160
161         I've also tweaked the sources so they compile clean under GCC -- they
162         assumed the older K&R model of forward reference, causing many warning
163         references.
164
165         Finally, I've sped up expand_perimeter by cutting down on the
166         number of array references it has to compute. This eliminates several
167         multiplies from the inner loop, and is a technique that should be
168         applied much more widely in the code.
169
170 Eric S. Raymond
171 esr@snark.thyrsus.com
172 (home page: //www.ccil.org/~esr/home.html)