diff --git a/CHANGELOG.md b/CHANGELOG.md index 6717f701b..47e7f494e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,9 @@ [[_TOC_]] -## Version 1.1.0 (in development) +## Version 1.1.0 -**Release date:** TBD +**Release date:** 2021-08-10 ### Release overview diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6223d218c..1782ef565 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -91,7 +91,7 @@ To see which features have been implemented in previous versions, please refer t The visual appearance aspect of the coding style is automatically applied using clang-format, so to understand the exact formatting rules, refer to the .clang-format file in the root of the repository. -Due to this approach, all code changes must be auto-formatted before they are committed. You can read in [INSTALL-DEV.md](INSTALL-DEV.md#using-clang-format-for-automatic-code-formatting) how clang-format is installed and used. +Due to this approach, all code changes must be auto-formatted before they are committed. You can read in [INSTALL.md](INSTALL.md#using-clang-format-for-automatic-code-formatting) how clang-format is installed and used. But as clang-format won't change the actual code content or fix all code style choices, here are some additional key points: diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 011efc852..041fb5670 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -162,11 +162,11 @@ cmake . make ``` -By default the master branch will be used, which is where development takes place. To instead build the latest stable release, switch to the `stable` branch: +By default the master branch will be used, which is where development takes place. To instead build a stable release, switch to the `stable-x.x` branch for the version, for example: ``` cd emulationstation-de -git checkout stable +git checkout stable-1.1 cmake . make ``` @@ -493,11 +493,11 @@ cmake . make ``` -By default the master branch will be used, which is where the development takes place. To instead build the latest stable release, switch to the `stable` branch: +By default the master branch will be used, which is where development takes place. To instead build a stable release, switch to the `stable-x.x` branch for the version, for example: ``` cd emulationstation-de -git checkout stable +git checkout stable-1.1 cmake . make ``` @@ -890,11 +890,11 @@ This works the same as on Unix or macOS, just run the following: git clone https://gitlab.com/leonstyhre/emulationstation-de.git ``` -By default the master branch will be used, which is where development takes place. To instead build the latest stable release, switch to the `stable` branch: +By default the master branch will be used, which is where development takes place. To instead build a stable release, switch to the `stable-x.x` branch for the version, for example: ``` cd emulationstation-de -git checkout stable +git checkout stable-1.1 ``` **Setup the include directories:** diff --git a/INSTALL.md b/INSTALL.md index 09fc6f005..59b72a6af 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -2,8 +2,6 @@ **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. -Also note that this document is only relevant for the latest stable ES-DE release, if you would like to see the documentation for the current development version, refer to [INSTALL-DEV.md](INSTALL-DEV.md) instead. - Table of contents: [[_TOC_]] @@ -14,66 +12,113 @@ ES-DE is developed and compiled using Clang/LLVM and GCC on Unix, Clang/LLVM on CMake is the build system for all the supported operating systems, used in conjunction with `make` on Unix and macOS and `nmake` and `make` on Windows. Xcode on macOS or Visual Studio on Windows are not required for building ES-DE and they have not been used during the development. The only exception is notarization of codesigned macOS packages which require the `altool` and `stapler` binaries that come bundled with Xcode. +For automatic code formatting [clang-format](https://clang.llvm.org/docs/ClangFormat.html) is used. + Any code editor can be used of course, but I recommend [VSCode](https://code.visualstudio.com). ## Building on Unix -The code has some dependencies. For building, you'll need CMake and development packages for cURL, FreeImage, FreeType, libVLC, pugixml, SDL2 and RapidJSON. +There are some dependencies that need to be fulfilled in order to build ES-DE. These are detailed per operating system below. -**Installing dependencies:** - -**On Debian/Ubuntu** +**Debian/Ubuntu** All of the required packages can be installed with apt-get: ``` -sudo apt-get install build-essential git cmake libsdl2-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev rapidjson-dev libasound2-dev vlc libvlc-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 rapidjson-dev libasound2-dev libgl1-mesa-dev ``` -**On Fedora** +If building with the optional VLC video player, the following packages are also needed: +``` +sudo apt-get install vlc libvlc-dev +``` -First add the RPM Fusion repository which is required for VLC. Go to [https://rpmfusion.org/Configuration](https://rpmfusion.org/Configuration) and download the .rpm package for the free repository, then install it such as this: +**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: ``` sudo dnf install ./rpmfusion-free-release-33.noarch.rpm +sudo dnf install vlc vlc-devel ``` -Then use dnf to install all the required packages: -``` -sudo dnf install gcc-c++ cmake SDL2-devel freeimage-devel freetype-devel curl-devel pugixml-devel rapidjson-devel alsa-lib-devel mesa-libGL-devel vlc vlc-devel -``` - -**On Manjaro** +**Manjaro** Use pacman to install all the required packages: ``` -pacman -S gcc make cmake pkgconf sdl2 freeimage freetype2 pugixml rapidjson vlc +sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml rapidjson ``` -**On FreeBSD** +If building with the optional VLC video player, the following package is also needed: +``` +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 +``` + +If building with the optional VLC video player, the following packages are also needed: +``` +sudo apt-get install vlc libvlc-dev +``` + +To build with CEC support you also need to install these packages: +``` +sudo apt-get install libcec-dev libp8-platform-dev +``` + +**FreeBSD** Use pkg to install the dependencies: ``` -pkg install git pkgconf cmake sdl2 freeimage pugixml rapidjson vlc +pkg install git pkgconf cmake sdl2 ffmpeg freeimage pugixml rapidjson ``` -Clang/LLVM and cURL should already be installed in the base OS image. +If building with the optional VLC video player, the following package is also needed: +``` +pkg install vlc +``` -**On NetBSD** +Clang/LLVM and cURL should already be included in the base OS installation. + +**NetBSD** Use pkgin to install the dependencies: ``` -pkgin install git cmake pkgconf SDL2 freeimage pugixml rapidjson vlc +pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage pugixml rapidjson ``` -NetBSD ships with GCC by default, and although you should be able to install and use Clang/LLVM, it's probably easier to just stick to the default compiler environment. +If building with the optional VLC video player, the following package is also needed: +``` +pkgin vlc +``` -**On OpenBSD** +NetBSD ships with GCC by default, and although you should be able to use Clang/LLVM, it's probably easier to just stick to the default compiler environment. The reason why the clang package needs to be installed is to get clang-format onto the system. + +**OpenBSD** Use pkg_add to install the dependencies: ``` -pkg_add cmake pkgconf sdl2 freeimage vlc +pkg_add clang-tools-extra cmake pkgconf sdl2 ffmpeg freeimage +``` + +If building with the optional VLC video player, the following package is also needed: +``` +pkg_add vlc ``` In the same manner as for FreeBSD, Clang/LLVM and cURL should already be installed by default. @@ -115,16 +160,22 @@ cmake . make ``` -By default the master branch will be used, which is where the development takes place. To instead build the latest stable release, switch to the `stable` branch: +By default the master branch will be used, which is where development takes place. To instead build a stable release, switch to the `stable-x.x` branch for the version, for example: ``` cd emulationstation-de -git checkout stable +git checkout stable-1.1 cmake . make ``` -To create a debug build, run this instead: +To build ES-DE with the VLC video player in addition to the default FFmpeg player, enable the VLC_PLAYER option, for example: +``` +cmake -DVLC_PLAYER=on . +make +``` + +To create a debug build, run this: ``` cmake -DCMAKE_BUILD_TYPE=Debug . make @@ -173,22 +224,29 @@ scan-build cmake -DCMAKE_BUILD_TYPE=Debug . scan-build make -j6 ``` -You open the report with the `scan-view` command which lets you browse it using your web browser. Note that the compilation time is much higher when using the static analyzer compared to a normal compilation. As well this tool generates a lot of extra files and folders in the build tree, so it may make sense to run it in a separate copy of the source folder to avoid having to clean up all this extra data when the analysis has been completed. +You open the report with the `scan-view` command which lets you read it using your web browser. Note that the compilation time is much longer when using the static analyzer compared to a normal build. As well this tool generates a lot of extra files and folders in the build tree, so it may make sense to run it in a separate copy of the source folder to avoid having to clean up all this extra data when the analysis has been completed. -To build ES with CEC support, add the corresponding option, for example: +An even more advanced static analyzer is `clang-tidy`, to use it first make sure it's installed on your system and then run the following: +``` +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 CEC support, enable the corresponding option, for example: ``` -cmake -DCMAKE_BUILD_TYPE=Debug -DCEC=on . +cmake -DCEC=on . make ``` -I have however not been able to test the CEC support and I'm not entirely sure how it's supposed to work. +You will most likely need to install additional packages to get this to build. On Debian-based systems these are _libcec-dev_ and _libp8-platform-dev_. Note that the CEC support is currently untested. To build with the GLES renderer, run the following: ``` -cmake -DCMAKE_BUILD_TYPE=Debug -DGLES=on . +cmake -DGLES=on . make ``` -Note that 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. +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. 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: @@ -204,7 +262,7 @@ The following example will build the application for installtion under /opt: cmake -DCMAKE_INSTALL_PREFIX=/opt . ``` -It's important to know that this is not only the directory used by the install script, the CMAKE_INSTALL_PREFIX variable also modifies code inside ES-DE used to locate the required program resources. So it's necessary that the install prefix corresponds to the location where the application will actually be installed. +It's important to understand that this is not only the directory used by the install script, the CMAKE_INSTALL_PREFIX variable also modifies code inside ES-DE used to locate the required program resources. So it's necessary that the install prefix corresponds to the location where the application will actually be installed. On Linux, if you're not building a package and instead intend to install using `make install` it's recommended to set the installation prefix to /usr/local instead of /usr. @@ -212,26 +270,24 @@ On Linux, if you're not building a package and instead intend to install using ` Both Clang/LLVM and GCC work fine for building ES-DE. -I did some small benchmarks comparing Clang to GCC with the ES-DE codebase (as of writing it's year 2020) and it's pretty interesting. +I did some small benchmarks comparing Clang 10.0 to GCC 9.3.0 with the ES-DE v1.1 codebase on an Intel Xeon W-2245 @ 3.90GHz running Kubuntu 20.04.2 LTS and it's pretty interesting. Advantages with Clang (vs GCC): -* 10% smaller binary size for a release build -* 17% smaller binary size for a debug build -* 2% faster compile time for a release build -* 16% faster compile time for a debug build +* 8% smaller binary size for a release build +* 31% smaller binary size for a debug build +* 16% faster compile time for a release build +* 25% faster compile time for a debug build +* 13% faster application startup time for a release build * 4% faster application startup time for a debug build -Advantage with GCC (vs Clang): -* 1% faster application startup time for a release build - *Release build: Optimizations enabled, debug info disabled, binary stripped.* \ *Debug build: Optimizations disabled, debug info enabled, binary not stripped.* This Clang debug build is LLVM "native", i.e. intended to be debugged using the LLVM project debugger LLDB. The problem is that this is still not well integrated with VSCode that I use for development so I need to keep using GDB. But this is problematic as the libstd++ data required by GDB is missing in the binary, making it impossible to see the values of for instance std::string variables. -It's possible to activate the additional debug info needed by GDB by using the flag `-D_GLIBCXX_DEBUG`. I've added this to CMakeLists.txt when using Clang, but this bloats the binary and makes the code much slower. Actually, instead of a 4% faster application startup, it's now 36% slower! The same goes for the binary size, instead of 17% smaller it's now 17% larger. +It's possible to activate the additional debug info needed by GDB by using the flag `-D_GLIBCXX_DEBUG`. I've added this to CMakeLists.txt when using Clang, but this bloats the binary and makes the code much slower. Actually, instead of a 4% faster application startup, it's now 25% slower. The same goes for the binary size, instead of 31% smaller it's now 5% larger. The compilation time is still less than GCC but only by 10% instead of 25%. -I'm expecting this to be resolved in the near future though, and as I think Clang is an interesting compiler, I use it as the default when working on the project (I sometimes test with GCC to make sure that it still builds the software correctly). +But I'm expecting this issue to be resolved in the future so the workaround can be removed. It's by the way very easy to switch between LLVM and GCC using Ubuntu, just use the `update-alternatives` command: @@ -277,7 +333,7 @@ However, when installing manually instead of building a package, it's recommende Be aware that if using the GNOME desktop environment, /usr/share/pixmaps/emulationstation.svg must exist in order for the ES-DE icon to be shown in the Dash and task switcher. -ES-DE will look in the following locations for the resources, in the listed order: +ES-DE will look in the following locations for application resources, in the listed order: * \/.emulationstation/resources/ * \/share/emulationstation/resources/ @@ -285,7 +341,7 @@ ES-DE will look in the following locations for the resources, in the listed orde The resources directory is critical, without it the application won't start. -And it will look in the following locations for the themes, also in the listed order: +As well the following locations will be searched for themes, also in the listed order: * \/.emulationstation/themes/ * \/share/emulationstation/themes/ @@ -293,7 +349,7 @@ And it will look in the following locations for the themes, also in the listed o A theme is not mandatory to start the application, but ES-DE will be basically useless without it. -The home directory will always take precedence, and any resources or themes located there will override the ones in the installation path or in the path of the ES-DE executable. +As indicated above, the home directory will always take precedence and any resources or themes located there will override the ones in the installation path, or in the path of the ES-DE executable. **Creating .deb and .rpm packages** @@ -307,56 +363,63 @@ 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.0.0-x64.deb generated. +CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.1.0-x64.deb generated. ``` -You may like to check that the dependencies look fine, as they're automatically generated by CMake: +You may want to check that the dependencies look fine, as they're (mostly) automatically generated by CMake: ``` -dpkg -I ./emulationstation-de-1.0.0-x64.deb +dpkg -I ./emulationstation-de-1.1.0-x64.deb ``` The package can now be installed using a package manager, for example apt: ``` -sudo apt install ./emulationstation-de-1.0.0-x64.deb +sudo apt install ./emulationstation-de-1.1.0-x64.deb ``` -For RPM packages, remove the comment in es-app/CMakeLists.txt accordingly, from: +To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example: ``` -#SET(CPACK_GENERATOR "RPM") -``` -to: -``` -SET(CPACK_GENERATOR "RPM") +cmake -DLINUX_CPACK_GENERATOR=RPM . ``` -Then simply run cpack. +Then simply run `cpack`: -On Fedora, you need to install rpmbuild before this command can be run though: +``` +myusername@computer:~/emulationstation-de$ cpack +CPack: Create package using RPM +CPack: Install projects +CPack: - Run preinstall target for: emulationstation-de +CPack: - Install project: emulationstation-de [] +CPack: 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. +``` + +On Fedora, you need to install rpmbuild before this command can be run: ``` sudo dnf install rpm-build ``` -After the package generation you can check that the metadata looks fine using this command: +After the package generation you can check that the metadata looks fine using the `rpm` command: ``` -rpm -qi ./emulationstation-de-1.0.0-x64.rpm +rpm -qi ./emulationstation-de-1.1.0-x64.rpm ``` -And to see the automatically generated dependency requirements, run this: +To see the automatically generated dependencies, run this: ``` -rpm -q --requires ./emulationstation-de-1.0.0-x64.rpm +rpm -q --requires ./emulationstation-de-1.1.0-x64.rpm ``` And of course, you can also install the package: ``` -sudo dnf install ./emulationstation-de-1.0.0-x64.rpm +sudo dnf install ./emulationstation-de-1.1.0-x64.rpm ``` ## 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 deficiency 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. +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. 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. @@ -364,7 +427,7 @@ As for code editing, I use [VSCode](https://code.visualstudio.com). I suppose Xc 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 simplify the rest of the installation greatly. Install it by runing the following in a terminal window: +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: ``` /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" ``` @@ -375,23 +438,35 @@ Be aware that Homebrew can be really slow, especially when it compiles packages Install the required tools and dependencies: ``` -brew install cmake pkg-config sdl2 freeimage freetype pugixml rapidjson +brew install clang-format cmake pkg-config nasm fdk-aac libvpx sdl2 freeimage freetype pugixml rapidjson ``` -Curl could optionally be installed too, but normally the version shipped with macOS is fine to use. +If building with the optional VLC video player, then run this as well: -Install VLC/libVLC 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:** 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, but a simple command is enough to not having to ponder this any further. +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. 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: ``` @@ -416,81 +491,108 @@ cmake . make ``` -By default the master branch will be used, which is where the development takes place. To instead build the latest stable release, switch to the `stable` branch: +By default the master branch will be used, which is where development takes place. To instead build a stable release, switch to the `stable-x.x` branch for the version, for example: ``` cd emulationstation-de -git checkout stable +git checkout stable-1.1 cmake . make ``` -To generate a debug build, run this instead: +To build ES-DE with the VLC video player in addition to the default FFmpeg player, enable the VLC_PLAYER option: +``` +cmake -DVLC_PLAYER=on . +make +``` + +To generate a debug build, run this: ``` cmake -DCMAKE_BUILD_TYPE=Debug . make ``` -Keep in mind though that a debug version will be much slower due to all compiler optimizations being disabled. +Keep in mind that the debug version will be much slower due to all compiler optimizations being disabled. 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 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. The following will of course only be active during your session, and you need to set the variable for each terminal window that you want to start ES-DE from, unless you add it to your shell profile file: - +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: ``` export DYLD_LIBRARY_PATH=/Applications/VLC.app/Contents/MacOS/lib ``` -**Note:** 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. +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. **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 will be required for versions 10.14 and higher. +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 a short summary is that signing works as intended and can be enabled by uncommenting the following lines in the es-app/CMakeLists.txt file: +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: ``` -# Uncomment the following lines and change to your certificate identity to enable code signing. -#set(CPACK_BUNDLE_APPLE_CERT_APP "Developer ID Application: ") -#if(${CMAKE_OSX_DEPLOYMENT_TARGET} VERSION_GREATER 10.13) -# set(CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER "--deep --force --options runtime") -#endif() +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. + **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 and 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 versions. 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. You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the key SMinimumSystemVersion to the version you're building for. +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:** 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: ``` +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 -libvlccore.dylib +libvlc.dylib (only if building with the VLC video player) +libvlccore.dylib (only if building with the VLC video player) ``` -The first four would normally be installed by Homebrew under /usr/local/lib and the VLC libraries should be installed under /Applications/VLC.app/Contents/MacOS/lib/ +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/ Note that the filenames could be slightly different depending on what versions you have installed on your system. -For libfreetype there is a dependency on libpng and you need to rewrite the rpath to point to the local directory, otherwise any generated installation package will not work on other computers. Make sure that you have write permissions to libfreetype.6.dylib before attempting to run this: +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 -install_name_tool -change /usr/local/opt/libpng/lib/libpng16.16.dylib @rpath/libpng16.16.dylib libfreetype.6.dylib -install_name_tool -add_rpath @executable_path libfreetype.6.dylib +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 `otool -L libfreetype.6.dylib` - you should see something like the following: +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: @@ -501,9 +603,11 @@ libfreetype.6.dylib: /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1226.10.1) ``` -You of course only need to run this once, well at least until you replace the library in case of moving to a newer version or so. +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. -In addition to these libraries, you need to create a `plugins` directory and copy over the following VLC libraries, which are normally located in `/Applications/VLC.app/Contents/MacOS/plugins/`: +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/`: ``` libadummy_plugin.dylib @@ -522,29 +626,29 @@ libx264_plugin.dylib libx265_plugin.dylib ``` -If you only want to build ES-DE to be used on your own computer, there's the option to skip the entire bundling of the libraries and use the ones already installed using Homebrew, meaning you can skip the previous .dylib copying. To do so, run CMake with the following option: - -``` -cmake -DAPPLE_SKIP_INSTALL_LIBS=ON . -``` - -This also affects the .dmg package generation using cpack, so if this option is enabled, the package will be unusable for anyone but yourself as the required libraries will not be bundled with the application. - On macOS you can install the application as a normal user, i.e. no root privileges are required. Simply run the following: ``` make install ``` -This will be the directory structure for the installation: +This will be the directory structure for the installation (the VLC-related files are optional): ``` /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/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/plugins/* @@ -555,23 +659,23 @@ This will be the directory structure for the installation: /Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/* ``` -ES will look in the following locations for the resources, in the listed order: +ES-DE will look in the following locations for application resources, in the listed order: * \/.emulationstation/resources/ * \/../Resources/resources/ * \/resources/ -**Note:** The resources directory is critical, without it the application won't start. +The resources directory is critical, without it the application won't start. -And it will look in the following locations for the themes, also in the listed order: +As well the following locations will be searched for themes, also in the listed order: * \/.emulationstation/themes/ * \/../Resources/themes/ * \/themes/ -A theme is not mandatory to start the application, but ES will be basically useless without it. +A theme is not mandatory to start the application, but ES-DE will be basically useless without it. -The home directory will always take precedence, and any resources or themes located there will override the ones in the installation path or in the path of the ES executable. +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:** @@ -584,10 +688,10 @@ 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.0.0-x64.dmg generated. +CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.1.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 does however not seem to be true, which is quite unsurprising. +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:** @@ -598,16 +702,20 @@ This is certainly not perfect as the versions of the libraries are hardcoded ins 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 8.0.0) - @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.2.0) - @rpath/libSDL2-2.0.0.dylib (compatibility version 13.0.0, current version 13.0.0) - /System/Library/Frameworks/Cocoa.framework/Versions/A/Cocoa (compatibility version 1.0.0, current version 22.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 120.1.0) - /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1226.10.1) +./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. @@ -616,23 +724,12 @@ 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)` -This is the section in es-app/CMakeLists.txt that would need to be modified: - -``` -add_custom_command(TARGET EmulationStation POST_BUILD COMMAND ${CMAKE_INSTALL_NAME_TOOL} - -change /usr/local/opt/freeimage/lib/libfreeimage.dylib @rpath/libfreeimage.dylib - -change /usr/local/opt/freetype/lib/libfreetype.6.dylib @rpath/libfreetype.6.dylib - -change /usr/local/opt/libpng/lib/libpng16.16.dylib @rpath/libpng16.16.dylib - -change /usr/local/opt/sdl2/lib/libSDL2-2.0.0.dylib @rpath/libSDL2-2.0.0.dylib - $) -``` - ## Building on Windows Both MSVC and MinGW (GCC) work fine for building ES-DE on Windows. -As much as I would like to exclude support for MSVC, this proprietary compiler simply works much better when developing as it's much faster than MinGW when linking debug builds and when actually debugging. For release builds though MinGW is very fast and it seems as if ES-DE starts around 18% faster when built with MinGW so this compiler probably generates more efficient code overall. As well MSVC requires a lot more junk DLL files to be distributed with the application so it's not a good candidate for the final release build. +Although I would prefer to exclude support for MSVC, this compiler simply works much better when developing as it's much faster than MinGW when linking debug builds and when actually debugging. But for release builds MinGW is very fast and ES-DE starts around 18% faster when built with MinGW meaning this compiler probably generates more efficient code overall. As well MSVC requires a lot more junk DLL files to be distributed with the application so it's not a good candidate for the final release build. For this reason I think MSVC makes sense for development and MinGW for the releases. @@ -655,7 +752,7 @@ Just-In-Time debugger C++ CMake tools for Windows ``` -If you intend to use both MinGW and MSVC on the machine, it's probably better to exclude CMake and install it manually as described in the MinGW setup instructions below. +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. 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`. @@ -671,33 +768,41 @@ Download the following packages and install them: [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. +After installation, make a copy of `TDM-GCC-64\bin\mingw32-make` to `make` just for convenience. -Note that most GDB builds for Windows have broken Python support so that pretty printing won't work. The recommended MinGW installation should work fine though. +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:** +In order to get clang-format onto the system you need to download and install Clang: \ +[https://llvm.org/builds](https://llvm.org/builds) + +Just run the installer and make sure to select the option _Add LLVM to the system PATH for current user_. + Install your editor of choice, I use [VSCode](https://code.visualstudio.com). -Configure Git. I won't get into the details on how it's done, but there are many resources available online to support with this. The `Git Bash` shell shipped with Git for Windows is very useful though as it's somewhat reproducing a Unix environment using MinGW/MSYS2. +Configure Git. I won't get into the details on how this is done, but there are many resources available online to support with this. The `Git Bash` shell shipped with Git for Windows is very useful though as it's somewhat reproducing a Unix environment using MinGW/MSYS2. -It's strongly recommended to set line breaks to Unix-style (line feed only) directly in the editor, although it can also be configured in Git for conversion during commits. The source code for ES-DE only uses Unix-style line breaks. +It's strongly recommended to set line breaks to Unix-style (line feed only) directly in the editor. But if not done, lines breaks will anyway be converted when running clang-format on the code, as explained [here](INSTALL.md#using-clang-format-for-automatic-code-formatting). -In the description 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). +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:** +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) + FreeImage (binary distribution) \ [https://sourceforge.net/projects/freeimage](https://sourceforge.net/projects/freeimage) -cURL (Windows 64 bit binary, the MinGW version even if using MSVC) \ +cURL (Windows 64 bit binary, select the MinGW version even if using MSVC) \ [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html) SDL2 (development libraries, MinGW or VC/MSVC) \ [https://www.libsdl.org/download-2.0.php](https://www.libsdl.org/download-2.0.php) -libVLC (both win64 binary and source distributions) \ +libVLC (both win64 binary and source distributions) - optional, if building with the VLC video player\ [https://ftp.lysator.liu.se/pub/videolan/vlc](https://ftp.lysator.liu.se/pub/videolan/vlc) Uncompress the files from the above packages to a suitable directory, for example `C:\Programming\Dependencies` @@ -765,7 +870,7 @@ make [RapidJSON](http://rapidjson.org) -For RapidJSON, you don't need to compile it, you just need the include files: +For RapidJSON you don't need to compile, you just need the include files: ``` git clone git://github.com/Tencent/rapidjson.git @@ -783,11 +888,11 @@ This works the same as on Unix or macOS, just run the following: git clone https://gitlab.com/leonstyhre/emulationstation-de.git ``` -By default the master branch will be used, which is where the development takes place. To instead build the latest stable release, switch to the `stable` branch: +By default the master branch will be used, which is where development takes place. To instead build a stable release, switch to the `stable-x.x` branch for the version, for example: ``` cd emulationstation-de -git checkout stable +git checkout stable-1.1 ``` **Setup the include directories:** @@ -796,11 +901,13 @@ As there is no standardized include directory structure in Windows, you need to Make a directory in your build environment tree, for instance under `C:\Programming\include` -Copy the include files from cURL, FreeImage, FreeType, GLEW, pugixml, RapidJSON, SDL2 and VLC to this directory. +Copy the include files for cURL, FFmpeg, FreeImage, FreeType, GLEW, pugixml, RapidJSON, SDL2 and optionally VLC to this directory. You may need to create the SDL2 directory manually and copy the header files there. -It should then look something like this: +For FFmpeg, copy the directories libavcodec, libavfilter, libavformat and libavutil. + +It should look something like this: ``` $ ls -1 include/ @@ -809,11 +916,15 @@ FreeImage.h freetype/ ft2build.h GL/ +libavcodec/ +libavfilter/ +libavformat/ +libavutil/ pugiconfig.hpp pugixml.hpp rapidjson/ SDL2/ -vlc/ +vlc/ (only if building with the VLC video player) ``` **Copy the required library files to the ES-DE build directory:** @@ -824,6 +935,19 @@ Copy the files to the `emulationstation-de` build directory. Most of them will c **Required files for MSVC:** ``` +avcodec-58.dll +avcodec.lib +avfilter.lib +avfilter-7.dll +avformat-58.dll +avformat.lib +avutil-56.dll +avutil.lib +postproc-55.dll +swresample-3.dll +swresample.lib +swscale-5.dll +swscale.lib FreeImage.dll FreeImage.lib freetype.dll @@ -833,8 +957,8 @@ glew32.lib libcurl-x64.dll libcrypto-1_1-x64.dll (from the OpenSSL package, located in Git MinGW/MSYS2 under \mingw64\bin) libssl-1_1-x64.dll (from the OpenSSL package, located in Git MinGW under \mingw64\bin) -libvlc.dll -libvlccore.dll +libvlc.dll (only if building with the VLC video player) +libvlccore.dll (only if building with the VLC video player) pugixml.dll pugixml.lib SDL2.dll @@ -846,7 +970,7 @@ VCRUNTIME140.dll (from Windows\System32) VCRUNTIME140_1.dll (from Windows\System32) ``` -In addition to these files, you need libcurl-x64.lib and libvlc.lib, but these are not available for download so you need to generate them yourself from their corresponding DLL files. Do this inside the respective library directory and not within the emulationstation-de folder. +In addition to these files, you need libcurl-x64.lib and libvlc.lib (if building with the VLC video player), but these are not available for download so you need to generate them yourself from their corresponding DLL files. Do this inside the respective library directory and not within the emulationstation-de folder. libcurl-x64.lib: ``` @@ -869,6 +993,13 @@ lib /def:libvlc.def /out:libvlc.lib /machine:x64 **Required files for MinGW:** ``` +avcodec-58.dll +avfilter-7.dll +avformat-58.dll +avutil-56.dll +postproc-55.dll +swresample-3.dll +swscale-5.dll FreeImage.dll glew32.dll libcrypto-1_1-x64.dll (from the OpenSSL package, located in Git MinGW/MSYS2 under \mingw64\bin) @@ -877,19 +1008,17 @@ libfreetype.dll libpugixml.dll libSDL2main.a libssl-1_1-x64.dll (from the OpenSSL package, located in Git MinGW under \mingw64\bin) -libvlc.dll -libvlccore.dll +libvlc.dll (only if building with the VLC video player) +libvlccore.dll (only if building with the VLC video player) SDL2.dll vcomp140.dll (From Visual C++ Redistributable for Visual Studio 2015, 32-bit version) ``` -**Required files for both MSVC and MinGW:** +**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 to be able to play video files. There is a subdirectory structure under the plugins folder but there is no requirement to retain this as libVLC apparently looks recursively for the .dll files. +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. -It's a bit tricky to know which libraries are really needed. But as the plugins directory is around 120 MB (as of VLC version 3.0.11), we definitely only want to copy the files we need. - -The following files seem to be required to play most video and audio formats (place them in `emulationstation-de\plugins`): +The following libraries seem to be required to play most video and audio formats: ``` access\libfilesystem_plugin.dll @@ -909,7 +1038,9 @@ video_chroma\libswscale_plugin.dll video_output\libvmem_plugin.dll ``` -The combined size of these files is around 22 MB which is more reasonable. +The reason to not simply copy all plugins is that the combined size of these is around 120 MB (as of VLC version 3.0.11) and the size of the selected files listed above is around 22 MB, which is more reasonable. + +Place the files in the `emulationstation-de\plugins\` directory. **Building ES-DE using MSVC:** @@ -932,10 +1063,16 @@ nmake 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 much. Embrace this as a retro experience as in the 1990s we normally just had a single core available in our computers. +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. Be aware that MSVC links against different VC++ libraries for debug and release builds (e.g. MSVCP140.dll or MSVCP140d.dll), so any NSIS package made from a debug build will not work on computers without the MSVC development environment installed. +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 +``` + **Building ES-DE using MinGW:** For a release build: @@ -956,6 +1093,12 @@ For some reason defining the `../include` path doesn't work when running CMake f The make command works fine directly in PowerShell though so it can be run from the VSCode terminal. +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 "MinGW Makefiles" -DWIN32_INCLUDE_DIR=../include -DVLC_PLAYER=on . +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. @@ -965,7 +1108,7 @@ Note that compilation time is much longer than on Unix or macOS, and linking tim 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). -You simply extract the opengl32.dll file into the ES-DE directory and this will enable the llvmpipe renderer. The performance will be terrible of course, but everything should work and it should be good enough for test building on Windows without having to reboot your computer to a native Windows installation. (Note that you may need to copy opengl32.dll to your RetroArch installation directory as well to get the emulators to work correctly.) +You simply extract the opengl32.dll file into the ES-DE directory and this will enable the llvmpipe renderer. The performance will be terrible of course, but everything should work and it should be good enough for test building on Windows without having to reboot your computer to a native Windows installation. (Note that you may need to copy opengl32.dll to your RetroArch installation directory as well to get the emulators to work somehow correctly.) Obviously this library is only intended for development and will not be shipped with ES-DE. @@ -986,82 +1129,102 @@ 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.0.0-x64.exe generated. +CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-1.1.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. -ES will look in the following locations for the resources, in the listed order: +ES-DE will look in the following locations for application resources, in the listed order: * \\\.emulationstation\resources\ * \\resources\ The resources directory is critical, without it the application won't start. -And it will look in the following locations for the themes, also in the listed order: +As well the following locations will be searched for themes, also in the listed order: * \\\.emulationstation\themes\ * \\themes\ -The theme is not mandatory to start the application, but ES-DE will be basically useless without it. +A theme is not mandatory to start the application, but ES-DE will be basically useless without it. -So the home directory will always take precedence, and any resources or themes located there will override the ones in the path of the ES executable. +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. -**Setting up a portable installation:** -It's possible to easily create a portable installation of ES-DE for Windows, for example on a USB memory stick. +## Using clang-format for automatic code formatting -For the sake of this example, let's assume that the removable media has the device name `f:\`. +The entire ES-DE codebase is formatted using clang-format and all new code must be formatted using this tool before being committed. -* Copy the EmulationStation-DE installation directory to f:\ -* Create the directory `ES-DE_Home` directly under f:\ -* Copy your game ROMs into `f:\ES-DE_Home\ROMs` -* Copy your emulators to f:\ (such as the RetroArch directory) -* Create the file `start_es.bat` directly under f:\ +There is a style configuration file named .clang-format located directly at the root of the repository which contains the formatting rules. How to install clang-format is detailed per operating system earlier in this document. -Add the following lines to the start_es.bat file: -``` -@echo off -EmulationStation-DE\EmulationStation.exe --home %CD:~0,3%ES-DE_Home +There are two ways to run the tool, from the command line or from inside an editor such as VSCode. + +To format a file from the command line, simply run: + +```clang-format -i ``` + +The -i flag will make an inplace edit of the file. + +But the recommended approach is to run clang-format from within the editor. If using VSCode, there is an extension available named Clang-Format. After installing this, simply open a source file, right click and choose `Format Document` or use the applicable keyboard shortcut. The first time you do this, you will have to make a choice to perform the formatting using clang-format. The rest should be completely automatic. + +In some instances you may want to avoid getting code formatted, and you can accomplish this by simply enclosing the lines with the two comments "clang-format off" and "clang-format on", such as this: + +```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 } +}; +// clang-format on ``` -The contents of f:\ should now look something like this: -``` -EmulationStation-DE -ES-DE_Home -RetroArch -start_es.bat +Adding a comment on its own line will also prevent some formatting such as turning short functions and lambda expressions into single lines. For this function such a comment has been added: + +```c++ +const std::string FileData::get3DBoxPath() const +{ + // Return path to the 3D box image. + return getMediafilePath("3dboxes", "3dbox"); +} ``` -Now run the batch script, ES should start and ask you to configure any attached controllers. Following this, check that everything works as expected, i.e. the gamelists are properly populated etc. +If the comment was omitted, the function would get formatted like this: -You can optionally skip the configuration of the controllers by copying any existing es_input.cfg file to `f:\ES-DE_Home\.emulationstation\` - -Exit ES-DE and modify the file `f:\ES-DE_Home\.emulationstation\es_systems.cfg` to point to the emulators on the portable media. - -For example, change from this: -``` -retroarch.exe -L %EMUPATH%\cores\snes9x_libretro.dll %ROM% +```c++ +const std::string FileData::get3DBoxPath() const { return getMediafilePath("3dboxes", "3dbox"); } ``` -To this: -``` -%ESPATH%\..\RetroArch\retroarch.exe -L %EMUPATH%\cores\snes9x_libretro.dll %ROM% +Adding comments (even empty ones) can also force line breaks to avoid ugly formatting such as this: + +```c++ +for (auto it = mCursorStackHistory.begin(); it != mCursorStackHistory.end(); + it++) { + if (std::find(listEntries.begin(), listEntries.end(), *it) != + listEntries.end()) { + newCursor = *it; + mCursorStackHistory.erase(it); + break; + } +} ``` -The %ESPATH% variable is explained later in this document. - -Following this, optionally copy any existing gamelist.xml and game media files to the removable media. By default these files should be located here: - -``` -f:\ES-DE_Home\.emulationstation\gamelists\ -f:\ES-DE_Home\.emulationstation\downloaded_media\ +A comment at the right place produces this much nicer formatting: +```c++ +for (auto it = mCursorStackHistory.begin(); // Line break. + it != mCursorStackHistory.end(); it++) { + if (std::find(listEntries.begin(), listEntries.end(), *it) != + listEntries.end()) { + newCursor = *it; + mCursorStackHistory.erase(it); + break; + } +} ``` -You now have a fully functional portable retro gaming installation! - -The portable installation works exactly as a normal installation, i.e. you can use the built-in scraper, edit metadata etc. - +Of course you would like to get the code formatted according to the clang-format rules in most instances, these workaround are only meant for rare exceptions. Some compromises are necessary when auto-formatting code, at least with clang-format in its current state. ## CA certificates and MAME ROM information @@ -1081,9 +1244,9 @@ emulationstation-de/resources/certificates/curl-ca-bundle.crt **MAME ROM info:** -This is a bit tricky as the data needs to be converted to an internal format used by ES-DE. The original file is huge and most of the information is not required. +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. -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 file name such as `mame0226.xml`. Move the XML driver file to the resources/MAME directory and then convert it to the ES-DE internal files: @@ -1120,31 +1283,18 @@ git diff mamebioses git diff mamedevices ``` -The reason to not simply replace the BIOS and devices files with the new version is that we want to retain entries from all older MAME versions as otherwise older ROM sets used on older MAME versions would have missing information. This is so as the MAME project sometimes removes older entries when they're reorganizing the ROM sets. By merging the files we retain backwards compatibility but still support the latest MAME version. To clarify, this of course does not affect the emulation itself, but rather the filtering of BIOS and device files inside ES-DE. The mamenames.xml file containing the translation of MAME ROM names to the full game names does not suffer from this problem as it's cumulative, which is why it is simply overwritten. +The reason to not simply replace the BIOS and devices files with the new version is that we want to retain entries from all older MAME versions as otherwise older ROM sets used on older MAME versions would have missing information. This is so as the MAME project sometimes removes older entries when they're reorganizing the ROM sets. By merging the files we retain backward compatibility but still support the latest MAME version. To clarify, this of course does not affect the emulation itself, but rather the filtering of BIOS and device files inside ES-DE. The mamenames.xml file containing the translation of MAME ROM names to the full game names does not suffer from this problem as it's cumulative, which is why it is simply overwritten. ## Configuration -**~/.emulationstation/es_systems.cfg:** +**~/.emulationstation/es_settings.xml:** -ES-DE ships with a comprehensive `es_systems.cfg` configuration file, and as the logic is to use a `%ROMPATH%` variable to locate the ROM files (with a corresponding setting in `es_settings.cfg`), normally you shouldn't need to modify this file to the same extent as previous versions of EmulationStation. Still, see below in this document on how to adjust the es_systems.cfg file if required. - -Upon first startup of the application, if there is no es_systems.cfg file present, it will be copied from the template subdirectory inside the resources directory. This is located in the installation path of the application, for instance `/usr/share/emulationstation/resources/templates` or `/usr/local/share/emulationstation/resources/templates` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/templates` on macOS and `C:\Program Files\EmulationStation-DE\resources\templates`on Windows. - -The template file will be copied to `~/.emulationstation/es_systems.cfg`. - -The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows. - -Keep in mind that you have to set up your emulators separately from ES-DE as the es_systems.cfg file assumes that your emulator environment is properly configured. - - -**~/.emulationstation/es_settings.cfg:** - -When ES-DE is first run, a configuration file will be created as `~/.emulationstation/es_settings.cfg`. +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.cfg:** +**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. @@ -1157,24 +1307,28 @@ megadrive pcengine ``` -However, if you've saved your ROMs to another directory, you need to configure the ROMDirectory setting in es_settings.cfg.\ +However, if you've saved your ROMs to another directory, you need to configure the ROMDirectory setting in es_settings.xml.\ Here's an example: -`` +```xml + +``` -Keep in mind that you still need to group the ROMs into directories corresponding to the `` tags in es_systems.cfg. +Keep in mind that you still need to group the ROMs into directories corresponding to the `` tags in es_systems.xml. -There is also support to add the variable %ESPATH% to the ROM directory setting, this will expand to the path where the ES executable is started from. You would normally not need this, but the option is there, should you require it for some reason. +There is also support to add the variable %ESPATH% to the ROM directory setting, this will expand to the path where the ES-DE executable is started from. You should normally not need this, but the option is there for special cases. For example: -Here is such an example: +```xml + +``` -`` +**~/.emulationstation/es_input.xml:** -**~/.emulationstation/es_input.cfg:** +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. -You normally don't need to modify this file manually as it's created by the built-in input configuration step. This procedure is detailed in the [User guide](USERGUIDE.md#input-device-configuration). +But if you have customized your button layout and your controller or keyboard stop working, you can delete the `~/.emulationstation/es_input.xml` file to remove the customizations, or you can start ES-DE with the `--force-input-config` command line option to make the input configurator appear. -If your controller and keyboard stop working, you can delete the `~/.emulationstation/es_input.cfg` file to make the input configuration screen re-appear on the next startup, or you can start ES-DE with the `--force-input-config` command line option. +The input configuration is described in the [User guide](USERGUIDE.md#input-device-configuration). ## Command line options @@ -1228,9 +1382,9 @@ You can use **--help** or **-h** to view the list of command line options, as sh --help, -h Summon a sentient, angry tuba ``` -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 base directory. +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. -For the following options, the es_settings.cfg file is immediately updated/saved when passing the parameter: +For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter: ``` --display --fullscreen-normal @@ -1241,19 +1395,29 @@ For the following options, the es_settings.cfg file is immediately updated/saved ``` -## es_systems.cfg +## es_systems.xml -The es_systems.cfg 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 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. -ES-DE will only check in your home directory for an es_systems.cfg file, for example `~/.emulationstation/es_systems.cfg`, but if this file is not present, it will attempt to install it from the systems template directory as explained earlier in this document. +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. + +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.) + +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. -Below is an overview of the file layout with various examples. For a real system entry there can of course not be multiple entries for the same tag such as the multiple \ entries listed here. +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 - + @@ -1262,29 +1426,33 @@ Below is an overview of the file layout with various examples. For a real system snes - Super Nintendo Entertainment System + Nintendo SNES (Super Nintendo) %ROMPATH%/snes + You must include the period at the start of the extension and it's also case sensitive. --> .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% + + retroarch -L ~/.config/retroarch/cores/snes9x_libretro.so %ROM% - - retroarch -L %COREPATH%/snes9x_libretro.so %ROM% + + retroarch -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% - - /Applications/RetroArch.app/Contents/MacOS/RetroArch -L %COREPATH%/snes9x_libretro.dylib %ROM% + + /Applications/RetroArch.app/Contents/MacOS/RetroArch -L %CORE_RETROARCH%/snes9x_libretro.dylib %ROM% - "%ESPATH%\..\RetroArch\retroarch.exe" -L "%ESPATH%\..\RetroArch\cores\snes9x_libretro.dll" %ROM% + expanded to the directory of the ES-DE executable. --> + "%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM% + + + bash %ROM% + + + %HIDEWINDOW% cmd /C %ROM% snes + It's recommended to include this tag even if it's just to clarify that the theme should correspond to the system name. --> snes @@ -1318,11 +1493,11 @@ Below is an overview of the file layout with various examples. For a real system The following variable is expanded for the `path` tag: -`%ROMPATH%` - Replaced with the path defined in the setting ROMDirectory in es_settings.cfg. +`%ROMPATH%` - Replaced with the path defined in the setting ROMDirectory in es_settings.xml. The following variables are expanded for the `command` tag: -`%ROM%` - Replaced with the absolute path to the selected ROM, with most Bash special characters escaped with a backslash. +`%ROM%` - Replaced with the absolute path to the selected ROM, with most special characters escaped with a backslash. `%ROMRAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes. @@ -1332,7 +1507,11 @@ The following variables are expanded for the `command` tag: `%ESPATH%` - Replaced with the path to the ES-DE binary. Mostly useful for portable emulator installations, for example on a USB memory stick. -`%COREPATH%` - The core file defined after this variable will be searched in each of the directories listed in the setting EmulatorCorePath in es_settings.cfg. This is done until the first match occurs, or until the directories are exhausted and no core file was found. This makes it possible to create a more general es_systems.cfg file but still support the variation between different operating systems and different types of emulator installations (e.g. installed via the OS repository, via Snap, compiled from source etc.). This is primarily intended for RetroArch on Unix but it's also used on macOS due to the change in the RetroArch directory structure as of v1.9.2. It could also be used for special situations and for other emulators that utilize discrete emulator cores. For Windows the EmulatorCorePath setting is blank by default, for macOS it's set to `~/Library/Application Support/RetroArch/cores:/Applications/RetroArch.app/Contents/Resources/cores` and for Unix it's set to `~/.config/retroarch/cores:~/snap/retroarch/current/.config/retroarch/cores:/usr/lib/x86_64-linux-gnu/libretro:/usr/lib64/libretro:/usr/lib/libretro:/usr/local/lib/libretro:/usr/pkg/lib/libretro`. Note that colons are used to separate the directories on Unix and macOS and that semicolons are used on Windows. This path setting can be changed from within the GUI, as described in the [User guide](USERGUIDE.md#other-settings-1). Never use quotation marks around the directories for this setting. It's adviced to not add spaces to directory names, but if still done, ES-DE will handle this automatically by adding the appropriate quotation marks to the launch command. You can also use the %EMUPATH% and %ESPATH% variables within the EmulatorCorePath setting, which leads to quite flexible configuration options. +`%EMULATOR_` - This utilizes the emulator find rules as defined in `es_find_rules.xml`. This is the recommended way to configure the launch command. The find rules are explained in more detail below. + +`%CORE_` - This utilizes the core find rules as defined in `es_find_rules.xml`. This is the recommended way to configure the launch command. + +`%HIDEWINDOW%` - This variable is only available on Windows and is used primarily for hiding console windows when launching scripts (used for example by Steam games and source ports). If not defining this, the console window will be visible when launching the game. It needs to be placed first in the command tag. Here are some additional real world examples of system entries, the first one for Unix: @@ -1341,12 +1520,11 @@ Here are some additional real world examples of system entries, the first one fo dos DOS (PC) %ROMPATH%/dos - .bat .BAT .com .COM .exe .EXE .7z .7Z .zip .ZIP - retroarch -L %COREPATH%/dosbox_core_libretro.so %ROM% + .bat .BAT .com .COM .conf .CONF .cue .CUE .exe .EXE .iso .ISO .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% dos dos - ``` Then one for macOS: @@ -1357,7 +1535,7 @@ Then one for macOS: Nintendo Entertainment System %ROMPATH%/nes .nes .NES .unf .UNF .unif .UNIF .7z .7Z .zip .ZIP - /Applications/RetroArch.app/Contents/MacOS/RetroArch -L %COREPATH%/nestopia_libretro.dylib %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/nestopia_libretro.dylib %ROM% nes nes @@ -1371,11 +1549,173 @@ And finally one for Windows: Sega Mega Drive 32X %ROMPATH%\sega32x .bin .BIN .gen .GEN .smd .SMD .md .MD .32x .32X .cue .CUE .iso .ISO .sms .SMS .68k .68K .7z .7Z .zip .ZIP - retroarch.exe -L %EMUPATH%\cores\picodrive_libretro.dll %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%\picodrive_libretro.dll %ROM% sega32x sega32x +``` +## es_find_rules.xml + +This file makes it possible to define rules for where to search for the emulator binaries and emulator cores. + +The file is located in the resources directory in the same location as the es_systems.xml file, but a customized copy can be placed in ~/.emulationstation/custom_systems, which will override the bundled file. + +Here's an example es_find_rules.xml file for Unix: +```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 + + + +``` + +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`. + +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. + +The `name` attribute must correspond to the command tags in es_systems.xml, take for example this line: + +```xml +%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% +``` + +Here %EMULATOR_ and %CORE_ are followed by the string RETROARCH which corresponds to the name attribute in es_find_rules.xml. The name is case sensitive but it's recommended to use uppercase names to make the variables feel consistent (%EMULATOR_retroarch% doesn't look so pretty). + +Of course this makes it possible to add any number of emulators to the configuration file. + +The `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 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. + +As for `corepath` this rule is simply a path to search for the emulator core. + +Each rule supports multiple entry tags which are tried in the order that they are defined in the file. + +The %ESPATH% and %ROMPATH% variables can be used inside the staticpath rules and the %ESPATH% and %EMUPATH% variables can be used inside the corepath rules. + +The tilde symbol `~` is supported for the staticpath and corepath rules and will expand to the user home directory. Be aware that if ES-DE has been started with the --home command line option, the home directory is considered to be whatever path was passed as an argument to that option. The same is true if using a portable.txt file. + +All these options combined makes it possible to create quite powerful find rules. + +For reference, here are also example es_find_rules.xml files for macOS and Windows: + +```xml + + + + + + /Applications/RetroArch.app/Contents/MacOS/RetroArch + + + + + + ~/Library/Application Support/RetroArch/cores + + /Applications/RetroArch.app/Contents/Resources/cores + + + +``` + +```xml + + + + + + + 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 + + + ``` @@ -1383,15 +1723,21 @@ And finally one for Windows: The gamelist.xml file for a system defines the metadata for its entries, such as the game names, descriptions, release dates and ratings. -As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game media is configurable either manually in `es_settings.cfg` or via the GUI. If configured manually in es_settings.cfg, it looks something like this: +As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game media is configurable either manually in `es_settings.xml` or via the GUI. If configured manually in es_settings.xml, it looks something like this: -``` - +```xml + ``` -The default directory is `~/.emulationstation/downloaded_media` +There is also support to add the variable %ESPATH% to the media directory setting, this will expand to the path where the ES-DE executable is started from. You should normally not need this, but the option is there for special cases. For example: -You can use ES-DE's scraping tools to populate the gamelist.xml files, or manually update individual entries using the metadata editor. All of this is explained in the [User guide](USERGUIDE.md). +```xml + +``` + +The default media directory is `~/.emulationstation/downloaded_media` + +You can use ES-DE's scrapers to populate the gamelist.xml files, or manually update individual entries using the metadata editor. All of this is explained in the [User guide](USERGUIDE.md). The gamelist.xml files are searched for in the ES-DE home directory, i.e. `~/.emulationstation/gamelists//gamelist.xml` @@ -1433,10 +1779,10 @@ There are a few different data types for the metadata which the string values in * `string` - just text * `float` - a floating-point decimal value (written as a string) * `integer` - an integer value (written as a string) -* `datetime` - a date and, potentially, a time. These are encoded as an ISO string, in the following format: "%Y%m%dT%H%M%S%F%q". For example, the release date for Chrono Trigger is encoded as "19950311T000000" (no time specified) +* `datetime` - a date and optionally a time encoded as an ISO string in the format "%Y%m%dT%H%M%S", for example "19950311T000000" * `bool` - a true or false value -Some metadata is also marked as "statistic" - these are kept track of by ES-DE and do not show up in the metadata editor. They are shown in certain views (for example, the detailed view and the video view both show `lastplayed`, although the label can be disabled by the theme). +Some metadata is also marked as "statistic", these are kept track of by ES-DE and do not show up in the metadata editor. They are shown in certain views (for example, the detailed view and the video view both show `lastplayed`, although the label can be disabled by the theme). There are two basic categories of metadata, `game` and `folders` and the metdata tags for these are described in detail below. @@ -1519,6 +1865,65 @@ This will draw a semi-transparent blue frame around all text elements. This will reload either a single gamelist or all gamelists depending on where you're located when entering the key combination (go to the system view to make a complete reload). Very useful for theme development as any changes to the theme files will be activated without requiring an application restart. Note that the menu needs to be closed for this key combination to have any effect. +By default all controller input (keyboard and controller button presses) will be logged when the --debug flag has been passed. To disable the input logging, the setting DebugSkipInputLogging kan be set to false in the es_settings.xml file. There is no menu entry to change this as it's intended for developers and not for end users. + + +## Portable installation on Windows + +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:\` + +These are the steps to perform: + +* Copy the EmulationStation-DE installation directory to F:\ +* Copy your emulator directories to F:\EmulationStation-DE\ +* Copy your ROMs directory to F:\EmulationStation-DE\ +* Create an empty file named portable.txt in F:\EmulationStation-DE\ + +You should end up with something like this: +``` +F:\EmulationStation-DE\ +F:\EmulationStation-DE\RetroArch-Win64\ +F:\EmulationStation-DE\yuzu\ +F:\EmulationStation-DE\ROMs\ +F:\EmulationStation-DE\portable.txt +``` + +(Yuzu is an optional Nintendo Switch emulator.) + +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. + +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): + +``` +RetroArch-Win64\retroarch.exe +RetroArch\retroarch.exe +yuzu\yuzu-windows-msvc\yuzu.exe +..\RetroArch-Win64\retroarch.exe +..\RetroArch\retroarch.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. + +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\downloaded_media\ +``` + +You now have a fully functional portable retro gaming installation! + +The portable installation works exactly as a normal installation, i.e. you can use the built-in scraper, edit metadata etc. + ## Custom event scripts @@ -1527,10 +1932,10 @@ There are numerous locations throughout ES-DE where custom scripts will be execu The approach is quite straightforward, ES-DE will look for any files inside a script directory that corresponds to the event that is triggered and will then execute all these files. We'll go through two examples: -* Create 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 -* Change the system resolution when launching and returning from a game in order to run the emulator at a lower resolution than ES-DE +* 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 in 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). +**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 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. @@ -1563,7 +1968,7 @@ After creating the two scripts, you should have something like this on the files ~/.emulationstation/scripts/game-end/game_end_logging.sh ``` -Don't forget to make the scripts executable (e.g. 'chmod 755 ./game_start_logging.sh'). +Don't forget to make the scripts executable (e.g. "chmod 755 ./game_start_logging.sh"). 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: @@ -1617,4 +2022,4 @@ After creating the two scripts, you should have something like this on the files ~/.emulationstation/scripts/game-end/set_resolution_4K.sh ``` -Don't forget to make the scripts executable (e.g. 'chmod 755 ./set_resolution_1080p.sh'). +Don't forget to make the scripts executable (e.g. "chmod 755 ./set_resolution_1080p.sh"). diff --git a/README.md b/README.md index 120630995..6e5ee414c 100644 --- a/README.md +++ b/README.md @@ -38,30 +38,24 @@ The following operating systems have been tested with ES-DE (all for the x86 arc ### Download -The latest stable version is 1.0.1 (released 2021-05-01) +The latest version is 1.1.0 (released 2021-08-10) | Package | Operating systems | Architecture | Download link | | :------------------ | :------------------------------------------------------ | :----------- | :------------- | -| Debian DEB package | Ubuntu 20.04 to 21.04, Linux Mint 20, possibly others | x64 (x86) | [emulationstation-de-1.0.1-x64.deb](https://es-de.org/releases/stable/Linux/emulationstation-de-1.0.1-x64.deb)| -| Fedora RPM package | Fedora Workstation 33, possibly others | x64 (x86) | [emulationstation-de-1.0.1-x64.rpm](https://es-de.org/releases/stable/Linux/emulationstation-de-1.0.1-x64.rpm)| -| macOS DMG installer | macOS 10.14 "Mojave" to 11 "Big Sur" | x64 (x86) | [EmulationStation-DE-1.0.1-x64.dmg](https://es-de.org/releases/stable/macOS/EmulationStation-DE-1.0.1-x64.dmg)| -| macOS DMG installer | Legacy macOS 10.11 "El Capitan" to 10.13 "High Sierra" | x64 (x86) | [EmulationStation-DE-1.0.1-x64_legacy.dmg](https://es-de.org/releases/stable/macOS/EmulationStation-DE-1.0.1-x64_legacy.dmg)| -| Windows installer | Windows 10 and 8.1 | x64 (x86) | [EmulationStation-DE-1.0.1-x64.exe](https://es-de.org/releases/stable/Windows/EmulationStation-DE-1.0.1-x64.exe)| - -The latest pre-release version is 1.1.0-rc (released 2021-07-16) - -| Package | Operating systems | Architecture | Download link | -| :------------------ | :------------------------------------------------------ | :----------- | :------------- | -| Debian DEB package | Ubuntu 20.04 to 21.04, Linux Mint 20, possibly others | x64 (x86) | [emulationstation-de-1.1.0-rc-x64.deb](https://es-de.org/releases/beta/Linux/emulationstation-de-1.1.0-rc-x64.deb)| -| Fedora RPM package | Fedora Workstation 33, possibly others | x64 (x86) | [emulationstation-de-1.1.0-rc-x64.rpm](https://es-de.org/releases/beta/Linux/emulationstation-de-1.1.0-rc-x64.rpm)| -| Debian DEB package | Raspberry Pi OS (Raspian) - preview release | ARM | [emulationstation-de-1.1.0-rc-preview-armv7l.deb](https://es-de.org/releases/beta/RaspberryPi/emulationstation-de-1.1.0-rc-preview-armv7l.deb)| -| macOS DMG installer | macOS 10.14 "Mojave" to 11 "Big Sur" | x64 (x86) | [EmulationStation-DE-1.1.0-rc-x64.dmg](https://es-de.org/releases/beta/macOS/EmulationStation-DE-1.1.0-rc-x64.dmg)| -| Windows installer | Windows 10 and 8.1 | x64 (x86) | [EmulationStation-DE-1.1.0-rc-x64.exe](https://es-de.org/releases/beta/Windows/EmulationStation-DE-1.1.0-rc-x64.exe)| - -Unfortunately due to technical reasons, v1.0.1 will be the last release for legacy macOS versions. +| Debian DEB package | Ubuntu 20.04 to 21.04, Linux Mint 20, 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 33, possibly others | x64 (x86) | [emulationstation-de-1.1.0-x64.rpm](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/14892436/download)| +| Debian DEB package | Raspberry Pi OS (Raspian) - preview release | ARM | [emulationstation-de-1.1.0-preview-armv7l.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/14892276/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)| +| Windows installer | Windows 10 and 8.1 | x64 (x86) | [EmulationStation-DE-1.1.0-x64.exe](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/14892429/download)| The Raspberry Pi 4 release is a preview only, there are some bugs such as graphical glitches on this platform and some features like GLSL shaders are missing. Official support will probably be added for this device as of v1.2. +Unfortunately due to technical reasons, v1.0.1 (released 2021-05-01) will be the last version for legacy macOS. + +| Package | Operating systems | Architecture | Download link | +| :------------------ | :------------------------------------------------------ | :----------- | :------------- | +| macOS DMG installer | Legacy macOS 10.11 "El Capitan" to 10.13 "High Sierra" | x64 (x86) | [EmulationStation-DE-1.0.1-x64_legacy.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/14888836/download)| + For some of the rarer operating systems listed at the top you need to build ES-DE from source. The plan is to have ES-DE available in the software repositories of all supported operating systems (where this is applicable), so in the long term building from source should not be required. Please refer to [CHANGELOG.md](CHANGELOG.md) for more information about the releases, including known issues. diff --git a/USERGUIDE.md b/USERGUIDE.md index 313c51e51..511835245 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -1,38 +1,34 @@ # EmulationStation Desktop Edition (ES-DE) - User guide -**Note:** This document is intended as a quick start guide as well as a reference for the user interface settings and functionality. For more in-depth information and details on how to compile ES-DE and perform more advanced configuration, please refer to [INSTALL.md](INSTALL.md). - -Also note that this document is only relevant for the latest stable ES-DE release, if you would like to see the user guide for the current development version, refer to [USERGUIDE-DEV.md](USERGUIDE-DEV.md) instead. +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). Table of contents: [[_TOC_]] -## Basic steps to get ES-DE up and running +## Quick start guide If you just want to get started as quickly as possible, simply follow these steps: 1) Install ES-DE 2) Start the application and press the _Create directories_ button to generate the ROMs directory structure 3) Put your game ROMs in the directories created by the previous step, or see [here](USERGUIDE.md#supported-game-systems) for additional details -4) Install and configure [RetroArch](https://www.retroarch.com) -5) _Windows only: add the RetroArch directory to your system path environmental variable_ -6) Start RetroArch and install the required emulator cores - to see which ones you need look in the systeminfo.txt files in the directories created by step 2, or again see [here](USERGUIDE.md#supported-game-systems) -7) Start ES-DE and follow the on-screen instructions to configure your controller -8) Scrape game media for your collection and play some games! +4) Install [RetroArch](https://www.retroarch.com) +5) Start RetroArch and install the required emulator cores +6) Start ES-DE, scrape game media for your collection and play some games! -As long as ES-DE hasn't frozen, you can always press F4 to close the application. +You can always close the application immediately by pressing F4 on the keyboard. For additional details, read on below. There are also installation videos available at the ES-DE YouTube channel:\ [https://www.youtube.com/channel/UCosLuC9yIMQPKFBJXgDpvVQ](https://www.youtube.com/channel/UCosLuC9yIMQPKFBJXgDpvVQ) -## Getting started +## Installation and first startup -Getting started with ES-DE is easy, just make sure to install the software properly, either manually as built from source code or using one of the supplied packages. On Windows and macOS you'll use the installer instead of a package. +To install ES-DE, just download the package or installer from [https://es-de.org](https://es-de.org) and follow the brief instructions below. -The following operating systems have been tested with ES-DE (all for the x86 architecture unless otherwise stated): +The following operating systems have been tested (all for the x86 architecture unless otherwise stated): * Ubuntu 20.04 to 21.04 * Linux Mint 20 @@ -52,8 +48,7 @@ The installation procedure is just covered briefly here and may differ a bit for **Installing a Linux .deb package** -The .deb package is used for Linux distributions based on Debian, such as Ubuntu, Linux Mint etc. -Running the following should install ES-DE and resolve any dependencies: +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: ``` sudo apt install ./emulationstation-de-1.0.0-x64.deb @@ -61,33 +56,33 @@ sudo apt install ./emulationstation-de-1.0.0-x64.deb **Installing a Linux .rpm package** -On Fedora you run this command to install ES-DE, which should automatically resolve all dependencies: +On Fedora you can use the graphical package installer or run this command, either method should automatically resolve the dependencies: ``` sudo dnf install ./emulationstation-de-1.0.0-x64.rpm ``` -Note that this requires the RPM Fusion repository as there's a dependency on VLC, which is not part of the standard operating system repo. See [INSTALL.md](INSTALL.md#building-on-unix) for details on how to add this. - **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 it's just a 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** -Upon first startup, ES-DE will create its home directory, by default the location is ~/.emulationstation. +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.0 there is no internationalization support, so you would always need to supply the English directory name for your home directory, which is by the way always the real physical name on the file system. For instance in macOS, /Users/leon will be required instead of /Användare/leon which is what's shown inside the operating system for a Swedish localized installation. But using the tilde home symbol '~' is a workaround for this, and it's recommended to always use it for any ES-DE configuration settings that require a path to your home directory as it removes any confusion regarding localized home directory paths. +**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. -On first startup the configuration file `es_settings.cfg` will be generated in the ES-DE home directory, containing all the default settings. A file named `es_systems.cfg` will also be copied from the program resource folder. This file contains the game ROM paths and emulator settings and can be modified if needed. For information on how to do this, refer to the [INSTALL.md](INSTALL.md#es_systemscfg) document. +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. -There's a log file 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. +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, and it can be customized if needed. The customized version needs to 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 how to customize the systems configuration file in the [INSTALL.md](INSTALL.md#es_systemsxml) document. -After ES-DE finds at least one game file, it will populate that game system and the application will start. If there are no game files, a dialog will be shown explaining that you need to install your game files into your ROM directory, and you will also be given a choice to change that ROM directory if you don't want to use the default one. As well you have the option to generate the complete game systems directory structure based on information in es_systems.cfg. +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. -When generating the directory structure, a file named systeminfo.txt will be created in each game system folder which will provide you with some information about the system such as the supported file extensions. Here's an example for the _gc_ system as seen on macOS: +After ES-DE finds at least one game file, it will populate that game system and the application will start. If there are no game files, a dialog will be shown explaining that you need to install your game files into your ROMs directory. You will also be given a choice to change that ROMs directory path if you don't want to use the default one. As well you have the option to generate the complete game systems directory structure based on information in es_systems.xml. + +When generating the directory structure, a file named systeminfo.txt will be created in each game system folder which will provide you with some information about the system. Here's an example for the _gc_ system as seen on macOS: ``` System name: gc @@ -99,7 +94,7 @@ Supported file extensions: .gcm .GCM .iso .ISO .wbfs .WBFS .ciso .CISO .gcz .GCZ .elf .ELF .dol .DOL .dff .DFF .tgc .TGC .wad .WAD .7z .7Z .zip .ZIP Launch command: -/Applications/RetroArch.app/Contents/MacOS/RetroArch -L %EMUPATH%/../Resources/cores/dolphin_libretro.dylib %ROM% +%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dolphin_libretro.dylib %ROM% Platform (for scraping): gc @@ -108,7 +103,9 @@ Theme folder: gc ``` -In addition to this, a file named systems.txt will be created in the root ROM directory which shows the mapping between the directory names and the full system names. +The primary use of this file is to see which RetroArch core the system needs, which you will have to install manually from inside the RetroArch user interface. Also the supported file extensions can be quite useful to know. + +In addition to this, a file named systems.txt will be created in the root of the ROMs directory which shows the mapping between the directory names and the full system names. For example: @@ -118,61 +115,55 @@ genesis: Sega Genesis gx4000: Amstrad GX4000 ``` -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. +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. -Be aware that there will be a lot of directories created if using the template es_systems.cfg 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 significantly as ES-DE would otherwise need to scan for game files for all these systems. +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. ![alt text](images/current/es-de_ui_easy_setup.png "ES-DE Easy Setup") -_This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the real physical path, and that your operating system may present this as a localized path if you are using a language other than English._ +_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._ ## Migrating from other EmulationStation forks **IMPORTANT!!! IMPORTANT!!! IMPORTANT!!!** -ES-DE is designed to be backwards 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 removing the display of the game media if the files are opened in another ES fork. -Due to this, always make backups of at least the following data: +Due to this, always make backups of at least the following directories before testing ES-DE for the first time: ``` ~/.emulationstation/gameslists/ ~/.emulationstation/collections/ -~/.emulationstation/es_settings.cfg -~/.emulationstation/es_systems.cfg ``` -Actually as for `es_systems.cfg` you should probably rename or move it somewhere else as it's strongly recommended to use the es_systems.cfg template shipped with ES-DE (which will be automatically copied from the resources directory on startup as long as a file with this name does not already exist). It may still work to use an existing customized es_systems.cfg file, as again ES-DE should be backwards compatible, but if you have issues launching games this is the first thing to look at. +## Running on high resolution displays -It's probably also a good idea to rename or move `es_settings.cfg` elsewhere as a huge amount of things have changed in the configuration files in ES-DE. +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. - -## Running on 4K displays - -ES-DE fully supports 4K displays (as well as 1440p and other higher resolutions) but some emulators such as RetroArch will always run using the active screen resolution, meaning the emulation will also run in 4K. On slower computers and when resource intensive shaders are in use, the performance may be quite bad. Although it's possible to start ES-DE with the `--resolution` option (which also applies to any launched emulators), this is not really recommended. Full screen mode only works on Unix with this option and even then it's highly dependent on well-written graphics drivers for proper behavior. ES-DE uses the SDL library which insists on setting xrandr to panning mode when doing resolution changes, which is incredibly annoying especially when using Nvidia drivers. - -A better approach is to use the custom event scripts functionality in ES-DE to set a temporary resolution upon launching a game that will be reverted when returning from the emulator. This is detailed as an example for Unix in [INSTALL.md](INSTALL.md#custom-event-scripts) but should be possible to implement similarly on other operating systems such as macOS and Windows. +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. ## Input device configuration -When first starting ES-DE, the application will look for any attached controllers (joysticks and gamepads). If no devices are found, it will be assumed that only keyboard navigation is to be used and the default keyboard mappings will be applied. It's recommended to change these default values, and a message will be displayed describing just this. It's however possible to hide this notification permanently and continue to use the default keyboard mappings if you're happy with them. +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. -If a controller is attached when starting ES-DE and no `es_input.cfg` input configuration file exists, you will be presented with the input configuration dialog. Just follow the steps as described to map the inputs. +You can also force a run of this tool directly on startup via the command line argument `--force-input-config`. -If an es_input.cfg configuration file exists, you will not be presented with the input device configuration screen as that would normally just be annoying. If you need to configure a device to control the application (i.e. you've replaced your controller), you can do so by starting ES-DE with the command line argument `--force-input-config` or you can manually delete the es_input.cfg file prior to starting the application. Alternatively you can navigate to the menu using your keyboard and select **Configure input** to configure your new device. +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. +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. -Both new and old devices can be (re)configured at any time via the `Configure input` menu entry. New devices will be appended to the existing input configuration file, so your old devices will retain their configuration. +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 EmulationStation with the default settings, you will see the main screen first. From here you can navigate your game systems and enter their respective gamelists. +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 be scrolling left or right. +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. -The game systems are sorted by their full names, as defined in es_systems.cfg. +The game systems are sorted by their full names, as defined in the es_systems.xml file. ![alt text](images/current/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._ @@ -181,13 +172,13 @@ _The **System view** is the default starting point for the application, it's her The gamelist view is where you browse and start your games, and it's where you will spend most of your time using ES-DE. -Upon startup with the default settings, ES-DE is set to the gamelist view style **Automatic**. In this mode the application will look for any game media files (videos and images) and set the view style accordingly. If at least one image is found for any game, the view style **Detailed** will be shown, and if at least one video file is found, the view style **Video** will be selected (superceding the Detailed style). If no game media files are found for a system, the simple **Basic** view will be selected. Note that this automatic selection is applied per game system. +Upon startup with the default settings, ES-DE is set to the gamelist view style **Automatic**. In this mode the application will look for any game media files (videos and images) and set the view style accordingly. If at least one image is found for any game, the view style **Detailed** will be shown, and if at least one video file is found, the view style **Video** will be selected (superceding the Detailed style). If no game media files are found for a system, the simple **Basic** view style will be selected. This automatic selection is applied per game system. -Also note that the Video view style requires that the theme supports it. If not, the Detailed style will be selected instead. (The default theme rbsimple-DE supports both of these view styles). +Note that the Video view style requires that the theme supports it. If not, the Detailed style will be selected instead. The default theme rbsimple-DE supports both of these view styles. -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. +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.0 this is highly experimental and its use is not recommended. Future versions will update this style to a more useful state. +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. 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. @@ -195,7 +186,7 @@ If the theme supports it, there's a gamelist information field displayed in the _The **Gamelist view** is where you browse the games for a specific system._ ![alt text](images/current/es-de_basic_view_style.png "ES-DE Basic View Style") -_Here's an example of what the Basic view style looks like. Needless to say, ES-DE is not intended to be used like this. After scraping some game media for the system, the view style will automatically change to Detailed or Video (assuming the Automatic view style has been selected)._ +_Here's an example of what the Basic view style looks like. Needless to say, ES-DE is not intended to be used like this. After scraping some game media for the system, the view style will automatically change to Detailed or Video (assuming the Automatic view style option has been selected)._ ## UI modes @@ -207,13 +198,13 @@ These modes mandate the functionalty provided by the application in the followin * 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. -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**. It works to use either a keyboard or a configured controller to input the passkey sequence, but it can't be entered when a menu is open. +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. -The application can also be forced into any of the three modes via the command line options `-force-full`, `--force-kiosk` and `-force-kid`. Note that this is only temporary until the restart of the application, unless the settings menu is entered and the setting is saved to the configuration file (this assumes that the main menu is available in the selected UI mode of course). +The application can also be forced into any of the three modes via the command line options `--force-full`, `--force-kiosk` and `--force-kid`. This is only temporary until the restart of the application, unless the settings menu is entered and the setting is saved to the configuration file (this assumes that the main menu is available in the selected UI mode of course). ## Help system -There is a help system available throughout the application that provides an overview of the possible actions and buttons that can be used. Note though that some general button 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. +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/current/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._ @@ -221,7 +212,7 @@ _The help system is displayed at the bottom of the screen, showing the various a ## General navigation -The built-in help system will provide a contextual summary of the available navigation options, but here's still a general overview. These are the inputs you mapped in the previous input device configuration step. Note that this is not an exhaustive list, but it covers most situations. +The built-in help system will provide a contextual summary of the available navigation options, but here's still a general overview. These are the buttons mappings automatically applied by ES-DE, but they can be customized using the input configurator as described earlier in this document. It's not an exhaustive list, but it covers most situations. The button names are based on the Xbox 360 controller as that is the naming convention used by the SDL library which handles the controller input in ES-DE. The default keyboard mappings are shown in brackets. @@ -233,17 +224,17 @@ Navigate up and down in gamelists, between systems in the system view (if the th **Left and right**\ _(Arrow left / Arrow right)_ -Navigate between gamelists (if _Quick system select_ has been activated in the options), or between systems in the system view (if the theme has a horizontal carousel). +Navigate between gamelists (if the _Quick system select_ option has been enabled), between systems in the system view (if the theme has a horizontal carousel) and between media files in the media viewer. If the _Enable screensaver controls_ option has been enabled, either button also randomly selects a new game when using the Video or Slideshow screensavers. **Start button**\ _(Escape)_ Opens and closes the main menu. -**Select button**\ +**Back button**\ _(F1)_ -Opens and closes the game options menu in the gamelist view, or toggles the screensaver in the system view (if the _Enable screensaver controls_ setting is activated). +Opens and closes the game options menu in the gamelist view, or toggles the screensaver in the system view (if the _Enable screensaver controls_ setting is enabled). **Left and right shoulder buttons**\ _(Page up / Page down)_ @@ -258,12 +249,12 @@ Jumps to the first and last entry of the gamelists, menus and text edit dialogs. **Left and right thumbstick click**\ _(F2 / F3)_ -Reserved for future use. +Jumps to a random game or system depending on whether pressed when in the system view or gamelist view. Only available if the _Enable random system or game button_ option has been enabled. **A button**\ _(Enter)_ -Select button to open gamelists from the system view, launch games, choose menu entries etc. +Opens gamelists from the system view, launches games, selects menu entries etc. **B button**\ _(Back key)_ @@ -273,31 +264,30 @@ Back button, self explanatory. **X button**\ _(Delete)_ -Selects random games and systems. Used by some other minor functions as explained by the help system and/or this guide. +Starts the game media viewer (which is accessible from the gamelist views). Used by some other minor functions as explained by the help system and/or this guide. **Y button**\ _(Insert on Unix and Windows, F13 on macOS)_ -Marks games as favorites in the gamelist views. Used by some other minor functions as explained by the help system and/or this guide. +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)** -Quits the application. - +Quits the application immediately. ## Getting your games into ES-DE -For most systems, this is very straightforward, just put your game files into the folder corresponding to the platform name (these names can be found at the [end](USERGUIDE.md#supported-game-systems) of this guide.) +For most systems this is straightforward, just put your game files into the folder corresponding to the platform name (these names can be found at the [end](USERGUIDE.md#supported-game-systems) of this guide.) -For some systems though, a more elaborate setup is required, and we will attempt to cover such situations in this guide as well. +But for some systems a more elaborate setup is required, and we will attempt to cover such situations in this guide as well. ### Single game file installation -Let's start with the simple scenario of a single ROM game file per platform, which is the case for the majority of systems. In this example we're setting up ES-DE to play Nintendo Entertainment System games. +Let's start with the simple scenario of a single ROM file per game, which is the case for the majority of platforms. In this example we're setting up ES-DE to play Nintendo Entertainment System games. -The supported file extensions are listed in [es_systems.cfg_unix](resources/templates/es_systems.cfg_unix), [es_systems.cfg_macos](resources/templates/es_systems.cfg_macos) and [es_systems.cfg_windows](resources/templates/es_systems.cfg_windows). +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 es_systems.cfg_unix file: +Here is the snippet from the unix/es_systems.xml file: ``` @@ -305,21 +295,23 @@ Here is the snippet from the es_systems.cfg_unix file: Nintendo Entertainment System %ROMPATH%/nes .nes .NES .unf .UNF .unif .UNIF .7z .7Z .zip .ZIP - retroarch -L %COREPATH%/nestopia_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/nestopia_libretro.so %ROM% nes nes ``` -It's required that the ROM files are in one of the supported file extensions, or ES-DE won't find them. +The ROM files must named using one of the supported file extensions, or ES-DE won't find them. It's highly recommended to use filenames that are corresponding to the full name of the game, otherwise you will need to manually feed the scraper the game name when scraping which is very tedious. -The default game directory folder is ~/ROMs. On Unix this defaults to /home/\/ROMs, on macOS /Users/\/ROMs and on Windows C:\Users\\\ROMs\. +**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. 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 directory corresponding to the \ tag in es_systems.cfg, in 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: @@ -374,11 +366,11 @@ It's of course also possible to skip this type of directory structure and put al 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**. -As well it's recommended 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. ### Special game installation considerations -Not all systems are as simple as described above, or sometimes there are multiple ways to configure the systems. So specifics to such systems will be covered here. Consider this a work in progress as there are many systems supported by ES-DE. +Not all systems are as simple as described above, or there may be multiple ways to do the configuration. Specifics for such systems will be covered here. Consider this a work in progress as there are many platforms supported by ES-DE. #### Arcade and Neo Geo @@ -386,13 +378,37 @@ 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 used 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 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. + +#### Nintendo Switch + +The emulator for Nintendo Switch is Yuzu, which is distributed as a Snap package, Flatpak package or AppImage on Linux and as a regular installer on Windows. At the moment there is unfortunately no macOS release of this emulator and it's unclear if it can run on BSD Unix. + +If installed as a Snap or Flatpak package 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 more complicated as there is no real standardized directory for storing these images. + +What ES-DE will do is to look for _yuzu.AppImage_ in the system PATH as well as in the following locations: + +``` +~/Applications/yuzu.AppImage +~/.local/bin/yuzu.AppImage +~/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. + +Note that the name is case sensitive, so _yuzu.appimage_ will not be found by ES-DE. + +For Windows, ES-DE will look for _yuzu.exe_ in the system Path as well as in the default installation directory `~\AppData\Local\yuzu\yuzu-windows-msvc\` + +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. #### 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-disk images as described above. +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-disk images as described earlier. Here's an example of what the file structure could look like: @@ -410,13 +426,13 @@ 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 a .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 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. 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. #### Ports -Ports are not really executed using emulators, but are rather applications running natively in 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. +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. @@ -466,9 +482,11 @@ You don't need to set execution permissions for these scripts, ES-DE will run th #### Lutris -Lutris runs only on Unix so it's only present as a placeholder in the es_systems.cfg templates for macOS and Windows. +Lutris runs only on Unix so it's only present as a placeholder in the es_systems.xml files for macOS and Windows. -These games are executed via the Lutris binary (well it's actually a Python script), and you simply create a shell script per game using the syntax `lutris lutris:rungame/` +These games are executed via the Lutris binary (well it's actually a Python script) and you simply create a shell script per game inside the lutris system directory. + +Add the game information to each shell script using the syntax `lutris lutris:rungame/` You can see the list of installed games by running this command: ``` @@ -502,9 +520,9 @@ As an alternative, you can add the Lutris games to the Ports game system, if you **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. -As for the setup, it's recommended to place shell scripts/batch files directly in the root folder, with the filenames of these scripts corresponding to the game names. +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. -Add the game information to each file using the syntax `steam://rungameid/` +Add the game information to each shell script using the syntax ` steam://rungameid/` Here's an example for the game Broforce, first on Unix with the filename `Broforce.sh`: @@ -519,7 +537,6 @@ And on macOS with the filename `Broforce.sh`: And finally on Windows with the filename `Broforce.bat`: ``` -@echo off "c:\Program Files (x86)\Steam\steam.exe" steam://rungameid/26800 ``` @@ -531,6 +548,7 @@ On Linux it's very easy to find all your game ID's by looking in the desktop ent ``` grep steam ~/.local/share/applications/*desktop | grep rungameid +/home/myusername/.local/share/applications/Broforce.desktop:Exec=steam steam://rungameid/274190 /home/myusername/.local/share/applications/FEZ.desktop:Exec=steam steam://rungameid/224760 /home/myusername/.local/share/applications/INSIDE.desktop:Exec=steam steam://rungameid/304430 /home/myusername/.local/share/applications/Subnautica.desktop:Exec=steam steam://rungameid/264710 @@ -539,34 +557,24 @@ grep steam ~/.local/share/applications/*desktop | grep rungameid This of course assumes that you have menu entries setup for your Steam games. -## Emulator setup +## 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.cfg` 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.cfg file, please refer to the [INSTALL.md](INSTALL.md) document which goes into details on the structure of this file and more advanced configuration topics in general. +ES-DE is a game browsing front-end 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. 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. -A general recommendation regarding installation on Linux though is to try to avoid the versions 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 or Flatpak distributions or build from source. +Keep in mind that ES-DE will not install any RetroArch cores, you need to do this manually from within the RetroArch user interface. -In order to use the default es_systems.cfg file, you need to make sure that the emulator binary is in the operating system's path. On Unix systems this is normally not an issue (unless Flatpak is used) as a package manager has typically been used to install the emulator, and even if compiled from source there is a standardized directory structure which should have you covered. Likewise on macOS, it's assumed that the emulator is installed under the Applications folder so everything should just work. But for Windows you may need to add the emulator directory to your %PATH% variable manually (tip: open Settings from the Start menu and search for _path_). +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 installing RetroArch as Flatpak on Linux you have to work around an incredibly annoying deficiency of this type of software distribution which is that there will be no RetroArch executable directly available to run. To run RetroArch you would instead need to execute `flatpak run org.libretro.RetroArch` and to get ES-DE to work properly with this you either need to use a customized es_systems.cfg file, or create a shell script somewhere in your path that executes the Flatpak command. -Here's an example of such a script: ``` -#!/bin/sh -flatpak run org.libretro.RetroArch "$@" +~/Applications/RetroArch-Linux-x86_64.AppImage +~/.local/bin/RetroArch-Linux-x86_64.AppImage +~/bin/RetroArch-Linux-x86_64.AppImage ``` -For instance on Fedora you could place the shell script in `~/bin` and name it `retroarch` and then everything will work fine. - -There is also a Flatpak-specific es_systems.cfg template shipped with ES-DE, but you need to manually install it if you would like to use it: -``` -cp /usr/share/emulationstation/resources/templates/es_systems.cfg_unix_flatpak ~/.emulationstation/es_systems.cfg -``` - -The source path may differ from this example depending on which prefix was used when building ES-DE. - -As an alternative, if the emulator is not in your search path, you can either hardcode an absolute path in es_systems.cfg or use the %ESPATH% variable to set the emulator relative to the ES-DE binary location. Again, please refer to [INSTALL.md](INSTALL.md#es_systemscfg) for details regarding this. - 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. @@ -576,7 +584,7 @@ Scraping means downloading metadata and game media files (images and videos) for 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. -Here is an overview of what's supported by ES-DE and these scrapers: +Here's an overview of what's supported when using these scrapers: | Media type or option | ScreenScraper | TheGamesDB | | :----------------------- | :-----------: | :--------: | @@ -606,7 +614,7 @@ The single-game scraper is launched from the metadata editor. You navigate to a ### Multi-scraper -The multi-scraper is accessed from the main menu by selecting **Scrape**. +The multi-scraper is accessed from the main menu by entering the **Scraper** menu and then selecting the **Start** button. ### Scraping process @@ -614,17 +622,17 @@ The process of scraping games is basically identical between the single-game scr 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. -The behavior of using the metadata name rather than the file name can be changed using the setting **Search using metadata name**. +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. -Note that there is an exception to this behavior for arcade games (MAME and Neo Geo). For ScreenScraper the short MAME names are used by default as this scraper service fully supports that. For TheGamesDB the short names are instead expanded to the full games names using a lookup in the MAME name database supplied with the ES-DE installation. It's possible to override this automatic behavior by using the _Refine Search_ button in the scraper GUI if the search did not yield any results, or if the wrong game was returned. In general though, searching for arcade games is very reliable assuming the physical game files follow the MAME name standard. +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. -Apart from this, hopefully the scraping process should be self-explanatory once you try it in ES-DE. +Apart from this, hopefully the scraping process should be self-explanatory. ### Manually copying game media files -If you already have a library of game media (images and videos) you can manually copy it into ES-DE. +If you already have a library of game media (images and videos) you can manually copy these files into ES-DE. -The default directory is `~/.emulationstation/downloaded_media//` +The default media directory is `~/.emulationstation/downloaded_media//` For example on Unix: ``` @@ -643,7 +651,7 @@ For example on Windows: C:\Users\Myusername\.emulationstation\downloaded_media\c64\screenshots\ ``` -The media type directories are: +The media directories per game system are: * 3dboxes * covers @@ -652,7 +660,7 @@ The media type directories are: * screenshots * videos -**Note:** The miximages files are not generated by ES-DE as of v1.0, but if you have used something like [Skyscraper](https://github.com/muldjord/skyscraper) to generate this type of images for your game collection, then they can be displayed inside ES-DE by locating them in this directory. +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: @@ -667,18 +675,16 @@ Must have corresponding filenames for its media files in this fashion: ~/.emulationstation/downloaded_media/c64/videos/Multidisk/Last Ninja 2/Last Ninja 2.mp4 ``` -JPG and PNG file formats and file extensions are supported for images, and AVI, MKV, MOV, MP4 and WMV are supported for videos. +For images .jpg and .png file extensions are supported and for videos .avi, .mkv, .mov, .mp4 and .wmv are supported. -Remember that on Unix files 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. +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. -As an alternative, you can also locate your game media in the ROM directory. This is explained below when covering the option **Display game media from ROM directories**. This is however not recommended and the built-in scraper will never save any game media to this folder structure. - -It's possible to change the game media directory 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 views. It contains the scraper, the input configuration tool and the application settings. Settings are saved when navigating back from any menu screen, assuming at least one setting was changed. Pressing F4 to quit the application 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) will also save any pending changes. ![alt text](images/current/es-de_main_menu.png "ES-DE Main Menu") _The ES-DE main menu._ @@ -698,7 +704,7 @@ Scraper service selection, currently ScreenScraper.fr and TheGamesDB.net are sup **Scrape these games** -Criteria for what games to include in the scraping. It can be set to _All games, Favorite games, No metadata, No game image, No game video_ or _Folders only_. +Criteria for what games to include. It can be set to _All games, Favorite games, No metadata, No game image, No game video_ or _Folders only_. **Scrape these systems** @@ -710,7 +716,7 @@ Setup of ScreenScraper account. **Use this account for ScreenScraper** -Whether to use the account that has been setup here. If this is disabled, the username and password configured 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. +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** @@ -718,15 +724,15 @@ Username as registered on screenscraper.fr. **ScreenScraper password** -The password as registered on screenscraper.fr. Note that the password is masked using asterisks on this screen, and the password input field will be blank when attempting to update an existing password. Entering a new password will of course work, and it will be saved accordingly. Be aware though that the es_settings.cfg file contains the password in clear text. +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. #### Content settings -Describes the content types to include in the scraping. Most users will probably not need to adjust so many of these. +Describes the content types to include in the scraping. **Scrape game names** -Whether to scrape the names of the games. This does not affect the actual files on the filesystem and is only used for viewing and sorting purposes. The downloaded media files are also 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 the 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)_ @@ -754,11 +760,55 @@ Logotype for the game. **Scrape 3D box images** _(ScreenScraper only)_ -These images are currently unused, but will be used for future versions of ES-DE so it's recommended to keep this option enabled. +These are primarily 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. + +**Miximage resolution** + +It's possible to select betweeen the 1280x960, 1920x1440 and 640x480 resolutions for the generated miximages. It's normally recommended to use the default option 1280x960 which gives good image quality without slowing down ES-DE too much. But for very weak machines, 640x480 may be a better option. The 1920x1440 resolution is normally not recommended as it brings little quality improvements over 1280x960 and slows down the gamelist browsing. + +**Screenshot scaling method** + +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. + +**Generate miximages when scraping** + +Enables or disables the miximage generator when scraping. Applies to both the single-game scraper and the multi-scraper. + +**Overwrite miximages (scraper/offline generator)** + +Controls whether miximages should be overwritten or not. Note that the scraper setting _Overwrite files and data_ does not affect the miximages. + +**Remove letterboxes from screenshots** + +With this option enabled, any horizontal pure black areas at the top and bottom of the screenshots are automatically cropped. + +**Remove pillarboxes from screenshots** + +With this option enabled, any vertical pure black areas at the left and right sides of the screenshots are automatically cropped. + +**Incude marquee image** + +Whether to include the marquee (wheel) image in the composite miximage. + +**Incude box image** + +Whether to include the box image in the composite miximage. If a 3D box exists for the game, this will be used. + +**Use cover image if 3D box is missing** + +Whether to use the 2D box cover as fallback if the 3D box image is missing for the game. + +**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. #### Other settings -Various scraping settings. Most users will probably not need to adjust so many of these. +Various scraping settings. **Region** _(ScreenScraper only)_ @@ -766,25 +816,23 @@ The region to scrape for. This affects game names, game media and release dates. **Preferred language** _(ScreenScraper only)_ -Multiple languages are supported by ScreenScraper, and this affects translations of game genres and game descriptions. As the option name implies this is the preferred language only as not all games have had their metadata translated. Unfortunately some less used languages have quite few games translated to them but hopefully this will improve over time as there's an ongoing community effort to make more translations. If the preferred language is not available for a game, ES-DE will fall back to scraping the English metadata. +Multiple languages are supported by ScreenScraper, and this affects translations of game genres and game descriptions. As the option name implies this is the preferred language only as not all games have had their metadata translated. Unfortunately some less used languages have quite few games translated, but hopefully this will improve over time as there's an ongoing community effort to make more translations. If the preferred language is not available for a game, ES-DE will fall back to using the English metadata. **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 vaules 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. +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. **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.0 the file verification is crude as it's just checking if the file is less than 350 bytes in size which should indicate a server error response rather than a real media file. In some exceedingly rare situations, proper media files may be smaller than 350 bytes, and for those rare instances, simply disabling this setting temporarily allows these files to be scraped. Future versions of ES-DE will implement proper CRC/checksum verifications for ScreenScraper and possibly media file integrity checks for TheGamesDB (as this scraper service does not provide file checksums). +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. **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 name regardless of such data being available, then turn off this option. - -Note that when using TheGamesDB as scraper service for arcade games (MAME/Neo Geo), the short MAME name will always be expanded to the full game name as this scraper does not properly support searches using MAME names. Also note that you need to save the game name in the metadata editor before you can use it for scraping. +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. **Interactive mode** _(Multi-scraper only)_ -If turned off, the scraping will be fully automatic and will not stop on multiple results or on missing games. +If turned off, the scraping will be fully automatic and will not stop on multiple results or when no matching game was found. **Auto-accept single game matches** _(Multi-scraper only)_ @@ -792,7 +840,7 @@ Used in conjunction with interactive mode, to not having to confirm searches whe **Respect per-file scraper exclusions** _(Multi-scraper only)_ -It's possible to set a flag per game file or directory to indicate that it should be excluded from the multi-scraper. This setting makes it possible to override that restriction and scrape all entries anyway. +It's possible to set a flag per game file or folder using the metadata editor to indicate that it should be excluded from the multi-scraper. This setting makes it possible to override that restriction and scrape all entries anyway. **Exclude folders recursively** _(Multi-scraper only)_ @@ -802,13 +850,17 @@ If this setting is enabled and a folder has its flag set to be excluded from the Enabling this option causes folders themselves to be included by the scraper. This is useful for DOS games or any multi-disk games where there is a folder for each individual game. +**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". + ### UI settings -Various settings that affects the user interface. +Various settings that affect the user interface. **Gamelist on startup** -If set to _None_, the system view will be showed. Any other value will jump to that game system automatically on startup. +If set to _None_, the system view will be displayed. Any other value will jump to that game system automatically on startup. **Gamelist view style** @@ -816,7 +868,7 @@ Sets the view style to _Automatic, Basic, Detailed, Video_ or _Grid_. See the de **Transition style** -Graphical transition effect, either _Slide, Fade_ or _Instant_. +Transition animation when navigating between the views. Can be set to _Slide, Fade_ or _Instant_. **Theme set** @@ -830,9 +882,13 @@ Sets the user interface mode for the application to _Full, Kiosk_ or _Kid_. See The order in which to sort your gamelists. This can be overriden per game system using the game options menu, but that override will only be persistent during the application session. The _System_ sorting can not be selected here as it's only applicable to collection systems. -**Menu opening effect** _(OpenGL renderer only)_ +**Menu opening effect** -Animation to play when opening the main menu or the game options menu. Can be set to _Scale-up, _Fade-in_ or _None_. +Animation to play when opening the main menu or the game options menu. Also sets the animation for the game launch screen. Can be set to _Scale-up_ or _None_. + +**Launch screen duration** + +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. **Blur background when menu is open** _(OpenGL renderer only)_ @@ -844,7 +900,7 @@ With this option enabled, there are black pillarboxes (and to a lesser extent le **Render scanlines for gamelist videos** _(OpenGL renderer only)_ -Whether to use a shader to render scanlines for videos in the gamelist view. The effect is usually pretty subtle as the video is normally renderered in a limited size in the GUI, and the scanlines are sized relative to the video window size. +Whether to use a shader to render scanlines for videos in the gamelist view. The effect is usually pretty subtle as the video is normally renderered in a limited size in the GUI and the scanlines are sized relative to the video window size. **Sort folders on top of gamelists** @@ -856,15 +912,23 @@ 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 very confusing. +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. + +**Use plain ASCII for special gamelist characters** + +There are some special characters in ES-DE such as the favorites star, the folder icon and the tickmark (seen when editing custom collections) that are displayed using symbols from the bundled Font Awesome. This normally looks perfectly fine, but on some specific theme sets with very pixelated fonts such as [es-themes-snes-mini](https://github.com/ruckage/es-theme-snes-mini) and [es-themes-workbench](https://github.com/ehettervik/es-theme-workbench) these symbols look terrible. For such themes, this option is available, which will use plain ASCII characters instead of the Font Awesome symbols. For the favorites an asterisk `*` will be used, for folders a hash sign `#` will be used and for the tickmark an exclamation mark `!` will be used. This only applies to the gamelist view, in all other places in the application the Font Awesome symbols are retained. Make sure to disable this option if not using such a pixelated theme as it looks equally terrible to enable this option on themes where it's not supposed to be used. **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 name. 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 will be shown instead. -**Enable shortcut to toggle favorites** +**Enable toggle favorites button** -This setting enables the _Y_ button for quickly toggling a game as favorite. Although this may be convenient at times, it's also quite easy to accidentally remove a favorite tagging of a game when using the application more casually. As such it could sometimes make sense to disable this functionality. It's of course still possible to mark a game as favorite using the metadata editor when this setting is disabled. For additional restrictions, the application can be set to Kid or Kiosk mode as is explained [elsewhere](USERGUIDE.md#ui-modes) in this guide. Note that this setting does not affect the functionality to use the _Y_ button to add games to custom collections. +This setting enables the _Y_ button for quickly toggling a game as favorite. Although this may be convenient at times, it's also quite easy to accidentally remove a favorite tagging of a game when using the application more casually. As such it could sometimes make sense to disable this functionality. It's of course still possible to mark a game as favorite using the metadata editor when this setting is disabled. The option does not affect the use of the _Y_ button to add or remove games when editing custom collections. + +**Enable random system or game button** + +This enables or disables the ability to jump to a random system or game. It's mapped to the thumbstick click button, either the left or right thumbstick will work. The help prompts will also visually indicate whether this option is enabled or not. **Enable gamelist filters** @@ -872,23 +936,47 @@ Activating or deactivating the ability to filter your gamelists. This can normal **Enable quick system select** -If enabled, it will be possible to jump between gamelists using the _Left_ and _Right_ buttons without having to first go back to the system view. +If enabled, it's possible to navigate between gamelists using the _Left_ and _Right_ buttons without having to first go back to the System view. **Display on-screen help** -Activating or deactivating the built-in help system that provides contextual information regarding button usage. +Activates or deactivates the built-in help system that provides contextual information regarding button usage. **Play videos immediately (override theme)** Some themes (including rbsimple-DE) display the game images briefly before playing the game videos. This setting forces the videos to be played immediately, regardless of the configuration in the theme. Note though that if there is a video available for a game, but no images, the video will always start to play immediately no matter the theme configuration or whether this settings has been enabled or not. +#### Media viewer settings + +Settings for the media viewer that is accessible from the gamelist views. + +**Keep videos running when viewing images** + +With this option enabled, the video will continue to run when viewing the images for the game. If disabling this setting, the video will stop immediately when browsing to the first image, and it will restart when navigating back to the video. + +**Stretch videos to screen resolution** + +This will fill the entire screen surface but will probably break the aspect ratio of the video. + +**Render scanlines for videos** _(OpenGL renderer only)_ + +Whether to use a shader to render scanlines for the videos. Be aware that this is quite demanding for the GPU. + +**Render blur for videos** _(OpenGL renderer only)_ + +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)_ + +Whether to use a shader to render scanlines for the screenshot images. + #### Screensaver settings Settings for the built-in screensaver. **Start screensaver after (minutes)** -After how many minutes to start the screensaver. If set to 0 minutes, the timer will be deactivated and the screensaver will never start automatically. It's however still possible to start the screensaver manually in this case, assuming the _Enable screensaver controls_ setting is enabled. Note that while any menu is open, the screensaver will not start regardless of how this timer setting is configured. +After how many minutes to start the screensaver. If set to 0 minutes, the timer will be deactivated and the screensaver will never start automatically. It's however still possible to start the screensaver manually in this case, assuming the _Enable screensaver controls_ setting is enabled. While any menu is open, the screensaver will not start regardless of how this timer setting is configured. **Screensaver type** @@ -896,7 +984,7 @@ The screensaven type to use; _Dim_, _Black_, _Slideshow_ or _Video_. **Enable screensaver controls** -This includes the ability to start the screensaver manually using the _Select_ 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 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. #### Slideshow screensaver settings @@ -908,11 +996,11 @@ For how long to display images before changing to the next game. Allowed range i **Stretch images to screen resolution** -This will fill the entire screen surface but will possibly break the aspect ratio of the image. +This will fill the entire screen surface but will probably break the aspect ratio of the image. **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 a favorite. +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. **Render scanlines** _(OpenGL renderer only)_ @@ -928,7 +1016,7 @@ Whether to search the custom image directory recursively. **Custom image directory** -The directory for the custom images. +The directory for the custom images. The tilde `~` symbol can be used which will expand to the user home directory. It's also possible to use the %ESPATH% and %ROMPATH% variables which will set the directory relative to the ES-DE binary directory or the ROMs directory. #### Video screensaver settings @@ -936,19 +1024,15 @@ 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 setting), the next game will be selected after the entire video has finished playing. - -**Play audio for screensaver videos** - -Muting or playing the audio. +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. **Stretch videos to screen resolution** -This will fill the entire screen surface but will possibly break the aspect ratio of the video. +This will fill the entire screen surface but will probably break the aspect ratio of the video. **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 a favorite. +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. **Render scanlines** _(OpenGL renderer only)_ @@ -961,11 +1045,11 @@ Whether to use a shader to render a slight horizontal blur which somewhat simula ### Sound settings -General sound settings. +Various sound settings. **System volume** _(Linux and Windows only)_ -As the name implies, this sets the overall system volume and not the volume specifically for ES-DE. Note that the volume change is applied only after leaving the sound settings menu. +As the name implies, this sets the overall system volume and not the volume specifically for ES-DE. The volume change is applied when leaving the sound settings menu and not immediately when moving the slider. **Navigation sounds volume** @@ -973,36 +1057,61 @@ Sets the volume for the navigation sounds. **Video player volume** -Sets the volume for the video player. This applies to both the gamelist views and the video screensaver. +Sets the volume for the video player. This applies to the gamelist view, the media viewer and the video screensaver. **Play audio for videos in the gamelist view** -With this turned off, audio won't play for game videos in the gamelists. +With this turned off, audio won't play for videos in the gamelists. + +**Play audio for media viewer videos** + +With this turned off, audio won't play for videos displayed using the media viewer. + +**Play audio for screensaver videos** + +With this turned off, audio won't play for videos when using the video screensaver. **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. +### Input device settings + +Settings related to the input devices, i.e. the keyboard and controllers. + +**Controller type** + +This setting gives the ability to choose between the controller types _Xbox, Xbox 360, PlayStation 4, PlayStation 5_ and _SNES_ (Super Nintendo). Doing so alters the help icons and help text as well as the icons and text for the input device configurator. The setting is only cosmetic and does not change the controller behavior or the controller button mappings. + +**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. + +**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. + + ### Game collection settings -Handles collections, which are built using the games already present in your game systems. See the [collections](USERGUIDE.md#game-collections) section below in this document for more information. +Handles collections, which are assembled using games present in the game systems. See the [collections](USERGUIDE.md#game-collections) section below in this document for more information. -**Finish editing _'COLLECTION NAME'_ collection** _(Entry only displayed when editing a custom collection)_ +**Finish editing _'COLLECTION NAME'_ collection** _(Entry only visible when editing a custom collection)_ Self explanatory. **Automatic game collections** -This opens a screen that lets you enable or disable the automatic game collections _All games, Favorites_ and _Last played_. +This lets you enable or disable the automatic game collections _All games, Favorites_ and _Last played_. **Custom game collections** This lets you enable or disable your own custom game collections. -**Create new custom collection from theme** _(Entry only displayed if the ability is provided by the theme set)_ +**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 here. 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** @@ -1010,7 +1119,7 @@ This lets you create a completely custom collection with a name of your choice. **Delete custom collection** -This permanently deletes a custom collection, including its configuration file on the file system. A list of available collections is shown, and a confirmation dialog is displayed before committing the actual deletion. Only one collection at a time can be deleted. +This permanently deletes a custom collection, including its configuration file on the file system. A list of available collections is shown, and a confirmation dialog is displayed before performing the actual deletion. Only one collection at a time can be deleted. **Sort favorites on top for custom collections** @@ -1018,11 +1127,11 @@ 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_ but is applied specifically to custom collections. It's disabled by default. +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. **Group unthemed custom collections** -With this enabled, if you have created custom collections and there is no theme support for the names you've selected, the collections will be grouped in a general collection which is correctly themed. It's strongly recommended to keep this option enabled as otherwise your collections would be completely unthemed which doesn't make much sense. This option is provided mostly for testing and theme development purposes. +With this enabled, if you have created custom collections and there is no theme support for the names you've selected, the collections will be grouped in a general collection system which is correctly themed. It's strongly recommended to keep this option enabled as otherwise your collections would be completely unthemed which doesn't make much sense. This option is provided mostly for testing and theme development purposes. **Show system names in collections** @@ -1034,87 +1143,93 @@ These are mostly technical settings. **VRAM limit** -The amount of video RAM to use for the application. Defaults to 256 MiB 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 and with lots of game systems enabled, it's recommended to increase this number to 512 MiB or so 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.cfg file manually, ES-DE will log a warning and automatically adjust the value within the allowable range. +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. **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 of 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.cfg. Be aware that 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). +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 and by manual editing (using the metadata editor), but also when launching it as this updates the _Times played_ counter and the _Last played_ date. 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. +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. **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_ -**Emulator core path** - -This setting defines the path for which to search for emulator cores. This is used by the variable %COREPATH% which can be included in the systems configuration file es_systems.cfg. By default this variable and corresponding setting is used on all operating systems except Windows. For Windows the %COREPATH% variable is not included in the es_systems.cfg template and the default core path value is therefore set to blank. If required for special setups it can be used for this operating system, but the primary use is on Unix where the core path may vary depending on the operating system, how the emulator was packaged etc. For example the default RetroArch core directory is ~/.config/retroarch/cores if compiled from source code but if installed as a Snap package or as part of the OS repository the cores could be stored elsewhere. The setting is primarily intended for RetroArch but it can be used for any emulator that utilizes discrete emulator cores. When attempting to launch a game, the core for the game system will be searched in each of the defined directories until the first match occurs. Multiple directories can be defined by separating them using colons on Unix and macOS and by semicolons on Windows. Please see [INSTALL.md](INSTALL.md#es_systemscfg) for more information about this. - **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 games and when returning from games. It could potentially cause some issues on some Windows installations though, so the option is 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 when returning from games. But it can potentially cause issues on some Windows installations so it's disabled by default. -**Run in background (while game is launched)** _(Windows only)_ +**Run in background (while game is launched)** -This is really a last-resort setting if ES-DE freezes when launching games. This issue seems to only occur on Windows 8.1 and older but that's not fully confirmed. ES-DE will behave a bit strange with this option enabled so keep it disabled unless you absolutely need it. +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. + +**AMD and Intel GPU game launch workaround** _(Windows only)_ + +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. + +**FFmpeg/Video hardware decoding (experimental)** _(All platforms except Raspberry Pi)_ + +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. + +**Upscale video frame rate to 60 FPS (FFmpeg)** + +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.cfg on a per-game basis. 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 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. **Show hidden files and folders (requires restart)** -If this option is disabled, hidden files and folders within the ROM 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 probably mostly useful 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 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)** -You can mark games as hidden in the metadata editor, which is useful for instance for DOS games where you may not want to see some batch files and executables inside ES-DE, or for multi-disk games where you may only want to show the .m3u playlists and not the individual game files, as is discussed [here](USERGUIDE.md#multiple-gamefiles-installation). By disabling this option these files will not be processed at all when ES-dE starts up. If you enable the setting you will see the files, but their name entries will be almost transparent in the gamelist view to visually indicate that they are hidden. +You can mark games as hidden in the metadata editor, which is useful for instance for DOS games where you may not want to see some batch files and executables inside ES-DE, or for multi-disk games where you may only want to show the .m3u playlists and not the individual game files. By disabling this option these files will not be processed at all when ES-DE starts up. If you enable the option you will see the files, but their name entries will be almost transparent in the gamelist view to visually indicate that they are hidden. **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 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. It's recommended to leave it at its default off value unless you need it as it otherwise generates unnecessary debug logging. **Only show ROMs from gamelist.xml files** If enabled, only ROMs that have metadata saved to the gamelist.xml files will be shown in ES-DE. This option is intended primarily for testing and debugging purposes so it should normally not be enabled. -**Display game media from ROM directories** - -Using this option, you can place game images and videos in the ROM directory tree. The media files are searched inside the directory _\/\/images/_ and _\/\/videos/_ and the filenames must match the ROM names, followed by a dash and the media type. For example _~/ROMs/nes/images/Contra-screenshot.jpg, ~/ROMs/nes/images/Contra-marquee.jpg_ and _~/ROMs/nes/videos/Contra-video.jpg_. This option is mostly intended for legacy purposes, if you have an existing game collection with this media setup that you would like to open in ES-DE. The scraper will never save files to this directory structure and will instead use the standard media directory logic. It's recommended to keep this option disabled unless you really need it since it slows down the application somewhat. - **Disable desktop composition (requires restart)** _(Unix only)_ -The window manager desktop composition can adversely affect the framerate of ES-DE, especially on weaker graphic cards and when running in 4K resolution. As such the desktop compositor is disabled by default, although the window manager has to be configured to allow applications to do this for the option to have any effect. Note that this setting can cause problems with some graphic drivers (notably the Nvidia proprietary drivers) so if you see strange flickering and similar after quitting ES-DE, then disable the setting. In case of such issues, make sure that the emulator is also not blocking the composition (e.g. RetroArch has a corresponding option). +The window manager desktop composition can adversely affect the framerate of ES-DE, especially on weaker graphic cards and when running at higher resolution. As such the desktop compositor is disabled by default, although the window manager has to be configured to allow applications to do this for the option to have any effect. Note that this setting can cause problems with some graphic drivers (notably the Nvidia proprietary drivers) so if you see strange flickering and similar after quitting ES-DE, then disable the setting. In case of such issues, make sure that the emulator is also not blocking the composition (e.g. RetroArch has a corresponding option). **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 version 1.0 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.1 the VRAM usage statistics is not accurate. This will be addressed in a future version. **Enable menu in kid mode** -Enabling or disabling the menu when the UI mode is set to Kid. Mostly intended for testing purposes as it's normally not recommended to enable the menu in this restricted mode. +Enabling or disabling the menu when the UI mode is set to Kid. Mostly intended for testing purposes as it's not recommended to enable the menu in this restricted mode. **Show quit menu (reboot and power off entries)** _(Unix and Windows only)_ -With this setting enabled, there is a Quit menu shown as the last entry on the main menu which provides options to quit ES-DE, to reboot the computer or to power off the computer. With this setting disabled, there will simply be an entry shown to quit the application instead of the complete quit menu. +With this setting enabled, there is a Quit menu shown as the last entry on the main menu which provides options to quit ES-DE, to reboot the computer or to power off the computer. With this setting disabled, there will simply be an entry to quit the application instead of the complete quit menu. -### Configure input +### Quit / Quit EmulationStation +The _Quit_ menu or _Quit EmulationStation_ entry as described by the _Show quit menu (reboot and power off entries)_ option above. -This tool allows the configuration of button mappings for known or new input devices, as is explained [here](USERGUIDE.md#input-device-configuration). - -### Quit -The menu where you quit ES-DE, or reboot or power off your computer. This menu can be disabled using an option, and in this case it's replaced with a _Quit EmulationStation_ entry. +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. +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. **Reboot system** _(Unix and Windows only)_ @@ -1127,9 +1242,9 @@ Self explanatory. ## Game options menu -This menu is opened from the gamelist views, 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 platform. -You open the menu using the **Select** 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 Select button again, the menu is closed without applying any changes. +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. ![alt text](images/current/es-de_game_options_menu.png "ES-DE Game Options Menu") _The game options menu as laid out when opening it from within a custom collection, which adds the menu entry to add or remove games from the collection._ @@ -1138,7 +1253,7 @@ Here's a summary of the menu entries: ### Jump to.. -This provides the ability to jump to a certain letter using a quick selector. If the setting to sort favorite games above non-favorites has been selected (it is enabled by default), then it's also possible to jump to the favorites games by choosing the star symbol. If there are only folders or only favorite games in a certain game list, these games and folders will be indexed as well, making it possible to jump betwen them using 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 be disabled in the quick selector. ### Sort games by @@ -1161,14 +1276,14 @@ The secondary sorting is always in ascending filename order. ### Filter gamelist -Choosing this entry opens a separate screen where it's possible to apply a filter to the gamelist. The filter is persistent throughout the program session, or until it's manually reset. The option to reset all filters is also shown on the same screen. +Choosing this entry opens a separate screen where it's possible to apply a filter to the gamelist. The filter is persistent throughout the program session, or until it's manually reset. The option to reset all filters is shown on the same screen. ![alt text](images/current/es-de_gamelist_filters.png "ES-DE Gamelist Filters") _The gamelist filter screen, accessed from the game options menu._ The following filters can be applied: -**Text Filter (Game name)** +**Text Filter (game name)** **Favorites** @@ -1209,7 +1324,7 @@ This opens the metadata editor for the currently selected game file or folder. ## Metadata editor -In the metadata editor, you can modify the metadata for a game, scrape for game info and media files, delete media files and gamelist entries, or delete the entire game. When manually modifying a value, it will change color from gray to blue, and if the scraper has changed a value, it will change to red. When leaving the metadata editor you will be asked whether you want to save any settings done manually or by the scraper. +In the metadata editor, you can modify the metadata, scrape for game info and media files, clear the entry which will delete all metadata and game media files, or delete the entire game which also removes its file on the filesystem. When manually modifying a value, it will change color from gray to blue, and if the scraper has changed a value, it will change to red. When leaving the metadata editor you will be asked whether you want to save any settings done manually or by the scraper. ![alt text](images/current/es-de_metadata_editor.png "ES-DE Metadata Editor") _The metadata editor._ @@ -1224,7 +1339,7 @@ This is the name that will be shown when browsing the gamelist. If no sortname h **Sortname** _(files only)_ -This entry makes it possible to change the sorting of a game without having to change its name. For instance it can be used to sort _Mille Miglia_ as _1000 Miglia_ or _The Punisher_ as _Punisher, The_. Be aware though that the _Jump to..._ quick selector on the game options menu will base its index on the first character of the sortname if it exists for a game, which could be slightly confusing in some instances when quick jumping in the gamelist. +This entry makes it possible to change the sorting of a game without having to change its name. For instance it can be used to sort _Mille Miglia_ as _1000 Miglia_ or _The Punisher_ as _Punisher, The_. Note that the _Jump to..._ quick selector on the game options menu will base its index on the first character of the sortname if it exists for a game, which could be slightly confusing in some instances when quick jumping in the gamelist. **Description** @@ -1252,11 +1367,11 @@ One or multiple genres for the game. **Players** -The amount of players the game supports. +The amount of players the game supports. This could be an absolute number such as 1 or 3, or it could be a range, such as 2-4. **Favorite** -A flag to indicate whether this is a favorite. Can also be set directly from the gamelist view by using the _Y_ button (unless this has been disabled in the main menu settings). +A flag to indicate whether this is a favorite game. This flag can also be set directly from the gamelist view by using the _Y_ button (assuming the _Enable toggle favorites buttom_ option is enabled). **Completed** @@ -1268,7 +1383,7 @@ A flag to mark whether the game is suitable for children. This will be applied a **Hidden** -A flag to indicate that the game is hidden. If the corresponding option has been set in the main menu, the game will not be shown. Useful for example for DOS games to hide batch scripts and unnecessary binaries or to hide the actual game files for multi-disk games. If a file or folder is flagged as hidden but the correponding option to hide hidden games has not been enabled, then the opacity of the text will be lowered significantly to make it clear that it's a hidden game. +A flag to indicate that the game is hidden. If the corresponding option has been set in the main menu, the game will not be shown. Useful for example for DOS games to hide batch scripts and unnecessary binaries or to hide the actual game files for multi-disk games. If a file or folder is flagged as hidden but the corresponding option to hide hidden games has not been enabled, then the opacity of the text will be lowered significantly to make it clear that it's a hidden entry. **Broken/not working** @@ -1280,7 +1395,7 @@ A flag to indicate whether the game should be excluded from being counted. If th **Exclude from multi-scraper** -Whether to exclude the file from the multi-scraper. This is quite useful in order to avoid scraping all the disks for multi-disk games for example. There is an option in the scraper settings to ignore this flag, but by default the scraper will respect it. Note that the manual single-file scraper will work regardless of whether this flag is set or not. +Whether to exclude the file from the multi-scraper. This is quite useful in order to avoid scraping all the disks for multi-disk games for example. There is an option in the scraper settings to ignore this flag, but by default the multi-scraper will respect it. **Hide metadata fields** @@ -1288,7 +1403,7 @@ This option will hide most metadata fields in the gamelist view. The intention i **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 for the game system. Very useful for MAME/arcade games. +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. **Times played** _(files only)_ @@ -1300,7 +1415,7 @@ For game files, there will be five buttons displayed on the bottom of the metada **Scrape** -Opens the single-game scraper, which is explained [above](USERGUIDE.md#single-game-scraper) in this guide. The _Y_ button can also be used as a shortcut to start the scraper without having to navigate to this button. +Opens the single-game scraper. The _Y_ button can also be used as a shortcut to start the scraper without having to navigate to this button. **Save** @@ -1312,12 +1427,21 @@ Cancels any changes and closes the window. **Clear** -This will remove any media files for the file or folder and also remove its entry from the gamelist.xml file. The actual game file or folder will however _not_ be deleted. A prompt will be shown asking for confirmation. +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)_ 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. +## Game media viewer + +The game media viewer displays videos and images in fullscreen mode and is launched from the gamelist view by pressing the _X_ button. + +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. + +Pressing any other button than _left_ or _right_ closes the media viewer. ## Screensaver @@ -1327,20 +1451,24 @@ 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 **Select** key. In addition to this, for the Slideshow and Video screensavers, the controls will allow you to jump to a new random image or video 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. + +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. ![alt text](images/current/es-de_screensaver.png "ES-DE Screensaver") _An example of what the video screensaver looks like._ ## Game collections -ES-DE provides two types of collections, **Automatic collections** and **Custom collections**, the latter being defined by the user. Collections are as the name implies only collections of games already present in your actual game systems, so they're basically grouping your games together into convenient views. As such the use of collections is entirely optional, but it is a very nice feature and it's worth some effort to setup. +ES-DE provides two types of collections, **Automatic collections** and **Custom collections**, the latter being defined by the user. Collections are as the name implies only collections of games already present in your actual game systems, so they're basically grouping of games into convenient views. As such the use of collections is entirely optional, but especially the custom collection support is a very nice feature which is worth some effort to setup. The numerous collection settings available are covered [here](USERGUIDE.md#game-collection-settings). ### 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**. @@ -1352,7 +1480,7 @@ These are collections that you create yourself. Examples could be grouping in ge 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 quick jump to this 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**. @@ -1362,7 +1490,7 @@ The collection will now be created and the collection edit mode will be entered. 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. As well, games marked as hidden or to not be counted as games can't be added either. +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. @@ -1395,7 +1523,7 @@ The file contents is simply a list of ROM files, such as the following: Any changes to custom collections (for example adding or removing a game) will be immediately written to the corresponding collection configuration file. -Note that 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, even though you copy the files into the collections directory, they will not show up inside the application as you always need to enable the collections from the menu. ES-DE looks inside the es_settings.cfg file during startup to see which collections should be enabled. +If you copy or migrate a collection from a previous version of EmulationStation or if you're setting up ES-DE on a new computer, the collection will not be enabled by just copying its configuration file to the `~/.emulationstation/collections` directory. You always need to explicitly enable each collection via the menu. If you're migrating from a previous version of EmulationStation that has absolute paths in the collection files, these will be rewritten with the %ROMPATH% variable the first time you make a change to the collection. @@ -1406,22 +1534,22 @@ ES-DE is fully themeable, and although the application ships with the comprehens 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. -Note that this Desktop Edition fork adds 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. But effort is spent trying to make ES-DE backwards compatible with the available themes used by other EmulationStation versions. The exception to this are some themes made for the Recalbox and Batocera forks of EmulationStation as they have added a lot of additional theme functionality that ES-DE has no intention to replicate. +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 in your ES-DE home directory, i.e. `~/.emulationstation/themes`. By just adding the theme sets there, one folder each, they will be found by ES-DE during startup and you can then choose between them via UI Settings 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. -Note that 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. +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 folder: +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: ``` ~/.emulationstation/themes/es-theme-carbon ~/.emulationstation/themes/es-theme-fundamental ``` -You would now have three entries for the Theme set selector in the UI settings menu, i.e. rbsimple-DE, es-theme-carbon and 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. Here are some resources where additional theme sets can be downloaded. @@ -1442,49 +1570,49 @@ _An example of a modified version of the [Fundamental](https://github.com/G-rila There are numerous locations throughout ES-DE where custom scripts will be executed if the option to do so has been enabled in the settings. By default it's deactivated so be sure to enable it to use this feature. -The setup for event scripts is a bit technical, so please refer to the [INSTALL.md](INSTALL.md#custom-event-scripts) document to see how it's configured. +The setup for event scripts is a bit technical, so refer to the [INSTALL.md](INSTALL.md#custom-event-scripts) document to see how it's configured. ## 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, please refer to the [INSTALL.md](INSTALL.md#building-on-windows) document 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 retro gaming solution. The setup is somewhat technical, refer to [INSTALL.md](INSTALL.md#portable-installation-on-windows) to see how it's done. -## Command line arguments +## Command line options -Please refer to the [INSTALL.md](INSTALL.md#command-line-arguments) document for a list of the command line arguments per operating system. +Refer to 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.cfg 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 not be themed which looks very ugly. +**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 as well that the list and corresponding es_systems.cfg 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. +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`. -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.cfg 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 modified 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 circumstances 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. +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. -The **Default emulator** column shows the emulator configured in es_systems.cfg, 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 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. -For additional details regarding which game file extensions are supported per system, refer to the es_systems.cfg templates [es_systems.cfg_unix](resources/templates/es_systems.cfg_unix), [es_systems.cfg_macos](resources/templates/es_systems.cfg_macos) and [es_systems.cfg_windows](resources/templates/es_systems.cfg_windows). Normally the extensions setup in these files should cover everything that the emulators support. +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. -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 modify the es_systems.cfg file, or you can use the `mame` system which comes preconfigured for the RetroArch core _MAME 2003-Plus_. There are other alternatives as well such as _MAME 2010_ that uses the 0.139 ROM set but this would require a manual change of the es_systems.cfg file and is generally not recommended. +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. + +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. 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. -Running RetroArch on macOS is a bit problematic as some cores (e.g. the Nintendo 64 emulators) don't exist at all, and some cores are unusable on older macOS versions as the compilation was done without the necessary backwards compatibility support. On macOS you may therefore need to compile some cores yourself. - 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) [no n64 emulator available on macOS?] | | +| 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-disk | | 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-disk | @@ -1495,7 +1623,7 @@ Consider the table below a work in progress as it's obvioulsy not fully populate | 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) | Single archive or ROM file in root folder | +| 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 | | | @@ -1554,7 +1682,7 @@ Consider the table below a work in progress as it's obvioulsy not fully populate | naomi | Sega NAOMI | RetroArch (Flycast) | | | naomigd | Sega NAOMI GD-ROM | RetroArch (Flycast) | | | n3ds | Nintendo 3DS | RetroArch (Citra) | | -| n64 | Nintendo 64 | RetroArch (Mupen64Plus-Next) [no n64 emulator available on macOS?] | Single archive or ROM file in root folder | +| 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) | @@ -1599,6 +1727,7 @@ Consider the table below a work in progress as it's obvioulsy not fully populate | 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) | |