Xargon/ES-DE
1
0
Fork 0
mirror of https://github.com/RetroDECK/ES-DE.git synced 2024-11-21 21:55:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation update for the 2.1.0 release

Browse source
This commit is contained in:
Leon Styhre 2023-07-13 17:57:52 +02:00
parent 954492b1f4
commit 52d00745a1
5 changed files with 300 additions and 131 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

173
INSTALL.md
View file

@ -1,4 +1,4 @@
# EmulationStation Desktop Edition (ES-DE) v2.0 - Building and advanced configuration # EmulationStation Desktop Edition (ES-DE) v2.1 - Building and advanced configuration
Table of contents: Table of contents:
@ -23,7 +23,7 @@ There are some dependencies that need to be fulfilled in order to build ES-DE. T
All of the required packages can be installed with apt-get: 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 libgit2-dev libcurl4-openssl-dev libpugixml-dev libasound2-dev libgl1-mesa-dev sudo apt-get install build-essential clang-format git cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libfreetype6-dev libgit2-dev libcurl4-openssl-dev libpugixml-dev libasound2-dev libgl1-mesa-dev libpoppler-cpp-dev
``` ```
**Fedora** **Fedora**
@ -38,7 +38,7 @@ https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -
Then you can use dnf to install all the required packages: Then you can use dnf to install all the required packages:
``` ```
sudo dnf install gcc-c++ clang-tools-extra cmake libasan rpm-build SDL2-devel ffmpeg-devel freeimage-devel freetype-devel libgit2-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel sudo dnf install gcc-c++ clang-tools-extra cmake libasan rpm-build SDL2-devel ffmpeg-devel freeimage-devel freetype-devel libgit2-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel poppler-cpp-devel
``` ```
**Manjaro** **Manjaro**
@ -46,14 +46,14 @@ sudo dnf install gcc-c++ clang-tools-extra cmake libasan rpm-build SDL2-devel ff
Use pacman to install all the required packages: Use pacman to install all the required packages:
``` ```
sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 libgit2 pugixml sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 libgit2 pugixml poppler
``` ```
**Raspberry Pi OS (Raspian)** **Raspberry Pi OS (Raspian)**
All of the required packages can be installed with apt-get: 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 libgit2-dev libcurl4-gnutls-dev libpugixml-dev sudo apt-get install clang-format cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libgit2-dev libcurl4-gnutls-dev libpugixml-dev libpoppler-cpp-dev
``` ```
To build with CEC support you also need to install these packages: To build with CEC support you also need to install these packages:
@ -71,7 +71,7 @@ Only the OpenGL ES 3.0 renderer works on Raspberry Pi and it's enabled by defaul
Use pkg to install the dependencies: Use pkg to install the dependencies:
``` ```
pkg install llvm-devel git pkgconf cmake sdl2 ffmpeg freeimage libgit2 pugixml pkg install llvm-devel git pkgconf cmake sdl2 ffmpeg freeimage libgit2 pugixml poppler
``` ```
Clang/LLVM and curl should already be included in the base OS installation. Clang/LLVM and curl should already be included in the base OS installation.
@ -80,7 +80,7 @@ Clang/LLVM and curl should already be included in the base OS installation.
Use pkgin to install the dependencies: Use pkgin to install the dependencies:
``` ```
pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage libgit2 pugixml pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage libgit2 pugixml poppler-cpp
``` ```
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. 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.
@ -89,7 +89,7 @@ NetBSD ships with GCC by default, and although you should be able to use Clang/L
Use pkg_add to install the dependencies: Use pkg_add to install the dependencies:
``` ```
pkg_add clang-tools-extra cmake pkgconf sdl2 ffmpeg freeimage libgit2 pkg_add clang-tools-extra cmake pkgconf sdl2 ffmpeg freeimage libgit2 poppler
``` ```
In the same manner as for FreeBSD, Clang/LLVM and curl should already be installed by default. In the same manner as for FreeBSD, Clang/LLVM and curl should already be installed by default.
@ -349,19 +349,19 @@ CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPackDeb: - Generating dependency list CPackDeb: - Generating dependency list
CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.2.0-x64.deb generated. CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-2.1.0-x64.deb generated.
``` ```
You may want to check that the dependencies look fine, as they're (mostly) 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.2.0-x64.deb dpkg -I ./emulationstation-de-2.1.0-x64.deb
``` ```
The package can now be installed using a package manager, for example apt: The package can now be installed using a package manager, for example apt:
``` ```
sudo apt install ./emulationstation-de-1.2.0-x64.deb sudo apt install ./emulationstation-de-2.1.0-x64.deb
``` ```
To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example: To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example:
@ -380,7 +380,7 @@ CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPackRPM: Will use GENERATED spec file: /home/myusername/emulationstation-de/_CPack_Packages/Linux/RPM/SPECS/emulationstation-de.spec 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.2.0-x64.rpm generated. CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-2.1.0-x64.rpm generated.
``` ```
On Fedora, you need to install rpmbuild before this command can be run: On Fedora, you need to install rpmbuild before this command can be run:
@ -390,17 +390,17 @@ sudo dnf install rpm-build
After the package generation you can check that the metadata looks fine using the `rpm` command: After the package generation you can check that the metadata looks fine using the `rpm` command:
``` ```
rpm -qi ./emulationstation-de-1.2.0-x64.rpm rpm -qi ./emulationstation-de-2.1.0-x64.rpm
``` ```
To see the automatically generated dependencies, run this: To see the automatically generated dependencies, run this:
``` ```
rpm -q --requires ./emulationstation-de-1.2.0-x64.rpm rpm -q --requires ./emulationstation-de-2.1.0-x64.rpm
``` ```
And of course, you can also install the package: And of course, you can also install the package:
``` ```
sudo dnf install ./emulationstation-de-1.2.0-x64.rpm sudo dnf install ./emulationstation-de-2.1.0-x64.rpm
``` ```
**Creating an AppImage** **Creating an AppImage**
@ -449,7 +449,7 @@ export PATH=/opt/homebrew/bin:$PATH
Install the required tools: Install the required tools:
``` ```
brew install clang-format cmake pkg-config nasm yasm brew install clang-format cmake pkg-config meson nasm yasm
``` ```
**Developer mode** **Developer mode**
@ -548,10 +548,6 @@ Running `make -j6` (or whatever number of parallel jobs you prefer) speeds up th
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.
**Building for the M1 (ARM) processor**
The build steps detailed above should in theory work identically on an M1 processor but possibly some of the dependencies will not build correctly and may need manual patching. Cross-compiling using an Intel processor has been attempted but failed due to multiple issues with dependencies refusing to build.
**Code signing** **Code signing**
Due to the Apple notarization requirement implemented as of macOS 10.14.5 a build with simple code signing is needed for versions up to 10.13 and another build with both code signing and notarization is required for version 10.14 and higher. 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.
@ -561,7 +557,12 @@ macOS code signing is beyond the scope of this document, but the CMake option MA
cmake -DMACOS_CODESIGN_IDENTITY="My Name" . 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. For some reason code signing fails if run via an SSH session, so in order for the cpack command to succeed it needs to run from a terminal window started via the GUI. 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. In order to run cpack from an SSH session you first need to run the following command:
```
security unlock-keychain
```
This is not required if cpack is run from a terminal window started via the desktop interface as the keychain is unlocked as part of the desktop login.
**Legacy build** **Legacy build**
@ -586,19 +587,25 @@ This will be the directory structure for the installation:
``` ```
/Applications/EmulationStation Desktop Edition.app/Contents/Info.plist /Applications/EmulationStation Desktop Edition.app/Contents/Info.plist
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/es-pdf-convert
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavcodec.58.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.0.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavfilter.7.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavcodec.60.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavformat.58.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavfilter.9.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavutil.56.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavformat.60.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfdk-aac.2.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavutil.58.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfontconfig.1.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpostproc.55.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libgit2.1.6.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.3.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libjpeg.62.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.5.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libopenjp2.7.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpoppler-cpp.0.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpoppler.129.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpostproc.57.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.4.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.7.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libtiff.6.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbis.0.4.9.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbis.0.4.9.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbisenc.2.0.12.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbisenc.2.0.12.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/plugins/*
/Applications/EmulationStation Desktop Edition.app/Contents/Resources/EmulationStation-DE.icns /Applications/EmulationStation Desktop Edition.app/Contents/Resources/EmulationStation-DE.icns
/Applications/EmulationStation Desktop Edition.app/Contents/Resources/LICENSE /Applications/EmulationStation Desktop Edition.app/Contents/Resources/LICENSE
/Applications/EmulationStation Desktop Edition.app/Contents/Resources/licenses/* /Applications/EmulationStation Desktop Edition.app/Contents/Resources/licenses/*
@ -635,7 +642,7 @@ CPack: Install projects
CPack: - Run preinstall target for: emulationstation-de CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.2.0-x64.dmg generated. CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-2.1.0-x64.dmg generated.
``` ```
## Building on Windows ## Building on Windows
@ -831,7 +838,7 @@ CPack: Install projects
CPack: - Run preinstall target for: emulationstation-de CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-1.2.0-x64.exe generated. CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-2.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. The default installation directory suggested by the installer is `C:\Program Files\EmulationStation-DE` but this can of course be changed by the user.
@ -1179,6 +1186,8 @@ It doesn't matter in which order you define the systems as they will be sorted b
Note that the `<systemsortname>` 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. Note that the `<systemsortname>` 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.
But instead of changing the sorting directly in the es_systems.xml file it could be a better idea to use the dedicated es_systems_sorting.xml file instead. How to do that is described later in this document.
Wildcards are supported for emulator binaries, but not for directories: Wildcards are supported for emulator binaries, but not for directories:
```xml ```xml
<!-- This is supported, first matching file will be selected --> <!-- This is supported, first matching file will be selected -->
@ -1454,29 +1463,74 @@ Here is yet another example with the addition of the `snes` system where some fi
</systemList> </systemList>
``` ```
## es_systems_sorting.xml
This file makes it possible to apply a custom systems sorting without having to modify the es_systems.xml file directly. It should be placed in the custom_systems directory, e.g. `~/.emulationstation/custom_systems/es_systems_sorting.xml`
The structure of this file is essentially a simplified version of the es_systems.xml file, but with only the `<name>` and `<systemsortname>` tags present per system.
Here's an example where three systems have been sorted by release year instead of the default full system name:
```xml
<?xml version="1.0"?>
<systemList>
<system>
<name>amiga</name>
<systemsortname>1985</systemsortname>
</system>
<system>
<name>c64</name>
<systemsortname>1982</systemsortname>
</system>
<system>
<name>vic20</name>
<systemsortname>1980</systemsortname>
</system>
</systemList>
```
You only need to include systems that you want to customize sorting for, and if there's also a systemsortname tag present in the es_systems.xml file for any system, then the es_systems_sorting.xml entry will take precedence.
Note that the `<systemsortname>` 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.
There are also four complete sorting files bundled with ES-DE, you can find them in the resources/sorting/ directory, or you can access them [here](https://gitlab.com/es-de/emulationstation-de/-/tree/master/resources/sorting).
These files include all systems supported by ES-DE and provide the following sorting options:
* Hardware type, release year
* Manufacturer, hardware type, release year
* Manufacturer, release year
* Release year
## es_find_rules.xml ## es_find_rules.xml
This file makes it possible to define rules for where to search for the emulator binaries and emulator cores. 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. The file is located in the resources directory in the same location as the es_systems.xml file, but a customized copy can be placed in ~/.emulationstation/custom_systems, which will complement the bundled file.
Here's an example es_find_rules.xml file for Unix (this is not the complete file shipped with ES-DE as that would be too large to include here): Here's an example es_find_rules.xml file for Unix (this is not the complete file shipped with ES-DE as that would be too large to include here):
```xml ```xml
<?xml version="1.0"?> <?xml version="1.0"?>
<!-- This is the ES-DE find rules configuration file for Unix --> <!-- This is the ES-DE find rules configuration file for Unix -->
<ruleList> <ruleList>
<emulator name="OS-SHELL">
<!-- Operating system shell -->
<rule type="systempath">
<entry>bash</entry>
<entry>sh</entry>
</rule>
</emulator>
<emulator name="RETROARCH"> <emulator name="RETROARCH">
<rule type="systempath"> <rule type="systempath">
<entry>retroarch</entry> <entry>retroarch</entry>
<entry>org.libretro.RetroArch</entry> <entry>org.libretro.RetroArch</entry>
<entry>RetroArch-Linux-x86_64.AppImage</entry>
</rule> </rule>
<rule type="staticpath"> <rule type="staticpath">
<entry>~/Applications/RetroArch-Linux*.AppImage</entry>
<entry>~/.local/bin/RetroArch-Linux*.AppImage</entry>
<entry>~/bin/RetroArch-Linux*.AppImage</entry>
<entry>/var/lib/flatpak/exports/bin/org.libretro.RetroArch</entry> <entry>/var/lib/flatpak/exports/bin/org.libretro.RetroArch</entry>
<entry>~/.local/share/flatpak/exports/bin/org.libretro.RetroArch</entry> <entry>~/.local/share/flatpak/exports/bin/org.libretro.RetroArch</entry>
<entry>~/Applications/RetroArch-Linux-x86_64.AppImage</entry>
<entry>~/.local/bin/RetroArch-Linux-x86_64.AppImage</entry>
<entry>~/bin/RetroArch-Linux-x86_64.AppImage</entry>
</rule> </rule>
</emulator> </emulator>
<core name="RETROARCH"> <core name="RETROARCH">
@ -1499,7 +1553,7 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
<entry>/usr/pkg/lib/libretro</entry> <entry>/usr/pkg/lib/libretro</entry>
</rule> </rule>
</core> </core>
<emulator name="DOSBOX_STAGING"> <emulator name="DOSBOX-STAGING">
<!-- DOS emulator DOSBox Staging --> <!-- DOS emulator DOSBox Staging -->
<rule type="systempath"> <rule type="systempath">
<entry>dosbox-staging</entry> <entry>dosbox-staging</entry>
@ -1507,6 +1561,7 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
</rule> </rule>
<rule type="staticpath"> <rule type="staticpath">
<entry>/var/lib/flatpak/exports/bin/io.github.dosbox-staging</entry> <entry>/var/lib/flatpak/exports/bin/io.github.dosbox-staging</entry>
<entry>~/.local/share/flatpak/exports/bin/io.github.dosbox-staging</entry>
</rule> </rule>
</emulator> </emulator>
<emulator name="YUZU"> <emulator name="YUZU">
@ -1514,13 +1569,13 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
<rule type="systempath"> <rule type="systempath">
<entry>yuzu</entry> <entry>yuzu</entry>
<entry>org.yuzu_emu.yuzu</entry> <entry>org.yuzu_emu.yuzu</entry>
<entry>yuzu.AppImage</entry>
</rule> </rule>
<rule type="staticpath"> <rule type="staticpath">
<entry>/var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu</entry>
<entry>~/Applications/yuzu*.AppImage</entry> <entry>~/Applications/yuzu*.AppImage</entry>
<entry>~/.local/bin/yuzu*.AppImage</entry> <entry>~/.local/bin/yuzu*.AppImage</entry>
<entry>~/bin/yuzu*.AppImage</entry> <entry>~/bin/yuzu*.AppImage</entry>
<entry>/var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu</entry>
<entry>~/.local/share/flatpak/exports/bin/org.yuzu_emu.yuzu</entry>
</rule> </rule>
</emulator> </emulator>
</ruleList> </ruleList>
@ -1586,6 +1641,13 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
<?xml version="1.0"?> <?xml version="1.0"?>
<!-- This is the ES-DE find rules configuration file for macOS --> <!-- This is the ES-DE find rules configuration file for macOS -->
<ruleList> <ruleList>
<emulator name="OS-SHELL">
<!-- Operating system shell -->
<rule type="systempath">
<entry>zsh</entry>
<entry>bash</entry>
</rule>
</emulator>
<emulator name="RETROARCH"> <emulator name="RETROARCH">
<rule type="staticpath"> <rule type="staticpath">
<entry>/Applications/RetroArch.app/Contents/MacOS/RetroArch</entry> <entry>/Applications/RetroArch.app/Contents/MacOS/RetroArch</entry>
@ -1627,6 +1689,12 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
<?xml version="1.0"?> <?xml version="1.0"?>
<!-- This is the ES-DE find rules configuration file for Windows --> <!-- This is the ES-DE find rules configuration file for Windows -->
<ruleList> <ruleList>
<emulator name="OS-SHELL">
<!-- Operating system shell -->
<rule type="systempath">
<entry>cmd.exe</entry>
</rule>
</emulator>
<emulator name="RETROARCH"> <emulator name="RETROARCH">
<rule type="winregistrypath"> <rule type="winregistrypath">
<!-- Check for an App Paths entry in the Windows Registry --> <!-- Check for an App Paths entry in the Windows Registry -->
@ -1653,10 +1721,8 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
<!-- Portable installation --> <!-- Portable installation -->
<entry>%ESPATH%\Emulators\RetroArch-Win64\retroarch.exe</entry> <entry>%ESPATH%\Emulators\RetroArch-Win64\retroarch.exe</entry>
<entry>%ESPATH%\Emulators\RetroArch\retroarch.exe</entry> <entry>%ESPATH%\Emulators\RetroArch\retroarch.exe</entry>
<entry>%ESPATH%\RetroArch-Win64\retroarch.exe</entry> <entry>%ESPATH%\..\Emulators\RetroArch-Win64\retroarch.exe</entry>
<entry>%ESPATH%\RetroArch\retroarch.exe</entry> <entry>%ESPATH%\..\Emulators\RetroArch\retroarch.exe</entry>
<entry>%ESPATH%\..\RetroArch-Win64\retroarch.exe</entry>
<entry>%ESPATH%\..\RetroArch\retroarch.exe</entry>
</rule> </rule>
</emulator> </emulator>
<core name="RETROARCH"> <core name="RETROARCH">
@ -1666,18 +1732,14 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
</core> </core>
<emulator name="PCSX2"> <emulator name="PCSX2">
<!-- Sony PlayStation 2 emulator PCSX2 --> <!-- Sony PlayStation 2 emulator PCSX2 -->
<rule type="winregistryvalue">
<entry>SOFTWARE\PCSX2\Install_Dir|\pcsx2.exe</entry>
</rule>
<rule type="systempath"> <rule type="systempath">
<entry>pcsx2.exe</entry> <entry>pcsx2-qt.exe</entry>
<entry>pcsx2-qtx64.exe</entry>
<entry>pcsx2-qtx64-avx2.exe</entry>
</rule> </rule>
<rule type="staticpath"> <rule type="staticpath">
<entry>C:\Program Files (x86)\PCSX2\pcsx2.exe</entry> <entry>%ESPATH%\Emulators\PCSX2-Qt\pcsx2-qt*.exe</entry>
<entry>D:\Program Files (x86)\PCSX2\pcsx2.exe</entry> <entry>%ESPATH%\..\Emulators\PCSX2-Qt\pcsx2-qt*.exe</entry>
<entry>%ESPATH%\Emulators\PCSX2\pcsx2.exe</entry>
<entry>%ESPATH%\PCSX2\pcsx2.exe</entry>
<entry>%ESPATH%\..\PCSX2\pcsx2.exe</entry>
</rule> </rule>
</emulator> </emulator>
<emulator name="YUZU"> <emulator name="YUZU">
@ -1688,8 +1750,7 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
<rule type="staticpath"> <rule type="staticpath">
<entry>~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe</entry> <entry>~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
<entry>%ESPATH%\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe</entry> <entry>%ESPATH%\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
<entry>%ESPATH%\yuzu\yuzu-windows-msvc\yuzu.exe</entry> <entry>%ESPATH%\..\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
<entry>%ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
</rule> </rule>
</emulator> </emulator>
</ruleList> </ruleList>

2
README.md
View file

@ -18,7 +18,7 @@ Two theme sets (Slate and Modern) are bundled with the application, and addition
## Download ## Download
The latest stable version is **2.0.1** (released 2023-04-23) The latest stable version is **2.1.0** (released 2023-07-13)
Visit https://es-de.org/ to download ES-DE or go to the [package registry](https://gitlab.com/es-de/emulationstation-de/-/packages) where you can also find all previous releases. Visit https://es-de.org/ to download ES-DE or go to the [package registry](https://gitlab.com/es-de/emulationstation-de/-/packages) where you can also find all previous releases.

14
THEMES.md
View file

@ -1,4 +1,4 @@
# EmulationStation Desktop Edition (ES-DE) v2.0 - Themes # EmulationStation Desktop Edition (ES-DE) v2.1 - Themes
If creating theme sets specifically for ES-DE, please add `-es-de` to the repository/directory name, as in `slate-es-de`. Because ES-DE theme engine functionality has deviated greatly from the RetroPie EmulationStation fork on which it was originally based, any newer themes will not work on such older forks. At least the -es-de extension is an indicator that it's an ES-DE specific theme set. The actual theme name as defined using the `themeName` tag in capabilities.xml does of course not need to include the `-es-de` extension as that's the actual theme name that will be displayed when selecting theme sets from the _UI Settings_ menu. For example slate-es-de will be listed simply as _Slate_ in this menu. If creating theme sets specifically for ES-DE, please add `-es-de` to the repository/directory name, as in `slate-es-de`. Because ES-DE theme engine functionality has deviated greatly from the RetroPie EmulationStation fork on which it was originally based, any newer themes will not work on such older forks. At least the -es-de extension is an indicator that it's an ES-DE specific theme set. The actual theme name as defined using the `themeName` tag in capabilities.xml does of course not need to include the `-es-de` extension as that's the actual theme name that will be displayed when selecting theme sets from the _UI Settings_ menu. For example slate-es-de will be listed simply as _Slate_ in this menu.
@ -16,9 +16,9 @@ https://github.com/lilbud/es-de-theme-stuff
To test whether your theme set includes support for all ES-DE systems, download one of the following archives which contain ROMs directory structures fully populated with dummy files: To test whether your theme set includes support for all ES-DE systems, download one of the following archives which contain ROMs directory structures fully populated with dummy files:
[ROMs_ALL_Unix.zip](https://gitlab.com/es-de/emulationstation-de/-/blob/stable-2.0/tools/system-dirs-dummy-files/ROMs_ALL_Unix.zip)\ [ROMs_ALL_Unix.zip](https://gitlab.com/es-de/emulationstation-de/-/blob/stable-2.1/tools/system-dirs-dummy-files/ROMs_ALL_Unix.zip)\
[ROMs_ALL_macOS.zip](https://gitlab.com/es-de/emulationstation-de/-/blob/stable-2.0/tools/system-dirs-dummy-files/ROMs_ALL_macOS.zip)\ [ROMs_ALL_macOS.zip](https://gitlab.com/es-de/emulationstation-de/-/blob/stable-2.1/tools/system-dirs-dummy-files/ROMs_ALL_macOS.zip)\
[ROMs_ALL_Windows.zip](https://gitlab.com/es-de/emulationstation-de/-/blob/stable-2.0/tools/system-dirs-dummy-files/ROMs_ALL_Windows.zip) [ROMs_ALL_Windows.zip](https://gitlab.com/es-de/emulationstation-de/-/blob/stable-2.1/tools/system-dirs-dummy-files/ROMs_ALL_Windows.zip)
If you unzip and temporarily replace your ROMs directory with one of these, every system will be enabled on startup. If you unzip and temporarily replace your ROMs directory with one of these, every system will be enabled on startup.
@ -158,7 +158,7 @@ The directory name can be changed to whatever you like using the --prefix flag.
**Logos** **Logos**
Likewise there's a repository of system logotypes that can also be added and used in a similar fashion as the metadata. It can be found here: Likewise there's a repository of system logotypes that can also be added and used in the same fashion as the metadata. It can be found here:
https://gitlab.com/es-de/themes/system-logos https://gitlab.com/es-de/themes/system-logos
@ -182,7 +182,6 @@ Note that the remotes are only setup for your local repository, so if you clone
git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git
git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git
``` ```
After doing this you'll be able to pull repository updates as described above. After doing this you'll be able to pull repository updates as described above.
## Simple example theme ## Simple example theme
@ -986,6 +985,8 @@ Just remember, _this only works if the elements have the same type._
Navigation sounds are configured globally per theme set, so it needs to be defined using the special `all` view. Navigation sounds are configured globally per theme set, so it needs to be defined using the special `all` view.
It's recommended to put these elements in a separate file and include it from the main theme file (e.g. `<include>./navigationsounds.xml</include>`). Starting ES-DE with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sounds are provided by the theme, ES-DE will use the bundled navigation sounds as a fallback. This is done per sound file, so the theme could provide for example one or two custom sounds while using the bundled ES-DE sounds for the rest. It's recommended to put these elements in a separate file and include it from the main theme file (e.g. `<include>./navigationsounds.xml</include>`). Starting ES-DE with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sounds are provided by the theme, ES-DE will use the bundled navigation sounds as a fallback. This is done per sound file, so the theme could provide for example one or two custom sounds while using the bundled ES-DE sounds for the rest.
When fast-scrolling the textlist (by holding the up/down or shoulder buttons) the _scroll_ and _systembrowse_ sounds always play to completion before being played again, so it will sound weird if you have long samples such as those with reverb or silence added to the end. As such make sure to always use short samples for these sounds and test thoroughly with fast-scrolling. This is not an issue if using the carousel or grid elements.
Example debug output: Example debug output:
``` ```
Jul 12 11:28:58 Debug: NavigationSounds::loadThemeNavigationSounds(): Theme set includes navigation sound support, loading custom sounds Jul 12 11:28:58 Debug: NavigationSounds::loadThemeNavigationSounds(): Theme set includes navigation sound support, loading custom sounds
@ -2189,6 +2190,7 @@ Properties:
- `broken` - Will be shown when the game is marked as broken. - `broken` - Will be shown when the game is marked as broken.
- `controller` - Will be shown and overlaid by the corresponding controller icon if a controller type has been selected for the game (using the metadata editor or via scraping). - `controller` - Will be shown and overlaid by the corresponding controller icon if a controller type has been selected for the game (using the metadata editor or via scraping).
- `altemulator` - Will be shown when an alternative emulator is setup for the game. - `altemulator` - Will be shown when an alternative emulator is setup for the game.
- `manual` - Will be shown when a PDF manual has been downloaded for the game.
- `all` - Including this value will enable all badges. If some badges have been added already they will be shown in the order they were defined and the remaining ones will be added at the end, in the order listed above. Using the `all` value can be used as a way to future-proof the theme, because if additional badges are added in future ES-DE releases, no theme updates would be needed to accomodate them. Just make sure to include space for a few extra badges in the layout, and increase the `lines` and `itemsPerLine` accordingly. - `all` - Including this value will enable all badges. If some badges have been added already they will be shown in the order they were defined and the remaining ones will be added at the end, in the order listed above. Using the `all` value can be used as a way to future-proof the theme, because if additional badges are added in future ES-DE releases, no theme updates would be needed to accomodate them. Just make sure to include space for a few extra badges in the layout, and increase the `lines` and `itemsPerLine` accordingly.
* `controllerPos` - type: NORMALIZED_PAIR * `controllerPos` - type: NORMALIZED_PAIR
- The position of the controller icon relative to the parent `controller` badge. - The position of the controller icon relative to the parent `controller` badge.

6
USERGUIDE-DEV.md
View file

@ -137,7 +137,7 @@ Regardless of package format and operating system it's a good idea to update the
![alt text](images/es-de_application_updater.png "ES-DE Application Updater") ![alt text](images/es-de_application_updater.png "ES-DE Application Updater")
_This is what the application updater looks like when the update process has been completed._ _This is what the application updater looks like when the update process has been completed._
**Linux .deb packages** **Linux .deb package**
Upgrading ES-DE using this package type is very straightforward, just run it through the package manager of your operating system and the process should be entirely automatic. Upgrading ES-DE using this package type is very straightforward, just run it through the package manager of your operating system and the process should be entirely automatic.
@ -2389,7 +2389,7 @@ The order in which to sort your gamelists. This can be overriden per game system
**Menu color scheme** **Menu color scheme**
Provides a selection between a _Light_ and a _Dark_ color scheme. This will affect the entire menu system as well as the launch screen. Provides a selection between a _Dark_ and a _Light_ color scheme. This will affect the entire menu system as well as the launch screen.
**Menu opening effect** **Menu opening effect**
@ -3312,7 +3312,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file | | wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file |
| wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,<br>PrimeHack **(Standalone)** [UW] | No | | | wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,<br>PrimeHack **(Standalone)** [UW] | No | |
| wiiu | Nintendo Wii U | Cemu **(Standalone)** | | No | See the specific _Nintendo Wii U_ section elsewhere in this guide | | wiiu | Nintendo Wii U | Cemu **(Standalone)** | | No | See the specific _Nintendo Wii U_ section elsewhere in this guide |
| windows | Microsoft Windows | _Suspend ES-DE_ | _Keep ES-DE running_,<br>_AppImage (Suspend ES-DE)_ [U],<br>_AppImage (Keep ES-DE running)_ [U] | No | Shortcut (.desktop/.app/.lnk) file or script | | windows | Microsoft Windows | _Suspend ES-DE_ | _Keep ES-DE running_,<br>_AppImage (Suspend ES-DE)_ [U],<br>_AppImage (Keep ES-DE running)_ [U] | No | Shortcut (.desktop/.app/.lnk) file, script or AppImage |
| wonderswan | Bandai WonderSwan | Beetle Cygne | Mednafen **(Standalone)**,<br>ares **(Standalone)**,<br>ares [Benesse Pocket Challenge V2] **(Standalone)** | No | Single archive or ROM file | | wonderswan | Bandai WonderSwan | Beetle Cygne | Mednafen **(Standalone)**,<br>ares **(Standalone)**,<br>ares [Benesse Pocket Challenge V2] **(Standalone)** | No | Single archive or ROM file |
| wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file | | wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file |
| x1 | Sharp X1 | x1 | | | Single archive or ROM file | | x1 | Sharp X1 | x1 | | | Single archive or ROM file |

236
USERGUIDE.md
View file

@ -1,4 +1,4 @@
# EmulationStation Desktop Edition (ES-DE) v2.0 - User guide # EmulationStation Desktop Edition (ES-DE) v2.1 - User guide
It's generally recommended to read the [Frequently Asked Questions (FAQ)](FAQ.md) document prior to diving into the information in this guide. It's generally recommended to read the [Frequently Asked Questions (FAQ)](FAQ.md) document prior to diving into the information in this guide.
@ -37,23 +37,7 @@ The installation procedure is just covered briefly here and may differ a bit for
The .deb package is intended for Ubuntu but may work on other Debian-based distributions like Linux Mint and vanilla Debian. Your distribution should include a graphical package installer, but if you prefer to use the command line, run the following which will install ES-DE and resolve any dependencies: The .deb package is intended for Ubuntu but may work on other Debian-based distributions like Linux Mint and vanilla Debian. 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-2.0.0-x64.deb sudo apt install ./emulationstation-de-2.1.0-x64.deb
```
**Installing the Linux .rpm package**
On Fedora the RPM Fusion repository is a prerequisite for the installation, it can be installed like this:
```
sudo dnf install \
https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
```
Then you can use the graphical package installer or run this command, either method should automatically resolve the dependencies:
```
sudo dnf install ./emulationstation-de-2.0.0-x64.rpm
``` ```
**Running the Linux AppImage** **Running the Linux AppImage**
@ -63,6 +47,11 @@ The AppImage release should be usable on most modern x86 64-bit Linux distributi
chmod +x EmulationStation-DE-x64.AppImage chmod +x EmulationStation-DE-x64.AppImage
``` ```
Or if you're using the Steam Deck AppImage:
```
chmod +x EmulationStation-DE-x64_SteamDeck.AppImage
```
To run AppImage files you need libfuse2 installed, but some newer distributions like Ubuntu 22.04 LTS no longer ship with this library preinstalled. You can however easily install it like this: To run AppImage files you need libfuse2 installed, but some newer distributions like Ubuntu 22.04 LTS no longer ship with this library preinstalled. You can however easily install it like this:
``` ```
sudo apt install libfuse2 sudo apt install libfuse2
@ -86,30 +75,31 @@ There's an application log file created in the ES-DE home directory named `es_lo
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. 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 Unix: 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 _dos_ system as seen on Unix:
``` ```
System name: System name:
gc dos
Full system name: Full system name:
Nintendo GameCube DOS (PC)
Supported file extensions: Supported file extensions:
.ciso .CISO .dff .DFF .dol .DOL .elf .ELF .gcm .GCM .gcz .GCZ .iso .ISO .json .JSON .m3u .M3U .rvz .RVZ .tgc .TGC .wad .WAD .wbfs .WBFS .wia .WIA .7z .7Z .zip .ZIP .bat .BAT .com .COM .conf .CONF .cue .CUE .dosz .DOSZ .exe .EXE .iso .ISO .7z .7Z .zip .ZIP
Launch command: Launch command:
%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dolphin_libretro.so %ROM% %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_pure_libretro.so %ROM%
Alternative launch commands: Alternative launch commands:
%EMULATOR_DOLPHIN% -b -e %ROM% %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM%
%EMULATOR_PRIMEHACK% -b -e %ROM% %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_svn_libretro.so %ROM%
%EMULATOR_TRIFORCE% -b -e %ROM% %STARTDIR%=%GAMEDIR% %EMULATOR_DOSBOX-X% %ROM%
%STARTDIR%=%GAMEDIR% %EMULATOR_DOSBOX-STAGING% %ROM%
Platform (for scraping): Platform (for scraping):
gc dos
Theme folder: Theme folder:
gc dos
``` ```
This file is not needed to run ES-DE, it's only a convenience to easily see which emulators and file extensions are supported per system. This file is not needed to run ES-DE, it's only a convenience to easily see which emulators and file extensions are supported per system.
@ -119,25 +109,35 @@ In addition to this, a file named systems.txt will be created in the root of the
For example: For example:
``` ```
gc: Nintendo GameCube dos: DOS (PC)
genesis: Sega Genesis dragon32: Dragon Data Dragon 32
gx4000: Amstrad GX4000 dreamcast: Sega Dreamcast
easyrpg: EasyRPG Game Engine
epic: Epic Games Store
famicom: Nintendo Family Computer
``` ```
If a custom es_systems.xml file is present in ~/.emulationstation/custom_systems/ any entries from this file will have their names trailed by the text _(custom system)_. So if the GameCube system in the example above would be present in the custom systems configuration file, the system would be shown as _gc (custom system)_ instead of simply _gc_. This is only applicable for the systems.txt and systeminfo.txt files, the trailing text is not applied or used anywhere else in the application. If a custom es_systems.xml file is present in ~/.emulationstation/custom_systems/ any entries from this file will have their names trailed by the text _(custom system)_. So if the _dos_ system in the example above would be present in the custom systems configuration file, the system would be shown as _dos (custom system)_ instead of simply _dos_. This is only applicable for the systems.txt and systeminfo.txt files, the trailing text is not applied or used anywhere else in the application.
![alt text](images/es-de_ui_easy_setup.png "ES-DE Easy Setup") ![alt text](images/es-de_ui_easy_setup.png "ES-DE Easy Setup")
_This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._ _This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._
## Upgrading to a newer release ## Upgrading to a newer release
**Note:** Before upgrading ES-DE, make sure that you have not made any system customizations anywhere in the installation directory structure as these files will be overwritten during the upgrade process. All customizations should go into ~/.emulationstation/custom_systems/ as described elsewhere in this guide. None of the upgrade methods mentioned below will ever touch any files inside your .emulationstation directory. **Note:** Before upgrading ES-DE, make sure that you have not made any system customizations anywhere in the installation directory structure as these files will be overwritten during the upgrade process. All customizations should go into ~/.emulationstation/custom_systems/ as described elsewhere in this guide. None of the upgrade methods mentioned below will ever touch any files inside your .emulationstation directory tree.
It's possible that the new ES-DE release adds support for more systems and emulators compared to the version you previously had installed, so you may want to recreate the ROMs directory tree after you've completed the installation. The easiest way to do that is to start ES-DE once with the _--create-system-dirs_ command line option which will create any missing system directories and also update the systems.txt and systeminfo.txt files. This is a safe operation as it will not overwrite or delete your game files. As of ES-DE 2.1.0 there is a built-in application updater that can update the Linux AppImage releases. Later on this will hopefully be expanded to cover more package formats and operating systems. Its use is straightforward, just follow the on-screen instructions. The old AppImage file is retained by renaming it, adding its version to the filename followed by the .OLD extension, for example `EmulationStation-DE-x64_SteamDeck.AppImage_2.1.0.OLD`
**Linux .deb and .rpm packages** Note that the updater will keep whatever filename you had for your running AppImage file, which could potentially be confusing if you for example added version information to the filename. It's always recommend to keep the default AppImage filenames, i.e. `EmulationStation-DE-x64.AppImage` and `EmulationStation-DE-x64_SteamDeck.AppImage`
Upgrading ES-DE using these packages is very straightforward, just run them through the package manager of your operating system and the process should be entirely automatic. Regardless of package format and operating system it's a good idea to update the ROMs directory tree after upgrading to a new version. It's possible that the new ES-DE release adds support for more systems and emulators compared to the version you previously had installed. The easiest way to do this is to start ES-DE once with the _--create-system-dirs_ command line option which will create any missing system directories and also update the systems.txt and systeminfo.txt files. This is a safe operation as it will not overwrite or delete your game files.
![alt text](images/es-de_application_updater.png "ES-DE Application Updater")
_This is what the application updater looks like when the update process has been completed._
**Linux .deb package**
Upgrading ES-DE using this package type is very straightforward, just run it through the package manager of your operating system and the process should be entirely automatic.
**Linux AUR** **Linux AUR**
@ -145,7 +145,7 @@ AUR upgrades should be automatically handled via your package manager and it sho
**Linux AppImage** **Linux AppImage**
As the ES-DE AppImages always retain their filenames between stable releases you only need to replace the previous AppImage with the new one and you're done. Just make sure to set the new AppImage as executable so it can be launched. Use the built-in application updater as described above.
**macOS** **macOS**
@ -286,7 +286,7 @@ As the Steam Deck is essentially a Linux desktop computer with a custom user int
Another way to install ES-DE is via [RetroDECK](http://retrodeck.net) which is shipped as a Flatpak and can be easily installed via Discover. As RetroDECK bundles both ES-DE and all its emulators inside the Flatpak you don't need to update any emulators separately or set Flatpak permissions manually. The drawback compared to running ES-DE standalone is that less systems and emulators are supported. Most popular systems should work fine though and more emulators are getting added continuously so the situation will improve over time. Also note that if going for RetroDECK you will have a non-standard ES-DE installation so some parts of this user guide will no longer apply. For documentation specific to RetroDECK, refer to their [wiki](https://github.com/XargonWan/RetroDECK/wiki). Another way to install ES-DE is via [RetroDECK](http://retrodeck.net) which is shipped as a Flatpak and can be easily installed via Discover. As RetroDECK bundles both ES-DE and all its emulators inside the Flatpak you don't need to update any emulators separately or set Flatpak permissions manually. The drawback compared to running ES-DE standalone is that less systems and emulators are supported. Most popular systems should work fine though and more emulators are getting added continuously so the situation will improve over time. Also note that if going for RetroDECK you will have a non-standard ES-DE installation so some parts of this user guide will no longer apply. For documentation specific to RetroDECK, refer to their [wiki](https://github.com/XargonWan/RetroDECK/wiki).
It's also possible to install ES-DE using [EmuDeck](https://www.emudeck.com) which will automatically download the latest Steam Deck-specific AppImage. Just be aware that if using EmuDeck you will have a non-standard ES-DE installation as their installer makes some customizations to paths and other settings. This guide only covers default installations so in case you see something mentioned that doesn't match your setup, make sure to contact the EmuDeck support. It's also possible to install ES-DE using [EmuDeck](https://www.emudeck.com) which will automatically download the latest Steam Deck-specific AppImage. Just be aware that if using EmuDeck you will have a non-standard ES-DE installation as their installer makes some customizations to paths and other settings. For this and other reasons it's therefore not recommended to use EmuDeck, it's generally better to make a manual installation of ES-DE and your emulators and set everything up exactly to your liking.
Unless RetroDECK is used, Flatpak releases of some emulators may need some extra permissions to be able to launch games placed on external devices such as a memory card. This is the case for instance for melonDS and RPCS3. The easiest way to do this is by using [Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal). The option you need to enable is generally _All system files_ in the _Filesystem_ section. If using EmuDeck some of these settings will be applied automatically via their installer. Unless RetroDECK is used, Flatpak releases of some emulators may need some extra permissions to be able to launch games placed on external devices such as a memory card. This is the case for instance for melonDS and RPCS3. The easiest way to do this is by using [Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal). The option you need to enable is generally _All system files_ in the _Filesystem_ section. If using EmuDeck some of these settings will be applied automatically via their installer.
@ -300,6 +300,8 @@ If you are unfamiliar with Unix operating systems, make sure to at least read up
ES-DE on the Raspberry Pi requires a desktop environment, or more specifically a window manager and a sound server (like PulseAudio or PipeWire). There are no plans to add support for direct hardware access to the framebuffer or to ALSA. If you want to use your Raspberry Pi as an appliance, take a look at [RetroPie](https://retropie.org.uk), [Recalbox](https://www.recalbox.com) or [Batocera](https://batocera.org) instead. ES-DE on the Raspberry Pi requires a desktop environment, or more specifically a window manager and a sound server (like PulseAudio or PipeWire). There are no plans to add support for direct hardware access to the framebuffer or to ALSA. If you want to use your Raspberry Pi as an appliance, take a look at [RetroPie](https://retropie.org.uk), [Recalbox](https://www.recalbox.com) or [Batocera](https://batocera.org) instead.
Also note that there are no prebuilt packages for the Raspberry Pi, so you will need to compile ES-DE yourself. Fortunately this is easy to do and the process is documented [here](INSTALL.md#building-on-unix).
The Raspberry Pi 4/400 is the minimum recommended version and earlier boards have not been tested. The GPU memory should be set to at least 256 MiB using `raspi-config` and the GL driver must be set to `GL (Fake KMS)` or the performance will be horrible. On Raspberry Pi OS 11 the KMS option is enabled by default. The Raspberry Pi 4/400 is the minimum recommended version and earlier boards have not been tested. The GPU memory should be set to at least 256 MiB using `raspi-config` and the GL driver must be set to `GL (Fake KMS)` or the performance will be horrible. On Raspberry Pi OS 11 the KMS option is enabled by default.
In general, 720p works fine with the RPi 4, and 1080p is tolerable but not really a nice and smooth experience. Due to the relative weakness of the Rasperry Pi GPU, the video scanline rendering options for the screensaver and media viewer have been disabled. These options can be re-enabled via the menu if you don't mind lower video framerates. In general, 720p works fine with the RPi 4, and 1080p is tolerable but not really a nice and smooth experience. Due to the relative weakness of the Rasperry Pi GPU, the video scanline rendering options for the screensaver and media viewer have been disabled. These options can be re-enabled via the menu if you don't mind lower video framerates.
@ -454,7 +456,7 @@ Default keyboard mappings are shown in brackets.
**Up and down**\ **Up and down**\
_(Arrow up / Arrow down)_ _(Arrow up / Arrow down)_
Navigates between system and game entries where these buttons are applicable, such as for textlists and vertical carousels. Also used in menus for general navigation. Navigates between system and game entries where these buttons are applicable, such as for textlists, grids and vertical carousels. Also used in menus for general navigation. For the media viewer it changes viewing mode between game media and PDF manuals.
**Left and right**\ **Left and right**\
_(Arrow left / Arrow right)_ _(Arrow left / Arrow right)_
@ -474,12 +476,12 @@ Opens and closes the gamelist options menu in the gamelist view.
**Left and right shoulder buttons**\ **Left and right shoulder buttons**\
_(Page up / Page down)_ _(Page up / Page down)_
Provides quick jumping in textlists and menus, jumps 10 games in the gamelists and 6 entries in the menus. Navigates between gamelists if the _Quick system select_ option has been set to use these buttons and the primary element supports it. Also used as back and blankspace keys in text edit dialogs. Provides quick jumping in textlists and menus, jumps 10 games in the gamelists and 6 entries in the menus. Navigates between gamelists if the _Quick system select_ option has been set to use these buttons and the primary element supports it. Also used as back and blankspace keys in text edit dialogs and for zooming in and out when viewing PDF game manuals.
**Left and right trigger buttons**\ **Left and right trigger buttons**\
_(Home / End)_ _(Home / End)_
Jumps to the first or last entries in carousels, grids and textlists as well as in menus and text edit dialogs. Navigates between gamelists if the _Quick system select_ option has been set to use these buttons and the primary element supports it. Jumps to the first or last entries in carousels, grids and textlists as well as in menus and text edit dialogs. Navigates between gamelists if the _Quick system select_ option has been set to use these buttons and the primary element supports it. Also jumps to the first or last entry/page when using the media viewer.
**Left and right thumbstick click**\ **Left and right thumbstick click**\
_(F2 / F3)_ _(F2 / F3)_
@ -637,9 +639,10 @@ The following emulators are supported in AppImage format when using the bundled
| gc | Triforce | dolphin-emu-triforce*.AppImage | | gc | Triforce | dolphin-emu-triforce*.AppImage |
| macintosh | Basilisk II | BasiliskII*.AppImage | | macintosh | Basilisk II | BasiliskII*.AppImage |
| macintosh | SheepShaver | SheepShaver*.AppImage | | macintosh | SheepShaver | SheepShaver*.AppImage |
| n3ds | Citra | citra*.AppImage |
| n64 | RMG | RMG*.AppImage | | n64 | RMG | RMG*.AppImage |
| n64dd | RMG | RMG*.AppImage | | n64dd | RMG | RMG*.AppImage |
| ps2 | PCSX2 | pcsx2*-Qt.AppImage | | ps2 | PCSX2 | pcsx2*.AppImage |
| ps2 | Play! | Play!*.AppImage | | ps2 | Play! | Play!*.AppImage |
| ps3 | RPCS3 | rpcs3*.AppImage | | ps3 | RPCS3 | rpcs3*.AppImage |
| psx | DuckStation | duckstation-nogui*.AppImage | | psx | DuckStation | duckstation-nogui*.AppImage |
@ -652,6 +655,46 @@ The following emulators are supported in AppImage format when using the bundled
_RMG = Rosalie's Mupen GUI_ _RMG = Rosalie's Mupen GUI_
## AppImage vs Flatpak search order on Linux
As of ES-DE 2.1.0 emulator AppImages are always searched before Flatpaks while in previous releases the opposite was true.
To clarify with an example, this is what the find rule entry for the Dolphin emulator looks like:
```xml
<emulator name="DOLPHIN">
<!-- Nintendo GameCube and Wii emulator Dolphin -->
<rule type="systempath">
<entry>dolphin-emu</entry>
<entry>org.DolphinEmu.dolphin-emu</entry>
</rule>
<rule type="staticpath">
<entry>~/Applications/Dolphin_Emulator*.AppImage</entry>
<entry>~/.local/bin/Dolphin_Emulator*.AppImage</entry>
<entry>~/bin/Dolphin_Emulator*.AppImage</entry>
<entry>/var/lib/flatpak/exports/bin/org.DolphinEmu.dolphin-emu</entry>
<entry>~/.local/share/flatpak/exports/bin/org.DolphinEmu.dolphin-emu</entry>
</rule>
</emulator>
```
The _staticpath_ rules are always parsed in the order they are defined, and as the AppImage entries are listed above the Flatpak entries, these will be searched first.
There is however a workaround available to launch the Flatpak first, should you prefer that. As you can see in the above example there is also a _systempath_ entry for the Flatpak launch file, and by manually defining the path to your Flatpak bin directory you can make use of this systempath entry instead, which will always be executed before the staticpath entries.
For example if using the ES-DE AppImage release, this would be the command to execute:
```
PATH=/var/lib/flatpak/exports/bin:~/.local/share/flatpak/exports/bin:$PATH ./EmulationStation-DE-x64.AppImage
```
Obviously you would need to change the path to the AppImage if it's not in your current working directory.
You can also set the PATH variable permanently in your shell environment configuration file:
```
export PATH=/var/lib/flatpak/exports/bin:~/.local/share/flatpak/exports/bin:$PATH
```
Refer to your operating system documentation for more details of how the PATH environmental variable works and how to customize your shell environment.
## Using manually downloaded emulators on Linux ## Using manually downloaded emulators on Linux
Normally on Linux you would install emulators using either one of the established cross-distribution package formats, i.e. AppImage, Snap or Flatpak, or you would install them using the operating system repository (including the AUR if available on your OS). Less likely would be to manually build from source code and install to a standard system directory. In all these instances ES-DE should be able to find the emulator when launching a game. But in some cases you may instead manually download an emulator as an archive file to unzip somewhere on the file system. Normally you would want to place these files in your home directory, and if running a distribution that has an immutable filesystem (such as SteamOS or Fedora Silverblue), you don't even have the choice to install them to a standard system directory. Normally on Linux you would install emulators using either one of the established cross-distribution package formats, i.e. AppImage, Snap or Flatpak, or you would install them using the operating system repository (including the AUR if available on your OS). Less likely would be to manually build from source code and install to a standard system directory. In all these instances ES-DE should be able to find the emulator when launching a game. But in some cases you may instead manually download an emulator as an archive file to unzip somewhere on the file system. Normally you would want to place these files in your home directory, and if running a distribution that has an immutable filesystem (such as SteamOS or Fedora Silverblue), you don't even have the choice to install them to a standard system directory.
@ -856,7 +899,7 @@ Also in this case the directory will be displayed as a regular game file inside
### Folder flattening ### Folder flattening
**This functionality is experimental and may cause all sorts of issues including corrupting your gamelist.xml files, so make sure to have backups of your data prior to attempting to use this.** **This functionality is experimental and may cause all sorts of issues like corrupting your gamelist.xml files, so make sure to have backups of your data prior to attempting to use this.**
ES-DE works according to the filesystem paradigm used on most operating systems, meaning the file and directory structure of your ROMs directory is reflected inside the application. So if you create a directory on the filesystem and place some games in there, it will be reflected inside ES-DE as a folder that you can enter and launch games from. ES-DE works according to the filesystem paradigm used on most operating systems, meaning the file and directory structure of your ROMs directory is reflected inside the application. So if you create a directory on the filesystem and place some games in there, it will be reflected inside ES-DE as a folder that you can enter and launch games from.
@ -1038,7 +1081,7 @@ ln -s /usr/local/Cellar/mame/0.248/share/mame/hash ~/.mame/ # on x86/Int
#### Bally Astrocade #### Bally Astrocade
Place the ROMs in the `~/ROMs/astrocde` directory, the files must have the short MAME names such as _astrobat.zip_ and _conan.zip_. If using MAME standalone then no further setup is required and the games should just launch. Place your ROMs in the `~/ROMs/astrocde` directory, the files must have the short MAME names such as _astrobat.zip_ and _conan.zip_. Also make sure that the BIOS archive astrocde.zip is included with the ROM set. If using MAME standalone then no further setup is required and the games should just launch.
If instead using the _MAME - Current_ RetroArch core, then a hash file must be added inside the RetroArch system directory at this location: If instead using the _MAME - Current_ RetroArch core, then a hash file must be added inside the RetroArch system directory at this location:
@ -1445,9 +1488,9 @@ Do NOT overwrite any files when copying over the `data` and `font` directories,
#### Nintendo 64DD #### Nintendo 64DD
The Japan-only 64DD floppy disk addon for the Nintendo 64 is of limited use since there were almost no games released for it, but ES-DE still supports it. The setup below is applicable to both the regular n64 system and the specific n64dd system. The Japan-only 64DD floppy disk addon for the Nintendo 64 is of limited use since there were almost no games released for it, but ES-DE still supports it. The setup below is applicable to both the regular n64 system and the specific n64dd system, with the exception of ares which can't launch 64DD games if they are placed in the regular n64 system.
The setup is quite particular and works differently between the three supported emulators ParaLLEl N64, Mupen64Plus-Next and Rosalie's Mupen GUI. The setup is quite particular and works differently between the four supported emulators ParaLLEl N64, Mupen64Plus-Next, Rosalie's Mupen GUI and ares.
**ParaLLEl N64** **ParaLLEl N64**
@ -1477,6 +1520,10 @@ For RMG you should use the exact same IPL file as for ParaLLEl N64 but it has to
Following this setup you will be able to launch games with the .ndd, .d64, .7z and .zip file extensions. Following this setup you will be able to launch games with the .ndd, .d64, .7z and .zip file extensions.
**ares**
For ares you need the `64DD_IPL.bin` file added to the Firmware configuration screen inside the emulator. Following this you should be able to launch games with the .ndd file extension or such files compressed into .zip archives.
#### Nintendo Wii U #### Nintendo Wii U
The .wua archive format is the preferred method to use for Wii U games, but the method of using unpacked games is also documented here for reference. The .wua archive format is the preferred method to use for Wii U games, but the method of using unpacked games is also documented here for reference.
@ -1614,7 +1661,9 @@ This is what the complete setup could look like:
#### Ports and desktop applications #### Ports and desktop applications
As ports and desktop applications are handled in almost exactly the same way in ES-DE both of these are described in this section. For these systems it's generally native applications rather that emulated games that are executed. There are two main approaches to setting up such entries and these are _shortcuts_ and _scripts_. Note that these can be mixed in the same system, you can have some entries that are shortcuts and some that are scripts and they will still all work. _The emulators system is essentially a clone of the desktop system so it's not discussed specifically in this section._
As ports and desktop applications are handled in almost exactly the same way in ES-DE both of these are described in this section. For these systems it's generally native applications rather that emulated games that are executed. There are two main approaches to setting up such entries and these are _shortcuts_ and _scripts_. Note that these can be mixed in the same system, you can have some entries that are shortcuts and some that are scripts and they will still all work. On Linux there is also a third option to launch AppImages directly, which is covered below as well.
For the _desktop_ system specifically, you can choose to suspend ES-DE while an application or game is launched, or you can choose to keep ES-DE running in the background. This is controlled by the selection of either the default emulator _Suspend ES-DE_ or the alternative emulator _Keep ES-DE running_. As is the case for all alternative emulator entries, this can be configured system-wide or on a per-game basis. For the _desktop_ system specifically, you can choose to suspend ES-DE while an application or game is launched, or you can choose to keep ES-DE running in the background. This is controlled by the selection of either the default emulator _Suspend ES-DE_ or the alternative emulator _Keep ES-DE running_. As is the case for all alternative emulator entries, this can be configured system-wide or on a per-game basis.
@ -1680,6 +1729,10 @@ vkquake_arcane_dimensions.sh:
You don't need to set execution permissions for these scripts, ES-DE will run them anyway. You don't need to set execution permissions for these scripts, ES-DE will run them anyway.
**Method 3, AppImages** _Linux only_
On Linux it's also possible to launch AppImages directly without having to call them from a shell script. For emulators it's generally required to keep their AppImages in the `~/Applications/` directory and symlink them into the ROMs directory tree, but for other applications and games it may be fine to store them directly in the ROMs tree. In order for this to work you need to use one of the alternative emulator entries that enable AppImages to be launched. It will not work if attempting to use the emulator entries that run scripts and shortcuts. You can set the alternative emulator per game/file from the metadata editor.
#### ScummVM #### ScummVM
ScummVM overlaps a bit with DOS when it comes to the logic of setting it up. It's recommended to keep games in separate folders, so if you have a game distributed as a ZIP file, uncompress it to its own directory. ScummVM overlaps a bit with DOS when it comes to the logic of setting it up. It's recommended to keep games in separate folders, so if you have a game distributed as a ZIP file, uncompress it to its own directory.
@ -1918,6 +1971,7 @@ Here's an overview of what's supported when using these scrapers:
| 3D boxes | Yes | No | | 3D boxes | Yes | No |
| Fan art | Yes | Yes | | Fan art | Yes | Yes |
| Physical media | Yes | No | | Physical media | Yes | No |
| Game manuals (PDF) | Yes | No |
The category **Other game metadata** includes Description, Release date, Developer, Publisher, Genre and Players. The category **Other game metadata** includes Description, Release date, Developer, Publisher, Genre and Players.
@ -1997,6 +2051,7 @@ The media directories per game system are:
* backcovers * backcovers
* covers * covers
* fanart * fanart
* manuals
* marquees * marquees
* miximages * miximages
* physicalmedia * physicalmedia
@ -2044,7 +2099,10 @@ It's possible to change the game media directory location from within ES-DE, for
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. Using the keyboard quit shortcut (Alt + F4 / Command + Q by default) 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. Using the keyboard quit shortcut (Alt + F4 / Command + Q by default) will also save any pending changes.
![alt text](images/es-de_main_menu.png "ES-DE Main Menu") ![alt text](images/es-de_main_menu.png "ES-DE Main Menu")
_The main menu with its multiple submenus._ _The main menu with its multiple submenus using the default dark menu color scheme._
![alt text](images/es-de_main_menu_light.png "ES-DE Main Menu, Light")
_The main menu using the alternative light menu color scheme._
Following is a breakdown of the main menu entries. Following is a breakdown of the main menu entries.
@ -2135,6 +2193,10 @@ Images of cartridges, diskettes, tapes, CD-ROMs etc. that were used to distribut
Fan art. These can get quite large so if you don't need them then disable this option to speed up the scraping process. Fan art. These can get quite large so if you don't need them then disable this option to speed up the scraping process.
**Game manuals** _(ScreenScraper only)_
Manuals in PDF format. Note that these files can be quite large.
#### Miximage settings #### 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, box/cover and physical media images to make a composite picture that is displayed in the gamelist view. There are various settings for the generator. These are the settings for the miximage generator, which can either be run from the scraper (single-game scraper or multi-scraper) or from the offline generator. The miximage combines the screenshot, marquee, box/cover and physical media images to make a composite picture that is displayed in the gamelist view. There are various settings for the generator.
@ -2143,6 +2205,22 @@ These are the settings for the miximage generator, which can either be run from
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. 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.
**Horizontal screenshot fit**
For horizontally oriented screenshots which do not match the aspect ratio of the miximage frame, this option defines how to fit the image. Valid options are _contain_ which will keep the entire image within the frame while maintaining its aspect ratio, _crop_ which will crop the image so it fills the entire frame, and _stretch_ which will fill the entire frame while possibly breaking the aspect ratio of the image. Generally _crop_ is the best option for widescreen images like games running at 16:9 aspect ratios and similar.
**Vertical screenshot fit**
For vertically oriented screenshots which do not match the aspect ratio of the miximage frame, this option defines how to fit the image. Valid options are _contain_ which will keep the entire image within the frame while maintaining its aspect ratio, _crop_ which will crop the image so it fills the entire frame, and _stretch_ which will fill the entire frame while possibly breaking the aspect ratio of the image. Generally _contain_ is the best option for vertically oriented images like vertical arcade shooters and similar.
**Screenshot aspect ratio threshold**
This option defines the tolerated deviation from the miximage frame's aspect ratio before applying _crop_ and _contain_ to a screenshot. As such this option has no effect if _stretch_ has been selected as the screenshot fit. When set to _low_ only very small deviations are accepted which will more strictly enforce the aspect ratio of the screenshot with the drawback of possibly adding a small amount of crop and blank area around the image. It's usually best to keep this option set to _high_ which will stretch screenshots to a reasonable degree before applying any _crop_ or _contain_ fitting.
**Blank areas fill color**
When setting the screenshot fit to _contain_ there will be blank areas around the screenshot as it's fitted within the miximage frame. This option defines whether to fill this area with a _black_ color or if the _frame_ color should be used instead.
**Screenshot scaling method** **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. 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.
@ -2209,7 +2287,7 @@ Multiple languages are supported by ScreenScraper, and this affects translations
**Automatic retries on error** **Automatic retries on error**
How many times to automatically retry scraping if an error is encountered, from 0 to 10. How many times to automatically retry scraping if an error is encountered, from 0 to 10. Note that this is only applied when running in automatic or semi-automatic mode and not when for instance using the single-game scraper. It also doesn't apply to non-recoverable errors such as insufficient permissions or if the disk is full.
**Retry attempt timer** **Retry attempt timer**
@ -2307,6 +2385,10 @@ If set to _None_, the system view will be displayed. Any other value will jump t
The order in which to sort your gamelists. This can be overriden per game system using the gamelist 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. The order in which to sort your gamelists. This can be overriden per game system using the gamelist 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 color scheme**
Provides a selection between a _Dark_ and a _Light_ color scheme. This will affect the entire menu system as well as the launch screen.
**Menu opening effect** **Menu opening effect**
Animation to play when opening the main menu or the gamelist options menu. Also sets the animation for the game launch screen. Can be set to _Scale-up_ or _None_. Animation to play when opening the main menu or the gamelist options menu. Also sets the animation for the game launch screen. Can be set to _Scale-up_ or _None_.
@ -2383,6 +2465,14 @@ Activates or deactivates the built-in help system that provides contextual infor
Settings for the media viewer that is accessible from the gamelist views. Settings for the media viewer that is accessible from the gamelist views.
**Help prompts**
Controls positioning of the navigation help prompts. The available options are _top_, _bottom_ or _disabled_.
**Display media types**
Whether the help prompts should include the media type for the current entry, i.e. _video, box cover, box back cover, title screen, screenshot, fan art_ or _miximage_.
**Keep videos running when viewing images** **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. 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.
@ -2427,6 +2517,10 @@ Options specific to the slideshow screensaver.
For how long to display images before changing to the next game. Allowed range is between 2 and 120 seconds in 2-second increments. The default value is 10 seconds. For how long to display images before changing to the next game. Allowed range is between 2 and 120 seconds in 2-second increments. The default value is 10 seconds.
**Only include favorite games**
Whether to only include games marked as favorites.
**Stretch images to screen resolution** **Stretch images to screen resolution**
This will fill the entire screen surface but will probably break the aspect ratio of the image. This will fill the entire screen surface but will probably break the aspect ratio of the image.
@ -2459,6 +2553,10 @@ Options specific to the video screensaver.
For how long to play videos before changing to the next game. Allowed range is between 0 and 120 seconds in 2-second increments. If set to 0 (which is the default value), the next game will be selected after the entire video has finished playing. If set to a higher value than the length of a game video, it will loop until reaching the swap time. For how long to play videos before changing to the next game. Allowed range is between 0 and 120 seconds in 2-second increments. If set to 0 (which is the default value), the next game will be selected after the entire video has finished playing. If set to a higher value than the length of a game video, it will loop until reaching the swap time.
**Only include favorite games**
Whether to only include games marked as favorites.
**Stretch videos to screen resolution** **Stretch videos to screen resolution**
This will fill the entire screen surface but will probably break the aspect ratio of the video. This will fill the entire screen surface but will probably break the aspect ratio of the video.
@ -2903,15 +3001,17 @@ This will remove the actual game file, its gamelist.xml entry, its entry in any
## Game media viewer ## 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. The game media viewer displays videos, images and PDF manuals 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. If a game video is available, then this will be played automatically when launching the viewer. The _left_ and _right_ buttons are used to navigate betweeen media files one at a time, and the trigger buttons can be used to jump to the first and last entries. 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 media viewer can display the following media: _video, box cover, box back cover, title screen, screenshot_, _fan art_ and _miximage_. The following media can be displayed: _video, box cover, box back cover, title screen, screenshot_, _fan art_ and _miximage_.
The other settings for the media viewer are similar to what is available for the screensavers; the audio can be enabled or disabled, the video can be stretched to fill the entire screen and scanlines and blur can be rendered on top of it. For screenshots and title screens, scanlines can be rendered. All these options are configurable via the _UI Settings_ menu. If the game has a downloaded PDF manual then you can view it by pressing the _up_ button which will change the media viewer to PDF viewing mode. To get back to displaying videos and images when in this mode, press the _down_ button. When in PDF viewing mode it's possible to zoom in and out using the shoulder buttons. When zoomed in, the left, right, up and down buttons will pan the view. So in order to re-enable page navigation either zoom out completely or reset the view by pressing the left or right trigger button.
Pressing any other button than _left_ or _right_ closes the media viewer. Pressing any other button than those mentioned above closes the media viewer.
The settings for the media viewer are similar to what is available for the screensavers; the audio can be enabled or disabled, the video can be stretched to fill the entire screen and scanlines and blur can be rendered on top of it. For screenshots and title screens, scanline rendering can be enabled or disabled. It's also possible to change the positioning of the help prompts to the top or bottom, or to disable them entirely. All these options are configurable via the _UI Settings_ menu and are described in more detail elsewhere in this document.
## Screensaver ## Screensaver
@ -3050,14 +3150,14 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| amiga1200 | Commodore Amiga 1200 | PUAE | PUAE 2021 | Yes | See the specific _Commodore Amiga_ section elsewhere in this guide | | amiga1200 | Commodore Amiga 1200 | PUAE | PUAE 2021 | Yes | See the specific _Commodore Amiga_ section elsewhere in this guide |
| amiga600 | Commodore Amiga 600 | PUAE | PUAE 2021 | Yes | See the specific _Commodore Amiga_ section elsewhere in this guide | | amiga600 | Commodore Amiga 600 | PUAE | PUAE 2021 | Yes | See the specific _Commodore Amiga_ section elsewhere in this guide |
| amigacd32 | Commodore Amiga CD32 | PUAE | PUAE 2021 | Yes | | | amigacd32 | Commodore Amiga CD32 | PUAE | PUAE 2021 | Yes | |
| amstradcpc | Amstrad CPC | Caprice32 | CrocoDS,<br>CPCemu **(Standalone)** | No | | | amstradcpc | Amstrad CPC | Caprice32 | CrocoDS,<br>CPCemu **(Standalone)**,<br>MAME **(Standalone)** | Yes for MAME | Single archive or disk file |
| android | Google Android | BlueStacks **(Standalone)** [W] | | No | Shortcut (.lnk) file | | android | Google Android | BlueStacks **(Standalone)** [W] | | No | Shortcut (.lnk) file |
| apple2 | Apple II | LinApple **(Standalone)** [U],<br>Mednafen **(Standalone)** [M],<br>AppleWin **(Standalone)** [W] | Mednafen **(Standalone)** [UW],<br>MAME **(Standalone)** | Yes for Mednafen and MAME | See the specific _Apple II_ section elsewhere in this guide | | apple2 | Apple II | LinApple **(Standalone)** [U],<br>Mednafen **(Standalone)** [M],<br>AppleWin **(Standalone)** [W] | Mednafen **(Standalone)** [UW],<br>MAME **(Standalone)** | Yes for Mednafen and MAME | See the specific _Apple II_ section elsewhere in this guide |
| apple2gs | Apple IIGS | MAME **(Standalone)** | | Yes | See the specific _Apple IIGS_ section elsewhere in this guide | | apple2gs | Apple IIGS | MAME **(Standalone)** | | Yes | See the specific _Apple IIGS_ section elsewhere in this guide |
| arcade | Arcade | MAME - Current | MAME 2010,<br>MAME 2003-Plus,<br>MAME 2000,<br>MAME **(Standalone)**,<br>FinalBurn Neo,<br>FinalBurn Neo **(Standalone)** [UW],<br>FB Alpha 2012,<br>Flycast,<br>Flycast **(Standalone)**,<br>Kronos [UW],<br>Model 2 Emulator **(Standalone)** [W],<br>Model 2 Emulator [Suspend ES-DE] **(Standalone)** [W],<br>Supermodel **(Standalone)** [UW],<br>Supermodel [Fullscreen] **(Standalone)** [UW],<br>_Shortcut or script_ | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | | arcade | Arcade | MAME - Current | MAME 2010,<br>MAME 2003-Plus,<br>MAME 2000,<br>MAME **(Standalone)**,<br>FinalBurn Neo,<br>FinalBurn Neo **(Standalone)** [UW],<br>FB Alpha 2012,<br>Flycast,<br>Flycast **(Standalone)**,<br>Kronos [UW],<br>Model 2 Emulator **(Standalone)** [W],<br>Model 2 Emulator [Suspend ES-DE] **(Standalone)** [W],<br>Supermodel **(Standalone)** [UW],<br>Supermodel [Fullscreen] **(Standalone)** [UW],<br>_Shortcut or script_ | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide |
| arcadia | Emerson Arcadia 2001 | MAME **(Standalone)** | | No | Single archive or ROM file | | arcadia | Emerson Arcadia 2001 | MAME **(Standalone)** | | No | Single archive or ROM file |
| arduboy | Arduboy Miniature Game System | Arduous | | No | Single archive or .hex file | | arduboy | Arduboy Miniature Game System | Arduous | | No | Single archive or .hex file |
| astrocde | Bally Astrocade | MAME - Current | MAME **(Standalone)** | | See the specific _Bally Astrocade_ section elsewhere in this guide | | astrocde | Bally Astrocade | MAME - Current | MAME **(Standalone)** | Yes | See the specific _Bally Astrocade_ section elsewhere in this guide |
| atari2600 | Atari 2600 | Stella | Stella 2014,<br>Stella **(Standalone)**,<br>Gopher2600 **(Standalone)** [UW],<br>ares **(Standalone)** | No | Single archive or ROM file | | atari2600 | Atari 2600 | Stella | Stella 2014,<br>Stella **(Standalone)**,<br>Gopher2600 **(Standalone)** [UW],<br>ares **(Standalone)** | No | Single archive or ROM file |
| atari5200 | Atari 5200 | a5200 | Atari800,<br>Atari800 **(Standalone)** | Yes | Single archive or ROM file | | atari5200 | Atari 5200 | a5200 | Atari800,<br>Atari800 **(Standalone)** | Yes | Single archive or ROM file |
| atari7800 | Atari 7800 ProSystem | ProSystem | | Yes | Single archive or ROM file | | atari7800 | Atari 7800 ProSystem | ProSystem | | Yes | Single archive or ROM file |
@ -3071,7 +3171,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| bbcmicro | Acorn Computers BBC Micro | MAME **(Standalone)** | | Yes | Single archive or diskette image file | | bbcmicro | Acorn Computers BBC Micro | MAME **(Standalone)** | | Yes | Single archive or diskette image file |
| c64 | Commodore 64 | VICE x64sc Accurate | VICE x64sc Accurate **(Standalone)**,<br>VICE x64 Fast,<br>VICE x64 SuperCPU,<br>VICE x128,<br>Frodo | No | Single archive or image file for tape, cartridge or single-diskette games, .m3u playlist for multi-diskette games | | c64 | Commodore 64 | VICE x64sc Accurate | VICE x64sc Accurate **(Standalone)**,<br>VICE x64 Fast,<br>VICE x64 SuperCPU,<br>VICE x128,<br>Frodo | No | Single archive or image file for tape, cartridge or single-diskette games, .m3u playlist for multi-diskette games |
| cavestory | Cave Story (NXEngine) | NXEngine | | | | | cavestory | Cave Story (NXEngine) | NXEngine | | | |
| cdimono1 | Philips CD-i | SAME CDi | CDi 2015 | Yes | Single .bin/.cue pair | | cdimono1 | Philips CD-i | SAME CDi | CDi 2015,<br>MAME **(Standalone)** | Yes | Single .bin/.cue pair |
| cdtv | Commodore CDTV | PUAE | PUAE 2021 | Yes | | | cdtv | Commodore CDTV | PUAE | PUAE 2021 | Yes | |
| chailove | ChaiLove Game Engine | ChaiLove | | | | | chailove | ChaiLove Game Engine | ChaiLove | | | |
| channelf | Fairchild Channel F | FreeChaF | | | | | channelf | Fairchild Channel F | FreeChaF | | | |
@ -3083,12 +3183,13 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| cps3 | Capcom Play System III | MAME - Current | MAME 2010,<br>MAME 2003-Plus,<br>MAME 2000,<br>MAME **(Standalone)**,<br>FinalBurn Neo,<br>FinalBurn Neo **(Standalone)** [UW],<br>FB Alpha 2012,<br>FB Alpha 2012 CPS-3 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | | cps3 | Capcom Play System III | MAME - Current | MAME 2010,<br>MAME 2003-Plus,<br>MAME 2000,<br>MAME **(Standalone)**,<br>FinalBurn Neo,<br>FinalBurn Neo **(Standalone)** [UW],<br>FB Alpha 2012,<br>FB Alpha 2012 CPS-3 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide |
| crvision | VTech CreatiVision | MAME **(Standalone)** | | Yes | Single archive or ROM file | | crvision | VTech CreatiVision | MAME **(Standalone)** | | Yes | Single archive or ROM file |
| daphne | Daphne Arcade LaserDisc Emulator | Hypseus [Daphne] **(Standalone)** [UW] | Hypseus [Singe] **(Standalone)** [UW] | Yes for Daphne games | See the specific _Hypseus Singe (Daphne)_ section elsewhere in this guide | | daphne | Daphne Arcade LaserDisc Emulator | Hypseus [Daphne] **(Standalone)** [UW] | Hypseus [Singe] **(Standalone)** [UW] | Yes for Daphne games | See the specific _Hypseus Singe (Daphne)_ section elsewhere in this guide |
| desktop | Desktop Applications | _Suspend ES-DE_ | _Keep ES-DE running_ | | See the specific _Ports and desktop applications_ section elsewhere in this guide | | desktop | Desktop Applications | _Suspend ES-DE_ | _Keep ES-DE running_,<br>_AppImage (Suspend ES-DE)_ [U],<br>_AppImage (Keep ES-DE running)_ [U] | No | See the specific _Ports and desktop applications_ section elsewhere in this guide |
| doom | Doom | PrBoom | PrBoom+ **(Standalone)**,<br>Boom 3 [UW],<br>Boom 3 xp [UW],<br>_Shortcut or script_ | No | | | doom | Doom | PrBoom | PrBoom+ **(Standalone)**,<br>Boom 3 [UW],<br>Boom 3 xp [UW],<br>_Shortcut or script_ | No | |
| dos | DOS (PC) | DOSBox-Pure | DOSBox-Core,<br>DOSBox-SVN,<br>DOSBox-X **(Standalone)**,<br>DOSBox Staging **(Standalone)** | No | See the specific _DOS / PC_ section elsewhere in this guide | | dos | DOS (PC) | DOSBox-Pure | DOSBox-Core,<br>DOSBox-SVN,<br>DOSBox-X **(Standalone)**,<br>DOSBox Staging **(Standalone)** | No | See the specific _DOS / PC_ section elsewhere in this guide |
| dragon32 | Dragon Data Dragon 32 | XRoar Dragon 32 **(Standalone)** | XRoar Dragon 64 **(Standalone)** | Yes | See the specific _Dragon 32 and Tano Dragon_ section elsewhere in this guide | | dragon32 | Dragon Data Dragon 32 | XRoar Dragon 32 **(Standalone)** | XRoar Dragon 64 **(Standalone)** | Yes | See the specific _Dragon 32 and Tano Dragon_ section elsewhere in this guide |
| dreamcast | Sega Dreamcast | Flycast | Flycast **(Standalone)**,<br>Redream **(Standalone)** | No | In separate folder interpreted as a file, with .m3u playlist if multi-disc game | | dreamcast | Sega Dreamcast | Flycast | Flycast **(Standalone)**,<br>Redream **(Standalone)** | No | In separate folder interpreted as a file, with .m3u playlist if multi-disc game |
| easyrpg | EasyRPG Game Engine | EasyRPG | EasyRPG Player **(Standalone)** | No | See the specific _EasyRPG Game Engine_ section elsewhere in this guide | | easyrpg | EasyRPG Game Engine | EasyRPG | EasyRPG Player **(Standalone)** | No | See the specific _EasyRPG Game Engine_ section elsewhere in this guide |
| emulators | Emulators | _Suspend ES-DE_ | _Keep ES-DE running_,<br>_AppImage (Suspend ES-DE)_ [U],<br>_AppImage (Keep ES-DE running)_ [U] | No | See the specific _Ports and desktop applications_ section elsewhere in this guide |
| epic | Epic Games Store | Epic Games Store **(Standalone)** | | No | Shortcut (.desktop/.app/.lnk) file | | epic | Epic Games Store | Epic Games Store **(Standalone)** | | No | Shortcut (.desktop/.app/.lnk) file |
| famicom | Nintendo Family Computer | Mesen | Nestopia UE,<br>Nestopia UE **(Standalone)** [U],<br>FCEUmm,<br>QuickNES,<br>puNES **(Standalone)** [UW],<br>Mednafen **(Standalone)**,<br>ares **(Standalone)**,<br>ares FDS **(Standalone)** | No | Single archive or ROM file | | famicom | Nintendo Family Computer | Mesen | Nestopia UE,<br>Nestopia UE **(Standalone)** [U],<br>FCEUmm,<br>QuickNES,<br>puNES **(Standalone)** [UW],<br>Mednafen **(Standalone)**,<br>ares **(Standalone)**,<br>ares FDS **(Standalone)** | No | Single archive or ROM file |
| fba | FinalBurn Alpha | FB Alpha 2012 | FB Alpha 2012 Neo Geo,<br>FB Alpha 2012 CPS-1,<br>FB Alpha 2012 CPS-2,<br>FB Alpha 2012 CPS-3 | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | | fba | FinalBurn Alpha | FB Alpha 2012 | FB Alpha 2012 Neo Geo,<br>FB Alpha 2012 CPS-1,<br>FB Alpha 2012 CPS-2,<br>FB Alpha 2012 CPS-3 | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide |
@ -3096,6 +3197,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| fds | Nintendo Famicom Disk System | Mesen | Nestopia UE,<br>Nestopia UE **(Standalone)** [U],<br>FCEUmm,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | Yes | Single archive or ROM file | | fds | Nintendo Famicom Disk System | Mesen | Nestopia UE,<br>Nestopia UE **(Standalone)** [U],<br>FCEUmm,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | Yes | Single archive or ROM file |
| flash | Adobe Flash | Ruffle **(Standalone)** | Lightspark **(Standalone)** [U],<br>ArcadeFlashWeb **(Standalone)** [W] | No | Single .swf file | | flash | Adobe Flash | Ruffle **(Standalone)** | Lightspark **(Standalone)** [U],<br>ArcadeFlashWeb **(Standalone)** [W] | No | Single .swf file |
| fmtowns | Fujitsu FM Towns | Tsugaru **(Standalone)** [UW] | | Yes | See the specific _Fujitsu FM Towns_ section elsewhere in this guide | | fmtowns | Fujitsu FM Towns | Tsugaru **(Standalone)** [UW] | | Yes | See the specific _Fujitsu FM Towns_ section elsewhere in this guide |
| fpinball | Future Pinball | Future Pinball **(Standalone)** [W] | | No | |
| gameandwatch | Nintendo Game and Watch | MAME Local Artwork **(Standalone)** | MAME **(Standalone)**,<br>Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | | gameandwatch | Nintendo Game and Watch | MAME Local Artwork **(Standalone)** | MAME **(Standalone)**,<br>Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide |
| gamecom | Tiger Electronics Game.com | MAME **(Standalone)** | | Yes | Single archive or ROM file | | gamecom | Tiger Electronics Game.com | MAME **(Standalone)** | | Yes | Single archive or ROM file |
| gamegear | Sega Game Gear | Genesis Plus GX | Genesis Plus GX Wide,<br>Gearsystem,<br>SMS Plus GX,<br>PicoDrive,<br>Mednafen **(Standalone)** | | | | gamegear | Sega Game Gear | Genesis Plus GX | Genesis Plus GX Wide,<br>Gearsystem,<br>SMS Plus GX,<br>PicoDrive,<br>Mednafen **(Standalone)** | | |
@ -3104,11 +3206,13 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| gbc | Nintendo Game Boy Color | Gambatte | SameBoy,<br>SameBoy **(Standalone)**,<br>Gearboy,<br>Gearboy **(Standalone)** [UW],<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | No | Single archive or ROM file | | gbc | Nintendo Game Boy Color | Gambatte | SameBoy,<br>SameBoy **(Standalone)**,<br>Gearboy,<br>Gearboy **(Standalone)** [UW],<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | No | Single archive or ROM file |
| gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)**,<br>PrimeHack **(Standalone)** [UW],<br>Triforce **(Standalone)** [UW] | No | Disc image file for single-disc games, .m3u playlist for multi-disc games | | gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)**,<br>PrimeHack **(Standalone)** [UW],<br>Triforce **(Standalone)** [UW] | No | Disc image file for single-disc games, .m3u playlist for multi-disc games |
| genesis | Sega Genesis | Genesis Plus GX | Genesis Plus GX Wide,<br>PicoDrive,<br>BlastEm,<br>BlastEm **(Standalone)** [U],<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file | | genesis | Sega Genesis | Genesis Plus GX | Genesis Plus GX Wide,<br>PicoDrive,<br>BlastEm,<br>BlastEm **(Standalone)** [U],<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file |
| gmaster | Hartung Game Master | MAME **(Standalone)** | | Yes | Single archive or ROM file |
| gx4000 | Amstrad GX4000 | Caprice32 | CrocoDS,<br>MAME **(Standalone)** | No | Single archive or ROM file | | gx4000 | Amstrad GX4000 | Caprice32 | CrocoDS,<br>MAME **(Standalone)** | No | Single archive or ROM file |
| intellivision | Mattel Electronics Intellivision | FreeIntv | | | | | intellivision | Mattel Electronics Intellivision | FreeIntv | | | |
| j2me | Java 2 Micro Edition (J2ME) | SquirrelJME | KEmulator **(Standalone)** [W] | No | Single .jar file | | j2me | Java 2 Micro Edition (J2ME) | SquirrelJME | KEmulator **(Standalone)** [W] | No | Single .jar file |
| kodi | Kodi Home Theatre Software | Kodi **(Standalone)** | | No | Shortcut (.desktop/.app/.lnk) file | | kodi | Kodi Home Theatre Software | Kodi **(Standalone)** | | No | Shortcut (.desktop/.app/.lnk) file |
| lcdgames | LCD Handheld Games | MAME Local Artwork **(Standalone)** | MAME **(Standalone)**,<br>Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | | lcdgames | LCD Handheld Games | MAME Local Artwork **(Standalone)** | MAME **(Standalone)**,<br>Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide |
| lowresnx | LowRes NX Fantasy Console | LowRes NX | | No | Single ROM file |
| lutris | Lutris Open Gaming Platform | Lutris **(Standalone)** [U] | | No | See the specific _Lutris_ section elsewhere in this guide | | lutris | Lutris Open Gaming Platform | Lutris **(Standalone)** [U] | | No | See the specific _Lutris_ section elsewhere in this guide |
| lutro | Lutro Game Engine | Lutro | | | | | lutro | Lutro Game Engine | Lutro | | | |
| macintosh | Apple Macintosh | MAME Mac SE Bootable **(Standalone)** | MAME Mac SE Boot Disk **(Standalone)**,<br>MAME Mac Plus Bootable **(Standalone)**,<br>MAME Mac Plus Boot Disk **(Standalone)**,<br>Basilisk II **(Standalone)**,<br>SheepShaver **(Standalone)** | Yes | See the specific _Apple Macintosh_ section elsewhere in this guide | | macintosh | Apple Macintosh | MAME Mac SE Bootable **(Standalone)** | MAME Mac SE Boot Disk **(Standalone)**,<br>MAME Mac Plus Bootable **(Standalone)**,<br>MAME Mac Plus Boot Disk **(Standalone)**,<br>Basilisk II **(Standalone)**,<br>SheepShaver **(Standalone)** | Yes | See the specific _Apple Macintosh_ section elsewhere in this guide |
@ -3136,7 +3240,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| naomigd | Sega NAOMI GD-ROM | Flycast | Flycast **(Standalone)** | | | | naomigd | Sega NAOMI GD-ROM | Flycast | Flycast **(Standalone)** | | |
| n3ds | Nintendo 3DS | Citra [UW],<br>Citra **(Standalone)** [M] | Citra 2018 [UW],<br>Citra **(Standalone)** [UW] | No | Single ROM file | | n3ds | Nintendo 3DS | Citra [UW],<br>Citra **(Standalone)** [M] | Citra 2018 [UW],<br>Citra **(Standalone)** [UW] | No | Single ROM file |
| n64 | Nintendo 64 | Mupen64Plus-Next | Mupen64Plus **(Standalone)**,<br>ParaLLEl N64,<br>simple64 **(Standalone)** [UW],<br>Rosalie's Mupen GUI **(Standalone)** [UW],<br>Project64 **(Standalone)** [W],<br>ares **(Standalone)**,<br>sixtyforce **(Standalone)** [M] | No | Single archive or ROM file | | n64 | Nintendo 64 | Mupen64Plus-Next | Mupen64Plus **(Standalone)**,<br>ParaLLEl N64,<br>simple64 **(Standalone)** [UW],<br>Rosalie's Mupen GUI **(Standalone)** [UW],<br>Project64 **(Standalone)** [W],<br>ares **(Standalone)**,<br>sixtyforce **(Standalone)** [M] | No | Single archive or ROM file |
| n64dd | Nintendo 64DD | ParaLLEl N64 [UW],<br>Mupen64Plus-Next [M] | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M],<br>Rosalie's Mupen GUI **(Standalone)** [UW] | Yes | See the specific _Nintendo 64DD_ section elsewhere in this guide | | n64dd | Nintendo 64DD | ParaLLEl N64 [UW],<br>Mupen64Plus-Next [M] | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M],<br>Rosalie's Mupen GUI **(Standalone)** [UW],<br>ares **(Standalone)** | Yes | See the specific _Nintendo 64DD_ section elsewhere in this guide |
| nds | Nintendo DS | DeSmuME | DeSmuME 2015,<br>DeSmuME **(Standalone)** [U],<br>melonDS,<br>melonDS **(Standalone)** | No | Single archive or ROM file | | nds | Nintendo DS | DeSmuME | DeSmuME 2015,<br>DeSmuME **(Standalone)** [U],<br>melonDS,<br>melonDS **(Standalone)** | No | Single archive or ROM file |
| neogeo | SNK Neo Geo | FinalBurn Neo | FinalBurn Neo **(Standalone)** [UW],<br>MAME **(Standalone)** | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | | neogeo | SNK Neo Geo | FinalBurn Neo | FinalBurn Neo **(Standalone)** [UW],<br>MAME **(Standalone)** | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide |
| neogeocd | SNK Neo Geo CD | NeoCD | FinalBurn Neo,<br>FinalBurn Neo **(Standalone)** [U],<br>MAME **(Standalone)** | Yes | .chd (NeoCD and MAME only) or .cue file | | neogeocd | SNK Neo Geo CD | NeoCD | FinalBurn Neo,<br>FinalBurn Neo **(Standalone)** [U],<br>MAME **(Standalone)** | Yes | .chd (NeoCD and MAME only) or .cue file |
@ -3156,7 +3260,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| pcfx | NEC PC-FX | Beetle PC-FX | Mednafen **(Standalone)** | Yes | | | pcfx | NEC PC-FX | Beetle PC-FX | Mednafen **(Standalone)** | Yes | |
| pico8 | PICO-8 Fantasy Console | PICO-8 **(Standalone)** | PICO-8 Splore **(Standalone)** | No | See the specific _PICO-8_ section elsewhere in this guide | | pico8 | PICO-8 Fantasy Console | PICO-8 **(Standalone)** | PICO-8 Splore **(Standalone)** | No | See the specific _PICO-8_ section elsewhere in this guide |
| pokemini | Nintendo Pokémon Mini | PokeMini | | No | | | pokemini | Nintendo Pokémon Mini | PokeMini | | No | |
| ports | Ports | _Various_ | | No | See the specific _Ports and desktop applications_ section elsewhere in this guide | | ports | Ports | _Shortcut or script_ | _AppImage_ [U] | No | See the specific _Ports and desktop applications_ section elsewhere in this guide |
| ps2 | Sony PlayStation 2 | LRPS2 [UW],<br>PCSX2 **(Standalone)** [M] | PCSX2 [UW] @,<br>PCSX2 **(Standalone)** [UW],<br>PCSX2 Legacy **(Standalone)** @,<br>Play! **(Standalone)**,<br>AetherSX2 **(Standalone)** [M] | Yes except for Play! | | | ps2 | Sony PlayStation 2 | LRPS2 [UW],<br>PCSX2 **(Standalone)** [M] | PCSX2 [UW] @,<br>PCSX2 **(Standalone)** [UW],<br>PCSX2 Legacy **(Standalone)** @,<br>Play! **(Standalone)**,<br>AetherSX2 **(Standalone)** [M] | Yes except for Play! | |
| ps3 | Sony PlayStation 3 | RPCS3 Shortcut **(Standalone)** | RPCS3 Directory **(Standalone)** | Yes | See the specific _Sony PlayStation 3_ section elsewhere in this guide | | ps3 | Sony PlayStation 3 | RPCS3 Shortcut **(Standalone)** | RPCS3 Directory **(Standalone)** | Yes | See the specific _Sony PlayStation 3_ section elsewhere in this guide |
| ps4 | Sony PlayStation 4 | _Placeholder_ | | | | | ps4 | Sony PlayStation 4 | _Placeholder_ | | | |
@ -3170,13 +3274,14 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| saturn | Sega Saturn | Beetle Saturn | Kronos [UW],<br>YabaSanshiro [UW],<br>Yabause,<br>Mednafen **(Standalone)**,<br>SSF **(Standalone)** [W] | Yes | In separate folder interpreted as a file, with .m3u playlist if multi-disc game | | saturn | Sega Saturn | Beetle Saturn | Kronos [UW],<br>YabaSanshiro [UW],<br>Yabause,<br>Mednafen **(Standalone)**,<br>SSF **(Standalone)** [W] | Yes | In separate folder interpreted as a file, with .m3u playlist if multi-disc game |
| saturnjp | Sega Saturn [Japan] | Beetle Saturn | Kronos [UW],<br>YabaSanshiro [UW],<br>Yabause,<br>Mednafen **(Standalone)**,<br>SSF **(Standalone)** [W] | Yes | In separate folder interpreted as a file, with .m3u playlist if multi-disc game | | saturnjp | Sega Saturn [Japan] | Beetle Saturn | Kronos [UW],<br>YabaSanshiro [UW],<br>Yabause,<br>Mednafen **(Standalone)**,<br>SSF **(Standalone)** [W] | Yes | In separate folder interpreted as a file, with .m3u playlist if multi-disc game |
| scummvm | ScummVM Game Engine | ScummVM | ScummVM **(Standalone)** | No | See the specific _ScummVM_ section elsewhere in this guide | | scummvm | ScummVM Game Engine | ScummVM | ScummVM **(Standalone)** | No | See the specific _ScummVM_ section elsewhere in this guide |
| scv | Epoch Super Cassette Vision | MAME **(Standalone)** | | Yes | Single archive or ROM file |
| sega32x | Sega Mega Drive 32X | PicoDrive | ares **(Standalone)** | No | Single archive or ROM file | | sega32x | Sega Mega Drive 32X | PicoDrive | ares **(Standalone)** | No | Single archive or ROM file |
| sega32xjp | Sega Super 32X [Japan] | PicoDrive | ares **(Standalone)** | No | Single archive or ROM file | | sega32xjp | Sega Super 32X [Japan] | PicoDrive | ares **(Standalone)** | No | Single archive or ROM file |
| sega32xna | Sega Genesis 32X [North America] | PicoDrive | ares **(Standalone)** | No | Single archive or ROM file | | sega32xna | Sega Genesis 32X [North America] | PicoDrive | ares **(Standalone)** | No | Single archive or ROM file |
| segacd | Sega CD | Genesis Plus GX | Genesis Plus GX Wide,<br>PicoDrive,<br>ares **(Standalone)** | Yes | | | segacd | Sega CD | Genesis Plus GX | Genesis Plus GX Wide,<br>PicoDrive,<br>ares **(Standalone)** | Yes | |
| sfc | Nintendo SFC (Super Famicom) | Snes9x - Current | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file | | sfc | Nintendo SFC (Super Famicom) | Snes9x - Current | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file |
| sg-1000 | Sega SG-1000 | Genesis Plus GX | Genesis Plus GX Wide,<br>Gearsystem,<br>blueMSX,<br>ares **(Standalone)** | No | | | sg-1000 | Sega SG-1000 | Genesis Plus GX | Genesis Plus GX Wide,<br>Gearsystem,<br>blueMSX,<br>ares **(Standalone)** | No | |
| sgb | Nintendo Super Game Boy | Mesen-S | mGBA,<br>mGBA **(Standalone)** | | Single archive or ROM file | | sgb | Nintendo Super Game Boy | Mesen-S | SameBoy,<br>mGBA,<br>mGBA **(Standalone)** | | Single archive or ROM file |
| snes | Nintendo SNES (Super Nintendo) | Snes9x - Current | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file | | snes | Nintendo SNES (Super Nintendo) | Snes9x - Current | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file |
| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file | | snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file |
| solarus | Solarus Game Engine | Solarus **(Standalone)** | | No | Single .solarus game file | | solarus | Solarus Game Engine | Solarus **(Standalone)** | | No | Single .solarus game file |
@ -3200,15 +3305,16 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| vic20 | Commodore VIC-20 | VICE xvic | VICE xvic **(Standalone)** | No | Single archive or tape, cartridge or diskette image file | | vic20 | Commodore VIC-20 | VICE xvic | VICE xvic **(Standalone)** | No | Single archive or tape, cartridge or diskette image file |
| videopac | Philips Videopac G7000 | O2EM | | | | | videopac | Philips Videopac G7000 | O2EM | | | |
| virtualboy | Nintendo Virtual Boy | Beetle VB | Mednafen **(Standalone)** | No | | | virtualboy | Nintendo Virtual Boy | Beetle VB | Mednafen **(Standalone)** | No | |
| vpinball | Visual Pinball | Visual Pinball **(Standalone)** [W] | | No | |
| vsmile | VTech V.Smile | MAME **(Standalone)** | | Yes | Single archive or ROM file | | vsmile | VTech V.Smile | MAME **(Standalone)** | | Yes | Single archive or ROM file |
| wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file | | wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file |
| wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,<br>PrimeHack **(Standalone)** [UW] | No | | | wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,<br>PrimeHack **(Standalone)** [UW] | No | |
| wiiu | Nintendo Wii U | Cemu **(Standalone)** | | No | See the specific _Nintendo Wii U_ section elsewhere in this guide | | wiiu | Nintendo Wii U | Cemu **(Standalone)** | | No | See the specific _Nintendo Wii U_ section elsewhere in this guide |
| windows | Microsoft Windows | _Suspend ES-DE_ | _Keep ES-DE running_ | | Shortcut (.desktop/.app/.lnk) file or script | | windows | Microsoft Windows | _Suspend ES-DE_ | _Keep ES-DE running_,<br>_AppImage (Suspend ES-DE)_ [U],<br>_AppImage (Keep ES-DE running)_ [U] | No | Shortcut (.desktop/.app/.lnk) file, script or AppImage |
| wonderswan | Bandai WonderSwan | Beetle Cygne | Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | | | wonderswan | Bandai WonderSwan | Beetle Cygne | Mednafen **(Standalone)**,<br>ares **(Standalone)**,<br>ares [Benesse Pocket Challenge V2] **(Standalone)** | No | Single archive or ROM file |
| wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | | | wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | Mednafen **(Standalone)**,<br>ares **(Standalone)** | No | Single archive or ROM file |
| x1 | Sharp X1 | x1 | | | Single archive or ROM file | | x1 | Sharp X1 | x1 | | | Single archive or ROM file |
| x68000 | Sharp X68000 | PX68k | | Yes | | | x68000 | Sharp X68000 | PX68k | MAME **(Standalone)** | Yes | |
| xbox | Microsoft Xbox | xemu **(Standalone)** | Cxbx-Reloaded **(Standalone)** [W] | Yes for xemu | Single .iso file for xemu or unpacked .iso directory for Cxbx-Reloaded | | xbox | Microsoft Xbox | xemu **(Standalone)** | Cxbx-Reloaded **(Standalone)** [W] | Yes for xemu | Single .iso file for xemu or unpacked .iso directory for Cxbx-Reloaded |
| xbox360 | Microsoft Xbox 360 | xenia **(Standalone)** [W] | | No | | | xbox360 | Microsoft Xbox 360 | xenia **(Standalone)** [W] | | No | |
| zmachine | Infocom Z-machine | Gargoyle **(Standalone)** | | No | | | zmachine | Infocom Z-machine | Gargoyle **(Standalone)** | | No | |