From c0ea3066d3d56457cc804777631858c66e667b03 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Sat, 11 Mar 2023 16:54:52 +0100 Subject: [PATCH] Documentation update for the 2.0.0 release --- CHANGELOG.md | 5 +- INSTALL.md | 568 +++------ README.md | 2 +- ROADMAP.md | 20 +- THEMES.md | 3158 +++++++++++++++++++++++++++++++++++----------- USERGUIDE-DEV.md | 11 +- USERGUIDE.md | 1835 +++++++++++++++------------ 7 files changed, 3612 insertions(+), 1987 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3991bd811..5777cf0bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,9 @@ [[_TOC_]] -## Version 2.0.0 (in development) +## Version 2.0.0 -**Release date:** TBD +**Release date:** 2023-03-11 ### Release overview @@ -60,6 +60,7 @@ Overall application speed and performance has been greatly improved with faster * Added support for the Microsoft Windows (windows) game system * Added support for the Nintendo Wii U (wiiu) game system on Linux and macOS by adding the Cemu standalone emulator * Added support for the Infocom Z-machine (zmachine) game system by adding the Gargoyle standalone emulator +* Added support for the Ava release of Ryujinx for the switch system on Linux and Windows * (macOS) Added support for the Nintendo Switch (switch) game system by adding the Ryujinx standalone emulator * Added ares standalone as an alternative emulator for many systems * Added MAME standalone as the default emulator for the macintosh system (Mac SE and Mac Plus diskette images) diff --git a/INSTALL.md b/INSTALL.md index 74a115b7a..02a20a7a3 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,12 +1,10 @@ -# EmulationStation Desktop Edition (ES-DE) v1.2 - Building and advanced configuration - -**Note:** This is a quite technical document intended for those that are interested in compiling ES-DE from source code, or would like to customize the configuration. If you just want to start using the software, check out [USERGUIDE.md](USERGUIDE.md) instead. +# EmulationStation Desktop Edition (ES-DE) v2.0 - Building and advanced configuration Table of contents: [[_TOC_]] -## Development Environment +## Development environment ES-DE is developed and compiled using Clang/LLVM and GCC on Unix, Clang/LLVM on macOS and MSVC and GCC (MinGW) on Windows. @@ -27,11 +25,6 @@ All of the required packages can be installed with apt-get: sudo apt-get install build-essential clang-format git cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev libasound2-dev libgl1-mesa-dev ``` -If building with the optional VLC video player, the following packages are also needed: -``` -sudo apt-get install vlc libvlc-dev -``` - **Fedora** On Fedora you first need to install the RPM Fusion repository: @@ -44,13 +37,7 @@ https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm - Then you can use dnf to install all the required packages: ``` -sudo dnf install gcc-c++ clang-tools-extra cmake rpm-build SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel -``` -If building with the optional VLC video player, the following packages are also needed: - - -``` -sudo dnf install vlc vlc-devel +sudo dnf install gcc-c++ clang-tools-extra cmake libasan rpm-build SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel ``` **Manjaro** @@ -61,11 +48,6 @@ Use pacman to install all the required packages: sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml ``` -If building with the optional VLC video player, the following package is also needed: -``` -sudo pacman -S vlc -``` - **Raspberry Pi OS (Raspian)** All of the required packages can be installed with apt-get: @@ -73,11 +55,6 @@ 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 ``` -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 @@ -85,7 +62,9 @@ sudo apt-get install libcec-dev libp8-platform-dev The Raspberry Pi 4/400 is the minimum recommended version and earlier boards have not been tested. The GPU memory should be set to at least 256 MB using `raspi-config` and the GL driver must be set to `GL (Fake KMS)` or the performance will be horrible. -Note that low-level ALSA sound support has been removed from ES-DE which means that a sound server like PulseAudio or PipeWire is required. +Note that low-level ALSA sound support has been removed from ES-DE which means that a sound server like PulseAudio or PipeWire is required. Likewise a display server (Xorg or Wayland) is required, direct framebuffer access is not supported. + +Only the OpenGL ES 3.0 renderer works on Raspberry Pi and it's enabled by default. **FreeBSD** @@ -94,11 +73,6 @@ Use pkg to install the dependencies: pkg install llvm-devel git pkgconf cmake sdl2 ffmpeg freeimage pugixml ``` -If building with the optional VLC video player, the following package is also needed: -``` -pkg install vlc -``` - Clang/LLVM and curl should already be included in the base OS installation. **NetBSD** @@ -108,11 +82,6 @@ Use pkgin to install the dependencies: pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage pugixml ``` -If building with the optional VLC video player, the following package is also needed: -``` -pkgin vlc -``` - 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** @@ -122,11 +91,6 @@ Use pkg_add to install the dependencies: 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. Pugixml does exist in the package collection but somehow this version is not properly detected by CMake, so you need to compile this manually as well: @@ -156,6 +120,14 @@ cmake . make ``` +By default the application updater will be built which checks for new releases on startup, to disable this functionality run the following: +``` +cmake -DAPPLICATION_UPDATER=off . +make +``` + +Note that the application updater is always disabled when building for the AUR, RetroDECK, Raspberry Pi or BSD Unix. + 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: ``` @@ -165,12 +137,6 @@ cmake . make ``` -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 . @@ -189,13 +155,24 @@ To enable AddressSanitizer which helps with identifying memory issues like corru cmake -DCMAKE_BUILD_TYPE=Debug -DASAN=on . make ``` +Due to buggy AMD GPU drivers it could be a good idea to use the `LSAN_suppressions` file included in the repository to avoid reports of a lot of irrelevant issue, for example: +``` +LSAN_OPTIONS="suppressions=tools/LSAN_suppressions" ./emulationstation --debug --resolution 2560 1440 +``` -To enable ThreadSanitizer which helps with identifying data races for multi-threaded code, build with the TSAN option: +This applies to LeakSanitizer specifically, which is integrated into AddressSanitizer. + +To enable ThreadSanitizer which helps with identifying data races and other thread-related issues, build with the TSAN option: ``` cmake -DCMAKE_BUILD_TYPE=Debug -DTSAN=on . make ``` +It could also be a good idea to use the `TSAN_suppressions` file included in the repository to suppress issues reported by some third party libraries, for example: +``` +TSAN_OPTIONS="suppressions=tools/TSAN_suppressions" ./emulationstation --debug --resolution 2560 1440 +``` + To enable UndefinedBehaviorSanitizer which helps with identifying bugs that may otherwise be hard to find, build with the UBSAN option: ``` cmake -DCMAKE_BUILD_TYPE=Debug -UBSAN=on . @@ -269,12 +246,13 @@ make ``` 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: +To build with the GLES 3.0 renderer, run the following: ``` cmake -DGLES=on . make ``` -The GLES renderer is quite limited as there is no shader support for it, so ES-DE will definitely not look as pretty as when using the default OpenGL renderer. This option is basically deprecated as the releases for all supported platforms are built using the desktop OpenGL renderer (including the Raspberry Pi). + +This renderer is generally only needed on the Raspberry Pi and the desktop OpenGL renderer should otherwise be used. 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: @@ -296,28 +274,7 @@ On Linux, if you're not building a package and instead intend to install using ` **Compilers** -Both Clang/LLVM and GCC work fine for building ES-DE. - -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): -* 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 - -*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 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%. - -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: +Both Clang/LLVM and GCC work fine for building ES-DE, and on Ubuntu it's easy to switch between the two using `update-alternatives`: ``` myusername@computer:~$ sudo update-alternatives --config c++ @@ -494,12 +451,6 @@ Install the required tools: brew install clang-format cmake pkg-config nasm yasm ``` -If building with the optional VLC video player, then run this as well: - -``` -brew install --cask vlc -``` - **Developer mode** Enable developer mode to avoid annoying password requests when attaching the debugger to a process: @@ -515,7 +466,7 @@ To clone the source repository, run the following: git clone https://gitlab.com/es-de/emulationstation-de.git ``` -For macOS all dependencies are built in-tree in the `external` directory tree. There are two scripts in the tools directory that automate this entirely and they are executed such as this: +On macOS all dependencies are built in-tree in the `external` directory tree. There are two scripts in the tools directory that automate this entirely and they are executed such as this: ``` cd emulationstation-de @@ -555,12 +506,6 @@ cmake . make ``` -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 . @@ -600,11 +545,6 @@ export ASAN_OPTIONS=detect_container_overflow=0 Running `make -j6` (or whatever number of parallel jobs you prefer) speeds up the compilation time if you have cores to spare. -After building ES-DE and trying to execute the application, there could be issues with finding the dynamic link libraries for VLC (assuming VLC was enabled for the build) as these are not installed into a standard location but rather into the /Applications folder. As such, you may need to set the DYLD_LIBRARY_PATH environment 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 -``` - 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. **Building for the M1 (ARM) processor** @@ -634,40 +574,13 @@ You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the As macOS does not have any package manager which would have handled the library dependencies, we need to bundle the required shared libraries with the application. This is almost completely automated by the build scripts. -The only exceptions are these libraries for the optional VLC video player: -``` -libvlc.dylib -libvlccore.dylib -``` - -If building the VLC video player, copy these files from the /Applications/VLC.app/Contents/MacOS/lib/ directory to the emulationstation-de build folder. - -In addition to these you need to create a `plugins` directory and copy over the following libraries, which are located in /Applications/VLC.app/Contents/MacOS/plugins/: - -``` -libadummy_plugin.dylib -libamem_plugin.dylib -libaudio_format_plugin.dylib -libauhal_plugin.dylib -libavcodec_plugin.dylib -libconsole_logger_plugin.dylib -libfilesystem_plugin.dylib -libfreetype_plugin.dylib -libswscale_plugin.dylib -libtrivial_channel_mixer_plugin.dylib -libvmem_plugin.dylib -libwave_plugin.dylib -libx264_plugin.dylib -libx265_plugin.dylib -``` - -On macOS you can install the application as a normal user, i.e. no root privileges are required. Simply run the following: +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 (the VLC-related files are optional): +This will be the directory structure for the installation: ``` /Applications/EmulationStation Desktop Edition.app/Contents/Info.plist @@ -682,8 +595,6 @@ This will be the directory structure for the installation (the VLC-related files /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpostproc.55.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.3.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.5.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlc.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlccore.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbis.0.4.9.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbisenc.2.0.12.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/plugins/* @@ -730,9 +641,9 @@ CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.2. Both MSVC and MinGW (GCC) work fine for building ES-DE on Windows. -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. +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 DLL files to be distributed with the application and the console window is always displayed on startup for some reason. -For this reason I think MSVC makes sense for development and MinGW for the releases. +For these reasons I think MSVC makes sense for development and MinGW for the releases. **MSVC setup** @@ -788,7 +699,7 @@ Note that most GDB builds for Windows have broken Python support so that pretty **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) +[https://releases.llvm.org](https://releases.llvm.org) Just run the installer and make sure to select the option _Add LLVM to the system PATH for current user_. @@ -800,90 +711,9 @@ It's strongly recommended to set line breaks to Unix-style (line feed only) dire In the descriptions below it's assumed that all build steps for MinGW/GCC will be done in the Git Bash shell, and all the build steps for MSVC will be done in the MSVC developer console (x64 Native Tools Command Prompt for VS). +**Cloning and setting up dependencies** -**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, 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) - 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` - -Append `_src` or something appropriate to the VLC source distribution directory as it has the same name as the binary distribution. - -GLEW\ -[http://glew.sourceforge.net](http://glew.sourceforge.net) - -If using MinGW, this library needs to be compiled from source as the pre-built libraries don't seem to work with GCC. The GitHub repo seems to be somewhat broken as well, therefore the manual download is required. It's recommended to get the source in zip format and uncompress it to the same directory as the other libraries listed above. - -Then simply build the required glew32.dll library: - -``` -unzip glew-2.1.0.zip -cd glew-2.1.0 -make -``` -You will probably see a huge amount of compiler warnings, and the glewinfo.exe tool may fail to build, but we don't need it so it's not an issue. - -If using MSVC, simply download the binary distribution of GLEW. - -The following packages are not readily available for Windows, so clone the repos and build them yourself: - -[FreeType](https://www.freetype.org) -``` -git clone git://git.savannah.gnu.org/freetype/freetype2.git -cd freetype2 -git checkout VER-2-10-4 -mkdir build -cd build -``` - -MSVC: -``` -cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON .. -nmake -``` - -MinGW: -``` -cmake -G "MinGW Makefiles" -DBUILD_SHARED_LIBS=ON .. -make -``` - -[pugixml](https://pugixml.org) -``` -git clone https://github.com/zeux/pugixml.git -cd pugixml -git checkout v1.10 -``` - -MSVC: - -``` -cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON . -nmake -``` - -MinGW: -``` -cmake -G "MinGW Makefiles" -DBUILD_SHARED_LIBS=ON . -make -``` - -**Clone the ES-DE repository** - -This works the same as on Unix or macOS, just run the following: +To clone the source repository, run the following: ``` git clone https://gitlab.com/es-de/emulationstation-de.git @@ -896,222 +726,80 @@ cd emulationstation-de git checkout stable-1.2 ``` -**Setup the include directories** - -As there is no standardized include directory structure in Windows, you need to provide the include files manually. - -Make a directory in your build environment tree, for instance under `C:\Programming\include` - -Copy the include files for curl, FFmpeg, FreeImage, FreeType, GLEW, pugixml, SDL2 and optionally VLC to this directory. - -You may need to create the SDL2 directory manually and copy the header files there. - -For FFmpeg, copy the directories libavcodec, libavfilter, libavformat and libavutil. - -It should look something like this: +On Windows all dependencies are kept in-tree in the `external` directory tree. Most of the libraries can be downloaded in binary form, but a few need to be built from source code. There are four scripts in the tools directory that automate this entirely. Two of them are used for the MSVC compiler and the other two for MinGW. +For MSVC, you run them like this: ``` -$ ls -1 include/ -curl/ -FreeImage.h -freetype/ -ft2build.h -GL/ -libavcodec/ -libavfilter/ -libavformat/ -libavutil/ -pugiconfig.hpp -pugixml.hpp -SDL2/ -vlc/ (only if building with the VLC video player) +cd emulationstation-de +tools\Windows_dependencies_setup_MSVC.bat +tools\Windows_dependencies_build_MSVC.bat ``` -**Copy the required library files to the ES-DE build directory** - -As there's no package manager in Windows and no way to handle dependencies, we need to ship all the required shared libraries with the application. - -Copy the files to the `emulationstation-de` build directory. Most of them will come from the packages that were provided in the previous steps of this guide. - -**Required files for MSVC:** +And for MinGW like the following: ``` -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 -freetype.lib -glew32.dll -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 (only if building with the VLC video player) -libvlccore.dll (only if building with the VLC video player) -pugixml.dll -pugixml.lib -SDL2.dll -SDL2.lib -SDL2main.lib -MSVCP140.dll (from Windows\System32) -VCOMP140.DLL (from Windows\System32) -VCRUNTIME140.dll (from Windows\System32) -VCRUNTIME140_1.dll (from Windows\System32) +cd emulationstation-de +tools/Windows_dependencies_setup_MinGW.sh +tools/Windows_dependencies_build_MinGW.sh ``` -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. +Re-running the setup script will delete and download all dependencies again, and re-running the build script will clean and rebuild from scratch. You can of course also manually recompile an individual library if needed. -libcurl-x64.lib: -``` -dumpbin /exports libcurl-x64.dll > exports.txt -echo LIBRARY libcurl-x64 > libcurl-x64.def -echo EXPORTS >> libcurl-x64.def -for /f "skip=19 tokens=4" %A in (exports.txt) do echo %A >> libcurl-x64.def -lib /def:libcurl-x64.def /out:libcurl-x64.lib /machine:x64 -``` +The setup scripts for both MSVC and MinGW will download and launch an installer for OpenSSL for Windows if this has not already been installed on the build machine. Just run through the installer using the default settings and everything should work fine. -libvlc.lib: -``` -dumpbin /exports libvlc.dll > exports.txt -echo LIBRARY libvlc > libvlc.def -echo EXPORTS >> libvlc.def -for /f "skip=19 tokens=4" %A in (exports.txt) do echo %A >> libvlc.def -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) -libcurl-x64.dll -libfreetype.dll -libpugixml.dll -libSDL2main.a -libssl-1_1-x64.dll (from the OpenSSL package, located in Git MinGW under \mingw64\bin) -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) -``` - -**Additional files for both MSVC and MinGW if building with the VLC video player** - -In addition to the files above, you need to copy some libraries from the VLC `plugins` folder. This contains a subdirectory structure but there is no requirement to retain this as libVLC apparently looks recursively for the .dll files. - -The following libraries seem to be required to play most video and audio formats: - -``` -access\libfilesystem_plugin.dll -audio_filter\libaudio_format_plugin.dll -audio_filter\libtrivial_channel_mixer_plugin.dll -audio_output\libadummy_plugin.dll -audio_output\libamem_plugin.dll -audio_output\libdirectsound_plugin.dll -audio_output\libmmdevice_plugin.dll -audio_output\libwasapi_plugin.dll -audio_output\libwaveout_plugin.dll -codec\libavcodec_plugin.dll -codec\libx264_plugin.dll -codec\libx265_plugin.dll -logger\libconsole_logger_plugin.dll -video_chroma\libswscale_plugin.dll -video_output\libvmem_plugin.dll -``` - -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. +Following these preparations, ES-DE should be ready to be compiled. **Building ES-DE using MSVC** -There is a bug in libVLC when building using MSVC, so three lines need to be commented out from `libvlc_media.h`. The compiler error messages will provide you with the line numbers, but they involve the callback `libvlc_media_read_cb`. - -After doing this, ES-DE should build correctly. - For a release build: ``` -cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DWIN32_INCLUDE_DIR=../include . +cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release . nmake ``` Or for a debug build: ``` -cmake -G "NMake Makefiles" -DWIN32_INCLUDE_DIR=../include . +cmake -G "NMake Makefiles" . 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. + To enable AddressSanitizer which helps with identifying memory issues like corruption bugs and buffer overflows, build with the ASAN option: ``` -cmake -G "NMake Makefiles" -DWIN32_INCLUDE_DIR=../include -DASAN=on . +cmake -G "NMake Makefiles" -DASAN=on . nmake ``` ThreadSanitizer and UndefinedBehaviorSanitizer aren't available for the MSVC compiler. -For some annoying reason MSVC is the only compiler that creates a debug build by default and where you need to explicitly set the build type to Release. +There are a number of compiler warnings for the bundled rlottie library when building with MSVC. Unfortunately these need to be resolved upstream, but everything should still work fine so the warnings can be ignored for now. 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 . -nmake -``` - **Building ES-DE using MinGW** For a release build: ``` -cmake -G "MinGW Makefiles" -DWIN32_INCLUDE_DIR=../include . +cmake -G "MinGW Makefiles" . make ``` Or for a debug build: ``` -cmake -G "MinGW Makefiles" -DWIN32_INCLUDE_DIR=../include -DCMAKE_BUILD_TYPE=Debug . +cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug . make ``` Unfortunately AddressSanitizer, ThreadSanitizer and UndefinedBehaviorSanitizer do not seem to be supported with MinGW. -For some reason defining the `../include` path doesn't work when running CMake from PowerShell (and no, changing to backslash doesn't help). Instead use Bash, by running from a Git Bash shell. - -The make command works fine directly in PowerShell though so it can be run from the VSCode terminal. - -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 compared to Linux). The debug binary is also much larger than on Unix. +Note that compilation time is much longer than on Unix or macOS, and linking is incredibly slow for a debug build (around 10 times longer compared to Linux). The debug binary is also much larger than on Unix. **TLS/SSL certificates** @@ -1163,7 +851,6 @@ A theme is not mandatory to start the application, but ES-DE will be basically u As indicated above, the home directory will always take precedence and any resources or themes located there will override the ones in the path of the ES-DE executable. - ## Using clang-format for automatic code formatting The entire ES-DE codebase is formatted using clang-format and all new code must be formatted using this tool before being committed. @@ -1178,8 +865,12 @@ To format a file from the command line, simply run: The -i flag will make an inplace edit of the file. +Alternatively the `tools/reformat_codebase.sh` script can be executed to format the entire codebase in one go. + 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. +Whatever you do, don't set up your editor to run clang-format on commit because if something goes wrong (which has happened in the past) you will potentially commit a lot of garbage which could take some effort to clean up. Adding to this, string literals can get strange formatting from time to time and there are occasionally clang-format bugs that may cause other problems. So always review the formatted code manually before commit. + 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++ @@ -1298,7 +989,6 @@ 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 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_settings.xml** @@ -1343,42 +1033,52 @@ But if you have customized your button layout and your controller or keyboard st The input configuration is described in the [User guide](USERGUIDE.md#input-device-configuration). - ## Command line options You can use **--help** or **-h** to view the list of command line options, as shown here. ``` ---display [index 1-4] Display/monitor to use ---resolution [width] [height] Application resolution ---vsync [1/on or 0/off] Turn VSync on or off (default is on) ---max-vram [size] Max VRAM to use (in mebibytes) before swapping ---no-splash Don't show the splash screen during startup ---gamelist-only Skip automatic game ROM search, only read from gamelist.xml ---ignore-gamelist Ignore the gamelist files (useful for troubleshooting) ---show-hidden-files Show hidden files and folders ---show-hidden-games Show hidden games ---force-full Force the UI mode to Full ---force-kiosk Force the UI mode to Kiosk ---force-kid Force the UI mode to Kid ---force-input-config Force configuration of input device ---create-system-dirs Create game system directories ---home [path] Directory to use as home path ---debug Print debug information ---version, -v Display version information ---help, -h Summon a sentient, angry tuba +--display [1 to 4] Display/monitor to use +--resolution [width] [height] Application resolution +--screenoffset [horiz.] [vert.] Offset screen contents within application window +--screenrotate [0, 90, 180 or 270] Rotate screen contents within application window +--fullscreen-padding [1/on or 0/off] Padding if --resolution is lower than display resolution +--vsync [1/on or 0/off] Turn VSync on or off (default is on) +--max-vram [size] Max VRAM to use (in mebibytes) before swapping +--anti-aliasing [0, 2 or 4] Set MSAA anti-aliasing to disabled, 2x or 4x +--no-splash Don't show the splash screen during startup +--no-update-check Don't check for application updates during startup +--gamelist-only Skip automatic game ROM search, only read from gamelist.xml +--ignore-gamelist Ignore the gamelist.xml files +--show-hidden-files Show hidden files and folders +--show-hidden-games Show hidden games +--force-full Force the UI mode to Full +--force-kiosk Force the UI mode to Kiosk +--force-kid Force the UI mode to Kid +--force-input-config Force configuration of input devices +--create-system-dirs Create game system directories +--home [path] Directory to use as home path +--debug Print debug information +--version, -v Display version information +--help, -h Summon a sentient, angry tuba ``` +_The --anti-aliasing option is not available if ES-DE is built using the OpenGL ES renderer and the --no-update-check option is not available for builds where the application updater is disabled._ + As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `emulationstation --home ~/games/emulation`, ES-DE will use `~/games/emulation/.emulationstation` as its application home directory. Be aware that this option completely replaces what is considered the home directory, meaning the default ROM directory ~/ROMs would be resolved to ~/games/emulation/ROMs. The same is true for the emulator core locations if es_find_rules.xml is configured to look for them relative to the home directory. So of course RetroArch and other emulators would also need to be configured to use ~/games/emulation as its base directory in this instance. -Setting the resolution to a lower or higher value than the display resolution will add a border to the application window. +Setting --resolution to a lower or higher value than the display resolution will add a border to the application window. The exception is if defining a lower resolution than the display resolution in combination with the --fullscreen-padding flag as this will pad the screen contents on a black background. This can be combined with the --screenoffset option for exact positioning on displays where bezels or similar may obstruct part of the viewable area. + +The --no-update-check option only disabled the application updater for the current startup. To permanently disable this functionality use the _Check for application updates_ option in the _Other settings_ menu. The command line option is primarily intended for the unlikely event that the application updater breaks the application and makes it impossible to start. Running with the --create-system-dirs option will generate all the game system directories in the ROMs folder. This is equivalent to starting ES-DE with no game ROMs present and pressing the _Create directories_ button. Detailed output for the directory creation will be available in es_log.txt and the application will quit immediately after the directories have been created. For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter: ``` --display +--screenrotate --max-vram +--anti-aliasing --gamelist-only --show-hidden-files --show-hidden-games @@ -1388,6 +1088,50 @@ As well, passing the option --ignore-gamelist will disable the ParseGamelistOnly The --ignore-gamelist option is only active during the program session and is not saved to es_settings.xml. But --gamelist-only is however saved, so in order to return to the normal operation of parsing the gamelist.xml files after starting ES-DE with the --gamelist-only option, you will need to disable the setting _Only show ROMs from gamelist.xml files_ in the _Other settings_ menu (or manually change the ParseGamelistOnly entry in es_settings.xml). +## Settings not configurable via the GUI + +There are some settings which are not configurable via the GUI as modifying these should normally not be required. To still change these, edit the es_settings.xml file directly. + +**DebugSkipInputLogging** + +Enabling this will skip all input event logging (button and key presses). Default value is false. + +**DebugSkipMissingThemeFiles** + +Enabling this will skip all debug messages about missing files when loading a theme set. Default value is false. + +**DebugSkipMissingThemeFilesCustomCollections** + +Enabling this will skip all debug messages about missing files specifically for custom collections when loading a theme set. Note that DebugSkipMissingThemeFiles takes precedence, so if that setting is set to true then the DebugSkipMissingThemeFilesCustomCollections setting will be ignored. Default value is true. + +**LegacyGamelistFileLocation** + +As of ES-DE 2.0.0 any gamelist.xml files stored in the game system directories (e.g. under `~/ROMs/`) will not get loaded, they are instead required to be placed in the `~/.emulationstation/gamelists/` directory tree. By setting this option to `true` it's however possible to retain the old behavior of first looking for gamelist.xml files in the system directories on startup. Note that even if this setting is enabled ES-DE will still always create new gamelist.xml files under `~/.emulationstation/gamelists/` which was the case also for the 1.x.x releases. + +**LottieMaxFileCache** + +Sets the maximum per-file animation cache for Lottie animations. Minimum value is 0 MiB and maximum value is 1024 MiB. Default value is 150 MiB. + +**LottieMaxTotalCache** + +Sets the maximum total animation cache for Lottie animations. Minimum value is 0 MiB and maximum value is 4096 MiB. Default value is 1024 MiB. + +**OpenGLVersion** + +If using the regular desktop OpenGL renderer, the allowed values are 3.3 (default on all builds except the Steam Deck), 4.2 and 4.6 (default on the Steam Deck). If using the OpenGL ES renderer, the allowed values are 3.0 (default), 3.1 and 3.2. + +**ScraperConnectionTimeout** + +Sets the server connection timeout for the scraper. Minimum value is 0 seconds (infinity) and maximum value is 300 seconds. Default value is 30 seconds. + +**ScraperTransferTimeout** + +Sets the transfer timeout per HTTPS request. Minimum value is 0 seconds (infinity) and maximum value is 300 seconds. Default value is 120 seconds. + +**UIMode_passkey** + +The passkey to use to change from the _Kiosk_ or _Kid_ UI modes to the _Full_ UI mode. + ## es_systems.xml The es_systems.xml file contains the game systems configuration data for ES-DE, written in XML format. This defines the system name, the full system name, the ROM path, the allowed file extensions, the launch command, the platform (for scraping) and the theme to use. @@ -1400,6 +1144,8 @@ This custom file functionality is designed to be complementary to the bundled es 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. +If you're using the AppImage release of ES-DE then the bundled es_systems.xml file is embedded in the AppImage together with the rest of the resources. + It doesn't matter in which order you define the systems as they will be sorted by the `` tag or by the optional `` tag when displayed inside the application. But it's still a good idea to add the systems in alphabetical order to make the configuration file easier to maintain. Note that the `` tags are sorted in [lexicographic order](https://en.wikipedia.org/wiki/Lexicographic_order) so 11 will be sorted above 2 but 002 will be sorted above 011. @@ -1414,6 +1160,8 @@ Wildcards are supported for emulator binaries, but not for directories: ~/App*/yuzu*.AppImage %ROM% ``` +There is a special case when it comes to file extensions where it's possible to use extensionless files if required. To accomplish this simply add a dot (.) to the list of extensions in the `` tag. Obviously this makes it impossible to use the _directories interpreted as files_ functionality as there is no file extension, but apart from that everything should work the same as for regular files. + 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. @@ -1444,8 +1192,8 @@ Below is an overview of the file layout with various examples. For the command t All subdirectories (and non-recursive links) will be included. --> %ROMPATH%/snes - + .smc .SMC .sfc .SFC .swc .SWC .fig .FIG .bs .BS .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP + but for this example they're added. --> "C:\My Games\RetroArch\retroarch.exe" -L "%EMUPATH%\cores\snes9x_libretro.dll" %ROM% + + 0.49 0.8 + 0.4 0.28 + 35 + + + +``` +Whether this is a good idea is another question, it would probably be better to set the name attribute for the image to _systemLogo_ or similar for this example. -*Properties* control how a particular *element* looks - for example its position, size, image path etc. The type of the property determines what kinds of values you can use. You can read about the types below in the "Reference" section. Properties are defined like this: +In addition to this, if the name is used for the same element type but for different views, then there will also not be any collision: ```xml -ValueHere + + + + 0.04 0.73 + 0.5 0.5 + 0.12 0.22 + 40 + + + + + 0.27 0.32 + 0.5 0.5 + 0.12 0.41 + 40 + + ``` +## Debugging during theme development -## Advanced features +If you are writing a theme it's recommended to launch ES-DE with the `--debug` flag from a terminal window. You can also pass the `--resolution` flag to avoid having the application window fill the entire screen. By doing so, you can read error messages directly in the terminal window without having to open the es_log.txt file. You can also reload the current gamelist or system view with `Ctrl+r` if the `--debug` flag has been set. There is also support for highlighting the size and position of each image and animation element by using the `Ctrl+i` key combination and likewise to highlight each text element by using the `Ctrl+t` keys. Again, both of these require that ES-DE has been launched with the `--debug` command line option, for example: +``` +emulationstation --debug --resolution 1280 720 +``` -If you are writing a theme it's recommended to launch ES-DE with the `--debug` flag from a terminal window. You can also pass the `--resolution` flag to avoid having the application window fill the entire screen. By doing so, you can read error messages directly in the terminal window without having to open the log file. You can also reload the current gamelist view and system view with `Ctrl-R` if the `--debug` flag has been set. +Enforcement of a correct theme configuration is quite strict, and most errors will abort the theme loading, leading to an unthemed system. In each such situation the log output will be very clear of what happened, for instance: +``` +Jan 28 17:17:30 Error: ThemeData::parseElement(): "/home/myusername/.emulationstation/themes/mythemeset-es-de/theme.xml": Property "origin" for element "image" has no value defined (system "collections", theme "custom-collections") +``` -### The \ tag +Note that an unthemed system means precisely that, the specific system where the error occured will be unthemed but not necessarily the entire theme set. The latter can still happen if the error is global such as a missing variable used by all XML files or an error in a file included by all XML files. The approach is to only untheme relevant sections of the theme set to be able to pinpoint precisely where the problem lies. + +Sanitization for valid data format and structure is done in this manner, but verification that property values are actually correct (or reasonable) is handled by the individual component that takes care of creating and rendering the specific theme element. What happens in many instances is that a warning log entry is created and the invalid property is reset to its default value. So for these situations, the system will not become unthemed. Here's an example where a badges element accidentally had its horizontalAlignment property set to _leftr_ instead of _left_: +``` +Jan 28 17:25:27 Warn: BadgeComponent: Invalid theme configuration, property "horizontalAlignment" for element "gamelistBadges" defined as "leftr" +``` + +Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the [Reference](THEMES.md#reference) section of this document for valid values for each property. + +For more serious issues where it does not make sense to assign a default value or auto-adjust the configuration, an error log entry is generated and the element will in most instances not get rendered at all. Here's such an example where the imageType property for a video element was accidentally set to _covr_ instead of _cover_: + +``` +Jan 28 17:29:11 Error: VideoComponent: Invalid theme configuration, property "imageType" for element "gamelistVideo" defined as "covr" +``` + +Error handling for missing files is handled a bit differently depending on whether the paths have been defined explicitly or via a variable. For explicitly defined paths a warning will be logged for element properties and an error will be triggered for include files. Here's an example of the latter case: + +``` +Jan 28 17:32:29 Error: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mythemeset-es-de/theme.xml" -> "./colors_dark.xml" not found (resolved to "/home/myusername/.emulationstation/themes/mythemeset-es-de/colors_dark.xml") +``` + +However, if a variable has been used to define the include file, only a debug message will be generated if the file is not found: +``` +Jan 28 17:34:03 Debug: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mythemeset-es-de/theme.xml": Couldn't find file "./${system.theme}/colors.xml" which resolves to "/home/myusername/.emulationstation/themes/mythemeset-es-de/amiga/colors.xml" +``` + +It works essentially the same way for element path properties as for include files. This distinction between explicit values and variables makes it possible to create a theme configuration where both include files and files for fonts, images, videos etc. will be used if found, and if not found a fallback configuration can still be applied so the system will be themed. + +By default all debug messages regarding missing files will be logged for regular systems and automatic collections and suppressed for custom collections. This behavior can be changed by modifying the _DebugSkipMissingThemeFiles_ and _DebugSkipMissingThemeFilesCustomCollections_ settings in es_settings.xml. You can read more about those settings [here](INSTALL.md#settings-not-configurable-via-the-gui). + +## Variants + +A core concept of ES-DE is the use of theme set _variants_ to provide different theme profiles. These are not fixed presets and a theme author can instead name and define whatever variants he wants for his theme (or possibly use no variants at all as they are optional). + +The variants could be purely cosmetic, such as providing different designs for a theme set, or they could provide distinctive functionality by for instance using different primary elements like a carousel or a text list. + +Before a variant can be used it needs to be declared, which is done in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detail later in this document. + +The use of variants is straightforward, a section of the configuration that should be included for a certain variant is enclosed inside the `` tag pair. This has to be placed inside the `` tag pair, and it can only be used at this level of the hierarchy and not inside a `` tag pair for example. + +The mandatory _name_ attribute is used to specificy which variants to use, and multiple variants can be specified at the same time by separating them by commas or by whitespace characters (tabs, spaces or line breaks). It's also possible to use the special _all_ variant that will apply the configuration to all defined variants (although this is only a convenient shortcut and you can explicitly define every variant individually if you prefer that). Note that _all_ is a reserved name and attempting to use it in the capabilities.xml file will trigger a warning on application startup. + +It could sometimes be a good idea to separate the variant configuration into separate files that are then included from the main theme file as this could improve the structure and readability of the theme set configuration. + +It's also possible to apply only portions of the theme configuration to the variants and keep a common set of elements that are shared between all variants. This is accomplished by simply adding the shared configuration without specifying a variant, as is shown in the first example below for the `infoText01` text element. Just be aware that the variant-specific configuration will always be loaded after the general configuration even if it's located above the general configuration in the XML file. As this is potentially confusing and error-prone it's instead generally recommended to use the special _all_ variant to define common configuration used by all variants in the theme set rather than mixing variants configuration with non-variants configuration. + +Here are some example uses of the `` functionality: + +```xml + + + + ./gamelist_textlist.xml + + + ./gamelist_carousel.xml + + + + + ./${system.theme}/systeminfo.xml + + + + + + ./core/font.ttf + 0.035 + 0.3 0.56 + + + +``` + +```xml + + + + + + + + + + + titlescreen + true + 42 + + + + +``` + +```xml + + + + + + titlescreen + true + 42 + + + + +``` + +## Variant triggers (overrides) + +Variant triggers is an optional feature which can be used to replicate the automatic view style switching functionality of the legacy theme engine. This can be used to automatically override the selected variant based on two triggers, either when there are no game videos found for a system, or if there are no game media files of some specified types found for a system. These two trigger types are named `noVideos` and `noMedia` respectively. + +For the `noMedia` trigger there's an optional `mediaType` tag that can be used to specify precisely which media files should be checked for to determine whether to switch to the override variant. Valid values are `miximage`, `marquee`, `screenshot`, `titlescreen`, `cover`, `backcover`, `3dbox`, `physicalmedia`, `fanart` and `video`. Multiple values can be defined, in which case they are separated by a comma, or by a whitespace character (tab, space or line break). If no value is defined, it will be set to `miximage`. + +The `useVariant` tag specifies which variant to use to override the selected variant. + +You'll probably rarely need to use the `noVideos` trigger as `video` can be defined also when using the `noMedia` trigger. The reason for including both trigger types is that it makes it possible to apply a specific variant only when videos are missing and another variant when no media files at all are present. + +The following example (from the `capabilities.xml` file) defines a `noGameMedia` variant which is used as the override for the `withVideos` variant if no miximages, screenshots, covers and videos are found for any game in a system. For this example the `noGameMedia` variant has been set as non-selectable from the _UI Settings_ menu by defining the `selectable` property as `false`. + +As can be seen here, the overall variant trigger configuration needs to be enclosed within an `override` tag pair. And you can only define a single `override` tag pair per trigger type. + +```xml + + + true + + noMedia + miximage, screenshot, cover, video + noGameMedia + + + + + + false + +``` + +Note that variant triggers will only apply to the gamelist view and not the system view. Also be aware that it will add a potentially noticeable application slowdown as game media files need to be scanned for at various points when using the application, as well as during startup. The impact of the performance penalty depends on multiple factors such as the game collection size, how many games have been scraped, as well as disk I/O and filesystem performance. So only use variant triggers if really necessary for your theme design. As well, specifying many values for the `mediaType` tag will lead to more files potentially being scanned which could introduce further lag and latency. + +As a final note, variant triggers can also be globally disabled by the user via the _Enable theme variant triggers_ option in the _UI Settings menu_. Not everyone may want the variant auto-switching to take place, and if all systems contain scraped media then disabling the functionality will eliminate the performance penalty described above. + +## Color schemes + +Color schemes are essentially a collection of variables that can be selected between from the _UI Settings_ menu. This makes it possible to define different values that will be applied to the overall theme configuration based on this menu selection. Only variables can be used for the color schemes, but since variables can be used for almost everything this makes the functionality very flexible. In most cases you'll probably want to apply different color values to `` properties and similar, but it's also possible to apply different images, animations, fonts etc. per color scheme. + +To understand the basics on how to use variables, make sure to read the _Theme variables_ section elsewhere in this document. + +Before a color scheme can be used it needs to be declared, which is done in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detail later in this document. + +The `` tag pair can be placed directly inside the `` tags, inside the `` tags or inside the `` tags. + +The mandatory name attribute is used to specificy which color scheme to use, and multiple values can be specified at the same time by separating them by commas or by whitespace characters (tabs, spaces or line breaks). + +Note that the use of color schemes for a theme set is entirely optional. + +Here's an example configuration: + +```xml + + + + 404040 + F0F0F0 + + + + + + 707070 + 262626 + + + + + + 74747488 + + + + 0 0 + 1 1 + ./core/images/background.png + true + ${backgroundColor} + + + 0.5 0.6437 + 1 0.056 + ${defaultTextColor} + + + + +``` + +## Aspect ratios + +The aspect ratio support works almost identically to the variants and color schemes with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme set can still decide which of the aspect ratios to support (or none at all in which case the theme aspect ratio is left undefined) but it can't create entirely new aspect ratio entries. + +In the same manner as for the variants and color schemes, the aspect ratios that the theme set provides need to be declared in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detailed later in this document. + +The `` tag pair can be placed directly inside the `` tags or inside the `` tags. + +Once the aspect ratios have been defined, they are applied to the theme configuration like the following examples: + +```xml + + + + ./../layout_narrow.xml + + + ./../layout_wide.xml + + + ./../layout_ultrawide.xml + + + + + ./core/font.ttf + 0.035 + + + +``` + +```xml + + + + + + 0.3 0.56 + + + + + + + + 0.42 0.31 + + + + +``` + +```xml + + + + + + + 0.3 0.56 + + + + + +``` + +```xml + + + + + + 0.3 0.56 + + + + +``` + +## Transitions (animation profiles) + +Using the `capabilities.xml` file it's possible to define granular transition animation profiles. Prior to ES-DE 2.0 there was only a user-selectable option for _Instant_, _Slide_ or _Fade_ animations that was applied globally. It's now possible to select each of these animation types individually for the following transitions: + +* System to system +* System to gamelist +* Gamelist to gamelist +* Gamelist to system +* Startup to system +* Startup to gamelist + +This is a brief overview of the supported animations: + +* Instant - as the name implies, transitions are immediate +* Slide - pans the camera to move between views which may look broken with some elements like textlists and grids when used in the system view +* Fade - fades to black when transitioning between views + + +Here's an example configuration: +```xml + + + true + instant + slide + instant + slide + fade + fade + + + + + true + instant + instant + instant + instant + +``` + +The `name` attribute is mandatory and it must be set to a unique value for each profile. Any string can be used except the three reserved values `builtin-instant`, `builtin-slide` and `builtin-fade`. + +The `selectable` property which is set to `true` by default defines whether the transitions profile can be selected from the _Theme transitions_ entry on the _UI Settings_ menu. The `label` defines the label to show there. If no label value is set then a default _Theme profile_ label will be applied. + +At least one of the six transition types must be defined or the `transitions` entry is not considered valid. Any non-defined types will be set to `instant` with the exception of `startupToSystem` which will be set to the same value as `systemToSystem` and `startupToGamelist` which will be set to the same value as `gamelistToGamelist`. + +The profiles will be listed in the _UI Settings_ menu in the order that they have been defined, and the first profile (regardless of whether it's set as user-selectable or not), will be used if the _Automatic_ entry has been selected, unless a per-variant configuration is defined in the theme configuration. + +In addition to defining custom transition profiles it's possible to suppress the built-in profiles. For example slide transitions will look very broken with some theme designs so in such cases it could make sense to disable this animation type altogether. Suppressing a profile simply means its entry will not show up under _Theme transitions_ in the _UI Settings_ menu, making it impossible to select and use it. + +Here's an example where all the built-in transition profiles have been disabled: + +```xml + + builtin-instant + builtin-slide + builtin-fade + +``` + +Regardless of whether any custom profiles have been created or whether the built-in profiles have been disabled there will always be an `Automatic` entry added to the _Theme transition animations_ menu. If no theme profiles have been defined and all built-in profiles have been suppressed, then the `Automatic` entry will be the only available option. In this case `instant` animations will by applied to all transition types. + +Finally it's possible to apply theme-defined transition profiles on a per-variant basis. This requires that the user has selected the `Automatic` profile from the _Theme transitions_ menu as selecting any other profile will override whatever is defined in the theme configuration. Note that the built-in transition profiles can't be used in this manner, only profiles defined in `capabilities.xml`. + +```xml + + instantAndSlide + + + + instant + +``` + +## capabilities.xml + +Variants, variant triggers, color schemes, aspect ratios and transition animation profiles need to be declared before they can be used inside the actual theme set configuration files and that is done in the `capabilities.xml` file. This file needs to exist in the root of the theme directory, for example: +``` +~/.emulationstation/themes/mythemeset-es-de/capabilities.xml +``` + +This file type was introduced with the new ES-DE theme engine in v2.0 and is an indicator that the theme set is of the new generation instead of being of the legacy type (i.e. a theme set backward compatible with RetroPie EmulationStation). In other words, if the capabilities.xml file is absent, the theme will get loaded as a legacy set. + +The structure of the file is simple, as can be seen in this example: + +```xml + + + My theme set + + 16:9 + 4:3 + 4:3_vertical + + + + + + + + + + + instant + slide + instant + slide + + + + + true + + noMedia + miximage, screenshot, cover, video + noGameMedia + + + + + + true + + noMedia + miximage, screenshot, cover + noGameMedia + + + + + + false + + +``` +The file format is hopefully mostly self-explanatory; this example provides three aspect ratios, two color schemes, one transition animation profile and three variants, one of which is a variant trigger override. The `