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