From b09e85d75f14b6231b79b5f719b0182beec834a8 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Tue, 28 Dec 2021 17:01:33 +0100 Subject: [PATCH] Updated the download links and documentation for the 1.2.0 release. --- CHANGELOG.md | 5 +- INSTALL-DEV.md | 22 +- INSTALL.md | 991 ++++++++++++++++++++++++------------------- README.md | 42 +- USERGUIDE-DEV.md | 12 +- USERGUIDE.md | 1043 +++++++++++++++++++++++++++++----------------- 6 files changed, 1284 insertions(+), 831 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c348a6322..047307b1c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,9 @@ [[_TOC_]] -## Version 1.2.0 (in development) +## Version 1.2.0 -**Release date:** TBD +**Release date:** 2021-12-28 ### Release overview @@ -183,6 +183,7 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac * When running really low on texture memory, the menu texture would not get rendered correctly * At low screen resolutions, logos on the System view carousel would sometimes jump down a pixel when scaling down * There was a tiny and randomly occuring gap between the system carousel and systemInfo bar during slide transitions between the System and Gamelist views +* The "no games" dialog did not have correct line wrapping when running at 1280x1024 * SliderComponent had very inconsistent widths at different screen aspect ratios * SliderComponent did not properly align the knob and bar vertically * Buttons were not sized and padded consistently across different screen resolutions diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index d138fa085..9518ba081 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -163,7 +163,7 @@ By default the master branch will be used, which is where development takes plac ``` cd emulationstation-de -git checkout stable-1.1 +git checkout stable-1.2 cmake . make ``` @@ -550,7 +550,7 @@ By default the master branch will be used, which is where development takes plac ``` cd emulationstation-de -git checkout stable-1.1 +git checkout stable-1.2 cmake . make ``` @@ -893,7 +893,7 @@ By default the master branch will be used, which is where development takes plac ``` cd emulationstation-de -git checkout stable-1.1 +git checkout stable-1.2 ``` **Setup the include directories** @@ -1816,6 +1816,22 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo %EMUPATH%\cores + + + + SOFTWARE\PCSX2\Install_Dir|\pcsx2.exe + + + pcsx2.exe + + + C:\Program Files (x86)\PCSX2\pcsx2.exe + D:\Program Files (x86)\PCSX2\pcsx2.exe + + %ESPATH%\PCSX2\pcsx2.exe + %ESPATH%\..\PCSX2\pcsx2.exe + + diff --git a/INSTALL.md b/INSTALL.md index 918b62cad..f639e0a9f 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,4 +1,4 @@ -# EmulationStation Desktop Edition (ES-DE) v1.1 - Building and advanced configuration +# EmulationStation Desktop Edition (ES-DE) v1.2 - Building and advanced configuration **Note:** This is a quite technical document intended for those that are interested in compiling ES-DE from source code, or would like to customize the configuration. If you just want to start using the software, check out [USERGUIDE.md](USERGUIDE.md) instead. @@ -25,7 +25,7 @@ There are some dependencies that need to be fulfilled in order to build ES-DE. T All of the required packages can be installed with apt-get: ``` -sudo apt-get install build-essential clang-format git cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev rapidjson-dev libasound2-dev libgl1-mesa-dev +sudo apt-get install build-essential clang-format git cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev libasound2-dev libgl1-mesa-dev ``` If building with the optional VLC video player, the following packages are also needed: @@ -35,17 +35,22 @@ sudo apt-get install vlc libvlc-dev **Fedora** -Use dnf to install all the required packages: -``` -sudo dnf install gcc-c++ clang-tools-extra cmake SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel rapidjson-devel alsa-lib-devel mesa-libGL-devel -``` - -If building with the VLC video player, add the RPM Fusion repository. - -Go to [https://rpmfusion.org/Configuration](https://rpmfusion.org/Configuration) and download the .rpm package for the free repository. Then install it, followed by VLC: +On Fedora you first need to install the RPM Fusion repository: + +``` +sudo dnf install \ +https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \ +https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm +``` + +Then you can use dnf to install all the required packages: +``` +sudo dnf install gcc-c++ clang-tools-extra cmake rpm-build SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel +``` +If building with the optional VLC video player, the following packages are also needed: + ``` -sudo dnf install ./rpmfusion-free-release-33.noarch.rpm sudo dnf install vlc vlc-devel ``` @@ -54,7 +59,7 @@ sudo dnf install vlc vlc-devel Use pacman to install all the required packages: ``` -sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml rapidjson +sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml ``` If building with the optional VLC video player, the following package is also needed: @@ -64,11 +69,9 @@ sudo pacman -S vlc **Raspberry Pi OS (Raspian)** -Note: The Raspberry Pi 4 is the minimum recommended model to use with ES-DE. As this type of device is quite weak and because the FFmpeg video player does not support hardware decoding on this platform, it's strongly adviced to build with the VLC player, which is hardware accelerated. - All of the required packages can be installed with apt-get: ``` -sudo apt-get install clang-format cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libcurl4-gnutls-dev libpugixml-dev rapidjson-dev +sudo apt-get install clang-format cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libcurl4-gnutls-dev libpugixml-dev ``` If building with the optional VLC video player, the following packages are also needed: @@ -81,11 +84,15 @@ To build with CEC support you also need to install these packages: sudo apt-get install libcec-dev libp8-platform-dev ``` +The Raspberry Pi 4/400 is the minimum recommended version and earlier boards have not been tested. The GPU memory should be set to at least 256 MB using `raspi-config` and the GL driver must be set to `GL (Fake KMS)` or the performance will be horrible. + +Note that low-level ALSA sound support has been removed from ES-DE which means that a sound server like PulseAudio or PipeWire is required. + **FreeBSD** Use pkg to install the dependencies: ``` -pkg install git pkgconf cmake sdl2 ffmpeg freeimage pugixml rapidjson +pkg install llvm-devel git pkgconf cmake sdl2 ffmpeg freeimage pugixml ``` If building with the optional VLC video player, the following package is also needed: @@ -99,7 +106,7 @@ Clang/LLVM and cURL should already be included in the base OS installation. Use pkgin to install the dependencies: ``` -pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage pugixml rapidjson +pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage pugixml ``` If building with the optional VLC video player, the following package is also needed: @@ -123,16 +130,6 @@ pkg_add vlc In the same manner as for FreeBSD, Clang/LLVM and cURL should already be installed by default. -RapidJSON is not part of the OpenBSD ports/package collection as of v6.8, so you need to compile it yourself. At the time of writing, the latest release v1.1.0 does not compile on OpenBSD, so you need to use the master branch: - -``` -git clone https://github.com/Tencent/rapidjson.git -cd rapidjson -cmake . -make -make install -``` - Pugixml does exist in the package collection but somehow this version is not properly detected by CMake, so you need to compile this manually as well: ``` @@ -164,7 +161,7 @@ By default the master branch will be used, which is where development takes plac ``` cd emulationstation-de -git checkout stable-1.1 +git checkout stable-1.2 cmake . make ``` @@ -188,7 +185,32 @@ cmake -DCMAKE_BUILD_TYPE=Profiling . make ``` -As for more advanced debugging, Valgrind is a very powerful and useful tool which can analyze many aspects of the application. Be aware that some of the Valgrind tools should be run with an optimized build, and some with optimizations turned off. Refer to the Valgrind documentation for more information. +To enable AddressSanitizer which helps with identifying memory issues like corruption bugs and buffer overflows, build with the ASAN option: +``` +cmake -DCMAKE_BUILD_TYPE=Debug -DASAN=on . +make +``` + +To enable ThreadSanitizer which helps with identifying data races for multi-threaded code, build with the TSAN option: +``` +cmake -DCMAKE_BUILD_TYPE=Debug -DTSAN=on . +make +``` + +To enable UndefinedBehaviorSanitizer which helps with identifying bugs that may otherwise be hard to find, build with the UBSAN option: +``` +cmake -DCMAKE_BUILD_TYPE=Debug -UBSAN=on . +make +``` + +To get stack traces printed as well, set this environmental variable: +``` +export UBSAN_OPTIONS=print_stacktrace=1 +``` + +These tools aren't very useful without debug symbols so only use them for a Debug or Profiling build. Clang and GCC support all three tools. Note that ASAN and TSAN can't be combined. + +As for advanced debugging, Valgrind is a very powerful and useful tool which can analyze many aspects of the application. Be aware that some of the Valgrind tools should be run with an optimized build, and some with optimizations turned off. Refer to the Valgrind documentation for more information. The most common tool is Memcheck to check for memory leaks, which you run like this: @@ -233,6 +255,13 @@ cmake -DCLANG_TIDY=on . Even though many irrelevant checks are filtered out via the configuration, this will still likely produce a quite huge report (at least until most of the recommendations have been implemented). In the same manner as for scan-view, the compilation time is much longer when using this static analyzer compared to a normal build. +To build ES-DE with experimental FFmpeg video hardware decoding support, enable the following option: + +``` +cmake -DVIDEO_HW_DECODING=on . +make +``` + To build ES-DE with CEC support, enable the corresponding option, for example: ``` @@ -246,7 +275,7 @@ To build with the GLES renderer, run the following: cmake -DGLES=on . make ``` -The GLES renderer is quite limited as there is no shader support for it, so ES-DE will definitely not look as pretty as when using the default OpenGL renderer. When building on a Raspberry Pi, the GLES renderer will be automatically selected. +The GLES renderer is quite limited as there is no shader support for it, so ES-DE will definitely not look as pretty as when using the default OpenGL renderer. This option is basically deprecated as the releases for all supported platforms are built using the desktop OpenGL renderer (including the Raspberry Pi). Running multiple compile jobs in parallel is a good thing as it speeds up the build time a lot (scaling almost linearly). Here's an example telling make to run 6 parallel jobs: @@ -308,7 +337,7 @@ update-alternatives: using /usr/bin/clang++ to provide /usr/bin/c++ (c++) in man Following this, just re-run cmake and make and the binary should be built by Clang instead. -**Installing:** +**Installing** Installing the software requires root permissions, the following command will install all the required application files: @@ -363,19 +392,19 @@ CPack: - Run preinstall target for: emulationstation-de CPack: - Install project: emulationstation-de [] CPack: Create package CPackDeb: - Generating dependency list -CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.1.0-x64.deb generated. +CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.2.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-1.1.0-x64.deb +dpkg -I ./emulationstation-de-1.2.0-x64.deb ``` The package can now be installed using a package manager, for example apt: ``` -sudo apt install ./emulationstation-de-1.1.0-x64.deb +sudo apt install ./emulationstation-de-1.2.0-x64.deb ``` To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example: @@ -394,7 +423,7 @@ CPack: - Run preinstall target for: emulationstation-de CPack: - Install project: emulationstation-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-1.1.0-x64.rpm generated. +CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.2.0-x64.rpm generated. ``` On Fedora, you need to install rpmbuild before this command can be run: @@ -404,41 +433,55 @@ 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-1.1.0-x64.rpm +rpm -qi ./emulationstation-de-1.2.0-x64.rpm ``` To see the automatically generated dependencies, run this: ``` -rpm -q --requires ./emulationstation-de-1.1.0-x64.rpm +rpm -q --requires ./emulationstation-de-1.2.0-x64.rpm ``` And of course, you can also install the package: ``` -sudo dnf install ./emulationstation-de-1.1.0-x64.rpm +sudo dnf install ./emulationstation-de-1.2.0-x64.rpm ``` +**Creating an AppImage** + +The process to create a Linux AppImage is completely automated. You simply run the AppImage creation script, which has to be executed from the root of the repository: + +``` +tools/create_AppImage.sh +``` + +This script has only been tested on Ubuntu 20.04 LTS and it's recommended to go for an older operating system when building the AppImage to achieve compatibility with a large number of distributions. This does come with some sacrifices though, such as the use of an older SDL version which may not support the latest game controllers. + +The script will delete CMakeCache.txt and run cmake with the BUNDLED_CERTS option, as otherwise scraping wouldn't work on Fedora (and probably on openSUSE and a few other distributions as well). + +Both _appimagetool_ and _linuxdeploy_ are required for the build process but they will be downloaded automatically by the script if they don't exist. So to force an update to the latest build tools, delete these two AppImages prior to running create_AppImage.sh. + +After creating the AppImage it's recommended to delete CMakeCache.txt manually so the BUNDLED_CERTS option is not accidentally enabled when building the other packages. + ## Building on macOS -EmulationStation for macOS is built using Clang/LLVM which is the default compiler for this operating system. It's pretty straightforward to build software on this OS. The main problem is that there is no native package manager, but as there are several third party package managers available, this can be partly compensated for. The use of one of them, [Homebrew](https://brew.sh), is detailed below. +ES-DE for macOS is built using Clang/LLVM which is the default compiler for this operating system. It's pretty straightforward to build software on this OS. The main problem is that there is no native package manager, but as there are several third party package managers available, this can be partly compensated for. The use of one of them, [Homebrew](https://brew.sh), is detailed below. -As for code editing, I use [VSCode](https://code.visualstudio.com). I suppose Xcode could be used instead but I have no experience with this tool and no interest in it as I want to use the same tools for all the operating systems that I develop on. - -**Setting up the build tools:** +**Setting up the build tools** Install the Command Line Tools which include Clang/LLVM, Git, make etc. Simply open a terminal and enter the command `clang`. This will open a dialog that will let you download and install the tools. -Following this, install the Homebrew package manager which will greatly simplify the rest of the installation. Install it by runing the following in a terminal window: +Following this, install the Homebrew package manager which will simplify the installation of some additional required packages. Run the following in a terminal window: ``` /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" ``` Be aware that Homebrew can be really slow, especially when it compiles packages from source code. -**Package installation with Homebrew:** +**Package installation with Homebrew** -Install the required tools and dependencies: +Install the required tools: ``` -brew install clang-format cmake pkg-config nasm fdk-aac libvpx sdl2 freeimage freetype pugixml rapidjson +brew install clang-format cmake pkg-config nasm yasm ``` If building with the optional VLC video player, then run this as well: @@ -447,26 +490,13 @@ If building with the optional VLC video player, then run this as well: brew install --cask vlc ``` -**Compiling FFmpeg:** - -The FFmpeg build distributed via Homebrew has a lot of dependencies we don't need, and which would make it very difficult to package the application. Instead we will build this software with only some limited options: - -``` -git clone https://github.com/FFmpeg/FFmpeg.git -cd FFmpeg -git checkout n4.4 -./configure --prefix=/usr/local --enable-gpl --enable-nonfree --enable-shared --enable-libfdk-aac --enable-libvpx -make -sudo make install -``` - -**Some additional/optional steps:** +**Some additional/optional steps** Enable developer mode to avoid annoying password requests when attaching the debugger to a process: ``` sudo /usr/sbin/DevToolsSecurity --enable ``` -It makes me wonder who designed this functionality and what was their thinking, I've never seen anything like this on any of the other systems I've been developing on. +It makes me wonder who designed this functionality and what was their thinking, quite strange. If required, define SDKROOT. This is only needed if during compilation you get error messages regarding missing include files. Running the following will properly setup the development environment paths: ``` @@ -475,7 +505,7 @@ export SDKROOT=$(xcrun --sdk macosx --show-sdk-path) I suppose you should add this to your shell profile file or similar, but I didn't have to do this step so I'm not sure. -**Cloning and compiling:** +**Cloning and compiling** To clone the source repository, run the following: @@ -483,10 +513,33 @@ To clone the source repository, run the following: git clone https://gitlab.com/leonstyhre/emulationstation-de.git ``` -Then generate the Makefile and build the software: +For macOS all dependencies are built in-tree in the `external` directory tree. There are two scripts in the tools directory that automate this entirely and they are executed such as this: ``` cd emulationstation-de +tools/macOS_dependencies_setup.sh +tools/macOS_dependencies_build.sh +``` +This can take quite a while as multiple packages are downloaded and compiled. It's important to not have any of the dependency libraries installed using Homebrew as they will interfere with the in-tree build. + +Re-running macOS_dependencies_setup.sh will delete and download all dependencies again, and re-running macOS_dependencies_build.sh will clean and rebuild all packages. If you want to recompile a single package, make sure to first set the MACOSX_DEPLOYMENT_TARGET variable: +``` +export MACOSX_DEPLOYMENT_TARGET=10.14 +``` + +Then manually recompile the package, for example: +``` +cd external/pugixml +rm CMakeCache.txt +cmake . +make clean +make -j4 +cp libpugixml.a ../.. +``` + +After all dependencies have been built, generate the Makefile and build ES-DE: + +``` cmake . make ``` @@ -495,7 +548,7 @@ By default the master branch will be used, which is where development takes plac ``` cd emulationstation-de -git checkout stable-1.1 +git checkout stable-1.2 cmake . make ``` @@ -513,6 +566,36 @@ make ``` Keep in mind that the debug version will be much slower due to all compiler optimizations being disabled. +To enable AddressSanitizer which helps with identifying memory issues like corruption bugs and buffer overflows, build with the ASAN option: +``` +cmake -DCMAKE_BUILD_TYPE=Debug -DASAN=on . +make +``` + +To enable ThreadSanitizer which helps with identifying data races for multi-threaded code, build with the TSAN option: +``` +cmake -DCMAKE_BUILD_TYPE=Debug -DTSAN=on . +make +``` + +To enable UndefinedBehaviorSanitizer which helps with identifying bugs that may otherwise be hard to find, build with the UBSAN option: +``` +cmake -DCMAKE_BUILD_TYPE=Debug -UBSAN=on . +make +``` + +To get stack traces printed as well, set this environmental variable: +``` +export UBSAN_OPTIONS=print_stacktrace=1 +``` + +These tools aren't very useful without debug symbols so only use them for a Debug or Profiling build. Note that ASAN and TSAN can't be combined. + +Specifically on macOS it seems as if AddressSanitizer generates a lot of false positives regarding container overflows, so it may be necessary to ignore these: +``` +export ASAN_OPTIONS=detect_container_overflow=0 +``` + Running `make -j6` (or whatever number of parallel jobs you prefer) speeds up the compilation time if you have cores to spare. After building ES-DE and trying to execute the application, there could be issues with finding the dynamic link libraries for VLC (assuming VLC was enabled for the build) as these are not installed into a standard location but rather into the /Applications folder. As such, you may need to set the DYLD_LIBRARY_PATH environmental variable to find the VLC libraries. Note that this is not intended or required for the release build that will be shipped in a DMG installer or if you manually install ES-DE using _make install_. It's only needed to be able to run the binary from the build directory. You should add this to your shell profile file to avoid having to set it each time you open a new terminal window: @@ -522,92 +605,42 @@ export DYLD_LIBRARY_PATH=/Applications/VLC.app/Contents/MacOS/lib Running ES-DE from the build directory may be a bit flaky as there is no Info.plist file available which is required for setting the proper window mode and such. It's therefore recommended to run the application from the installation directory for any more in-depth testing. But normal debugging can of course be done from the build directory. -Be aware that the approach taken for macOS has the limitation that you can't build for previous operating system versions. You can certainly set CMAKE_OSX_DEPLOYMENT_TARGET to whatever version you like, but the problem is that the Homebrew libraries will most likely not work on earlier macOS versions. In theory this can be worked around by building all these libraries yourself with a lower deployment target, but it's hardly worth the effort. It's better to build on the lowest OS version that should be supported and rely on forward compatibility. +**Building for the M1 (ARM) processor** -**Code signing:** +The build steps detailed above should in theory work identically on an M1 processor but possibly some of the dependencies will not build correctly and may need manual patching. Cross-compiling using an Intel processor has been attempted but failed due to multiple issues with dependencies refusing to build. + +**Code signing** Due to the Apple notarization requirement implemented as of macOS 10.14.5 a build with simple code signing is needed for versions up to 10.13 and another build with both code signing and notarization is required for version 10.14 and higher. -macOS code signing is beyond the scope of this document, but the option MACOS_CODESIGN_IDENTITY is used to specify the code signing certificate identity, for example: +macOS code signing is beyond the scope of this document, but the CMake option MACOS_CODESIGN_IDENTITY is used to specify the code signing certificate identity, for example: ``` cmake -DMACOS_CODESIGN_IDENTITY="My Name" . ``` -Assuming the code signing ceritificate is properly setup in Keychain Access, the process will be automatic and the resulting DMG package can be notarized as-is. +Assuming the code signing ceritificate is properly setup in Keychain Access, the process will be automatic and the resulting DMG package can be notarized as-is. For some reason code signing fails if run via an SSH session, so in order for the cpack command to succeed it needs to run from a terminal window started via the GUI. -**Legacy build:** +**Legacy build** -Normally ES-DE is meant to be built for macOS 10.14 and higher, but a legacy build for earlier operating system versions can be enabled. This has been tested with a minimum version of 10.11. It's unclear if it works with even older macOS versions. +Normally ES-DE is meant to be built for macOS 10.14 and higher, but a legacy build for earlier operating system versions can be enabled. This has been tested with a minimum version of 10.11. It's unclear if it works with even older macOS releases. -To enable a legacy build, change the CMAKE_OSX_DEPLOYMENT_TARGET variable in CMakeLists.txt from 10.14 to whatever version you would like to build for. This will disable Hardened Runtime if signing is enabled and it will add 'legacy' to the DMG installer file name when running CPack. +To enable a legacy build, change the CMAKE_OSX_DEPLOYMENT_TARGET variable in CMakeLists.txt from 10.14 to whatever version you would like to build for. This will disable Hardened Runtime if signing is enabled and it will add "legacy" to the DMG installer filename when running CPack. It will also enable the bundled TLS/SSL certificates. As these older macOS releases are no longer receiving patches from Apple, certificates have likely expired meaning the scraper would not work if the bundled certificates were not used. -You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the key SMinimumSystemVersion to the version you're building for. +You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the key SMinimumSystemVersion to the version you're building for. And finally CMAKE_OSX_DEPLOYMENT_TARGET needs to be updated in tools/macOS_dependencies_build.sh. This script then needs to be executed to rebuild all dependencies for the configured macOS version. -Due to issues with getting FFmpeg to compile on some older macOS versions, ES-DE v1.0.1 is the last version where a legacy build has been tested. +**Installing** -**Installing:** - -As macOS does not have any package manager which would have handled the library dependencies, we need to bundle the required shared libraries with the application. Copy the following .dylib files from their respective installation directories to the emulationstation-de build directory: +As macOS does not have any package manager which would have handled the library dependencies, we need to bundle the required shared libraries with the application. This is almost completely automated by the build scripts. +The only exceptions are these libraries for the optional VLC video player: ``` -libavcodec.58.dylib -libavfilter.7.dylib -libavformat.58.dylib -libavutil.56.dylib -libpostproc.55.dylib -libswresample.3.dylib -libswscale.5.dylib -libfdk-aac.2.dylib -libSDL2-2.0.0.dylib -libfreeimage.dylib -libfreetype.6.dylib -libpng16.16.dylib -libvlc.dylib (only if building with the VLC video player) -libvlccore.dylib (only if building with the VLC video player) +libvlc.dylib +libvlccore.dylib ``` -All except the VLC libraries should be located in /usr/local/lib. The VLC libraries should be located in /Applications/VLC.app/Contents/MacOS/lib/ +If building the VLC video player, copy these files from the /Applications/VLC.app/Contents/MacOS/lib/ directory to the emulationstation-de build folder. -Note that the filenames could be slightly different depending on what versions you have installed on your system. - -After copying the libraries to the build directory, set their permissions like this: -``` -chmod 755 ./*.dylib -``` - -There are some secondary internal dependencies between some of these library files, and these are baked into the files as absolute paths. As such we need to rewrite these to rpaths (relative paths) which is done using the install_name_tool command. - -A script is available to automate this: `tools/macOS_change_dylib_rpaths.sh` - -Simply run the following: -``` -cd emulationstation-de -tools/macOS_change_dylib_rpaths.sh -Found file libfreetype.6.dylib - changing to rpaths -Found file libavcodec.58.dylib - changing to rpaths -Found file libavfilter.7.dylib - changing to rpaths -Found file libavformat.58.dylib - changing to rpaths -Found file libpostproc.55.dylib - changing to rpaths -Found file libswresample.3.dylib - changing to rpaths -Found file libswscale.5.dylib - changing to rpaths -``` - -Verify that it worked as expected by running the otool command, for example `otool -L libfreetype.6.dylib` should show something like the following: - -``` -libfreetype.6.dylib: - /usr/local/opt/freetype/lib/libfreetype.6.dylib (compatibility version 24.0.0, current version 24.2.0) - /usr/lib/libbz2.1.0.dylib (compatibility version 1.0.0, current version 1.0.5) - @rpath/libpng16.16.dylib (compatibility version 54.0.0, current version 54.0.0) - /usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.5) - /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1226.10.1) -``` - -It's unclear why the first line shows a reference to itself, and this line apparently can't be modified using the install_name_tool command. It doesn't matter though and the application will work fine even if this path does not exist on the system. - -You of course only need to change the absolute paths to rpaths once, well at least until you replace the libraries in case of moving to a newer version or so. - -In addition to these libraries, if building with the optional VLC video player, you need to create a `plugins` directory and copy over the following libraries, which are normally located in `/Applications/VLC.app/Contents/MacOS/plugins/`: +In addition to these you need to create a `plugins` directory and copy over the following libraries, which are located in /Applications/VLC.app/Contents/MacOS/plugins/: ``` libadummy_plugin.dylib @@ -637,20 +670,20 @@ This will be the directory structure for the installation (the VLC-related files ``` /Applications/EmulationStation Desktop Edition.app/Contents/Info.plist /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.0.dylib +/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavcodec.58.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavfilter.7.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavformat.58.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavutil.56.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfdk-aac.2.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreeimage.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpng16.16.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpostproc.55.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.3.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.5.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlc.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlccore.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/MacOS/plugins/* /Applications/EmulationStation Desktop Edition.app/Contents/Resources/EmulationStation-DE.icns /Applications/EmulationStation Desktop Edition.app/Contents/Resources/LICENSE @@ -677,7 +710,7 @@ A theme is not mandatory to start the application, but ES-DE will be basically u As indicated above, the home directory will always take precedence and any resources or themes located there will override the ones in the path of the ES-DE executable. -**Creating a .dmg installer:** +**Creating a .dmg installer** Simply run `cpack` to build a .dmg disk image/installer: @@ -688,43 +721,9 @@ CPack: Install projects CPack: - Run preinstall target for: emulationstation-de CPack: - Install project: emulationstation-de [] CPack: Create package -CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.1.0-x64.dmg generated. +CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.2.0-x64.dmg generated. ``` -Generating .dmg installers on older version of macOS seems to make them forward compatible to a pretty good extent, for instance building on El Capitan seems to generate an application that is usable on Catalina and Big Sur. The other way around is not true due to the use of dependencies from the Homebrew repository. - -**Special considerations regarding run-paths:** - -Even after considerable effort I've been unable to make CMake natively set correct rpaths for the EmulationStation binary on macOS. Therefore a hack/workaround is in place that uses install_name_tool to change absolute paths to rpaths for most of the bundled libraries. - -This is certainly not perfect as the versions of the libraries are hardcoded inside es-app/CMakeLists.txt. Therefore always check that all the rpaths are set correctly if you intend to create a .dmg image that will be used on other computers than your own. - -Simply run `otool -L EmulationStation` and verify that the result looks something like this: - -``` -./EmulationStation: - /usr/lib/libcurl.4.dylib (compatibility version 7.0.0, current version 9.0.0) - @rpath/libavcodec.58.dylib (compatibility version 58.0.0, current version 58.134.100) - @rpath/libavfilter.7.dylib (compatibility version 7.0.0, current version 7.110.100) - @rpath/libavformat.58.dylib (compatibility version 58.0.0, current version 58.76.100) - @rpath/libavutil.56.dylib (compatibility version 56.0.0, current version 56.70.100) - @rpath/libfreeimage.dylib (compatibility version 3.0.0, current version 3.18.0) - @rpath/libfreetype.6.dylib (compatibility version 24.0.0, current version 24.4.0) - @rpath/libSDL2-2.0.0.dylib (compatibility version 15.0.0, current version 15.0.0) - /System/Library/Frameworks/Cocoa.framework/Versions/A/Cocoa (compatibility version 1.0.0, current version 23.0.0) - @rpath/libvlc.dylib (compatibility version 12.0.0, current version 12.0.0) - /System/Library/Frameworks/OpenGL.framework/Versions/A/OpenGL (compatibility version 1.0.0, current version 1.0.0) - /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 400.9.4) - /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1252.250.1) -``` - -If any of the lines that should start with @rpath instead has an absolute path, then you have a problem and need to modify the install_name_tools parameters in es-app/CMakeLists.txt. - -This is what an incorrect line would look like: - -`/usr/local/opt/sdl2/lib/libSDL2-2.0.0.dylib (compatibility version 13.0.0, current version 13.0.0)` - - ## Building on Windows Both MSVC and MinGW (GCC) work fine for building ES-DE on Windows. @@ -733,7 +732,7 @@ Although I would prefer to exclude support for MSVC, this compiler simply works For this reason I think MSVC makes sense for development and MinGW for the releases. -**MSVC setup:** +**MSVC setup** Install Git for Windows: \ [https://gitforwindows.org](https://gitforwindows.org) @@ -743,22 +742,31 @@ Download the Visual Studio Build Tools (choose Visual Studio Community edition): It seems as if Microsoft has dropped support for installing the Build Tools without the Visual Studio IDE, at least I've been unable to find a way to exclude it. But I just pretend it's not installed and use VSCode instead which works perfectly fine. -During installation, choose the Desktop development with C++ workload with the following options (version details excluded): +During installation, choose the Desktop development with C++ workload with the following options (version details may differ): ``` -MSVC and x64/x86 build tools +MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest) Windows 10 SDK Just-In-Time debugger +C++ AddressSanitizer +``` + +If you will only use MSVC and not MinGW, then also add this option: +``` C++ CMake tools for Windows ``` -If you intend to use both MinGW and MSVC on the same machine, it's probably better to exclude CMake and install it manually as described in the MinGW setup instructions below. +If not installing the CMake version supplied by Microsoft, you need to make sure that you have a recent version on your machine or CMake will not be able to detect MSVC correctly. -The way the MSVC environment works is that a specific developer shell is provided where the build environment is properly configured. You open this from the Start menu via `Visual Studio 2019` -> `Visual Studio tools` -> `VC` -> `x64 Native Tools Command Prompt for VS 2019`. +As well you may need to install the latest version of Microsoft Visual C++ Redistributable which can be downloaded here:\ +https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redis -It's very 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:** +The way the MSVC environment works is that a specific developer shell is provided where the build environment is properly configured. You open this from the Start menu via `Visual Studio 2022` -> `Visual Studio tools` -> `VC` -> `x64 Native Tools Command Prompt for VS 2022 Current`. + +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: @@ -766,13 +774,16 @@ Download the following packages and install them: [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` just for convenience. +Version 9.2.0 of MinGW has been confirmed to work fine, but 10.3.0 appears broken as it causes huge performance problems for the FFmpeg function avfilter_graph_free() with execution times going from milliseconds to hundreds of milliseconds or even seconds. + Note that most GDB builds for Windows have broken Python support so that pretty printing won't work. The recommended MinGW distribution should work fine though. -**Other preparations:** +**Other preparations** In order to get clang-format onto the system you need to download and install Clang: \ [https://llvm.org/builds](https://llvm.org/builds) @@ -788,7 +799,7 @@ It's strongly recommended to set line breaks to Unix-style (line feed only) dire In the descriptions below it's assumed that all build steps for MinGW/GCC will be done in the Git Bash shell, and all the build steps for MSVC will be done in the MSVC developer console (x64 Native Tools Command Prompt for VS). -**Download the dependency packages:** +**Download the dependency packages** FFmpeg (choose the n4.4 package with win64-gpl-shared in the filename, the snapshot version will not work) \ [https://github.com/BtbN/FFmpeg-Builds/releases](https://github.com/BtbN/FFmpeg-Builds/releases) @@ -868,19 +879,7 @@ cmake -G "MinGW Makefiles" -DBUILD_SHARED_LIBS=ON . make ``` -[RapidJSON](http://rapidjson.org) - -For RapidJSON you don't need to compile, you just need the include files: - -``` -git clone git://github.com/Tencent/rapidjson.git -cd rapidjson -git checkout v1.1.0 -``` - - - -**Clone the ES-DE repository:** +**Clone the ES-DE repository** This works the same as on Unix or macOS, just run the following: @@ -892,16 +891,16 @@ By default the master branch will be used, which is where development takes plac ``` cd emulationstation-de -git checkout stable-1.1 +git checkout stable-1.2 ``` -**Setup the include directories:** +**Setup the include directories** As there is no standardized include directory structure in Windows, you need to provide the include files manually. Make a directory in your build environment tree, for instance under `C:\Programming\include` -Copy the include files for cURL, FFmpeg, FreeImage, FreeType, GLEW, pugixml, RapidJSON, SDL2 and optionally VLC to this directory. +Copy the include files for cURL, FFmpeg, FreeImage, FreeType, GLEW, pugixml, SDL2 and optionally VLC to this directory. You may need to create the SDL2 directory manually and copy the header files there. @@ -922,12 +921,11 @@ libavformat/ libavutil/ pugiconfig.hpp pugixml.hpp -rapidjson/ SDL2/ vlc/ (only if building with the VLC video player) ``` -**Copy the required library files to the ES-DE build directory:** +**Copy the required library files to the ES-DE build directory** As there's no package manager in Windows and no way to handle dependencies, we need to ship all the required shared libraries with the application. @@ -1014,7 +1012,7 @@ SDL2.dll vcomp140.dll (From Visual C++ Redistributable for Visual Studio 2015, 32-bit version) ``` -**Additional files for both MSVC and MinGW if building with the VLC video player:** +**Additional files for both MSVC and MinGW if building with the VLC video player** In addition to the files above, you need to copy some libraries from the VLC `plugins` folder. This contains a subdirectory structure but there is no requirement to retain this as libVLC apparently looks recursively for the .dll files. @@ -1042,7 +1040,7 @@ The reason to not simply copy all plugins is that the combined size of these is Place the files in the `emulationstation-de\plugins\` directory. -**Building ES-DE using MSVC:** +**Building ES-DE using MSVC** There is a bug in libVLC when building using MSVC, so three lines need to be commented out from `libvlc_media.h`. The compiler error messages will provide you with the line numbers, but they involve the callback `libvlc_media_read_cb`. @@ -1061,6 +1059,14 @@ cmake -G "NMake Makefiles" -DWIN32_INCLUDE_DIR=../include . nmake ``` +To enable AddressSanitizer which helps with identifying memory issues like corruption bugs and buffer overflows, build with the ASAN option: +``` +cmake -G "NMake Makefiles" -DWIN32_INCLUDE_DIR=../include -DASAN=on . +nmake +``` + +ThreadSanitizer and UndefinedBehaviorSanitizer aren't available for the MSVC compiler. + For some annoying reason MSVC is the only compiler that creates a debug build by default and where you need to explicitly set the build type to Release. Unfortunately nmake does not support parallel compiles so it's very slow. There are third party solutions to get multi-core building working with MSVC, but I've not investigated this in depth. @@ -1070,10 +1076,10 @@ Be aware that MSVC links against different VC++ libraries for debug and release To build ES-DE with the VLC video player in addition to the default FFmpeg player, enable the VLC_PLAYER option, for example: ``` cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DWIN32_INCLUDE_DIR=../include -DVLC_PLAYER=on . -make +nmake ``` -**Building ES-DE using MinGW:** +**Building ES-DE using MinGW** For a release build: @@ -1089,6 +1095,8 @@ cmake -G "MinGW Makefiles" -DWIN32_INCLUDE_DIR=../include -DCMAKE_BUILD_TYPE=Deb make ``` +Unfortunately AddressSanitizer, ThreadSanitizer and UndefinedBehaviorSanitizer do not seem to be supported with MinGW. + For some reason defining the `../include` path doesn't work when running CMake from PowerShell (and no, changing to backslash doesn't help). Instead use Bash, by running from a Git Bash shell. The make command works fine directly in PowerShell though so it can be run from the VSCode terminal. @@ -1101,10 +1109,13 @@ make 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 or macOS, and linking time is unendurable for a debug build (around 10 times longer on my computer compared to Linux). The debug binary is also much larger than on Unix. +Note that compilation time is much longer than on Unix or macOS, and linking time is unendurable for a debug build (around 10 times longer compared to Linux). The debug binary is also much larger than on Unix. +**TLS/SSL certificates** -**Running with OpenGL software rendering:** +On Windows the certificates supplied with the operating system will not be utilized, instead TLS/SSL certificates bundled with ES-DE will be used. + +**Running with OpenGL software rendering** If you are running Windows in a virtualized environment such as QEMU-KVM that does not support HW accelerated OpenGL, you can install the Mesa3D for Windows library, which can be downloaded at [https://fdossena.com/?p=mesa/index.frag](https://fdossena.com/?p=mesa/index.frag). @@ -1112,7 +1123,7 @@ You simply extract the opengl32.dll file into the ES-DE directory and this will Obviously this library is only intended for development and will not be shipped with ES-DE. -**Creating an NSIS installer:** +**Creating an NSIS installer** To create an NSIS installer (Nullsoft Scriptable Install System) you need to first install the NSIS creation tool: @@ -1129,7 +1140,7 @@ CPack: Install projects CPack: - Run preinstall target for: emulationstation-de CPack: - Install project: emulationstation-de [] CPack: Create package -CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-1.1.0-x64.exe generated. +CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-1.2.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. @@ -1172,11 +1183,11 @@ In some instances you may want to avoid getting code formatted, and you can acco ```c++ // clang-format off CollectionSystemDecl systemDecls[] = { -// Type Name Long name Theme folder isCustom - { AUTO_ALL_GAMES, "all", "all games", "auto-allgames", false }, - { AUTO_LAST_PLAYED, "recent", "last played", "auto-lastplayed", false }, - { AUTO_FAVORITES, "favorites", "favorites", "auto-favorites", false }, - { CUSTOM_COLLECTION, myCollectionsName, "collections", "custom-collections", true } +// Type Name Long name Theme folder isCustom + {AUTO_ALL_GAMES, "all", "all games", "auto-allgames", false}, + {AUTO_LAST_PLAYED, "recent", "last played", "auto-lastplayed", false}, + {AUTO_FAVORITES, "favorites", "favorites", "auto-favorites", false}, + {CUSTOM_COLLECTION, myCollectionsName, "collections", "custom-collections", true } }; // clang-format on ``` @@ -1228,7 +1239,7 @@ Of course you would like to get the code formatted according to the clang-format ## CA certificates and MAME ROM information -**CA certificates:** +**CA certificates** There are some files shipped with ES-DE that need to be pulled from external resources, the first one being the CA certificate bundle to get TLS/SSL support working on Windows. @@ -1242,11 +1253,11 @@ After downloading the file, rename it from `cacert.pem` to `curl-ca-bundle.crt` emulationstation-de/resources/certificates/curl-ca-bundle.crt ``` -**MAME ROM info:** +**MAME ROM info** ES-DE automatically identifies and excludes MAME BIOS and device files, as well as translating the short MAME ROM names to their full game names. This is done using information from the MAME driver file shipped with the official MAME distribution. The file needs to be converted to an internal format used by ES-DE as the original file is huge and most of the information is not required. -To get hold of the driver file, go to [https://www.mamedev.org/release.php](https://www.mamedev.org/release.php) and select the Windows version, but only download the driver information in XML format and not MAME itself. This file will be named something like `mame0226lx.zip` and unzipping it will give you a file name such as `mame0226.xml`. +To get hold of the driver file, go to [https://www.mamedev.org/release.php](https://www.mamedev.org/release.php) and select the Windows version, but only download the driver information in XML format and not MAME itself. This file will be named something like `mame0226lx.zip` and unzipping it will give you a filename such as `mame0226.xml`. Move the XML driver file to the resources/MAME directory and then convert it to the ES-DE internal files: @@ -1288,13 +1299,13 @@ The reason to not simply replace the BIOS and devices files with the new version ## Configuration -**~/.emulationstation/es_settings.xml:** +**~/.emulationstation/es_settings.xml** When ES-DE is first started, a configuration file will be created as `~/.emulationstation/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. -**Setting the ROM directory in es_settings.xml:** +**Setting the ROM directory in es_settings.xml** This complete configuration step can normally be skipped as you're presented with a dialog to change the ROM directory upon application startup if no game files are found. @@ -1322,7 +1333,7 @@ There is also support to add the variable %ESPATH% to the ROM directory setting, ``` -**~/.emulationstation/es_input.xml:** +**~/.emulationstation/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. @@ -1335,33 +1346,6 @@ The input configuration is described in the [User guide](USERGUIDE.md#input-devi You can use **--help** or **-h** to view the list of command line options, as shown here. -### Unix - -``` ---display [index 1-4] Display/monitor to use ---resolution [width] [height] Application resolution ---windowed Windowed mode, should be combined with --resolution ---fullscreen-normal Normal fullscreen mode ---fullscreen-borderless Borderless fullscreen mode (always on top) ---vsync [1/on or 0/off] Turn VSync on or off (default is on) ---max-vram [size] Max VRAM to use (in mebibytes) before swapping ---no-splash Don't show the splash screen during startup ---gamelist-only Skip automatic game ROM search, only read from gamelist.xml ---ignore-gamelist Ignore the gamelist files (useful for troubleshooting) ---show-hidden-files Show hidden files and folders ---show-hidden-games Show hidden games ---force-full Force the UI mode to Full ---force-kiosk Force the UI mode to Kiosk ---force-kid Force the UI mode to Kid ---force-input-config Force configuration of input device ---home [path] Directory to use as home path ---debug Print debug information ---version, -v Display version information ---help, -h Summon a sentient, angry tuba -``` - -### macOS and Windows - ``` --display [index 1-4] Display/monitor to use --resolution [width] [height] Application resolution @@ -1384,11 +1368,11 @@ You can use **--help** or **-h** to view the list of command line options, as sh 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. +Setting the resolution to a lower or higher value than the display resolution will add a border to the application window. + For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter: ``` --display ---fullscreen-normal ---fullscreen-borderless --max-vram --show-hidden-files --show-hidden-games @@ -1397,24 +1381,22 @@ For the following options, the es_settings.xml file is immediately updated/saved ## es_systems.xml -The es_systems.xml file contains the system configuration data for ES-DE, written in XML format. This defines the system name, the full system name, the ROM path, the allowed file extensions, the launch command, the platform (for scraping) and the theme to use. +The es_systems.xml file contains the game systems configuration data for ES-DE, written in XML format. This defines the system name, the full system name, the ROM path, the allowed file extensions, the launch command, the platform (for scraping) and the theme to use. -ES-DE ships with a comprehensive `es_systems.xml` configuration file and normally you shouldn't need to modify this. However there may be special circumstances such as wanting to use alternative emulators for some game systems or perhaps you need to add additional systems altogether. +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 make a customized version of the systems configuration file, it first needs to be copied to `~/.emulationstation/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows unless overridden using 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. `~/.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.) + +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. -Note that when copying the bundled es_systems.xml file to ~/.emulationstation/custom_systems/, it will completely replace the default file processing. So when upgrading to future ES-DE versions, any modifications such as additional game systems will not be enabled until the customized configuration file has been manually updated. - -It doesn't matter in which order you define the systems as they will be sorted by the full system name inside the application, but it's still probably a good idea to add them in alphabetical order to make the file easier to maintain. +It doesn't matter in which order you define the systems as they will be sorted by the `` tag or by the optional `` tag when displayed inside the application. But it's still a good idea to add the systems in alphabetical order to make the configuration file easier to maintain. Keep in mind that you have to set up your emulators separately from ES-DE as the es_systems.xml file assumes that your emulator environment is properly configured. Below is an overview of the file layout with various examples. For the command tag, the newer es_find_rules.xml logic described later in this document removes the need for most of the legacy options, but they are still supported for special configurations and for backward compatibility with old configuration files. -For a real system entry there can of course not be multiple entries for the same tag such as the multiple \ entries listed here. - ```xml @@ -1422,28 +1404,46 @@ For a real system entry there can of course not be multiple entries for the same - + snes Nintendo SNES (Super Nintendo) + + Super Nintendo + %ROMPATH%/snes + The extensions are case sensitive and they must begin with a dot. --> .smc .SMC .sfc .SFC .swc .SWC .fig .FIG .bs .BS .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% + + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x2010_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_mercury_accuracy_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/mednafen_supafaust_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/mesen-s_libretro.so %ROM% + retroarch -L ~/.config/retroarch/cores/snes9x_libretro.so %ROM% @@ -1469,12 +1469,14 @@ For a real system entry there can of course not be multiple entries for the same expanded to the directory of the ES-DE executable. --> "%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM% - - bash %ROM% + + %RUNINBACKGROUND% bash %ROM% - %HIDEWINDOW% cmd /C %ROM% + The optional %HIDEWINDOW% variable is used to hide the console window, which would otherwise be visible when launching games. --> + %HIDEWINDOW% %RUNINBACKGROUND% cmd.exe /C %ROM% + + + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .zip .ZIP + /usr/games/fceux %ROM% + nes + nes + + +``` + +If adding the `` tag to the file, the bundled es_systems.xml file will not be processed. For this example it wouldn't be a very good idea as NES would then be the only platform that could be used in ES-DE. + +```xml + + + + + + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .zip .ZIP + /usr/games/fceux %ROM% + nes + nes + + +``` + +Here is yet another example with the addition of the `snes` system where some file extensions and alternative emulator entries have been removed, and the full name and sorting have been modified. + +```xml + + + + + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .zip .ZIP + /usr/games/fceux %ROM% + nes + nes + + + snes + Super Nintendo + Nintendo SNES (Super Nintendo) + %ROMPATH%/snes + .smc .SMC .sfc .SFC .swc .SWC .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x2010_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_libretro.so %ROM% + snes + snes + + ``` ## es_find_rules.xml @@ -1561,81 +1634,92 @@ This file makes it possible to define rules for where to search for the emulator 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 override the bundled file. -Here's an example es_find_rules.xml file for Unix: +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 - - - retroarch - org.libretro.RetroArch - RetroArch-Linux-x86_64.AppImage - - - /var/lib/flatpak/exports/bin/org.libretro.RetroArch - ~/Applications/RetroArch-Linux-x86_64.AppImage - ~/.local/bin/RetroArch-Linux-x86_64.AppImage - ~/bin/RetroArch-Linux-x86_64.AppImage - - - - - - yuzu - org.yuzu_emu.yuzu - yuzu.AppImage - - - /var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu - ~/Applications/yuzu.AppImage - ~/.local/bin/yuzu.AppImage - ~/bin/yuzu.AppImage - - - - - - ~/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 - - + + + retroarch + org.libretro.RetroArch + RetroArch-Linux-x86_64.AppImage + + + /var/lib/flatpak/exports/bin/org.libretro.RetroArch + ~/Applications/RetroArch-Linux-x86_64.AppImage + ~/.local/bin/RetroArch-Linux-x86_64.AppImage + ~/bin/RetroArch-Linux-x86_64.AppImage + + + + + + ~/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 + + + + + + yuzu + org.yuzu_emu.yuzu + yuzu.AppImage + + + /var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu + ~/Applications/yuzu.AppImage + ~/.local/bin/yuzu.AppImage + ~/bin/yuzu.AppImage + + ``` -It's pretty straightforward, there are currently three rules supported for finding emulators, `winregistrypath`, `systempath` and `staticpath` and there is one rule supported for finding the emulator cores, `corepath`. +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` is 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_fules.xml file. +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% +%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 `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`, the key `SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\retroarch.exe` will be searched for. 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 key actually exists, and 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 `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. -The winregistrypath rules are always processed first, followed by systempath and then staticpath. This is done regardless of which order they are defined in the es_find_rules.xml file. +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. @@ -1653,19 +1737,41 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo - - - /Applications/RetroArch.app/Contents/MacOS/RetroArch - - - - - - ~/Library/Application Support/RetroArch/cores - - /Applications/RetroArch.app/Contents/Resources/cores - - + + + /Applications/RetroArch.app/Contents/MacOS/RetroArch + + + + + + ~/Library/Application Support/RetroArch/cores + + /Applications/RetroArch.app/Contents/Resources/cores + + + + + + /Applications/dosbox-staging.app/Contents/MacOS/dosbox + + /usr/local/bin/dosbox-staging + + + + + + /Applications/mupen64plus.app/Contents/MacOS/mupen64plus + + /usr/local/bin/mupen64plus + + + + + + /Applications/PCSX2.app/Contents/MacOS/PCSX2 + + ``` @@ -1673,48 +1779,69 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo - - - - 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 - - %ESPATH%\RetroArch-Win64\retroarch.exe - %ESPATH%\RetroArch\retroarch.exe - %ESPATH%\..\RetroArch-Win64\retroarch.exe - %ESPATH%\..\RetroArch\retroarch.exe - - - - - - yuzu.exe - - - ~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe - - %ESPATH%\yuzu\yuzu-windows-msvc\yuzu.exe - %ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe - - - - - %EMUPATH%\cores - - + + + + 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%\RetroArch-Win64\retroarch.exe + %ESPATH%\RetroArch\retroarch.exe + %ESPATH%\..\RetroArch-Win64\retroarch.exe + %ESPATH%\..\RetroArch\retroarch.exe + + + + + %EMUPATH%\cores + + + + + + SOFTWARE\PCSX2\Install_Dir|\pcsx2.exe + + + pcsx2.exe + + + C:\Program Files (x86)\PCSX2\pcsx2.exe + D:\Program Files (x86)\PCSX2\pcsx2.exe + + %ESPATH%\PCSX2\pcsx2.exe + %ESPATH%\..\PCSX2\pcsx2.exe + + + + + + yuzu.exe + + + ~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe + + %ESPATH%\yuzu\yuzu-windows-msvc\yuzu.exe + %ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe + + ``` @@ -1748,7 +1875,7 @@ For example: ~/.emulationstation/gamelists/megadrive/gamelist.xml ``` -**gamelist.xml file structure:** +**gamelist.xml file structure** An example gamelist.xml entry for the Commodore 64 game Popeye: @@ -1772,7 +1899,7 @@ An example gamelist.xml entry for the Commodore 64 game Popeye: Everything is enclosed in a `` tag, and the information for each game or folder is enclosed in a corresponding `` or `` tag. Each piece of metadata is encoded as a string. -**gamelist.xml reference:** +**gamelist.xml reference** There are a few different data types for the metadata which the string values in the gamelist.xml files are converted to during file loading: @@ -1805,8 +1932,9 @@ There are two basic categories of metadata, `game` and `folders` and the metdata * `nogamecount` - bool, indicates whether the game should be excluded from the game counter and the automatic and custom collections * `nomultiscrape` - bool, indicates whether the game should be excluded from the multi-scraper * `hidemetadata` - bool, indicates whether to hide most of the metadata fields when displaying the game in the gamelist view -* `launchcommand` - string, overrides the emulator and core settings on a per-game basis * `playcount` - integer, the number of times this game has been played +* `controller` - string, used to display controller badges +* `altemulator` - string, overrides the emulator/launch command on a per game basis * `lastplayed` - statistic, datetime, the last date and time this game was played For folders, most of the fields are identical although some are removed. In the list below, the fields with identical function compared to the game files described above have been left without a description. @@ -1827,9 +1955,10 @@ For folders, most of the fields are identical although some are removed. In the * `broken` * `nomultiscrape` * `hidemetadata` +* `controller` * `lastplayed` - statistic, for folders this is inherited by the latest game file launched inside the folder. -**Additional gamelist.xml information:** +**Additional gamelist.xml information** * If a value matches the default for a particular piece of metadata, ES-DE will not write it to the gamelist.xml file (for example, if `genre` isn't specified, an empty genre tag will not be written) @@ -1872,7 +2001,7 @@ By default all controller input (keyboard and controller button presses) will be It's possible to easily create a portable installation of ES-DE on Windows, for example to place on a USB memory stick. -For the sake of this example, let's assume that the removable media has the device name `F:\` +For this example, let's assume that the removable media has the device name `F:\` These are the steps to perform: @@ -1884,45 +2013,61 @@ These are the steps to perform: You should end up with something like this: ``` F:\EmulationStation-DE\ +F:\EmulationStation-DE\dosbox-staging\ +F:\EmulationStation-DE\PCSX2\ F:\EmulationStation-DE\RetroArch-Win64\ -F:\EmulationStation-DE\yuzu\ F:\EmulationStation-DE\ROMs\ +F:\EmulationStation-DE\RPCS3\ +F:\EmulationStation-DE\xemu\ +F:\EmulationStation-DE\xenia\ +F:\EmulationStation-DE\yuzu\ F:\EmulationStation-DE\portable.txt ``` -(Yuzu is an optional Nintendo Switch emulator.) +This is just an example, you may not have all these emulators installed and as well there will of course be many more files and directories than those listed above inside the F:\EmulationStation-DE directory. -Of course there will be many more files and directories from the normal installation than those listed above. - -How this 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 in 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:\ in 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 .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:\ in this example. If the --home command line parameter is passed when starting ES-DE, that will override the portable.txt file. -The emulators that will be automatically searched for by ES-DE are (relative to the EmulationStation-DE directory): +By default the emulators that will be automatically searched for by ES-DE are (relative to the EmulationStation-DE directory): ``` RetroArch-Win64\retroarch.exe RetroArch\retroarch.exe +dosbox-staging\dosbox.exe +PCSX2\pcsx2.exe +RPCS3\rpcs3.exe +xemu\xemu.exe +xenia\xenia.exe yuzu\yuzu-windows-msvc\yuzu.exe ..\RetroArch-Win64\retroarch.exe ..\RetroArch\retroarch.exe +..\dosbox-staging\dosbox.exe +..\PCSX2\pcsx2.exe +..\RPCS3\rpcs3.exe +..\xemu\xemu.exe +..\xenia\xenia.exe ..\yuzu\yuzu-windows-msvc\yuzu.exe ``` If you want to place your emulators elsewhere, you need to create a customized es_find_rules.xml file, which is explained earlier in this document. -Start ES-DE from the F:\ device and check that everything works as expected. +Start ES-DE from the F:\ device and check that everything works as expected. Just be aware that some emulators may not play that well with a portable setup and may store their configuration files in your home directory (probably on your C: drive) or at some other location. So when using the portable installation on another computer you may need to perform some additional emulator-specific setup. Following this, optionally copy any existing gamelist.xml files, game media files etc. to the removable media. For example: ``` -F:\EmulationStation-DE\.emulationstation\gamelists\ +F:\EmulationStation-DE\.emulationstation\collections\ F:\EmulationStation-DE\.emulationstation\downloaded_media\ +F:\EmulationStation-DE\.emulationstation\gamelists\ ``` -You now have a fully functional portable retro gaming installation! +You could also 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. -The portable installation works exactly as a normal installation, i.e. you can use the built-in scraper, edit metadata etc. +You now have a fully functional portable retrogaming installation! + +The portable installation works exactly as a normal installation, i.e. you can use the built-in scraper, edit metadata, launch games etc. ## Custom event scripts @@ -1935,22 +2080,22 @@ We'll go through two examples: * Creating a log file that will record the start and end time for each game we play, letting us see how much time we spend on retro-gaming * Changing the system resolution when launching and returning from a game in order to run the emulator at a lower resolution than ES-DE -**Note:** The following examples are for Unix systems, but it works the same way on macOS (which is also Unix after all), and on Windows (although .bat batch files are then used instead of shell scripts and any spaces in the parameters are not escaped as is the case on Unix). +The following examples are for Unix systems, but it works the same way on macOS (which is also Unix after all), and on Windows (although .bat batch files are then used instead of shell scripts and any spaces in the parameters are not escaped as is the case on Unix). -The events executed when a game starts and ends are called `game-start` and `game-end` respectively. Finding these event names is easily achieved by starting ES-DE with the `--debug` flag. If this is done, all attempts to execute custom event scripts will be logged to es_log.txt, including the event names. +The events executed when a game starts and ends are named `game-start` and `game-end` respectively. Finding these event names is easily achieved by starting ES-DE with the `--debug` flag. If this is done, all attempts to execute custom event scripts will be logged to es_log.txt, including the event names. So let's create the folders for these events in the scripts directory. The location is `~/.emulationstation/scripts` -**Game log:** +**Game log** -After creating the directories, we need to create the scripts to log the actual game launch and game ending. The parameters that are passed to the scripts varies depending on the type of event, but for these events the two parameters are the absolute path to the game file, and the game name as shown in the gamelist view. +After creating the directories, we need to create the scripts to log the actual game launch and game ending. The parameters that are passed to the scripts vary depending on the type of event, but for these events the four parameters are the absolute path to the game file, the game name as shown in the gamelist view, the system name and the full system name. 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}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt +echo Starting game "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt ``` And let's name the end script `game_end_logging.sh` with the following contents: @@ -1958,7 +2103,7 @@ 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}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt +echo "Ending game " "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt ``` After creating the two scripts, you should have something like this on the filesystem: @@ -1973,27 +2118,27 @@ Don't forget to make the scripts executable (e.g. "chmod 755 ./game_start_loggin If we now start ES-DE with the debug flag and launch a game, something like the following should show up in es_log.txt: ``` -Aug 05 14:19:24 Debug: Scripting::fireEvent(): game-start "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" -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" +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:27:15 Debug: Scripting::fireEvent(): game-end "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" -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" +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" ``` Finally after running some games, ~/.emulationstation/game_playlog.txt should contain something like the following: ``` -Starting game "The Legend Of Zelda" ("/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip") at 2020-08-05 14:19:24 -Ending game "The Legend Of Zelda" ("/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip") at 2020-08-05 14:27:15 -Starting game "Quake" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 14:38:46 -Ending game "Quake" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 15:13:58 -Starting game "Pirates!" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:15:24 -Ending game "Pirates!" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:17:11 +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 +Ending game "The Legend Of Zelda" "Nintendo Entertainment System" ("/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip") at 2020-08-05 14:27:15 +Starting game "Quake" "Ports" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 14:38:46 +Ending game "Quake" "Ports" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 15:13:58 +Starting game "Pirates!" "Commodore 64" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:15:24 +Ending game "Pirates!" "Commodore 64" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:17:11 ``` -**Resolution changes:** +**Resolution changes** The same directories are used as for the above example with the game log. diff --git a/README.md b/README.md index 97ec5b3d1..13e7d8be6 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ YouTube channel with installation instruction videos:\ Discord server:\ [https://discord.gg/EVVX4DqWAP](https://discord.gg/EVVX4DqWAP) -Although there are multiple forks of EmulationStation in existence, the goal of this edition is to make the software as easy as possible to install and use as a standalone application, and to support the major desktop operating systems, i.e. Unix/Linux, macOS and Windows. Since it's intended to be used as a desktop application rather than as the primary interface for the computer, there are no plans to provide system administration utilities or control over emulator settings from within ES-DE. +Although there are multiple forks of EmulationStation in existence, the goal of this edition is to make the software as easy as possible to install and use as a standalone application, and to support the major desktop operating systems, i.e. Windows, macOS and Unix/Linux. Since it's intended to be used as a desktop application rather than as the primary interface for the computer, there are no plans to provide system administration utilities or control over emulator settings from within ES-DE. The software comes preconfigured for use primarily with [RetroArch](https://www.retroarch.com), although this can be changed as all emulator settings are fully configurable, even on a per-game basis. @@ -38,31 +38,21 @@ If using a Mac with an M1 processor you need to install the x86 version of Retro ### Download -The latest stable version is 1.1.0 (released 2021-08-10) +The latest version is 1.2.0 (released 2021-12-28) | Package | Operating systems | Architecture | Download link | | :------------------ | :------------------------------------------------------ | :----------- | :------------- | -| Windows installer | Windows 10 and 8.1 (probably Windows 11 as well) | x64 (x86) | [EmulationStation-DE-1.1.0-x64.exe](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/14892429/download)| -| macOS DMG installer | macOS 10.14 "Mojave" to 11 "Big Sur" | x64 (x86) | [EmulationStation-DE-1.1.0-x64.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/14892342/download)| -| Debian DEB package | Ubuntu 20.04 to 21.10, Linux Mint 20.2, possibly others | x64 (x86) | [emulationstation-de-1.1.0-x64.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/14892301/download)| -| Fedora RPM package | Fedora Workstation 35, possibly others | x64 (x86) | [emulationstation-de-1.1.0-x64.rpm](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/14892436/download)| - -The latest prerelease version is 1.2.0-rc (released 2021-12-19) - -| Package | Operating systems | Architecture | Download link | -| :------------------ | :------------------------------------------------------ | :----------- | :------------- | -| Windows installer | Windows 10 and 8.1 (probably Windows 11 as well) | x64 (x86) | [EmulationStation-DE-1.2.0-rc-x64.exe](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/24488187/download)| -| macOS DMG installer | macOS 10.14 "Mojave" to 12 "Monterey" | x64 (x86) | [EmulationStation-DE-1.2.0-rc-x64.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/24488181/download)| -| macOS DMG installer | Legacy macOS 10.11 "El Capitan" to 10.13 "High Sierra" | x64 (x86) | [EmulationStation-DE-1.2.0-rc-x64_legacy.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/24488192/download)| -| Debian DEB package | Ubuntu 20.04 to 21.10, Linux Mint 20.2, possibly others | x64 (x86) | [emulationstation-de-1.2.0-rc-x64.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/24488172/download)| -| Fedora RPM package | Fedora Workstation 35, possibly others | x64 (x86) | [emulationstation-de-1.2.0-rc-x64.rpm](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/24488198/download)| -| Linux AppImage | Most modern Linux distributions | x64 (x86) | [emulationstation-de-1.2.0-rc-x64.AppImage](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/24488168/download)| -| Debian DEB package | Raspberry Pi OS (Raspian) | ARM 32-bit | [emulationstation-de-1.2.0-rc-armv7l.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/24488160/download)| -| Debian DEB package | Raspberry Pi OS (Raspian) | ARM 64-bit | [emulationstation-de-1.2.0-rc-aarch64.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/24488150/download)| +| Windows installer | Windows 10 and 8.1 (probably Windows 11 as well) | x64 (x86) | [EmulationStation-DE-1.2.0-x64.exe](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023950/download)| +| macOS DMG installer | macOS 10.14 "Mojave" to 12 "Monterey" | x64 (x86) | [EmulationStation-DE-1.2.0-x64.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023939/download)| +| macOS DMG installer | Legacy macOS 10.11 "El Capitan" to 10.13 "High Sierra" | x64 (x86) | [EmulationStation-DE-1.2.0-x64_legacy.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023954/download)| +| Debian DEB package | Ubuntu 20.04 to 21.10, Linux Mint 20.2, possibly others | x64 (x86) | [emulationstation-de-1.2.0-x64.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023934/download)| +| Fedora RPM package | Fedora Workstation 35, possibly others | x64 (x86) | [emulationstation-de-1.2.0-x64.rpm](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023958/download)| +| Linux AppImage | Most modern Linux distributions | x64 (x86) | [emulationstation-de-1.2.0-x64.AppImage](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023919/download)| +| Debian DEB package | Raspberry Pi OS (Raspian) | ARM 32-bit | [emulationstation-de-1.2.0-armv7l.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023905/download)| +| Debian DEB package | Raspberry Pi OS (Raspian) | ARM 64-bit | [emulationstation-de-1.2.0-aarch64.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023885/download)| All previous releases can be downloaded from [here](https://gitlab.com/leonstyhre/emulationstation-de/-/packages). - Flatpak will not be supported on Linux as this packaging system is too restrictive with its sandbox approach, making ES-DE virtually useless as it can't freely locate and launch emulators on the system. If using FreeBSD, NetBSD or OpenBSD you will need to build ES-DE from source code for the time being, as explained in [INSTALL.md](INSTALL.md). @@ -72,7 +62,7 @@ Please refer to [CHANGELOG.md](CHANGELOG.md) for more information about the rele ### Contributing -If you would like to contribute to the development of ES-DE, then that's great! Please read how to participate [here](CONTRIBUTING.md). (You can also read about planned future releases and features there). +If you would like to contribute to the development of ES-DE, then that's great! Please read how to participate [here](CONTRIBUTING.md) where you can also read about planned future releases and features. # Additional information @@ -89,13 +79,13 @@ If you would like to contribute to the development of ES-DE, then that's great! # Some feature highlights -Here are some highlights of what EmulationStation Desktop Edition provides, displayed using the default theme set rbsimple-DE. There are of course many more features available, as covered in the [User guide](USERGUIDE.md). +Here are some highlights of what ES-DE provides, displayed using the default theme set rbsimple-DE. There are of course many more features available, as covered in the [User guide](USERGUIDE.md). ![alt text](images/es-de_system_view.png "ES-DE System View") _The **System view**, which is the default starting point for the application, it's here that you browse through your game systems._ ![alt text](images/es-de_gamelist_view.png "ES-DE Gamelist View") -_The **Gamelist view**, it's here that you browse the games for a specific system. Note the support for mixing files and folders, and as well that favorite games are marked with stars. There is a game counter to the upper right, displaying the total number of games and the number of favorite games for this system._ +_The **Gamelist view**, it's here that you browse the actual games per system. Note the support for mixing files and folders, and as well that a few badges are displayed indicating that the selected game is a favorite, that it's suitable for children and that it's controlled using a joystick. There is a game counter to the upper right as well, displaying the total number of games and the number of favorite games for this system._ ![alt text](images/es-de_folder_support.png "ES-DE Folder Support") _Another example of the gamelist view, displaying advanced folder support. You can scrape folders for game info and game media, sort folders as you would files, mark them as favorites etc. In this example ES-DE has been configured to sort favorite games above non-favorites._ @@ -110,13 +100,13 @@ _This is a view of the built-in scraper which downloads game info and game media _There are many settings for the scraper including options to define which type of info and media to download. The above screenshot shows only a portion of these settings._ ![alt text](images/es-de_metadata_editor.png "ES-DE Metadata Editor") -_In addition to the scraper there is a fully-featured metadata editor that can be used to modify information on a per-game basis. Here you can also toggle some additional flags which the scraper does not set, such as if the game is a favorite or if you have completed it. Some of these flags can then be filtered in the gamelist view, letting you for instance only display games that you have not played through._ +_In addition to the scraper there is a fully-featured metadata editor that can be used to modify information on a per-game basis. Here you can also toggle some additional flags which the scraper does not set, such as if the game is a favorite or if you have completed it. Most of these flags can also be filtered in the gamelist view, letting you for instance only display games that you have not played through._ ![alt text](images/es-de_screensaver.png "ES-DE Screensaver") -_There are four types of built-in screensavers available, including a slideshow and the video screensaver shown in action above. These screensavers start after a configurable number of minutes of inactivity, and randomly display game media that you have previously scraped. If the corresponding option has been enabled, you can jump to the game from the screensaver, or even start it directly. There is shader support in ES-DE to render scanlines and screen blur on top of the videos (for the slideshow screensaver, scanline rendering is provided)._ +_There are four types of built-in screensavers available, including a slideshow and the video screensaver shown in action above. These screensavers start after a configurable number of minutes of inactivity, and randomly display game media that you have previously scraped. If the corresponding option has been enabled, you can jump to the game from the screensaver, or even launch it directly. There is shader support in ES-DE to render scanlines and screen blur on top of the videos (for the slideshow screensaver, scanline rendering is provided)._ ![alt text](images/es-de_ui_theme_support.png "ES-DE Theme Support") -_ES-DE is fully themeable, so if you prefer another look than what the default theme rbsimple-DE gives you, it's possible to apply another theme set. In the example above a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme is used. Be aware though that although ES-DE is backwards compatible with older EmulationStation themes, some newer features which are specific to ES-DE will not work, at least not until the theme authors update their themes._ +_ES-DE is fully themeable, so if you prefer another look than what the default theme rbsimple-DE offers, it's possible to apply another theme set. The image above is of the modern-DE theme that is also bundled with the application. Note that although ES-DE is backward compatible with older RetroPie EmulationStation themes, some newer features which are specific to ES-DE will not work, at least not until the theme authors update their themes._ ![alt text](images/es-de_ui_easy_setup.png "ES-DE Easy Setup") _A lot of effort has been spent on making ES-DE easy to setup and use. The above screenshot shows the dialog if starting the application without any game files present in the default ROM directory. ES-DE also ships with a comprehensive game systems configuration file, so unless you really want to customize your setup, you should not need to tinker with the configuration._ \ No newline at end of file diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 2c47e4a9b..94e8854b4 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -55,7 +55,7 @@ As for display resolutions, the minimum pixel value is 224 and the maximum is 76 The installation procedure is just covered briefly here and may differ a bit for your specific operating system, so in case of problems refer to your system documentation. -**Installing a Linux .deb package** +**Installing the Linux .deb package** The .deb package is intended for Linux distributions based on Debian, such as Ubuntu, Linux Mint, Raspberry Pi OS etc. Your distribution should include a graphical package installer, but if you prefer to use the command line, run the following which will install ES-DE and resolve any dependencies: @@ -63,7 +63,7 @@ The .deb package is intended for Linux distributions based on Debian, such as Ub sudo apt install ./emulationstation-de-1.2.0-x64.deb ``` -**Installing a Linux .rpm package** +**Installing the Linux .rpm package** On Fedora the RPM Fusion repository is a prerequisite for the installation, it can be installed like this: @@ -81,7 +81,7 @@ sudo dnf install ./emulationstation-de-1.2.0-x64.rpm Of course the filename will differ slightly depending on the architecture, the example above is for the x64/x86 platform. -**Running a Linux AppImage file** +**Running the Linux AppImage file** In addition to the .deb and .rpm packages covered above, ES-DE is also available as an AppImage which should be usable on most modern x86 64-bit Linux distributions. After download you have to set the file as executable, such as this: ``` @@ -241,7 +241,7 @@ sudo snap connect retroarch:removable-media On Raspberry Pi OS 10 Sony DualShock 4 controllers have problems with some button presses that don't register correctly. The issue appears resolved on Raspberry Pi OS 11. -On Raspberry Pi OS 11 there are various graphics issues and sometimes the application or emulator completely freezes which requires a power cycle of the machine. This is seemingly due to GPU driver bugs and we can only wait for OS updates to address these problems. These issues have not been encountered on Raspberry Pi OS 10. +On Raspberry Pi OS 11 there are various graphics issues and sometimes the application or emulator completely freezes which requires a power cycle of the machine. This is seemingly due to GPU driver bugs and we can only wait for OS updates to address these problems. These issues have not been encountered on Raspberry Pi OS 10 so for now this older OS version is recommended. ## Game system customizations @@ -1447,7 +1447,7 @@ These are mostly technical settings. Using this interface it's possible to select alternative emulators to use per game system, which requires that these alternatives have been defined in the es_systems.xml file. Note that only systems that you have currently populated will be listed. To change to an alternative emulator, you simply select a system from the list and choose which alternative to use from the presented options. If you select an alternative emulator and later remove its corresponding entry from the es_systems.xml file, an error message will be shown on application startup telling you to review your invalid emulator selection. Games will still launch, but the default emulator will be used in this case. How to clear an invalid entry should be self-explanatory once you access the interface. It's also possible to set alternative emulators per game using the metadata editor. If this is done, it will take precedence and override the system-wide emulator selection for the specific game. The alternative emulator badges and the corresponding gamelist filter are controlled by these per-game alternative emulator values and not by the system-wide option. ![alt text](images/es-de_alternative_emulators.png "ES-DE Scraper Settings") -_The system-wide alternative emulators interface. An entry in bold and with a gear symbol indicates that an alternative emulator has been selected. The other entries are using the default emulators._ +_The system-wide alternative emulators interface. An entry in bold and with a gear symbol indicates that an alternative emulator has been selected._ **Game media directory** @@ -1816,7 +1816,7 @@ You can later add additional games to the collection by navigating to it, bringi _Example of custom collections, here configured as genres._ ![alt text](images/es-de_custom_collections_editing.png "ES-DE Custom Collections") -_When editing a custom collection, a tick symbol will be displayed for any game that is already part of the collection._ +_When editing a custom collection, 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` diff --git a/USERGUIDE.md b/USERGUIDE.md index d3ec78078..39dcac20d 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -1,4 +1,4 @@ -# EmulationStation Desktop Edition (ES-DE) v1.1 - User guide +# EmulationStation Desktop Edition (ES-DE) v1.2 - User guide This document is intended as a quick start guide and as a reference for the application settings and general functionality. For details on how to build ES-DE from source code and to perform more advanced configuration, please refer to [INSTALL.md](INSTALL.md). @@ -17,7 +17,7 @@ If you just want to get started as quickly as possible, simply follow these step 5) Start RetroArch and install the required emulator cores 6) Start ES-DE, scrape game media for your collection and play some games! -You can always close the application immediately by pressing F4 on the keyboard. +You can always close the application immediately by using the keyboard, by default the exit key is mapped to F4 but this can be changed to Alt + F4, Alt + Q or Command Q (on macOS) using the _Exit button combo_ menu option. For additional details, read on below. @@ -31,41 +31,66 @@ To install ES-DE, just download the package or installer from [https://es-de.org The following operating systems have been tested (all for the x86 architecture unless otherwise stated): -* Ubuntu 20.04 to 21.04 -* Linux Mint 20 -* Manjaro 21 -* Fedora 33 Workstation -* FreeBSD 12.2 -* NetBSD 9.1 -* OpenBSD 6.8 -* macOS 10.14 "Mojave" to 11 "Big Sur" (ARM via Rosetta 2 is supported) -* macOS 10.11 "El Capitan" (v1.0 release only) * Windows 10 * Windows 8.1 +* macOS 10.14 "Mojave" to 12 "Monterey" (the M1 processor is supported via Rosetta 2) +* macOS 10.11 "El Capitan" (legacy release) +* Ubuntu 20.04 to 21.10 +* Linux Mint 20.2 +* Manjaro 21.1 +* Fedora 35 Workstation +* elementary OS 6 +* Raspberry Pi OS 10 and 11 (armv7l and aarch64) +* FreeBSD 13.0 +* NetBSD 9.1 +* OpenBSD 6.8 -**Note:** If using a Mac with an ARM CPU (e.g. M1) you need to install the x86 version of RetroArch and any other emulators, or you won't be able to launch any games. This will be fixed whenever a native macOS ARM build of ES-DE is released. +If using a Mac with an M1 processor you need to install the x86 version of RetroArch and any other emulators, or you won't be able to launch any games. This will be fixed whenever a native macOS ARM build of ES-DE is released. + +Additional known issues are detailed in [CHANGELOG.md](CHANGELOG.md#known-issues). + +As for display resolutions, the minimum pixel value is 224 and the maximum is 7680. This means that you can run ES-DE at for instance 320x224 all the way up to 7680x4320 (8K UHD). Vertical screen orientation is also supported, as well as ultra-wide resolutions like 3840x1440. Note that there could be some minor visual glitches when running in vertical orientation (this will be fixed in future ES-DE releases) and for the best experience you will probably need to use a customized theme set when running at extreme or unusual resolutions. The installation procedure is just covered briefly here and may differ a bit for your specific operating system, so in case of problems refer to your system documentation. -**Installing a Linux .deb package** +**Installing the Linux .deb package** -The .deb package is intended for Linux distributions based on Debian, such as Ubuntu, Linux Mint etc. Your distribution should include a graphical package installer, but if you prefer to use the command line, run the following which will install ES-DE and resolve any dependencies: +The .deb package is intended for Linux distributions based on Debian, such as Ubuntu, Linux Mint, Raspberry Pi OS etc. Your distribution should include a graphical package installer, but if you prefer to use the command line, run the following which will install ES-DE and resolve any dependencies: ``` -sudo apt install ./emulationstation-de-1.0.0-x64.deb +sudo apt install ./emulationstation-de-1.2.0-x64.deb ``` -**Installing a Linux .rpm package** +**Installing the Linux .rpm package** -On Fedora you can use the graphical package installer or run this command, either method should automatically resolve the dependencies: +On Fedora the RPM Fusion repository is a prerequisite for the installation, it can be installed like this: ``` -sudo dnf install ./emulationstation-de-1.0.0-x64.rpm +sudo dnf install \ +https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \ +https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm ``` +Then you can use the graphical package installer or run this command, either method should automatically resolve the dependencies: + +``` +sudo dnf install ./emulationstation-de-1.2.0-x64.rpm +``` + +Of course the filename will differ slightly depending on the architecture, the example above is for the x64/x86 platform. + +**Running the Linux AppImage file** + +In addition to the .deb and .rpm packages covered above, ES-DE is also available as an AppImage which should be usable on most modern x86 64-bit Linux distributions. After download you have to set the file as executable, such as this: +``` +chmod +x emulationstation-de-1.2.0-x64.AppImage +``` + + Following this you can launch ES-DE by double-clicking on the file using your file manager. It's also possible to run it from a terminal window. All command line options work as if installed as an ordinary package. + **Installing on macOS and Windows** -There's not really much to say about these operating systems, just install ES-DE as you would any other application. On maCOS it's via the .dmg drag-and-drop installer, and on Windows via the normal application installer. +There's not really much to say about these operating systems, just install ES-DE as you would any other application. On macOS it's via the .dmg drag-and-drop installer, and on Windows via the normal application installer. **On first application startup** @@ -73,11 +98,11 @@ Upon first startup, ES-DE will create its `~/.emulationstation` home directory. On Unix this means /home/\/.emulationstation/, on macOS /Users/\/.emulationstation/ and on Windows C:\Users\\\\.emulationstation\ -**Note:** As of ES-DE v1.1 there is no internationalization support, which means that the application will always require the physical rather than the localized path to your home directory. For instance on macOS configured for the Swedish language /Users/myusername will be the physical path but /Användare/myusername is the localized path that is actually shown in the user interface. The same is true on Windows where the directories would be C:\Users\myusername and C:\Användare\myusername respectively. If attempting to enter the localized path for any directory-related setting, ES-DE will not be able to find it. But it's always possible to use the tilde `~` symbol when referring to your home directory, which ES-DE will expand to the physical location regardless of what language you have configured for your operating system. If you're using an English-localized system, this whole point is irrelevant as the physical and localized paths are then identical. +**Note:** As of ES-DE v1.2 there is no internationalization support, which means that the application will always require the physical rather than the localized path to your home directory. For instance on macOS configured for the Swedish language /Users/myusername will be the physical path but /Användare/myusername is the localized path that is actually shown in the user interface. The same is true on Windows where the directories would be C:\Users\myusername and C:\Användare\myusername respectively. If attempting to enter the localized path for any directory-related setting, ES-DE will not be able to find it. But it's always possible to use the tilde `~` symbol when referring to your home directory, which ES-DE will expand to the physical location regardless of what language you have configured for your operating system. If you're using an English-localized system, this whole point is irrelevant as the physical and localized paths are then identical. -It's also possible to override the home directory path using the --home command line option, but this is normally required only for very special situations so we can safely ignore that option for now. +It's possible to override the home directory path using the --home command line option, but this is normally required only for very special situations so we can safely ignore that option for now. -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. The systems configuration file can be customized, as described in the next section. +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 some 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. There's an application log file created in the ES-DE home directory named `es_log.txt`, please refer to this in case of any issues as it should hopefully provide information on what went wrong. Starting ES-DE with the --debug flag provides even more detailed information. @@ -116,6 +141,8 @@ genesis: Sega Genesis gx4000: Amstrad GX4000 ``` +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 GameCube system in the example above would be present in the custom systems configuration file, the system would be shown as _gc (custom system)_ instead of simply _gc_. 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. + Note that neither the systeminfo.txt files or the systems.txt file are needed to run ES-DE, they're only generated as a convenience to help with the setup. There will be a lot of directories created if using the es_systems.xml file bundled with the installation, so it may be a good idea to remove the ones you don't need. It's recommended to move them to another location to be able to use them later if more systems should be added. For example a directory named _DISABLED could be created inside the ROMs folder (i.e. ~/ROMs/_DISABLED) and all game system directories you don't need could be moved there. Doing this reduces the application startup time as ES-DE would otherwise need to scan for game files for all these systems. @@ -124,9 +151,39 @@ There will be a lot of directories created if using the es_systems.xml file bund _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._ +## Disabling game systems + +The way ES-DE works is that it will always try to load any system for which there are game files available, so to disable a system it needs to be hidden from ES-DE. This is easily accomplished by renaming the game directory to something that is not recognized, for example changing `~/ROMs/c64` to `~/ROMs/c64_DISABLED`. Another approach is to create a subdirectory named DISABLED (or whatever name you prefer that is not matching a supported system) in the ROMs directory and move the game folder there, such as `~/ROMs/DISABLED/c64`. This makes it easy to disable and re-enable game systems in ES-DE. Note that the gamelist and any game media files are retained while the system is disabled so this is an entirely safe thing to do. + + +## Using the Steam release of RetroArch + +On Windows it's no problem to use the Steam release of RetroArch although you may have to add the installation location manually to your Path environment variable. By default the following locations will be searched: +``` +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 +``` + +If you have installed RetroArch at another location, simply start the Settings application, search for _path_ in the _Find a setting_ field and choose _Edit environment variables for your account_. Edit the _Path_ variable and add the directory where RetroArch is installed. This is required as there is no apparent way for ES-DE to find where RetroArch has been installed by the Steam application. + +Unfortunately on Linux it's at the moment not possible to run the Steam release of RetroArch due to technical reasons. This RetroArch release runs as a type of container which can't be executed from ES-DE while correctly passing the necessary core and game options. Similarly it's not possible to launch RetroArch via the Steam application either as there seems to be a bug in Steam or RetroArch that prevents blankspaces from being present in game ROM files when passed as arguments (this works fine on Windows so it's definitely a Linux-specific issue and as well the same problem occurs if attempting to manually enter the launch command from a terminal window). + + ## Specific notes for macOS -On macOS, the first time you launch a game from within ES-DE, the operating system will present you with a security option with the following description: +The main issue with macOS is lack of emulator support and missing (or buggy) controller drivers. + +As Apple refuses to support Vulkan some emulators are simply not available, and other emulators exist but have not been updated for macOS in recent years. As well many emulators are available for download but are not codesigned or notarized which require you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, then go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button in the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions. + +Lack of controller support is another issue, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot. + +ES-DE currently ships only as an x86/Intel binary so if you run it on an M1 Mac, you need to also install x86 versions of all emulators including RetroArch. That's also the case for any emulators installed via Homebrew. The reason this is needed is that the Rosetta 2 translation environment does not support mixing of ARM and x86 architectures. + +Another macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" must be enabled or ES-DE will not be able to switch to the emulator window. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. It's currently unclear if other emulators than RetroArch are affected by this issue, at least until now none of the other emulators tested have displayed this behavior. The standalone PlayStation 2 emulator PCSX2 has a similar issue but that seems to be GPU driver related and is problematic also on other operating systems. If using this emulator you need to manually switch to the PCSX2 window using Command + Tab after launching the game from ES-DE. + +The first time you launch a 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.` @@ -134,21 +191,73 @@ If you don't allow this, you will not be able to place system BIOS ROMs in the R If you accidentally refused ES-DE the folder access, you can fix this by opening _System Preferences_, selecting _Security & Privacy_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _EmulationStation Desktop Edition_. -Another macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" must be enabled or ES-DE will not be able to switch to the emulator window. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. It's currently unclear if other emulators than RetroArch are affected by this issue. +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. -Another problem on macOS 11 Big Sur (and possibly older OS versions) is that when connecting a Sony DualShock 4 controller either via Bluetooth or using a USB cable, two separate controller devices are registered in parallel. This is a bug in either macOS or the DualShock driver and it makes it seem as if ES-DE is registering double button presses when actually two separate controller devices are generating identical input. A workaround if using Bluetooth mode is to plug in the USB cable just after connecting the controller, wait a second or two and then remove the cable again. This will remove the cabled device, leaving only the Bluetooth device active. Another workaround is to enable the setting _Only accept input from first controller_ in the ES-DE input device settings. The reason why this bug may not be visible in some other games and applications is that ES-DE enables and auto-configures all connected controllers. +Another problem on macOS 11 Big Sur (and possibly older OS versions) is that when connecting a Sony DualShock 4 controller either via Bluetooth or using a USB cable, two separate controller devices are registered in parallel. This is a bug in either macOS or the DualShock driver and it makes it seem as if ES-DE is registering double button presses when actually two separate controller devices are generating identical input. A workaround if using Bluetooth mode is to plug in the USB cable just after connecting the controller, wait a second or two and then remove the cable again. This will remove the cabled device, leaving only the Bluetooth device active. Another workaround is to enable the setting _Only accept input from first controller_ in the ES-DE input device settings. The reason why this bug may not be visible in some other games and applications is that ES-DE enables and auto-configures all connected controllers. The issue appears to be resolved in macOS Monterey. -## Customizing the systems configuration file +## Specific notes for Raspberry Pi -The `es_systems.xml` file 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 a customized file is needed, this should instead be placed in the `custom_systems` folder in the ES-DE home directory, i.e. `~/.emulationstation/custom_systems/es_systems.xml`. You can find information on the file structure and how to adapt the configuration in the [INSTALL.md](INSTALL.md#es_systemsxml) document. +ES-DE on the Raspberry Pi requires a desktop environment, or more specifically a window manager and a sound server (like PulseAudio or PipeWire). There are no plans to add support for direct hardware access to the framebuffer or to ALSA. If you want to use your Raspberry Pi as an appliance, take a look at [RetroPie](https://retropie.org.uk), [Recalbox](https://www.recalbox.com) or [Batocera](https://batocera.org) instead. + +The Raspberry Pi 4/400 is the minimum recommended version and earlier boards have not been tested. The GPU memory should be set to at least 256 MiB using `raspi-config` and the GL driver must be set to `GL (Fake KMS)` or the performance will be horrible. On Raspberry Pi OS 11 the KMS option is enabled by default. + +In general, 720p works fine with the RPi 4, and 1080p is tolerable but not really a nice and smooth experience. Due to the relative weakness of the Rasperry Pi GPU, the video scanline rendering options for the screensaver and media viewer have been disabled (they're enabled by default on all other platforms). These options can be re-enabled via the menu if you don't mind lower video framerates. + +Both the 32-bit (armv7l) and 64-bit (aarch64) versions of Raspberry Pi OS are supported. Although the 64-bit version of ES-DE actually runs much better than the 32-bit version it's still generally recommended to go for the 32-bit OS for now. The reason is that the Raspberry Pi Foundation has still not officially released the 64-bit version of Raspberry Pi OS so it's somewhat of a beta with some functionality apparently broken. As well there seems to be issues with installing RetroArch cores on aarch64 so you would probably need to compile them from source code. + +At the time of writing the Snap version of RetroArch appears broken and won't start on the 32-bit OS, so the Flatpak version would have to be installed. That is accomplished using these commands: + +``` +sudo apt install flatpak +sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo +``` + +Following this you need to reboot, and then run this command: + +``` +sudo flatpak install retroarch +``` + +This will download and install a few hundred megabytes of data as there are some dependencies. Unfortunately the Flatpak environment does not seem to be properly setup so you will have to launch RetroArch like this to install your emulator cores: + +``` +/var/lib/flatpak/exports/bin/org.libretro.RetroArch +``` + +ES-DE will however detect and launch RetroArch correctly. + +If the Snap version of RetroArch will be fixed in the future, it can be installed like this: + +``` +sudo apt-get install snapd +sudo snap install retroarch +sudo snap connect retroarch:removable-media +``` + +(The last line is only required if you intend to place your ROMs on an external device such as a USB-connected hard drive.) + +On Raspberry Pi OS 10 Sony DualShock 4 controllers have problems with some button presses that don't register correctly. The issue appears resolved on Raspberry Pi OS 11. + +On Raspberry Pi OS 11 there are various graphics issues and sometimes the application or emulator completely freezes which requires a power cycle of the machine. This is seemingly due to GPU driver bugs and we can only wait for OS updates to address these problems. These issues have not been encountered on Raspberry Pi OS 10 so for now this older OS version is recommended. + + +## Game system customizations + +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, i.e. `~/.emulationstation/custom_systems/es_systems.xml`. + +Although it's possible to make a copy of the bundled configuration file, to modify it and then place it in this directory, that is not how the system customization is designed to be done. Instead the intention is that the file in `custom_systems` complements the bundled configuration, meaning only systems that are to be customized should be included. + +For example you may want to replace the emulator launch command, modify the full name or change the supported file extensions for a single system. In this case it wouldn't make sense to copy the complete bundled file and just apply these minor modifications, instead an es_systems.xml file only containing the configuration for that single system should be placed in the custom_systems directory. + +The instructions for how to customize the es_systems.xml file can be found in [INSTALL.md](INSTALL.md#es_systemsxml). There you can also find some examples of custom files that you can copy into ~/.emulationstation/custom_systems/ and modify as required. ## Migrating from other EmulationStation forks **IMPORTANT!!! IMPORTANT!!! IMPORTANT!!!** -ES-DE is designed to be backward compatible to a certain degree, that is, it should be able to read data from other/previous EmulationStation versions such as the RetroPie fork. But the opposite is not true and it's a one-way ticket for your gamelist.xml files and your custom collection files when migrating to ES-DE as they will be modified in ways that previous ES versions will see as data loss. For instance ES-DE does not use image tags inside the gamelist.xml files to find game media but instead matches the media to the names of the game/ROM files. So it will not save any such tags back to the gamelist files during updates, effectively removing the display of the game media if the files are opened in another ES fork. +ES-DE is designed to be backward compatible to a certain degree. That is, it should be able to read data from other/previous EmulationStation versions such as the RetroPie fork. But the opposite is not true and it's a one-way ticket for your gamelist.xml files and your custom collection files when migrating to ES-DE as they will be modified in ways that previous ES versions will see as data loss. For instance ES-DE does not use image tags inside the gamelist.xml files to find game media but instead matches the media to the names of the game/ROM files. So it will not save any such tags back to the gamelist files during updates, effectively disabling the game media if the files are opened in another ES fork. Due to this, always make backups of at least the following directories before testing ES-DE for the first time: @@ -157,38 +266,40 @@ Due to this, always make backups of at least the following directories before te ~/.emulationstation/collections/ ``` -If migrating from Batocera or Recalbox, be aware that ES-DE follows the RetroPie naming conventions for system folders. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera and Recalbox has the `sg1000` system name, but is `sg-1000` in RetroPie and ES-DE. See the [Supported game systems](USERGUIDE.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE. This issue also means that theme sets that were written or adapted specifically for Batocera or Recalbox may display unthemed systems in ES-DE. All RetroPie theme sets should however work fine (of course assuming that all your systems are actually supported by the theme). +It's also strongly adviced to not rename an old es_settings.cfg file to es_settings.xml for use in ES-DE. Although this has been tested to some extent, it may cause undefined behavior. + +If migrating from Batocera or Recalbox, be aware that ES-DE follows the RetroPie naming conventions for game systems. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera and Recalbox has the _sg1000_ system name, but is _sg-1000_ in RetroPie and ES-DE. See the [Supported game systems](USERGUIDE.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE. This issue also means that theme sets that were written or adapted specifically for Batocera or Recalbox may display unthemed systems in ES-DE. All RetroPie theme sets should however work fine (of course assuming that all your systems are actually supported by the theme set). ## Running on high resolution displays -ES-DE fully supports high resolution displays such as 4K, 6K, 1440p, ultrawide monitors etc. But some emulators such as RetroArch will also run using the same resolution which may cause performance problems on slower machines or when using resource intensive shaders. Although some emulator cores will have options to set their internal resolution, they still need to be scaled up to the screen resolution. On Unix it's possible to start ES-DE with the `--resolution` option to set a lower screen resolution (this will also affect the emulators) but this is not really recommended as it's highly dependent on well-written graphics drivers for proper behavior. +ES-DE fully supports high resolution displays such as 1440p, 4K, 6K, 8K, ultrawide monitors etc. But many emulators (e.g. RetroArch) will also run using the same resolution which may cause performance problems on slower machines or when using resource intensive shaders. Although some emulator cores will have options to set their internal resolution, they still need to be scaled up to the screen resolution. -A better approach is to use the custom event scripts functionality to set a temporary resolution upon launching a game that will be reverted when returning to ES-DE. Such a setup is detailed in [INSTALL.md](INSTALL.md#custom-event-scripts) for Unix, but should hopefully be possible to implement similarly on macOS and Windows. +A solution to this is to use the custom event scripts functionality to set a temporary resolution upon launching a game that will be reverted when returning to ES-DE. Such a setup is detailed in [INSTALL.md](INSTALL.md#custom-event-scripts) for Unix, but should hopefully be possible to implement similarly on Windows. When going for this setup it's important that the setting _Run in background (while game is launched)_ is disabled or ES-DE may not be able to correctly switch to the emulator window when launching games. + +On macOS it's problematic to change screen resolutions on the fly or on a per-application basis as Apple has seemingly disabled most of this functionality in recent operating system releases. The only real option here is to lower the display resolution prior to launching ES-DE. ## Input device configuration -ES-DE automatically configures the keyboard and any connected controllers using default button mappings, and normally no additional setup is required. But if you would like to apply custom button mappings for your devices, you can run the `Configure keyboard and controllers` tool from the `Input device settings` entry on the main menu. +ES-DE automatically configures the keyboard and any connected controllers using default button mappings, and normally no additional setup is required. But if you would like to apply custom button mappings for your devices or if you have an unusual device which isn't automatically configured, you can run the _Configure keyboard and controllers_ tool from the _Input device settings_ entry on the main menu. You can also force a run of this tool directly on startup via the command line argument `--force-input-config`. -The actual procedure to map the inputs should be self-explanatory, just follow the on-screen instructions. But note that custom button mappings will not change the help prompts. +The actual procedure to map the inputs should be self-explanatory, just follow the on-screen instructions. Note that custom button mappings will not change the help prompts. 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 the mappings by deleting or renaming the file ~/.emulationstation/es_input.xml. -If you experience double button presses with your DualShock 4 controller on macOS, please read about the workaround for this issue in the [Known issues](CHANGELOG.md#known-issues) section of the changelog. - ## System view (main screen) When starting ES-DE with the default settings, you will see the System view first. From here you can navigate your game systems and enter their respective gamelists. -Depending on the theme, the system navigation carousel can be either horizontal or vertical. The default theme rbsimple-DE provides horizontal navigation, i.e. you browse your systems by scrolling left or right. +Depending on the theme, the system navigation carousel can be horizontal, vertical or displayed as a wheel. The default theme rbsimple-DE provides horizontal navigation, i.e. you browse your systems by scrolling left or right. -The game systems are sorted by their full names, as defined in the es_systems.xml file. +The game systems are sorted by their full names by default, as defined in the es_systems.xml file. It's however possible to set a custom sortname per system, as explained in the [INSTALL.md](INSTALL.md#es_systemsxml) document. ![alt text](images/es-de_system_view.png "ES-DE System View") _The **System view** is the default starting point for the application, it's here that you browse through your game systems._ @@ -204,9 +315,11 @@ Note that the Video view style requires that the theme supports it. If not, the It's possible to manually set a specific gamelist view style in the UI settings entry of the main menu, but this is applied globally regardless of what media files are available per game system. The manual setting also overrides the theme-supported view styles which has the potential of making ES-DE very ugly indeed if the theme does not support the selected view style. -In addition to the styles just described, there is a **Grid** view style as well, but as of ES-DE version 1.1 this is highly experimental and its use is not recommended. Future versions may update this style to a more useful state or it may be removed entirely. +In addition to the styles just described, there is a **Grid** view style as well, but as of ES-DE version 1.2 this does not work correctly and is set as deprecated. Future ES-DE releases will remove this style entirely. -If the theme supports it, there's a gamelist information field displayed in the gamelist view, showing the number of games for the system (total and favorites) as well as a folder icon if a folder has been entered. When applying any filters to the gamelist, the game counter is replaced with the amount of games filtered, as in 'filtered / total games', e.g. '19 / 77'. If there are game entries in the filter result that are marked not to be counted as games, the number of such files will be indicated as 'filtered + filtered non-games / total games', for example '23 + 4 / 77' indicating 23 normal games, 4 non-games out of a total of 77. Due to this approach it's theoretically possible that the combined filtered game amount exceeds the number of counted games in the collection, for instance '69 + 11 / 77'. This is not considered a bug and is so by design. This gamelist information field functionality is specific to EmulationStation Desktop Edition so older themes will not support this. +If the theme supports it, there's a gamelist information field displayed in the gamelist view, showing the number of games for the system (total and favorites) as well as a folder icon if a folder has been entered. When applying any filters to the gamelist, the game counter is replaced with the amount of games filtered, as in 'filtered / total games', e.g. '19 / 77'. If there are game entries in the filter result that are marked not to be counted as games, the number of such files will be indicated as 'filtered + filtered non-games / total games', for example '23 + 4 / 77' indicating 23 normal games, 4 non-games out of a total of 77. Due to this approach it's theoretically possible that the combined filtered game amount exceeds the number of counted games in the collection, for instance '69 + 11 / 77'. This is not considered a bug and is so by design. This gamelist information field functionality is specific to ES-DE so older themes will not support this. + +Another feature which requires theme support is **Badges**, which is a set of icons displaying the status for various metadata fields. The currently supported badge types are _favorite, completed, kidgame, broken, controller_ and _alternative emulator_. If any of the first four metadata fields have been set for a game, their corresponding badges will be displayed. If a game-specific controller has been selected via the metadata editor, the corresponding controller badge will be shown, and if an alternative emulator has been selected for the specific game, that badge will be displayed. Setting an alternative emulator system-wide will not display this badge as it's only intended to indicate game-specific overrides. As well, disabling the option _Enable alternative emulators per game_ will also hide the alternative emulator badges. ![alt text](images/es-de_gamelist_view.png "ES-DE Gamelist View") _The **Gamelist view** is where you browse the games for a specific system._ @@ -223,7 +336,7 @@ These modes mandate the functionalty provided by the application in the followin * Full - This is the default mode which enables all functionality. * Kiosk - The main menu will be severely restricted, only displaying the entry to change the audio volume. The game options menu will be restricted as well, removing the metadata editor and the ability to modify custom game collections. And finally the ability to flag or unflag games as favorites will be removed. Apart from this all games will be playable. -* Kid - Only games marked as being suitable for children will be displayed (this flag is set manually per game using the metadata editor). Additionally, the game options menu is disabled, as well as the screensaver controls and the ability to flag and unflag games as favorites. There is also a separate option available to enable or disable the main menu when in Kid mode, see **Enable menu in kid mode** for additional information. +* Kid - Only games marked as being suitable for children will be displayed (this flag is set manually per game using the metadata editor). Additionally, the game options menu is disabled, as well as the screensaver controls and the ability to flag and unflag games as favorites. There is also a separate option available to enable or disable the main menu when in Kid mode, see _Enable menu in kid mode_ for additional information. There is an unlock code available to revert to the Full mode from the Kiosk or Kid mode, as is described when changing this setting from the main menu. By default the button sequence is **Up, Up, Down, Down, Left, Right, Left, Right, B, A** (or equivalent buttons if an Xbox controller is not used). Either the keyboard or a controller can be used to input the passkey sequence, but it can't be entered when a menu is open. @@ -235,7 +348,7 @@ The application can also be forced into any of the three modes via the command l There is a help system available throughout the application that provides an overview of the possible actions and buttons that can be used. But some general actions are never shown, such as the ability to quick jump in gamelists, menus and text input fields using the shoulder and trigger buttons. It's also possible to disable the help system using a menu option for a somewhat cleaner look. ![alt text](images/es-de_folder_support.png "ES-DE Help System") -_The help system is displayed at the bottom of the screen, showing the various actions currently available._ +_The help system is displayed at the bottom of the screen, indicating the various actions currently available._ ## General navigation @@ -282,7 +395,7 @@ Jumps to a random game or system depending on whether pressed when in the system **A button**\ _(Enter)_ -Opens gamelists from the system view, launches games, selects menu entries etc. +Opens gamelists from the system view, launches games, enters folders, selects menu entries etc. **B button**\ _(Back key)_ @@ -299,9 +412,9 @@ _(Insert on Unix and Windows, F13 on macOS)_ Marks games as favorites in the gamelist view (if the _Enable toggle favorites button_ option has been enabled). Used by some other minor functions as explained by the help system and/or this guide. -**F4 (keyboard only)** +**F4 (keyboard only)** _Could alternatively be Alt + F4, Alt + Q or Command + Q_ -Quits the application immediately. +Quits the application. This key combination can be changed using the _Exit button combo_ menu option described later in this document. ## Getting your games into ES-DE @@ -315,17 +428,20 @@ Let's start with the simple scenario of a single ROM file per game, which is the The supported file extensions are listed in [unix/es_systems.xml](resources/systems/unix/es_systems.xml), [macos/es_systems.xml](resources/systems/macos/es_systems.xml) and [windows/es_systems.xml](resources/systems/windows/es_systems.xml) but if you generated the game system directories on first application startup, there will be a file named systeminfo.txt in each game system directory that includes the list of supported file extensions. -Here is the snippet from the unix/es_systems.xml file: +Here is a snippet from unix/es_systems.xml: -``` +```xml - nes - Nintendo Entertainment System - %ROMPATH%/nes - .nes .NES .unf .UNF .unif .UNIF .7z .7Z .zip .ZIP - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/nestopia_libretro.so %ROM% - nes - nes + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .unf .UNF .unif .UNIF .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/nestopia_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/fceumm_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/mesen_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/quicknes_libretro.so %ROM% + nes + nes ``` @@ -335,13 +451,11 @@ It's highly recommended to use filenames that are corresponding to the full name **Note:** Symlinks are supported for both ROM directories and individual game files, but make sure to not symlink between files within the same system directory or there may be undefined application behavior when scraping, launching games etc. -The default game directory folder is ~/ROMs. On Unix this defaults to /home/\/ROMs, on macOS /Users/\/ROMs and on Windows C:\Users\\\ROMs\. 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 Unix this defaults to /home/\/ROMs, on macOS /Users/\/ROMs and on Windows C:\Users\\\ROMs\. 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. -If ES-DE can't find any game files during startup, an error message will be displayed with the option to change the ROM directory path. +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`. -Assuming the default ROM directory is used, we need to create a directory corresponding to the \ tag in es_systems.xml, in this example it's `nes`. - -This would look something like the following: +So this would look something like the following: ``` /home/myusername/ROMs/nes # On Unix @@ -359,7 +473,7 @@ Then simply copy your game ROMs into this folder, and you should end up with som **Note:** These directories are case sensitive on Unix, so creating a directory named `Nes` instead of `nes` won't work. -That's it, start ES-DE and the NES game system should be populated. You can now scrape information and media for the games, and assuming you've setup RetroArch correctly with the Nestopia UE core, you can launch the games. +That's it, start ES-DE and the NES game system should be populated. You can now scrape information and media for the games, and assuming you've setup RetroArch correctly with the Nestopia UE core, you can launch the games. If you instead prefer to use any of the three alternative emulators listed above (FCEUmm, Mesen or QuickNES) you can install one of these cores instead and change your emulator preference using the _Alternative emulators_ interface in the _Other settings_ menu. Note that alternative emulators are only available for some game systems. ### Multiple game files installation @@ -392,9 +506,31 @@ LNINJA2B.D64 It's of course also possible to skip this type of directory structure and put all the games in the root folder, but then there will be multiple entries for the same game which is not so tidy. Another approach would be to put all the files in the root folder and then hide the game files, showing only the .m3u playlist files. ES-DE is flexible so do whatever makes most sense for the situation. -When setting up games in this fashion, it's recommended to scrape the directory in addition to the .m3u file as it looks nicer to see the metadata for the games also when browsing the folders. ES fully supports scraping folders, although some metadata is not included for folders for logical reasons. If you only scrape the folders and not the actual game files, it may look somehow ok when browsing, but when a game is part of a collection, the metadata will be missing there. This includes the **Last played** and **All games** collections for instance. Also note that while it's possible to mark a folder as a favorite, it will never be part of a collection, such as **Favorites**. +When setting up games in this fashion, it's recommended to scrape the directory in addition to the .m3u file as it looks nicer to see the metadata for the games also when browsing the folders. ES-DE fully supports scraping folders, although some metadata is not included for logical reasons (and while it's possible to mark a folder as favorite, it will not be part of the Favorites collection as only files can be part of collections). If you only scrape the folders and not the actual game files, it may look somehow ok when browsing the gamelist, but when such a game is part of a collection, the metadata will be missing there. This includes the _All games, Favorites_ and _Last played_ collections but also any custom collection where the game has been added. -It's also recommended to use the metadata editor to set the flags **Exclude from game counter** and **Exclude from automatic scraper** for the actual game files so that they are not counted for the game statistics display and not scraped when running the multi-scraper. If you don't want to hide the individual game files but still want a cleaner look, it's also possible to set the flag **Hide metadata fields** for the game files. +It's also recommended to use the metadata editor to set the flags _Exclude from game counter_ and _Exclude from automatic scraper_ for the actual game files so that they are not counted for the game statistics display and not scraped when running the multi-scraper. If you don't want to hide the individual game files but still want a cleaner look, it's also possible to set the flag _Hide metadata fields_ for the game files. + +### Directories interpreted as files + +There is a very special use case which ES-DE supports where you can interpret a directory as if it were a file. This is used in some cases such as for the PlayStation 3 emulator RPCS3 where a directory rather than a file is passed as an argument to the emulator during game launch. + +If you add the extension that is configured for the emulator to a directory name it will be loaded as if it was a file when ES-DE starts up. + +As an example using the Sony PlayStation 3 system, the extension in es_systems.xml is .ps3dir so this is what such a directory could look like: +``` +~/ROMs/ps3/Gran Turismo 5.ps3dir +``` + +It's also possible to combine these types of special directories with normal directories, for a setup like this: +``` +~/ROMs/ps3/racing/Gran Turismo 5.ps3dir +``` + +For all intents and purposes the `Gran Turismo 5.ps3dir` directory will now be considered a file within ES-DE, i.e. all file metadata fields can be used and the directory can be part of both automatic and custom collections. + +The only exception is that the _Delete_ button in the metadata editor will be disabled for these special types of entries as ES-DE does not support deletion of directories for safety reasons. + +When setting up a directory like this, make sure to not name any files or folders inside the base directory using the same extension as that will force the base directory to be processed normally, breaking the functionality. ### Special game installation considerations @@ -406,7 +542,7 @@ For all the supported MAME variants as well as Final Burn Alpha/FinalBurn Neo an For instance `topgunnr.7z` will be expanded to `Top Gunner`. -This is required by the TheGamesDB scraper where the expanded file names are used for game searches. (Screenscraper natively supports searches using the MAME names). It's also quite nice to have the gamelist populated with the expanded game names even before any scraping has taken place. +This is required by the TheGamesDB scraper where the expanded filenames are used for game searches. (Screenscraper natively supports searches using the MAME names). It's also quite nice to have the gamelist populated with the expanded game names even before any scraping has taken place. #### Nintendo Switch @@ -424,7 +560,7 @@ What ES-DE will do is to look for _yuzu.AppImage_ in the system PATH as well as ~/bin/yuzu.AppImage ``` -When downloading the AppImage from [https://yuzu-emu.org](https://yuzu-emu.org) it will be named something like `yuzu-20210621-45d9504ea.AppImage`, just rename this to yuzu.AppImage and everything should work correctly. +When downloading the AppImage from [https://yuzu-emu.org](https://yuzu-emu.org) it will be named something like `yuzu-20210621-45d9504ea.AppImage`, just rename this to yuzu.AppImage and everything should work correctly. Another approach is to make a symlink named yuzu.AppImage, either way will work fine. Note that the name is case sensitive, so _yuzu.appimage_ will not be found by ES-DE. @@ -432,11 +568,76 @@ For Windows, ES-DE will look for _yuzu.exe_ in the system Path as well as in the Apart from the potential difficulty in locating the emulator binary, there are some special configuration steps required for the emulator, refer to the Yuzu website for more information about this. +#### Sony PlayStation 3 + +The RPCS3 emulator is only available on Linux and Windows and requires a bit of special setup. + +On Windows RPCS3 does not ship with an installer but rather as a zip file that contains all the application files. You will need to unzip the content and manually add that directory to your environment Path variable so that ES-DE will be able to find the emulator binary rpcs3.exe. + +On Linux RPCS3 is shipped as a Snap package, Flatpak package or AppImage. If installed as a Snap or Flatpak or if built from source code, ES-DE should be able to easily locate the emulator binary. + +But if using the AppImage it's a bit problematic as there are no standard directories where these files are located. + +What ES-DE will do is to look for _rpcs3.AppImage_ in the system PATH as well as in the following locations: + +``` +~/Applications/rpcs3.AppImage +~/.local/bin/rpcs3.AppImage +~/bin/rpcs3.AppImage +``` + +When downloading the AppImage from [https://rpcs3.net](https://rpcs3.net) it will be named something like `rpcs3-v0.0.19-13103-cc21d1b3_linux64.AppImage`, just rename this to rpcs3.AppImage and everything should work correctly. Another approach is to make a symlink named rpcs3.AppImage, either way will work fine. + +Note that the name is case sensitive, so _rpcs3.appimage_ will not be found by ES-DE. + +As for the game installation on both Windows and Linux, you need to retain the directory structure of the Blu-ray disc or the directory created by installing the .pkg file. Each directory needs to be renamed by adding the .ps3dir extension, which will make ES-DE interpret the directory as if it were a file and pass that directory to the emulator when launching a game. + +Here's an example of what a Blu-ray disc directory could look like: +``` +~/ROMs/ps3/Gran Turismo 5.ps3dir +``` + +It's possible to create a symlink instead, and in this case only the symlink needs to have the .ps3dir extension. + +Here's how to do it on Linux: +``` +cd ~/ROMs +ln -s ~/games/PS3/Gran\ Turismo\ 5 Gran\ Turismo\ 5.ps3dir +``` + +And here's how to do it on Windows (you need to run this as Administrator): +``` +cd C:\Users\Myusername\ROMs\ps3 +mklink /D "Gran Turismo 5.ps3dir" "C:\Games\PS3\Gran Turismo 5" +``` + +If you've installed a .pkg using RPCS3 you can either symlink to the installation directory or move the directory to the ROMs folder. Also in this case the directory (or symlink) needs to be named with the .ps3dir extension. + +An example on Linux: +``` +cd ~/ROMs +ln -s ~/.config/rpcs3/dev_hdd0/game/NPUA30002 Bejeweled2.ps3dir +``` + +This example is for the AppImage version of RPCS3, for the Snap or Flatpak versions, the installed games will be located in a different directory. + +Here's how to achieve the same on Windows: +``` +cd C:\Users\Myusername\ROMs\ps3 +mklink /D "Bejeweled2.ps3dir" "C:\Emulators\RPCS3\dev_hdd0\game\NPUA30002" +``` + +Of course you can name the symlink anything you want as long as it has the .ps3dir extension. + +Apparently some specific games have issues launching when using symlinks so you need to test and experiment with what works for your collection. + +Apart from this you need to install the PS3 system firmware to use the emulator, but that is described in the RPCS3 documentation. + #### Commodore Amiga There are multiple ways to run Amiga games, but the recommended approach is to use WHDLoad. The best way is to use hard disk images in `.hdf` or `.hdz` format, meaning there will be a single file per game. This makes it just as easy to play Amiga games as any console with game ROMs. -An alternative would be to use `.adf` images as not all games may be available with WHDLoad support. For this, you can either put single-disk images in the root folder or in a dedicated adf directory, or multiple-disk games in separate folders. It's highly recommended to create `.m3u` playlist files for multi-disc images as described earlier. +An alternative would be to use `.adf` images as not all games may be available with WHDLoad support. For this, you can either put single-disc images in the root folder or in a dedicated adf directory, or multiple-disk games in separate folders. It's highly recommended to create `.m3u` playlist files for multi-disc images as described earlier. Here's an example of what the file structure could look like: @@ -454,15 +655,15 @@ Advanced topics such as the need for the Amiga Kickstart ROMs to run Amiga games #### DOS / PC -The DOS (and PC) platform uses the DOSBox emulator and the recommended approach here is to keep the directory structure intact, just as if running the game on a real DOS computer. So this means one folder per game in ES-DE. It's also recommended to set the metadata field **Count as game** to off for all files but the actual file used to launch the game, i.e. the binary or the .bat batch file. This is done so that the game counter correctly reflects the number of games you have installed. It's also possible to mark files and subdirectories as hidden to avoid seeing them in ES-DE. Both of these fields can be set using the metadata editor. +The DOS (and PC) platform uses the DOSBox emulator and the recommended approach here is to keep the directory structure intact, just as if running the game on a real DOS PC. So this means one folder per game in ES-DE. It's also recommended to set the metadata field _Count as game_ to off for all files but the actual file used to launch the game, i.e. the binary or the .bat batch file. This is done so that the game counter correctly reflects the number of games you have installed. It's also possible to mark files and subdirectories as hidden to avoid seeing them in ES-DE. Both of these fields can be set using the metadata editor. -Apart from this, DOS games should work the same as any other system. The game folders can be scraped so that it looks nice when browsing the list of games, but make sure to also scrape the files used to launch the games or otherwise the entries in the collections **Last played**, **Favorites** and **All games** as well as any custom collections will miss the game metadata and game media. If you don't have these collections activated, then this can of course be skipped. +Apart from this, DOS games should work the same as any other system. The game folders can be scraped so that it looks nice when browsing the list of games, but make sure to also scrape the files used to launch the games or otherwise the entries in the collections _All games, Favorites_ and _Last played_ as well as any custom collections will miss the game metadata and game media. If you don't have these collections activated, then this can of course be skipped. #### Ports Ports are not really executed using emulators, but are rather applications running natively on the operating system. The easiest way to handle these is to add a simple shell script or batch file where you can customize the exact launch parameters for the game. -It's of course possible to add these as single files to the root folder, but normally it's recommended to setup a separate folder per game as there may be more than a single file available per game. You very often want to have easy access to the game setup utility for instance. +It's possible to add these files directly to the root folder, but normally it's recommended to setup a separate directory per game as there may be more than a single file required. For instance you often want to have easy access to the game setup utility which may have to be executed separately from the actual game. Here's an example for setting up Chocolate-Doom, GZDoom and DarkPlaces on Unix: @@ -546,7 +747,7 @@ As an alternative, you can add the Lutris games to the Ports game system, if you #### Steam -**Note:** Launching Steam games currently has some limitations such as missing error messages when a game fails to start as well as missing game output logging. ES-DE also needs to keep running in the background when launching Steam games, which has some minor side effects. +**Note:** Launching Steam games currently has some limitations such as missing error messages when a game fails to start as well as missing game output logging. ES-DE also needs to keep running in the background for technical reasons, which has some minor side effects. As for the setup, it's recommended to place shell scripts/batch files directly in the steam system directory, with the filenames of these scripts corresponding to the game names. @@ -565,7 +766,7 @@ And on macOS with the filename `Broforce.sh`: And finally on Windows with the filename `Broforce.bat`: ``` -"c:\Program Files (x86)\Steam\steam.exe" steam://rungameid/26800 +"c:\Program Files (x86)\Steam\steam.exe" steam://rungameid/274190 ``` The game ID can be found by going to [https://store.steampowered.com](https://store.steampowered.com) and searching for a game. The Broforce example would have an URL such as this: @@ -584,10 +785,12 @@ grep steam ~/.local/share/applications/*desktop | grep rungameid This of course assumes that you have menu entries setup for your Steam games. +To greatly simplify this setup, automatic Steam library import is planned for a future ES-DE release. + ## RetroArch setup -ES-DE is a game browsing frontend and does not provide any emulation by itself. It does however come preconfigured for use with emulators as setup in the `es_systems.xml` file. By default it's primarily setup for use with [RetroArch](https://www.retroarch.com) but this can be modified if needed. If you're interested in customizing your es_systems.xml file, please refer to the [INSTALL.md](INSTALL.md#es_systemsxml) document which goes into details on the structure of this file and more advanced configuration topics in general. +ES-DE is a game browsing frontend and does not provide any emulation by itself. It does however come preconfigured for use with emulators as setup in the `es_systems.xml` file. By default it's primarily setup for use with [RetroArch](https://www.retroarch.com) but this can be modified if needed. If you're interested in customizing your es_systems.xml file, please refer to the [INSTALL.md](INSTALL.md#es_systemsxml) document which goes into detail on the structure of this file and more advanced configuration topics in general. Installation and configuration of RetroArch and other emulators is beyond the scope of this guide, but many good resources can be found online on how to do this. @@ -595,7 +798,12 @@ Keep in mind that ES-DE will not install any RetroArch cores, you need to do thi A general recommendation regarding installation on Linux is to try to avoid the RetroArch releases included in the OS repositories as they're usually quite limited with regards to the number of available cores, and they're usually older versions. Instead go for either the Snap, Flatpak or AppImage distributions or build from source. -The default es_systems.xml file is paired with a file named es_find_rules.xml which tries to find the emulators and cores using some predefined rules. For Windows this should normally just work, and for macOS too as long as RetroArch is installed at the default location /Applications/RetroArch.app. For Unix/Linux there is one exception that is problematic which is AppImages as there is no real standardized directory for storing these images. ES-DE will look for the RetroArch AppImage in the following locations in addition to searching the PATH variable: +If using the Snap distribution you need to run the following command if you intend to place your ROMs on a removable device such as a USB-connected hard drive: +``` +sudo snap connect retroarch:removable-media +``` + +The default es_systems.xml file is paired with a file named es_find_rules.xml which tries to find the emulators and cores using some predefined rules. For Windows this should normally just work, and for macOS too as long as RetroArch is installed at the default location /Applications/RetroArch.app. For Unix/Linux there is one exception that is problematic which is AppImages as there is no standardized directory for storing these images. ES-DE will look for the RetroArch AppImage in the following locations in addition to searching the PATH variable: ``` ~/Applications/RetroArch-Linux-x86_64.AppImage @@ -603,54 +811,66 @@ The default es_systems.xml file is paired with a file named es_find_rules.xml wh ~/bin/RetroArch-Linux-x86_64.AppImage ``` -In any instance, ES-DE will display an error notification if attempting to launch a game where the emulator binary is not found. Likewise it will notify if the defined emulator core is not installed. The es_log.txt file will also provide additional details. +In any instance, an error notification will be displayed if attempting to launch a game where the emulator binary is not found. Likewise a notification will be shown if the defined emulator core is not installed. The es_log.txt file will also provide additional details. ## Scraping -Scraping means downloading metadata and game media files (images and videos) for the games in your collections. +Scraping means downloading metadata and game media files (images and videos) for the games in your collection. -ES-DE supports the two scrapers [ScreenScraper.fr](https://www.screenscraper.fr) and [TheGamesDB.net](https://thegamesdb.net). In general TheGamesDB supports less formats and less systems, but in some areas such PC gaming, the quality is better and sometimes ScreenScraper is missing some specific information such as release dates where TheGamesDB may be able to fill in the gaps. +ES-DE supports the two scraper services [ScreenScraper.fr](https://www.screenscraper.fr) and [TheGamesDB.net](https://thegamesdb.net). In general TheGamesDB supports less formats and less systems, but in some areas such PC gaming, the quality is better and sometimes ScreenScraper is missing some specific information such as release dates where TheGamesDB may be able to fill in the gaps. Here's an overview of what's supported when using these scrapers: -| Media type or option | ScreenScraper | TheGamesDB | -| :----------------------- | :-----------: | :--------: | -| Region (EU/JP/US/WOR) | Yes | No | -| Multi-language | Yes | No | -| Game names | Yes | Yes | -| Ratings | Yes | No | -| Other game metadata | Yes | Yes | -| Videos | Yes | No | -| Screenshots | Yes | Yes | -| Box covers (2D) | Yes | Yes | -| Marquees/wheels | Yes | Yes | -| 3D boxes | Yes | No | +| Media type or option | ScreenScraper | TheGamesDB | +| :-------------------------------- | :-----------: | :--------: | +| Region (EU/JP/US/WOR) | Yes | No | +| Multi-language | Yes | No | +| Game names | Yes | Yes | +| Ratings | Yes | No | +| Controllers (arcade systems only) | Yes | No | +| Other game metadata | Yes | Yes | +| Videos | Yes | No | +| Screenshots | Yes | Yes | +| Title screens | Yes | Yes | +| Box covers | Yes | Yes | +| Box back covers | Yes | No | +| Marquees/wheels | Yes | Yes | +| 3D boxes | Yes | No | +| Physical media | Yes | No | The category **Other game metadata** includes Description, Release date, Developer, Publisher, Genre and Players. The **Multi-language** support includes translated game genres and game descriptions for a number of languages. -There are two approaches to scraping, either for a single game from the metadata editor, or for many games and systems using the multi-scraper. +**Controllers** is metadata indicating the controller type (it's not images of controllers). + +**Physical media** means images of cartridges, diskettes, tapes, CD-ROMs etc. that were used to distribute the games. + +There are two approaches to scraping, either for a single game from the metadata editor, or for multiple games and systems using the multi-scraper. ![alt text](images/es-de_scraper_running.png "ES-DE Scraper Running") _Here's an example of the multi-scraper running in interactive mode, asking the user to make a selection from the multiple matching games returned by the scraper service._ ### Single-game scraper -The single-game scraper is launched from the metadata editor. You navigate to a game, open the game options menu, choose **Edit this game's metadata** and then select the **Scrape** button. +The single-game scraper is launched from the metadata editor. You navigate to a game, open the game options menu, choose **Edit this game's metadata** and then select the **Scrape** button (alternatively the "Y" button shortcut can be used to start the scraper). ### Multi-scraper -The multi-scraper is accessed from the main menu by entering the **Scraper** menu and then selecting the **Start** button. +The multi-scraper is accessed from the main menu by entering the **Scraper** menu and then selecting the **Start** button (or the "Y" button shortcut can be used). ### Scraping process -The process of scraping games is basically identical between the single-game scraper and the multi-scraper. You're presented with the returned scraper results, and you're able to refine the search if the scraper could not find your game. Sometimes small changes like adding or removing a colon or a minus sign can yield better results. Note that the searching is handled entirely by the scraper service, ES-DE just presents the results returned from the service. +Assuming the default _Interactive mode_ option is enabled, the process of scraping games is basically identical between the single-game scraper and the multi-scraper. You're presented with the returned scraper results, and you're able to refine the search if the scraper could not find your game. Sometimes small changes like adding or removing a colon or a minus sign can yield better results. Note that searches are handled entirely by the scraper service, ES-DE just presents the results returned from the service. -By default, ES-DE will search using the metadata name of the game. If no name has been defined via scraping or manually using the metadata editor, this name will correspond to the physical file name minus all text inside either normal brackets `()` or square brackets `[]`. So for example the physical filename `Mygame (U) [v2].zip` will be stripped to simply `Mygame` when performing the scraping. +It's generally recommended to keep the _Auto-accept single game matches_ option enabled as it will run the scraper in semi-automatic mode, only stopping to ask for user input if there are multiple results returned or if no game was found. If this option is disabled, the scraper will stop and ask for confirmation for every game. -By disabling the option **Search using metadata name**, the physical file name will be used even if there is a scraped or manually entered name for the game. +But by disabling the _Interactive mode_ option, the multi-scraper will run in a fully automatic mode, selecting the first game in case of multiple results and skipping to the next game if no results were returned. This is quite convenient for large game libraries but if the correct game is not the first one returned by the scraper service, the wrong game data will be scraped which will require manual correction using the single-game scraper. + +By default, ES-DE will search using the metadata name of the game. If no name has previously been defined via scraping or via manually entering it using the metadata editor, the name used for searching will correspond to the physical filename minus all text inside either normal brackets `()` or square brackets `[]`. So for example the physical filename `Mygame (U) [v2].zip` will be stripped to simply `Mygame` when performing the scraper search. + +By disabling the option _Search using metadata name_, the physical filename will be used even if there is a scraped or manually entered name for the game. There is however an exception to this for arcade games (MAME and Neo Geo) when using the TheGamesDB scraper. As this service does not support searches using the short MAME names, these will be expanded to the full game names via a lookup in the MAME name database supplied with the ES-DE installation. But if using ScreenScraper the _Search using metadata name_ option is always respected as this service fully support scraping based on the short MAME names. @@ -682,21 +902,24 @@ C:\Users\Myusername\.emulationstation\downloaded_media\c64\screenshots\ The media directories per game system are: * 3dboxes +* backcovers * covers * marquees * miximages +* physicalmedia * screenshots +* titlescreens * videos The miximages are generated by ES-DE. Normally that takes place automatically when scraping, but in this example of manually copying existing media files, the miximage offline generator should be used instead. This tool can generate the miximages for the complete game collection in one go. How that works is explained elsewhere in this guide. -The media files must correspond exactly to the game files. For example the following game: +The media files must correspond exactly to the game files. Take for example this game: ``` ~/ROMs/c64/Multidisk/Last Ninja 2/Last Ninja 2.m3u ``` -Must have corresponding filenames for its media files in this fashion: +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 @@ -707,15 +930,15 @@ For images .jpg and .png file extensions are supported and for videos .avi, .mkv Remember that on Unix filenames are case sensitive, and as well the file extensions must be in lower case, such as .png instead of .PNG or .Png or the file won't be found. -It's possible to change the game media directory location from within ES-DE, for this see the option **Game media directory**. +It's possible to change the game media directory location from within ES-DE, for this see the option _Game media directory_. ## Main menu -This menu can be accessed from both the system view and gamelist view. It contains the scraper, application settings and various tools such as the input configurator and the miximage generator. Settings are saved when navigating back from any menu screen, assuming at least one setting was changed. Pressing the application exit key (F4) will also save any pending changes. +This menu can be accessed from both the system view and gamelist view. It contains the scraper, application settings and various tools such as the input configurator and the miximage generator. Settings are saved when navigating back from any menu screen, assuming at least one setting was changed. Pressing the application exit key (F4 by default) will also save any pending changes. ![alt text](images/es-de_main_menu.png "ES-DE Main Menu") -_The ES-DE main menu._ +_The main menu with its multiple submenus._ Following is a breakdown of the main menu entries. @@ -742,10 +965,6 @@ A selection of which systems to scrape for. It's possible to automatically scrap Setup of ScreenScraper account. -**Use this account for ScreenScraper** - -Whether to use the account that has been configured. If this is disabled, the username and password setup on this screen will be ignored during scraping. This can be useful if you have scraping issues and want to check whether it's related to your account or if it's a general problem. Note that screenscraper.fr does not seem to return a proper error message regarding incorrect username and password, but starting ES-DE with the --debug flag will indicate in the log file whether the username was included in the server response. - **ScreenScraper username** Username as registered on screenscraper.fr. @@ -754,45 +973,65 @@ Username as registered on screenscraper.fr. The password as registered on screenscraper.fr. This is masked using asterisks on the screen, and the password input field will be blank when attempting to update an existing password. This is by design and not a bug. Be aware that the es_settings.xml file contains the password in clear text. +**Use this account for ScreenScraper** + +Whether to use the account that has been configured. If this is disabled, the username and password setup on this screen will be ignored during scraping. This can be useful if you have scraping issues and want to check whether it's related to your account or if it's a general problem. Note that screenscraper.fr does not seem to return a proper error message regarding incorrect username and password, but starting ES-DE with the --debug flag will indicate in the log file whether the username was included in the server response. + #### Content settings Describes the content types to include in the scraping. -**Scrape game names** +**Game names** Whether to scrape the names of the games. This does not affect the actual files on the filesystem and the game name is primarily used for appearance and sorting purposes. The downloaded media files are matched against the physical game files on the filesystem, and not against this metadata. See the comments under _Overwrite files and data_ below to understand some additional implications regarding game names. -**Scrape ratings** _(ScreenScraper only)_ +**Ratings** _(ScreenScraper only)_ Downloads game ratings. -**Scrape other metadata** +**Controllers (arcade systems only)** _(ScreenScraper only)_ + +Scrapes controller metadata which is used to set the correct controller badge. This is only available for MAME arcade games, for systems such as _arcade_, _mame_, _neogeo_, _fba_ etc. This is so because ScreenScraper does not seem to provide controller information for other platforms. The type of controllers that are scraped are _joystick_ (separated into entries from no buttons up to 6 buttons), _steering wheel_, _flight stick_, _spinner_, _trackball_ and _lightgun_. + +**Other metadata** This includes the game description, release date, developer, publisher, genre and the number of players. -**Scrape videos** _(ScreenScraper only)_ +**Videos** _(ScreenScraper only)_ Videos of actual gameplay. -**Scrape screenshot images** +**Screenshot images** Screenshot images of actual gameplay. -**Scrape box cover images** +**Title screen images** -Cover art. +Screenshot images of the title screen. -**Scrape marquee (wheel) images** +**Box cover images** + +Cover art, front of box/case. + +**Box back cover images** _(ScreenScraper only)_ + +Back of box/case. + +**Marquee (wheel) images** Logotype for the game. -**Scrape 3D box images** _(ScreenScraper only)_ +**3D box images** _(ScreenScraper only)_ -These are primarily used for generating miximages. +These are only used for generating miximages. + +**Physical media images** _(ScreenScraper only)_ + +Images of cartridges, diskettes, tapes, CD-ROMs etc. that were used to distribute the games. These are only used for generating miximages. #### Miximage settings -These are the settings for the miximage generator, which can either be run from the scraper (single-game scraper or multi-scraper) or from the offline generator. The miximage combines the screenshot, marquee and box images to make a composite picture that is displayed in the gamelist view. There are various settings for the generator. +These are the settings for the miximage generator, which can either be run from the scraper (single-game scraper or multi-scraper) or from the offline generator. The miximage combines the screenshot, marquee, box/cover and physical media images to make a composite picture that is displayed in the gamelist view. There are various settings for the generator. **Miximage resolution** @@ -802,6 +1041,14 @@ It's possible to select betweeen the 1280x960, 1920x1440 and 640x480 resolutions The _sharp_ scaling method uses nearest-neighbor interpolation which retains sharp pixels and looks better for most low-resolution retro games. The _smooth_ scaling method uses the Lanczos algorithm and produces smoother pixels. This may look better on some more modern games at higher resolutions. If unsure, use the _sharp_ method. +**Box size** + +The size of the 3D game box, or the cover image if there is no 3D box and the _Use cover image if 3D box is missing_ setting has been enabled. The available options are _medium, small_ and _large_. + +**Physical media size** + +The size of the physical media image. The available options are _medium, small_ and _large_. + **Generate miximages when scraping** Enables or disables the miximage generator when scraping. Applies to both the single-game scraper and the multi-scraper. @@ -818,6 +1065,10 @@ With this option enabled, any horizontal pure black areas at the top and bottom With this option enabled, any vertical pure black areas at the left and right sides of the screenshots are automatically cropped. +**Rotate horizontally oriented boxes** + +Some consoles such as Super Nintendo have game boxes with the cover printed horizontally rather than using the more common vertical format. If enabling this setting, those images will be rotated 90 degrees so they stand up like the box images for most other systems. + **Incude marquee image** Whether to include the marquee (wheel) image in the composite miximage. @@ -830,9 +1081,13 @@ Whether to include the box image in the composite miximage. If a 3D box exists f Whether to use the 2D box cover as fallback if the 3D box image is missing for the game. +**Include physical media image** + +Whether to include the image of the physical media used to distribute the game, for example a cartridge, diskette, tape, CD-ROM etc. + **Offline generator** -This is not a setting, but instead a GUI to generate miximages offline without going via the scraper. This tool uses the same game system selections as the scraper, so you need to select at least one system on the scraper menu before attempting to run it. All the miximage settings are applied in the same way as when generating images via the scraper. The prerequisite is that at least a screenshot exists for each game. If there is no screenshot, or if the screenshot is unreadable for some reason, the generation for that specific game will fail. There is statistics shown in the tool displaying the number of generated, overwritten, skipped and failed images. Any error message is also shown on screen as well as being saved to the es_log.txt file. +This is not a setting, but instead a GUI to generate miximages offline without going via the scraper. This tool uses the same game system selections as the scraper, so you need to select at least one system on the scraper menu before attempting to run it. All the miximage settings are applied in the same way as when generating images via the scraper. The prerequisite is that at least a screenshot exists for each game. If there is no screenshot, or if the screenshot is unreadable for some reason, the generation for that specific game will fail. There is statistics shown in the tool displaying the number of generated, overwritten, skipped and failed images. Any error message is shown on screen as well as being saved to the es_log.txt file. Note that although the system selections are the same as for the scraper, the _Scrape these games_ filter is ignored and the generator always attempts to generate miximages for all games in a system. #### Other settings @@ -848,15 +1103,15 @@ Multiple languages are supported by ScreenScraper, and this affects translations **Overwrite files and data** -Affects both overwriting of metadata as well as actual game media files on the filesystem. Even with this option disabled, metadata entries which are set to their default values will of course be populated by the scraper. In other words, this option only affects overwriting of previously scraped data. Game names are considered as set to their default values if either corresponding to the physical game file on disk minus the extension (e.g. the entry _Commando_ if the file is named _Commando.zip_), or for arcade games if corresponding to the MAME names as defined in the bundled mamenames.xml. Note that this setting does not affect generated miximages, that is instead controlled by the setting _Overwrite miximages (scraper/offline generator)_ found in the miximage settings menu. +Affects both overwriting of metadata as well as actual game media files on the filesystem. Even with this option disabled, metadata entries which are set to their default values will be populated by the scraper. In other words, this option only affects overwriting of previously scraped data, or data manually entered via the metadata editor. Game names are considered as set to their default values if either corresponding to the physical game file on disk minus the extension (e.g. the entry _Commando_ if the file is named _Commando.zip_), or for arcade games if corresponding to the MAME names as defined in the bundled mamenames.xml. Note that this setting does not affect generated miximages, that is instead controlled by the setting _Overwrite miximages (scraper/offline generator)_ found in the miximage settings menu. **Halt on invalid media files** -With this setting enabled, if any media files returned by the scraper seem to be invalid, the scraping is halted and an error message is presented where it's possible to retry or cancel the scraping of the specific game. In the case of multi-scraping it's also possible to skip the game and proceed to the next one in the queue. With this setting disabled, all media files will always be accepted and saved to disk. As of ES-DE v1.1 the file verification is quite basic and future versions will improve on this by using file checksums and other file integrity checks. +With this setting enabled, if any media files returned by the scraper seem to be invalid, the scraping is halted and an error message is presented where it's possible to retry or cancel the scraping of the specific game. In the case of multi-scraping it's also possible to skip the game and proceed to the next one in the queue. With this setting disabled, all media files will always be accepted and saved to disk. As of ES-DE v1.2 the file verification is quite basic and future versions will improve on this by using file checksums and other file integrity checks. There is an exception in place for box back covers when using ScreenScraper. As many of these specific images are broken, there is an automatic filter built in that is always active and which removes blank images and those containing only a few lines of pixels. **Search using metadata names** -By default ES-DE will perform scraper searches based on the game name that has been manually set in the metadata editor, or that has been previously scraped. If you prefer to search using the physical file name regardless of such data being available, then disable this option. Note that when using TheGamesDB as scraper service for arcade games (MAME and Neo Geo), the short MAME name will always be expanded to the full game name as this scraper service does not support searches using short MAME names. +By default ES-DE will perform scraper searches based on the game name that has been manually set in the metadata editor, or that has been previously scraped. If you prefer to search using the physical filename regardless of such data being available, then disable this option. Note that when using TheGamesDB as scraper service for arcade games (MAME and Neo Geo), the short MAME name will always be expanded to the full game name as this scraper service does not support searches using short MAME names. In general it's recommended to disable this option if scraping arcade games using ScreenScraper as the MAME short names is much more reliable than using the metadata names. **Interactive mode** _(Multi-scraper only)_ @@ -880,7 +1135,7 @@ Enabling this option causes folders themselves to be included by the scraper. Th **Auto-retry on peer verification errors** _(ScreenScraper only)_ -ScreenScraper sometimes has issues with its TLS certificates which causes searches to randomly fail. It's normally resolved within a few days, but in the meanwhile activating this setting will have the scraper automatically make up to eight additional attempts when this error occurs. That is normally enough to complete the search, but if not, just press 'Retry' in the error dialog and ES-DE will try eight more times. This setting applies to both the single-game scraper and the multi-scraper. The following error notification dialog and corresponding es_log.txt entry is displayed when this error occurs: "Error downloading thumbnail: SSL peer certificate or SSH remote key was not OK". +ScreenScraper sometimes has issues with its TLS certificates which causes searches to randomly fail. It's normally resolved within a few days, but in the meanwhile activating this setting will have the scraper automatically make up to eight additional attempts when this error occurs. That is normally enough to complete the search, but if not, just press _Retry_ in the error dialog and ES-DE will try eight more times. This setting applies to both the single-game scraper and the multi-scraper. The following error notification dialog and corresponding es_log.txt entry is displayed when this error occurs: "Error downloading thumbnail: SSL peer certificate or SSH remote key was not OK". ### UI settings @@ -896,11 +1151,11 @@ Sets the view style to _Automatic, Basic, Detailed, Video_ or _Grid_. See the de **Transition style** -Transition animation when navigating between the views. Can be set to _Slide, Fade_ or _Instant_. +Transition animation when navigating between gamelists, or between systems on the System view carousel. Can be set to _Slide, Fade_ or _Instant_. **Theme set** -The theme to use. Defaults to rbsimple-DE, the theme shipped with ES-DE. +The theme set to use. Defaults to rbsimple-DE which is shipped with the application. **UI mode** @@ -918,6 +1173,14 @@ Animation to play when opening the main menu or the game options menu. Also sets This configures for how long to display the game launch screen when starting a game. The options are _Normal_, _Brief_, _Long_ and _Disabled_. If set to _Disabled_, a simple notification popup will be displayed instead. +**Media viewer settings** + +Submenu containing all the settings for the media viewer. These are described in detail below. + +**Screensaver settings** + +Submenu containing all the settings for the screensaver. These are described in detailed below. + **Blur background when menu is open** _(OpenGL renderer only)_ This option will blur the background behind the menu slightly. Normally this can be left enabled, but if you have a really slow GPU, disabling this option may make the application feel a bit more responsive. @@ -940,7 +1203,7 @@ Whether to sort your favorite games above your other games in the gamelists. **Add star markings to favorite games** -With this setting enabled, there is a star symbol added at the beginning of the game name in the gamelist views. It's strongly recommended to keep this setting enabled if the option to sort favorite games above non-favorites has been enabled. If not, favorite games would be sorted on top of the gamelist with no visual indication that they are favorites, which would be quite confusing. +With this setting enabled, there is a star symbol added at the beginning of the game name in the gamelist views. If you're not using a theme set which support badges, it's strongly recommended to keep this setting enabled. Especially so if the option to sort favorite games above non-favorites has been enabled. Otherwise favorite games would be sorted on top of the gamelist with no clear visual indication that they are favorites which would be quite confusing. **Use plain ASCII for special gamelist characters** @@ -948,7 +1211,15 @@ There are some special characters in ES-DE such as the favorites star, the folde **Enable quick list scrolling overlay** -With this option enabled, there will be an overlay displayed when scrolling the gamelists quickly, i.e. when holding down the _Up_, _Down_, _Left shoulder_ or _Right shoulder_ buttons for some time. The overlay will darken the background slightly and display the first two characters of the game names. If the game is a favorite and the setting to sort favorites above non-favorites has been enabled, a star will be shown instead. +With this option enabled, there will be an overlay displayed when scrolling the gamelists quickly, i.e. when holding down the _Up_, _Down_, _Left shoulder_ or _Right shoulder_ buttons for some time. The overlay will darken the background slightly and display the first two characters of the game names. If the game is a favorite and the setting to sort favorites above non-favorites has been enabled, a star symbol will be shown instead. + +**Enable virtual keyboard** + +This enables a virtual (on-screen) keyboard that can be used at various places throughout the application to input text and numbers using a controller. The Shift and Alt keys can be toggled individually or combined to access many special characters. The general use of the virtual keyboard should hopefully be self-explanatory. + +**Enable menu scroll indicators** + +With this option enabled, "up and down" scroll indicators will be displayed in the upper right corner of menus (including the metadata editor and scraper) if there are more entries available than can be shown on the screen at the same time. These indicators will change dynamically as the list is scrolled. If the setting is disabled, a simplified static indicator will be displayed instead. **Enable toggle favorites button** @@ -994,9 +1265,9 @@ Whether to use a shader to render scanlines for the videos. Be aware that this i Whether to use a shader to render a slight horizontal blur which somewhat simulates a well-used CRT monitor. Be aware that this is quite demanding for the GPU. -**Render scanlines for screenshots** _(OpenGL renderer only)_ +**Render scanlines for screenshots and titles** _(OpenGL renderer only)_ -Whether to use a shader to render scanlines for the screenshot images. +Whether to use a shader to render scanlines for the screenshot and title screen images. #### Screensaver settings @@ -1012,7 +1283,7 @@ The screensaven type to use; _Dim_, _Black_, _Slideshow_ or _Video_. **Enable screensaver controls** -This enables the ability to start the screensaver manually using the _Back_ button from the system view, but also while the screensaver is running to jump to a new random game using the _Left_ and _Right_ buttons, to launch the game currently shown using the _A_ button and to jump to the game in its gamelist using the _Y_ button. If this setting is disabled, any key or button press will stop the screensaver. +This enables the ability to start the screensaver manually using the _Back_ button from the system view, but also while the screensaver is running to jump to a new random game using the _Left_ and _Right_ buttons, to launch the game currently shown using the _A_ button or to jump to the game in its gamelist using the _Y_ button. If this setting is disabled, any key or button press will stop the screensaver. #### Slideshow screensaver settings @@ -1028,7 +1299,7 @@ This will fill the entire screen surface but will probably break the aspect rati **Display game info overlay** -This will display an overlay in the upper left corner, showing the game name and the game system name. A star following the game name indicates that it's flagged as a favorite. +This will display an overlay in the upper left corner, showing the game name and the game system name. A star symbol following the game name indicates that it's flagged as a favorite. **Render scanlines** _(OpenGL renderer only)_ @@ -1036,7 +1307,7 @@ Whether to use a shader to render scanlines for the images. **Use custom images** -Using this option, it's possible to use custom images instead of random images from the game library. As is the case with the rest of ES-DE, the supported file formats are JPG and PNG. +Using this option it's possible to use custom images instead of random images from the game library. As is the case with the rest of ES-DE, the supported file formats are JPG and PNG. **Custom image directory recursive search** @@ -1052,7 +1323,7 @@ Options specific to the video screensaver. **Swap videos after (seconds)** -For how long to play videos before changing to the next game. Allowed range is between 0 and 120 seconds in 2-second increments. If set to 0 (which is the default value), the next game will be selected after the entire video has finished playing. +For how long to play videos before changing to the next game. Allowed range is between 0 and 120 seconds in 2-second increments. If set to 0 (which is the default value), the next game will be selected after the entire video has finished playing. If set to a higher value than the length of a game video, it will loop until reaching the swap time. **Stretch videos to screen resolution** @@ -1060,7 +1331,7 @@ This will fill the entire screen surface but will probably break the aspect rati **Display game info overlay** -This will display an overlay in the upper left corner, showing the game name and the game system name. A star following the game name indicates that it's flagged as a favorite. +This will display an overlay in the upper left corner, showing the game name and the game system name. A star symbol following the game name indicates that it's flagged as a favorite. **Render scanlines** _(OpenGL renderer only)_ @@ -1101,7 +1372,7 @@ With this turned off, audio won't play for videos when using the video screensav **Enable navigation sounds** -Enable or disable navigation sounds throughout the application. Sounds are played when browsing systems and lists, starting games, adding and removing games as favorites etc. The sounds can be customized per theme, but if the theme does not support navigation sounds, ES-DE will fall back to its built-in sounds. +Enables or disables navigation sounds throughout the application. Sounds are played when browsing systems and lists, starting games, adding and removing games as favorites etc. The sounds can be customized per theme, but if the theme does not support navigation sounds, ES-DE will fall back to its built-in samples. ### Input device settings @@ -1114,11 +1385,11 @@ This setting gives the ability to choose between the controller types _Xbox, Xbo **Only accept input from first controller** -If enabling this option, only the first controller detected during startup will send its input to ES-DE. This is a good way to limit potential chaos with mutliple users fighting over which games to start. Disconnecting and reconnecting controllers while ES-DE is running may change what is considered the first controller. This setting does not affect the emulators in any way, it's only applied to ES-DE. +If enabling this option, only the first controller detected during startup will send its input to ES-DE (the keyboard input is unaffected by this setting and will be enabled regardless). This is a good way to limit potential chaos with multiple persons fighting over which games to start. Disconnecting and reconnecting controllers while ES-DE is running may change what is considered the first controller. This setting does not affect the emulators in any way, it's only applied to ES-DE. **Configure keyboard and controllers** -This tool provides configuration of button mappings for the keyboard and controllers, as explained [here](USERGUIDE.md#input-device-configuration). Normally this is not required as ES-DE automatically configures all input devices, but button customizations may be useful in some special situations. Be aware that custom button mappings will not change the help icons or help text. +This tool provides configuration of button mappings for the keyboard and controllers, as explained [here](USERGUIDE.md#input-device-configuration). Normally this is not required as ES-DE automatically configures all input devices, but button customizations may be useful in some special situations. You may also need to run this tool if you have an unusual controller which could not be automatically configured. Be aware that custom button mappings will not change the help icons or help text. ### Game collection settings @@ -1135,11 +1406,11 @@ This lets you enable or disable the automatic game collections _All games, Favor **Custom game collections** -This lets you enable or disable your own custom game collections. +This lets you enable or disable your own custom game collections. If there are no custom collections available, this menu entry will be grayed out. **Create new custom collection from theme** _(Entry only visible if the ability is provided by the theme set)_ -If the theme set in use provides themes for custom collections, then this entry can be selected. For example, there could be themes for _"Fighting games"_ or _"Driving games"_ etc. The default rbsimple-DE theme set does not provide such themes for custom collections and in general it's not recommended to use this approach, as is explained [later](USERGUIDE.md#custom-collections) in this guide. +If the theme set in use provides themes for custom collections, then this entry can be selected. For example, there could be themes for _Fighting games_ or _Driving games_ etc. The default rbsimple-DE theme set does not provide such themes for custom collections and in general it's not recommended to use this approach, as is explained [later](USERGUIDE.md#custom-collections) in this guide. **Create new custom collection** @@ -1155,7 +1426,7 @@ Whether to sort your favorite games above your other games. This is disabled by **Display star markings for custom collections** -With this option enabled, there is a star marking added to each favorite game name. It works identically to the setting _Add star markings to favorite games_ under the _UI settings_ menu but is applied specifically to custom collections. It's disabled by default. +With this option enabled, there is a star symbol added to each favorite game name. It works identically to the setting _Add star markings to favorite games_ under the _UI settings_ menu but is applied specifically to custom collections. It's disabled by default. **Group unthemed custom collections** @@ -1169,57 +1440,56 @@ Enables the system name to be shown in square brackets after the game name, for These are mostly technical settings. -**VRAM limit** +**Alternative emulators** -The amount of video RAM to use for the application. Defaults to 256 MiB (80 MiB on the Raspberry Pi) which works fine most of the time when running at 1080p resolution and with a moderate amount of game systems. If running at 4K resolution or similar and with lots of game systems enabled, it's recommended to increase this number to 512 MiB or possibly more to avoid stuttering transition animations caused by unloading and loading of textures from the cache. Enabling the GPU statistics overlay gives some indications regarding the amount of texture memory currently used by ES-DE, which is helpful to determine a reasonable value for this option. The allowed range for the settings is 80 to 1024 MiB. If you try to set it lower or higher than this by passing such values as command line parameters or by editing the es_settings.xml file manually, ES-DE will log a warning and automatically adjust the value within the allowable range. +Using this interface it's possible to select alternative emulators to use per game system, which requires that these alternatives have been defined in the es_systems.xml file. Note that only systems that you have currently populated will be listed. To change to an alternative emulator, you simply select a system from the list and choose which alternative to use from the presented options. If you select an alternative emulator and later remove its corresponding entry from the es_systems.xml file, an error message will be shown on application startup telling you to review your invalid emulator selection. Games will still launch, but the default emulator will be used in this case. How to clear an invalid entry should be self-explanatory once you access the interface. It's also possible to set alternative emulators per game using the metadata editor. If this is done, it will take precedence and override the system-wide emulator selection for the specific game. The alternative emulator badges and the corresponding gamelist filter are controlled by these per-game alternative emulator values and not by the system-wide option. -**Display/monitor index (requires restart)** - -This option sets the display to use for ES-DE for multi-monitor setups. The possible values are the monitor index numbers 1, 2, 3 or 4. If a value is set here for a display that does not actually exist, then ES-DE will set it to 1 upon startup. Index 1 is the primary display for the computer. It's also possible to override the setting by passing the --display command line argument. Doing so will also overwrite the display index setting in es_settings.xml. The Display/monitor index option only changes the display used by ES-DE; the emulators need to be configured separately (which can easily be done globally if using RetroArch). - -**Fullscreen mode (requires restart)** _(Unix only)_ - -This gives you a choice between _Normal_ and _Borderless_ modes. With the borderless being more seamless as the ES-DE window will always stay on top of other windows so the taskbar will not be visible when launching and returning from games. It will however break the alt-tab application switching of your window manager. For normal fullscreen mode, if a lower resolution than the screen resolution has been set via the --resolution command line argument, ES-DE will render in full screen at the lower resolution. If a higher resolution than the screen resolution has been set, ES-DE will run in a window. For the borderless mode, any changes to the resolution will make ES-DE run in a window. - -**Video player** _(Only on some builds and operating systems)_ - -This gives the choice between FFmpeg and VLC, which is applied to the gamelist videos, the media viewer and the video screensaver. The VLC video player is not included on some builds. If this option is not available in the menu, it means that the FFmpeg video player is in use. - -**When to save game metadata** - -The metadata for a game is updated by scraping or by manual editing using the metadata editor, but also when launching it as this updates the _Times played_ counter and the _Last played_ timestamp. This setting enables you to define when to write such metadata changes to the gamelist.xml files. Setting the option to _Never_ will disable writing to these files altogether, except for some special conditions such as when a game is manually deleted using the metadata editor, or when scraping using the multi-scraper (the multi-scraper will always save any updates immediately to the gamelist.xml files). In theory _On exit_ will give some performance gains, but it's normally recommended to leave the setting at its default value which is _Always_. Note that with the settings set to _Never_, any updates such as the _Last played_ date will still be shown on screen, but during the next application startup, any values previously saved to the gamelist.xml files will be read in again. As well, when changing this setting to _Always_ from either of the two other options, any pending changes will be immediately written to the gamelist.xml files. +![alt text](images/es-de_alternative_emulators.png "ES-DE Scraper Settings") +_The system-wide alternative emulators interface. An entry in bold and with a gear symbol indicates that an alternative emulator has been selected._ **Game media directory** This setting defines the directory for the game media, i.e. game images and videos. The default location is _~/.emulationstation/downloaded_media_ +**VRAM limit** + +The amount of video RAM to use for the application. Defaults to 256 MiB (184 MiB on the Raspberry Pi) which works fine most of the time when running at 1080p resolution and with a moderate amount of game systems. If running at 4K resolution or similar and with lots of game systems enabled, it's recommended to increase this number to 512 MiB or possibly more to avoid stuttering transition animations caused by unloading and loading of textures from the cache. Enabling the GPU statistics overlay gives some indications regarding the amount of texture memory currently used, which is helpful to determine a reasonable value for this option. The allowed range for the settings is 80 to 1024 MiB. If you try to set it lower or higher than this by passing such values as command line parameters or by editing the es_settings.xml file manually, ES-DE will log a warning and automatically adjust the value within the allowable range. + +**Display/monitor index (requires restart)** + +This option sets the display to use for ES-DE for multi-monitor setups. The possible values are the monitor index numbers 1, 2, 3 or 4. If a value is set here for a display that does not actually exist, then ES-DE will set it to 1 upon startup. Index 1 is the primary display for the computer. It's also possible to override the setting by passing the --display command line argument. Doing so will also overwrite the display index setting in es_settings.xml. The Display/monitor index option only changes the display used by ES-DE; the emulators need to be configured separately (which can easily be done globally if using RetroArch). + +**Exit button combo** + +This gives the choice of which key combination to use to close the application. The default value is F4, but this can be changed to Alt + F4 on all operating systems. Additionally on macOS the Command + Q combination is selectable and on all other operating systems Alt + Q is selectable instead. Note that on Windows and most window managers on Unix/Linux, Alt + F4 will close the application regardless of the selected option as that key combination is a default which can't be restricted by ES-DE. Similarly on macOS, Command + Q always closes the application, so selecting this combination simply disables the previously selected exit button. + +**When to save game metadata** + +The metadata for a game is updated by scraping or by manual editing using the metadata editor, but also when launching it as this updates the _Times played_ counter and the _Last played_ timestamp. This setting enables you to define when to write such metadata changes to the gamelist.xml files. Setting the option to _Never_ will disable writing to these files altogether, except for some special conditions such as when a game is manually deleted using the metadata editor, when scraping using the multi-scraper (the multi-scraper will always save any updates immediately to the gamelist.xml files) or when changing the system-wide alternative emulator. In theory _On exit_ will give some small performance gains, but it's normally recommended to leave the setting at its default value which is _Always_. Note that with the settings set to _Never_, any updates such as the _Last played_ date will still be shown on screen, but during the next application startup, any values previously saved to the gamelist.xml files will be read in again. As well, when changing this setting to _Always_ from either of the two other options, any pending changes will be immediately written to the gamelist.xml files. + **Hide taskbar (requires restart)** _(Windows only)_ -With this setting enabled, the taskbar will be hidden when launching ES-DE, and it will be restored when the application exits. This can make for a more seamless experience as the taskbar could otherwise flash by briefly when launching and when returning from games. But it can potentially cause issues on some Windows installations so it's disabled by default. +With this setting enabled, the taskbar will be hidden when launching ES-DE, and it will be restored when the application exits. This can make for a more seamless experience as the taskbar could otherwise flash by briefly when launching and returning from games. **Run in background (while game is launched)** -Enabling this option makes ES-DE continue to run while a game is launched. This is normally not recommended as it leads to a slightly strange application behavior and also removes the ability to capture return codes and log output from the emulators. But with some graphics drivers on Windows this may be a suitable workaround if there are problems launching games (also see the next option below). Note that launching Steam games on all supported operating systems always makes ES-DE continue to run in the background for technical reasons. +Enabling this option makes ES-DE continue to run while a game is launched. This is normally not recommended as it leads to a slightly strange application behavior and it also removes the ability to capture return codes and log output from the emulators. Generally this option should only be enabled if there are issues with launching games while suspending ES-DE. Note however that some systems like Valve Steam will always keep ES-DE running in the background because they require it for technical reasons (i.e. those systems will override this menu option). -**AMD and Intel GPU game launch workaround** _(Windows only)_ +**Upscale video frame rate to 60 FPS** -There is an issue with launching games on some Windows computers, seemingly on those with AMD and Intel GPUs. The emulator will start and work correctly, but the screen will be blank. Enabling this option is a workaround for that problem, with the drawback that the screen will become white instead of black when the emulator is loading. This option is enabled by default, so experiment with disabling it for a slightly better experience. If you're using an Nvidia GPU, chances are high that it will then work fine. An alternative workaround is to enable the _Run in background (while game is launched)_ option described above, so test which gives the best result. The two options can however not be enabled at the same time. Hopefully this whole game launching issue can be resolved completely in a future ES-DE release. +With this option enabled, videos with lower frame rates than 60 FPS, such as 24 and 30 will get upscaled to 60 FPS. This results in slightly smoother playback for some videos. There is a small performance hit from this option, so on weaker machines it may be necessary to keep it disabled for fluent video playback. -**FFmpeg/Video hardware decoding (experimental)** _(All platforms except Raspberry Pi)_ +**Preload gamelists on startup** -Enabling this option offloads video decoding to the GPU. Whether this actually increases performance is another matter. As desktop-class CPUs are very capable of decoding the video streams directly, the performance may actually get worse as hardware decoding requires data to be passed back and forth between the CPU and GPU. This potential degradation is especially true for integrated GPUs, and even more so if the GPU is heavily utilized. In addition to this, most GPUs can only decode a subset of video codecs and profiles, meaning ES-DE will anyway have to fallback to software decoding when the GPU is unable to process the stream. With that said, there are still situations where hardware decoding can help, so experiment with the setting to see if it's useful for your configuration. Unfortunately hardware decoding for the FFmpeg video player is not supported on the Raspberry Pi and it will probably stay this way unless FFmpeg starts to support the MMAL decoder internally. For this device the VLC-based video player can be used instead, which supports hardware decoding. +When this option is enabled, all gamelists will be loaded on application startup. This will increase the startup time slightly and lead to a higher initial memory utilization, but navigation will be smoother the first time a gamelist is entered. The improvement is especially noticeable when the _slide_ transition style has been selected. -**Upscale video frame rate to 60 FPS (FFmpeg)** +**Enable alternative emulators per game** -With this option enabled, videos with lower frame rates than 60 FPS, such as 24 and 30 will get upscaled to 60 FPS. This results in slightly smoother playback for some videos. There is a small performance hit from this option, so on weaker machines it may be necessary to disable it for fluent video playback. This setting has no effect when using the VLC video player. If the VLC video player is not included in the ES-DE build, the "(FFmpeg)" text is omitted from the setting name. - -**Per game launch command override** - -If enabled, you can override the launch command defined in es_systems.xml on a per-game basis using the metadata editor. It's only recommended to disable this option for testing purposes, such as when a game won't start and you're unsure if it's your custom launch command that causes the problem. +If enabled, you will be able to select alternative emulators per game using the metadata editor, which will be used when launching the game. If disabled, the corresponding entry in the metadata editor will be hidden, the alternative emulator badges will not be displayed and it will not be possible to filter the gamelist based on these values. As well, the game will be launched using the default emulator, or using the system-wide alternative emulator if this has been configured for the game system. It's only recommended to disable this option for testing purposes. **Show hidden files and folders (requires restart)** -If this option is disabled, hidden files and folders within the ROMs directory tree are excluded from ES-DE. On Unix this means those starting with a dot, and on Windows it's those set as hidden by using an NTFS attribute. This setting is only intended for special situations and is not to be confused with the next option which hides files based on metadata configuration within ES-DE. +If this option is disabled, hidden files and folders within the ROMs directory tree are excluded from ES-DE. On Unix and macOS this means those starting with a dot, and on Windows it's those set as hidden by using an NTFS attribute. This setting is only intended for special situations and is not to be confused with the next option which hides files based on metadata configuration within ES-DE. **Show hidden games (requires restart)** @@ -1227,7 +1497,7 @@ You can mark games as hidden in the metadata editor, which is useful for instanc **Enable custom event scripts** -It's possible to trigger custom scripts for a number of actions in ES-DE, as is discussed [below](USERGUIDE.md#custom-event-scripts), and this setting decides whether this functionality is enabled. It's recommended to leave it at its default off value unless you need it as it otherwise generates unnecessary debug logging. +It's possible to trigger custom scripts for a number of actions in ES-DE, as is discussed [below](USERGUIDE.md#custom-event-scripts), and this setting decides whether this functionality is enabled. **Only show ROMs from gamelist.xml files** @@ -1239,7 +1509,7 @@ The window manager desktop composition can adversely affect the framerate of ES- **Display GPU statistics overlay** -Displays the framerate and VRAM statistics as an overlay. You normally never need to use this unless you're debugging a performance problem or similar. **Note:** As of ES-DE v1.1 the VRAM usage statistics is not accurate. This will be addressed in a future version. +Displays the framerate and VRAM statistics as an overlay. You normally never need to use this unless you're debugging a performance problem or similar. **Note:** As of ES-DE v1.2 the VRAM usage statistics is not accurate. This will be addressed in a future release. **Enable menu in kid mode** @@ -1257,7 +1527,7 @@ If the menu is enabled, these are its entries: **Quit EmulationStation** -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 of course also applies 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 EmulationStation_ entry. **Reboot system** _(Unix and Windows only)_ @@ -1270,7 +1540,7 @@ Self explanatory. ## Game options menu -This menu is opened from the gamelist view, and can't be accessed from the system view. The menu changes slightly depending on the context, for example if a game file or a folder is selected, or whether the current system is a collection or a normal game platform. +This menu is opened from the gamelist view, and can't be accessed from the system view. The menu changes slightly depending on the context, for example if a game file or a folder is selected, or whether the current system is a collection or a normal game system. You open the menu using the **Back** button, and by pressing **B** or selecting the **Apply** button any settings such as letter jumping using the quick selector or sorting changes are applied. If you instead press the Back button again or select the **Cancel** button, the menu is closed without applying any changes. @@ -1281,11 +1551,11 @@ Here's a summary of the menu entries: ### Jump to.. -This provides a quick selector for jumping to a certain letter. If the setting to sort favorite games above non-favorites has been enabled, then it's also possible to jump to the favorites games by choosing the star symbol. Similarly if there is a mix of folders and game files in the system and folders are configured to be sorted on top, then it's possible to jump to the folders using the folder icon. If there are only folders or only favorite games for the system, these games and folders will be indexed by their first letters and the star and folder symbols will be disabled in the quick selector. +This provides a quick selector for jumping to a certain letter. If the setting to sort favorite games above non-favorites has been enabled, then it's also possible to jump to the favorites games by choosing the star symbol. Similarly if there is a mix of folders and game files in the system and folders are configured to be sorted on top, then it's possible to jump to the folders using the folder icon. If there are only folders or only favorite games for the system, these games and folders will be indexed by their first letters and the star and folder symbols will not be disabled in the quick selector. ### Sort games by -This is the sort order for the gamelist. The default sorting shown here is taken from the setting **Default sort order** under **UI settings** in the main menu. Any sorting that is applied via the game options menu will be persistent throughout the program session, and it can be set individually per game system and per collection. +This is the sort order for the gamelist. The default sorting shown here is taken from the setting _Default sort order_ under _UI settings_ in the main menu. Any sorting that is applied via the game options menu will be persistent throughout the program session, and it can be set individually per game system and per collection. Sorting can be applied using the following metadata, in either ascending or descending order: @@ -1311,32 +1581,42 @@ _The gamelist filter screen, accessed from the game options menu._ The following filters can be applied: -**Text Filter (game name)** +**Game name** -**Favorites** +**Rating** + +**Developer** + +**Publisher** **Genre** **Players** -**Publisher / Developer** - -**Rating** - -**Kidgame** +**Favorite** **Completed** +**Kidgame** + +**Hidden** _If the "Show hidden games" option is enabled_ + **Broken** -**Hidden** +**Controller** -With the exception of the text filter, all available filter values are assembled from metadata from the actual gamelist, so if there for instance are no games marked as completed, the Completed filter will only have the selectable option False, i.e. True will be missing. +**Alternative emulator** _If the "Enable alternative emulators per game" option is enabled_ -Be aware that although folders can have most of the metadata values set, the filters are only applied to files (this is also true for the text/game name filter). So if you for example set a filter to only display your favorite games, any folder that contains a favorite game will be displayed, and other folders which are themselves marked as favorites but that do not contain any favorite games will be hidden. +With the exception of the game name text filter, all available filter values are assembled from metadata from the actual gamelist, so if there is no data to filter for the specific field, the text _Nothing to filter_ will be displayed. This for example happens for the _Completed_ filter if there are no games marked as having been completed in the current gamelist. The same happens if a metadata setting is identical for all games, such as all games being flagged as favorites. + +Note that the _Alternative emulator_ filter only includes game-specific values that have been set using the metadata editor, the system-wide alternative emulators setting has no effect on this filter. + +Be aware that although folders can have most of the metadata values set, the filters are only applied to files (this is also true for the game name text filter). So if you for example set a filter to only display your favorite games, any folder that contains a favorite game will be displayed, and other folders which are themselves marked as favorites but that do not contain any favorite games will be hidden. The filters are always applied for the complete game system, including all folder content. +Note that the game name filter is case insensitive. + ### Add/remove games to this collection This entry is only shown if the system is a custom collection. The way this works is described in more detail [below](USERGUIDE.md#custom-collections). @@ -1363,7 +1643,7 @@ The following entries can be modified (note that some of these are not available **Name** -This is the name that will be shown when browsing the gamelist. If no sortname has been defined, the games are sorted using this field. +This is the name that will be shown when browsing the gamelist. If no sortname has been defined, the games are sorted using this field. If the scraper option _Search using metadata names_ has been enabled, this name will be used for scraper searches. **Sortname** _(files only)_ @@ -1405,9 +1685,9 @@ A flag to indicate whether this is a favorite game. This flag can also be set di A flag to indicate whether you have completed the game. -**Kidgame** _(files only)_ +**Kidgame** -A flag to mark whether the game is suitable for children. This will be applied as a filter when starting ES-DE in _Kid_ mode. +A flag to mark whether the game is suitable for children. This will be applied as a filter when starting ES-DE in _Kid_ mode. Although it's possible to also set this flag for folders, this will **not** affect the actual files inside those folders. It will instead only be used to display the Kidgame badge for the folders themselves. **Hidden** @@ -1419,7 +1699,7 @@ A flag to indicate whether the game is broken. Useful for MAME games for instanc **Exclude from game counter** _(files only)_ -A flag to indicate whether the game should be excluded from being counted. If this is set for a game, it will not be included in the game counter shown per system on the system view, and it will not be included in the system information field in the gamelist view. As well, it will be excluded from all automatic and custom collections. This option is quite useful for multi-file games such as multi-disc Amiga or Commodore 64 games, or for DOS games where you want to exclude setup programs and similar but still need them available in ES-DE and therefore can't hide them. Files that have this flag set will have a lower opacity in the gamelists, making them easy to spot. +A flag to indicate whether the game should be excluded from being counted. If this is set for a game, it will not be included in the game counter shown per system in the system view, and it will not be included in the system information field in the gamelist view. As well, it will be excluded from all automatic and custom collections. This option is quite useful for multi-file games such as multi-disc Amiga or Commodore 64 games, or for DOS games where you want to exclude setup programs and similar but still need them available in ES-DE and therefore can't hide them. Files that have this flag set will have a lower opacity in the gamelists, making them easy to spot. **Exclude from multi-scraper** @@ -1427,16 +1707,20 @@ Whether to exclude the file from the multi-scraper. This is quite useful in orde **Hide metadata fields** -This option will hide most metadata fields in the gamelist view. The intention is to be able to hide the fields for situations such as general folders (Multi-disc, Cartridges etc.) and for setup programs and similar (e.g. SETUP.EXE or INSTALL.BAT for DOS games). It could also be used on the game files for multi-disc games where perhaps only the .m3u playlist should have any metadata values. The only fields shown with this option enabled are the game name and description. Using the description it's possible to write some comments regarding the file or folder, should you want to. It's also possible to display game images and videos with this setting enabled. - -**Launch command** _(files only)_ - -Here you can override the launch command for the game, for example to use a different emulator than the default one defined for the game system. Very useful for MAME/arcade games. +This option will hide most metadata fields as well as any badges. The intention is to be able to hide the fields for situations such as general folders (Multi-disc, Cartridges etc.) and for setup programs and similar (e.g. SETUP.EXE or INSTALL.BAT for DOS games). It could also be used on the game files for multi-disc games where perhaps only the .m3u playlist should have any metadata values. The only fields shown with this option enabled are the game name and description. So using the description it's possible to write some comments regarding the file or folder, should you want to. Game images and videos will also still be displayed if this setting is enabled. **Times played** _(files only)_ A statistics counter that tracks how many times you have played the game. You normally don't need to touch this, but if you want to, the possibility is there. +**Controller** + +This entry provides a selection of controller icons that are built into ES-DE (although the theme set can override the actual graphics files). The selected icon will be displayed as a badge if the current theme set support badges. The gamelist can also be filtered based on the controllers, but apart from this the functionality is cosmetic and will not affect the actual emulators. + +**Alternative emulator** _(files only)_ + +If the option _Enable alternative emulators per game_ has been enabled, there will be an entry shown where you can select between alternative emulators for the specific game. There is a similar _Alternative emulators_ entry under the _Other settings_ menu, but that will apply the selection to the entire game system. If you select an alternative for a specific game using the metadata editor, that will take precedence and override any system-wide emulator selection (the currently selected system-wide emulator will be clearly marked on the selection screen). The alternative emulators need to be defined in the es_systems.xml file, and if there are no alternatives available for the current system, this row in the metadata editor will be grayed out. If you select an alternative emulator and later remove its corresponding entry from the es_systems.xml file, an error notice will be shown on this row. In this case you have the option to remove the invalid entry. But even if there is an invalid entry, games will still launch using the default emulator while logging a warning message to the es_log.txt file. Apart from this, the emulator selection should hopefully be self-explanatory. + ### Buttons For game files, there will be five buttons displayed on the bottom of the metadata editor window, and for folders there will be four. These are their functions: @@ -1457,9 +1741,9 @@ Cancels any changes and closes the window. This will remove any media files for the file or folder and also remove its entry from the gamelist.xml file, effectively deleting all metadata. The actual game file or folder will however _not_ be deleted. A prompt will be shown asking for confirmation. -**Delete** _(Files only)_ +**Delete** _(files only, and not for directories interpreted as files)_ -This will remove the actual game file, its gamelist.xml entry, its entry in any custom collections and its media files. A prompt will be shown asking for confirmation. The deletion of folders is not supported as that would potentially be a bit dangerous, instead use the appropriate operating system tools to handle deletion of folders. +This will remove the actual game file, its gamelist.xml entry, its entry in any custom collections and its media files. A prompt will be shown asking for confirmation. The deletion of folders is not supported as that would potentially be dangerous, instead use the appropriate operating system tools to handle deletion of directories. Likewise, for directories that are interpreted as files (this functionality is described earlier in this document) the Delete button is disabled. ## Game media viewer @@ -1467,7 +1751,9 @@ The game media viewer displays videos and images in fullscreen mode and is launc If a game video is available, this will be played automatically when launching the viewer. The _left_ and _right_ buttons are used to navigate betweeen the game media files. By default the video will continue to play when browsing the images, but this can be changed with a setting as described earlier in this document. -The other settings for the media viewer are similar to what is available for the screensavers; the audio can be enabled or disabled, the video can be stretched to fill the entire screen and scanlines and blur can be rendered on top of it. For screenshots, scanlines can be rendered. All these options are configurable via the _UI Settings_ menu. +The media viewer can display the _video, box cover, box back cover, title screen, screenshot_ and _miximage_. + +The other settings for the media viewer are similar to what is available for the screensavers; the audio can be enabled or disabled, the video can be stretched to fill the entire screen and scanlines and blur can be rendered on top of it. For screenshots and title screens, scanlines can be rendered. All these options are configurable via the _UI Settings_ menu. Pressing any other button than _left_ or _right_ closes the media viewer. @@ -1479,9 +1765,9 @@ Numerous options can be set for these screensavers, as detailed [here](USERGUIDE The Dim screensaver simply dims and desaturates the current view and Black will show a black screen. The Slideshow and Video screensavers are more interesting as they can display images and videos from your game collection. In addition to this, the Slideshow screensaver can be configured to only show images from a specified directory. -If the option **Enable screensaver controls** has been activated, you can manually toggle the screensaver from the system view by pressing the **Back** button. In addition to this, for the Slideshow and Video screensavers, the controls will allow you to jump to a new random image or video by using the **Left** and **Right** buttons on your keyboard or controller. It's also possible to launch the game currently displayed using the **A** button, and the **Y** button will jump to the game in its gamelist without starting it. +If the option _Enable screensaver controls_ has been activated, you can manually toggle the screensaver from the system view by pressing the _Back_ button. In addition to this, for the Slideshow and Video screensavers, the controls will allow you to jump to a new random image or video by using the _Left_ and _Right_ buttons on your keyboard or controller. It's also possible to launch the game currently displayed using the _A_ button, and the _Y_ button will jump to the game in its gamelist without starting it. -For the video and slideshow screensavers, an overlay can be enabled via the screensaver options that displays the game name and the game system as well as a star if the game is marked as a favorite. +For the video and slideshow screensavers, an overlay can be enabled via the screensaver options that displays the game name and the game system as well as a star symbol if the game is marked as a favorite. If the Video screensaver has been selected and there are no videos available, a fallback to the Dim screensaver will take place. The same is true for the Slideshow screensaver if no game images are available. @@ -1496,33 +1782,31 @@ The numerous collection settings available are covered [here](USERGUIDE.md#game- ### Automatic collections -The automatic collections are named **All games**, **Favorites** and **Last played**. The _All games_ collection simply groups all your game systems into one big list, _Favorites_ combines all your games marked as favorites from all your game systems, and _Last played_ is a list of the 50 last games you have launched. +The automatic collections are named _All games, Favorites_ and _Last played_. The _All games_ collection simply groups all your game systems into one big list, _Favorites_ combines all your games marked as favorites from all your game systems, and _Last played_ is a list of the 50 last games you have launched. -These automatic collections can be individually enabled or disabled by going to the main menu, selecting **Game collection settings** and then **Automatic game collections**. - -Note that you should only enable these collections if you really need them as they slow down the application quite a bit. By default these collections are therefore disabled. +These automatic collections can be individually enabled or disabled by going to the main menu, selecting _Game collection settings_ and then _Automatic game collections_. ### Custom collections -These are collections that you create yourself. Examples could be grouping in genres like `Shoot em up`, `Fighting games` etc. or perhaps a time period like `1980s`, `1990s` and so on. +These are collections that you create yourself. Examples could be grouping in genres like _Shoot em up_, _Fighting games_ etc. or perhaps a time period like _1980s_, _1990s_ and so on. -If the theme set supports it, you can create a custom collection directly from a theme. However, rbsimple-DE does not provide such themes as it's believed that grouping them together in a dedicated Collections system is a more elegant solution. Especially since the theme set would need to ship with an almost endless amount of collection themes for whatever categories the users would like to use for their game collections. +If the theme set supports it, you can create a custom collection directly from a theme. However, rbsimple-DE does not provide such themes as it's believed that grouping them together in a dedicated _Collections_ system is a more elegant solution. Especially since the theme set would need to ship with an almost endless amount of collection themes for whatever categories the users would like to use for their game collections. -So if you have enabled the option **Group unthemed custom collections** (it's enabled by default), any collections you add will show up in the special Collections system. Here you can access them just as you would access folders inside a regular gamelist. The amount of games per collection is shown in the description, and a random game is displayed each time you browse through the list (you can also quick jump to this random game by pressing the **Y** button). +So if you have enabled the option _Group unthemed custom collections_ (it's enabled by default), any collections you add will show up in the special _Collections_ system. Here you can access them just as you would access folders inside a regular gamelist. The amount of games per collection is shown in the description, and a random game is displayed each time you browse through the list. You can also quick jump to this random game by pressing the _Y_ button. To create a custom collection, go to **Game collection settings** from the main menu and choose **Create new custom collection**. -Choose a name and press enter, let's use the name `Platform` for this example. +Choose a name and press enter, let's use the name _Platform_ for this example. -The collection will now be created and the collection edit mode will be entered. You can now add games to the collection by navigating to any gamelist and pressing the **Y** button. Any number of games from any of your game systems can be added. A game can also be part of multiple collections, there is no real limit for this in ES-DE. +The collection will now be created and the collection edit mode will be entered. You can now add games to the collection by navigating to any gamelist and pressing the _Y_ button. Any number of games from any of your game systems can be added. A game can also be part of multiple collections, there is no real limit for this. -Removing games works the same way, just press **Y** to remove it if it's already present in your collection. You can do this either from the gamelist where the game was added, or from the collection itself. +Removing games works the same way, just press _Y_ to remove it if it's already present in your collection. You can do this either from the gamelist where the game was added, or from the collection itself. Only files can be part of collections, not folders. Games marked as hidden or to not be counted as games can't be added either. During the time that the collection is being edited, any game that is part of the collection is marked with a leading tick symbol in the game name. -When you are done adding games, you can either open the main menu and go to **Game collection settings** and select the **Finish editing 'Platform' collection** or you can open the game options menu and select the same option there. The latter works from within any game system, so you don't need to first navigate back to the collection that you're editing. +When you are done adding games, you can either open the main menu and go to **Game collection settings** and select the **Finish editing 'Platform' collection** or you can open the game options menu and select the same option there. The latter works from within any gamelist, so you don't need to first navigate back to the collection that you're editing. You can later add additional games to the collection by navigating to it, bringing up the game options menu and choosing **Add/remove games to this game collection**. @@ -1530,7 +1814,7 @@ You can later add additional games to the collection by navigating to it, bringi _Example of custom collections, here configured as genres._ ![alt text](images/es-de_custom_collections_editing.png "ES-DE Custom Collections") -_When editing a custom collection, a tick symbol will be displayed for any game that is already part of the collection._ +_When editing a custom collection, 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` @@ -1549,7 +1833,7 @@ The file contents is simply a list of ROM files, such as the following: %ROMPATH%/c64/Zorro.d64 ``` -Any changes to custom collections (for example adding or removing a game) will be immediately written to the corresponding collection configuration file. +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. @@ -1558,26 +1842,26 @@ If you're migrating from a previous version of EmulationStation that has absolut ## Themes -ES-DE is fully themeable, and although the application ships with the comprehensive rbsimple-DE theme set, you can replace it with a number of themes available from various locations on the Internet. +ES-DE is fully themeable, and although the application ships with the comprehensive rbsimple-DE and modern-DE theme sets, you can use any RetroPie-compatible EmulationStation themes as well. Just be aware that ES-DE has added additional theme functionality compared to the RetroPie fork and more still will be added in future versions. This means that you may not get the full benefits of the application if you're using a theme set which has not been updated specifically for ES-DE. Some themes may also look slightly different as bugs that were present in the RetroPie fork have been fixed. Also note that most Batocera and Recalbox themes are not compatible as these forks are quite different. -Somewhat confusingly the terms _theme_ and _theme set_ are used to refer to the same thing. The technically correct term for what you apply to the application to achieve a different look is actually _theme set_ as it's a collection of a number of themes for a number of game systems. The bundled rbsimple-DE is an example of such a theme set. But in this guide and in other EmulationStation resources on the Internet, the term theme is often used to refer to the same thing as a theme set. +As a side comment, the terms _theme_ and _theme set_ are both used when talking about theming. The technically correct term for what you apply to the application to achieve a different look is a _theme set_ as it's a collection of a number of themes for a number of game systems. But in practice it doesn't matter as both terms refer to the same thing and the terms are used interchangeably in this guide. -Note that the Desktop Edition fork has added additional features to the themes and more still will be added in future versions. This means that you may not get the full benefits of the application if you're using a different theme set which has not been updated specifically for ES-DE. But effort is spent trying to make ES-DE backward compatible with the available themes used by other EmulationStation versions. The exception to this are some themes made for the Recalbox and Batocera forks as they have added a lot of additional theme functionality that ES-DE does not support. -Themes are most easily installed to your ES-DE home directory, i.e. `~/.emulationstation/themes`. By just adding the theme sets 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. +Themes are most easily installed to your ES-DE home directory, i.e. `~/.emulationstation/themes`. By just adding the theme sets 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. -Although you can put additional themes in your ES-DE home directory, the default rbsimple-DE theme is located in your installation folder. For example this could be `/usr/share/emulationstation/themes` or `/usr/local/share/emulationstation/themes` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes` on macOS or `C:\Program Files\EmulationStation-DE\themes` on Windows. - -If you would like to customize the rbsimple-DE theme, simply make a copy of the complete rbsimple-DE directory to ~/.emulationstation/themes and then that copy of the theme will take precedence over the one in the application installation directory. - -In this example, we've downloaded the [Carbon](https://github.com/RetroPie/es-theme-carbon) and [Fundamental](https://github.com/G-rila/es-theme-fundamental) themes and uncompressed them to the ES-DE home directory: +For this example, we've downloaded the [Carbon](https://github.com/RetroPie/es-theme-carbon) and [Fundamental](https://github.com/G-rila/es-theme-fundamental) themes and uncompressed them to the ES-DE home directory: ``` ~/.emulationstation/themes/es-theme-carbon ~/.emulationstation/themes/es-theme-fundamental ``` -We now have three entries in the _Theme set_ selector in the UI settings menu, i.e. rbsimple-DE, es-theme-carbon and es-theme-fundamental. +We now have four entries in the Theme set selector in the UI settings menu, i.e. _rbsimple-DE, modern-DE, es-theme-carbon_ and _es-theme-fundamental_. + +Although you place additional themes in your ES-DE home directory, the default rbsimple-DE and modern-DE themes are located in the installation folder. For example this could be `/usr/share/emulationstation/themes` or `/usr/local/share/emulationstation/themes` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes` on macOS or `C:\Program Files\EmulationStation-DE\themes` on Windows. + +So if you would like to customize the rbsimple-DE or modern-DE theme sets, 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. + Here are some resources where additional theme sets can be downloaded. @@ -1590,8 +1874,7 @@ https://gitlab.com/recalbox/recalbox-themes https://wiki.batocera.org/themes ![alt text](images/es-de_ui_theme_support.png "ES-DE Theme Support") -_An example of a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme applied to ES-DE._ - +_This is a screenshot of the modern-DE theme that is bundled with ES-DE (in addition to the default rbsimple-DE theme)._ ## Custom event scripts @@ -1603,178 +1886,196 @@ The setup for event scripts is a bit technical, so refer to the [INSTALL.md](INS ## Portable installation (Windows only) -On Windows, ES-DE can be installed to and run from a removable media device such as a USB memory stick. Together with games and emulators this makes for a fully portable retro gaming solution. The setup is somewhat technical, refer to [INSTALL.md](INSTALL.md#portable-installation-on-windows) to see how it's done. +On Windows, ES-DE can be installed to and run from a removable media device such as a USB memory stick. Together with games and emulators this makes for a fully portable retrogaming solution. The setup is somewhat technical, refer to [INSTALL.md](INSTALL.md#portable-installation-on-windows) to see how it's done. ## Command line options -Refer to the [INSTALL.md](INSTALL.md#command-line-options) document for a list of the command line options per operating system. +See the [INSTALL.md](INSTALL.md#command-line-options) document for a list of the command line options per operating system. ## Supported game systems -**Note:** The following list is what the default es_systems.xml files and the rbsimple-DE theme supports. This theme set is very comprehensive, so if you're using another theme, it may be that some or many of these systems are not supported. ES-DE will still work but the game system will unthemed which looks very ugly. +**Note:** The following list is what the default es_systems.xml files and the rbsimple-DE and modern-DE themes support. These theme sets are very comprehensive, so if you're using another theme, it may be that some or many of these systems are not supported. ES-DE will still work but the game system will unthemed which looks very ugly. Note as well that the list and corresponding es_systems.xml templates may not reflect what is readily available for all supported operating system. This is especially true on Unix/Linux if installing RetroArch via the OS repository instead of using the Snap or Flatpak distributions (or compiling from source code) as the repository versions are normally quite crippled. -The column **Game system name** corresponds to the directory where you should put your game files, e.g. `~/ROMs/c64` or `~/ROMs/megadrive`. +The column **System name** corresponds to the directory where you should put your game files, e.g. `~/ROMs/c64` or `~/ROMs/megadrive`. This follows the RetroPie naming convention, with some additions for systems that are not supported on RetroPie. So if migrating from Batocera or Recalbox, check this carefully and rename your system folders as required or ES-DE will not be able to find your games. -Regional differences are handled by simply using the game system name corresponding to your region. For example for Sega Mega Drive, _megadrive_ would be used by most people in the world, although persons from North America would use _genesis_ instead. The same is true for _pcengine_ vs _tg16_ etc. This only affects the theme selection and the corresponding theme graphics, the same emulator and scraper settings are still used for the regional variants although that can of course be modified in the es_systems.xml file if you wish. +Regional differences are handled by simply using the game system name corresponding to your region. For example for Sega Mega Drive, _megadrive_ would be used by most people in the world, although persons from North America would use _genesis_ instead. The same is true for _pcengine_ vs _tg16_ etc. This only affects the theme selection and the corresponding theme graphics, the same emulator and scraper settings are still used for the regional variants although that can of course be customized in the es_systems.xml file if you wish. Sometimes the name of the console is (more or less) the same for multiple regions, and in those cases the region has been added as a suffix to the game system name. For instance `na` for North America has been added to `snes` (Super Nintendo) giving the system name `snesna`. The same goes for Japan, as in `megacd` and `megacdjp`. Again, this only affects the theme and theme graphics. -For the **Full name** column, text inside square brackets [] are comments and not part of the actual game system name. +For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name. -The **Default emulator** column shows the emulator configured in es_systems.xml, and for emulators that support multiple cores, the configured core is shown inside brackets. Any system marked with an asterisk (*) in this column requires additional system/BIOS ROMs to run, as should be explained in the emulator documentation. +The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup. -For additional details regarding which game file extensions are supported per system, refer to the es_systems.xml files [unix/es_systems.xml](resources/systems/unix/es_systems.xml), [macos/es_systems.xml](resources/systems/macos/es_systems.xml) and [windows/es_systems.xml](resources/systems/windows/es_systems.xml). Normally the extensions setup in these files should cover everything that the emulators support. +The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. -If you generated the ROMs directory structure when first starting ES-DE, the systeminfo.txt files located in each game system directory will also contain the information about the emulator core and supported file extensions. +The **Needs BIOS** column indicates if additional BIOS/system ROMs are required, as should be explained by the emulator documentation. Good starting points for such documentation are [https://docs.libretro.com](https://docs.libretro.com) and [https://docs.libretro.com/library/bios](https://docs.libretro.com/library/bios) -MAME emulation is a bit special as the choice of emulator or core depends on which ROM set you're using. It's recommended to go for the latest available set, as MAME is constantly improved with more complete and accurate emulation. Therefore the default `arcade` system is preconfigured to use the RetroArch core _MAME - Current_ which as the name implies will be the latest available MAME version. For really slow computers though, the 0.78 ROM set is a popular choice. To use this you either need to make a customized es_systems.xml file, or you can use the `mame` system which comes preconfigured for the RetroArch core _MAME 2003-Plus_ that is compatible with the 0.78 ROM set. There are other alternatives as well such as _MAME 2010_ that uses the 0.139 ROM set but this is generally not recommended. +For additional details regarding which game file extensions are supported per system, refer to the es_systems.xml files [unix/es_systems.xml](resources/systems/unix/es_systems.xml), [macos/es_systems.xml](resources/systems/macos/es_systems.xml) and [windows/es_systems.xml](resources/systems/windows/es_systems.xml). Normally the extensions setup in these files should cover everything that the emulators support. For systems that have alternative emulators defined, the list of extensions is a combination of what is supported by all the emulators. This approach is necessary as you want to be able to see all games for each system while potentially testing and switching between different emulators, either system-wide or on a per game basis. -There are other MAME versions and derivates available as well such as MAME4ALL, AdvanceMAME, FinalBurn Alpha and FinalBurn Neo but it's beyond the scope of this document to describe those in detail. For more information, refer to the [RetroPie arcade documentation](https://retropie.org.uk/docs/Arcade) which has a good overview of the various MAME alternatives. +If you generated the ROMs directory structure when first starting ES-DE, the systeminfo.txt files located in each game system directory will also contain information about the emulators and supported file extensions. + +For CD-based systems it's generally recommended to use CHD files (extension .chd) as this saves space due to compression compared to BIN/CUE, IMG, ISO etc. The CHD format is also supported by most emulators. You can convert to CHD from various formats using the MAME `chdman` utility, for example `chdman createcd -i mygame.iso -o mygame.chd`. Sometimes chdman has issues converting from the IMG and BIN formats, and in this case it's possible to first convert to ISO using `ccd2iso`, such as `ccd2iso mygame.img mygame.iso` or in the case of BIN files `ccd2iso mygame.bin mygame.iso`. + +MAME emulation is a bit special as the choice of emulator depends on which ROM set you're using. It's recommended to go for the latest available set, as MAME is constantly improved with more complete and accurate emulation. Therefore the `arcade` system is configured to use _MAME - Current_ by default, which as the name implies will be the latest available MAME version. But if you have a really slow computer you may want to use another ROM set such as the popular 0.78. In this case, you can either select _MAME 2003-Plus_ as an alternative emulator, or you can use the `mame` system which comes configured with this emulator as the default. There are more MAME versions available as alternative emulators, as you can see in the table below. + +There are also other MAME forks and derivates available such as MAME4ALL, AdvanceMAME, FinalBurn Alpha and FinalBurn Neo but it's beyond the scope of this document to describe those in detail. For more information, refer to the [RetroPie arcade documentation](https://retropie.org.uk/docs/Arcade) which has a good overview of the various MAME alternatives. + +In general .zip or .7z files are recommended for smaller-sized games like those from older systems (assuming the emulator supports it). But for CD-based systems it's not a good approach as uncompressing the larger CD images takes quite some time, leading to slow game launches. As explained above, converting CD images to CHD files is a better solution for achieving file compression while still enjoying fast game launches. Consider the table below a work in progress as it's obvioulsy not fully populated yet! -| Game system name | Full name | Default emulator | Recommended game setup | -| :-------------------- | :--------------------------------------------- | :-------------------------------- | :----------------------------------- | -| 3do | 3DO | | | -| 64dd | Nintendo 64DD | RetroArch (Mupen64Plus-Next on Unix and Windows, ParaLLEl N64 on macOS) | | -| ags | Adventure Game Studio game engine | | | -| amiga | Commodore Amiga | RetroArch (P-UAE)* | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disk, or in separate folder with .m3u playlist if multi-disc | -| amiga600 | Commodore Amiga 600 | RetroArch (P-UAE)* | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disk, or in separate folder with .m3u playlist if multi-disc | -| amiga1200 | Commodore Amiga 1200 | RetroArch (P-UAE)* | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disk, or in separate folder with .m3u playlist if multi-disc | -| amigacd32 | Commodore Amiga CD32 | | | -| amstradcpc | Amstrad CPC | | | -| apple2 | Apple II | | | -| apple2gs | Apple IIGS | | | -| arcade | Arcade | RetroArch (MAME - Current)* | Single archive file following MAME name standard in root folder | -| astrocade | Bally Astrocade | | | -| atari2600 | Atari 2600 | RetroArch (Stella on macOS and Windows, Stella 2014 on Unix) | Single archive or ROM file in root folder | -| atari5200 | Atari 5200 | | | -| atari7800 | Atari 7800 ProSystem | | | -| atari800 | Atari 800 | | | -| atarijaguar | Atari Jaguar | | | -| atarijaguarcd | Atari Jaguar CD | | | -| atarilynx | Atari Lynx | | | -| atarist | Atari ST [also STE and Falcon] | | | -| atarixe | Atari XE | | | -| atomiswave | Atomiswave | | | -| bbcmicro | BBC Micro | | | -| c64 | Commodore 64 | RetroArch (VICE x64sc, accurate) | Single disk, tape or cartridge image in root folder and/or multi-disc images in separate folder | -| cavestory | Cave Story (NXEngine) | | | -| cdtv | Commodore CDTV | | | -| chailove | ChaiLove game engine | | | -| channelf | Fairchild Channel F | | | -| coco | Tandy Color Computer | | | -| colecovision | ColecoVision | | | -| daphne | Daphne Arcade Laserdisc Emulator | | | -| desktop | Desktop applications | N/A | | -| doom | Doom | | | -| dos | DOS (PC) | RetroArch (DOSBox-core) | In separate folder (one folder per game, with complete file structure retained) | -| dragon32 | Dragon 32 | | | -| dreamcast | Sega Dreamcast | | | -| famicom | Nintendo Family Computer | RetroArch (Nestopia UE) | Single archive or ROM file in root folder | -| fba | FinalBurn Alpha | RetroArch (FB Alpha 2012)* | Single archive file following MAME name standard in root folder | -| fbneo | FinalBurn Neo | RetroArch (FinalBurn Neo)* | Single archive file following MAME name standard in root folder | -| fds | Nintendo Famicom Disk System | RetroArch (Nestopia UE)* | Single archive or ROM file in root folder | -| gameandwatch | Nintendo Game and Watch | | | -| gamegear | Sega Game Gear | | | -| gb | Nintendo Game Boy | | | -| gba | Nintendo Game Boy Advance | | | -| gbc | Nintendo Game Boy Color | | | -| gc | Nintendo GameCube | | | -| genesis | Sega Genesis | RetroArch (Genesis Plus GX) | Single archive or ROM file in root folder | -| gx4000 | Amstrad GX4000 | | | -| intellivision | Mattel Electronics Intellivision | | | -| kodi | Kodi home theatre software | N/A | | -| lutris | Lutris open gaming platform | Lutris application (Unix only) | Shell script in root folder | -| lutro | Lutro game engine | | | -| macintosh | Apple Macintosh | | | -| mame | Multiple Arcade Machine Emulator | RetroArch (MAME 2003-Plus)* | Single archive file following MAME name standard in root folder | -| mame-advmame | AdvanceMAME | | Single archive file following MAME name standard in root folder | -| mame-mame4all | MAME4ALL | | Single archive file following MAME name standard in root folder | -| mastersystem | Sega Master System | RetroArch (Genesis Plus GX) | Single archive or ROM file in root folder | -| megacd | Sega Mega-CD | | | -| megacdjp | Sega Mega-CD [Japan] | | | -| megadrive | Sega Mega Drive | RetroArch (Genesis Plus GX) | Single archive or ROM file in root folder | -| mess | Multi Emulator Super System | | | -| moonlight | Moonlight game streaming | | | -| moto | Thomson MO/TO series | RetroArch (Theodore) | | -| msx | MSX | RetroArch (blueMSX) | | -| msx1 | MSX1 | RetroArch (blueMSX) | | -| msx2 | MSX2 | RetroArch (blueMSX) | | -| msxturbor | MSX Turbo R | RetroArch (blueMSX) | | -| multivision | Othello Multivision | RetroArch (Gearsystem) | | -| naomi | Sega NAOMI | RetroArch (Flycast) | | -| naomigd | Sega NAOMI GD-ROM | RetroArch (Flycast) | | -| n3ds | Nintendo 3DS | RetroArch (Citra) | | -| n64 | Nintendo 64 | RetroArch (Mupen64Plus-Next on Unix and Windows, ParaLLEl N64 on macOS) | Single archive or ROM file in root folder | -| nds | Nintendo DS | | | -| neogeo | SNK Neo Geo | RetroArch (FinalBurn Neo)* | Single archive file following MAME name standard in root folder | -| neogeocd | SNK Neo Geo CD | RetroArch (NeoCD)* | Single archive in root folder (which includes the CD image and ripped audio) | -| neogeocdjp | SNK Neo Geo CD [Japan] | RetroArch (NeoCD)* | Single archive in root folder (which includes the CD image and ripped audio) | -| nes | Nintendo Entertainment System | RetroArch (Nestopia UE) | Single archive or ROM file in root folder | -| ngp | SNK Neo Geo Pocket | | | -| ngpc | SNK Neo Geo Pocket Color | | | -| odyssey2 | Magnavox Odyssey2 | | | -| openbor | OpenBOR game engine | | | -| oric | Tangerine Computer Systems Oric | | | -| palm | Palm OS | | | -| pc | IBM PC | RetroArch (DOSBox-core) | In separate folder (one folder per game, with complete file structure retained) | -| pc88 | NEC PC-8800 series | RetroArch (QUASI88) | | -| pc98 | NEC PC-9800 series | RetroArch (Neko Project II Kai) | | -| pcengine | NEC PC Engine | RetroArch (Beetle PCE) | Single archive or ROM file in root folder | -| pcenginecd | NEC PC Engine CD | RetroArch (Beetle PCE) | | -| pcfx | NEC PC-FX | | | -| pokemini | Nintendo Pokémon Mini | | | -| ports | Ports | N/A | Shell/batch script in separate folder (possibly combined with game data) | -| ps2 | Sony PlayStation 2 | | | -| ps3 | Sony PlayStation 3 | | | -| ps4 | Sony PlayStation 4 | | | -| psp | Sony PlayStation Portable | | | -| psvita | Sony PlayStation Vita | | | -| psx | Sony PlayStation | | | -| residualvm | ResidualVM game engine | | | -| samcoupe | SAM Coupé | | | -| satellaview | Nintendo Satellaview | | | -| saturn | Sega Saturn | RetroArch (Beetle Saturn) | | -| saturnjp | Sega Saturn [Japan] | RetroArch (Beetle Saturn) | | -| scummvm | ScummVM game engine | RetroArch (ScummVM) | In separate folder (one folder per game, with complete file structure retained) | -| sega32x | Sega Mega Drive 32X | RetroArch (PicoDrive) | Single archive or ROM file in root folder | -| sega32xjp | Sega Super 32X [Japan] | RetroArch (PicoDrive) | Single archive or ROM file in root folder | -| sega32xna | Sega Genesis 32X [North America] | RetroArch (PicoDrive) | Single archive or ROM file in root folder | -| segacd | Sega CD | | | -| sg-1000 | Sega SG-1000 | | | -| snes | Nintendo SNES (Super Nintendo) | RetroArch (Snes9x - Current) | Single archive or ROM file in root folder | -| snesna | Nintendo SNES (Super Nintendo) [North America] | RetroArch (Snes9x - Current) | Single archive or ROM file in root folder | -| solarus | Solarus game engine | | | -| spectravideo | Spectravideo | | | -| steam | Valve Steam | Steam application | Shell script/batch file in root folder | -| stratagus | Stratagus game engine | | | -| sufami | Bandai SuFami Turbo | | | -| supergrafx | NEC SuperGrafx | | | -| switch | Nintendo Switch | Yuzu (Linux and Windows only, not available on macOS) | | -| tanodragon | Tano Dragon | | | -| tg16 | NEC TurboGrafx-16 | RetroArch (Beetle PCE) | Single archive or ROM file in root folder | -| tg-cd | NEC TurboGrafx-CD | RetroArch (Beetle PCE) | | -| ti99 | Texas Instruments TI-99 | | | -| tic80 | TIC-80 game engine | | | -| to8 | Thomson TO8 | RetroArch (Theodore) | | -| trs-80 | Tandy TRS-80 | | | -| uzebox | Uzebox | | | -| vectrex | Vectrex | | | -| videopac | Philips Videopac G7000 (Magnavox Odyssey2) | | | -| virtualboy | Nintendo Virtual Boy | | | -| wii | Nintendo Wii | | | -| wiiu | Nintendo Wii U | | | -| wonderswan | Bandai WonderSwan | | | -| wonderswancolor | Bandai WonderSwan Color | | | -| x1 | Sharp X1 | RetroArch (x1) | Single archive or ROM file in root folder | -| x68000 | Sharp X68000 | | | -| xbox | Microsoft Xbox | | | -| xbox360 | Microsoft Xbox 360 | | | -| zmachine | Infocom Z-machine | | | -| zx81 | Sinclair ZX81 | | | -| zxspectrum | Sinclair ZX Spectrum | | | +Default emulator/Alternative emulators columns: \ +**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs manual Path environment variable entry + +All emulators are RetroArch cores unless marked as **(Standalone**) + +| System name | Full name | Default emulator | Alternative emulators | Needs BIOS | Recommended game setup | +| :-------------------- | :--------------------------------------------- | :-------------------------------- | :-------------------------------- | :----------- | :----------------------------------- | +| 3do | 3DO | 4DO | | | | +| 64dd | Nintendo 64DD | Mupen64Plus-Next [UW],
ParaLLEl N64 [M] | ParaLLEl N64 [UW],
Mupen64Plus **(Standalone)** [M] | | | +| ags | Adventure Game Studio Game Engine | _Placeholder_ | | | | +| amiga | Commodore Amiga | PUAE | | Yes | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disc, or in separate folder with .m3u playlist if multi-disc | +| amiga600 | Commodore Amiga 600 | PUAE | | Yes | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disc, or in separate folder with .m3u playlist if multi-disc | +| amiga1200 | Commodore Amiga 1200 | PUAE | | Yes | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disc, or in separate folder with .m3u playlist if multi-disc | +| amigacd32 | Commodore Amiga CD32 | PUAE | | | | +| amstradcpc | Amstrad CPC | Caprice32 | CrocoDS | | | +| android | Google Android | _Placeholder_ | | | | +| apple2 | Apple II | _Placeholder_ | | | | +| apple2gs | Apple IIGS | _Placeholder_ | | | | +| arcade | Arcade | MAME - Current | MAME 2000,
MAME 2003-Plus,
MAME 2010,
FinalBurn Neo,
FB Alpha 2012 | Depends | Single archive file following MAME name standard in root folder | +| astrocade | Bally Astrocade | _Placeholder_ | | | | +| atari2600 | Atari 2600 | Stella | Stella 2014 | No | Single archive or ROM file in root folder | +| atari5200 | Atari 5200 | Atari800 | | | | +| atari7800 | Atari 7800 ProSystem | ProSystem | | | | +| atari800 | Atari 800 | Atari800 | | | | +| atarijaguar | Atari Jaguar | Virtual Jaguar | | | | +| atarijaguarcd | Atari Jaguar CD | Virtual Jaguar | | | | +| atarilynx | Atari Lynx | Handy | Beetle Lynx | | | +| atarist | Atari ST [also STE and Falcon] | Hatari | | | | +| atarixe | Atari XE | Atari800 | | | | +| atomiswave | Atomiswave | Flycast | | | | +| bbcmicro | BBC Micro | _Placeholder_ | | | | +| c64 | Commodore 64 | VICE x64sc Accurate | VICE x64 Fast,
VICE x64 SuperCPU,
VICE x128,
Frodo | No | Single disk, tape or cartridge image in root folder and/or multi-disc images in separate folder | +| cavestory | Cave Story (NXEngine) | NXEngine | | | | +| cdimono1 | Philips CD-i | _Placeholder_ | | | | +| cdtv | Commodore CDTV | _Placeholder_ | | | | +| chailove | ChaiLove Game Engine | ChaiLove | | | | +| channelf | Fairchild Channel F | FreeChaF | | | | +| coco | Tandy Color Computer | _Placeholder_ | | | | +| colecovision | ColecoVision | blueMSX | | | | +| daphne | Daphne Arcade LaserDisc Emulator | _Placeholder_ | | | | +| desktop | Desktop Applications | N/A | | No | | +| doom | Doom | PrBoom | | | | +| dos | DOS (PC) | DOSBox-Core | DOSBox-Pure,
DOSBox-SVN,
DOSBox Staging **(Standalone)** [UMW*] | No | In separate folder (one folder per game with complete file structure retained) | +| dragon32 | Dragon 32 | _Placeholder_ | | | | +| dreamcast | Sega Dreamcast | Flycast | | | | +| epic | Epic Games Store | Epic Games Store application **(Standalone)** | | No | Shell script/batch file in root folder | +| famicom | Nintendo Family Computer | Nestopia UE | FCEUmm,
Mesen,
QuickNES | No | Single archive or ROM file in root folder | +| fba | FinalBurn Alpha | FB Alpha 2012 | FB Alpha 2012 Neo Geo,
FB Alpha 2012 CPS-1,
FB Alpha 2012 CPS-2,
FB Alpha 2012 CPS-3 | Yes | Single archive file following MAME name standard in root folder | +| fbneo | FinalBurn Neo | FinalBurn Neo | | Yes | Single archive file following MAME name standard in root folder | +| fds | Nintendo Famicom Disk System | Nestopia UE | | Yes | Single archive or ROM file in root folder | +| gameandwatch | Nintendo Game and Watch | GW | | | | +| gamegear | Sega Game Gear | Gearsystem | SMS Plus GX,
Genesis Plus GX,
Genesis Plus GX Wide | | | +| gb | Nintendo Game Boy | SameBoy | Gambatte,
Gearboy,
TGB Dual,
Mesen-S,
bsnes | | | +| gba | Nintendo Game Boy Advance | mGBA | VBA-M,
VBA Next,
gpSP | | | +| gbc | Nintendo Game Boy Color | SameBoy | Gambatte,
Gearboy,
TGB Dual,
Mesen-S,
bsnes | | | +| gc | Nintendo GameCube | Dolphin | | | | +| genesis | Sega Genesis | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm | No | Single archive or ROM file in root folder | +| gx4000 | Amstrad GX4000 | _Placeholder_ | | | | +| intellivision | Mattel Electronics Intellivision | FreeIntv | | | | +| j2me | Java 2 Micro Edition (J2ME) | SquirrelJME | | Yes | Single JAR file in root folder | +| kodi | Kodi Home Theatre Software | N/A | | No | | +| lutris | Lutris Open Gaming Platform | Lutris application **(Standalone)** [U] | | No | Shell script in root folder | +| lutro | Lutro Game Engine | Lutro | | | | +| macintosh | Apple Macintosh | _Placeholder_ | | | | +| mame | Multiple Arcade Machine Emulator | MAME 2003-Plus | MAME 2000,
MAME 2010,
MAME - Current,
FinalBurn Neo,
FB Alpha 2012 | Depends | Single archive file following MAME name standard in root folder | +| mame-advmame | AdvanceMAME | _Placeholder_ | | Depends | Single archive file following MAME name standard in root folder | +| mame-mame4all | MAME4ALL | _Placeholder_ | | Depends | Single archive file following MAME name standard in root folder | +| mastersystem | Sega Master System | Genesis Plus GX | Genesis Plus GX Wide,
SMS Plus GX,
Gearsystem,
PicoDrive | No | Single archive or ROM file in root folder | +| megacd | Sega Mega-CD | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive | | | +| megacdjp | Sega Mega-CD [Japan] | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive | | | +| megadrive | Sega Mega Drive | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm | No | Single archive or ROM file in root folder | +| mess | Multi Emulator Super System | MESS 2015 | | | | +| moonlight | Moonlight Game Streaming | _Placeholder_ | | | | +| moto | Thomson MO/TO Series | Theodore | | | | +| msx | MSX | blueMSX | fMSX | | | +| msx1 | MSX1 | blueMSX | fMSX | | | +| msx2 | MSX2 | blueMSX | fMSX | | | +| msxturbor | MSX Turbo R | blueMSX | | | | +| multivision | Othello Multivision | Gearsystem | | | | +| naomi | Sega NAOMI | Flycast | | | | +| naomigd | Sega NAOMI GD-ROM | Flycast | | | | +| n3ds | Nintendo 3DS | Citra [UW] | Citra 2018 [UW] | | | +| n64 | Nintendo 64 | Mupen64Plus-Next [UW],
ParaLLEl N64 [M] | ParaLLEl N64 [UW],
Mupen64Plus **(Standalone)** [M] | No | Single archive or ROM file in root folder | +| nds | Nintendo DS | DeSmuME | DeSmuME 2015,
melonDS | | | +| neogeo | SNK Neo Geo | FinalBurn Neo | | Yes | Single archive file following MAME name standard in root folder | +| neogeocd | SNK Neo Geo CD | NeoCD | | Yes | Single archive in root folder (which includes the CD image and ripped audio) | +| neogeocdjp | SNK Neo Geo CD [Japan] | NeoCD | | Yes | Single archive in root folder (which includes the CD image and ripped audio) | +| nes | Nintendo Entertainment System | Nestopia UE | FCEUmm,
Mesen,
QuickNES | No | Single archive or ROM file in root folder | +| ngp | SNK Neo Geo Pocket | Beetle NeoPop | RACE | | | +| ngpc | SNK Neo Geo Pocket Color | Beetle NeoPop | RACE | | | +| odyssey2 | Magnavox Odyssey2 | O2EM | | | | +| openbor | OpenBOR Game Engine | _Placeholder_ | | | | +| oric | Tangerine Computer Systems Oric | _Placeholder_ | | | | +| palm | Palm OS | Mu | | | | +| pc | IBM PC | DOSBox-Core | DOSBox-Pure,
DOSBox-SVN,
DOSBox Staging **(Standalone)** [UMW*] | No | In separate folder (one folder per game with complete file structure retained) | +| pc88 | NEC PC-8800 Series | QUASI88 | | | | +| pc98 | NEC PC-9800 Series | Neko Project II Kai | Neko Project II | | | +| pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST | No | Single archive or ROM file in root folder | +| pcenginecd | NEC PC Engine CD | Beetle PCE | Beetle PCE FAST | Yes | | +| pcfx | NEC PC-FX | Beetle PC-FX | | | | +| pokemini | Nintendo Pokémon Mini | PokeMini | | No | | +| ports | Ports | N/A | | No | Shell/batch script in separate folder (possibly combined with game data) | +| ps2 | Sony PlayStation 2 | PCSX2 [UW],
PCSX2 **(Standalone)** [M] | PCSX2 **(Standalone)** [UW] | Yes | | +| ps3 | Sony PlayStation 3 | RPCS3 **(Standalone)** [UW*] | | Yes | In separate folder (one folder per game with complete file structure retained, renamed to the .ps3dir extension) | +| ps4 | Sony PlayStation 4 | _Placeholder_ | | | | +| psp | Sony PlayStation Portable | PPSSPP | | | | +| psvita | Sony PlayStation Vita | _Placeholder_ | | | | +| psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,
PCSX ReARMed,
DuckStation | Yes | .chd file in root folder for single-disc games, .m3u playlist in root folder for multi-disc games | +| samcoupe | SAM Coupé | SimCoupe | | | | +| satellaview | Nintendo Satellaview | Snes9x - Current | Snes9x 2010,
bsnes,
bsnes-mercury Accuracy,
Mesen-S | | | +| saturn | Sega Saturn | Beetle Saturn | Kronos [UW],
YabaSanshiro [UW],
Yabause | | | +| saturnjp | Sega Saturn [Japan] | Beetle Saturn | Kronos [UW],
YabaSanshiro [UW],
Yabause | | | +| scummvm | ScummVM Game Engine | ScummVM | | No | In separate folder (one folder per game with complete file structure retained) | +| sega32x | Sega Mega Drive 32X | PicoDrive | | No | Single archive or ROM file in root folder | +| sega32xjp | Sega Super 32X [Japan] | PicoDrive | | No | Single archive or ROM file in root folder | +| sega32xna | Sega Genesis 32X [North America] | PicoDrive | | No | Single archive or ROM file in root folder | +| segacd | Sega CD | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive | | | +| sg-1000 | Sega SG-1000 | Gearsystem | Genesis Plus GX,
Genesis Plus GX Wide,
blueMSX | | | +| snes | Nintendo SNES (Super Nintendo) | Snes9x - Current | Snes9x 2010,
bsnes,
bsnes-mercury Accuracy,
Beetle Supafaust [UW],
Mesen-S | No | Single archive or ROM file in root folder | +| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,
bsnes,
bsnes-mercury Accuracy,
Beetle Supafaust [UW],
Mesen-S | No | Single archive or ROM file in root folder | +| solarus | Solarus Game Engine | _Placeholder_ | | | | +| spectravideo | Spectravideo | blueMSX | | | | +| steam | Valve Steam | Steam application **(Standalone)** | | No | Shell script/batch file in root folder | +| stratagus | Stratagus Game Engine | _Placeholder_ | | | | +| sufami | Bandai SuFami Turbo | Snes9x - Current | Snes9x 2010,
bsnes,
bsnes-mercury Accuracy | | | +| supergrafx | NEC SuperGrafx | Beetle SuperGrafx | Beetle PCE | | | +| switch | Nintendo Switch | Yuzu **(Standalone)** [UW] | | Yes | | +| symbian | Symbian | _Placeholder_ | | | | +| tanodragon | Tano Dragon | _Placeholder_ | | | | +| tg16 | NEC TurboGrafx-16 | Beetle PCE | Beetle PCE FAST | No | Single archive or ROM file in root folder | +| tg-cd | NEC TurboGrafx-CD | Beetle PCE | Beetle PCE FAST | Yes | | +| ti99 | Texas Instruments TI-99 | _Placeholder_ | | | | +| tic80 | TIC-80 Game Engine | _Placeholder_ | | | | +| to8 | Thomson TO8 | Theodore | | | | +| trs-80 | Tandy TRS-80 | _Placeholder_ | | | | +| uzebox | Uzebox | Uzem | | | | +| vectrex | Vectrex | vecx | | | | +| vic20 | Commodore VIC-20 | VICE xvic | | | Single disk, tape or cartridge image in root folder | +| videopac | Philips Videopac G7000 | O2EM | | | | +| virtualboy | Nintendo Virtual Boy | Beetle VB | | | | +| wii | Nintendo Wii | Dolphin | | | | +| wiiu | Nintendo Wii U | _Placeholder_ | | | | +| wonderswan | Bandai WonderSwan | Beetle Cygne | | | | +| wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | | | | +| x1 | Sharp X1 | x1 | | | Single archive or ROM file in root folder | +| x68000 | Sharp X68000 | PX68k | | | | +| xbox | Microsoft Xbox | xemu **(Standalone)** [UW*] | | Yes | Single ISO file in root folder | +| xbox360 | Microsoft Xbox 360 | xenia **(Standalone)** [W*] | | No | | +| zmachine | Infocom Z-machine | _Placeholder_ | | | | +| zx81 | Sinclair ZX81 | EightyOne | | | | +| zxspectrum | Sinclair ZX Spectrum | Fuse | | | |