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