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

Data directory

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

2. If a --no-data-dir (-n) command-line option is given, don't use a separate data directory.

3. (windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\DataDir registry key exists, use it's value.

4. (windows-only) If the HKEY_LOCAL_MACHINE\Software\ArxLibertatis\DataDir registry key exists, use it's value.

5. If a cmake -DDATA_DIR and -DDATA_DIR_PREFIXES options are given and DATA_DIR is a relative path after expanding environment variables, interpret DATA_DIR_PREFIXES as a colon-separated list (after expanding environment variables) and search for DATA_DIR in each entry. Use the first match found.

• default value is 'arx'
• (linux-only) default value for DATA_DIR_PREFIXES is '${CMAKE_INSTALL_PREFIX}/share:$XDG_DATA_DIRS'

6. If a cmake -DDATA_DIR option was given, use it after expanding environment variables.

If a data directory was found but does not exist, clear it. If no data directory was found, that's ok - the user directory can contain all required files.

User directory

1. If a --user-dir=... command-line option is given, always use that user directory. If the requested directory doesn't exist, create it.

3. (windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir registry key exists, use it's value.

4. (windows-only) If the HKEY_LOCAL_MACHINE\Software\ArxLibertatis\UserDir registry key exists, use it's value.

5. If a cmake -DUSER_DIR and -DUSER_DIR_PREFIXES options are given and USER_DIR is a relative path after expanding environment variables, interpret USER_DIR_PREFIXES as a colon-separated list (after expanding environment variables) and search for USER_DIR in each entry. Use the first match found.

• default value is 'arx'
• (linux-only) default value for USER_DIR_PREFIXES is '$XDG_DATA_HOME'
• (windows-only) default value for USER_DIR_PREFIXES is '%USERPROFILE%/My Documents/Games'

6. If a cmake -DUSER_DIR option was given, use it after expanding environment variables.

7. If a data directory has been found but not user directory and the preconditions for step 5 hold, create USER_DIR in the first directory of USER_DIR_PREFIXES that already exists. If none of the directories in USER_DIR_PREFIXES exist, create the first entry.

8. If a data directory has been found but not user directory and the preconditions for step 6 hold, create USER_DIR.

9. Otherwise, use the current working directory as the user directory.

If no user directory was found or could be created, quit.