X-Git-Url: http://git.pond.sub.org/?p=empserver;a=blobdiff_plain;f=doc%2Feconfig;h=794d814e5d8428f0c9f8abc0961795f9736b163a;hp=32c3bf547aa267ce1ebe162094fcd034c23ae0a4;hb=HEAD;hpb=5b57f4c222d925448aaee2d1344f1cb0304d6513 diff --git a/doc/econfig b/doc/econfig index 32c3bf547..794d814e5 100644 --- a/doc/econfig +++ b/doc/econfig @@ -1,75 +1,42 @@ -This is a short note on the empire configuration stuff. Some of this -is for deities to enable them to configure things, some of it is for -coders to see how this stuff works. +This is a short note on the Empire run-time configuration stuff. Some +of this is for deities to enable them to configure things, some of it +is for coders to see how this stuff works. Julian Onions 15/7/95 --- -Also, the Empire config files are now self-documenting (to a point.) -Each option/variable now has a comment associated with it to hopefully -make life easier on deities wanting to change things. - --- Steve McClure, 10/21/1998 -- -Deity Notes ------------ +Deity Information +----------------- -To find out the current configuration, the simplest method is to -compile up util/pconfig and the run it. It can be run either with no -arguments, in which case it will printout in config format the current -compiled in options. Otherwise with a file containing a configuration -it will first read in this file, and override any compiled in -variables and then printout the merged options. +To find out the compiled-in configuration, the simplest method is to +run pconfig. It can be run either with no arguments, in which case it +will print the current compiled-in configuration in econfig format. +Otherwise, with a file name argument, it will first read in this file, +and override any compiled in variables, and then print the merged +configuration. -So the first method shows you what's compiled in, the 2nd how a config -file would modify this. +So the first method shows you what's compiled in, the second how a +config file would modify this. Blank lines are ignored, as are lines starting with a # character. -Most of the options are straight forward, they take either a string -(quote using " to get spaces in it) or a number - integer or floating -point depending on the option. - -For instance - privname "The Deity" -sets the internal privname variable to that string, and - port "7777" -sets the empire port to 7777. - btu_build_rate 0.0004 -sets the internal floating point number for btu building rate, -and so on. - -The only other type of variable currently defined are the -options. These may be specified as one or more lines starting -"option" and turned off with the keyword "nooption". - -So, for instance - - option FUEL ORBIT -and - option FUEL - option ORBIT - -are equivalent +A line of the form KEY VALUE configures an econfig key to a value. A +value is either a string (quote using " to get spaces in it), an +integer or a floating-point number, depending on the key. -To turn off an option that is compiled in, you can similarly have +For instance, + data "/empire/data" +configures the data directory to that place, and + port "7777" +configures the empire port to 7777, + btu_build_rate 0.0004 +configures the BTU build rate, and so on. - nooption FUEL - nooption ORBIT -or - nooption FUEL ORBIT - - -As a check, pconfig will printout some of the internal file names as -comments at the end just to check they are in the right place. - -The server can take a -e config file as a command line option so that -it will read a specific config file. If not, it will default to -looking for a file econfig in the built in data directory, but it -won't mind if one is absent. Similarly, util/files and util/fairland -et al all take a -e config file to run from a different config. -Thus, to start two games on the same host, you might have +The programs look for the config file in a compiled-in location, which +is shown by emp_server -h. Use -e to make the programs use another +config file instead. Thus, to start two games on the same host, you +might have Game1: files -e econfig1 @@ -94,51 +61,60 @@ info "/empire/info.nr" port "7778" You only need the lines in that file that you require to override the -compiled in definitions, however having all the definitions may help -you to understand what is on and off. You could do this with +compiled-in definitions, however having all the definitions may help +you to understand what is on and off. You could do this with pconfig econfig1 > e1 && mv e1 econfig1 pconfig econfig2 > e2 && mv e2 econfig2 -which will fill in all the missing options and values with their defaults. +which will fill in all the missing keys and values with their defaults. + +You define your update schedule in the schedule file, in the same +directory as your econfig. See doc/schedule for details. +Additional customization is possible through key custom_tables, which +is a list of files containing tables in xdump format (see doc/xdump +for technical information on xdump). To customize a table, copy the +default table from the directory given by econfig key builtindir to a +file next to your econfig, then name the file in custom_tables. Do +*not* edit the default table in-place! That bypasses important +consistency checks. + +A word of caution: Just because you can customize something doesn't +mean you should! The server makes an effort to catch mistakes that +could crash the game. It has no chance to catch mistakes that +unbalance it. Coder information ----------------- -The simplest way to describe this is to step through how a new option -would be added. +The simplest way to describe this is perhaps to step through how a new +key would be added. Let's do this for a new option "DUMB". -1. Think of the option name, say, "DUMB". -2. In src/lib/global/options.c define an integer and set it to 1 or 0 -as appropriate. This is usually done as +1. Define the variable for the key. Options go into +src/lib/global/options.c, like this: -#ifdef DUMB int opt_DUMB = 1; -#else -int opt_DUMB = 0; -#endif -3. At the end of that file, add an entry into the table so it is -configurable. This is done with a line like +The initializer provides the compiled-in value. + +Other keys go into src/lib/global/constants.c. - { "DUMB", &opt_DUMB }, +2. Declare the econfig key in include/econfig-spec.h: -Make sure the table is still terminated by two NULL values! +EMPCF_OPT("DUMP", opt_DUMP, "Enable additional dumbness") -4. In include/optlist.h add an external definition of this variable +For a non-option key, you'd use EMPCFBOTH() there. -extern int opt_DUMB; +The declaration is visible both in include/optlist.h as an external +variable, and in struct keymatch configkeys[], which is used by the +econfig parser. -5. Now the variable is defined, and configurable through the option -keyword in the config file. So you can go ahead and make changes -elsewhere in the code. This normally looks like +3. Use the variable in your code. This normally looks like if (opt_DUMB) { - pr("You're being dumb\n"); + pr("You're being dumb\n"); } else { - pr ("You're being really dumb\n"); + pr("You're being really dumb\n"); } - -but it may call subroutines, return early from functions or whatever.