diff --git a/USERGUIDE.md b/USERGUIDE.md index 3a7572b23..f17cc741c 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -148,6 +148,29 @@ There will be a lot of directories created if using the es_systems.xml file bund ![alt text](images/es-de_ui_easy_setup.png "ES-DE Easy Setup") _This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._ +## Placing games into non-standard directories + +As explained above, the basic logic for how ES-DE works is that it expects game files to be placed into a standardized directory structure under the ROMs directory. The location of this directory is configurable so it could for instance be placed on an external storage device or on a file share served by a NAS. The way it's implemented is via the %ROMPATH% variable in the es_systems.xml file which will always point to this ROM directory. For example this is an entry for the Super Nintendo system: +``` +%ROMPATH%/snes +``` + +In theory it's possible to make a custom system entry and hardcode the path to a specific directory instead of using the %ROMPATH% variable, but this is not really supported and it also makes custom collections non-portable as the path to every game will be an absolute path rather than a path relative to the %ROMPATH% variable. So if you move your games to a different directory, you would manually need to modify all your custom collections configuration files as well as your custom es_systems.xml file. + +If you really insist on not placing your games into the ES-DE standard directory structure, a much better solution is to symlink the game directories into the standard directory. In this way you don't need to make a custom es_systems.xml file and any additional emulators and other configuration added to future ES-DE releases will just work after upgrading. + +This is an example of symlinking the Super Nintendo game directory on Unix and macOS: +``` +cd ~/ROMs +ln -s ~/my_games/super_nintendo/ snes +``` + +And on Windows (you need to run this as Administrator): +``` +cd C:\Users\Myusername\ROMs +mklink /D snes "C:\My Games\Super Nintendo\" +``` + ## Disabling game systems The way ES-DE works is that it will always try to load any system for which there are game files available, so to disable a system it needs to be hidden from ES-DE. This is easily accomplished by renaming the game directory to something that is not recognized, for example changing `~/ROMs/c64` to `~/ROMs/c64_DISABLED`. Another approach is to create a subdirectory named DISABLED (or whatever name you prefer that is not matching a supported system) in the ROMs directory and move the game folder there, such as `~/ROMs/DISABLED/c64`. This makes it easy to disable and re-enable game systems in ES-DE. Note that the gamelist and any game media files are retained while the system is disabled so this is an entirely safe thing to do.