Data directories

This page describes how data / config / save files are located by Arx Libertatis:

The game recognizes three different directories, a data directory, a user directory and a config 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, screenshots, but can also hold asset data that takes priority over that from the data directory (like user-installed mods).
• The config directory holds cfg.ini.

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

• It should be possible to load data, save and config files from the current working directory.
• 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. Other systems should use their respective standard directories.

Default directories

ℹ️  Currently Arx Libertatis requires some filenames and directory names in the user, config and data directories to be lower-case, even on case-insensitive filesystems like Windows'.

This section provides a summary of the default directories. Besides the operating system-specific directories below, Arx Libertatis will use the current working directory as the user and config directory if no system-wide data directory has been found. This allows setting up portable installations of arx. If you want to force arx to use the current directory even if there is a system-wide installation, run it as

arx --no-data-dir --user-dir=. --config-dir=.

Windows

• user and config dir:
  • XP: '%USERPROFILE%\My Documents\My Games\Arx Libertatis'
  • Vista and up: '%USERPROFILE%\Saved Games\Arx Libertatis'
• data dir: location stored in HKCU\Software\ArxLibertatis\DataDir or HKLM\Software\ArxLibertatis\DataDir registry keys

Linux

• user dir: '~/.local/share/arx/'
• config dir: '~/.config/arx/'
• data dir: '/usr/share/games/arx/' or '/usr/local/share/games/arx/'

macOS

• user and config dir: '~/Library/Application Support/ArxLibertatis/'
• data dir: '/Applications/ArxLibertatis/'

Directory detection procedure

Here the complete detection procedure is detailed. For normal users the default directories described in the previous section should be enough, but the procedure has been designed to allow users to overwrite these directories to accommodate edge cases.

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 (windows: semicolon-seperated) list (after expanding environment variables) and search for DATA_DIR in each entry. Use the first match found.

• Windows: default value for DATA_DIR is 'Arx Libertatis'; DATA_DIR_PREFIXES is not set
• Linux: default value for DATA_DIR is 'games/arx'
• Linux: default value for DATA_DIR_PREFIXES is '$XDG_DATA_DIRS', which defaults to '/usr/local/share/:/usr/share/' at run-time
• macOS: default value for DATA_DIR is 'ArxLibertatis'
• macOS: default value for DATA_DIR_PREFIXES is '/Applications'

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=... (-u ...) 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 (windows: semicolon-seperated) list (after expanding environment variables) and search for USER_DIR in each entry. Use the first match found.

• Windows: default value for USER_DIR is 'Arx Libertatis'
• Windows: default value for USER_DIR_PREFIXES is '%FOLDERID_SavedGames%' which expands to:
  • Windows XP: the 'My Games' subdirectory in 'My Documents' (default: %USERPROFILE%\My Documents\My Games')
  • Windows Vista and up: the standard Saved Games directory (default: '%USERPROFILE%\Saved Games')
• Linux: default value for USER_DIR is 'arx'
• Linux: default value for USER_DIR_PREFIXES is '$XDG_DATA_HOME', which defaults to '$HOME/.local/share' at run-time
• macOS: default value for USER_DIR is 'ArxLibertatis'
• macOS: value for USER_DIR_PREFIXES is '~/Library/Application Support'

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

7. If a data directory has been found but no 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 no 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.

Config directory

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

2. If a cmake -DCONFIG_DIR and -DCONFIG_DIR_PREFIXES options are given and CONFIG_DIR is a relative path after expanding environment variables, interpret CONFIG_DIR_PREFIXES as a colon-separated (windows: semicolon-seperated) list (after expanding environment variables) and search for CONFIG_DIR in each entry. Use the first match found.

• Windows and macOS: CONFIG_DIR and CONFIG_DIR_PREFIXES are not set
• Linux: default value for CONFIG_DIR is 'arx'
• Linux: default value for CONFIG_DIR_PREFIXES is '$XDG_CONFIG_HOME', which defaults to '$HOME/.config' at run-time

3. If a cmake -DCONFIG_DIR option was given, use it after expanding environment variables.

4. If a data directory has been found but no config directory and the preconditions for step 2 hold, create CONFIG_DIR in the first directory of CONFIG_DIR_PREFIXES that already exists. If none of the directories in CONFIG_DIR_PREFIXES exist, create the first entry.

5. If a data directory has been found but no config directory and the preconditions for step 3 hold, create CONFIG_DIR.

6. Otherwise, use the user directory as the config directory.

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

Troubleshooting

The --list-dirs (-l) command-line option can be used to print all the data and user directories considered by the game.

Example output under Linux without a system-wide installation:

Data directories (data files):
 - --data-dir (-d) command-line parameter
 - "games/arx" in one of "$XDG_DATA_DIRS"
    = "/usr/local/share:/usr/share":
  * "/usr/local/share/games/arx"
  * "/usr/share/games/arx"
 - "games/arx"
selected: (none)

User directories (save files, data files):
 - --user-dir (-u) command-line parameter
 - "arx" in one of "$XDG_DATA_HOME"
    = "/home/user/.local/share":
  * "/home/user/.local/share/arx"
 - "arx"
 - Current working directory
selected: "."

Config directories:
 - --config-dir (-c) command-line parameter
 - "arx" in one of "$XDG_CONFIG_HOME"
    = "/home/user/.config":
  * "/home/user/.config/arx"
 - "arx"
 - The selected user directory
selected: "."