git.pond.sub.org Git - empserver/blob - 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 Additional customization is possible through key custom_tables, which
  73 is a list of files containing tables in xdump format (see doc/xdump
  74 for technical information on xdump).  To customize a table, copy the
  75 default table from the directory given by econfig key builtindir to a
  76 file next to your econfig, then add the file to custom_keys.  Do *not*
  77 edit the default table in-place!
  78
  79 The server lets you customize more tables than the ones in builtindir.
  80 This is not recommended at this time.  You can use the xdump command
  81 to dump the default table to a file.  The resulting table is in
  82 machine-readable form, and may not be portable between different
  83 server versions.
  84
  85 A word of caution: Just because you can customize something doesn't
  86 mean you should!  The server makes an effort to catch mistakes that
  87 could crash the game.  It has no chance to catch mistakes that
  88 unbalance it.
  89
  90
  91 Coder information
  92 -----------------
  93
  94 The simplest way to describe this is perhaps to step through how a new
  95 key would be added.  Let's do this for a new option "DUMB".
  96
  97 1. Define the variable for the key.  Options go into
  98 src/lib/global/options.c, like this:
  99
 100 int opt_DUMB = 1;
 101
 102 The initializer provides the compiled-in value.
 103
 104 Other keys go into src/lib/global/constants.c.
 105
 106 2. Declare the econfig key in include/econfig-spec.h:
 107
 108 EMPCF_OPT("DUMP", opt_DUMP, "Enable additional dumbness")
 109
 110 For a non-option key, you'd use EMPCFBOTH() there.
 111
 112 The declaration is visible both in include/optlist.h as an external
 113 variable, and in struct keymatch configkeys[], which is used by the
 114 econfig parser.
 115
 116 3. Use the variable in your code.  This normally looks like
 117
 118           if (opt_DUMB) {
 119              pr("You're being dumb\n");
 120           } else {
 121              pr("You're being really dumb\n");
 122           }