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