Config.xml

From FreeOrionWiki
Revision as of 16:01, 20 May 2017 by Lgmdoyle (Talk | contribs) (Update example to new logging system)

Jump to: navigation, search

The FreeOrion user settings directory contains config.xml, which contains user settings, as well as .log files generated when the game is run, and the directory containing saved games.

Some display options and other options may not have controls in the Options window, but may still be directly edited in config.xml.

When editing files for FreeOrion, a somewhat more advanced editor may be necessary. For example, on Windows, the Notepad and Wordpad editors can cause trouble, but the third party NotePad++ editor should be fine. An added benefit of using NotePad++ is that one of our contributors has made an add-on to help with the FOCS syntax.

If you damage your config.xml file you can delete it and a fresh one will be built at the start of the next game (with default parameters).

The user settings directory is located:

  • On Linux:

FreeOrion complies with the XDG Base Directory Specification.

Configuration files, such as config.xml and persistent_config.xml are stored in $XDG_CONFIG_HOME/freeorion which defaults to:

~/.config/freeorion

Application data, such as FreeOrion log files and saved games, are stored in $XDG_DATA_HOME/freeorion which defaults to:

~/.local/share/freeorion

These folders may be hidden (due to the . at the start of its name) and may not appear on all directory listings. Make sure to list hidden folders when searching for them.

  • On Windows Vista or later:
C:\Users\Username\AppData\Roaming\FreeOrion

It may be necessary to show hidden files and folders to find this directory.

  • On Windows XP:
C:\Documents and Settings\UserName\Application Data\FreeOrion

It may be necessary to show hidden files and folders to find this directory.

  • On MacOSX:
Username/Library/Application Support/FreeOrion/

Persistent Config

A persistent config file will override settings in the config.xml file.
This may be useful to keep certain settings between updates.
This file must be created manually, and is never changed by the game. Note that changes in the game will not be kept if they are defined in this file.

Before editing or starting a new file, remember to use a capable editor as mentioned previously.

To create a persistent config, copy the following into a new file named persistent_config.xml
Make sure it is located in the same directory as the config.xml file.

<?xml version="1.0"?>
<XMLDoc>
</XMLDoc>

Then copy any values you wish to keep from config.xml and place them within the XMLDoc node.

Each node in an XML file can have child nodes, make sure to copy over any parent nodes of values you copy over.
If you are unfamiliar with XML structure, there are a number of good tutorials on the web. A search for "XML tutorial" should get you started.

Any option found in the config.xml file may be used in the persistent_config.xml file.
It is recommended not to copy over version-string as this will cause your config.xml file to be reset each time the game is loaded.

Alternatively, you can copy the config.xml file to persistent_config.xml and remove any values they may change or are the default value.
If you opt for this method, try to remove as much as possible (especially the version-string), to reduce any problems from changes an update may introduce.

Since the game is constantly changing, there may be a change that causes you an issue when using a new build.
If you have a persistent_config.xml file and have an issue:

  • Rename persistent_config.xml to something else (e.g. persistent_config.old)
  • Delete the config.xml file
  • Start the game

If the issue is still present, please check the Issue tracker and the Forums.

Command line arguments override values in either config file.

Examples

Enable verbose logging:

<?xml version="1.0"?>
<XMLDoc>
  <logging>
    <execs>
      <ai>debug</ai>
      <client>warn</client>
      <server>trace</server>
    </execs>
    <sources>
      <FSM>info</FSM>
      <combat>warn</combat>
      <combat_log>trace</combat_log>
      <effects>warn</effects>
      <log>trace</log>
      <network>warn</network>
    </sources>
  </logging>
</XMLDoc>

Disable sound:

<?xml version="1.0"?>
<XMLDoc>
  <UI>
    <sound>
      <enabled>0</enabled>
    </sound>
  </UI>
</XMLDoc>