Data directories

From Arx Libertatis Wiki
Jump to navigation Jump to search

This page describes how data, config and 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 directories hold read-only asset data and possibly config defaults (namely cfg_default.ini). There can be multiple data directories, sorted by priority.
  • The user directory holds save games, screenshots. This is generally also a high-priority data directory to allow for user-specific overrides / mods.
  • The config directory holds config files (namely cfg.ini).

This should allow the game run either from a portable install, or from a system-wide installation with per-user config and save files.

Goals

Default directories

This section provides a summary of the default data, config and save file directories.

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 and FreeBSD

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

macOS

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

Portable installs

If you want to force arx to use the current directory for data, config and save files, run it as 

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

Directory detection procedure

Here the complete detection algorithm 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.

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. If it could not be created, abort.

2. ( Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir or HKEY_LOCAL_MACHINE\Software\ArxLibertatis\UserDir registry key exists, use its value. If both exist, use first. If the directory doesn't exists create it. If it could not be created, continue with the next step.

3. If the cmake -DUSER_DIR_PREFIXES and/or -DUSER_DIR options are given, interpret them as a colon-separated (Windows: semicolon-seperated) lists after expanding environment variables and search for all USER_DIR_PREFIXES + USER_DIR permutations ordered by the prefix index first and the suffix index second. Use the first match found.

  • Windows: default value for USER_DIR is 'Arx Libertatis'
  • Windows: default value for USER_DIR_PREFIXES is (unset)
  • Windows: besides the paths from USER_DIR_PREFIXES, additional paths are searched:
    • 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'

4. If the preconditions for the previousstep hold, create the first 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.

5. 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. If it could not be created, abort.

2. If the cmake -DCONFIG_DIR_PREFIXES and/or -DCONFIG_DIR options are given, interpret them as a colon-separated (Windows: semicolon-seperated) lists after expanding environment variables and search for all CONFIG_DIR_PREFIXES + CONFIG_DIR permutations ordered by the prefix index first and the suffix index second. 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 the preconditions for the previous step hold, create the first 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.

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

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

Data directory

1. Add the user directory as the first data directory.

2. For each --data-dir=... (-d ...) command-line option is given, add the value as the next data directory.

3. If a --no-data-dir (-n) command-line option is given, skip all following steps.

4. If the <exename>_PATH environment variable is set, interpret its value as a colon-separated (Windows: semicolon-seperated) lists and append all entries to the list of data directories.

5. If the directory containing the game executable is not one listed in -DIGNORE_EXE_DIR cmake option, add it as the last data directory.

  • Linux: default value for IGNORE_EXE_DIR is '/usr/bin:/usr/games:/usr/games/bin:/usr/local/bin:/usr/local/games:/usr/local/games/bin'

6. ( Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\DataDir or HKEY_LOCAL_MACHINE\Software\ArxLibertatis\DataDir registry key exists, add the value as the next data directory. If both exist, use first.

7. If the cmake -DDATA_DIR_PREFIXES and/or -DDATA_DIR options are given, interpret them as a colon-separated (Windows: semicolon-seperated) lists after expanding environment variables and append all DATA_DIR_PREFIXES + DATA_DIR permutations ordered by the prefix index first and the suffix index second to the list of data directories.

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

Ignore non-existent data directories. Ignore duplicated data directories, keeping the first instance.

For all of these search paths (except those manually added using --data-dir options): If a search paths contains a data subdirectory, add that first. If an entry contains a data file, interpret each line as a path (relative to the base search path) and add those first.

If no separate data directory was found, that's ok - the user directory can contain all required files.

For Windows registry keys, read both 32-bit and 64-bit registries - first the one native to the current process, then the foreign one.

Troubleshooting

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

On Windows arx.exe is a GUI application and you will not be able to see the --list-dirs output. Instead, you can use the option with arxunpak.exe.

Example output under Linux without a system-wide installation: 

User directories (select first existing):
 - --user-dir (-u) command-line parameter
 - "$XDG_DATA_HOME" / "arx":
  -> "/home/user/.local/share/arx"
 - Current working directory
selected: "/home/user/.local/share/arx"

Config directories (select first existing):
 - --config-dir (-c) command-line parameter
 - "$XDG_CONFIG_HOME" / "arx":
  -> "/home/user/.config/arx"
 - The selected user directory
selected: "/home/user/.config/arx"

Data directories (decreasing priority):
 - The selected user directory
 - --data-dir (-d) command-line parameters
 only without --no-data-dir (-n): 
 - "$XDG_DATA_DIRS:/opt" / "games/arx:arx":
  -> "/usr/local/share/games/arx"
  -> "/usr/local/share/arx"
  -> "/usr/share/games/arx"
  -> "/usr/share/arx"
  -> "/opt/games/arx"
  -> "/opt/arx"
 - The directory containing the game executable
selected:
 - "/home/user/.local/share/arx"
 - "/usr/share/games/arx"
Retrieved from "https://wiki.arx-libertatis.org/index.php?title=Data_directories&oldid=5459"