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