Data file locations
===================

When Dwarf Fortress is started via /usr/games/dwarf-fortress (or the
accompanying desktop menu entry) it will look for data files in these
locations:

 * /usr/share/games/dwarf-fortress/gamedata (for vanilla
   dwarf-fortress data contained in the Debian package)
 * /usr/local/share/games/dwarf-fortress/* (for data installed by the
   local administrator)
 * $XDG_DATA_DIRS/dwarf-fortress/* (for user data, usually refers to
   $HOME/.local/share/dwarf-fortress)

If a file with the same relative path is contained in more than one of
these directories, the files from the latter directories take
precedence over the former.

All modifications made to data files made by Dwarf Dortress during
gameplay (such as saved worlds) are retained in
$XDG_DATA_HOME/dwarf-fortress/run.

Configuration file locations
============================

When Dwarf Fortress is started, it looks for configurations files in
the usual data file locations described above under the data/init
subdirectory.

Additionally it will look for configuration files found in
$XDG_CONFIG_DIRS/dwarf-fortress and include those as well. Files
placed in these directories should be placed directly there without
the data/init subdirectory.

When configuration files with the same name are found both in
configuration directories as well as in data file directories, the
files from configuration file directories take precedence.

Installing data files
=====================

(The instructions below describe installing into
$XDG_DATA_HOME/dwarf-fortress. The same instructions also apply when
installing into /usr/local/share/games/dwarf-fortress)

If you want to install additional data files such a tilesets you can
just drop the additional data files into as subdirectory of
$XDG_DATA_HOME/dwarf-fortress preserving their intended directory
structure (e.g. if the installation instructions of the files your are
installing tell you to install something into the dwarf-fortress
directory at data/art/ you should put it into
$XDG_DATA_HOME/dwarf-fortress/something/data/art). Note that some
directories, such as raw, which normally exist in a dwarf-fortress
installation may not exist yet. In that case just create them as
needed.

Modifying configuration files
=============================

When you modify configuration files or create new ones you should only
modify those in $XDG_DATA_DIRS, never those in data file locations,
because modifications to the latter directories will be overwritten on
package updates.

In practice this usually means that you want to apply configuration
changes in ~/.config/dwarf-fortress or /etc/xdg/dwarf-fortress.

When looking into $XDG_CONFIG_HOME (usually ~/.config/dwarf-fortress)
you might notice, that Dwarf Fortress automatically creates symlinks
to other configuration files found in $XDG_CONFIG_DIRS. This has
internal reasons. You can ignore these symlinks, replace them with
your own configuration files or even create symlinks pointing
somewhere else. Dwarf Fortress will always try to not interfere with
changes you make to this directory.

 -- Sven Bartscher <kritzefitz@debian.org>, Fri, 26 Mar 2021 16:03:01 +0100