Data directories

From Arx Libertatis Wiki
Revision as of 03:05, 18 April 2012 by Ds (talk | contribs) (→‎Goals)
Jump to navigation Jump to search

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

The game will recognize 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

  • 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. Other systems should use their respective standard directories.

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. (File:Windows icon.png Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\DataDir registry key exists, use it's value.

4. (File:Windows icon.png 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.

  • File:Windows icon.png Windows: default value for DATA_DIR is 'Arx Libertatis', DATA_DIR_PREFIXES is not set
  • File:Tux.png Linux: default value for DATA_DIR is 'games/arx'
  • File:Tux.png Linux: default value for DATA_DIR_PREFIXES is '$XDG_DATA_DIRS', which defaults to '/usr/local/share/:/usr/share/' at run-time
  • File:Apple icon.png Mac OS X: default value for DATA_DIR is 'ArxLibertatis'
  • File:Apple icon.png Mac OS X: 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. (File:Windows icon.png Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir registry key exists, use it's value.

4. (File:Windows icon.png 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.

  • File:Windows icon.png Windows: default value for USER_DIR is 'Arx Libertatis'
  • File:Windows icon.png 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')
  • File:Tux.png Linux: default value for USER_DIR is 'arx'
  • File:Tux.png Linux: default value for USER_DIR_PREFIXES is '$XDG_DATA_HOME', which defaults to '$HOME/.local/share' at run-time
  • File:Apple icon.png Mac OS X: default value for USER_DIR is 'ArxLibertatis'
  • File:Apple icon.png Mac OS X: 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.

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: "."
Retrieved from "https://wiki.arx-libertatis.org/index.php?title=Data_directories&oldid=746"