git.pond.sub.org Git - empserver/blob - doc/econfig

   1 This is a short note on the empire configuration stuff. Some of this
   2 is for deities to enable them to configure things, some of it is for
   3 coders to see how this stuff works.
   4
   5 Julian Onions <j.onions@nexor.co.uk>  15/7/95
   6
   7 --
   8 Also, the Empire config files are now self-documenting (to a point.)
   9 Each option/variable now has a comment associated with it to hopefully
  10 make life easier on deities wanting to change things.
  11
  12 -- Steve McClure, 10/21/1998
  13 --
  14
  15
  16 Deity Notes.
  17 -----------
  18
  19 To find out the current configuration, the simplest method is to
  20 compile up util/pconfig and the run it. It can be run either with no
  21 arguments, in which case it will printout in config format the current
  22 compiled in options. Otherwise with a file containing a configuration
  23 it will first read in this file, and overright any copmiled in
  24 variables and then printout the merged options.
  25
  26 So the first method shows you whats compield in, the 2nd how a config
  27 file would modify this.
  28
  29 Blank lines are ignored, as are lines starting with a # character.
  30
  31 Most of the options are straight forward, they take either a string
  32 (quote using " to get spaces in it) or a number - integer or floating
  33 point depending on the option.
  34
  35 For instance
  36   privname "The Deity"
  37 sets the internal privname variable to that string, and
  38   port "7777"
  39 sets the empire port to 7777.
  40   btu_build_rate 0.0004
  41 sets the internal floating point number for btu building rate,
  42 and so on.
  43
  44 The only other type of variable currently defined are the
  45 options. These may be specified as one or more lines starting
  46 "option" and turned off with the keyword "nooption".
  47
  48 So, for instance
  49
  50     option FUEL ORBIT
  51 and
  52     option FUEL
  53     option ORBIT
  54
  55 are equivalent
  56
  57 To turn off an option that is compiled in, you can similarly have
  58
  59     nooption FUEL
  60     nooption ORBIT
  61 or
  62     nooption FUEL ORBIT
  63
  64
  65 As a check, pconfig will printout some of the internal file names as
  66 comments at the end just to check they are in the right place.
  67
  68 The server can take a -e config file as a command line option so that
  69 it will read a specific config file. If not, it will default to
  70 looking for a file econfig in the built in data directory, but it
  71 won't mind if one is absent. Similarly, util/files and util/fairland
  72 et al all take a -e config file to run from a different config.
  73 Thus, to start two games on the same host, you might have
  74
  75 Game1:
  76 files -e econfig1
  77 fairland -e econfig1
  78 emp_sever -e econfig1
  79
  80 Game2
  81 files -e econfig2
  82 fairland -e econfig2
  83 emp_server -e econfig2
  84
  85 econfig1 might have the lines
  86 data "/empire/data1"
  87 info "/empre/info"
  88 port "7777"
  89
  90 and econfig2 might have the lines
  91
  92 data "/empire/data2"
  93 info "/empre/info"
  94 port "7778"
  95
  96 You only need the lines in that file that you require to override the
  97 compiled in definitions, however having all the definitions may help
  98 you to understand what is on and off. You could do this with
  99
 100 pconfig econfig1 > e1 && mv e1 econfig1
 101 pconfig econfig2 > e2 && mv e2 econfig2
 102
 103 which will fill in all the missing options and values with their defaults.
 104
 105
 106
 107 Coders information
 108 ------------------
 109
 110 The simplest way to describe this is to step through how a new option
 111 would be added.
 112
 113 1. Think of the option name, say, "DUMB".
 114 2. In lib/global/options.c define an integer and set it to 1 or 0 as
 115 appropriate. This is usually done as
 116 #ifdef DUMB
 117 int opt_DUMB = 1;
 118 #else
 119 int opt_DUMB = 0;
 120 #endif
 121
 122 3. At the end of that file, add an entry into the table so it is
 123 configurable. This is done with a line like
 124 { "DUMB",     &opt_DUMB },
 125 Make sure the table is still terminated by two NULL values!
 126
 127 4. In h/optlist.h add an external definition of this variable
 128
 129 extern int opt_DUMB;
 130
 131 5. Now the variable is defined, and configurable through the option
 132 keyword in the config file. So you can go ahead and make changes
 133 elsewhere in the code. This normally looks like
 134
 135           if (opt_DUMB) {
 136              pr("You're being dumb\n");
 137           } else {
 138              pr ("You're being really dumb\n");
 139           }
 140 but it may call subroutines, return early from functions or whatever.
 141