Split up README, most of it goes to HACKING.
[vms-empire.git] / HACKING
1 /*
2  *    Copyright (C) 1987, 1988 Chuck Simmons
3  * 
4  * See the file COPYING, distributed with empire, for restriction
5  * and warranty information.
6  */
7
8 C Empire Sources (now called vms-empire).
9
10 A few notes on how to debug and modify this code.  This used to be
11 part of the README.
12
13 Organization:
14
15         empire.h   -- definitions of data structures
16         extern.h   -- definitions of global variables
17         data.c     -- constant data
18         main.c     -- option parsing
19         empire.c   -- main program loop and outermost command handler
20         usermove.c -- move the user's pieces
21         compmove.c -- move the computer's pieces
22         edit.c     -- handle the user's edit mode commands
23         game.c     -- saving, restoring, and initializing the game board
24         display.c  -- update the screen
25         term.c     -- deal with information area of screen
26         math.c     -- mathematical routines
27         object.c   -- routines for manipulating objects
28         attack.c   -- handle attacks between pieces
29         map.c      -- find paths for moving pieces
30         util.c     -- miscellaneous routines, especially I/O.
31
32 Debugging notes:
33
34         From command mode, there are two special commands that
35         can be used to turn debugging mode on or off.  "++" turns
36         debugging mode on.  "+-" turns debugging mode off.
37
38         When debugging mode is turned on, the following commands are
39         available:
40
41         "#" -- display a sector of the computer's map.
42
43         "%" -- enter "movie" mode.  The computer continuously makes
44                moves, and the computer's map is shown on the screen.
45                This is useful for debugging the algorithm used by the
46                computer when it makes a move.  Don't confuse this
47                with saving a movie and replaying it.
48
49         "@" -- enable/disable "trace pathmap" mode.  If this command
50                is followed by a "+", trace pathmap mode is enabled.
51                If this command is followed by a "-", trace pathmap
52                mode is disabled.  In this mode, every time a "pathmap"
53                is created, it is displayed.  This is useful for
54                debugging the subroutines that search for an optimal
55                path along which to move a piece.
56
57         "$" -- enable/disable "print_debug".  This command is also
58                followed by either a "+" or "-".  In this mode,
59                various messages will be printed out at times which
60                may indicate that something is being done non-optimally.
61
62         "&" -- enable/disable "print_vmap".  This command is followed
63                by a char that specifies the type of vmap to be
64                displayed.  Values are
65
66                 "a" -- army load maps
67                 "l" -- transport load maps
68                 "u" -- transport unload maps
69                 "s" -- ship maps
70                 "i" -- pruned explore map
71
72                Any other character disables the printing of vmaps.
73
74         The program will not provide any prompts for the debugging
75         commands.  If you make a mistake, the computer just beeps.
76
77         You can also replay a saved movie with the normal "W" command
78         when debugging mode is turned on.
79
80         Also, the -DDEBUG flag can be turned on to cause consistency
81         checking to be performed frequently on the internal database.
82         This consistency checking is fairly exhaustive and checks for
83         all sorts of screwed up pointers.  My measurements suggest
84         that consistency checking causes the program to run half
85         as fast.