Data directories

This page describes the current proposal for how data / config / save files should be located (see also https://github.com/arx/ArxLibertatis/issues/88):

The game will recognize two different directories, a data directory and a user directory.

• The data directory holds read-only asset data and possibly a cfg_default.ini. The data directory can be empty to only load data from the user directory.
• The user directory holds save games, cfg.ini, screenshots, but can also hold asset data that takes priority over that from the data directory (like user-installed mods).

This should allow the game run either from all files in the current directory or from a system-wide installation with per-user config and save files.

Goals

• Starting from a local directory should be as simple as possibly and store saves/settings in that directory. This is for compatibility with the current way arx-libertatis is run and to allow easier testing.
• Windows installers should be able to specify the directories in the registry.
• By default, linux installations should look in the directories specified by the XDG Base Directory Specification

Directory detection procedure

1. If a --data-dir=... command-line option is given, always use that data directory.

2. If a --user-dir=... command-line option is given, always use that user directory.

3. If neither command-line option is given and the current directory contains the game data files, set the user directory to the current directory and the data directory to empty (none).

• TODO what files should be checked for? Just data.pak or all pak files? Checking for cfg.ini / cfg_default.ini won't work because that file might not exist before the first run. Also, we need to take case-sensitivity into account for non-windows systems when checking if files exist.
• Maybe we should remove the automatic to-lowercase procedure and instead make that an explicit step users need to do? I would still recommend doing that step on all systems (both windows and linux) though, as
  • some paths (the misc and graph directories) will be mapped to internal asset names, which are always case-sensitive.
  • this will make it easier to move/share installations between linux and windows.
• TODO should we check for write permissions?
• TODO maybe we should allow to disable this with a command-line option?

4. (windows-only) If appropriate registry keys exist, use those for the data/user directory.

• HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir
• HKEY_CURRENT_USER\Software\ArxLibertatis\DataDir

5. If a cmake -DDATA_DIR option was given and it (expanding environment variables) is an absolute path, use that.

• default value is 'arx'

6. If DATA_DIR expands to a relative path and a cmake -DDATA_DIR_PREFIXES option (colon-seperated list after expanding environment variables) was given, search for ${DATA_DIR} in all entries in ${DDATA_DIR_PREFIXES}.

• (linux-only) default value for DATA_DIR_PREFIXES is '$XDG_DATA_DIRS'

7. If a cmake -DUSER_DIR option was given and it (expanding environment variables) is an absolute path, use that.

• default value is 'arx'

8. If USER_DIR expands to a relative path and a cmake -DUSER_DIR_PREFIXES option (colon-seperated list) was given, search for ${USER_DIR} in all entries in ${USER_DIR_PREFIXES}. If none was found and a data directory was detected, create a ${USER_DIR} subdirectory in the first entry of ${USER_DIR_PREFIXES} and use that as the user directory.

• (linux-only) default value for USER_DIR_PREFIXES is '$XDG_DATA_HOME'
• (windows-only) default value for USER_DIR_PREFIXES is '%USERPROFILE%/TODO'

9. If no user directory was found, quit. If no data directory was found and the user directory doesn't contain all required assets, quit.