Data directories: Difference between revisions
No edit summary |
(Update to match changes in the code.) |
||
Line 1: | Line 1: | ||
This page describes how data / config / save files are located by Arx Libertatis: | This page describes how data / config / save files are located by Arx Libertatis: | ||
The game will recognize | The game will recognize three different directories, a <b>data</b> directory, a <b>user</b> directory and a <b>config</b> directory. | ||
* The <b>data</b> 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 <b>data</b> 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 <b>user</b> directory holds save games | * The <b>user</b> directory holds save games, screenshots, but can also hold asset data that takes priority over that from the <b>data</b> directory (like user-installed mods). | ||
* The <b>config</b> 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. | 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. | ||
Line 27: | Line 28: | ||
5. If a <b>cmake <code>-DDATA_DIR</code> and <code>-DDATA_DIR_PREFIXES</code> options</b> are given and <code>DATA_DIR</code> is a relative path after expanding <b>environment variables</b>, interpret <code>DATA_DIR_PREFIXES</code> as a colon-separated (windows: semicolon-seperated) list (after expanding <b>environment variables</b>) and search for <code>DATA_DIR</code> in each entry. Use the first match found. | 5. If a <b>cmake <code>-DDATA_DIR</code> and <code>-DDATA_DIR_PREFIXES</code> options</b> are given and <code>DATA_DIR</code> is a relative path after expanding <b>environment variables</b>, interpret <code>DATA_DIR_PREFIXES</code> as a colon-separated (windows: semicolon-seperated) list (after expanding <b>environment variables</b>) and search for <code>DATA_DIR</code> in each entry. Use the first match found. | ||
* default value for <code>DATA_DIR</code> is 'arx' | * default value for <code>DATA_DIR</code> is 'games/arx' for Linux and 'Arx Libertatis' for Windows | ||
* (linux-only) default value for <code>DATA_DIR_PREFIXES</code> is ' | * (linux-only) default value for <code>DATA_DIR_PREFIXES</code> is '$XDG_DATA_DIRS' | ||
6. If a <b>cmake <code>-DDATA_DIR</code> option</b> was given, use it after expanding <b>environment variables</b>. | 6. If a <b>cmake <code>-DDATA_DIR</code> option</b> was given, use it after expanding <b>environment variables</b>. | ||
Line 44: | Line 45: | ||
5. If a <b>cmake <code>-DUSER_DIR</code> and <code>-DUSER_DIR_PREFIXES</code> options</b> are given and <code>USER_DIR</code> is a relative path after expanding <b>environment variables</b>, interpret <code>USER_DIR_PREFIXES</code> as a colon-separated (windows: semicolon-seperated) list (after expanding <b>environment variables</b>) and search for <code>USER_DIR</code> in each entry. Use the first match found. | 5. If a <b>cmake <code>-DUSER_DIR</code> and <code>-DUSER_DIR_PREFIXES</code> options</b> are given and <code>USER_DIR</code> is a relative path after expanding <b>environment variables</b>, interpret <code>USER_DIR_PREFIXES</code> as a colon-separated (windows: semicolon-seperated) list (after expanding <b>environment variables</b>) and search for <code>USER_DIR</code> in each entry. Use the first match found. | ||
* default value for <code>USER_DIR</code> is 'arx' | * default value for <code>USER_DIR</code> is 'arx' for Linux and 'Arx Fatalis' for Windows | ||
* (linux-only) default value for <code>USER_DIR_PREFIXES</code> is '<code>$XDG_DATA_HOME</code>' | * (linux-only) default value for <code>USER_DIR_PREFIXES</code> is '<code>$XDG_DATA_HOME</code>' | ||
* (windows-only) default value for <code>USER_DIR_PREFIXES</code> is '<code>%USERPROFILE%\My Documents\My Games</code>' on XP and '<code>%USERPROFILE%\Saved games</code>' on Vista and up | * (windows-only) default value for <code>USER_DIR_PREFIXES</code> is '<code>%USERPROFILE%\My Documents\My Games</code>' on XP and '<code>%USERPROFILE%\Saved games</code>' on Vista and up | ||
Line 50: | Line 51: | ||
6. If a <b>cmake <code>-DUSER_DIR</code> option</b> was given, use it after expanding <b>environment variables</b>. | 6. If a <b>cmake <code>-DUSER_DIR</code> option</b> was given, use it after expanding <b>environment variables</b>. | ||
7. If a data directory has been found but | 7. If a data directory has been found but no user directory and the preconditions for step 5 hold, <b>create <code>USER_DIR</code> in the first directory of <code>USER_DIR_PREFIXES</code></b> that already exists. If none of the directories in <code>USER_DIR_PREFIXES</code> exist, create the first entry. | ||
8. If a data directory has been found but | 8. If a data directory has been found but no user directory and the preconditions for step 6 hold, <b>create <code>USER_DIR</code></b>. | ||
9. Otherwise, use the <b>current working directory</b> as the user directory. | 9. Otherwise, use the <b>current working directory</b> as the user directory. | ||
If no user directory was found or could be created, quit. | |||
=== Config directory === | |||
1. If a <b><code>--config-dir=...</code> (<code>-c ...</code>) command-line option</b> is given, always use that config directory. If the requested directory doesn't exist, create it. | |||
2. If a <b>cmake <code>-DCONFIG_DIR</code> and <code>-DCONFIG_DIR_PREFIXES</code> options</b> are given and <code>CONFIG_DIR</code> is a relative path after expanding <b>environment variables</b>, interpret <code>CONFIG_DIR_PREFIXES</code> as a colon-separated (windows: semicolon-seperated) list (after expanding <b>environment variables</b>) and search for <code>CONFIG_DIR</code> in each entry. Use the first match found. | |||
* (linux-only) default value for <code>CONFIG_DIR</code> is 'arx' | |||
* (linux-only) default value for <code>CONFIG_DIR_PREFIXES</code> is '<code>$XDG_CONFIG_HOME</code>' | |||
3. If a <b>cmake <code>-DCONFIG_DIR</code> option</b> was given, use it after expanding <b>environment variables</b>. | |||
4. If a data directory has been found but no config directory and the preconditions for step 2 hold, <b>create <code>CONFIG_DIR</code> in the first directory of <code>CONFIG_DIR_PREFIXES</code></b> that already exists. If none of the directories in <code>CONFIG_DIR_PREFIXES</code> exist, create the first entry. | |||
5. If a data directory has been found but no config directory and the preconditions for step 3 hold, <b>create <code>CONFIG_DIR</code></b>. | |||
6. Otherwise, use the user directory as the config directory. | |||
If no user directory was found or could be created, quit. | If no user directory was found or could be created, quit. | ||
Line 66: | Line 85: | ||
- --data-dir (-d) command-line parameter | - --data-dir (-d) command-line parameter | ||
- Registry key {HKCU,HKLM}\Software\ArxLibertatis\DataDir | - Registry key {HKCU,HKLM}\Software\ArxLibertatis\DataDir | ||
- "arx" in one of " | - "games/arx" in one of "$XDG_DATA_DIRS" | ||
= "/usr/local | = "/usr/local/share:/usr/share": | ||
* "/usr/local/share/ | * "/usr/local/share/games/arx" | ||
* "/usr/share/games/arx" | * "/usr/share/games/arx" | ||
- "arx" | - "games/arx" | ||
selected: (none) | selected: (none) | ||
User directories ( | User directories (save files, data files): | ||
- --user-dir (-u) command-line parameter | - --user-dir (-u) command-line parameter | ||
- Registry key {HKCU,HKLM}\Software\ArxLibertatis\UserDir | - Registry key {HKCU,HKLM}\Software\ArxLibertatis\UserDir | ||
- "arx" in one of "$XDG_DATA_HOME" | - "arx" in one of "$XDG_DATA_HOME" | ||
= "/home/ | = "/home/dscharrer/.local/share": | ||
* "/home/ | * "/home/dscharrer/.local/share/arx" | ||
- "arx" | - "arx" | ||
- Current working directory | - Current working directory | ||
selected: "." | |||
Config directories: | |||
- --config-dir (-c) command-line parameter | |||
- "arx" in one of "$XDG_CONFIG_HOME" | |||
= "/home/dscharrer/.config": | |||
* "/home/dscharrer/.config/arx" | |||
- "arx" | |||
- The selected user directory | |||
selected: "." | selected: "." |
Revision as of 18:30, 22 March 2012
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
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 (windows: semicolon-seperated) list (after expanding environment variables) and search for DATA_DIR
in each entry. Use the first match found.
- default value for
DATA_DIR
is 'games/arx' for Linux and 'Arx Libertatis' for Windows - (linux-only) default value for
DATA_DIR_PREFIXES
is '$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=...
(-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.
- default value for
USER_DIR
is 'arx' for Linux and 'Arx Fatalis' for Windows - (linux-only) default value for
USER_DIR_PREFIXES
is '$XDG_DATA_HOME
' - (windows-only) default value for
USER_DIR_PREFIXES
is '%USERPROFILE%\My Documents\My Games
' on XP and '%USERPROFILE%\Saved games
' on Vista and up
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.
- (linux-only) default value for
CONFIG_DIR
is 'arx' - (linux-only) default value for
CONFIG_DIR_PREFIXES
is '$XDG_CONFIG_HOME
'
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 - Registry key {HKCU,HKLM}\Software\ArxLibertatis\DataDir - "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 - Registry key {HKCU,HKLM}\Software\ArxLibertatis\UserDir - "arx" in one of "$XDG_DATA_HOME" = "/home/dscharrer/.local/share": * "/home/dscharrer/.local/share/arx" - "arx" - Current working directory selected: "." Config directories: - --config-dir (-c) command-line parameter - "arx" in one of "$XDG_CONFIG_HOME" = "/home/dscharrer/.config": * "/home/dscharrer/.config/arx" - "arx" - The selected user directory selected: "."