client: Unbreak standalone build
[empserver] / doc / econfig
1 This is a short note on the Empire run-time configuration stuff.  Some
2 of this is for deities to enable them to configure things, some of it
3 is for coders to see how this stuff works.
4
5 Julian Onions <j.onions@nexor.co.uk>  15/7/95
6
7 --
8
9 Deity Information
10 -----------------
11
12 To find out the compiled-in configuration, the simplest method is to
13 run pconfig.  It can be run either with no arguments, in which case it
14 will print the current compiled-in configuration in econfig format.
15 Otherwise, with a file name argument, it will first read in this file,
16 and override any compiled in variables, and then print the merged
17 configuration.
18
19 So the first method shows you what's compiled in, the second how a
20 config file would modify this.
21
22 Blank lines are ignored, as are lines starting with a # character.
23
24 A line of the form KEY VALUE configures an econfig key to a value.  A
25 value is either a string (quote using " to get spaces in it), an
26 integer or a floating-point number, depending on the key.
27
28 For instance,
29     data "/empire/data"
30 configures the data directory to that place, and
31     port "7777"
32 configures the empire port to 7777,
33     btu_build_rate 0.0004
34 configures the BTU build rate, and so on.
35
36 The programs look for the config file in a compiled-in location, which
37 is shown by emp_server -h.  Use -e to make the programs use another
38 config file instead.  Thus, to start two games on the same host, you
39 might have
40
41 Game1:
42 files -e econfig1
43 fairland -e econfig1
44 emp_server -e econfig1
45
46 Game2:
47 files -e econfig2
48 fairland -e econfig2
49 emp_server -e econfig2
50
51 econfig1 might have the lines
52
53 data "/empire/data1"
54 info "/empire/info.nr"
55 port "7777"
56
57 and econfig2 might have the lines
58
59 data "/empire/data2"
60 info "/empire/info.nr"
61 port "7778"
62
63 You only need the lines in that file that you require to override the
64 compiled-in definitions, however having all the definitions may help
65 you to understand what is on and off.  You could do this with
66
67 pconfig econfig1 > e1 && mv e1 econfig1
68 pconfig econfig2 > e2 && mv e2 econfig2
69
70 which will fill in all the missing keys and values with their defaults.
71
72 You define your update schedule in the schedule file, in the same
73 directory as your econfig.  See doc/schedule for details.
74
75 Additional customization is possible through key custom_tables, which
76 is a list of files containing tables in xdump format (see doc/xdump
77 for technical information on xdump).  To customize a table, copy the
78 default table from the directory given by econfig key builtindir to a
79 file next to your econfig, then name the file in custom_tables.  Do
80 *not* edit the default table in-place!  That bypasses important
81 consistency checks.
82
83 A word of caution: Just because you can customize something doesn't
84 mean you should!  The server makes an effort to catch mistakes that
85 could crash the game.  It has no chance to catch mistakes that
86 unbalance it.
87
88
89 Coder information
90 -----------------
91
92 The simplest way to describe this is perhaps to step through how a new
93 key would be added.  Let's do this for a new option "DUMB".
94
95 1. Define the variable for the key.  Options go into
96 src/lib/global/options.c, like this:
97
98 int opt_DUMB = 1;
99
100 The initializer provides the compiled-in value.
101
102 Other keys go into src/lib/global/constants.c.
103
104 2. Declare the econfig key in include/econfig-spec.h:
105
106 EMPCF_OPT("DUMP", opt_DUMP, "Enable additional dumbness")
107
108 For a non-option key, you'd use EMPCFBOTH() there.
109
110 The declaration is visible both in include/optlist.h as an external
111 variable, and in struct keymatch configkeys[], which is used by the
112 econfig parser.
113
114 3. Use the variable in your code.  This normally looks like
115
116           if (opt_DUMB) {
117               pr("You're being dumb\n");
118           } else {
119               pr("You're being really dumb\n");
120           }