diff --git a/CHANGELOG.md b/CHANGELOG.md index e47b8096a..85b297615 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,10 +20,11 @@ * Added the .dirksimple file extension to the daphne and laserdisc systems * (Unix) Removed the -Minimized flag from the Visual Pinball launch command * (Windows) Updated the find rules for Visual Pinball to match the actual filenames of the official releases +* (Windows) Added the %RUNINBACKGROUND% variable for the epic system +* (Windows) Removed support for building the application using MinGW * Added a "renderDuringTransitions" property to the image element * Added support for the 1:1 display aspect ratio * Added workarounds for some mobile GPUs which do not support all OpenGL operations when using the BGRA pixel format -* Replaced a number of homecooked functions in FileSystemUtil with those from the C++ Standard Library ### Bug fixes diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 0709f81d2..376fddb8e 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -162,7 +162,7 @@ make -j8 ``` Due to buggy AMD GPU drivers it could be a good idea to use the `LSAN_suppressions` file included in the repository to avoid reports of a lot of irrelevant issue, for example: ``` -LSAN_OPTIONS="suppressions=tools/LSAN_suppressions" ./emulationstation --debug --resolution 2560 1440 +LSAN_OPTIONS="suppressions=tools/LSAN_suppressions" ./es-de --debug --resolution 2560 1440 ``` This applies to LeakSanitizer specifically, which is integrated into AddressSanitizer. @@ -175,7 +175,7 @@ make -j8 It could also be a good idea to use the `TSAN_suppressions` file included in the repository to suppress issues reported by some third party libraries, for example: ``` -TSAN_OPTIONS="suppressions=tools/TSAN_suppressions" ./emulationstation --debug --resolution 2560 1440 +TSAN_OPTIONS="suppressions=tools/TSAN_suppressions" ./es-de --debug --resolution 2560 1440 ``` To enable UndefinedBehaviorSanitizer which helps with identifying bugs that may otherwise be hard to find, build with the UBSAN option: @@ -196,17 +196,17 @@ As for advanced debugging, Valgrind is a very powerful and useful tool which can The most common tool is Memcheck to check for memory leaks, which you run like this: ``` -valgrind --tool=memcheck --leak-check=full --log-file=../valgrind_run_01 ./emulationstation +valgrind --tool=memcheck --leak-check=full --log-file=../valgrind_run_01 ./es-de ``` There are numerous flags that can be used, for example this will also track reachable memory which could indicate further leaks: ``` -valgrind --tool=memcheck --leak-check=full --track-origins=yes --show-reachable=yes --log-file=../valgrind_run_01 ./emulationstation +valgrind --tool=memcheck --leak-check=full --track-origins=yes --show-reachable=yes --log-file=../valgrind_run_01 ./es-de ``` Another helpful tool is the Callgrind call-graph analyzer: ``` -valgrind --tool=callgrind --log-file=../valgrind_run_01 ./emulationstation +valgrind --tool=callgrind --log-file=../valgrind_run_01 ./es-de ``` The output file can be loaded into an application such as KCachegrind for data analysis. @@ -215,7 +215,7 @@ The output file can be loaded into an application such as KCachegrind for data a Yet another very useful Valgrind tool is the Massif heap profiler, which can be run like this: ``` -valgrind --tool=massif --massif-out-file=../massif.out.01 ./emulationstation +valgrind --tool=massif --massif-out-file=../massif.out.01 ./es-de ``` The output file can be loaded into an application such as Massif-Visualizer for analysis. @@ -303,35 +303,35 @@ sudo make install Assuming the default installation prefix /usr has been used, this is the directory structure for the installation: ``` -/usr/bin/emulationstation +/usr/bin/es-de /usr/bin/es-pdf-convert -/usr/share/applications/org.es_de.emulationstation-de.desktop -/usr/share/emulationstation/licenses/* -/usr/share/emulationstation/resources/* -/usr/share/emulationstation/themes/* -/usr/share/emulationstation/LICENSE -/usr/share/icons/hicolor/scalable/apps/org.es_de.emulationstation-de.svg -/usr/share/man/man6/emulationstation.6.gz -/usr/share/metainfo/org.es_de.emulationstation-de.appdata.xml -/usr/share/pixmaps/org.es_de.emulationstation-de.svg +/usr/share/applications/org.es_de.frontend.desktop +/usr/share/es-de/licenses/* +/usr/share/es-de/resources/* +/usr/share/es-de/themes/* +/usr/share/es-de/LICENSE +/usr/share/icons/hicolor/scalable/apps/org.es_de.frontend.svg +/usr/share/man/man6/es-de.6.gz +/usr/share/metainfo/org.es_de.frontend.appdata.xml +/usr/share/pixmaps/org.es_de.frontend.svg ``` However, when installing manually instead of building a package, it's recommended to change the install prefix to /usr/local instead of /usr. -Be aware that if using the GNOME desktop environment, /usr/share/pixmaps/emulationstation.svg must exist in order for the ES-DE icon to be shown in the Dash and task switcher. +Be aware that if using the GNOME desktop environment, /usr/share/pixmaps/org.es_de.frontend.svg must exist in order for the ES-DE icon to be shown in the Dash and task switcher. ES-DE will look in the following locations for application resources, in the listed order: -* \/.emulationstation/resources/ -* \/share/emulationstation/resources/ +* \/ES-DE/resources/ +* \/share/es-de/resources/ * \/resources/ The resources directory is critical, without it the application won't start. As well the following locations will be searched for themes, also in the listed order: -* \/.emulationstation/themes/ -* \/share/emulationstation/themes/ +* \/ES-DE/themes/ +* \/share/es-de/themes/ * \/themes/ A theme is not mandatory to start the application, but ES-DE will be basically useless without it. @@ -346,23 +346,23 @@ Creation of Debian .deb packages is enabled by default, simply run `cpack` to ge myusername@computer:~/emulationstation-de$ cpack CPack: Create package using DEB CPack: Install projects -CPack: - Run preinstall target for: emulationstation-de -CPack: - Install project: emulationstation-de [] +CPack: - Run preinstall target for: es-de +CPack: - Install project: es-de [] CPack: Create package CPackDeb: - Generating dependency list -CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-2.2.0-x64.deb generated. +CPack: - package: /home/myusername/emulationstation-de/es-de_3.0.0-x64.deb generated. ``` You may want to check that the dependencies look fine, as they're (mostly) automatically generated by CMake: ``` -dpkg -I ./emulationstation-de-2.2.0-x64.deb +dpkg -I ./es-de_3.0.0-x64.deb ``` The package can now be installed using a package manager, for example apt: ``` -sudo apt install ./emulationstation-de-2.2.0-x64.deb +sudo apt install ./es-de_3.0.0-x64.deb ``` To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example: @@ -377,11 +377,11 @@ Then simply run `cpack`: myusername@computer:~/emulationstation-de$ cpack CPack: Create package using RPM CPack: Install projects -CPack: - Run preinstall target for: emulationstation-de -CPack: - Install project: emulationstation-de [] +CPack: - Run preinstall target for: es-de +CPack: - Install project: es-de [] CPack: Create package -CPackRPM: Will use GENERATED spec file: /home/myusername/emulationstation-de/_CPack_Packages/Linux/RPM/SPECS/emulationstation-de.spec -CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-2.2.0-x64.rpm generated. +CPackRPM: Will use GENERATED spec file: /home/myusername/emulationstation-de/_CPack_Packages/Linux/RPM/SPECS/es-de.spec +CPack: - package: /home/myusername/emulationstation-de/es-de_3.0.0-x64.rpm generated ``` On Fedora, you need to install rpmbuild before this command can be run: @@ -391,17 +391,17 @@ sudo dnf install rpm-build After the package generation you can check that the metadata looks fine using the `rpm` command: ``` -rpm -qi ./emulationstation-de-2.2.0-x64.rpm +rpm -qi ./es-de_3.0.0-x64.rpm ``` To see the automatically generated dependencies, run this: ``` -rpm -q --requires ./emulationstation-de-2.2.0-x64.rpm +rpm -q --requires ./es-de_3.0.0-x64.rpm ``` And of course, you can also install the package: ``` -sudo dnf install ./emulationstation-de-2.2.0-x64.rpm +sudo dnf install ./es-de_3.0.0-x64.rpm ``` **Creating an AppImage** @@ -576,37 +576,37 @@ make install This will be the directory structure for the installation: ``` -/Applications/EmulationStation Desktop Edition.app/Contents/Info.plist -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/es-pdf-convert -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.0.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavcodec.60.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavfilter.9.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavformat.60.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavutil.58.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfontconfig.1.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libgit2.1.6.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libjpeg.62.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libopenjp2.7.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpoppler-cpp.0.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpoppler.129.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpostproc.57.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.4.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.7.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libtiff.6.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbis.0.4.9.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbisenc.2.0.12.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/EmulationStation-DE.icns -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/LICENSE -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/licenses/* -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/* -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/* +/Applications/ES-DE.app/Contents/Info.plist +/Applications/ES-DE.app/Contents/MacOS/ES-DE +/Applications/ES-DE.app/Contents/MacOS/es-pdf-convert +/Applications/ES-DE.app/Contents/MacOS/libSDL2-2.0.0.dylib +/Applications/ES-DE.app/Contents/MacOS/libavcodec.60.dylib +/Applications/ES-DE.app/Contents/MacOS/libavfilter.9.dylib +/Applications/ES-DE.app/Contents/MacOS/libavformat.60.dylib +/Applications/ES-DE.app/Contents/MacOS/libavutil.58.dylib +/Applications/ES-DE.app/Contents/MacOS/libfontconfig.1.dylib +/Applications/ES-DE.app/Contents/MacOS/libfreetype.6.dylib +/Applications/ES-DE.app/Contents/MacOS/libgit2.1.6.dylib +/Applications/ES-DE.app/Contents/MacOS/libjpeg.62.dylib +/Applications/ES-DE.app/Contents/MacOS/libopenjp2.7.dylib +/Applications/ES-DE.app/Contents/MacOS/libpoppler-cpp.0.dylib +/Applications/ES-DE.app/Contents/MacOS/libpoppler.129.dylib +/Applications/ES-DE.app/Contents/MacOS/libpostproc.57.dylib +/Applications/ES-DE.app/Contents/MacOS/libswresample.4.dylib +/Applications/ES-DE.app/Contents/MacOS/libswscale.7.dylib +/Applications/ES-DE.app/Contents/MacOS/libtiff.6.dylib +/Applications/ES-DE.app/Contents/MacOS/libvorbis.0.4.9.dylib +/Applications/ES-DE.app/Contents/MacOS/libvorbisenc.2.0.12.dylib +/Applications/ES-DE.app/Contents/Resources/ES-DE.icns +/Applications/ES-DE.app/Contents/Resources/LICENSE +/Applications/ES-DE.app/Contents/Resources/licenses/* +/Applications/ES-DE.app/Contents/Resources/resources/* +/Applications/ES-DE.app/Contents/Resources/themes/* ``` ES-DE will look in the following locations for application resources, in the listed order: -* \/.emulationstation/resources/ +* \/ES-DE/resources/ * \/../Resources/resources/ * \/resources/ @@ -614,7 +614,7 @@ The resources directory is critical, without it the application won't start. As well the following locations will be searched for themes, also in the listed order: -* \/.emulationstation/themes/ +* \/ES-DE/themes/ * \/../Resources/themes/ * \/themes/ @@ -630,19 +630,15 @@ Simply run `cpack` to build a .dmg disk image/installer: myusername@computer:~/emulationstation-de$ cpack CPack: Create package using Bundle CPack: Install projects -CPack: - Run preinstall target for: emulationstation-de -CPack: - Install project: emulationstation-de [] +CPack: - Run preinstall target for: es-de +CPack: - Install project: es-de [] CPack: Create package -CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-2.2.0-x64.dmg generated. +CPack: - package: /Users/myusername/emulationstation-de/ES-DE_3.0.0-arm64.dmg generated. ``` ## Building on Windows -Although both Microsoft Visual C++ (MSVC) and GCC (MinGW) have historically been supported for building ES-DE on Windows, as of the 2.2.0 release MinGW is no longer recommended and support for it will likely be dropped in future releases. - -Although MinGW produces much higher quality code than MSVC with ES-DE running around 10% to 25% faster it's unfortunately not sustainable to keep using it. There are multiple technical issues with third party libraries like severe threading issues with FFmpeg and some libraries like Poppler not being readily available. Debugging with MinGW is also a very slow and tedious process compared to MSVC. MinGW up to 9.2.0 works more or less fine but anything more modern than this introduces issues like FFmpeg's avfilter_graph_free() call taking up to 7000 times longer to complete which makes video playback unusable. Setting filter graphs to use single threads solves some but not all issues. As well libgit2 has (probably) a race condition that causes random repository corruption that is likely only present when using MinGW. - -Clang/LLVM has also been evaluated but it suffers from at least the same threading issues as MinGW, likely because it uses libraries from the latter. It also fails to build some of the third party libraries needed by ES-DE. +Only the Microsoft Visual C++ (MSVC) compiler is supported on Windows. Although MinGW/GCC produces higher quality code with ES-DE running around 10% to 25% faster it's unfortunately not sustainable to use it. There are multiple technical issues with third party libraries like severe threading issues with FFmpeg and some libraries like Poppler not being readily available. **MSVC setup** @@ -679,21 +675,6 @@ The way the MSVC environment works is that a specific developer shell is provide It's important to choose the x64-specific shell and not the x86 variant, as ES-DE will only compile as a 64-bit application. -**MinGW (GCC) setup** - -Download the following packages and install them: - -[https://gitforwindows.org](https://gitforwindows.org) - -[https://cmake.org/download](https://cmake.org/download) - -Download the _MinGW-w64 based_ version of GCC: \ -[https://jmeubank.github.io/tdm-gcc](https://jmeubank.github.io/tdm-gcc) - -After installation, make a copy of `TDM-GCC-64\bin\mingw32-make` to `make` for your convenience. - -Only version 9.2.0 of MinGW has been confirmed to work correctly, anything newer introduces severe problems and MSVC should instead be used if a more modern compiler is required. - **Other preparations** In order to get clang-format onto the system you need to download and install Clang/LLVM: \ @@ -709,7 +690,7 @@ Configure Git. Details about its setup is beyond the scope of this document, but It's strongly recommended to set line breaks to Unix-style (line feed only) directly in the code editor. But if not done, lines breaks will anyway be converted when running clang-format on the code, as explained [here](INSTALL-DEV.md#using-clang-format-for-automatic-code-formatting). -The instructions below assume all build steps for MSVC are done in the MSVC developer console (x64 Native Tools Command Prompt for VS) and all MinGW build steps are done using the Git Bash shell. +The instructions below assume all build steps for MSVC are done in the MSVC developer console (x64 Native Tools Command Prompt for VS). **Cloning and setting up dependencies** @@ -726,29 +707,21 @@ cd emulationstation-de git checkout stable-2.2 ``` -On Windows all dependencies are kept in-tree in the `external` directory tree. Most of the libraries can be downloaded in binary form, but a few need to be built from source code. There are four scripts in the tools directory that automate this entirely. Two of them are used for the MSVC compiler and the other two for MinGW. +On Windows all dependencies are kept in-tree in the `external` directory tree. Most of the libraries can be downloaded in binary form, but a few need to be built from source code. There are two scripts in the tools directory that automate this entirely. You run them like this: -For MSVC, you run them like this: ``` cd emulationstation-de -tools\Windows_dependencies_setup_MSVC.bat -tools\Windows_dependencies_build_MSVC.bat -``` - -And for MinGW like the following: -``` -cd emulationstation-de -tools/Windows_dependencies_setup_MinGW.sh -tools/Windows_dependencies_build_MinGW.sh +tools\Windows_dependencies_setup.bat +tools\Windows_dependencies_build.bat ``` Re-running the setup script will delete and download all dependencies again, and re-running the build script will clean and rebuild from scratch. -The setup scripts for both MSVC and MinGW will download and launch an installer for OpenSSL for Windows if this has not already been installed on the build machine. Just run through the installer using the default settings and everything should work fine. +The setup scripts will download and launch an installer for OpenSSL for Windows if this has not already been installed on the build machine. Just run through the installer using the default settings and everything should work fine. Following these preparations, ES-DE should be ready to be compiled. -**Building ES-DE using MSVC** +**Building ES-DE** It's assumed that [Jom](https://wiki.qt.io/Jom) is used, but if instead using nmake then just remove _JOM_ from the -G flag argument and remove the -j flag as nmake does not support building in parallel. @@ -777,31 +750,7 @@ nmake ThreadSanitizer and UndefinedBehaviorSanitizer aren't available for the MSVC compiler. -There are a number of compiler warnings for the bundled rlottie library when building with MSVC. Unfortunately these need to be resolved upstream, but everything should still work fine so the warnings can be ignored for now. - -**Building ES-DE using MinGW** - -For a release build: - -``` -cmake -G "MinGW Makefiles" . -make -j8 -``` - -Or for a debug build: - -``` -cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug . -make -j8 -``` - -Change the -j flag to whatever amount of parallel threads you want to use for the compilation. - -Unfortunately AddressSanitizer, ThreadSanitizer and UndefinedBehaviorSanitizer do not seem to be supported with MinGW. - -You run a parallel build using multiple CPU cores with the `-j` flag, for example, `make -j6`. - -Note that compilation time is much longer than on Unix/Linux or macOS, and linking is incredibly slow for a debug build (around 10 times longer compared to Linux). The debug binary is also much larger than on Unix. +There are a number of compiler warnings for the bundled rlottie library. Unfortunately these need to be resolved upstream, but everything should still work fine so the warnings can be ignored for now. **TLS/SSL certificates** @@ -829,24 +778,24 @@ After the installation has been completed, go to the emulationstation-de directo $ cpack CPack: Create package using NSIS CPack: Install projects -CPack: - Run preinstall target for: emulationstation-de -CPack: - Install project: emulationstation-de [] +CPack: - Run preinstall target for: es-de +CPack: - Install project: es-de [] CPack: Create package -CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-2.2.0-x64.exe generated. +CPack: - package: C:/Programming/emulationstation-de/ES-DE_3.0.0-x64.exe generated. ``` -The default installation directory suggested by the installer is `C:\Program Files\EmulationStation-DE` but this can of course be changed by the user. +The default installation directory suggested by the installer is `C:\Program Files\ES-DE` but this can of course be changed by the user. ES-DE will look in the following locations for application resources, in the listed order: -* \\\.emulationstation\resources\ +* \\\ES-DE\resources\ * \\resources\ The resources directory is critical, without it the application won't start. As well the following locations will be searched for themes, also in the listed order: -* \\\.emulationstation\themes\ +* \\\ES-DE\themes\ * \\themes\ A theme is not mandatory to start the application, but ES-DE will be basically useless without it. @@ -1017,9 +966,9 @@ The reason to not simply replace the BIOS and devices files with the new version ## Configuration -**~/.emulationstation/es_settings.xml** +**~/ES-DE/settings/es_settings.xml** -When ES-DE is first started, a configuration file will be created as `~/.emulationstation/es_settings.xml` +When ES-DE is first started, a configuration file will be created as `~/ES-DE/settings/es_settings.xml` This file will contain all supported settings at their default values. Normally you shouldn't need to modify this file manually, instead you should be able to use the menu inside ES-DE to update all the necessary settings. @@ -1051,11 +1000,11 @@ There is also support to add the variable %ESPATH% to the ROM directory setting, ``` -**~/.emulationstation/es_input.xml** +**~/ES-DE/settings/es_input.xml** As ES-DE auto-configures the keyboard and controllers, neither the input configuration step or manual adjustments to the es_input.xml file should normally be needed. Actually, unless the button layout has been customized using the input configurator, the es_input.xml file will not even exist. -But if you have customized your button layout and your controller or keyboard stop working, you can delete the `~/.emulationstation/es_input.xml` file to remove the customizations, or you can start ES-DE with the `--force-input-config` command line option to make the input configurator appear. +But if you have customized your button layout and your controller or keyboard stop working, you can delete the `~/ES-DE/settings/es_input.xml` file to remove the customizations, or you can start ES-DE with the `--force-input-config` command line option to make the input configurator appear. The input configuration is described in the [User guide](USERGUIDE-DEV.md#input-device-configuration). @@ -1091,7 +1040,7 @@ You can use **--help** or **-h** to view the list of command line options, as sh _The --anti-aliasing option is not available if ES-DE is built using the OpenGL ES renderer and the --no-update-check option is not available for builds where the application updater is disabled._ -As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `emulationstation --home ~/games/emulation`, ES-DE will use `~/games/emulation/.emulationstation` as its application home directory. Be aware that this option completely replaces what is considered the home directory, meaning the default ROM directory ~/ROMs would be resolved to ~/games/emulation/ROMs. The same is true for the emulator core locations if es_find_rules.xml is configured to look for them relative to the home directory. So of course RetroArch and other emulators would also need to be configured to use ~/games/emulation as its base directory in this instance. +As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `es-de --home ~/games/emulation`, ES-DE will use `~/games/emulation/ES-DE` as its application data directory. Be aware that this option completely replaces what is considered the home directory, meaning the default ROM directory ~/ROMs would be resolved to ~/games/emulation/ROMs. The same is true for the emulator core locations if es_find_rules.xml is configured to look for them relative to the home directory. So of course RetroArch and other emulators would also need to be configured to use ~/games/emulation as its base directory in this instance. Setting --resolution to a lower or higher value than the display resolution will add a border to the application window. The exception is if defining a lower resolution than the display resolution in combination with the --fullscreen-padding flag as this will pad the screen contents on a black background. This can be combined with the --screenoffset option for exact positioning on displays where bezels or similar may obstruct part of the viewable area. @@ -1132,7 +1081,7 @@ Enabling this will skip all debug messages about missing files specifically for **LegacyGamelistFileLocation** -As of ES-DE 2.0.0 any gamelist.xml files stored in the game system directories (e.g. under `~/ROMs/`) will not get loaded, they are instead required to be placed in the `~/.emulationstation/gamelists/` directory tree. By setting this option to `true` it's however possible to retain the old behavior of first looking for gamelist.xml files in the system directories on startup. Note that even if this setting is enabled ES-DE will still always create new gamelist.xml files under `~/.emulationstation/gamelists/` which was the case also for the 1.x.x releases. +As of ES-DE 2.0.0 any gamelist.xml files stored in the game system directories (e.g. under `~/ROMs/`) will not get loaded, they are instead required to be placed in the `~/ES-DE/gamelists/` directory tree. By setting this option to `true` it's however possible to retain the old behavior of first looking for gamelist.xml files in the system directories on startup. Note that even if this setting is enabled ES-DE will still always create new gamelist.xml files under `~/ES-DE/gamelists/` which was the case also for the 1.x.x releases. **LottieMaxFileCache** @@ -1160,7 +1109,261 @@ The passkey to use to change from the _Kiosk_ or _Kid_ UI modes to the _Full_ UI **UserThemeDirectory** -Sets the user theme directory. If left blank it will default to `~/.emulationstation/themes/` +Sets the user theme directory. If left blank it will default to `~/ES-DE/themes/` + +## es_find_rules.xml + +This file makes it possible to define rules for where to search for the emulator binaries and emulator cores. + +The file is located in the resources directory in the same location as the es_systems.xml file, but a customized copy can be placed in ~/ES-DE/custom_systems, which will complement the bundled file. + +Here's an example es_find_rules.xml file for Linux (this is not the complete file shipped with ES-DE as that would be too large to include here): +```xml + + + + + + + bash + sh + + + + + retroarch + org.libretro.RetroArch + + + ~/Applications/RetroArch-Linux*.AppImage + ~/.local/bin/RetroArch-Linux*.AppImage + ~/bin/RetroArch-Linux*.AppImage + /var/lib/flatpak/exports/bin/org.libretro.RetroArch + ~/.local/share/flatpak/exports/bin/org.libretro.RetroArch + + + + + + ~/snap/retroarch/current/.config/retroarch/cores + + ~/.var/app/org.libretro.RetroArch/config/retroarch/cores + + ~/.config/retroarch/cores + + /usr/lib/x86_64-linux-gnu/libretro + + /usr/lib64/libretro + + /usr/lib/libretro + + + + + + dosbox-staging + io.github.dosbox-staging + + + /var/lib/flatpak/exports/bin/io.github.dosbox-staging + ~/.local/share/flatpak/exports/bin/io.github.dosbox-staging + + + + + + yuzu + org.yuzu_emu.yuzu + + + ~/Applications/yuzu*.AppImage + ~/.local/bin/yuzu*.AppImage + ~/bin/yuzu*.AppImage + /var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu + ~/.local/share/flatpak/exports/bin/org.yuzu_emu.yuzu + + + +``` + +It's pretty straightforward, there are currently four rules supported for finding emulators, `winregistrypath`, `winregistryvalue`, `systempath` and `staticpath` and there is one rule supported for finding the emulator cores, `corepath`. + +Of these, `winregistrypath` and `winregistryvalue` are only available on Windows, and attempting to use the rule on any other operating system will generate a warning in the log file when processing the es_find_rules.xml file. + +The `name` attribute must correspond to the command tags in es_systems.xml, take for example this line: +```xml +%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% +``` + +Here %EMULATOR_ and %CORE_ are followed by the string RETROARCH which corresponds to the name attribute in es_find_rules.xml. The name is case sensitive but it's recommended to use uppercase names to make the variables feel consistent (%EMULATOR_retroarch% doesn't look so pretty). + +Of course this makes it possible to add any number of emulators to the configuration file. + +The find rules can also be used by the %PRECOMMAND_ variable, which is for instance useful for running Windows emulators on Linux using Wine or Proton. In the following example two separate find rules are used, one for the %PRECOMMAND_ variable and another one for the %EMULATOR_ variable: +```xml +%STARTDIR%=%EMUDIR% %PRECOMMAND_WINE% %EMULATOR_XENIA-WINDOWS% %ROM% +``` + +The `winregistrypath` rule searches the Windows Registry "App Paths" keys for the emulators defined in the `` tags. If for example this tag is set to `retroarch.exe`, a search will be performed for the key `SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\retroarch.exe`. HKEY_CURRENT_USER is tried first, and if no key is found there, HKEY_LOCAL_MACHINE is tried as well. In addition to this, ES-DE will check that the binary defined in the default value for the key actually exists. If not, it will proceed with the next rule. Be aware that the App Paths keys are added by the emulators during their installation, and although RetroArch does add this key, not all emulators do. + +The `winregistryvalue` rule will search for the specific registry value, and if it exists, it will use that value as the path to the emulator binary. HKEY_CURRENT_USER will be tried first, followed by HKEY_LOCAL_MACHINE. In the same manner as `winregistrypath`, ES-DE will check that the binary defined in the registry value actually exists. If not, it will proceed with the next rule. For example, if setting the `` tag for this rule to `SOFTWARE\Valve\Steam\SteamExe`, the emulator binary would be set to `c:\program files (x86)\steam\steam.exe`, assuming that's where Steam has been installed. As this rule can be used to query any value in the Registry, it's a quite powerful tool to locate various emulators and applications. In addition to this it's posssible to append an arbitrary string to the key value if it's found and use that as the emulator binary path. This is accomplished by using the pipe sign, so for example the entry `SOFTWARE\PCSX2\Install_Dir|\pcsx2.exe` will look for the key `SOFTWARE\PCSX2\Install_Dir` and if it's found it will take the value of that key and append the string `\pcsx2.exe` to it. This could for example result in `C:\Program Files (x86)\PCSX2\pcsx2.exe`. Also for this setup, ES-DE will check that the emulator binary actually exists, or it will proceed to the next rule. + +The other rules are probably self-explanatory with `systempath` searching the PATH environment variable for the binary names defined by the `` tags and `staticpath` defines absolute paths to the emulators. For staticpath, the actual emulator binary must be included in the entry tag. Wildcards (*) are supported for the emulator binary, but not for directories. Wildcards are very useful for AppImages which often embed version information into the filenames. Note that if multiple files match a wildcard pattern, the first file returned by the operating system will be selected. + +```xml + + + ~/Applications/yuzu*.AppImage + + ~/Applications/yuzu*.App* + + ~/App*/yuzu*.AppImage + +``` + +There is also support for substituting the emulator binary in a staticpath rule with an explicit command. To accomplish this add a pipe (|) character after the emulator entry followed by the command to execute. This is for example useful for Flatpaks when you want to check the presence of a package while still launching a specific command inside the package using the --command option. For example: + +``` xml + + /var/lib/flatpak/exports/bin/com.github.AmatCoder.mednaffe|flatpak run --command=mednafen com.github.AmatCoder.mednaffe + ~/.local/share/flatpak/exports/bin/com.github.AmatCoder.mednaffe|flatpak run --command=mednafen com.github.AmatCoder.mednaffe + +``` + +This will execute the regular logic of checking if the Mednaffe Flatpak is installed but will actually run the command after the pipe character when launching the game. Note that no checks or controls are in place for the explicitly defined command, it's just blindly executed. + +The winregistrypath rules are always processed first, followed by winregistryvalue, then systempath and finally staticpath. This is done regardless of which order they are defined in the es_find_rules.xml file. + +As for `corepath` this rule is simply a path to search for the emulator core. + +Each rule supports multiple entry tags which are tried in the order that they are defined in the file. + +The %ESPATH% and %ROMPATH% variables can be used inside the staticpath rules and the %ESPATH% and %EMUPATH% variables can be used inside the corepath rules. + +The tilde symbol `~` is supported for the staticpath and corepath rules and will expand to the user home directory. Be aware that if ES-DE has been started with the --home command line option, the home directory is considered to be whatever path was passed as an argument to that option. The same is true if using a portable.txt file. + +All these options combined makes it possible to create quite powerful find rules. + +For reference, here are also example es_find_rules.xml files for macOS and Windows: + +```xml + + + + + + + zsh + bash + + + + + /Applications/RetroArch.app/Contents/MacOS/RetroArch + + + + + + ~/Library/Application Support/RetroArch/cores + + /Applications/RetroArch.app/Contents/Resources/cores + + + + + + /Applications/dosbox-staging.app/Contents/MacOS/dosbox + /opt/homebrew/bin/dosbox-staging + /usr/local/bin/dosbox-staging + + + + + + /Applications/mupen64plus.app/Contents/MacOS/mupen64plus + /usr/local/bin/mupen64plus + + + + + + /Applications/PCSX2.app/Contents/MacOS/PCSX2 + + + +``` + +```xml + + + + + + + cmd.exe + + + + + + retroarch.exe + + + + retroarch.exe + + + + C:\RetroArch-Win64\retroarch.exe + C:\RetroArch\retroarch.exe + ~\AppData\Roaming\RetroArch\retroarch.exe + C:\Program Files\RetroArch-Win64\retroarch.exe + C:\Program Files\RetroArch\retroarch.exe + C:\Program Files (x86)\RetroArch-Win64\retroarch.exe + C:\Program Files (x86)\RetroArch\retroarch.exe + + C:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe + D:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe + C:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe + D:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe + + %ESPATH%\Emulators\RetroArch-Win64\retroarch.exe + %ESPATH%\Emulators\RetroArch\retroarch.exe + %ESPATH%\..\Emulators\RetroArch-Win64\retroarch.exe + %ESPATH%\..\Emulators\RetroArch\retroarch.exe + + + + + %EMUPATH%\cores + + + + + + pcsx2-qt.exe + pcsx2-qtx64.exe + pcsx2-qtx64-avx2.exe + + + %ESPATH%\Emulators\PCSX2-Qt\pcsx2-qt*.exe + %ESPATH%\..\Emulators\PCSX2-Qt\pcsx2-qt*.exe + + + + + + yuzu.exe + + + ~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe + %ESPATH%\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe + %ESPATH%\..\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe + + + +``` ## es_systems.xml @@ -1168,11 +1371,11 @@ The es_systems.xml file contains the game systems configuration data for ES-DE, ES-DE ships with a comprehensive `es_systems.xml` file and most users will probably never need to make any customizations. But there may be special circumstances such as wanting to use different emulators for some game systems or perhaps to add additional systems altogether. -To accomplish this, ES-DE supports customizations via a separate es_systems.xml file that is to be placed in the `custom_systems` folder in the application home directory, i.e. `~/.emulationstation/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows unless overridden via the --home command line option.) +To accomplish this, ES-DE supports customizations via a separate es_systems.xml file that is to be placed in the `custom_systems` folder in the application home directory, i.e. `~/ES-DE/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows unless overridden via the --home command line option.) This custom file functionality is designed to be complementary to the bundled es_systems.xml file, meaning you should only add entries to the custom configuration file for game systems that you actually want to add or override. So to for example customize a single system, this file should only contain a single `` tag. The structure of the custom file is identical to the bundled file with the exception of an additional optional tag named ``. If this is placed in the custom es_systems.xml file, ES-DE will not load the bundled file. This is normally not recommended and should only be used for special situations. At the end of this section you can find an example of a custom es_systems.xml file. -The bundled es_systems.xml file is located in the resources directory that is part of the application installation. For example this could be `/usr/share/emulationstation/resources/systems/unix/es_systems.xml` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/systems/macos/es_systems.xml` on macOS or `C:\Program Files\EmulationStation-DE\resources\systems\windows\es_systems.xml` on Windows. The actual location may differ from these examples of course, depending on where ES-DE has been installed. +The bundled es_systems.xml file is located in the resources directory that is part of the application installation. For example this could be `/usr/share/es-de/resources/systems/linux/es_systems.xml` on Linux, `/Applications/ES-DE.app/Contents/Resources/resources/systems/macos/es_systems.xml` on macOS or `C:\Program Files\ES-DE\resources\systems\windows\es_systems.xml` on Windows. The actual location may differ from these examples of course, depending on where ES-DE has been installed. If you're using the AppImage release of ES-DE then the bundled es_systems.xml file is embedded in the AppImage together with the rest of the resources. @@ -1398,10 +1601,10 @@ And finally one for Windows: ``` -As well, here's an example for Unix of a custom es_systems.xml file placed in ~/.emulationstation/custom_systems/ that overrides a single game system from the bundled configuration file: +As well, here's an example for Linux of a custom es_systems.xml file placed in ~/ES-DE/custom_systems/ that overrides a single game system from the bundled configuration file: ```xml - + nes @@ -1464,9 +1667,130 @@ Here is yet another example with the addition of the `snes` system where some fi ``` +## es_find_rules.xml and es_systems.xml on Android + +ES-DE works a bit differently on Android which is also reflected in the es_find_rules.xml and es_systems.xml configuration. Emulators on Android are launched via so-called _Intents_ which is an API rather than the typical command line approach used on Unix systems. Although ES-DE on Windows also uses an API call to launch emulators it's still closely connected to the regular operating system paradigms on how to start binaries and pass application options so the systems configuration still looks quite traditional. On Android this is not the case and there is therefore a heavy use of variables to reflect the Intent API functionality. + +To better understand the configuration in this section it could be a good idea to refer the official Android documentation:\ +https://developer.android.com/reference/android/content/Intent + +There is a command line tool in Android named _am_ which implements the _Intent_ API and can be used to test emulator launching, but this is not intended to be used by other applications and therefore ES-DE implements direct (albeit partial) support for the Intent API. Testing the modern FileProvider interface using the _am_ utility may also be difficult, or maybe impossible. + +**es_find_rules.xml** + +The es_find_rules.xml file is structured the same as for the other operating systems but there'a special _androidpackage_ find rule where you define the name of the emulator package as well as optionally which _activity_ to launch. If the activity is not defined then the default one for the package will be used. Although this may work in some instances it's usually a good idea to explicity set it. Apart from that the find rules work as on the other platforms, i.e. they will be traversed in the order they are defined. So by adding multiple _androidpackage_ entries for an emulator it's possible to look for multiple releases or forks without having to create separate emulator entries in es_systems.xml. It's also possible to override find rules by adding an ES-DE/custom_systems/es_find_rules.xml file, again the same logic applies as for all other platforms. + +The _androidpackage_ find rule entries are structured as `packagename/activity` and if only a package is defined then the forward slash can be omitted, i.e. only `packagename` is needed. + +Here's an example es_find_rules.xml file defining two emulators: + +```xml + + + + + + com.retroarch.aarch64/com.retroarch.browser.retroactivity.RetroActivityFuture + com.retroarch.ra32/com.retroarch.browser.retroactivity.RetroActivityFuture + com.retroarch/com.retroarch.browser.retroactivity.RetroActivityFuture + + + + + + org.yuzu.yuzu_emu.ea/org.yuzu.yuzu_emu.activities.EmulationActivity + org.yuzu.yuzu_emu/org.yuzu.yuzu_emu.activities.EmulationActivity + + + +``` + +**es_systems.xml** + +The es_systems.xml file on Android utilizes variables heavily to implement the _Intent_ API and these variables are covered in detail below. It's possible to override the systems configuration by adding an ES-DE/custom_systems/es_systems.xml file, the same logic applies as for all other platforms. + +`%EMULATOR_` - This utilizes the emulator find rules as defined in `es_find_rules.xml`. This is the only way to configure the launch command on Android and it works identically to the other platforms. + +`%ACTION%` - The general Intent action to be performed, you need to assign its value using an equal sign. + +There are two main ways to pass options to emulators, using _extras_ or using the _data_ URI. There can only be a single data URI but there can be an arbitrary amount of extras. To understand more about the way this works, you can read about the _putExtra()_ and and _setData()_ functions here:\ +https://developer.android.com/reference/android/content/Intent + +There are three approaches to passing game ROMs to emulators by using the following variables: + +`%ROM%` - Replaced with the absolute path to the selected ROM. This is a traditional method to provide the game ROM and its use will likely decrease or go away completely long term as emulators move to more modern methods. + +`%ROMSAF%` - Replaced with an Android Storage Access Framework (SAF) document URI which always starts with the _content://com.android.externalstorage.documents/_ string. You can read more about the SAF here:\ +https://developer.android.com/guide/topics/providers/document-provider + +`%ROMPROVIDER%` - This is the most modern approach to passing game ROMs to emulators. It uses the _FileProvider_ API to provide permissions to the file. This means that you don't need to setup the emulator upfront to have access to the directory where the game file is stored, access is instead temporarily granted by ES-DE. You can read more about the FileProvider API here:\ +https://developer.android.com/reference/androidx/core/content/FileProvider + +The `%ROM%` and `%ROMSAF%` variables can be used with both the `%DATA%` and `%EXTRA_` variables, but `%ROMPROVIDER%` can only be used with the `%DATA%` variable. For the `%DATA%` variable you'll just assign the ROM variable with an equal sign as there can only be a single _setData()_ API call per Intent. For the `%EXTRA_` variable you need to specify a name of the extra and then define it using an equal sign as an arbitrary amount of _putExtra()_ API calls can be used for an Intent. There is also a special `%EXTRABOOL_` variable that specifically passes boolean values (true/false) to emulators that support such arguments. + +Here are some examples to clarify how this works: +``` +%DATA%=%ROM% +%DATA%=%ROMSAF% +%DATA%=%ROMPROVIDER% +%EXTRA_ROM%=%ROM% +%EXTRA_bootPath%=%ROMSAF% +%EXTRABOOL_resumeState%=false +``` + +There is also support for a couple of activity flags that affect the emulator/game launch behavior, you can read more about these flags here:\ +https://developer.android.com/reference/android/content/Intent + +The descriptions below are taken from the official documentation just linked above: + +`%ACTIVITY_CLEAR_TASK%` - If set in an Intent passed to Context.startActivity(), this flag will cause any existing task that would be associated with the activity to be cleared before the activity is started. That is, the activity becomes the new root of an otherwise empty task, and any old activities are finished. + +`%ACTIVITY_CLEAR_TOP%` - If set, and the activity being launched is already running in the current task, then instead of launching a new instance of that activity, all of the other activities on top of it will be closed and this Intent will be delivered to the (now on top) old activity as a new Intent. + +`%ACTIVITY_NO_HISTORY%` - If set, the new activity is not kept in the history stack. As soon as the user navigates away from it, the activity is finished. This may also be set with the noHistory attribute. If set, onActivityResult() is never invoked when the current activity starts a new activity which sets a result and finishes. + +Here's an example es_systems.xml file for Android: +```xml + + + + + gc + Nintendo GameCube + %ROMPATH%/gc + .ciso .CISO .dff .DFF .dol .DOL .elf .ELF .gcm .GCM .gcz .GCZ .iso .ISO .json .JSON .m3u .M3U .rvz .RVZ .tgc .TGC .wad .WAD .wbfs .WBFS .wia .WIA .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=/data/data/%ANDROIDPACKAGE%/cores/dolphin_libretro_android.so %EXTRA_ROM%=%ROM% + %EMULATOR_DOLPHIN% %ACTION%=android.intent.action.MAIN %DATA%=%ROMPROVIDER% + gc + gc + + + n3ds + Nintendo 3DS + %ROMPATH%/n3ds + .3ds .3DS .3dsx .3DSX .app .APP .axf .AXF .cci .CCI .cxi .CXI .elf .ELF .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=/data/data/%ANDROIDPACKAGE%/cores/citra_libretro_android.so %EXTRA_ROM%=%ROM% + %EMULATOR_CITRA% %ACTIVITY_NO_HISTORY% %EXTRA_SelectedGame%=%ROMSAF% + %EMULATOR_CITRA-MMJ% %EXTRA_GamePath%=%ROM% + n3ds + n3ds + + + psx + Sony PlayStation + %ROMPATH%/psx + .bin .BIN .cbn .CBN .ccd .CCD .chd .CHD .cue .CUE .ecm .ECM .exe .EXE .img .IMG .iso .ISO .m3u .M3U .mdf .MDF .mds .MDS .minipsf .MINIPSF .pbp .PBP .psexe .PSEXE .psf .PSF .toc .TOC .z .Z .znx .ZNX .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=mednafen_psx_libretro_android.so %EXTRA_ROM%=%ROM% + %EMULATOR_DUCKSTATION% %EXTRABOOL_resumeState%=false %EXTRA_bootPath%=%ROMSAF% + psx + psx + + +``` + ## es_systems_sorting.xml -This file makes it possible to apply a custom systems sorting without having to modify the es_systems.xml file directly. It should be placed in the custom_systems directory, e.g. `~/.emulationstation/custom_systems/es_systems_sorting.xml` +This file makes it possible to apply custom systems sorting without having to modify the es_systems.xml file directly. It should be placed in the custom_systems directory, e.g. `~/ES-DE/custom_systems/es_systems_sorting.xml` Note that in order for ES-DE to load this file you'll need to set the _Systems sorting_ option in the _UI settings_ menu to _Full names or custom_. @@ -1507,272 +1831,14 @@ These files include all systems supported by ES-DE and provide the following sor You can apply any of these sorting files via the _Systems sorting_ option in the _Other settings_ menu. Note that in order to load a es_systems_sorting.xml file placed in the custom_systems directory you'll need to set this option to _Full names or custom_. -## es_find_rules.xml - -This file makes it possible to define rules for where to search for the emulator binaries and emulator cores. - -The file is located in the resources directory in the same location as the es_systems.xml file, but a customized copy can be placed in ~/.emulationstation/custom_systems, which will complement the bundled file. - -Here's an example es_find_rules.xml file for Unix (this is not the complete file shipped with ES-DE as that would be too large to include here): -```xml - - - - - - - bash - sh - - - - - retroarch - org.libretro.RetroArch - - - ~/Applications/RetroArch-Linux*.AppImage - ~/.local/bin/RetroArch-Linux*.AppImage - ~/bin/RetroArch-Linux*.AppImage - /var/lib/flatpak/exports/bin/org.libretro.RetroArch - ~/.local/share/flatpak/exports/bin/org.libretro.RetroArch - - - - - - ~/snap/retroarch/current/.config/retroarch/cores - - ~/.var/app/org.libretro.RetroArch/config/retroarch/cores - - ~/.config/retroarch/cores - - /usr/lib/x86_64-linux-gnu/libretro - - /usr/lib64/libretro - - /usr/lib/libretro - - /usr/local/lib/libretro - - /usr/pkg/lib/libretro - - - - - - dosbox-staging - io.github.dosbox-staging - - - /var/lib/flatpak/exports/bin/io.github.dosbox-staging - ~/.local/share/flatpak/exports/bin/io.github.dosbox-staging - - - - - - yuzu - org.yuzu_emu.yuzu - - - ~/Applications/yuzu*.AppImage - ~/.local/bin/yuzu*.AppImage - ~/bin/yuzu*.AppImage - /var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu - ~/.local/share/flatpak/exports/bin/org.yuzu_emu.yuzu - - - -``` - -It's pretty straightforward, there are currently four rules supported for finding emulators, `winregistrypath`, `winregistryvalue`, `systempath` and `staticpath` and there is one rule supported for finding the emulator cores, `corepath`. - -Of these, `winregistrypath` and `winregistryvalue` are only available on Windows, and attempting to use the rule on any other operating system will generate a warning in the log file when processing the es_find_rules.xml file. - -The `name` attribute must correspond to the command tags in es_systems.xml, take for example this line: -```xml -%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% -``` - -Here %EMULATOR_ and %CORE_ are followed by the string RETROARCH which corresponds to the name attribute in es_find_rules.xml. The name is case sensitive but it's recommended to use uppercase names to make the variables feel consistent (%EMULATOR_retroarch% doesn't look so pretty). - -Of course this makes it possible to add any number of emulators to the configuration file. - -The find rules can also be used by the %PRECOMMAND_ variable, which is for instance useful for running Windows emulators on Linux using Wine or Proton. In the following example two separate find rules are used, one for the %PRECOMMAND_ variable and another one for the %EMULATOR_ variable: -```xml -%STARTDIR%=%EMUDIR% %PRECOMMAND_WINE% %EMULATOR_XENIA-WINDOWS% %ROM% -``` - -The `winregistrypath` rule searches the Windows Registry "App Paths" keys for the emulators defined in the `` tags. If for example this tag is set to `retroarch.exe`, a search will be performed for the key `SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\retroarch.exe`. HKEY_CURRENT_USER is tried first, and if no key is found there, HKEY_LOCAL_MACHINE is tried as well. In addition to this, ES-DE will check that the binary defined in the default value for the key actually exists. If not, it will proceed with the next rule. Be aware that the App Paths keys are added by the emulators during their installation, and although RetroArch does add this key, not all emulators do. - -The `winregistryvalue` rule will search for the specific registry value, and if it exists, it will use that value as the path to the emulator binary. HKEY_CURRENT_USER will be tried first, followed by HKEY_LOCAL_MACHINE. In the same manner as `winregistrypath`, ES-DE will check that the binary defined in the registry value actually exists. If not, it will proceed with the next rule. For example, if setting the `` tag for this rule to `SOFTWARE\Valve\Steam\SteamExe`, the emulator binary would be set to `c:\program files (x86)\steam\steam.exe`, assuming that's where Steam has been installed. As this rule can be used to query any value in the Registry, it's a quite powerful tool to locate various emulators and applications. In addition to this it's posssible to append an arbitrary string to the key value if it's found and use that as the emulator binary path. This is accomplished by using the pipe sign, so for example the entry `SOFTWARE\PCSX2\Install_Dir|\pcsx2.exe` will look for the key `SOFTWARE\PCSX2\Install_Dir` and if it's found it will take the value of that key and append the string `\pcsx2.exe` to it. This could for example result in `C:\Program Files (x86)\PCSX2\pcsx2.exe`. Also for this setup, ES-DE will check that the emulator binary actually exists, or it will proceed to the next rule. - -The other rules are probably self-explanatory with `systempath` searching the PATH environment variable for the binary names defined by the `` tags and `staticpath` defines absolute paths to the emulators. For staticpath, the actual emulator binary must be included in the entry tag. Wildcards (*) are supported for the emulator binary, but not for directories. Wildcards are very useful for AppImages which often embed version information into the filenames. Note that if multiple files match a wildcard pattern, the first file returned by the operating system will be selected. - -```xml - - - ~/Applications/yuzu*.AppImage - - ~/Applications/yuzu*.App* - - ~/App*/yuzu*.AppImage - -``` - -There is also support for substituting the emulator binary in a staticpath rule with an explicit command. To accomplish this add a pipe (|) character after the emulator entry followed by the command to execute. This is for example useful for Flatpaks when you want to check the presence of a package while still launching a specific command inside the package using the --command option. For example: - -``` xml - - /var/lib/flatpak/exports/bin/com.github.AmatCoder.mednaffe|flatpak run --command=mednafen com.github.AmatCoder.mednaffe - ~/.local/share/flatpak/exports/bin/com.github.AmatCoder.mednaffe|flatpak run --command=mednafen com.github.AmatCoder.mednaffe - -``` - -This will execute the regular logic of checking if the Mednaffe Flatpak is installed but will actually run the command after the pipe character when launching the game. Note that no checks or controls are in place for the explicitly defined command, it's just blindly executed. - -The winregistrypath rules are always processed first, followed by winregistryvalue, then systempath and finally staticpath. This is done regardless of which order they are defined in the es_find_rules.xml file. - -As for `corepath` this rule is simply a path to search for the emulator core. - -Each rule supports multiple entry tags which are tried in the order that they are defined in the file. - -The %ESPATH% and %ROMPATH% variables can be used inside the staticpath rules and the %ESPATH% and %EMUPATH% variables can be used inside the corepath rules. - -The tilde symbol `~` is supported for the staticpath and corepath rules and will expand to the user home directory. Be aware that if ES-DE has been started with the --home command line option, the home directory is considered to be whatever path was passed as an argument to that option. The same is true if using a portable.txt file. - -All these options combined makes it possible to create quite powerful find rules. - -For reference, here are also example es_find_rules.xml files for macOS and Windows: - -```xml - - - - - - - zsh - bash - - - - - /Applications/RetroArch.app/Contents/MacOS/RetroArch - - - - - - ~/Library/Application Support/RetroArch/cores - - /Applications/RetroArch.app/Contents/Resources/cores - - - - - - /Applications/dosbox-staging.app/Contents/MacOS/dosbox - /opt/homebrew/bin/dosbox-staging - /usr/local/bin/dosbox-staging - - - - - - /Applications/mupen64plus.app/Contents/MacOS/mupen64plus - /usr/local/bin/mupen64plus - - - - - - /Applications/PCSX2.app/Contents/MacOS/PCSX2 - - - -``` - -```xml - - - - - - - cmd.exe - - - - - - retroarch.exe - - - - retroarch.exe - - - - C:\RetroArch-Win64\retroarch.exe - C:\RetroArch\retroarch.exe - ~\AppData\Roaming\RetroArch\retroarch.exe - C:\Program Files\RetroArch-Win64\retroarch.exe - C:\Program Files\RetroArch\retroarch.exe - C:\Program Files (x86)\RetroArch-Win64\retroarch.exe - C:\Program Files (x86)\RetroArch\retroarch.exe - - C:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe - D:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe - C:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe - D:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe - - %ESPATH%\Emulators\RetroArch-Win64\retroarch.exe - %ESPATH%\Emulators\RetroArch\retroarch.exe - %ESPATH%\..\Emulators\RetroArch-Win64\retroarch.exe - %ESPATH%\..\Emulators\RetroArch\retroarch.exe - - - - - %EMUPATH%\cores - - - - - - pcsx2-qt.exe - pcsx2-qtx64.exe - pcsx2-qtx64-avx2.exe - - - %ESPATH%\Emulators\PCSX2-Qt\pcsx2-qt*.exe - %ESPATH%\..\Emulators\PCSX2-Qt\pcsx2-qt*.exe - - - - - - yuzu.exe - - - ~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe - %ESPATH%\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe - %ESPATH%\..\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe - - - -``` - ## gamelist.xml The gamelist.xml file for a system defines the metadata for its entries, such as the game names, descriptions, release dates and ratings. -As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game media is configurable either manually in `es_settings.xml` or via the GUI. If configured manually in es_settings.xml, it looks something like this: +As of the fork to ES-DE, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game media is configurable either manually in `es_settings.xml` or via the GUI. If configured manually in es_settings.xml, it looks something like this: ```xml - + ``` There is also support to add the variable %ESPATH% to the media directory setting, this will expand to the path where the ES-DE executable is started from. You should normally not need this, but the option is there for special cases. For example: @@ -1781,17 +1847,17 @@ There is also support to add the variable %ESPATH% to the media directory settin ``` -The default media directory is `~/.emulationstation/downloaded_media` +The default media directory is `~/ES-DE/downloaded_media` You can use ES-DE's scrapers to populate the gamelist.xml files, or manually update individual entries using the metadata editor. All of this is explained in the [User guide](USERGUIDE-DEV.md). -The gamelist.xml files are searched for in the ES-DE home directory, i.e. `~/.emulationstation/gamelists//gamelist.xml` +The gamelist.xml files are searched for in the ES-DE home directory, i.e. `~/ES-DE/gamelists//gamelist.xml` For example: ``` -~/.emulationstation/gamelists/c64/gamelist.xml -~/.emulationstation/gamelists/megadrive/gamelist.xml +~/ES-DE/gamelists/c64/gamelist.xml +~/ES-DE/gamelists/megadrive/gamelist.xml ``` **gamelist.xml file structure** @@ -1922,7 +1988,7 @@ Before attempting to add a custom profile for your controller you need to check ES-DE uses the [SDL](https://www.libsdl.org) (Simple DirectMedia Layer) library to handle controller input, so in order for a controller to work in ES-DE, it has to be supported by SDL. There is however a possibility to add custom controller profiles to SDL which in some cases could enable devices in ES-DE that would otherwise not be supported. This is generally a temporary solution though, as controller support is constantly getting improved natively in SDL. As a first step it's therefore recommended to open a request at the SDL [issue tracker](https://github.com/libsdl-org/SDL/issues) to have your specific controller added to a future SDL release. -Assuming the controller works in other applications than ES-DE, you can attempt to add a custom profile by creating the file `~/.emulationstation/es_controller_mappings.cfg` and enter the appropriate configuration inside this file. +Assuming the controller works in other applications than ES-DE, you can attempt to add a custom profile by creating the file `~/ES-DE/controllers/es_controller_mappings.cfg` and enter the appropriate configuration inside this file. The required format is described here:\ https://github.com/gabomdq/SDL_GameControllerDB @@ -1932,7 +1998,7 @@ https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontro But just do this as a first step to see whether you controller gets enabled. If it does, then you should remove all entries that are not relevant. That is important as this file will take precedence over the built-in controller profiles in the SDL library, so any future controller bug fixes and similar would not apply. In the past the gamecontrollerdb.txt file has also included some invalid configuration entries, so even though it may make your controller work, it could actually break some other controllers that you may want to use now or in the future. -Therefore only keep the entries in the es_controller_mappings.cfg file that are relevant for your devices. You can find each relevant controller GUID by starting ES-DE and then looking in the ~/.emulationstation/es_log.txt file. You should see entries such as the following: +Therefore only keep the entries in the es_controller_mappings.cfg file that are relevant for your devices. You can find each relevant controller GUID by starting ES-DE and then looking in the `~/ES-DE/logs/es_log.txt` file. You should see entries such as the following: ``` May 16 18:26:17 Info: Added controller with custom configuration: "X360 Controller" (GUID: 030000005e0400008e02000010010000, instance ID: 0, device index: 0) ``` @@ -1954,26 +2020,26 @@ For this example, let's assume that the removable media has the device name `F:\ These are the steps to perform: * Install ES-DE -* Copy the EmulationStation-DE installation directory to F:\ -* Create a directory named F:\EmulationStation-DE\Emulators -* Copy your emulator directories to F:\EmulationStation-DE\Emulators\ -* Copy your ROMs directory to F:\EmulationStation-DE\ -* Create an empty file named portable.txt in F:\EmulationStation-DE\ +* Copy the ES-DE installation directory to F:\ +* Create a directory named F:\ES-DE\Emulators +* Copy your emulator directories to F:\ES-DE\Emulators\ +* Copy your ROMs directory to F:\ES-DE\ +* Create an empty file named portable.txt in F:\ES-DE\ You should end up with something like this: ``` -F:\EmulationStation-DE\ -F:\EmulationStation-DE\Emulators\dosbox-staging\ -F:\EmulationStation-DE\Emulators\RetroArch-Win64\ -F:\EmulationStation-DE\Emulators\RPCS3\ -F:\EmulationStation-DE\Emulators\xemu\ -F:\EmulationStation-DE\ROMs\ -F:\EmulationStation-DE\portable.txt +F:\ES-DE\ +F:\ES-DE\Emulators\dosbox-staging\ +F:\ES-DE\Emulators\RetroArch-Win64\ +F:\ES-DE\Emulators\RPCS3\ +F:\ES-DE\Emulators\xemu\ +F:\ES-DE\ROMs\ +F:\ES-DE\portable.txt ``` -This is just an example as you may of course not use these specific emulators. There are also many more emulators supported as detailed in the `es_find_rules.xml` configuration file. As well there will be many more files and directories than those listed above inside the F:\EmulationStation-DE folder. +This is just an example as you may of course not use these specific emulators. There are also many more emulators supported as detailed in the `es_find_rules.xml` configuration file. As well there will be many more files and directories than those listed above inside the F:\ES-DE folder. -How the portable setup works is that when ES-DE finds a file named portable.txt in its executable directory, it will by default locate the .emulationstation directory directly inside this folder. It's also possible to modify portable.txt with a path relative to the ES-DE executable directory. For instance if two dots `..` are placed inside the portable.txt file, then the .emulationstation directory will be located in the parent folder, which would be directly under F:\ for this example. +How the portable setup works is that when ES-DE finds a file named portable.txt in its executable directory, it will by default locate the ES-DE application data directory directly inside this folder. It's also possible to modify portable.txt with a path relative to the ES-DE executable directory. For instance if two dots `..` are placed inside the portable.txt file, then the ES-DE application data directory will be located in the parent folder, which would be directly under F:\ for this example. If the --home command line parameter is passed when starting ES-DE, that will override the portable.txt file. @@ -1982,12 +2048,12 @@ Start ES-DE from the F:\ device and check that everything works as expected. Jus Following this, optionally copy any existing gamelist.xml files, game media files etc. to the removable media. For example: ``` -F:\EmulationStation-DE\.emulationstation\collections\ -F:\EmulationStation-DE\.emulationstation\downloaded_media\ -F:\EmulationStation-DE\.emulationstation\gamelists\ +F:\ES-DE\ES-DE\collections\ +F:\ES-DE\ES-DE\downloaded_media\ +F:\ES-DE\ES-DE\gamelists\ ``` -You could alternatively copy over your entire .emulationstation directory, but in this case make sure that you have no settings in es_settings.xml that point to a specific location on your local filesystem, such as the game ROMs or game media directories. +You could alternatively copy over your entire ES-DE application data directory, but in this case make sure that you have no settings in es_settings.xml that point to a specific location on your local filesystem, such as the game ROMs or game media directories. You now have a fully functional portable retrogaming installation! @@ -2030,7 +2096,7 @@ The following examples are for Unix systems, but it works the same way on macOS As can be seen in the table above, the events executed when a game starts and ends are named _game-start_ and _game-end_ -So let's create the folders for these events in the scripts directory. The location is `~/.emulationstation/scripts` +So let's create the folders for these events in the scripts directory. The location is `~/ES-DE/scripts` **Game log** @@ -2041,7 +2107,7 @@ Let's name the start script `game_start_logging.sh` with the following contents: ``` #!/bin/bash TIMESTAMP=$(date +%Y-%m-%d' '%H:%M:%S) -echo Starting game "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt +echo Starting game "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/ES-DE/logs/game_playlog.txt ``` And let's name the end script `game_end_logging.sh` with the following contents: @@ -2049,14 +2115,14 @@ And let's name the end script `game_end_logging.sh` with the following contents: ``` #!/bin/bash TIMESTAMP=$(date +%Y-%m-%d' '%H:%M:%S) -echo "Ending game " "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt +echo "Ending game " "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/ES-DE/logs/game_playlog.txt ``` After creating the two scripts, you should have something like this on the filesystem: ``` -~/.emulationstation/scripts/game-start/game_start_logging.sh -~/.emulationstation/scripts/game-end/game_end_logging.sh +~/ES-DE/scripts/game-start/game_start_logging.sh +~/ES-DE/scripts/game-end/game_end_logging.sh ``` Don't forget to make the scripts executable (e.g. "chmod 755 ./game_start_logging.sh"). @@ -2065,15 +2131,14 @@ If we now start ES-DE with the debug flag and launch a game, something like the ``` Aug 05 14:19:24 Debug: Scripting::fireEvent(): game-start "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" -Aug 05 14:19:24 Debug: Executing: /home/myusername/.emulationstation/scripts/game-start/game_start_logging.sh "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" +Aug 05 14:19:24 Debug: Executing: /home/myusername/ES-DE/scripts/game-start/game_start_logging.sh "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" . . Aug 05 14:27:15 Debug: Scripting::fireEvent(): game-end "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" "" -Aug 05 14:27:15 Debug: Executing: /home/myusername/.emulationstation/scripts/game-end/game_end_logging.sh "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" - +Aug 05 14:27:15 Debug: Executing: /home/myusername/ES-DE/scripts/game-end/game_end_logging.sh "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" ``` -Finally after running some games, ~/.emulationstation/game_playlog.txt should contain something like the following: +Finally after running some games, ~/ES-DE/logs/game_playlog.txt should contain something like the following: ``` Starting game "The Legend Of Zelda" "Nintendo Entertainment System" ("/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip") at 2020-08-05 14:19:24 @@ -2101,7 +2166,7 @@ Then create the end script, which we'll name `set_resolution_4K.sh`: #!/bin/sh xrandr -s 3840x2160 sleep 0.3 -xdotool search --class emulationstation windowactivate +xdotool search --class es-de windowactivate ``` The last two lines are optional, they're used to set the focus back to ES-DE in case you're running attention-seeking applications such as Kodi which may steal focus after resolution changes. You may need to adjust the sleep time to get this to work reliably though, as the timing may differ between different computers and graphics drivers. @@ -2109,8 +2174,8 @@ The last two lines are optional, they're used to set the focus back to ES-DE in After creating the two scripts, you should have something like this on the filesystem: ``` -~/.emulationstation/scripts/game-start/set_resolution_1080p.sh -~/.emulationstation/scripts/game-end/set_resolution_4K.sh +~/ES-DE/scripts/game-start/set_resolution_1080p.sh +~/ES-DE/scripts/game-end/set_resolution_4K.sh ``` Don't forget to make the scripts executable (e.g. "chmod 755 ./set_resolution_1080p.sh"). diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 333767cb9..99272de9d 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -38,12 +38,12 @@ The installation procedure is just covered briefly here and may differ a bit for The AppImage release should be usable on most modern x86 64-bit Linux distributions. After download you may have to set the file as executable, such as this: ``` -chmod +x EmulationStation-DE-x64.AppImage +chmod +x ES-DE_x64.AppImage ``` Or if you're using the Steam Deck AppImage: ``` -chmod +x EmulationStation-DE-x64_SteamDeck.AppImage +chmod +x ES-DE_x64_SteamDeck.AppImage ``` To run AppImage files you need libfuse2 installed, but some newer distributions like Ubuntu 22.04 LTS no longer ship with this library preinstalled. You can however easily install it like this: @@ -59,11 +59,11 @@ There's not really much to say about these operating systems, just install ES-DE **On first application startup** -Upon first startup, ES-DE will create its `~/.emulationstation` home directory. +Upon first startup, ES-DE will create its `~/ES-DE` application data directory. -On Linux this means `/home//.emulationstation`, on macOS `/Users//.emulationstation` and on Windows `C:\Users\\.emulationstation` or `EmulationStation-DE\.emulationstation` depending on whether the installer release or the portable release is used. +On Linux this means `/home//ES-DE`, on macOS `/Users//ES-DE` and on Windows `C:\Users\\ES-DE` or `ES-DE\ES-DE` depending on whether the installer release or the portable release is used. -Also on first startup the configuration file `es_settings.xml` will be generated in the ES-DE home directory, containing all the application settings at their default values. Following this, a file named `es_systems.xml` will be loaded from the resources directory (which is part of the ES-DE installation). This file contains the game system definitions including which emulator to use per platform. For many systems there are also alternative emulators defined which can be applied system-wide or per game. How that works is explained later in this guide. A customized systems configuration file can also be used, as described in the next section below. +Also on first startup the configuration file `es_settings.xml` will be generated in the `ES-DE/settings` directory, containing all the application settings at their default values. Following this, a file named `es_systems.xml` will be loaded from the resources directory (which is part of the ES-DE installation). This file contains the game system definitions including which emulator to use per platform. For many systems there are also alternative emulators defined which can be applied system-wide or per game. How that works is explained later in this guide. A customized systems configuration file can also be used, as described in the next section below. In addition to es_systems.xml there's an `es_find_rules.xml` file that gets loaded as well and which contains rules on how to locate the emulators, i.e. how to find out where they've been installed. @@ -113,18 +113,18 @@ epic: Epic Games Store famicom: Nintendo Family Computer ``` -If a custom es_systems.xml file is present in ~/.emulationstation/custom_systems/ any entries from this file will have their names trailed by the text _(custom system)_. So if the _dos_ system in the example above would be present in the custom systems configuration file, the system would be shown as _dos (custom system)_ instead of simply _dos_. This is only applicable for the systems.txt and systeminfo.txt files, the trailing text is not applied or used anywhere else in the application. +If a custom es_systems.xml file is present in ~/ES-DE/custom_systems/ any entries from this file will have their names trailed by the text _(custom system)_. So if the _dos_ system in the example above would be present in the custom systems configuration file, the system would be shown as _dos (custom system)_ instead of simply _dos_. This is only applicable for the systems.txt and systeminfo.txt files, the trailing text is not applied or used anywhere else in the application. ![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._ ## Upgrading to a newer release -**Note:** Before upgrading ES-DE, make sure that you have not made any system customizations anywhere in the installation directory structure as these files will be overwritten during the upgrade process. All customizations should go into ~/.emulationstation/custom_systems/ as described elsewhere in this guide. None of the upgrade methods mentioned below will ever touch any files inside your .emulationstation directory tree. +**Note:** Before upgrading ES-DE, make sure that you have not made any system customizations anywhere in the installation directory structure as these files will be overwritten during the upgrade process. All customizations should go into ~/ES-DE/custom_systems/ as described elsewhere in this guide. None of the upgrade methods mentioned below will ever touch any files inside your ES-DE directory tree. -There is a built-in application updater that can automatically update the Linux AppImage releases, and as of ES-DE 2.2.0 there is also support for downloading the Windows and macOS packages. Just be aware that these will still need to be manually installed. Using the application updater is straightforward, just follow the on-screen instructions. For the AppImage releases the old file is retained by renaming it, adding its version to the filename followed by the .OLD extension, for example `EmulationStation-DE-x64_SteamDeck.AppImage_2.1.0.OLD` +There is a built-in application updater that can automatically update the Linux AppImage releases, and as of ES-DE 2.2.0 there is also support for downloading the Windows and macOS packages. Just be aware that these will still need to be manually installed. Using the application updater is straightforward, just follow the on-screen instructions. For the AppImage releases the old file is retained by renaming it, adding its version to the filename followed by the .OLD extension, for example `ES-DE_x64_SteamDeck.AppImage_3.0.0.OLD` -Note that the updater will keep whatever filename you had for your running AppImage file, which could potentially be confusing if you for example added version information to the filename. It's always recommend to keep the default AppImage filenames, i.e. `EmulationStation-DE-x64.AppImage` and `EmulationStation-DE-x64_SteamDeck.AppImage` +Note that the updater will keep whatever filename you had for your running AppImage file, which could potentially be confusing if you for example added version information to the filename. It's always recommend to keep the default AppImage filenames, i.e. `ES-DE_x64.AppImage` and `ES-DE_x64_SteamDeck.AppImage` On Windows and macOS you can specify to which directory you want to save the downloaded file. The default is `C:\Users\myusername\Downloads` on Windows and `/Users/myusername/Downloads` on macOS. @@ -145,7 +145,7 @@ AUR upgrades should be automatically handled via your package manager and it sho **macOS** -Open _Applications_ in Finder and right click on _EmulationStation Desktop Edition_ and choose _Move to Trash_. Then simply install the new release using the .dmg drag-and-drop installer. +Open _Applications_ in Finder and right click on _ES-DE_ and choose _Move to Trash_. Then simply install the new release using the .dmg drag-and-drop installer. **Windows installer** @@ -191,7 +191,7 @@ Note that if the setting _Only show games from gamelist.xml files_ has been enab ## Placing games and other resources on network shares -Although ES-DE does support placing game ROMs, the `.emulationstation` home directory and the `downloaded_media` directory on network shares, this can lead to serious performance problems in some instances. Especially problematic is the Microsoft SMB protocol as it offers abysmal performance for some disk operations on which ES-DE relies heavily. For small game libraries this can still be acceptable, but for libraries with hundreds or thousands of games the application startup time and overall usage will be very painful or even unusable. Similar issues could occur when using file hosting services like Google Drive. +Although ES-DE does support placing game ROMs, the `ES-DE` application data directory and the `downloaded_media` directory on network shares, this can lead to serious performance problems in some instances. Especially problematic is the Microsoft SMB protocol as it offers abysmal performance for some disk operations on which ES-DE relies heavily. For small game libraries this can still be acceptable, but for libraries with hundreds or thousands of games the application startup time and overall usage will be very painful or even unusable. Similar issues could occur when using file hosting services like Google Drive. A general recommendation is to place all game files and other data on drives connected directly to the machine where ES-DE is running. Even using low speed technology like USB thumb drives, SD cards etc. is generally fine and leads to acceptable performance in most instances. @@ -233,7 +233,7 @@ In order for ES-DE to run, graphics drivers with OpenGL support have to be insta On some GPUs with buggy drivers, ES-DE may only display a black screen on startup or when launching a game. The problem can be worked around by specifying a window size for ES-DE that is a single pixel wider than the actual screen resolution. So for example for a 1280x800 display, the resolution can be set to 1281x800 and then rendering should work correctly. This is applied using the --resolution command line option, for example: ``` -EmulationStation.exe --resolution 1281 800 +ES-DE.exe --resolution 1281 800 ``` Some computers using Intel Iris Xe GPUs refuse to start ES-DE or display excessive graphics corruption. These problems are seemingly caused by driver bugs and do not occur when using Linux with the same hardware. There is no known solution or workaround to this issue other than switching to Linux or waiting for Intel to resolve the problem with a driver update. @@ -254,7 +254,7 @@ If you want to create your own portable intallation from scratch or customize th A number of systems have alternative emulator entries named _Shortcut or script_ which allows the direct execution of .lnk shortcut files or .bat batch files. It's not possible by default to directly launch .ps1 PowerShell scripts. As running PowerShell scripts is not even enabled by default on Windows they are for sure not recommended. If you still want to use them the best approach is to execute them via either a .lnk shortcut file or a .bat wrapper script where you explicitly call powershell.exe with the -command flag. If you instead insist on running them directly from ES-DE, you'll need to add a custom system or find rule configuration where you execute powershell.exe instead of cmd.exe and you'll also need to add .ps1 as a file extension for each relevant system. -Some disk operations can have abysmal performance on Windows, and this may be especially obvious for the theme downloader. This is often caused by anti-virus software like Microsoft Defender. If it takes say 30 seconds rather than 300 milliseconds to open the theme downloader then it may be a good idea to add an exlusion for the .emulationstation\themes\ directory to Microsoft Defender. The same may also be true for other directories like the ROMs folder if disk performance is terrible. Refer to your anti-virus software documentation on how to setup such exclusions. +Some disk operations can have abysmal performance on Windows, and this may be especially obvious for the theme downloader. This is often caused by anti-virus software like Microsoft Defender. If it takes say 30 seconds rather than 300 milliseconds to open the theme downloader then it may be a good idea to add an exlusion for the ES-DE\themes\ directory to Microsoft Defender. The same may also be true for other directories like the ROMs folder if disk performance is terrible. Refer to your anti-virus software documentation on how to setup such exclusions. ## Specific notes for macOS @@ -270,13 +270,11 @@ At the time of writing there is an additional issue with the ARM release of Retr The first time you launch a RetroArch-emulated game from within ES-DE the operating system will present you with a security option with the following description: -`"EmulationStation Desktop Edition" would like to access files in your Documents folder.` +`"ES-DE" would like to access files in your Documents folder.` If you don't allow this, you will not be able to place system BIOS ROMs in the RetroArch default system directory `~/Documents/RetroArch/system` even if you've already given RetroArch access to this folder. This is so because RetroArch runs as a subprocess to ES-DE and therefore inherits the security settings from the parent application. Attempting to launch a game without enabling the access will simply display an error message in the emulator that the BIOS files are missing. This of course only applies to emulators that require BIOS ROMs, all other games should work fine regardless of this security setting. -If you accidentally refused ES-DE the folder access, you can fix this by opening _System Settings_, selecting _Privacy & Security_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _EmulationStation Desktop Edition_. - -By default files and directories starting with a dot are hidden on macOS, so to show the .emulationstation directory in your home directory you need to enable hidden files in Finder. You do this using the keyboard combination Shift + Command + . (dot). +If you accidentally refused ES-DE the folder access, you can fix this by opening _System Settings_, selecting _Privacy & Security_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _ES-DE_. A minor annoyance is that macOS creates metadata files starting with ._ in the filename when placing game/ROM files on some filesystem types such as exFAT. This means that you will see double entries inside ES-DE for all such games. To hide these extra files, the option _Show hidden files and folders (requires restart)_ in the _Other settings_ menu can be set to disabled. @@ -314,7 +312,7 @@ In general, 720p works fine with the RPi 4, and 1080p is tolerable but not reall The game systems configuration file `es_systems.xml` is located in the ES-DE resources directory which is part of the application installation. As such this file is not intended to be modified directly. If system customizations are required, a separate es_systems.xml file should instead be placed in the `custom_systems` folder in the ES-DE home directory. -On Linux this means `/home//.emulationstation/custom_systems/es_systems.xml`, on macOS `/Users//.emulationstation/custom_systems/es_systems.xml` and on Windows `C:\Users\\.emulationstation\custom_systems\es_systems.xml` or `EmulationStation-DE\.emulationstation\custom_systems\es_systems.xml` depending on whether the installer release or the portable release is used. +On Linux this means `/home//ES-DE/custom_systems/es_systems.xml`, on macOS `/Users//ES-DE/custom_systems/es_systems.xml` and on Windows `C:\Users\\ES-DE\custom_systems\es_systems.xml` or `ES-DE\ES-DE\custom_systems\es_systems.xml` depending on whether the installer release or the portable release is used. If you're using the AppImage release of ES-DE then the bundled es_systems.xml file is embedded in the AppImage together with the rest of the resources. You can extract it if you need it as a reference when creating your customized entries, or you can find it [here](https://gitlab.com/es-de/emulationstation-de/-/tree/master/resources/systems/linux). @@ -335,11 +333,11 @@ ES-DE is designed to be backward compatible to a certain degree. That is, it sho Due to this, always make backups of at least the following directories before testing ES-DE for the first time: ``` -~/.emulationstation/gameslists/ -~/.emulationstation/collections/ +~/ES-DE/gameslists/ +~/ES-DE/collections/ ``` -If you have gamelist.xml files in your ROMs directory tree then ES-DE will ignore those by default, so you need to move them to the ~/.emulationstation/gamelists/ tree. +If you have gamelist.xml files in your ROMs directory tree then ES-DE will ignore those by default, so you need to move them to the ~/ES-DE/gamelists/ tree. It's also strongly adviced to not rename an old es_settings.cfg file to es_settings.xml for use in ES-DE as it may cause undefined behavior and crashes. @@ -361,7 +359,7 @@ Example of a correct path tag readable by ES-DE: Manually removing game files from the ROMs directory tree instead of deleting them from ES-DE using the metadata editor will make any corresponding scraped media files, gamelist.xml entries and custom collection entries orphaned, i.e. they will refer to non-existent files. Although this is correctly handled by ES-DE and is not causing any serious issues, it does lead to unnecessary disk space usage and it does produce log warnings in es_log.txt on application startup. If a huge amount of game files have been manually removed it can also lead to performance problems. -In order to remove such unnecessary media files and configuration file entries, the _Orphaned data cleanup_ utility in the _Utilities_ menu can be used. This tool should be largely self-explanatory. And although it should generally be safe to use, unforeseen issues can occur so make sure to make backups of at least your `.emulationstation/gamelists` and `.emulationstation/collections` directories before attempting to use this tool. +In order to remove such unnecessary media files and configuration file entries, the _Orphaned data cleanup_ utility in the _Utilities_ menu can be used. This tool should be largely self-explanatory. And although it should generally be safe to use, unforeseen issues can occur so make sure to make backups of at least your `ES-DE/gamelists` and `ES-DE/collections` directories before attempting to use this tool. It's recommended to run this utility with the _Show hidden games_ setting enabled as orphaned gamelist.xml folder entries may otherwise not get purged. @@ -371,17 +369,17 @@ Note that there are no guarantees that any processed gamelist.xml files will be If the utility finds any data to be removed, a backup of the old files will be made. This will end up in a `CLEANUP` directory and will contain a date and time stamp. For example: ``` -~/.emulationstation/gamelists/CLEANUP/2023-07-27_142830/dos/gamelist.xml -~/.emulationstation/gamelists/CLEANUP/2023-07-27_142830/ports/gamelist.xml -~/.emulationstation/collections/CLEANUP/2023-07-27_143216/custom-Action.cfg -~/.emulationstation/collections/CLEANUP/2023-07-27_143216/custom-Fighting.cfg -~/.emulationstation/downloaded_media/CLEANUP/2023-07-27_123406/atari2600/titlescreens/H.E.R.O..png -~/.emulationstation/downloaded_media/CLEANUP/2023-07-27_123406/c64/3dboxes/Minerer 2049.crt.png +~/ES-DE/gamelists/CLEANUP/2023-07-27_142830/dos/gamelist.xml +~/ES-DE/gamelists/CLEANUP/2023-07-27_142830/ports/gamelist.xml +~/ES-DE/collections/CLEANUP/2023-07-27_143216/custom-Action.cfg +~/ES-DE/collections/CLEANUP/2023-07-27_143216/custom-Fighting.cfg +~/ES-DE/downloaded_media/CLEANUP/2023-07-27_123406/atari2600/titlescreens/H.E.R.O..png +~/ES-DE/downloaded_media/CLEANUP/2023-07-27_123406/c64/3dboxes/Minerer 2049.crt.png ``` This means that you will need to manually delete these backup directories to free up disk space when you are certain that you no longer need the data. -All files and entries that are removed are logged to `~/.emulationstation/es_log.txt` so it could be a good idea to make a backup copy of this file after running the cleanup, for future reference. +All files and entries that are removed are logged to `~/ES-DE/logs/es_log.txt` so it could be a good idea to make a backup copy of this file after running the cleanup, for future reference. Any media directories that are empty after the cleanup will also be removed by this utility. @@ -408,22 +406,22 @@ Below are some examples. For consistency it's assumed that the display resolutio Running at a lower application resolution in a window: ``` -emulationstation --resolution 1280 720 +es-de --resolution 1280 720 ``` Running at a lower application resolution in padded fullscreen mode: ``` -emulationstation --resolution 1824 1026 --fullscreen-padding 1 +es-de --resolution 1824 1026 --fullscreen-padding 1 ``` Same as above but also offsetting the screen slightly to the left and downwards: ``` -emulationstation --resolution 1824 1026 --fullscreen-padding 1 --screenoffset -40 22 +es-de --resolution 1824 1026 --fullscreen-padding 1 --screenoffset -40 22 ``` Rotate application screen contents 90 degrees while running at the native 1920x1080 screen resolution: ``` -emulationstation --screenrotate 90 +es-de --screenrotate 90 ``` ## Input device configuration @@ -436,7 +434,7 @@ The actual procedure to map the inputs should be self-explanatory, just follow t Any custom configuration is applied per unique device ID (GUID). So if two identical controllers are used with ES-DE, both will have the same configuration applied. If connecting controllers of the same type but of different revisions, the GUID may differ and therefore the custom configuration would need to be applied to each device individually. -If you have issues with your input configuration, as a last resort you can reset all mappings by deleting or renaming the file `~/.emulationstation/es_input.xml` +If you have issues with your input configuration, as a last resort you can reset all mappings by deleting or renaming the file `~/ES-DE/settings/es_input.xml` ## System view (main screen) @@ -561,13 +559,13 @@ As of ES-DE 2.2.0 no legacy EmulationStation themes are supported, such as those There are several user-selectable theme options in the _UI Settings_ menu, most notably _Theme variant_ which is essentially a form of theme profile. This could be anything, like different ways to navigate the themes, different layouts and designs etc. Additionally the _Theme color scheme_ setting makes it possible to select between different color schemes, if supported by the theme. The two remaining options _Theme aspect ratio_ and _Theme transitions_ are also important but you can normally leave them at their default _Automatic_ values, especially the _Theme aspect ratio_ option as it will be automatically detected. Be aware that all these theme settings are optional, it's up to the theme developer whether to add support for them to their themes. -Themes are most easily installed using the built-in theme downloader, but you can also manually add them to your ES-DE home directory, i.e. `~/.emulationstation/themes/`. By just adding them there, one folder each, they will be found during startup and you can then choose between them via the _UI Settings_ menu on the main menu. If using the portable release of ES-DE on Windows, the .emulationstation folder can be found in the root of the EmulationStation-DE directory. +Themes are most easily installed using the built-in theme downloader, but you can also manually add them to your ES-DE home directory, i.e. `~/ES-DE/themes/`. By just adding them there, one folder each, they will be found during startup and you can then choose between them via the _UI Settings_ menu on the main menu. If using the portable release of ES-DE on Windows, the ES-DE application data can be found in the root of the ES-DE directory. -Although you should place additional themes in your ES-DE home directory, the default Slate and Modern themes are located in the installation folder as they come bundled with the application. For example this could be `/usr/share/emulationstation/themes/` on Linux, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/` on macOS or `C:\Program Files\EmulationStation-DE\themes\` on Windows. If using the portable ES-DE release on Windows, the themes folder will be located in the root of the EmulationStation-DE directory. +Although you should place additional themes in your ES-DE home directory, the default Slate and Modern themes are located in the installation folder as they come bundled with the application. For example this could be `/usr/share/es-de/themes/` on Linux, `/Applications/ES-DE.app/Contents/Resources/themes/` on macOS or `C:\Program Files\ES-DE\themes\` on Windows. If using the portable ES-DE release on Windows, the themes folder will be located in the root of the ES-DE directory. Note that if using the AppImage release on Linux, then there is no installation folder as all files are contained inside the AppImage file. -If you would like to customize the Slate or Modern themes, simply make a copy of their directories to `~/.emulationstation/themes/` and then those copies will take precedence over the ones in the application installation directory. +If you would like to customize the Slate or Modern themes, simply make a copy of their directories to `~/ES-DE/themes/` and then those copies will take precedence over the ones in the application installation directory. Refer to the official themes list for a selection of high-quality themes (these are also available via the built-in theme downloader):\ https://gitlab.com/es-de/themes/themes-list @@ -589,7 +587,7 @@ If you have manually downloaded any of the themes from the [official themes list If you have customized a theme by for instance modifying any of its XML files, then this will be highlighted with an exclamation mark and the text _LOCAL CHANGES_ in the theme downloader interface. If you attempt to fetch updates for such a theme you will be asked a question of whether to overwrite your local changes, or whether to cancel. If you have however added additional files to the theme that are not included in the theme repository, then these will not interfere and you can go ahead and fetch theme updates without any risk of having your local files being deleted. But there is a special (although unlikely) situation, if you add files that are not part of the theme repository but that are later added by the theme developer as well, then your local copies of any such files will be ovewritten when fetching theme updates. -In worst case there could be a situation where a repository is corrupted and the theme downloader can't properly identify or handle the corruption. In this case you will have to rename or delete that directory. This could also apply to the actual themes list repository. The latter is named _themes-list_ so by just deleting this directory (i.e. `~/.emulationstation/themes/themes-list`) you'll reset the theme downloader to its initial state. +In worst case there could be a situation where a repository is corrupted and the theme downloader can't properly identify or handle the corruption. In this case you will have to rename or delete that directory. This could also apply to the actual themes list repository. The latter is named _themes-list_ so by just deleting this directory (i.e. `~/ES-DE/themes/themes-list`) you'll reset the theme downloader to its initial state. Note that the exFAT filesystem can't be used as it makes the theme downloader fail. But using this filesystem is strongly discouraged anyway as it offers very poor disk I/O performance which makes ES-DE run really slowly. @@ -736,7 +734,7 @@ There is however a workaround available to launch the Flatpak first, should you For example if using the ES-DE AppImage release, this would be the command to execute: ``` -PATH=/var/lib/flatpak/exports/bin:~/.local/share/flatpak/exports/bin:$PATH ./EmulationStation-DE-x64.AppImage +PATH=/var/lib/flatpak/exports/bin:~/.local/share/flatpak/exports/bin:$PATH ./ES-DE_x64.AppImage ``` Obviously you would need to change the path to the AppImage if it's not in your current working directory. @@ -955,7 +953,7 @@ It's highly recommended to use filenames that correspond to the full name of the Symlinks are supported for both ROM directories and individual game files, but make sure to never symlink between files within the same system directory or there may be undefined application behavior when scraping, launching games etc. -The default game folder is ~/ROMs. On Linux this defaults to `/home//ROMs`, on macOS `/Users//ROMs` and on Windows `C:\Users\\ROMs` or `EmulationStation-DE\ROMs` depending on whether the installer release or the portable release is used. If the --home command line option was used to start ES-DE, the tilde symbol will resolve to whatever directory was passed as an argument to this option. +The default game folder is ~/ROMs. On Linux this defaults to `/home//ROMs`, on macOS `/Users//ROMs` and on Windows `C:\Users\\ROMs` or `ES-DE\ROMs` depending on whether the installer release or the portable release is used. If the --home command line option was used to start ES-DE, the tilde symbol will resolve to whatever directory was passed as an argument to this option. Assuming the default ROM directory is used, we need to create a subdirectory corresponding to the \ tag in es_systems.xml, for this example it's `nes`. @@ -965,7 +963,7 @@ So it would look something like the following: /home/myusername/ROMs/nes # Linux /Users/myusername/ROMs/nes # macOS C:\Users\myusername\ROMs\nes # Windows installer -EmulationStation-DE\ROMs\nes # Windows portable +ES-DE\ROMs\nes # Windows portable ``` Now simply copy your game ROMs into this folder, and you should end up with something like this Linux example: @@ -2771,7 +2769,7 @@ Apart from this, hopefully the scraping process should be self-explanatory. If you already have a library of game media (images, videos and PDF manuals) you can manually copy these files into ES-DE. The same procedure applies if you want to add media for individual games, for instance when the scraper did not return any results or if you didn't like the media it provided. -The default media directory is `~/.emulationstation/downloaded_media//` +The default media directory is `~/ES-DE/downloaded_media//` This directory can however be changed using the _Game media directory_ setting in the _Other settings_ menu so make sure to check this setting before attempting to follow the instructions below. If the setting is blank, then the default directory is in use. @@ -2779,25 +2777,25 @@ See the [Supported game systems](USERGUIDE-DEV.md#supported-game-systems) table An example on Linux: ``` -/home/myusername/.emulationstation/downloaded_media/c64/screenshots/ +/home/myusername/ES-DE/downloaded_media/c64/screenshots/ ``` An example on macOS: ``` -/Users/myusername/.emulationstation/downloaded_media/c64/screenshots/ +/Users/myusername/ES-DE/downloaded_media/c64/screenshots/ ``` An example on Windows (installer release): ``` -C:\Users\Myusername\.emulationstation\downloaded_media\c64\screenshots\ +C:\Users\Myusername\ES-DE\downloaded_media\c64\screenshots\ ``` An example on Windows (portable release): ``` -EmulationStation-DE\.emulationstation\downloaded_media\c64\screenshots\ +ES-DE\ES-DE\downloaded_media\c64\screenshots\ ``` The media directories per game system are: @@ -2828,8 +2826,8 @@ The media files must correspond exactly to the game files. Take for example this For this example, the filename structure needs to look like the following: ``` -~/.emulationstation/downloaded_media/c64/screenshots/Multidisk/Last Ninja 2/Last Ninja 2.jpg -~/.emulationstation/downloaded_media/c64/videos/Multidisk/Last Ninja 2/Last Ninja 2.mp4 +~/ES-DE/downloaded_media/c64/screenshots/Multidisk/Last Ninja 2/Last Ninja 2.jpg +~/ES-DE/downloaded_media/c64/videos/Multidisk/Last Ninja 2/Last Ninja 2.mp4 ``` Note that there is seemingly an exception to this logic if the _Directories interpreted as files_ functionality has been used, in which case the "file extension" added to the directory is also included in the game media filenames. Take for example the following ScummVM game: @@ -2840,8 +2838,8 @@ Note that there is seemingly an exception to this logic if the _Directories inte The media files for this directory which is interpreted as a file will be: ``` -~/.emulationstation/downloaded_media/scummvm/screenshots/dig.scummvm.png -~/.emulationstation/downloaded_media/scummvm/videos/dig.scummvm.mp4 +~/ES-DE/downloaded_media/scummvm/screenshots/dig.scummvm.png +~/ES-DE/downloaded_media/scummvm/videos/dig.scummvm.mp4 ``` This is not a bug as these are not really file extensions after all, it's just a directory with a dot in the filename that happens to look like a file extension because that's how the _Directories interpreted as files_ logic works. @@ -3141,7 +3139,7 @@ If set to _None_, the system view will be displayed on startup. Any other value **Systems sorting** -The order in which to sort the game systems. The default option is _Full names or custom_ which will sort by full system names, unless there is a ~/.emulationstation/custom_systems/es_systems_sorting.xml file present which will then be used instead. The other options are using the bundled sorting configuration files for _Release year_ or _Manufacturer, release year_ or _HW type, release year_ or _Manufacturer, HW type, release year_. If using any of these bundled sorting files, then any ~/.emulationstation/custom_systems/es_systems_sorting.xml will be ignored. When changing this setting ES-DE will automatically reload. +The order in which to sort the game systems. The default option is _Full names or custom_ which will sort by full system names, unless there is a ~/ES-DE/custom_systems/es_systems_sorting.xml file present which will then be used instead. The other options are using the bundled sorting configuration files for _Release year_ or _Manufacturer, release year_ or _HW type, release year_ or _Manufacturer, HW type, release year_. If using any of these bundled sorting files, then any ~/ES-DE/custom_systems/es_systems_sorting.xml will be ignored. When changing this setting ES-DE will automatically reload. **Game default sort order** @@ -3373,7 +3371,7 @@ If enabling this option, only the first controller detected during startup will **Ignore keyboard input** -If this setting is enabled then all keyboard input will be ignored, except the quit shortcut used to shut down the application. The main reason for ignoring keyboard input is if running Steam in parallel to ES-DE and you need to use the Steam Input's _Desktop Layout_ functionality to send keyboard input using the controller. In this case double or conflicting input will be sent to ES-DE as both the controller and keyboard events are read by the application. It's however generally a better idea to disable this functionality altogether in Steam and leave the ES-DE setting untouched. If you accidentally enable this setting when using a keyboard as input device, then you'll either need to plug in a controller to disable it again, or you'll need to modify the _InputIgnoreKeyboard_ entry in the ~/.emulationstation/es_settings.xml configuration file. +If this setting is enabled then all keyboard input will be ignored, except the quit shortcut used to shut down the application. The main reason for ignoring keyboard input is if running Steam in parallel to ES-DE and you need to use the Steam Input's _Desktop Layout_ functionality to send keyboard input using the controller. In this case double or conflicting input will be sent to ES-DE as both the controller and keyboard events are read by the application. It's however generally a better idea to disable this functionality altogether in Steam and leave the ES-DE setting untouched. If you accidentally enable this setting when using a keyboard as input device, then you'll either need to plug in a controller to disable it again, or you'll need to modify the _InputIgnoreKeyboard_ entry in the ~/ES-DE/settings/es_settings.xml configuration file. **Configure keyboard and controllers** @@ -3432,7 +3430,7 @@ _The system-wide alternative emulators interface. An entry in bold and with a ge **Game media directory** -This setting defines the directory for game media, i.e. images, videos and PDF manuals that have normally been downloaded by the scraper. The default location is _~/.emulationstation/downloaded_media_ +This setting defines the directory for game media, i.e. images, videos and PDF manuals that have normally been downloaded by the scraper. The default location is _~/ES-DE/downloaded_media_ **VRAM limit** @@ -3538,15 +3536,15 @@ This utility will create all game system directories inside your ROM directory t This utility will rescan the ROM directory for any changes such as added or removed games and systems without having to restart the application. But don't use this utility to reload changes to gamelist.xml files that you have made outside ES-DE as this can lead to data corruption. If you need to manually edit your gamelist.xml files then do this while ES-DE is shut down. -### Quit / Quit EmulationStation +### Quit / Quit ES-DE -The _Quit_ menu or _Quit EmulationStation_ entry as described by the _Show quit menu (reboot and power off entries)_ option above. +The _Quit_ menu or _Quit ES-DE_ entry as described by the _Show quit menu (reboot and power off entries)_ option above. If the menu is enabled, these are its entries: -**Quit EmulationStation** +**Quit ES-DE** -If the option _When to save game metadata_ has been set to _On exit_, the gamelist.xml files will be updated at this point. This applies also if the Quit menu is disabled and replaced by the _Quit EmulationStation_ entry. +If the option _When to save game metadata_ has been set to _On exit_, the gamelist.xml files will be updated at this point. This applies also if the Quit menu is disabled and replaced by the _Quit ES-DE_ entry. **Reboot system** _(All operating systems except macOS)_ @@ -3854,9 +3852,9 @@ _Example of custom collections, here configured as genres._ _When editing a custom collection and the theme uses a textlist, then a tick symbol will be displayed for any game that is part of the collection._ -The way that custom collections are implemented is very simple. There is a single configuration file per collection inside the folder `~/.emulationstation/collections` +The way that custom collections are implemented is very simple. There is a single configuration file per collection inside the folder `~/ES-DE/collections` -For this example a file will have been created named `~/.emulationstation/collections/custom-Platform.cfg` +For this example a file will have been created named `~/ES-DE/collections/custom-Platform.cfg` The file contents is simply a list of ROM files, such as the following: @@ -3872,7 +3870,7 @@ The file contents is simply a list of ROM files, such as the following: Any changes to custom collections, for example adding or removing a game, will be immediately written to the corresponding collection configuration file. -If you copy or migrate a collection from a previous version of EmulationStation or if you're setting up ES-DE on a new computer, the collection will not be enabled by just copying its configuration file to the `~/.emulationstation/collections` directory. You always need to explicitly enable each collection via the menu. +If you copy or migrate a collection from a previous version of EmulationStation or if you're setting up ES-DE on a new computer, the collection will not be enabled by just copying its configuration file to the `~/ES-DE/collections` directory. You always need to explicitly enable each collection via the menu. If you're migrating from a previous version of EmulationStation that has absolute paths in the collection files, then these will be rewritten with the %ROMPATH% variable the first time you make a change to the collection.