diff --git a/CHANGELOG.md b/CHANGELOG.md index 4872c045d..9e0bad016 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,17 @@ # ES-DE (EmulationStation Desktop Edition) - Changelog -## Version 3.0.0 (in development) +## Version 3.0.0 -**Release date:** TBD +**Release date:** 2024-02-17 ### Release overview +The 3.0 release rebrands the application from EmulationStation Desktop Edition to simply ES-DE. And as part of this the application data directory has changed from .emulationstation to ES-DE and its internal structure has been improved. There is also a new default theme named Linear that is bundled with the application. + +Support for configurable font sizes has also been added, so assuming the theme supports it, it's now possible to select between these sizes from the _UI settings_ menu. + +A number of minor improvements and bug fixes are also part of this release. + ### Detailed list of changes * Renamed the application from EmulationStation Desktop Edition to ES-DE @@ -22,7 +28,7 @@ * Changed the custom slideshow image directory setting from ScreensaverSlideshowImageDir to ScreensaverSlideshowCustomDir * The HTTP error code will now be shown on scraper errors instead of the "File is smaller than 350 bytes" message * Removed the ScraperHaltOnInvalidMedia option and corresponding menu entry as it has been superseded by the HTTP error code logic -* Added a ScraperIgnoreHTTP404Errors option that can be manually set in es_settings.xml to ignore 404 errors (resource not found) +* Added a ScraperIgnoreHTTP404Errors option that can be manually set in es_settings.xml to ignore 404 errors (i.e. resource not found) * Added Mednafen standalone as an alternative emulator for the gb, gba, gbc and supergrafx systems * Added Mesen standalone as an alternative emulator for the gamegear, mastersystem and multivision systems on Linux, Unix and Windows * Added Mesen standalone as an alternative emulator for the sg-1000 and supergrafx systems on Linux, Unix and Windows @@ -58,6 +64,8 @@ * The relevant SDL error message is now printed to the log if a controller could not be added * Added rendering workarounds for some mobile GPUs which do not support all OpenGL operations when using the BGRA pixel format * Added the UTF8-CPP library as a dependency +* Updated SDL to 2.30.0 on Windows, macOS and the Linux AppImage builds +* Bundled the December 2023 release of the Mozilla TLS/SSL certificates ### Bug fixes diff --git a/FAQ.md b/FAQ.md index 922d4a0c6..594b8ac05 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,20 +1,16 @@ # ES-DE (EmulationStation Desktop Edition) - Frequently Asked Questions -## What is this project and how is it related to other EmulationStation forks? +## What's the correct name for the application? ES-DE, EmulationStation etc? -This project started in 2020 as a fork of RetroPie EmulationStation and it has been in very active development ever since. Large parts of the application have been rewritten and much functionality has been added, so overall it's a quite different application by now. - -## What's the correct name? EmulationStation, ES-DE, Emulation Station, EmuStation etc? - -The correct name is EmulationStation Desktop Edition, which is for practical reasons often shortened to EmulationStation-DE or more commonly ES-DE. It's not spelled Emulation Station (i.e. two separate words) in the same manner as you don't write Sony Play Station or Nintendo Game Cube. +As of the 3.0.0 release the official name for the project and application is ES-DE or sometimes ES-DE Frontend. This stands for EmulationStation Desktop Edition as the project originated from the RetroPie fork of EmulationStation in 2020, and was originally intended for desktop computers. However the application has now changed so much that it would just cause confusion to keep the EmulationStation name. During a transition period EmulationStation Desktop Edition will be included as a subtitle on the splash screen and mentioned in some documentation entries, but long term this will be dropped entirely. The red version of the EmulationStation logo will however remain as it's part of the application legacy. ## Is this software available for free, and is it open source? -ES-DE is available for free. Voluntary donations to support the project are however very welcome. The application is released under the MIT open source license with the source code readily available to anyone via the project's [GitLab site](https://gitlab.com/es-de/emulationstation-de). +ES-DE is available for free on Windows, macOS and Linux and it's released under the MIT open source license. ## Which operating systems are supported? -ES-DE runs on Windows, macOS and BSD Unix as well as on multiple Linux distributions including Ubuntu, Fedora, Arch, Manjaro, SteamOS etc. +ES-DE runs on Windows, macOS and multiple Linux distributions including Ubuntu, Fedora, Arch, Manjaro, SteamOS etc. ## What is the relationship between ES-DE and RetroDECK? @@ -22,7 +18,7 @@ ES-DE and [RetroDECK](http://retrodeck.net) are completely separate projects, bu ## What is the relationship between ES-DE and EmuDeck? -[EmuDeck](http://www.emudeck.com) is an installer that installs ES-DE and a number of emulators. There is no relationship between the two projects apart from this, and it's generally not recommended to use EmuDeck as this will lead to a non-standard installation. There are few tangible benefits to using EmuDeck over a manual installation apart from some convenience for the initial setup. Instead it's recommended to setup your emulators manually which will allow you to configure everything exactly to your liking. That is also a fun and interesting experience. +EmuDeck is an installer that installs ES-DE and a number of emulators. There is no relationship between the two projects apart from this, and it's not recommended to use EmuDeck as this will lead to a non-standard installation and can cause a lot of other issues as well. Instead it's recommended to setup your emulators manually which will allow you to configure everything exactly to your liking. ## What game systems/platforms and emulators are supported by ES-DE? @@ -34,7 +30,7 @@ Menus in ES-DE are not lists but grids, sometimes there is only a list but somet ## Can I change the system sorting to not sort by full system names? -Yes the systems sorting configuration file can be selected via the _Systems sorting_ option in the _UI Settings_ menu. There are four such files bundled with ES-DE to sort by _"Release year", "Manufacturer, release year", "Hardware type, release year"_ and _"Manufacturer, hardware type, release year"_. If you don't want to use any of the bundled files then you can create your own custom sorting file and place it into the ~/.emulationstation/custom_systems/ directory. More details about this setup can be found in the _es_systems_sorting.xml_ section of the [Building and advanced configuration](INSTALL.md#es_systems_sortingxml) document. +Yes the systems sorting configuration file can be selected via the _Systems sorting_ option in the _UI Settings_ menu. There are four such files bundled with ES-DE to sort by _"Release year", "Manufacturer, release year", "Hardware type, release year"_ and _"Manufacturer, hardware type, release year"_. If you don't want to use any of the bundled files then you can create your own custom sorting file and place it into the ~/ES-DE/custom_systems/ directory. More details about this setup can be found in the _es_systems_sorting.xml_ section of the [Building and advanced configuration](INSTALL.md#es_systems_sortingxml) document. ## I'm missing some systems like SNES MSU-1 and WiiWare, could those get added to ES-DE? @@ -46,7 +42,7 @@ ES-DE comes preconfigured with support for many alternative emulators, see the [ ## I'm on Windows and ES-DE can't find my emulators, what is wrong? -On Windows ES-DE is shipped as a portable installation and as a regular installer. If you're using the portable installation you need to drop your emulators inside the Emulators directory. Make sure to read the README.txt file directly in the EmulationStation-DE folder for more details. For the regular installer many emulators do not provide a method to inform ES-DE where they are installed, so you will need to add their installation directories to the Path environment variable in Windows. It's strongly recommended to read the _Specific notes for Windows_ section of the [User guide](USERGUIDE.md#specific-notes-for-windows) before attempting to setup and use ES-DE on Windows. +On Windows ES-DE is shipped as a portable installation and as a regular installer. If you're using the portable installation you need to drop your emulators inside the Emulators directory. Make sure to read the README.txt file directly in the ES-DE folder for more details. For the regular installer many emulators do not provide a method to inform ES-DE where they are installed, so you will need to add their installation directories to the Path environment variable in Windows. It's strongly recommended to read the _Specific notes for Windows_ section of the [User guide](USERGUIDE.md#specific-notes-for-windows) before attempting to setup and use ES-DE on Windows. ## I'm on Windows and ES-DE refuses to start, is the application broken? @@ -54,7 +50,7 @@ You're probably missing the OpenGL drivers required to run ES-DE. Try to downloa ## I'm on Windows and there is only a black screen shown on startup or when launching a game, is there a way to fix this? -This behavior has been observed for some specific AMD GPUs in the past. In some instances there is only a black screen on startup and in some instances the application starts and runs correctly but launching a game only shows a black screen. The issue is seemingly caused by GPU driver bugs and it only affects Windows as Linux works fine with the same hardware. The workaround is to make ES-DE run in windowed mode. You accomplish this by using the --resolution flag and setting the width to one pixel wider than your screen resolution. So if for instance running at a 1280x800 display resolution, run ES-DE such as this: `EmulationStation.exe --resolution 1281 800` +This behavior has been observed for some specific AMD GPUs in the past. In some instances there is only a black screen on startup and in some instances the application starts and runs correctly but launching a game only shows a black screen. The issue is seemingly caused by GPU driver bugs and it only affects Windows as Linux works fine with the same hardware. The workaround is to make ES-DE run in windowed mode. You accomplish this by using the --resolution flag and setting the width to one pixel wider than your screen resolution. So if for instance running at a 1280x800 display resolution, run ES-DE such as this: `ES-DE.exe --resolution 1281 800` ## The emulators don't seem to be properly configured? @@ -84,13 +80,9 @@ See the question above for a possible solution. Another approach would be to hid No, by default games are not removed from the gamelists when they are hidden and are instead only marked with a much lower opacity. You need to disable the setting _Show hidden games_ from the _Other Settings_ menu to make them disappear entirely. The reason this option is not disabled by default is that new users could very easily make a mistake by hiding some files accidentally without realizing it, only to have the entries being immediately removed from the gamelist view. It's also good practice to hide all your games with this option enabled and verify that it's all correct before going ahead and disabling it. -## I'm using Linux or macOS and I can't find the .emulationstation directory, where is it located? - -The .emulationstation directory is normally located in your home directory, but on these Unix-based operating systems files and directories starting with a dot are hidden by default. So you need to enable hidden files and directories in your file manager. On macOS this is done in Finder using the Shift + Command + . (a dot) keyboard combination. On Linux it depends on which file manager you're using, but in KDE's Dolphin it's accomplished by using the Alt + . (a dot) keyboard combination or via the corresponding entry in the hamburger menu. - ## I can't find a ROM directory setting in the user interface, so how do I relocate my games? -There is no need for such a setting as ES-DE will not start unless it finds at least one game. So you simply need to move your ROM directory to its new location using your operating system's file manager or terminal and then the next time you start ES-DE you will be shown a dialog where you can enter the new directory. Optionally you can manually change the ROMDirectory setting in ~/.emulationstation/es_settings.xml +There is no need for such a setting as ES-DE will not start unless it finds at least one game. So you simply need to move your ROM directory to its new location using your operating system's file manager or terminal and then the next time you start ES-DE you will be shown a dialog where you can enter the new directory. Optionally you can manually change the ROMDirectory setting in ~/ES-DE/es_settings.xml ## What are miximages precisely and why don't they get updated when I change my miximage settings? @@ -98,7 +90,7 @@ As the name implies these are images, and more specifically they are generated b ## Is there a way to customize existing systems, and/or to add more systems than those shipped by default? -Yes it's possible to both customize existing systems that are part of the bundled configuration as well as to add more systems than those shipped with ES-DE. Almost nothing is hardcoded in the application so there is a huge flexibility when it comes to such configuration. How this is done is covered in the _Game system customizations_ section of the [User guide](USERGUIDE.md#game-system-customizations). Just make sure to never modify the es_systems.xml and es_find_rules.xml files included in the application installation directory as these will be overwritten when upgrading ES-DE in the future. Always place your customizations in ~/.emulationstation/custom_systems/ as is also described in the user guide. +Yes it's possible to both customize existing systems that are part of the bundled configuration as well as to add more systems than those shipped with ES-DE. Almost nothing is hardcoded in the application so there is a huge flexibility when it comes to such configuration. How this is done is covered in the _Game system customizations_ section of the [User guide](USERGUIDE.md#game-system-customizations). Just make sure to never modify the es_systems.xml and es_find_rules.xml files included in the application installation directory as these will be overwritten when upgrading ES-DE in the future. Always place your customizations in ~/ES-DE/custom_systems/ as is also described in the user guide. ## Can I use the Steam release of RetroArch? @@ -110,7 +102,7 @@ You would normally use the built-in theme downloader to install additional theme ## I added some EmulationStation themes manually but they don't seem to show up inside ES-DE? -Only themes made specifically for ES-DE can be used. If you want to use a theme from Batocera, Recalbox, RetroBat, RetroPie etc. then it first needs to be ported to the ES-DE theme engine. If you place a non-supported theme in the ~/.emulationtation/themes/ directory then this will be ignored on startup, meaning it will not be selectable from the _UI Settings_ menu. +EmulationStation themes are not supported by ES-DE. If you want to use a theme from Batocera, Recalbox, RetroBat, RetroPie etc. then it first needs to be ported to the ES-DE theme engine. If you place a non-supported theme in the ES-DE/themes/ directory then this will be ignored on startup, meaning it will not be selectable from the _UI Settings_ menu. ## I used to be a Batocera/Recalbox user and ES-DE can't seem to find some of my games? @@ -122,15 +114,11 @@ There is a built-in application updater that works with the Linux AppImage relea ## I can't find any game media links in the gamelist.xml files, where is this data stored? -ES-DE works differently compared to all other EmulationStation forks when it comes to handling of game media. There are no links in the gamelist.xml files, instead media files are matched against the ROM/game file names which makes for a much simpler, faster and completely portable setup. Migrating game media from other EmulationStation forks (and potentially from other frontends as well) can be accomplished quite easily. See the next question below for more information. Make sure to also read the _Migrating from other EmulationStation forks_ section of the [User guide](USERGUIDE.md#migrating-from-other-emulationstation-forks) to avoid data loss if running ES-DE with existing data from another EmulationStation fork. +ES-DE works differently compared to EmulationStation when it comes to handling of game media. There are no links in the gamelist.xml files, instead media files are matched against the ROM/game file names which makes for a much simpler, faster and completely portable setup. Migrating game media from EmulationStation (and potentially from other frontends as well) can be accomplished quite easily. Make sure to also read the _Migrating from EmulationStation_ section of the [User guide](USERGUIDE.md#migrating-from-emulationstation) to avoid data loss if running ES-DE with existing data from EmulationStation. ## It seems like gamelist.xml files in the ROM directory tree are not getting loaded? -These files are not loaded by default as of ES-DE 2.0.0, only files placed in .emulationstation/gamelists/ are processed. If you insist on retaining the old logic of also looking for gamelist.xml files in the ROM directory tree then you can enable the LegacyGamelistFileLocation setting in es_settings.xml as explained in the _Settings not configurable via the GUI_ section of the [Building and advanced configuration](INSTALL.md#settings-not-configurable-via-the-gui) document. - -## Why do I sometimes get error messages when scraping stating that files are less than 350 bytes in size? - -This issue can occur occassionally as the ScreenScraper servers sometimes return invalid responses, in this case simply pressing the _RETRY_ button often works. But there is also a ScreenScraper bug where their cache could include entries that no longer exist. When a media file is removed from the ScreenScraper database, the cached link to that file is retained for some time and will be returned as a valid media file URL to ES-DE. However, when attempting to scrape such a file, it will only contain the text string _NOMEDIA_ which will trigger this error in ES-DE. The cache bug only affects the multi-scraper API call, so a workaround is to manually scrape such games using the single-game scraper (reachable via the metadata editor). The invalid cache entries seem to disappear within 24 hours so waiting for a while and rescraping should also resolve the problem. The issue has been reported to the ScreenScraper team but it's unclear if and when it will be resolved. +These files are not loaded by default, only files placed in ES-DE/gamelists/ are processed. If you insist on also looking for gamelist.xml files in the ROM directory tree then you can enable the LegacyGamelistFileLocation setting in es_settings.xml as explained in the _Settings not configurable via the GUI_ section of the [Building and advanced configuration](INSTALL.md#settings-not-configurable-via-the-gui) document. ## Can I use an external scraper application instead of the built-in scraper? diff --git a/INSTALL.md b/INSTALL.md index 31967beed..95c18a21f 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,4 +1,4 @@ -# ES-DE (EmulationStation Desktop Edition) v2.2 - Building and advanced configuration +# ES-DE (EmulationStation Desktop Edition) v3.0 - Building and advanced configuration Table of contents: @@ -160,7 +160,7 @@ make -j8 ``` Due to buggy AMD GPU drivers it could be a good idea to use the `LSAN_suppressions` file included in the repository to avoid reports of a lot of irrelevant issue, for example: ``` -LSAN_OPTIONS="suppressions=tools/LSAN_suppressions" ./emulationstation --debug --resolution 2560 1440 +LSAN_OPTIONS="suppressions=tools/LSAN_suppressions" ./es-de --debug --resolution 2560 1440 ``` This applies to LeakSanitizer specifically, which is integrated into AddressSanitizer. @@ -173,7 +173,7 @@ make -j8 It could also be a good idea to use the `TSAN_suppressions` file included in the repository to suppress issues reported by some third party libraries, for example: ``` -TSAN_OPTIONS="suppressions=tools/TSAN_suppressions" ./emulationstation --debug --resolution 2560 1440 +TSAN_OPTIONS="suppressions=tools/TSAN_suppressions" ./es-de --debug --resolution 2560 1440 ``` To enable UndefinedBehaviorSanitizer which helps with identifying bugs that may otherwise be hard to find, build with the UBSAN option: @@ -194,17 +194,17 @@ As for advanced debugging, Valgrind is a very powerful and useful tool which can The most common tool is Memcheck to check for memory leaks, which you run like this: ``` -valgrind --tool=memcheck --leak-check=full --log-file=../valgrind_run_01 ./emulationstation +valgrind --tool=memcheck --leak-check=full --log-file=../valgrind_run_01 ./es-de ``` There are numerous flags that can be used, for example this will also track reachable memory which could indicate further leaks: ``` -valgrind --tool=memcheck --leak-check=full --track-origins=yes --show-reachable=yes --log-file=../valgrind_run_01 ./emulationstation +valgrind --tool=memcheck --leak-check=full --track-origins=yes --show-reachable=yes --log-file=../valgrind_run_01 ./es-de ``` Another helpful tool is the Callgrind call-graph analyzer: ``` -valgrind --tool=callgrind --log-file=../valgrind_run_01 ./emulationstation +valgrind --tool=callgrind --log-file=../valgrind_run_01 ./es-de ``` The output file can be loaded into an application such as KCachegrind for data analysis. @@ -213,7 +213,7 @@ The output file can be loaded into an application such as KCachegrind for data a Yet another very useful Valgrind tool is the Massif heap profiler, which can be run like this: ``` -valgrind --tool=massif --massif-out-file=../massif.out.01 ./emulationstation +valgrind --tool=massif --massif-out-file=../massif.out.01 ./es-de ``` The output file can be loaded into an application such as Massif-Visualizer for analysis. @@ -301,35 +301,35 @@ sudo make install Assuming the default installation prefix /usr has been used, this is the directory structure for the installation: ``` -/usr/bin/emulationstation +/usr/bin/es-de /usr/bin/es-pdf-convert -/usr/share/applications/org.es_de.emulationstation-de.desktop -/usr/share/emulationstation/licenses/* -/usr/share/emulationstation/resources/* -/usr/share/emulationstation/themes/* -/usr/share/emulationstation/LICENSE -/usr/share/icons/hicolor/scalable/apps/org.es_de.emulationstation-de.svg -/usr/share/man/man6/emulationstation.6.gz -/usr/share/metainfo/org.es_de.emulationstation-de.appdata.xml -/usr/share/pixmaps/org.es_de.emulationstation-de.svg +/usr/share/applications/org.es_de.frontend.desktop +/usr/share/es-de/licenses/* +/usr/share/es-de/resources/* +/usr/share/es-de/themes/* +/usr/share/es-de/LICENSE +/usr/share/icons/hicolor/scalable/apps/org.es_de.frontend.svg +/usr/share/man/man6/es-de.6.gz +/usr/share/metainfo/org.es_de.frontend.appdata.xml +/usr/share/pixmaps/org.es_de.frontend.svg ``` However, when installing manually instead of building a package, it's recommended to change the install prefix to /usr/local instead of /usr. -Be aware that if using the GNOME desktop environment, /usr/share/pixmaps/emulationstation.svg must exist in order for the ES-DE icon to be shown in the Dash and task switcher. +Be aware that if using the GNOME desktop environment, /usr/share/pixmaps/org.es_de.frontend.svg must exist in order for the ES-DE icon to be shown in the Dash and task switcher. ES-DE will look in the following locations for application resources, in the listed order: -* \/.emulationstation/resources/ -* \/share/emulationstation/resources/ +* \/ES-DE/resources/ +* \/share/es-de/resources/ * \/resources/ The resources directory is critical, without it the application won't start. As well the following locations will be searched for themes, also in the listed order: -* \/.emulationstation/themes/ -* \/share/emulationstation/themes/ +* \/ES-DE/themes/ +* \/share/es-de/themes/ * \/themes/ A theme is not mandatory to start the application, but ES-DE will be basically useless without it. @@ -344,23 +344,23 @@ Creation of Debian .deb packages is enabled by default, simply run `cpack` to ge myusername@computer:~/emulationstation-de$ cpack CPack: Create package using DEB CPack: Install projects -CPack: - Run preinstall target for: emulationstation-de -CPack: - Install project: emulationstation-de [] +CPack: - Run preinstall target for: es-de +CPack: - Install project: es-de [] CPack: Create package CPackDeb: - Generating dependency list -CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-2.2.0-x64.deb generated. +CPack: - package: /home/myusername/emulationstation-de/es-de_3.0.0-x64.deb generated. ``` You may want to check that the dependencies look fine, as they're (mostly) automatically generated by CMake: ``` -dpkg -I ./emulationstation-de-2.2.0-x64.deb +dpkg -I ./es-de_3.0.0-x64.deb ``` The package can now be installed using a package manager, for example apt: ``` -sudo apt install ./emulationstation-de-2.2.0-x64.deb +sudo apt install ./es-de_3.0.0-x64.deb ``` To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example: @@ -375,11 +375,11 @@ Then simply run `cpack`: myusername@computer:~/emulationstation-de$ cpack CPack: Create package using RPM CPack: Install projects -CPack: - Run preinstall target for: emulationstation-de -CPack: - Install project: emulationstation-de [] +CPack: - Run preinstall target for: es-de +CPack: - Install project: es-de [] CPack: Create package -CPackRPM: Will use GENERATED spec file: /home/myusername/emulationstation-de/_CPack_Packages/Linux/RPM/SPECS/emulationstation-de.spec -CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-2.2.0-x64.rpm generated. +CPackRPM: Will use GENERATED spec file: /home/myusername/emulationstation-de/_CPack_Packages/Linux/RPM/SPECS/es-de.spec +CPack: - package: /home/myusername/emulationstation-de/es-de_3.0.0-x64.rpm generated ``` On Fedora, you need to install rpmbuild before this command can be run: @@ -389,17 +389,17 @@ sudo dnf install rpm-build After the package generation you can check that the metadata looks fine using the `rpm` command: ``` -rpm -qi ./emulationstation-de-2.2.0-x64.rpm +rpm -qi ./es-de_3.0.0-x64.rpm ``` To see the automatically generated dependencies, run this: ``` -rpm -q --requires ./emulationstation-de-2.2.0-x64.rpm +rpm -q --requires ./es-de_3.0.0-x64.rpm ``` And of course, you can also install the package: ``` -sudo dnf install ./emulationstation-de-2.2.0-x64.rpm +sudo dnf install ./es-de_3.0.0-x64.rpm ``` **Creating an AppImage** @@ -574,37 +574,37 @@ make install This will be the directory structure for the installation: ``` -/Applications/EmulationStation Desktop Edition.app/Contents/Info.plist -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/es-pdf-convert -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.0.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavcodec.60.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavfilter.9.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavformat.60.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavutil.58.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfontconfig.1.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libgit2.1.6.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libjpeg.62.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libopenjp2.7.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpoppler-cpp.0.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpoppler.129.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpostproc.57.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.4.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.7.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libtiff.6.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbis.0.4.9.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbisenc.2.0.12.dylib -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/EmulationStation-DE.icns -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/LICENSE -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/licenses/* -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/* -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/* +/Applications/ES-DE.app/Contents/Info.plist +/Applications/ES-DE.app/Contents/MacOS/ES-DE +/Applications/ES-DE.app/Contents/MacOS/es-pdf-convert +/Applications/ES-DE.app/Contents/MacOS/libSDL2-2.0.0.dylib +/Applications/ES-DE.app/Contents/MacOS/libavcodec.60.dylib +/Applications/ES-DE.app/Contents/MacOS/libavfilter.9.dylib +/Applications/ES-DE.app/Contents/MacOS/libavformat.60.dylib +/Applications/ES-DE.app/Contents/MacOS/libavutil.58.dylib +/Applications/ES-DE.app/Contents/MacOS/libfontconfig.1.dylib +/Applications/ES-DE.app/Contents/MacOS/libfreetype.6.dylib +/Applications/ES-DE.app/Contents/MacOS/libgit2.1.6.dylib +/Applications/ES-DE.app/Contents/MacOS/libjpeg.62.dylib +/Applications/ES-DE.app/Contents/MacOS/libopenjp2.7.dylib +/Applications/ES-DE.app/Contents/MacOS/libpoppler-cpp.0.dylib +/Applications/ES-DE.app/Contents/MacOS/libpoppler.129.dylib +/Applications/ES-DE.app/Contents/MacOS/libpostproc.57.dylib +/Applications/ES-DE.app/Contents/MacOS/libswresample.4.dylib +/Applications/ES-DE.app/Contents/MacOS/libswscale.7.dylib +/Applications/ES-DE.app/Contents/MacOS/libtiff.6.dylib +/Applications/ES-DE.app/Contents/MacOS/libvorbis.0.4.9.dylib +/Applications/ES-DE.app/Contents/MacOS/libvorbisenc.2.0.12.dylib +/Applications/ES-DE.app/Contents/Resources/ES-DE.icns +/Applications/ES-DE.app/Contents/Resources/LICENSE +/Applications/ES-DE.app/Contents/Resources/licenses/* +/Applications/ES-DE.app/Contents/Resources/resources/* +/Applications/ES-DE.app/Contents/Resources/themes/* ``` ES-DE will look in the following locations for application resources, in the listed order: -* \/.emulationstation/resources/ +* \/ES-DE/resources/ * \/../Resources/resources/ * \/resources/ @@ -612,7 +612,7 @@ The resources directory is critical, without it the application won't start. As well the following locations will be searched for themes, also in the listed order: -* \/.emulationstation/themes/ +* \/ES-DE/themes/ * \/../Resources/themes/ * \/themes/ @@ -628,19 +628,15 @@ Simply run `cpack` to build a .dmg disk image/installer: myusername@computer:~/emulationstation-de$ cpack CPack: Create package using Bundle CPack: Install projects -CPack: - Run preinstall target for: emulationstation-de -CPack: - Install project: emulationstation-de [] +CPack: - Run preinstall target for: es-de +CPack: - Install project: es-de [] CPack: Create package -CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-2.2.0-x64.dmg generated. +CPack: - package: /Users/myusername/emulationstation-de/ES-DE_3.0.0-arm64.dmg generated. ``` ## Building on Windows -Although both Microsoft Visual C++ (MSVC) and GCC (MinGW) have historically been supported for building ES-DE on Windows, as of the 2.2.0 release MinGW is no longer recommended and support for it will likely be dropped in future releases. - -Although MinGW produces much higher quality code than MSVC with ES-DE running around 10% to 25% faster it's unfortunately not sustainable to keep using it. There are multiple technical issues with third party libraries like severe threading issues with FFmpeg and some libraries like Poppler not being readily available. Debugging with MinGW is also a very slow and tedious process compared to MSVC. MinGW up to 9.2.0 works more or less fine but anything more modern than this introduces issues like FFmpeg's avfilter_graph_free() call taking up to 7000 times longer to complete which makes video playback unusable. Setting filter graphs to use single threads solves some but not all issues. As well libgit2 has (probably) a race condition that causes random repository corruption that is likely only present when using MinGW. - -Clang/LLVM has also been evaluated but it suffers from at least the same threading issues as MinGW, likely because it uses libraries from the latter. It also fails to build some of the third party libraries needed by ES-DE. +Only the Microsoft Visual C++ (MSVC) compiler is supported on Windows. Although MinGW/GCC produces higher quality code with ES-DE running around 10% to 25% faster it's unfortunately not sustainable to use it. There are multiple technical issues with third party libraries like severe threading issues with FFmpeg and some libraries like Poppler not being readily available. **MSVC setup** @@ -677,21 +673,6 @@ The way the MSVC environment works is that a specific developer shell is provide It's important to choose the x64-specific shell and not the x86 variant, as ES-DE will only compile as a 64-bit application. -**MinGW (GCC) setup** - -Download the following packages and install them: - -[https://gitforwindows.org](https://gitforwindows.org) - -[https://cmake.org/download](https://cmake.org/download) - -Download the _MinGW-w64 based_ version of GCC: \ -[https://jmeubank.github.io/tdm-gcc](https://jmeubank.github.io/tdm-gcc) - -After installation, make a copy of `TDM-GCC-64\bin\mingw32-make` to `make` for your convenience. - -Only version 9.2.0 of MinGW has been confirmed to work correctly, anything newer introduces severe problems and MSVC should instead be used if a more modern compiler is required. - **Other preparations** In order to get clang-format onto the system you need to download and install Clang/LLVM: \ @@ -707,7 +688,7 @@ Configure Git. Details about its setup is beyond the scope of this document, but It's strongly recommended to set line breaks to Unix-style (line feed only) directly in the code editor. But if not done, lines breaks will anyway be converted when running clang-format on the code, as explained [here](INSTALL.md#using-clang-format-for-automatic-code-formatting). -The instructions below assume all build steps for MSVC are done in the MSVC developer console (x64 Native Tools Command Prompt for VS) and all MinGW build steps are done using the Git Bash shell. +The instructions below assume all build steps for MSVC are done in the MSVC developer console (x64 Native Tools Command Prompt for VS). **Cloning and setting up dependencies** @@ -724,29 +705,21 @@ cd emulationstation-de git checkout stable-2.2 ``` -On Windows all dependencies are kept in-tree in the `external` directory tree. Most of the libraries can be downloaded in binary form, but a few need to be built from source code. There are four scripts in the tools directory that automate this entirely. Two of them are used for the MSVC compiler and the other two for MinGW. +On Windows all dependencies are kept in-tree in the `external` directory tree. Most of the libraries can be downloaded in binary form, but a few need to be built from source code. There are two scripts in the tools directory that automate this entirely. You run them like this: -For MSVC, you run them like this: ``` cd emulationstation-de -tools\Windows_dependencies_setup_MSVC.bat -tools\Windows_dependencies_build_MSVC.bat -``` - -And for MinGW like the following: -``` -cd emulationstation-de -tools/Windows_dependencies_setup_MinGW.sh -tools/Windows_dependencies_build_MinGW.sh +tools\Windows_dependencies_setup.bat +tools\Windows_dependencies_build.bat ``` Re-running the setup script will delete and download all dependencies again, and re-running the build script will clean and rebuild from scratch. -The setup scripts for both MSVC and MinGW will download and launch an installer for OpenSSL for Windows if this has not already been installed on the build machine. Just run through the installer using the default settings and everything should work fine. +The setup scripts will download and launch an installer for OpenSSL for Windows if this has not already been installed on the build machine. Just run through the installer using the default settings and everything should work fine. Following these preparations, ES-DE should be ready to be compiled. -**Building ES-DE using MSVC** +**Building ES-DE** It's assumed that [Jom](https://wiki.qt.io/Jom) is used, but if instead using nmake then just remove _JOM_ from the -G flag argument and remove the -j flag as nmake does not support building in parallel. @@ -775,31 +748,7 @@ nmake ThreadSanitizer and UndefinedBehaviorSanitizer aren't available for the MSVC compiler. -There are a number of compiler warnings for the bundled rlottie library when building with MSVC. Unfortunately these need to be resolved upstream, but everything should still work fine so the warnings can be ignored for now. - -**Building ES-DE using MinGW** - -For a release build: - -``` -cmake -G "MinGW Makefiles" . -make -j8 -``` - -Or for a debug build: - -``` -cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug . -make -j8 -``` - -Change the -j flag to whatever amount of parallel threads you want to use for the compilation. - -Unfortunately AddressSanitizer, ThreadSanitizer and UndefinedBehaviorSanitizer do not seem to be supported with MinGW. - -You run a parallel build using multiple CPU cores with the `-j` flag, for example, `make -j6`. - -Note that compilation time is much longer than on Unix/Linux or macOS, and linking is incredibly slow for a debug build (around 10 times longer compared to Linux). The debug binary is also much larger than on Unix. +There are a number of compiler warnings for the bundled rlottie library. Unfortunately these need to be resolved upstream, but everything should still work fine so the warnings can be ignored for now. **TLS/SSL certificates** @@ -827,24 +776,24 @@ After the installation has been completed, go to the emulationstation-de directo $ cpack CPack: Create package using NSIS CPack: Install projects -CPack: - Run preinstall target for: emulationstation-de -CPack: - Install project: emulationstation-de [] +CPack: - Run preinstall target for: es-de +CPack: - Install project: es-de [] CPack: Create package -CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-2.2.0-x64.exe generated. +CPack: - package: C:/Programming/emulationstation-de/ES-DE_3.0.0-x64.exe generated. ``` -The default installation directory suggested by the installer is `C:\Program Files\EmulationStation-DE` but this can of course be changed by the user. +The default installation directory suggested by the installer is `C:\Program Files\ES-DE` but this can of course be changed by the user. ES-DE will look in the following locations for application resources, in the listed order: -* \\\.emulationstation\resources\ +* \\\ES-DE\resources\ * \\resources\ The resources directory is critical, without it the application won't start. As well the following locations will be searched for themes, also in the listed order: -* \\\.emulationstation\themes\ +* \\\ES-DE\themes\ * \\themes\ A theme is not mandatory to start the application, but ES-DE will be basically useless without it. @@ -1015,9 +964,9 @@ The reason to not simply replace the BIOS and devices files with the new version ## Configuration -**~/.emulationstation/es_settings.xml** +**~/ES-DE/settings/es_settings.xml** -When ES-DE is first started, a configuration file will be created as `~/.emulationstation/es_settings.xml` +When ES-DE is first started, a configuration file will be created as `~/ES-DE/settings/es_settings.xml` This file will contain all supported settings at their default values. Normally you shouldn't need to modify this file manually, instead you should be able to use the menu inside ES-DE to update all the necessary settings. @@ -1049,16 +998,18 @@ There is also support to add the variable %ESPATH% to the ROM directory setting, ``` -**~/.emulationstation/es_input.xml** +**~/ES-DE/settings/es_input.xml** As ES-DE auto-configures the keyboard and controllers, neither the input configuration step or manual adjustments to the es_input.xml file should normally be needed. Actually, unless the button layout has been customized using the input configurator, the es_input.xml file will not even exist. -But if you have customized your button layout and your controller or keyboard stop working, you can delete the `~/.emulationstation/es_input.xml` file to remove the customizations, or you can start ES-DE with the `--force-input-config` command line option to make the input configurator appear. +But if you have customized your button layout and your controller or keyboard stop working, you can delete the `~/ES-DE/settings/es_input.xml` file to remove the customizations, or you can start ES-DE with the `--force-input-config` command line option to make the input configurator appear. The input configuration is described in the [User guide](USERGUIDE.md#input-device-configuration). ## Command line options +_There are no command line options available on Android as this operating system works completely differently than all other supported platforms._ + You can use **--help** or **-h** to view the list of command line options, as shown here. ``` @@ -1089,13 +1040,13 @@ You can use **--help** or **-h** to view the list of command line options, as sh _The --anti-aliasing option is not available if ES-DE is built using the OpenGL ES renderer and the --no-update-check option is not available for builds where the application updater is disabled._ -As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `emulationstation --home ~/games/emulation`, ES-DE will use `~/games/emulation/.emulationstation` as its application home directory. Be aware that this option completely replaces what is considered the home directory, meaning the default ROM directory ~/ROMs would be resolved to ~/games/emulation/ROMs. The same is true for the emulator core locations if es_find_rules.xml is configured to look for them relative to the home directory. So of course RetroArch and other emulators would also need to be configured to use ~/games/emulation as its base directory in this instance. +As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `es-de --home ~/games/emulation`, ES-DE will use `~/games/emulation/ES-DE` as its application data directory. Be aware that this option completely replaces what is considered the home directory, meaning the default ROM directory ~/ROMs would be resolved to ~/games/emulation/ROMs. The same is true for the emulator core locations if es_find_rules.xml is configured to look for them relative to the home directory. So of course RetroArch and other emulators would also need to be configured to use ~/games/emulation as its base directory in this instance. Setting --resolution to a lower or higher value than the display resolution will add a border to the application window. The exception is if defining a lower resolution than the display resolution in combination with the --fullscreen-padding flag as this will pad the screen contents on a black background. This can be combined with the --screenoffset option for exact positioning on displays where bezels or similar may obstruct part of the viewable area. The --no-update-check option only disabled the application updater for the current startup. To permanently disable this functionality use the _Check for application updates_ option in the _Other settings_ menu. The command line option is primarily intended for the unlikely event that the application updater breaks the application and makes it impossible to start. -Running with the --create-system-dirs option will generate all the game system directories in the ROMs folder. This is equivalent to starting ES-DE with no game ROMs present and pressing the _Create directories_ button. Detailed output for the directory creation will be available in es_log.txt and the application will quit immediately after the directories have been created. +Running with the --create-system-dirs option will generate all the game system directories in the ROMs folder. This is equivalent to starting ES-DE with no game ROMs present and pressing the _Create directories_ button. Detailed output for the directory creation will be available in es_log.txt and the application will quit immediately after the directories have been created. By default placeholder entries will be skipped, if you want to still create these directories then set the CreatePlaceholderSystemDirectories option to true in es_settings.xml. For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter: ``` @@ -1116,6 +1067,10 @@ The --ignore-gamelist option is only active during the program session and is no There are some settings which are not configurable via the GUI as modifying these should normally not be required. To still change these, edit the es_settings.xml file directly. +**CreatePlaceholderSystemDirectories** + +If a system in es_systems.xml has a single command tag with the text _PLACEHOLDER_ anywhere in the tag (regardless of letter case) then its directory and _systeminfo.txt_ file will not get created when running with the --create-system-dirs command line option, or when using the _Create/update system directories_ entry in the _Utilities_ menu or when pressing the _Create directories_ button in the no-games startup dialog. However setting this option to true will override the behavior so the placeholder directories will still be created. + **DebugSkipInputLogging** Enabling this will skip all input event logging (button and key presses). Default value is false. @@ -1130,7 +1085,7 @@ Enabling this will skip all debug messages about missing files specifically for **LegacyGamelistFileLocation** -As of ES-DE 2.0.0 any gamelist.xml files stored in the game system directories (e.g. under `~/ROMs/`) will not get loaded, they are instead required to be placed in the `~/.emulationstation/gamelists/` directory tree. By setting this option to `true` it's however possible to retain the old behavior of first looking for gamelist.xml files in the system directories on startup. Note that even if this setting is enabled ES-DE will still always create new gamelist.xml files under `~/.emulationstation/gamelists/` which was the case also for the 1.x.x releases. +As of ES-DE 2.0.0 any gamelist.xml files stored in the game system directories (e.g. under `~/ROMs/`) will not get loaded, they are instead required to be placed in the `~/ES-DE/gamelists/` directory tree. By setting this option to `true` it's however possible to retain the old behavior of first looking for gamelist.xml files in the system directories on startup. Note that even if this setting is enabled ES-DE will still always create new gamelist.xml files under `~/ES-DE/gamelists/` which was the case also for the 1.x.x releases. **LottieMaxFileCache** @@ -1152,369 +1107,28 @@ Sets the server connection timeout for the scraper. Minimum value is 0 seconds ( Sets the transfer timeout per HTTPS request. Minimum value is 0 seconds (infinity) and maximum value is 300 seconds. Default value is 120 seconds. +**ScraperIgnoreHTTP404Errors** + +Normally the scraper will stop whenever an HTTP error code with value 400 or above is returned from the scraper service, but by default there is an exception for 404 errors (resource not found). Changing this setting to _false_ will make the scraper handle 404 errors as all other error codes, meaning it will run through the configured retry attempts and then display an error notification dialog if the resource could not be retrieved. + **UIMode_passkey** The passkey to use to change from the _Kiosk_ or _Kid_ UI modes to the _Full_ UI mode. -**UserThemeDirectory** +**UserThemeDirectory** _(All operating systems except Android)_ -Sets the user theme directory. If left blank it will default to `~/.emulationstation/themes/` - -## es_systems.xml - -The es_systems.xml file contains the game systems configuration data for ES-DE, written in XML format. This defines the system name, the full system name, the ROM path, the allowed file extensions, the launch command, the platform (for scraping) and the theme to use. - -ES-DE ships with a comprehensive `es_systems.xml` file and most users will probably never need to make any customizations. But there may be special circumstances such as wanting to use different emulators for some game systems or perhaps to add additional systems altogether. - -To accomplish this, ES-DE supports customizations via a separate es_systems.xml file that is to be placed in the `custom_systems` folder in the application home directory, i.e. `~/.emulationstation/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows unless overridden via the --home command line option.) - -This custom file functionality is designed to be complementary to the bundled es_systems.xml file, meaning you should only add entries to the custom configuration file for game systems that you actually want to add or override. So to for example customize a single system, this file should only contain a single `` tag. The structure of the custom file is identical to the bundled file with the exception of an additional optional tag named ``. If this is placed in the custom es_systems.xml file, ES-DE will not load the bundled file. This is normally not recommended and should only be used for special situations. At the end of this section you can find an example of a custom es_systems.xml file. - -The bundled es_systems.xml file is located in the resources directory that is part of the application installation. For example this could be `/usr/share/emulationstation/resources/systems/unix/es_systems.xml` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/systems/macos/es_systems.xml` on macOS or `C:\Program Files\EmulationStation-DE\resources\systems\windows\es_systems.xml` on Windows. The actual location may differ from these examples of course, depending on where ES-DE has been installed. - -If you're using the AppImage release of ES-DE then the bundled es_systems.xml file is embedded in the AppImage together with the rest of the resources. - -It doesn't matter in which order you define the systems as they will be sorted by the `` tag or by the optional `` tag when displayed inside the application. But it's still a good idea to add the systems in alphabetical order to make the configuration file easier to maintain. - -Note that the `` tags are sorted in [lexicographic order](https://en.wikipedia.org/wiki/Lexicographic_order) so 11 will be sorted above 2 but 002 will be sorted above 011. Secondary sorting will always be done by the fullname tag in es_systems.xml. - -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: -```xml - -~/Applications/yuzu*.AppImage %ROM% - -~/Applications/yuzu*.App* %ROM% - -~/App*/yuzu*.AppImage %ROM% -``` - -There is a special case when it comes to file extensions where it's possible to use extensionless files if required. To accomplish this simply add a dot (.) to the list of extensions in the `` tag. Obviously this makes it impossible to use the _directories interpreted as files_ functionality as there is no file extension, but apart from that everything should work the same as for regular files. - -Keep in mind that you have to set up your emulators separately from ES-DE as the es_systems.xml file assumes that your emulator environment is properly configured. - -Below is an overview of the file layout with various examples. For the command tag, the newer es_find_rules.xml logic described later in this document removes the need for most of the legacy options, but they are still supported for special configurations and for backward compatibility with old configuration files. - -```xml - - - - - - - snes - - - Nintendo SNES (Super Nintendo) - - - Super Nintendo - - - %ROMPATH%/snes - - - .smc .SMC .sfc .SFC .swc .SWC .fig .FIG .bs .BS .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP - - - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% - - - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x2010_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_mercury_accuracy_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/mednafen_supafaust_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/mesen-s_libretro.so %ROM% - - - %STARTDIR%=%EMUDIR% %PRECOMMAND_WINE% %EMULATOR_XENIA-WINDOWS% %ROM% - - - retroarch -L ~/.config/retroarch/cores/snes9x_libretro.so %ROM% - - - retroarch -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% - - - ~/Applications/rpcs3*.AppImage --no-gui %ROM% - - - /Applications/RetroArch.app/Contents/MacOS/RetroArch -L %CORE_RETROARCH%/snes9x_libretro.dylib %ROM% - - - retroarch.exe -L %EMUPATH%\cores\snes9x_libretro.dll %ROM% - - - "C:\My Games\RetroArch\retroarch.exe" -L "%EMUPATH%\cores\snes9x_libretro.dll" %ROM% - - - "%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM% - - - %HIDEWINDOW% %EMULATOR_MAME% %STARTDIR%=%EMUDIR% -rompath %ROMPATH%\arcade %BASENAME% - - - %EMULATOR_MAME% %STARTDIR%=~/.mame -rompath %ROMPATH%/arcade %BASENAME% - - - %RUNINBACKGROUND% %ENABLESHORTCUTS% %EMULATOR_OS-SHELL% %ROM% - - - %HIDEWINDOW% %ESCAPESPECIALS% %RUNINBACKGROUND% cmd.exe /C %ROM% - - - snes - - - snes - - -``` - -The following variable is expanded for the `path` tag: - -`%ROMPATH%` - Replaced with the path defined in the setting ROMDirectory in es_settings.xml. - -The following variables are expanded for the `command` tag: - -`%ROM%` - Replaced with the absolute path to the selected ROM, with most special characters escaped with a backslash. - -`%ROMRAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes. - -`%ROMPATH%` - Replaced with the path defined in the setting ROMDirectory in es_settings.xml. If combined with a path that contains blankspaces, then it must be surrounded by quotation marks, for example `%ROMPATH%"\Arcade Games"`. Note that the quotation mark must be located before the directory separator in this case. - -`%BASENAME%` - Replaced with the "base" name of the path to the selected ROM. For example the path `/foo/bar.rom` would end up as the value `bar` - -`%FILENAME%` - Replaced with the filename of the selected ROM. For example the path `/foo/bar.rom` would end up as the value `bar.rom` - -`%STARTDIR%` - The directory to start in when launching the emulator. Must be defined as a pair separated by an equal sign. This is normally not required, but some emulators and game engines like standalone MAME and OpenBOR will not work properly unless you're in the correct directory when launching a game. Either an absolute path can be used, such as `%STARTDIR%=C:\Games\mame` or some variables are available that provide various functions. The `%EMUDIR%` variable can be used to start in the directory where the emulator binary is located, i.e. `%STARTDIR%=%EMUDIR%`, the `%GAMEDIR%` variable can be used to start in the directory where the game file is located, i.e. `%STARTDIR%=%GAMEDIR%` and the `%GAMEENTRYDIR%` variable can be used which works identically to `%GAMEDIR%` with the exception that it will interpret the actual game entry as the start directory. This is useful in very rare situations like for the EasyRPG Player where the game directories are interpreted as files but where the game engine must still be started from inside the game directory. If an absolute path is set that contains blankspaces, then it must be surrounded by quotation marks, for example `%STARTDIR%="C:\Retro games\mame"`. If the directory defined by this variable does not exist, it will be created on game launch. The variable can be placed anywhere in the launch command if the %EMULATOR_ variable is used, otherwise it has to be placed after the emulator binary. - -`%INJECT%` - This allows the injection of launch arguments or environment variables stored in a text file on the filesystem. The %INJECT% variable must be defined as a pair separated by an equal sign, for example `%INJECT%=game.commands`. The `%BASENAME%` variable can also be used in conjunction with this variable, such as `%INJECT%=%BASENAME%.commands`. By default a path relative to the game file will be assumed but it's also possible to use an absolute path or the ~ (tilde) symbol which will expand to the home directory. If a path contains spaces it needs to be surrounded by quotation marks, such as `%INJECT%="C:\My games\ROMs\daphne\%BASENAME%.daphne\%BASENAME%.commands"`. The variable can be placed anywhere in the launch command and the file contents will be injected at that position. It's also possible to have multiple injections by defining the variable more than once at different locations in the launch command string. The specified file is optional, if it does not exist, is empty, or if there are insufficient permissions to read the file, then it will simply be skipped. For safety reasons the injection file can only have a maximum size of 4096 bytes and if it's larger than this it will be skipped and a warning will be written to es_log.txt. - -`%EMUPATH%` - Replaced with the path to the emulator binary. This variable is used for manually specifying emulator core locations, and a check for the existence of the core file will be done on game launch and an error displayed if it can't be found. Normally %EMUPATH% should not be used as the %CORE_ variable is the recommended method for defining core locations. - -`%EMUDIR%` - Replaced with the path to the emulator binary. This is a general purpose variable as opposed to %EMUPATH% which is intended specifically for core locations. - -`%GAMEDIR%` - Replaced with the path to the game. - -`%GAMEDIRRAW%` - Replaced with the unescaped path to the game. - -`%ESPATH%` - Replaced with the path to the ES-DE binary. Mostly useful for portable emulator installations, for example on a USB memory stick. - -`%EMULATOR_` - This utilizes the emulator find rules as defined in `es_find_rules.xml`. This is the recommended way to configure the launch command. The find rules are explained in more detail below. - -`%PRECOMMAND_` - This utilizes the emulator find rules as defined in `es_find_rules.xml` to locate a pre-command binary. It's for instance useful for running Windows emulators on Linux using Wine or Proton. The %PRECOMMAND_ entry can be located anywhere in the launch command but it should be placed before the %EMULATOR_ variable in order to work as intended. - -`%CORE_` - This utilizes the core find rules as defined in `es_find_rules.xml`. This is the recommended way to configure the launch command. - -`%RUNINBACKGROUND%` - When this variable is present, ES-DE will continue to run in the background while a game is launched. This will also prevent the gamelist video from playing, the screensaver from starting, and the game name and game description from scrolling. This functionality is required for some systems such as Valve Steam. The variable can be placed anywhere in the launch command. - -`%HIDEWINDOW%` - This variable is only available on Windows and is used primarily for hiding console windows when launching scripts (used for example by Steam games and source ports). If not defining this, the console window will be visible when launching games. The variable can be placed anywhere in the launch command. - -`%ESCAPESPECIALS%` - This variable is only available on Windows and is used to escape the characters &()^=;, for the %ROM% variable, which would otherwise make binaries like cmd.exe fail when launching scripts or links. The variable can be placed anywhere in the launch command. - -`%ENABLESHORTCUTS%` - This variable is only available on Unix and macOS and is used to enable shortcuts to games and applications. On Unix these come in the form of .desktop files and ES-DE has a simple parser which essentially extracts the command defined in the Exec key and then executes it. Although some basic file structure checks are performed, the actual command listed with the Exec key is blindly executed. In addition to this the variables %F, %f, %U and %u are removed from the Exec key entry. On macOS shortcuts in the form of .app directories and alias files are executed using the `open -W -a` command. This makes it possible to launch shortcuts to emulators and applications like Steam as well as aliases for any application. However the latter need to be renamed to the .app file extension or it won't work. When a file is matching the .desktop or .app extension respectively, the emulator command defined using the %EMULATOR% variable will be stripped. An %EMULATOR% entry is however still required for the %ENABLESHORTCUTS% variable to work as the intention is to combine shortcuts with the ability to launch shell scripts without having to setup alternative emulators. The %ROM% variable is expanded to the command to execute when using %ENABLESHORTCUTS%, which also means that this variable has to be used, and for example %ROMRAW% will not work. - -Here are some additional real world examples of system entries, the first one for Unix: - -```xml - - dos - DOS (PC) - %ROMPATH%/dos - .bat .BAT .com .COM .conf .CONF .cue .CUE .exe .EXE .iso .ISO .7z .7Z .zip .ZIP - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_pure_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_svn_libretro.so %ROM% - dos - dos - -``` - -Then one for macOS: - -```xml - - n64 - Nintendo 64 - %ROMPATH%/n64 - .n64 .N64 .v64 .V64 .z64 .Z64 .bin .BIN .u1 .U1 .7z .7Z .zip .ZIP - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/parallel_n64_libretro.dylib %ROM% - n64 - n64 - -``` - -And finally one for Windows: - -```xml - - pcengine - NEC PC Engine - %ROMPATH%\pcengine - .bin .BIN .ccd .CCD .chd .CHD .cue .CUE .img .IMG .iso .ISO .m3u .M3U .pce .PCE .sgx .SGX .toc .TOC .7z .7Z .zip .ZIP - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%\mednafen_pce_libretro.dll %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%\mednafen_pce_fast_libretro.dll %ROM% - pcengine - pcengine - -``` - -As well, here's an example for Unix of a custom es_systems.xml file placed in ~/.emulationstation/custom_systems/ that overrides a single game system from the bundled configuration file: -```xml - - - - - nes - Nintendo Entertainment System - %ROMPATH%/nes - .nes .NES .zip .ZIP - /usr/games/fceux %ROM% - nes - nes - - -``` - -If adding the `` tag to the file, the bundled es_systems.xml file will not be processed. For this example it wouldn't be a very good idea as NES would then be the only platform that could be used in ES-DE. - -```xml - - - - - - nes - Nintendo Entertainment System - %ROMPATH%/nes - .nes .NES .zip .ZIP - /usr/games/fceux %ROM% - nes - nes - - -``` - -Here is yet another example with the addition of the `snes` system where some file extensions and alternative emulator entries have been removed, and the full name and sorting have been modified. - -```xml - - - - - nes - Nintendo Entertainment System - %ROMPATH%/nes - .nes .NES .zip .ZIP - /usr/games/fceux %ROM% - nes - nes - - - snes - Super Nintendo - Nintendo SNES (Super Nintendo) - %ROMPATH%/snes - .smc .SMC .sfc .SFC .swc .SWC .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x2010_libretro.so %ROM% - %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_libretro.so %ROM% - snes - snes - - -``` - -## es_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` - -Note that in order for ES-DE to load this file you'll need to set the _Systems sorting_ option in the _UI settings_ menu to _Full names or custom_. - -The structure of this file is essentially a simplified version of the es_systems.xml file, but with only the `` and `` 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 - - - - amiga - 1985 - - - c64 - 1982 - - - vic20 - 1980 - - -``` - -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 `` 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: - -* Release year -* Manufacturer, release year -* Hardware type, release year -* Manufacturer, hardware type, release year - -You can apply any of these sorting files via the _Systems sorting_ option in the _Other settings_ menu. Note that in order to load a es_systems_sorting.xml file placed in the custom_systems directory you'll need to set this option to _Full names or custom_. +Sets the user theme directory. If left blank it will default to `~/ES-DE/themes/` ## es_find_rules.xml This file makes it possible to define rules for where to search for the emulator binaries and emulator cores. -The file is located in the resources directory in the same location as the es_systems.xml file, but a customized copy can be placed in ~/.emulationstation/custom_systems, which will complement 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 ~/ES-DE/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 Linux (this is not the complete file shipped with ES-DE as that would be too large to include here): ```xml - + @@ -1550,10 +1164,6 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file /usr/lib64/libretro /usr/lib/libretro - - /usr/local/lib/libretro - - /usr/pkg/lib/libretro @@ -1763,14 +1373,497 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo ``` +## es_systems.xml + +The es_systems.xml file contains the game systems configuration data for ES-DE, written in XML format. This defines the system name, the full system name, the ROM path, the allowed file extensions, the launch command, the platform (for scraping) and the theme to use. + +ES-DE ships with a comprehensive `es_systems.xml` file and most users will probably never need to make any customizations. But there may be special circumstances such as wanting to use different emulators for some game systems or perhaps to add additional systems altogether. + +To accomplish this, ES-DE supports customizations via a separate es_systems.xml file that is to be placed in the `custom_systems` folder in the application home directory, i.e. `~/ES-DE/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows unless overridden via the --home command line option.) + +This custom file functionality is designed to be complementary to the bundled es_systems.xml file, meaning you should only add entries to the custom configuration file for game systems that you actually want to add or override. So to for example customize a single system, this file should only contain a single `` tag. The structure of the custom file is identical to the bundled file with the exception of an additional optional tag named ``. If this is placed in the custom es_systems.xml file, ES-DE will not load the bundled file. This is normally not recommended and should only be used for special situations. At the end of this section you can find an example of a custom es_systems.xml file. + +The bundled es_systems.xml file is located in the resources directory that is part of the application installation. For example this could be `/usr/share/es-de/resources/systems/linux/es_systems.xml` on Linux, `/Applications/ES-DE.app/Contents/Resources/resources/systems/macos/es_systems.xml` on macOS or `C:\Program Files\ES-DE\resources\systems\windows\es_systems.xml` on Windows. The actual location may differ from these examples of course, depending on where ES-DE has been installed. + +If you're using the AppImage release of ES-DE then the bundled es_systems.xml file is embedded in the AppImage together with the rest of the resources. + +It doesn't matter in which order you define the systems as they will be sorted by the `` tag or by the optional `` tag when displayed inside the application. But it's still a good idea to add the systems in alphabetical order to make the configuration file easier to maintain. + +Note that the `` tags are sorted in [lexicographic order](https://en.wikipedia.org/wiki/Lexicographic_order) so 11 will be sorted above 2 but 002 will be sorted above 011. + +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: +```xml + +~/Applications/yuzu*.AppImage %ROM% + +~/Applications/yuzu*.App* %ROM% + +~/App*/yuzu*.AppImage %ROM% +``` + +There is a special case when it comes to file extensions where it's possible to use extensionless files if required. To accomplish this simply add a dot (.) to the list of extensions in the `` tag. Obviously this makes it impossible to use the _directories interpreted as files_ functionality as there is no file extension, but apart from that everything should work the same as for regular files. + +Keep in mind that you have to set up your emulators separately from ES-DE as the es_systems.xml file assumes that your emulator environment is properly configured. + +Below is an overview of the file layout with various examples. For the command tag, the newer es_find_rules.xml logic described later in this document removes the need for most of the legacy options, but they are still supported for special configurations and for backward compatibility with old configuration files. + +```xml + + + + + + + snes + + + Nintendo SNES (Super Nintendo) + + + Super Nintendo + + + %ROMPATH%/snes + + + .smc .SMC .sfc .SFC .swc .SWC .fig .FIG .bs .BS .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP + + + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% + + + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x2010_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_mercury_accuracy_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/mednafen_supafaust_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/mesen-s_libretro.so %ROM% + + + %STARTDIR%=%EMUDIR% %PRECOMMAND_WINE% %EMULATOR_XENIA-WINDOWS% %ROM% + + + retroarch -L ~/.config/retroarch/cores/snes9x_libretro.so %ROM% + + + retroarch -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% + + + ~/Applications/rpcs3*.AppImage --no-gui %ROM% + + + /Applications/RetroArch.app/Contents/MacOS/RetroArch -L %CORE_RETROARCH%/snes9x_libretro.dylib %ROM% + + + retroarch.exe -L %EMUPATH%\cores\snes9x_libretro.dll %ROM% + + + "C:\My Games\RetroArch\retroarch.exe" -L "%EMUPATH%\cores\snes9x_libretro.dll" %ROM% + + + "%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM% + + + %HIDEWINDOW% %EMULATOR_MAME% %STARTDIR%=%EMUDIR% -rompath %ROMPATH%\arcade %BASENAME% + + + %EMULATOR_MAME% %STARTDIR%=~/.mame -rompath %ROMPATH%/arcade %BASENAME% + + + %RUNINBACKGROUND% %ENABLESHORTCUTS% %EMULATOR_OS-SHELL% %ROM% + + + %HIDEWINDOW% %ESCAPESPECIALS% %RUNINBACKGROUND% cmd.exe /C %ROM% + + + PLACEHOLDER %ROM% + + + snes + + + snes + + +``` + +The following variable is expanded for the `path` tag: + +`%ROMPATH%` - Replaced with the path defined in the setting ROMDirectory in es_settings.xml. + +The following variables are expanded for the `command` tag: + +`%ROM%` - Replaced with the absolute path to the selected ROM, with most special characters escaped with a backslash. + +`%ROMRAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes. + +`%ROMPATH%` - Replaced with the path defined in the setting ROMDirectory in es_settings.xml. If combined with a path that contains blankspaces, then it must be surrounded by quotation marks, for example `%ROMPATH%"\Arcade Games"`. Note that the quotation mark must be located before the directory separator in this case. + +`%BASENAME%` - Replaced with the "base" name of the path to the selected ROM. For example the path `/foo/bar.rom` would end up as the value `bar` + +`%FILENAME%` - Replaced with the filename of the selected ROM. For example the path `/foo/bar.rom` would end up as the value `bar.rom` + +`%STARTDIR%` - The directory to start in when launching the emulator. Must be defined as a pair separated by an equal sign. This is normally not required, but some emulators and game engines like standalone MAME and OpenBOR will not work properly unless you're in the correct directory when launching a game. Either an absolute path can be used, such as `%STARTDIR%=C:\Games\mame` or some variables are available that provide various functions. The `%EMUDIR%` variable can be used to start in the directory where the emulator binary is located, i.e. `%STARTDIR%=%EMUDIR%`, the `%GAMEDIR%` variable can be used to start in the directory where the game file is located, i.e. `%STARTDIR%=%GAMEDIR%` and the `%GAMEENTRYDIR%` variable can be used which works identically to `%GAMEDIR%` with the exception that it will interpret the actual game entry as the start directory. This is useful in very rare situations like for the EasyRPG Player where the game directories are interpreted as files but where the game engine must still be started from inside the game directory. If an absolute path is set that contains blankspaces, then it must be surrounded by quotation marks, for example `%STARTDIR%="C:\Retro games\mame"`. If the directory defined by this variable does not exist, it will be created on game launch. The variable can be placed anywhere in the launch command if the %EMULATOR_ variable is used, otherwise it has to be placed after the emulator binary. + +`%INJECT%` - This allows the injection of launch arguments or environment variables stored in a text file on the filesystem. The %INJECT% variable must be defined as a pair separated by an equal sign, for example `%INJECT%=game.commands`. The `%BASENAME%` variable can also be used in conjunction with this variable, such as `%INJECT%=%BASENAME%.commands`. By default a path relative to the game file will be assumed but it's also possible to use an absolute path or the ~ (tilde) symbol which will expand to the home directory. If a path contains spaces it needs to be surrounded by quotation marks, such as `%INJECT%="C:\My games\ROMs\daphne\%BASENAME%.daphne\%BASENAME%.commands"`. The variable can be placed anywhere in the launch command and the file contents will be injected at that position. It's also possible to have multiple injections by defining the variable more than once at different locations in the launch command string. The specified file is optional, if it does not exist, is empty, or if there are insufficient permissions to read the file, then it will simply be skipped. For safety reasons the injection file can only have a maximum size of 4096 bytes and if it's larger than this it will be skipped and a warning will be written to es_log.txt. + +`%EMUPATH%` - Replaced with the path to the emulator binary. This variable is used for manually specifying emulator core locations, and a check for the existence of the core file will be done on game launch and an error displayed if it can't be found. Normally %EMUPATH% should not be used as the %CORE_ variable is the recommended method for defining core locations. + +`%EMUDIR%` - Replaced with the path to the emulator binary. This is a general purpose variable as opposed to %EMUPATH% which is intended specifically for core locations. + +`%GAMEDIR%` - Replaced with the path to the game. + +`%GAMEDIRRAW%` - Replaced with the unescaped path to the game. + +`%ESPATH%` - Replaced with the path to the ES-DE binary. Mostly useful for portable emulator installations, for example on a USB memory stick. + +`%EMULATOR_` - This utilizes the emulator find rules as defined in `es_find_rules.xml`. This is the recommended way to configure the launch command. The find rules are explained in more detail below. + +`%PRECOMMAND_` - This utilizes the emulator find rules as defined in `es_find_rules.xml` to locate a pre-command binary. It's for instance useful for running Windows emulators on Linux using Wine or Proton. The %PRECOMMAND_ entry can be located anywhere in the launch command but it should be placed before the %EMULATOR_ variable in order to work as intended. + +`%CORE_` - This utilizes the core find rules as defined in `es_find_rules.xml`. This is the recommended way to configure the launch command. + +`%RUNINBACKGROUND%` - When this variable is present, ES-DE will continue to run in the background while a game is launched. This will also prevent the gamelist video from playing, the screensaver from starting, and the game name and game description from scrolling. This functionality is required for some systems such as Valve Steam. The variable can be placed anywhere in the launch command. + +`%HIDEWINDOW%` - This variable is only available on Windows and is used primarily for hiding console windows when launching scripts (used for example by Steam games and source ports). If not defining this, the console window will be visible when launching games. The variable can be placed anywhere in the launch command. + +`%ESCAPESPECIALS%` - This variable is only available on Windows and is used to escape the characters &()^=;, for the %ROM% variable, which would otherwise make binaries like cmd.exe fail when launching scripts or links. The variable can be placed anywhere in the launch command. + +`%ENABLESHORTCUTS%` - This variable is only available on Unix and macOS and is used to enable shortcuts to games and applications. On Unix these come in the form of .desktop files and ES-DE has a simple parser which essentially extracts the command defined in the Exec key and then executes it. Although some basic file structure checks are performed, the actual command listed with the Exec key is blindly executed. In addition to this the variables %F, %f, %U and %u are removed from the Exec key entry. On macOS shortcuts in the form of .app directories and alias files are executed using the `open -W -a` command. This makes it possible to launch shortcuts to emulators and applications like Steam as well as aliases for any application. However the latter need to be renamed to the .app file extension or it won't work. When a file is matching the .desktop or .app extension respectively, the emulator command defined using the %EMULATOR% variable will be stripped. An %EMULATOR% entry is however still required for the %ENABLESHORTCUTS% variable to work as the intention is to combine shortcuts with the ability to launch shell scripts without having to setup alternative emulators. The %ROM% variable is expanded to the command to execute when using %ENABLESHORTCUTS%, which also means that this variable has to be used, and for example %ROMRAW% will not work. + +Here are some additional real world examples of system entries, the first one for Unix: + +```xml + + dos + DOS (PC) + %ROMPATH%/dos + .bat .BAT .com .COM .conf .CONF .cue .CUE .exe .EXE .iso .ISO .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_pure_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_svn_libretro.so %ROM% + dos + dos + +``` + +Then one for macOS: + +```xml + + n64 + Nintendo 64 + %ROMPATH%/n64 + .n64 .N64 .v64 .V64 .z64 .Z64 .bin .BIN .u1 .U1 .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/parallel_n64_libretro.dylib %ROM% + n64 + n64 + +``` + +And finally one for Windows: + +```xml + + pcengine + NEC PC Engine + %ROMPATH%\pcengine + .bin .BIN .ccd .CCD .chd .CHD .cue .CUE .img .IMG .iso .ISO .m3u .M3U .pce .PCE .sgx .SGX .toc .TOC .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%\mednafen_pce_libretro.dll %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%\mednafen_pce_fast_libretro.dll %ROM% + pcengine + pcengine + +``` + +As well, here's an example for Linux of a custom es_systems.xml file placed in ~/ES-DE/custom_systems/ that overrides a single game system from the bundled configuration file: +```xml + + + + + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .zip .ZIP + /usr/games/fceux %ROM% + nes + nes + + +``` + +If adding the `` tag to the file, the bundled es_systems.xml file will not be processed. For this example it wouldn't be a very good idea as NES would then be the only platform that could be used in ES-DE. + +```xml + + + + + + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .zip .ZIP + /usr/games/fceux %ROM% + nes + nes + + +``` + +Here is yet another example with the addition of the `snes` system where some file extensions and alternative emulator entries have been removed, and the full name and sorting have been modified. + +```xml + + + + + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .zip .ZIP + /usr/games/fceux %ROM% + nes + nes + + + snes + Super Nintendo + Nintendo SNES (Super Nintendo) + %ROMPATH%/snes + .smc .SMC .sfc .SFC .swc .SWC .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x2010_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/bsnes_libretro.so %ROM% + snes + snes + + +``` + +## es_find_rules.xml and es_systems.xml on Android + +ES-DE works a bit differently on Android which is also reflected in the es_find_rules.xml and es_systems.xml configuration. Emulators on Android are launched via so-called _Intents_ which is an API rather than the typical command line approach used on Unix systems. Although ES-DE on Windows also uses an API call to launch emulators it's still closely connected to the regular operating system paradigms on how to start binaries and pass application options so the systems configuration still looks quite traditional. On Android this is not the case and there is therefore a heavy use of variables to reflect the Intent API functionality. + +To better understand the configuration in this section it could be a good idea to refer the official Android documentation:\ +https://developer.android.com/reference/android/content/Intent + +There is a command line tool in Android named _am_ which implements the _Intent_ API and can be used to test emulator launching, but this is not intended to be used by other applications and therefore ES-DE implements direct (albeit partial) support for the Intent API. Testing the modern FileProvider interface using the _am_ utility may also be difficult, or maybe impossible. + +**es_find_rules.xml** + +The es_find_rules.xml file is structured the same as for the other operating systems but there'a special _androidpackage_ find rule where you define the name of the emulator package as well as optionally which _activity_ to launch. If the activity is not defined then the default one for the package will be used. Although this may work in some instances it's usually a good idea to explicity set it. Apart from that the find rules work as on the other platforms, i.e. they will be traversed in the order they are defined. So by adding multiple _androidpackage_ entries for an emulator it's possible to look for multiple releases or forks without having to create separate emulator entries in es_systems.xml. It's also possible to override find rules by adding an ES-DE/custom_systems/es_find_rules.xml file, again the same logic applies as for all other platforms. + +The _androidpackage_ find rule entries are structured as `packagename/activity` and if only a package is defined then the forward slash can be omitted, i.e. only `packagename` is needed. + +Here's an example es_find_rules.xml file defining two emulators: + +```xml + + + + + + com.retroarch.aarch64/com.retroarch.browser.retroactivity.RetroActivityFuture + com.retroarch.ra32/com.retroarch.browser.retroactivity.RetroActivityFuture + com.retroarch/com.retroarch.browser.retroactivity.RetroActivityFuture + + + + + + org.yuzu.yuzu_emu.ea/org.yuzu.yuzu_emu.activities.EmulationActivity + org.yuzu.yuzu_emu/org.yuzu.yuzu_emu.activities.EmulationActivity + + + +``` + +**es_systems.xml** + +The es_systems.xml file on Android utilizes variables heavily to implement the _Intent_ API and these variables are covered in detail below. It's possible to override the systems configuration by adding an ES-DE/custom_systems/es_systems.xml file, the same logic applies as for all other platforms. + +`%EMULATOR_` - This utilizes the emulator find rules as defined in `es_find_rules.xml`. This is the only way to configure the launch command on Android and it works identically to the other platforms. + +`%ACTION%` - The general Intent action to be performed, you need to assign its value using an equal sign. + +`%MIMETYPE%` - Sets an explicit MIME type, which you need to assign using an equal sign such as %MIMETYPE%=text/plain. You will rarely, if ever, need to set an explicit MIME type so this variable is of limited use. By default Android will set the MIME type to application/octet-stream which is normally what you want. + +There are two main ways to pass options to emulators, using _extras_ or using the _data_ URI. There can only be a single data URI but there can be an arbitrary amount of extras. To understand more about the way this works, you can read about the _putExtra()_ and and _setData()_ functions here:\ +https://developer.android.com/reference/android/content/Intent + +`%EXTRA_` - This passes an _extra_ which contains any additional information that the emulator may support. This is provided as a key/value pair where you define the key name following the literal %EXTRA_ string and terminate it with a % sign and then assign the value using an equal sign. For example %EXTRA_LIBRETRO%=puae_libretro_android.so will pass the extra named _LIBRETRO_ with its value set to _puae_libretro_android.so_. You can pass an unlimited number of extras and you can also use various ROM variables in combination with this as described below. + +`%EXTRAARRAY_` - Defines an array of comma-separated string values following the key name. Only literal strings are supported, so this can't be used in combination with any ROM variables. As commas are used as separator characters, you'll need to escape any comma signs that you want to include in the actual value. For example %EXTRAARRAY_Parameters%=pone,p\\,two,pthree will pass the extra named _Parameters_ with the three separate array entries _pone_, _p,two_ and _pthree_. + +`%EXTRABOOL_` - Sets an extra with a boolean value, i.e. true/1 or false/0. + +`%DATA%` - Sets the data URI value for the intent using an equal sign. This is normally combined with one of the ROM variables. + +There are three approaches to passing game ROMs to emulators by using the following variables: + +`%ROM%` - Replaced with the absolute path to the selected ROM. This is a traditional method to provide the game ROM and its use will likely decrease or go away completely long term as emulators move to more modern methods. + +`%ROMSAF%` - Replaced with an Android Storage Access Framework (SAF) document URI which always starts with the _content://com.android.externalstorage.documents/_ string. You can read more about the SAF here:\ +https://developer.android.com/guide/topics/providers/document-provider + +`%ROMPROVIDER%` - This is the most modern approach to passing game ROMs to emulators. It uses the _FileProvider_ API to provide permissions to the file. This means that you don't need to setup the emulator upfront to have access to the directory where the game file is stored, access is instead temporarily granted by ES-DE. You can read more about the FileProvider API here:\ +https://developer.android.com/reference/androidx/core/content/FileProvider + +The `%ROM%` and `%ROMSAF%` variables can be used with both the `%DATA%` and `%EXTRA_` variables, but `%ROMPROVIDER%` can only be used with the `%DATA%` variable. For the `%DATA%` variable you'll just assign the ROM variable with an equal sign as there can only be a single _setData()_ API call per Intent. For the `%EXTRA_` variable you need to specify a name of the extra and then define it using an equal sign as an arbitrary amount of _putExtra()_ API calls can be used for an Intent. + +Here are some examples to clarify how this works: +``` +%DATA%=%ROM% +%DATA%=%ROMSAF% +%DATA%=%ROMPROVIDER% +%EXTRA_ROM%=%ROM% +%EXTRA_bootPath%=%ROMSAF% +%EXTRABOOL_resumeState%=false +``` + +There is also support for a couple of activity flags that affect the emulator/game launch behavior, you can read more about these flags here:\ +https://developer.android.com/reference/android/content/Intent + +The descriptions below are taken from the official documentation just linked above: + +`%ACTIVITY_CLEAR_TASK%` - If set in an Intent passed to Context.startActivity(), this flag will cause any existing task that would be associated with the activity to be cleared before the activity is started. That is, the activity becomes the new root of an otherwise empty task, and any old activities are finished. + +`%ACTIVITY_CLEAR_TOP%` - If set, and the activity being launched is already running in the current task, then instead of launching a new instance of that activity, all of the other activities on top of it will be closed and this Intent will be delivered to the (now on top) old activity as a new Intent. + +`%ACTIVITY_NO_HISTORY%` - If set, the new activity is not kept in the history stack. As soon as the user navigates away from it, the activity is finished. This may also be set with the noHistory attribute. If set, onActivityResult() is never invoked when the current activity starts a new activity which sets a result and finishes. + +Here's an example es_systems.xml file for Android: +```xml + + + + + gc + Nintendo GameCube + %ROMPATH%/gc + .ciso .CISO .dff .DFF .dol .DOL .elf .ELF .gcm .GCM .gcz .GCZ .iso .ISO .json .JSON .m3u .M3U .rvz .RVZ .tgc .TGC .wad .WAD .wbfs .WBFS .wia .WIA .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=/data/data/%ANDROIDPACKAGE%/cores/dolphin_libretro_android.so %EXTRA_ROM%=%ROM% + %EMULATOR_DOLPHIN% %ACTION%=android.intent.action.MAIN %DATA%=%ROMPROVIDER% + gc + gc + + + n3ds + Nintendo 3DS + %ROMPATH%/n3ds + .3ds .3DS .3dsx .3DSX .app .APP .axf .AXF .cci .CCI .cxi .CXI .elf .ELF .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=/data/data/%ANDROIDPACKAGE%/cores/citra_libretro_android.so %EXTRA_ROM%=%ROM% + %EMULATOR_CITRA% %ACTIVITY_NO_HISTORY% %EXTRA_SelectedGame%=%ROMSAF% + %EMULATOR_CITRA-MMJ% %EXTRA_GamePath%=%ROM% + n3ds + n3ds + + + psx + Sony PlayStation + %ROMPATH%/psx + .bin .BIN .cbn .CBN .ccd .CCD .chd .CHD .cue .CUE .ecm .ECM .exe .EXE .img .IMG .iso .ISO .m3u .M3U .mdf .MDF .mds .MDS .minipsf .MINIPSF .pbp .PBP .psexe .PSEXE .psf .PSF .toc .TOC .z .Z .znx .ZNX .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=mednafen_psx_libretro_android.so %EXTRA_ROM%=%ROM% + %EMULATOR_DUCKSTATION% %EXTRABOOL_resumeState%=false %EXTRA_bootPath%=%ROMSAF% + psx + psx + + +``` + +## es_systems_sorting.xml + +This file makes it possible to apply custom systems sorting without having to modify the es_systems.xml file directly. It should be placed in the custom_systems directory, e.g. `~/ES-DE/custom_systems/es_systems_sorting.xml` + +Note that in order for ES-DE to load this file you'll need to set the _Systems sorting_ option in the _UI settings_ menu to _Full names or custom_. + +The structure of this file is essentially a simplified version of the es_systems.xml file, but with only the `` and `` 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 + + + + amiga + 1985 + + + c64 + 1982 + + + vic20 + 1980 + + +``` + +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 `` 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. Secondary sorting will always be done by the fullname tag in es_systems.xml. + +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: + +* Release year +* Manufacturer, release year +* Hardware type, release year +* Manufacturer, hardware type, release year + +You can apply any of these sorting files via the _Systems sorting_ option in the _Other settings_ menu. Note that in order to load a es_systems_sorting.xml file placed in the custom_systems directory you'll need to set this option to _Full names or custom_. + ## gamelist.xml The gamelist.xml file for a system defines the metadata for its entries, such as the game names, descriptions, release dates and ratings. -As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game media is configurable either manually in `es_settings.xml` or via the GUI. If configured manually in es_settings.xml, it looks something like this: +As of the fork to ES-DE, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game media is configurable either manually in `es_settings.xml` or via the GUI. If configured manually in es_settings.xml, it looks something like this: ```xml - + ``` There is also support to add the variable %ESPATH% to the media directory setting, this will expand to the path where the ES-DE executable is started from. You should normally not need this, but the option is there for special cases. For example: @@ -1779,17 +1872,17 @@ There is also support to add the variable %ESPATH% to the media directory settin ``` -The default media directory is `~/.emulationstation/downloaded_media` +The default media directory is `~/ES-DE/downloaded_media` You can use ES-DE's scrapers to populate the gamelist.xml files, or manually update individual entries using the metadata editor. All of this is explained in the [User guide](USERGUIDE.md). -The gamelist.xml files are searched for in the ES-DE home directory, i.e. `~/.emulationstation/gamelists//gamelist.xml` +The gamelist.xml files are searched for in the ES-DE home directory, i.e. `~/ES-DE/gamelists//gamelist.xml` For example: ``` -~/.emulationstation/gamelists/c64/gamelist.xml -~/.emulationstation/gamelists/megadrive/gamelist.xml +~/ES-DE/gamelists/c64/gamelist.xml +~/ES-DE/gamelists/megadrive/gamelist.xml ``` **gamelist.xml file structure** @@ -1920,7 +2013,7 @@ Before attempting to add a custom profile for your controller you need to check ES-DE uses the [SDL](https://www.libsdl.org) (Simple DirectMedia Layer) library to handle controller input, so in order for a controller to work in ES-DE, it has to be supported by SDL. There is however a possibility to add custom controller profiles to SDL which in some cases could enable devices in ES-DE that would otherwise not be supported. This is generally a temporary solution though, as controller support is constantly getting improved natively in SDL. As a first step it's therefore recommended to open a request at the SDL [issue tracker](https://github.com/libsdl-org/SDL/issues) to have your specific controller added to a future SDL release. -Assuming the controller works in other applications than ES-DE, you can attempt to add a custom profile by creating the file `~/.emulationstation/es_controller_mappings.cfg` and enter the appropriate configuration inside this file. +Assuming the controller works in other applications than ES-DE, you can attempt to add a custom profile by creating the file `~/ES-DE/controllers/es_controller_mappings.cfg` and enter the appropriate configuration inside this file. The required format is described here:\ https://github.com/gabomdq/SDL_GameControllerDB @@ -1930,7 +2023,7 @@ https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontro But just do this as a first step to see whether you controller gets enabled. If it does, then you should remove all entries that are not relevant. That is important as this file will take precedence over the built-in controller profiles in the SDL library, so any future controller bug fixes and similar would not apply. In the past the gamecontrollerdb.txt file has also included some invalid configuration entries, so even though it may make your controller work, it could actually break some other controllers that you may want to use now or in the future. -Therefore only keep the entries in the es_controller_mappings.cfg file that are relevant for your devices. You can find each relevant controller GUID by starting ES-DE and then looking in the ~/.emulationstation/es_log.txt file. You should see entries such as the following: +Therefore only keep the entries in the es_controller_mappings.cfg file that are relevant for your devices. You can find each relevant controller GUID by starting ES-DE and then looking in the `~/ES-DE/logs/es_log.txt` file. You should see entries such as the following: ``` May 16 18:26:17 Info: Added controller with custom configuration: "X360 Controller" (GUID: 030000005e0400008e02000010010000, instance ID: 0, device index: 0) ``` @@ -1952,26 +2045,26 @@ For this example, let's assume that the removable media has the device name `F:\ These are the steps to perform: * Install ES-DE -* Copy the EmulationStation-DE installation directory to F:\ -* Create a directory named F:\EmulationStation-DE\Emulators -* Copy your emulator directories to F:\EmulationStation-DE\Emulators\ -* Copy your ROMs directory to F:\EmulationStation-DE\ -* Create an empty file named portable.txt in F:\EmulationStation-DE\ +* Copy the ES-DE installation directory to F:\ +* Create a directory named F:\ES-DE\Emulators +* Copy your emulator directories to F:\ES-DE\Emulators\ +* Copy your ROMs directory to F:\ES-DE\ +* Create an empty file named portable.txt in F:\ES-DE\ You should end up with something like this: ``` -F:\EmulationStation-DE\ -F:\EmulationStation-DE\Emulators\dosbox-staging\ -F:\EmulationStation-DE\Emulators\RetroArch-Win64\ -F:\EmulationStation-DE\Emulators\RPCS3\ -F:\EmulationStation-DE\Emulators\xemu\ -F:\EmulationStation-DE\ROMs\ -F:\EmulationStation-DE\portable.txt +F:\ES-DE\ +F:\ES-DE\Emulators\dosbox-staging\ +F:\ES-DE\Emulators\RetroArch-Win64\ +F:\ES-DE\Emulators\RPCS3\ +F:\ES-DE\Emulators\xemu\ +F:\ES-DE\ROMs\ +F:\ES-DE\portable.txt ``` -This is just an example as you may of course not use these specific emulators. There are also many more emulators supported as detailed in the `es_find_rules.xml` configuration file. As well there will be many more files and directories than those listed above inside the F:\EmulationStation-DE folder. +This is just an example as you may of course not use these specific emulators. There are also many more emulators supported as detailed in the `es_find_rules.xml` configuration file. As well there will be many more files and directories than those listed above inside the F:\ES-DE folder. -How the portable setup works is that when ES-DE finds a file named portable.txt in its executable directory, it will by default locate the .emulationstation directory directly inside this folder. It's also possible to modify portable.txt with a path relative to the ES-DE executable directory. For instance if two dots `..` are placed inside the portable.txt file, then the .emulationstation directory will be located in the parent folder, which would be directly under F:\ for this example. +How the portable setup works is that when ES-DE finds a file named portable.txt in its executable directory, it will by default locate the ES-DE application data directory directly inside this folder. It's also possible to modify portable.txt with a path relative to the ES-DE executable directory. For instance if two dots `..` are placed inside the portable.txt file, then the ES-DE application data directory will be located in the parent folder, which would be directly under F:\ for this example. If the --home command line parameter is passed when starting ES-DE, that will override the portable.txt file. @@ -1980,12 +2073,12 @@ Start ES-DE from the F:\ device and check that everything works as expected. Jus Following this, optionally copy any existing gamelist.xml files, game media files etc. to the removable media. For example: ``` -F:\EmulationStation-DE\.emulationstation\collections\ -F:\EmulationStation-DE\.emulationstation\downloaded_media\ -F:\EmulationStation-DE\.emulationstation\gamelists\ +F:\ES-DE\ES-DE\collections\ +F:\ES-DE\ES-DE\downloaded_media\ +F:\ES-DE\ES-DE\gamelists\ ``` -You could alternatively copy over your entire .emulationstation directory, but in this case make sure that you have no settings in es_settings.xml that point to a specific location on your local filesystem, such as the game ROMs or game media directories. +You could alternatively copy over your entire ES-DE application data directory, but in this case make sure that you have no settings in es_settings.xml that point to a specific location on your local filesystem, such as the game ROMs or game media directories. You now have a fully functional portable retrogaming installation! @@ -2028,7 +2121,7 @@ The following examples are for Unix systems, but it works the same way on macOS As can be seen in the table above, the events executed when a game starts and ends are named _game-start_ and _game-end_ -So let's create the folders for these events in the scripts directory. The location is `~/.emulationstation/scripts` +So let's create the folders for these events in the scripts directory. The location is `~/ES-DE/scripts` **Game log** @@ -2039,7 +2132,7 @@ Let's name the start script `game_start_logging.sh` with the following contents: ``` #!/bin/bash TIMESTAMP=$(date +%Y-%m-%d' '%H:%M:%S) -echo Starting game "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt +echo Starting game "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/ES-DE/logs/game_playlog.txt ``` And let's name the end script `game_end_logging.sh` with the following contents: @@ -2047,14 +2140,14 @@ And let's name the end script `game_end_logging.sh` with the following contents: ``` #!/bin/bash TIMESTAMP=$(date +%Y-%m-%d' '%H:%M:%S) -echo "Ending game " "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt +echo "Ending game " "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/ES-DE/logs/game_playlog.txt ``` After creating the two scripts, you should have something like this on the filesystem: ``` -~/.emulationstation/scripts/game-start/game_start_logging.sh -~/.emulationstation/scripts/game-end/game_end_logging.sh +~/ES-DE/scripts/game-start/game_start_logging.sh +~/ES-DE/scripts/game-end/game_end_logging.sh ``` Don't forget to make the scripts executable (e.g. "chmod 755 ./game_start_logging.sh"). @@ -2063,15 +2156,14 @@ If we now start ES-DE with the debug flag and launch a game, something like the ``` Aug 05 14:19:24 Debug: Scripting::fireEvent(): game-start "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" -Aug 05 14:19:24 Debug: Executing: /home/myusername/.emulationstation/scripts/game-start/game_start_logging.sh "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" +Aug 05 14:19:24 Debug: Executing: /home/myusername/ES-DE/scripts/game-start/game_start_logging.sh "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" . . Aug 05 14:27:15 Debug: Scripting::fireEvent(): game-end "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" "" -Aug 05 14:27:15 Debug: Executing: /home/myusername/.emulationstation/scripts/game-end/game_end_logging.sh "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" - +Aug 05 14:27:15 Debug: Executing: /home/myusername/ES-DE/scripts/game-end/game_end_logging.sh "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" "nes" "Nintendo Entertainment System" ``` -Finally after running some games, ~/.emulationstation/game_playlog.txt should contain something like the following: +Finally after running some games, ~/ES-DE/logs/game_playlog.txt should contain something like the following: ``` Starting game "The Legend Of Zelda" "Nintendo Entertainment System" ("/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip") at 2020-08-05 14:19:24 @@ -2099,7 +2191,7 @@ Then create the end script, which we'll name `set_resolution_4K.sh`: #!/bin/sh xrandr -s 3840x2160 sleep 0.3 -xdotool search --class emulationstation windowactivate +xdotool search --class es-de windowactivate ``` The last two lines are optional, they're used to set the focus back to ES-DE in case you're running attention-seeking applications such as Kodi which may steal focus after resolution changes. You may need to adjust the sleep time to get this to work reliably though, as the timing may differ between different computers and graphics drivers. @@ -2107,8 +2199,8 @@ The last two lines are optional, they're used to set the focus back to ES-DE in After creating the two scripts, you should have something like this on the filesystem: ``` -~/.emulationstation/scripts/game-start/set_resolution_1080p.sh -~/.emulationstation/scripts/game-end/set_resolution_4K.sh +~/ES-DE/scripts/game-start/set_resolution_1080p.sh +~/ES-DE/scripts/game-end/set_resolution_4K.sh ``` Don't forget to make the scripts executable (e.g. "chmod 755 ./set_resolution_1080p.sh"). diff --git a/THEMES-DEV.md b/THEMES-DEV.md index e29d521a4..cf78e75de 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -2,7 +2,7 @@ **Note:** This document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [THEMES.md](THEMES.md) instead. -If creating themes specifically for ES-DE, please add `-es-de` to the repository/directory name, as in `slate-es-de`. Themes made for ES-DE are not compatible with any other EmulationStation forks (and vice versa) and the -es-de extension makes it clear that it's an ES-DE theme. 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 themes from the _UI Settings_ menu. For example slate-es-de will be listed simply as _Slate_ in this menu. +If creating themes for ES-DE, please add `-es-de` to the repository/directory name to clearly indicate that it's a theme for this frontend. Two examples would be `linear-es-de` and `modern-es-de`. 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 themes from the _UI Settings_ menu. For example linear-es-de will be listed simply as _Linear_ in this menu. Before your start, make sure to download the _Theme engine examples_ theme that contains a number of example variants for things like vertical and horizontal carousels, wheel carousels, system view text lists, grids etc: diff --git a/THEMES.md b/THEMES.md index 50aee2746..28dea259d 100644 --- a/THEMES.md +++ b/THEMES.md @@ -1,6 +1,6 @@ -# ES-DE (EmulationStation Desktop Edition) v2.2 - Themes +# ES-DE (EmulationStation Desktop Edition) v3.0 - Themes -If creating themes specifically for ES-DE, please add `-es-de` to the repository/directory name, as in `slate-es-de`. Themes made for ES-DE are not compatible with any other EmulationStation forks (and vice versa) and the -es-de extension makes it clear that it's an ES-DE theme. 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 themes from the _UI Settings_ menu. For example slate-es-de will be listed simply as _Slate_ in this menu. +If creating themes for ES-DE, please add `-es-de` to the repository/directory name to clearly indicate that it's a theme for this frontend. Two examples would be `linear-es-de` and `modern-es-de`. 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 themes from the _UI Settings_ menu. For example linear-es-de will be listed simply as _Linear_ in this menu. Before your start, make sure to download the _Theme engine examples_ theme that contains a number of example variants for things like vertical and horizontal carousels, wheel carousels, system view text lists, grids etc: @@ -651,6 +651,95 @@ Here's an example configuration: ``` +## Font sizes + +The optional font sizes functionality makes it possible to use a set of predefined size options and connect these to theme variables that can be used to apply different text sizes and related design changes. The font sizes declared for the theme can be selected via the _Theme font size_ setting in the _UI Settings_ menu. + +To understand the basics on how to use variables, make sure to read the _Theme variables_ section elsewhere in this document. + +To use the font size entries you first need to declare them using `` tag pairs in the `capabilities.xml` file. The following sizes are available: + +| capabilities.xml name | UI Settings label | +| :-------------------- | :--------------- | +| medium | medium | +| large | large | +| small | small | +| x-large | extra large | +| x-small | extra small | + +The options will always be listed in the above order in the _UI Settings_ menu. + +Here's an example of a theme that implements three of these sizes: + +```xml + + + My theme + + medium + small + x-small + +``` + +In the theme configuration you'll also use a `` tag pair combined with a `` tag pair to define the variables you want to apply per font size. + +These `` tag pairs can be placed directly inside the `` tags, inside the `` tags or inside the `` tags. + +The mandatory name attribute is used to specificy which font size to use, and multiple values can be specified at the same time by separating them by commas or by whitespace characters (tabs, spaces or line breaks). + +Here's an example configuration: + +```xml + + + + 0.025 + 0.5 0.6437 + 0.022 + 0.016 + + + + + 0.015 + 0.45 0.6437 + 0.013 + + + + + 0.008 + 0.4 0.6437 + 0.006 + + + + 0.011 + + + + + + ${gameCounterPos} + 1 0.056 + ${gameCounterFontSize} + + + + 0.2 0.3412 + 0.2 0.040 + ${gameNameFontSize} + + + 0.33 0.3412 + 0.18 0.040 + ${publisherFontSize} + + + +``` + ## Aspect ratios The aspect ratio support works almost identically to the variants and color schemes with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme can still decide which of the aspect ratios to support (or none at all in which case the theme aspect ratio is left undefined) but it can't create entirely new aspect ratio entries. @@ -876,15 +965,18 @@ The variant, color scheme and transitions names as well as their labels can be s Unlike the types just mentioned, aspectRatio entries can not be set to arbitrary values, instead they have to use a value from the _horizontal name_ or _vertical name_ columns in the following table: -| Horizontal name | Vertical name | Common resolutions | -| :--------------- | :------------- | :--------------------------------------------- | -| 16:9 | 16:9_vertical | 1280x720, 1920x1080, 2560x1440, 3840x2160 | -| 16:10 | 16:10_vertical | 1280x800, 1440x900, 1920x1200 | -| 3:2 | 3:2_vertical | 2160x1440 | -| 4:3 | 4:3_vertical | 320x240, 640x480, 800x600, 1024x768, 1600x1200 | -| 5:4 | 5:4_vertical | 1280x1024 | -| 21:9 | 21:9_vertical | 2560x1080, 3840x1600, 5120x2160 | -| 32:9 | 32:9_vertical | 3840x1080, 5120x1440 | +| Horizontal name | Vertical name | Common resolutions | +| :--------------- | :-------------- | :--------------------------------------------- | +| 16:9 | 16:9_vertical | 1280x720, 1920x1080, 2560x1440, 3840x2160 | +| 16:10 | 16:10_vertical | 1280x800, 1440x900, 1920x1200 | +| 3:2 | 3:2_vertical | 2160x1440 | +| 4:3 | 4:3_vertical | 320x240, 640x480, 800x600, 1024x768, 1600x1200 | +| 5:4 | 5:4_vertical | 1280x1024 | +| 19.5:9 | 19.5:9_vertical | 2340x1080, 2532x1170 | +| 20:9 | 20:9_vertical | 2400x1080, 1600x720 | +| 21:9 | 21:9_vertical | 2560x1080, 3840x1600, 5120x2160 | +| 32:9 | 32:9_vertical | 3840x1080, 5120x1440 | +| 1:1 | 1:1 | Any square resolution | The 21:9 and 32:9 aspect ratios are approximate as monitors of slightly different ratios are collectively marketed using these numbers. @@ -1327,10 +1419,11 @@ It's important to understand how the theme configuration files are parsed in ord 1) Transitions 2) Variables 3) Color schemes -4) Included files -5) "General" (non-variant) configuration -6) Variants -7) Aspect ratios +4) Font sizes +5) Included files +6) "General" (non-variant) configuration +7) Variants +8) Aspect ratios When including a file using the `` tag (i.e. step 4 above) then all steps listed above are executed for that included file prior to continuing to the next line after the `` tag. @@ -1339,7 +1432,7 @@ For any given step, the configuration is parsed in the exact order that it's def ## Property data types * NORMALIZED_PAIR - two decimal values delimited by a space, for example `0.25 0.5` -* PATH - path to a resource. If the first character is a tilde (`~`) then it will be expanded to the user's home directory (`$HOME` for Unix and macOS and `%HOMEPATH%` for Windows) unless overridden using the --home command line option. If the first character is a dot (`.`) then the resource will be searched for relative to the location of the theme file, for example `./myfont.ttf` or `./../core/fonts/myfont.ttf` +* PATH - path to a resource. If the first character is a tilde (`~`) then it will be expanded to the user's home directory (`$HOME` for Linux, BSD Unix and macOS and `%HOMEPATH%` for Windows) unless overridden using the --home command line option. If the first character is a dot (`.`) then the resource will be searched for relative to the location of the theme file, for example `./myfont.ttf` or `./../core/fonts/myfont.ttf` * BOOLEAN - `true`/`1` or `false`/`0` * COLOR - a hexadecimal RGB or RGBA color value consisting of 6 or 8 digits. If a 6 digit value is used then the alpha channel will be set to `FF` (completely opaque) * UNSIGNED_INTEGER - an unsigned integer value @@ -1912,6 +2005,10 @@ Properties: - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the textlist exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is `0` and maximum value per axis is `1` - Default is `0 0` +* `selectorWidth` - type: FLOAT + - Width of the selector bar. If an image has been defined using `selectorImagePath` then setting this property to zero will retain the aspect ratio for that image. + - Minimum value is `0` and maximum value is `1` + - Default is the equivalent value as the width of the overall element. * `selectorHeight` - type: FLOAT - Height of the selector bar. This is expanded downwards so you'll probably want to adjust its position using `selectorVerticalOffset` if making use of this property. - Minimum value is `0` and maximum value is `1` @@ -2073,6 +2170,10 @@ Properties: - `always` - Set element as stationary during all transitions. - `never` - Don't set element as stationary during any transitions. - Default is `never` +* `renderDuringTransitions` - type: BOOLEAN + - This special property which is only usable for slide transitions between the system and gamelist views makes it possible to for example have a background image stay seamlessly in place when transitioning, or being able to use semi-transparent stationary elements without having them render on top of each other during transitions. For this to work correctly only define `stationary` for one view and set `renderDuringTransitions` to false for the corresponding element in the other view. This way the element from the former view will keep rendering until the slide animation has been completed, after which the latter view will "take over" by rendering the element normally. + - This property can only be used if slide transitions are used, and only when moving from the system view to the gamelist view, or vice versa. + - Default is `true` * `flipHorizontal` - type: BOOLEAN - Flips the image texture horizontally. - Default is `false` @@ -2643,7 +2744,7 @@ Properties: - `sourceSystemName` - The source short system name of the game. For regular systems this value will be identical to `systemName` but for collections it will show the actual system that the game is located in instead of the collection system name. - `sourceSystemFullname` - The source full system name of the game. For regular systems this value will be identical to `systemFullname` but for collections it will show the actual system that the game is located in instead of the collection system name. * `defaultValue` - type: STRING - - This property makes it possible to override the default "unknown" text that is displayed if `metadata` has been set to `developer`, `publisher`, `genre` or `players` and there is no metadata available for the defined type. Any string can be used but you can't set it to a blank value. If you don't want to display anything when there is no metadata available, then set this property to `:space:` in which case a blankspace will be used. This property has no effect on the metadata editor where "unknown" will still be shown for blank values. + - This property makes it possible to override the default "unknown" text that is displayed if `metadata` has been set to `developer`, `publisher`, `genre` or `players` and there is no metadata available for the defined type. Any string can be used but you can't set it to a blank value. If you don't want to display anything when there is no metadata available, then set this property to `:space:` in which case a blankspace will be used. This property has no effect on the metadata editor where "unknown" will still be shown for blank values. A secondary use for this property is to set a default value if `metadata` has been set to `systemName`, `systemFullname`, `sourceSystemName` or `sourceSystemFullname` in which case the value will be used if the metadata value is blank. This is useful for defining a specific string at the root of the custom collections system. * `systemNameSuffix` - type: BOOLEAN - Whether to add the system name in square brackets after the game name when inside a collection system (automatic as well as custom collections). If `metadata` has been set to `description` then this property will only apply when inside the root of the grouped custom collections system where a summary of available games for the currently selected collection is displayed. - Default is `true` @@ -2924,6 +3025,9 @@ Properties: - `always` - Set element as stationary during all transitions. - `never` - Don't set element as stationary during any transitions. - Default is `never` +* `hideIfZero` - type: BOOLEAN + - If set to true then the element will not get rendered if the rating value is zero. + - Default is `false` * `gameselector` - type: STRING - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view. * `gameselectorEntry` - type: UNSIGNED_INTEGER @@ -2988,7 +3092,6 @@ Properties: The helpsystem is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Note that this element does not have a zIndex value, instead it's always rendered on top of all other elements. It also has to have its name attribute set to `help` or the configuration will not get loaded. - It's possible to set this element as right-aligned or center-aligned using a combination of the `pos` and `origin` properties. For example `1 1` and `1 1` will place it in the lower right corner of the screen. Keep in mind that the width of this element can vary depending on a number of factors, for example the _Toggle favorites_ and _Random system or game_ buttons can be enabled or disabled via the _UI Settings_ menu. Test extensively with the menu system as well, especially the virtual keyboard which displays a number of helpsystem entries. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 7b3d1f397..18a62fe3f 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -324,26 +324,13 @@ Instructions on how to customize the es_systems.xml file can be found in [INSTAL In addition to the above it's also possible to customize the find rules via the `es_find_rules.xml` file. The logic is essentially identical to what is described for es_systems.xml, and details regarding this file can be found in [INSTALL-DEV.md](INSTALL-DEV.md#es_find_rulesxml) as well. -## Migrating from other EmulationStation forks +## Migrating from EmulationStation **IMPORTANT!!! IMPORTANT!!! IMPORTANT!!!** -ES-DE is designed to be backward compatible to a certain degree. That is, it should be able to read data from other/previous EmulationStation versions such as the RetroPie and Batocera forks. But the opposite is not true and it's a one-way ticket for your gamelist.xml files and your custom collection files when migrating to ES-DE as they will be modified in ways that previous ES versions will see as data loss. For instance ES-DE does not use tags inside the gamelist.xml files to find game media but instead matches the media to the names of the game/ROM files. So it will not save any such tags back to the gamelist files during updates, effectively disabling the game media if the files are opened in another ES fork. +ES-DE is partially compatible with EmulationStation as both frontends originally shared the same source code. That is, ES-DE should generally be able to read data from EmulationStation. But the opposite is not true and it's a one-way ticket for your gamelist.xml files and your custom collection files when migrating to ES-DE as they will be modified in ways that EmulationStation will see as data loss. For instance ES-DE does not use tags inside the gamelist.xml files to find game media but instead matches the media to the names of the game/ROM files. So it will not save any such tags back to the gamelist files during updates, effectively disabling the game media if the files are opened in EmulationStation. -Due to this, always make backups of at least the following directories before testing ES-DE for the first time: - -``` -~/ES-DE/gameslists/ -~/ES-DE/collections/ -``` - -If you have gamelist.xml files in your ROMs directory tree then ES-DE will ignore those by default, so you need to move them to the ~/ES-DE/gamelists/ tree. - -It's also strongly adviced to not rename an old es_settings.cfg file to es_settings.xml for use in ES-DE as it may cause undefined behavior and crashes. - -If migrating from Batocera, RetroBat or Recalbox, be aware that ES-DE follows the RetroPie naming conventions for most game systems. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera, RetroBat and Recalbox has the _sg1000_ system name, but is _sg-1000_ in RetroPie and ES-DE. See the [Supported game systems](USERGUIDE-DEV.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE. - -Another potential issue when migrating from another EmulationStation fork is that the path tag requires a leading ./ in ES-DE while that may not be present in other forks. If you don't see any metadata for your games inside ES-DE, then simply add the ./ characters to each path tag and it should hopefully work. +Another potential issue when migrating gamelist.xml files from EmulationStation is that the path tag requires a leading ./ in ES-DE while that may not be present in files coming from EmulationStation. If you don't see any metadata for your games inside ES-DE, then simply add the ./ characters to each path tag and it should hopefully work. Example of an unreadable path tag: ``` @@ -355,6 +342,11 @@ Example of a correct path tag readable by ES-DE: ./Another World.lha ``` +And if you have gamelist.xml files in your ROMs directory tree then ES-DE will ignore those by default, so you need to move them to the ~/ES-DE/gamelists/ tree. + +If migrating from Batocera, RetroBat or Recalbox, be aware that ES-DE does not always use the same system names as those frontends. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera, RetroBat and Recalbox has the _sg1000_ system name, but is _sg-1000_ in ES-DE. See the [Supported game systems](USERGUIDE-DEV.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE. + + ## Removing orphaned data Manually removing game files from the ROMs directory tree instead of deleting them from ES-DE using the metadata editor will make any corresponding scraped media files, gamelist.xml entries and custom collection entries orphaned, i.e. they will refer to non-existent files. Although this is correctly handled by ES-DE and is not causing any serious issues, it does lead to unnecessary disk space usage and it does produce log warnings in es_log.txt on application startup. If a huge amount of game files have been manually removed it can also lead to performance problems. diff --git a/USERGUIDE.md b/USERGUIDE.md index b223f973d..deb4a9e09 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -1,4 +1,4 @@ -# ES-DE (EmulationStation Desktop Edition) v2.2 - User guide +# ES-DE (EmulationStation Desktop Edition) v3.0 - 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. @@ -36,12 +36,12 @@ The installation procedure is just covered briefly here and may differ a bit for The AppImage release should be usable on most modern x86 64-bit Linux distributions. After download you may have to set the file as executable, such as this: ``` -chmod +x EmulationStation-DE-x64.AppImage +chmod +x ES-DE_x64.AppImage ``` Or if you're using the Steam Deck AppImage: ``` -chmod +x EmulationStation-DE-x64_SteamDeck.AppImage +chmod +x ES-DE_x64_SteamDeck.AppImage ``` To run AppImage files you need libfuse2 installed, but some newer distributions like Ubuntu 22.04 LTS no longer ship with this library preinstalled. You can however easily install it like this: @@ -57,11 +57,11 @@ There's not really much to say about these operating systems, just install ES-DE **On first application startup** -Upon first startup, ES-DE will create its `~/.emulationstation` home directory. +Upon first startup, ES-DE will create its `~/ES-DE` application data directory. -On Unix this means `/home//.emulationstation`, on macOS `/Users//.emulationstation` and on Windows `C:\Users\\.emulationstation` or `EmulationStation-DE\.emulationstation` depending on whether the installer release or the portable release is used. +On Linux this means `/home//ES-DE`, on macOS `/Users//ES-DE` and on Windows `C:\Users\\ES-DE` or `ES-DE\ES-DE` depending on whether the installer release or the portable release is used. -Also on first startup the configuration file `es_settings.xml` will be generated in the ES-DE home directory, containing all the application settings at their default values. Following this, a file named `es_systems.xml` will be loaded from the resources directory (which is part of the ES-DE installation). This file contains the game system definitions including which emulator to use per platform. For many systems there are also alternative emulators defined which can be applied system-wide or per game. How that works is explained later in this guide. A customized systems configuration file can also be used, as described in the next section below. +Also on first startup the configuration file `es_settings.xml` will be generated in the `ES-DE/settings` directory, containing all the application settings at their default values. Following this, a file named `es_systems.xml` will be loaded from the resources directory (which is part of the ES-DE installation). This file contains the game system definitions including which emulator to use per platform. For many systems there are also alternative emulators defined which can be applied system-wide or per game. How that works is explained later in this guide. A customized systems configuration file can also be used, as described in the next section below. In addition to es_systems.xml there's an `es_find_rules.xml` file that gets loaded as well and which contains rules on how to locate the emulators, i.e. how to find out where they've been installed. @@ -69,7 +69,7 @@ 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 ROM directory. You will also be given a choice to change that ROM 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 _dos_ 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 Linux: ``` System name: dos @@ -111,18 +111,18 @@ epic: Epic Games Store famicom: Nintendo Family Computer ``` -If a custom es_systems.xml file is present in ~/.emulationstation/custom_systems/ any entries from this file will have their names trailed by the text _(custom system)_. So if the _dos_ system in the example above would be present in the custom systems configuration file, the system would be shown as _dos (custom system)_ instead of simply _dos_. This is only applicable for the systems.txt and systeminfo.txt files, the trailing text is not applied or used anywhere else in the application. +If a custom es_systems.xml file is present in ~/ES-DE/custom_systems/ any entries from this file will have their names trailed by the text _(custom system)_. So if the _dos_ system in the example above would be present in the custom systems configuration file, the system would be shown as _dos (custom system)_ instead of simply _dos_. This is only applicable for the systems.txt and systeminfo.txt files, the trailing text is not applied or used anywhere else in the application. ![alt text](images/es-de_ui_easy_setup.png "ES-DE Easy Setup") _This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._ ## Upgrading to a newer release -**Note:** Before upgrading ES-DE, make sure that you have not made any system customizations anywhere in the installation directory structure as these files will be overwritten during the upgrade process. All customizations should go into ~/.emulationstation/custom_systems/ as described elsewhere in this guide. None of the upgrade methods mentioned below will ever touch any files inside your .emulationstation directory tree. +**Note:** Before upgrading ES-DE, make sure that you have not made any system customizations anywhere in the installation directory structure as these files will be overwritten during the upgrade process. All customizations should go into ~/ES-DE/custom_systems/ as described elsewhere in this guide. None of the upgrade methods mentioned below will ever touch any files inside your ES-DE directory tree. -There is a built-in application updater that can automatically update the Linux AppImage releases, and as of ES-DE 2.2.0 there is also support for downloading the Windows and macOS packages. Just be aware that these will still need to be manually installed. Using the application updater is straightforward, just follow the on-screen instructions. For the AppImage releases the old file is retained by renaming it, adding its version to the filename followed by the .OLD extension, for example `EmulationStation-DE-x64_SteamDeck.AppImage_2.1.0.OLD` +There is a built-in application updater that can automatically update the Linux AppImage releases, and as of ES-DE 2.2.0 there is also support for downloading the Windows and macOS packages. Just be aware that these will still need to be manually installed. Using the application updater is straightforward, just follow the on-screen instructions. For the AppImage releases the old file is retained by renaming it, adding its version to the filename followed by the .OLD extension, for example `ES-DE_x64_SteamDeck.AppImage_3.0.0.OLD` -Note that the updater will keep whatever filename you had for your running AppImage file, which could potentially be confusing if you for example added version information to the filename. It's always recommend to keep the default AppImage filenames, i.e. `EmulationStation-DE-x64.AppImage` and `EmulationStation-DE-x64_SteamDeck.AppImage` +Note that the updater will keep whatever filename you had for your running AppImage file, which could potentially be confusing if you for example added version information to the filename. It's always recommend to keep the default AppImage filenames, i.e. `ES-DE_x64.AppImage` and `ES-DE_x64_SteamDeck.AppImage` On Windows and macOS you can specify to which directory you want to save the downloaded file. The default is `C:\Users\myusername\Downloads` on Windows and `/Users/myusername/Downloads` on macOS. @@ -143,7 +143,7 @@ AUR upgrades should be automatically handled via your package manager and it sho **macOS** -Open _Applications_ in Finder and right click on _EmulationStation Desktop Edition_ and choose _Move to Trash_. Then simply install the new release using the .dmg drag-and-drop installer. +Open _Applications_ in Finder and right click on _ES-DE_ and choose _Move to Trash_. Then simply install the new release using the .dmg drag-and-drop installer. **Windows installer** @@ -164,7 +164,7 @@ In theory it's possible to make a custom system entry and hardcode the path to a If you really insist on not placing your games into the ES-DE standard directory structure, a much better solution is to symlink the game directories into the standard directory. In this way you don't need to make a custom es_systems.xml file and any additional emulators and other configuration added to future ES-DE releases will just work after upgrading. -This is an example of symlinking the Super Nintendo game directory on Unix and macOS: +This is an example of symlinking the Super Nintendo game directory on Linux and macOS: ``` cd ~/ROMs ln -s ~/my_games/super_nintendo/ snes @@ -189,7 +189,7 @@ Note that if the setting _Only show games from gamelist.xml files_ has been enab ## Placing games and other resources on network shares -Although ES-DE does support placing game ROMs, the `.emulationstation` home directory and the `downloaded_media` directory on network shares, this can lead to serious performance problems in some instances. Especially problematic is the Microsoft SMB protocol as it offers abysmal performance for some disk operations on which ES-DE relies heavily. For small game libraries this can still be acceptable, but for libraries with hundreds or thousands of games the application startup time and overall usage will be very painful or even unusable. Similar issues could occur when using file hosting services like Google Drive. +Although ES-DE does support placing game ROMs, the `ES-DE` application data directory and the `downloaded_media` directory on network shares, this can lead to serious performance problems in some instances. Especially problematic is the Microsoft SMB protocol as it offers abysmal performance for some disk operations on which ES-DE relies heavily. For small game libraries this can still be acceptable, but for libraries with hundreds or thousands of games the application startup time and overall usage will be very painful or even unusable. Similar issues could occur when using file hosting services like Google Drive. A general recommendation is to place all game files and other data on drives connected directly to the machine where ES-DE is running. Even using low speed technology like USB thumb drives, SD cards etc. is generally fine and leads to acceptable performance in most instances. @@ -231,7 +231,7 @@ In order for ES-DE to run, graphics drivers with OpenGL support have to be insta On some GPUs with buggy drivers, ES-DE may only display a black screen on startup or when launching a game. The problem can be worked around by specifying a window size for ES-DE that is a single pixel wider than the actual screen resolution. So for example for a 1280x800 display, the resolution can be set to 1281x800 and then rendering should work correctly. This is applied using the --resolution command line option, for example: ``` -EmulationStation.exe --resolution 1281 800 +ES-DE.exe --resolution 1281 800 ``` Some computers using Intel Iris Xe GPUs refuse to start ES-DE or display excessive graphics corruption. These problems are seemingly caused by driver bugs and do not occur when using Linux with the same hardware. There is no known solution or workaround to this issue other than switching to Linux or waiting for Intel to resolve the problem with a driver update. @@ -252,7 +252,7 @@ If you want to create your own portable intallation from scratch or customize th A number of systems have alternative emulator entries named _Shortcut or script_ which allows the direct execution of .lnk shortcut files or .bat batch files. It's not possible by default to directly launch .ps1 PowerShell scripts. As running PowerShell scripts is not even enabled by default on Windows they are for sure not recommended. If you still want to use them the best approach is to execute them via either a .lnk shortcut file or a .bat wrapper script where you explicitly call powershell.exe with the -command flag. If you instead insist on running them directly from ES-DE, you'll need to add a custom system or find rule configuration where you execute powershell.exe instead of cmd.exe and you'll also need to add .ps1 as a file extension for each relevant system. -Some disk operations can have abysmal performance on Windows, and this may be especially obvious for the theme downloader. This is often caused by anti-virus software like Microsoft Defender. If it takes say 30 seconds rather than 300 milliseconds to open the theme downloader then it may be a good idea to add an exlusion for the .emulationstation\themes\ directory to Microsoft Defender. The same may also be true for other directories like the ROMs folder if disk performance is terrible. Refer to your anti-virus software documentation on how to setup such exclusions. +Some disk operations can have abysmal performance on Windows, and this may be especially obvious for the theme downloader. This is often caused by anti-virus software like Microsoft Defender. If it takes say 30 seconds rather than 300 milliseconds to open the theme downloader then it may be a good idea to add an exlusion for the ES-DE\themes\ directory to Microsoft Defender. The same may also be true for other directories like the ROMs folder if disk performance is terrible. Refer to your anti-virus software documentation on how to setup such exclusions. ## Specific notes for macOS @@ -268,13 +268,11 @@ At the time of writing there is an additional issue with the ARM release of Retr The first time you launch a RetroArch-emulated game from within ES-DE the operating system will present you with a security option with the following description: -`"EmulationStation Desktop Edition" would like to access files in your Documents folder.` +`"ES-DE" would like to access files in your Documents folder.` If you don't allow this, you will not be able to place system BIOS ROMs in the RetroArch default system directory `~/Documents/RetroArch/system` even if you've already given RetroArch access to this folder. This is so because RetroArch runs as a subprocess to ES-DE and therefore inherits the security settings from the parent application. Attempting to launch a game without enabling the access will simply display an error message in the emulator that the BIOS files are missing. This of course only applies to emulators that require BIOS ROMs, all other games should work fine regardless of this security setting. -If you accidentally refused ES-DE the folder access, you can fix this by opening _System Settings_, selecting _Privacy & Security_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _EmulationStation Desktop Edition_. - -By default files and directories starting with a dot are hidden on macOS, so to show the .emulationstation directory in your home directory you need to enable hidden files in Finder. You do this using the keyboard combination Shift + Command + . (dot). +If you accidentally refused ES-DE the folder access, you can fix this by opening _System Settings_, selecting _Privacy & Security_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _ES-DE_. A minor annoyance is that macOS creates metadata files starting with ._ in the filename when placing game/ROM files on some filesystem types such as exFAT. This means that you will see double entries inside ES-DE for all such games. To hide these extra files, the option _Show hidden files and folders (requires restart)_ in the _Other settings_ menu can be set to disabled. @@ -288,12 +286,16 @@ It's also possible to install ES-DE using [EmuDeck](https://www.emudeck.com) whi 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. -If you are unfamiliar with Unix operating systems, make sure to at least read up on the concepts of _dotfiles_ (hidden files and directories), _home directories_ (including use of the tilde ~ character) and _symbolic links_ (symlinks): +If you are unfamiliar with Linux/Unix operating systems, make sure to at least read up on the concepts of _dotfiles_ (hidden files and directories), _home directories_ (including use of the tilde ~ character) and _symbolic links_ (symlinks): [https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory#Unix_and_Unix-like_environments](https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory#Unix_and_Unix-like_environments) \ [https://en.wikipedia.org/wiki/Home_directory#Unix](https://en.wikipedia.org/wiki/Home_directory#Unix) \ [https://en.wikipedia.org/wiki/Symbolic_link](https://en.wikipedia.org/wiki/Symbolic_link) +## Specific notes for Android + +The Android port of ES-DE is quite different than the other versions, so it has its specifics covered by a dedicated [ANDROID.md](ANDROID.md) document. + ## Specific notes for Raspberry Pi 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. @@ -308,9 +310,9 @@ In general, 720p works fine with the RPi 4, and 1080p is tolerable but not reall The game systems configuration file `es_systems.xml` is located in the ES-DE resources directory which is part of the application installation. As such this file is not intended to be modified directly. If system customizations are required, a separate es_systems.xml file should instead be placed in the `custom_systems` folder in the ES-DE home directory. -On Unix this means `/home//.emulationstation/custom_systems/es_systems.xml`, on macOS `/Users//.emulationstation/custom_systems/es_systems.xml` and on Windows `C:\Users\\.emulationstation\custom_systems\es_systems.xml` or `EmulationStation-DE\.emulationstation\custom_systems\es_systems.xml` depending on whether the installer release or the portable release is used. +On Linux this means `/home//ES-DE/custom_systems/es_systems.xml`, on macOS `/Users//ES-DE/custom_systems/es_systems.xml` and on Windows `C:\Users\\ES-DE\custom_systems\es_systems.xml` or `ES-DE\ES-DE\custom_systems\es_systems.xml` depending on whether the installer release or the portable release is used. -If you're using the AppImage release of ES-DE then the bundled es_systems.xml file is embedded in the AppImage together with the rest of the resources. You can extract it if you need it as a reference when creating your customized entries, or you can find it [here](https://gitlab.com/es-de/emulationstation-de/-/tree/master/resources/systems/unix). +If you're using the AppImage release of ES-DE then the bundled es_systems.xml file is embedded in the AppImage together with the rest of the resources. You can extract it if you need it as a reference when creating your customized entries, or you can find it [here](https://gitlab.com/es-de/emulationstation-de/-/tree/master/resources/systems/linux). Although it's possible to make a copy of the bundled configuration file, to modify it and then place it in this directory, that is not how the system customization is designed to be used. Instead the intention is that the file in `custom_systems` complements the bundled configuration, meaning only systems that are to be customized should be included. @@ -320,26 +322,13 @@ Instructions on how to customize the es_systems.xml file can be found in [INSTAL In addition to the above it's also possible to customize the find rules via the `es_find_rules.xml` file. The logic is essentially identical to what is described for es_systems.xml, and details regarding this file can be found in [INSTALL.md](INSTALL.md#es_find_rulesxml) as well. -## Migrating from other EmulationStation forks +## Migrating from EmulationStation **IMPORTANT!!! IMPORTANT!!! IMPORTANT!!!** -ES-DE is designed to be backward compatible to a certain degree. That is, it should be able to read data from other/previous EmulationStation versions such as the RetroPie and Batocera forks. But the opposite is not true and it's a one-way ticket for your gamelist.xml files and your custom collection files when migrating to ES-DE as they will be modified in ways that previous ES versions will see as data loss. For instance ES-DE does not use tags inside the gamelist.xml files to find game media but instead matches the media to the names of the game/ROM files. So it will not save any such tags back to the gamelist files during updates, effectively disabling the game media if the files are opened in another ES fork. +ES-DE is partially compatible with EmulationStation as both frontends originally shared the same source code. That is, ES-DE should generally be able to read data from EmulationStation. But the opposite is not true and it's a one-way ticket for your gamelist.xml files and your custom collection files when migrating to ES-DE as they will be modified in ways that EmulationStation will see as data loss. For instance ES-DE does not use tags inside the gamelist.xml files to find game media but instead matches the media to the names of the game/ROM files. So it will not save any such tags back to the gamelist files during updates, effectively disabling the game media if the files are opened in EmulationStation. -Due to this, always make backups of at least the following directories before testing ES-DE for the first time: - -``` -~/.emulationstation/gameslists/ -~/.emulationstation/collections/ -``` - -If you have gamelist.xml files in your ROMs directory tree then ES-DE will ignore those by default, so you need to move them to the ~/.emulationstation/gamelists/ tree. - -It's also strongly adviced to not rename an old es_settings.cfg file to es_settings.xml for use in ES-DE as it may cause undefined behavior and crashes. - -If migrating from Batocera, RetroBat or Recalbox, be aware that ES-DE follows the RetroPie naming conventions for most game systems. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera, RetroBat and Recalbox has the _sg1000_ system name, but is _sg-1000_ in RetroPie and ES-DE. See the [Supported game systems](USERGUIDE.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE. - -Another potential issue when migrating from another EmulationStation fork is that the path tag requires a leading ./ in ES-DE while that may not be present in other forks. If you don't see any metadata for your games inside ES-DE, then simply add the ./ characters to each path tag and it should hopefully work. +Another potential issue when migrating gamelist.xml files from EmulationStation is that the path tag requires a leading ./ in ES-DE while that may not be present in files coming from EmulationStation. If you don't see any metadata for your games inside ES-DE, then simply add the ./ characters to each path tag and it should hopefully work. Example of an unreadable path tag: ``` @@ -351,11 +340,16 @@ Example of a correct path tag readable by ES-DE: ./Another World.lha ``` +And if you have gamelist.xml files in your ROMs directory tree then ES-DE will ignore those by default, so you need to move them to the ~/ES-DE/gamelists/ tree. + +If migrating from Batocera, RetroBat or Recalbox, be aware that ES-DE does not always use the same system names as those frontends. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera, RetroBat and Recalbox has the _sg1000_ system name, but is _sg-1000_ in ES-DE. See the [Supported game systems](USERGUIDE.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE. + + ## Removing orphaned data Manually removing game files from the ROMs directory tree instead of deleting them from ES-DE using the metadata editor will make any corresponding scraped media files, gamelist.xml entries and custom collection entries orphaned, i.e. they will refer to non-existent files. Although this is correctly handled by ES-DE and is not causing any serious issues, it does lead to unnecessary disk space usage and it does produce log warnings in es_log.txt on application startup. If a huge amount of game files have been manually removed it can also lead to performance problems. -In order to remove such unnecessary media files and configuration file entries, the _Orphaned data cleanup_ utility in the _Utilities_ menu can be used. This tool should be largely self-explanatory. And although it should generally be safe to use, unforeseen issues can occur so make sure to make backups of at least your `.emulationstation/gamelists` and `.emulationstation/collections` directories before attempting to use this tool. +In order to remove such unnecessary media files and configuration file entries, the _Orphaned data cleanup_ utility in the _Utilities_ menu can be used. This tool should be largely self-explanatory. And although it should generally be safe to use, unforeseen issues can occur so make sure to make backups of at least your `ES-DE/gamelists` and `ES-DE/collections` directories before attempting to use this tool. It's recommended to run this utility with the _Show hidden games_ setting enabled as orphaned gamelist.xml folder entries may otherwise not get purged. @@ -365,17 +359,17 @@ Note that there are no guarantees that any processed gamelist.xml files will be If the utility finds any data to be removed, a backup of the old files will be made. This will end up in a `CLEANUP` directory and will contain a date and time stamp. For example: ``` -~/.emulationstation/gamelists/CLEANUP/2023-07-27_142830/dos/gamelist.xml -~/.emulationstation/gamelists/CLEANUP/2023-07-27_142830/ports/gamelist.xml -~/.emulationstation/collections/CLEANUP/2023-07-27_143216/custom-Action.cfg -~/.emulationstation/collections/CLEANUP/2023-07-27_143216/custom-Fighting.cfg -~/.emulationstation/downloaded_media/CLEANUP/2023-07-27_123406/atari2600/titlescreens/H.E.R.O..png -~/.emulationstation/downloaded_media/CLEANUP/2023-07-27_123406/c64/3dboxes/Minerer 2049.crt.png +~/ES-DE/gamelists/CLEANUP/2023-07-27_142830/dos/gamelist.xml +~/ES-DE/gamelists/CLEANUP/2023-07-27_142830/ports/gamelist.xml +~/ES-DE/collections/CLEANUP/2023-07-27_143216/custom-Action.cfg +~/ES-DE/collections/CLEANUP/2023-07-27_143216/custom-Fighting.cfg +~/ES-DE/downloaded_media/CLEANUP/2023-07-27_123406/atari2600/titlescreens/H.E.R.O..png +~/ES-DE/downloaded_media/CLEANUP/2023-07-27_123406/c64/3dboxes/Minerer 2049.crt.png ``` This means that you will need to manually delete these backup directories to free up disk space when you are certain that you no longer need the data. -All files and entries that are removed are logged to `~/.emulationstation/es_log.txt` so it could be a good idea to make a backup copy of this file after running the cleanup, for future reference. +All files and entries that are removed are logged to `~/ES-DE/logs/es_log.txt` so it could be a good idea to make a backup copy of this file after running the cleanup, for future reference. Any media directories that are empty after the cleanup will also be removed by this utility. @@ -388,7 +382,7 @@ _The Orphaned data cleanup utility after successfully removing some gamelist.xml ES-DE fully supports high resolution displays such as 1440p, 4K, 6K, 8K, ultrawide monitors etc. But many emulators (e.g. RetroArch) will also run using the same resolution which may cause performance problems on slower machines or when using resource intensive shaders. Although some emulator cores will have options to set their internal resolution, they still need to be scaled up to the screen resolution. -A solution to this is to use the custom event scripts functionality to set a temporary resolution upon launching a game that will be reverted when returning to ES-DE. Such a setup is detailed in [INSTALL.md](INSTALL.md#custom-event-scripts) for Unix, but should hopefully be possible to implement similarly on Windows. When going for this setup it's important that the setting _Run in background (while game is launched)_ is disabled or ES-DE may not be able to correctly switch to the emulator window when launching games. +A solution to this is to use the custom event scripts functionality to set a temporary resolution upon launching a game that will be reverted when returning to ES-DE. Such a setup is detailed in [INSTALL.md](INSTALL.md#custom-event-scripts) for Linux, but should hopefully be possible to implement similarly on Windows. When going for this setup it's important that the setting _Run in background (while game is launched)_ is disabled or ES-DE may not be able to correctly switch to the emulator window when launching games. On macOS it's problematic to change screen resolutions on the fly or on a per-application basis as Apple has seemingly disabled most of this functionality in recent operating system releases. The only real option here is to lower the display resolution prior to launching ES-DE. @@ -402,22 +396,22 @@ Below are some examples. For consistency it's assumed that the display resolutio Running at a lower application resolution in a window: ``` -emulationstation --resolution 1280 720 +es-de --resolution 1280 720 ``` Running at a lower application resolution in padded fullscreen mode: ``` -emulationstation --resolution 1824 1026 --fullscreen-padding 1 +es-de --resolution 1824 1026 --fullscreen-padding 1 ``` Same as above but also offsetting the screen slightly to the left and downwards: ``` -emulationstation --resolution 1824 1026 --fullscreen-padding 1 --screenoffset -40 22 +es-de --resolution 1824 1026 --fullscreen-padding 1 --screenoffset -40 22 ``` Rotate application screen contents 90 degrees while running at the native 1920x1080 screen resolution: ``` -emulationstation --screenrotate 90 +es-de --screenrotate 90 ``` ## Input device configuration @@ -430,7 +424,7 @@ The actual procedure to map the inputs should be self-explanatory, just follow t Any custom configuration is applied per unique device ID (GUID). So if two identical controllers are used with ES-DE, both will have the same configuration applied. If connecting controllers of the same type but of different revisions, the GUID may differ and therefore the custom configuration would need to be applied to each device individually. -If you have issues with your input configuration, as a last resort you can reset all mappings by deleting or renaming the file `~/.emulationstation/es_input.xml` +If you have issues with your input configuration, as a last resort you can reset all mappings by deleting or renaming the file `~/ES-DE/settings/es_input.xml` ## System view (main screen) @@ -488,6 +482,8 @@ When editing text it's also possible to paste from the clipboard into ES-DE usin Default keyboard mappings are shown in brackets below. +It's assumed that the option _Swap the A/B and X/Y buttons_ in the _Input device settings_ menu is disabled as some buttons will otherwise obviously be swapped. + **Up and down**\ _(Arrow up / Arrow down)_ @@ -539,7 +535,7 @@ _(Delete)_ Starts the media viewer in the gamelist view or the screensaver in the system view (if the _Enable screensaver controls_ setting is enabled). Used by some other minor functions as explained by the help system and/or this guide. **Y button**\ -_(Insert on Unix and Windows, F13 on macOS)_ +_(Insert on Linux and Windows, F13 on macOS)_ Marks games as favorites in the gamelist view (if the _Enable toggle favorites button_ option has been enabled). Used by some other minor functions as explained by the help system and/or this guide. @@ -555,13 +551,13 @@ As of ES-DE 2.2.0 no legacy EmulationStation themes are supported, such as those There are several user-selectable theme options in the _UI Settings_ menu, most notably _Theme variant_ which is essentially a form of theme profile. This could be anything, like different ways to navigate the themes, different layouts and designs etc. Additionally the _Theme color scheme_ setting makes it possible to select between different color schemes, if supported by the theme. The two remaining options _Theme aspect ratio_ and _Theme transitions_ are also important but you can normally leave them at their default _Automatic_ values, especially the _Theme aspect ratio_ option as it will be automatically detected. Be aware that all these theme settings are optional, it's up to the theme developer whether to add support for them to their themes. -Themes are most easily installed using the built-in theme downloader, but you can also manually add them to your ES-DE home directory, i.e. `~/.emulationstation/themes/`. By just adding them there, one folder each, they will be found during startup and you can then choose between them via the _UI Settings_ menu on the main menu. If using the portable release of ES-DE on Windows, the .emulationstation folder can be found in the root of the EmulationStation-DE directory. +Themes are most easily installed using the built-in theme downloader, but you can also manually add them to your ES-DE home directory, i.e. `~/ES-DE/themes/`. By just adding them there, one folder each, they will be found during startup and you can then choose between them via the _UI Settings_ menu on the main menu. If using the portable release of ES-DE on Windows, the ES-DE application data can be found in the root of the ES-DE directory. -Although you should place additional themes in your ES-DE home directory, the default Slate and Modern themes are located in the installation folder as they come bundled with the application. For example this could be `/usr/share/emulationstation/themes/` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/` on macOS or `C:\Program Files\EmulationStation-DE\themes\` on Windows. If using the portable ES-DE release on Windows, the themes folder will be located in the root of the EmulationStation-DE directory. +Although you should place additional themes in your ES-DE home directory, the default Slate and Modern themes are located in the installation folder as they come bundled with the application. For example this could be `/usr/share/es-de/themes/` on Linux, `/Applications/ES-DE.app/Contents/Resources/themes/` on macOS or `C:\Program Files\ES-DE\themes\` on Windows. If using the portable ES-DE release on Windows, the themes folder will be located in the root of the ES-DE directory. Note that if using the AppImage release on Linux, then there is no installation folder as all files are contained inside the AppImage file. -If you would like to customize the Slate or Modern themes, simply make a copy of their directories to `~/.emulationstation/themes/` and then those copies will take precedence over the ones in the application installation directory. +If you would like to customize the Slate or Modern themes, simply make a copy of their directories to `~/ES-DE/themes/` and then those copies will take precedence over the ones in the application installation directory. Refer to the official themes list for a selection of high-quality themes (these are also available via the built-in theme downloader):\ https://gitlab.com/es-de/themes/themes-list @@ -583,7 +579,7 @@ If you have manually downloaded any of the themes from the [official themes list If you have customized a theme by for instance modifying any of its XML files, then this will be highlighted with an exclamation mark and the text _LOCAL CHANGES_ in the theme downloader interface. If you attempt to fetch updates for such a theme you will be asked a question of whether to overwrite your local changes, or whether to cancel. If you have however added additional files to the theme that are not included in the theme repository, then these will not interfere and you can go ahead and fetch theme updates without any risk of having your local files being deleted. But there is a special (although unlikely) situation, if you add files that are not part of the theme repository but that are later added by the theme developer as well, then your local copies of any such files will be ovewritten when fetching theme updates. -In worst case there could be a situation where a repository is corrupted and the theme downloader can't properly identify or handle the corruption. In this case you will have to rename or delete that directory. This could also apply to the actual themes list repository. The latter is named _themes-list_ so by just deleting this directory (i.e. `~/.emulationstation/themes/themes-list`) you'll reset the theme downloader to its initial state. +In worst case there could be a situation where a repository is corrupted and the theme downloader can't properly identify or handle the corruption. In this case you will have to rename or delete that directory. This could also apply to the actual themes list repository. The latter is named _themes-list_ so by just deleting this directory (i.e. `~/ES-DE/themes/themes-list`) you'll reset the theme downloader to its initial state. Note that the exFAT filesystem can't be used as it makes the theme downloader fail. But using this filesystem is strongly discouraged anyway as it offers very poor disk I/O performance which makes ES-DE run really slowly. @@ -684,6 +680,7 @@ The following emulators are supported in AppImage format when using the bundled | ps2 | PCSX2 | pcsx2*.AppImage | | ps2 | Play! | Play!*.AppImage | | ps3 | RPCS3 | rpcs3*.AppImage | +| psvita | Vita3K | Vita3K*.AppImage | | psx | DuckStation | DuckStation*.AppImage | | snes | Snes9x | Snes9x*.AppImage | | switch | Yuzu | yuzu*.AppImage | @@ -730,7 +727,7 @@ There is however a workaround available to launch the Flatpak first, should you For example if using the ES-DE AppImage release, this would be the command to execute: ``` -PATH=/var/lib/flatpak/exports/bin:~/.local/share/flatpak/exports/bin:$PATH ./EmulationStation-DE-x64.AppImage +PATH=/var/lib/flatpak/exports/bin:~/.local/share/flatpak/exports/bin:$PATH ./ES-DE_x64.AppImage ``` Obviously you would need to change the path to the AppImage if it's not in your current working directory. @@ -812,6 +809,12 @@ cd ~/Applications/SkyEmu chmod +x SkyEmu ``` +And for VPinballX_GL: +``` +cd ~/Applications/VPinballX +chmod +x VPinballX_GL +``` + ## Running Windows emulators on Linux using Wine or Proton On Linux it's possible to run emulators developed specifically for Microsoft Windows via the Wine compatibility layer. Support is also included for the Proton fork of Wine. @@ -918,9 +921,9 @@ But for some systems a more elaborate setup is required, and the configuration f Let's start with the simple scenario of a single ROM file per game, which is the case for the majority of platforms. For this example we're setting up ES-DE to play Nintendo Entertainment System games. -The supported file extensions are listed in [unix/es_systems.xml](resources/systems/unix/es_systems.xml), [macos/es_systems.xml](resources/systems/macos/es_systems.xml) and [windows/es_systems.xml](resources/systems/windows/es_systems.xml) but if you generated the game system directories on first application startup or later via _Create/update system directories_ in the _Utilities_ menu, then there will be a file named systeminfo.txt in each game system directory that includes the list of supported file extensions. +The supported file extensions are listed in [linux/es_systems.xml](resources/systems/linux/es_systems.xml), [macos/es_systems.xml](resources/systems/macos/es_systems.xml) and [windows/es_systems.xml](resources/systems/windows/es_systems.xml) but if you generated the game system directories on first application startup or later via _Create/update system directories_ in the _Utilities_ menu, then there will be a file named systeminfo.txt in each game system directory that includes the list of supported file extensions. -Here is a simplified example from unix/es_systems.xml: +Here is a simplified example from linux/es_systems.xml: ```xml @@ -943,20 +946,20 @@ It's highly recommended to use filenames that correspond to the full name of the Symlinks are supported for both ROM directories and individual game files, but make sure to never symlink between files within the same system directory or there may be undefined application behavior when scraping, launching games etc. -The default game folder is ~/ROMs. On Unix this defaults to `/home//ROMs`, on macOS `/Users//ROMs` and on Windows `C:\Users\\ROMs` or `EmulationStation-DE\ROMs` depending on whether the installer release or the portable release is used. If the --home command line option was used to start ES-DE, the tilde symbol will resolve to whatever directory was passed as an argument to this option. +The default game folder is ~/ROMs. On Linux this defaults to `/home//ROMs`, on macOS `/Users//ROMs` and on Windows `C:\Users\\ROMs` or `ES-DE\ROMs` depending on whether the installer release or the portable release is used. If the --home command line option was used to start ES-DE, the tilde symbol will resolve to whatever directory was passed as an argument to this option. Assuming the default ROM directory is used, we need to create a subdirectory corresponding to the \ tag in es_systems.xml, for this example it's `nes`. So it would look something like the following: ``` -/home/myusername/ROMs/nes # Unix/Linux +/home/myusername/ROMs/nes # Linux /Users/myusername/ROMs/nes # macOS C:\Users\myusername\ROMs\nes # Windows installer -EmulationStation-DE\ROMs\nes # Windows portable +ES-DE\ROMs\nes # Windows portable ``` -Now simply copy your game ROMs into this folder, and you should end up with something like this Unix example: +Now simply copy your game ROMs into this folder, and you should end up with something like this Linux example: ``` ~/ROMs/nes/Legend of Zelda, the.zip @@ -964,7 +967,7 @@ Now simply copy your game ROMs into this folder, and you should end up with some ~/ROMs/nes/Super Mario Bros. 3.zip ``` -Note that these directories are case sensitive on Unix, so creating a directory named `Nes` instead of `nes` won't work. +Note that these directories are case sensitive on Linux/Unix, so creating a directory named `Nes` instead of `nes` won't work. That's it, start ES-DE and the NES game system should be populated. You can now scrape information and media for the games, and assuming you've setup RetroArch correctly with the Mesen core, you can launch games. If you instead prefer to use any of the three alternative emulators listed above (Nestopia UE, FCEUmm or QuickNES) then you can install one of those cores instead and change your emulator preference using the _Alternative emulators_ interface in the _Other settings_ menu or on a per-game basis via the metadata editor. Note that alternative emulators are only available for some game systems. @@ -1095,9 +1098,9 @@ Not all systems are as simple to setup as what was described in the previous sec ### Apple II -On Unix/Linux the default emulator for the apple2 system is [LinApple](http://linapple.sourceforge.net) and on Windows it's [AppleWin](https://github.com/AppleWin/AppleWin). Additionally the alternative emulators [Mednafen](https://mednafen.github.io) and [MAME](https://www.mamedev.org) standalone are supported. On macOS there is a port of AppleWin available named [Mariani](https://github.com/sh95014/AppleWin) but it appears broken at the moment as it does not accept any command line parameters. So instead only Mednafen and MAME are supported on macOS. +On Linux the default emulator for the apple2 system is [LinApple](http://linapple.sourceforge.net) and on Windows it's [AppleWin](https://github.com/AppleWin/AppleWin). Additionally the alternative emulators [Mednafen](https://mednafen.github.io) and [MAME](https://www.mamedev.org) standalone are supported. On macOS there is a port of AppleWin available named [Mariani](https://github.com/sh95014/AppleWin) but it appears broken at the moment as it does not accept any command line parameters. So instead only Mednafen and MAME are supported on macOS. -Depending on which Unix/Linux operating system you're using, LinApple may not be readily available and you may have to build it from source code or obtain a binary from somewhere on the Internet. See the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details on where it needs to be installed. If you're using an OS with access to the AUR, such as Arch or Manjaro, then LinApple is available there. Note that you need to use the _linapple-git_ package as the regular _linapple_ package does not work correctly. +Depending on which Linux operating system you're using, LinApple may not be readily available and you may have to build it from source code or obtain a binary from somewhere on the Internet. See the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details on where it needs to be installed. If you're using an OS with access to the AUR, such as Arch or Manjaro, then LinApple is available there. Note that you need to use the _linapple-git_ package as the regular _linapple_ package does not work correctly. Once the LinApple or AppleWin emulator is installed no additional configuration is required, just drop your games into the ~/ROMs/apple2 folder and launch them from inside ES-DE. @@ -1274,7 +1277,7 @@ ln -s /usr/local/Cellar/mame/0.248/share/mame/hash ~/.mame/ # on x86/Int These systems are generally straightforward to setup. For regular Atari Jaguar games you'll have a single ROM or zip archive per game that you place in the root of the `~/ROMs/atarijaguar` system directory. For Atari Jaguar CD games it's recommended to go for the .cdi format and you place these directly in the root of the `~/ROMs/atarijaguarcd` directory. -The only emulator that can run Atari Jaguar CD games is [BigPEmu](https://www.richwhitehouse.com/jaguar/) and while it's officially only available for the Windows operating system it's still possible to run it on Linux. To accomplish this you need to run it via the Wine (or Proton) translation layer. +The only emulator that can run Atari Jaguar CD games is [BigPEmL](https://www.richwhitehouse.com/jaguar/) and while it's officially only available for the Windows operating system it's still possible to run it on Linux. To accomplish this you need to run it via the Wine (or Proton) translation layer. How to setup Wine is covered in the [Running Windows emulators on Linux using Wine or Proton](USERGUIDE.md#running-windows-emulators-on-linux-using-wine-or-proton) section. @@ -1473,9 +1476,9 @@ Regardless of game setup method, per-game settings can be applied. If using the These computers as well as the Dragon 64 are slight varations of the Tandy Color Computer and as these machines are largely compatible with each other they're all emulated using the [XRoar](http://www.6809.org.uk/xroar) emulator. -This emulator is available for Unix/Linux, macOS and Windows, although on Linux you may need to build it from source code depending on which distribution you're using. Refer to the XRoar website for more information. If you manually download or build the emulator yourself then see the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details on where you need to install it. +This emulator is available for Linux, macOS and Windows, although on Linux you may need to build it from source code depending on which distribution you're using. Refer to the XRoar website for more information. If you manually download or build the emulator yourself then see the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details on where you need to install it. -In order to emulate the Dragon 32 you need the ROM file `d32.rom` and to emulate the Dragon 64 or Tano Dragon you need the `d64rom1.rom` and `d64rom2.rom` files. It's unclear whether `ddos10.rom` will also be needed for some games and applications. Even without these files the emulator will probably start, but you will likely see random character on screen and few if any games will run correctly. On Unix/Linux these files need to be placed into the `~/.xroar/roms` directory and on macOS you need to place them in `~/Library/XRoar/roms`. Note that neither of these directories are automatically created by the emulator so you need to create them yourself. On Windows you simply place the ROM files into the emulator installation directory next to the xroar.exe binary. +In order to emulate the Dragon 32 you need the ROM file `d32.rom` and to emulate the Dragon 64 or Tano Dragon you need the `d64rom1.rom` and `d64rom2.rom` files. It's unclear whether `ddos10.rom` will also be needed for some games and applications. Even without these files the emulator will probably start, but you will likely see random character on screen and few if any games will run correctly. On Linux these files need to be placed into the `~/.xroar/roms` directory and on macOS you need to place them in `~/Library/XRoar/roms`. Note that neither of these directories are automatically created by the emulator so you need to create them yourself. On Windows you simply place the ROM files into the emulator installation directory next to the xroar.exe binary. Following this setup there is not much to it, launching a cartridge or cassette image file will automatically run the game. @@ -1729,7 +1732,7 @@ You could optionally create a .commands file as well to specify some additional The next step is to modify the _\.singe_ file to point to the exact game directory. -So for example on Unix, modify the file `~/ROMs/laserdisc/mononoke.singe/mononoke.singe` by changing the following line: +So for example on Linux, modify the file `~/ROMs/laserdisc/mononoke.singe/mononoke.singe` by changing the following line: ``` MYDIR = "singe/mononoke/" ``` @@ -1757,11 +1760,13 @@ There are two ways to play these games, either via emulation or via simulation. **Method 1, emulation** -Proper emulation is done via the MAME standalone emulator. The games need to be in the MAME format and follow the MAME software list naming conventions, i.e. it will not be possible to run .mgw games with this emulator. The example game _Donkey Kong_ would have the filename `gnw_dkong.zip` and you'll place this file in the `gameandwatch` or `lcdgames` directory. +Proper emulation is done via the MAME - Current RetroArch core or the MAME standalone emulator. The games need to be in the MAME format and follow the MAME software list naming conventions, i.e. it will not be possible to run .mgw games with this emulator. The example game _Donkey Kong_ would have the filename `gnw_dkong.zip` and you'll place this file in the `gameandwatch` or `lcdgames` directory. However the game is only half of what's needed to properly emulate these games as you'll also need the artwork to see an image of the actual physical device when running the game. The artwork would also come in a .zip file with the same name as the game itself, e.g. `gnw_dkong.zip` and it must be located in the MAME artwork directory so it can be found by MAME. -For the artwork location there are two options available in the form of two separate MAME emulator entries, either the default _MAME Local Artwork (Standalone)_ entry or _MAME (Standalone)_. The former will require the artwork files to be placed in a directory inside the `gameandwatch` or `lcdgames` folder, which can be quite convenient as it's then bundled with the game files. Simply create an `artwork` subdirectory and place the files there. The second emulator entry will require the artwork files to be placed in the default MAME artwork directory. This location differs between operating systems and distributions so refer to the MAME documentation on where to find this folder. Here's an example of what _Donkey Kong_ would look like when going for the default option using the `gameandwatch` system: +For the RetroArch core this means it has to be placed in the system directory, specifically in `system/mame/artwork/` + +For MAME standalone there are two options available for the artwork location in the form of two separate MAME emulator entries, either the default _MAME Local Artwork (Standalone)_ entry or _MAME (Standalone)_. The former will require the artwork files to be placed in a directory inside the `gameandwatch` or `lcdgames` folder, which can be quite convenient as it's then bundled with the game files. Simply create an `artwork` subdirectory and place the files there. The second emulator entry will require the artwork files to be placed in the default MAME artwork directory. This location differs between operating systems and distributions so refer to the MAME documentation on where to find this folder. Here's an example of what _Donkey Kong_ would look like when going for the default option using the `gameandwatch` system: ``` ~/ROMs/gameandwatch/gnw_dkong.zip @@ -1770,7 +1775,7 @@ For the artwork location there are two options available in the form of two sepa As the artwork files also come with the .zip file extension they will show up inside ES-DE as if they were game files. So it's recommended to hide the entire artwork directory using the _Hidden_ option in the metadata editor, or alternatively exclude them from the multi-scraper using the _Exclude from multi-scraper_ option. -Be aware that neither ScreenScraper nor TheGamesDB currently support the MAME software list names natively so you'll need to refine the searches or the scraper services are unlikely to return any results at all (or very inaccurate results at best). +Be aware that neither ScreenScraper nor TheGamesDB currently support the MAME software list names natively so you'll need to refine the searches or the scraper services are unlikely to return any results at all (or very inaccurate results at best). However, if you have game files that match the MD5 hashes in the ScreenScraper database, then the games will scrape correctly regardless of their names. **Method 2, simulation** @@ -2134,10 +2139,21 @@ Starting ES-DE should now show the _Super Mario 3D World_ entry for the Wii U sy ### OpenBOR -The Open Beats of Rage (OpenBOR) game engine is available on Windows and Linux. Unfortunately the macOS ports seems to have been abandoned. +The Open Beats of Rage (OpenBOR) game engine is available on Android, Windows and Linux. Unfortunately the macOS port seems to have been abandoned. These games are often but not always distributed together with the game engine as specific engine versions may be required for some games. The setup is slightly different between Windows and Linux so they are described separately here. +**Android** + +Unfortunately there does not seem to be a way to launch individual OpenBOR games from ES-DE on Android, instead the OpenBOR user interface will open on game launch and you need to manually start your game from there. This means games need to be installed upfront in OpenBOR and .openbor dummy files should be added to the `ROMs/openbor` directory. These will then appear as individual games inside ES-DE and you can add metadata to them, scrape them etc. Refer to the OpenBOR documentation on how to add your game PAKs. + +Here's an example setup: + +``` +/storage/emulated/0/ROMs/openbor/D&D - K&D - The Endless Quest LNS.openbor +/storage/emulated/0/ROMs/openbor/He-Man.openbor +``` + **Windows:** There are two different OpenBOR setup methods supported on Windows, either to place the game directories directly inside the ROMs\openbor directory or to place the games somewhere else on the filesystems and create .lnk shortcuts and place these inside the ROMs\openbor directory. @@ -2210,6 +2226,8 @@ Doing this will make the game show up as if it was a single file inside ES-DE an PICO-8 Fantasy Console is a game engine developed by [Lexaloffle Games](https://www.lexaloffle.com/pico-8.php) that you need to buy a license to use. Doing so will provide you with download links to releases for Linux, macOS and Windows. Make sure to use the 64-bit release as the 32-bit release reportedly has some technical issues. On macOS and Windows the installation is straightforward, but on Linux you need to place PICO-8 in a location recognized by ES-DE. See the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details. +On Android it's recommended to use the Fake-08 RetroArch core, although this needs to be manually downloaded. How that is done is covered briefly in the [ANDROID.md](ANDROID.md#fake-08) document. + After the emulator has been installed you are ready to add some games. There are two ways to play games using PICO-8, either to add them to ES-DE as for any other system, or using the built-in Splore tool to explore and run games all through the PICO-8 user interface. For the first approach you can download games from the [PICO-8 forum](https://www.lexaloffle.com/bbs/?cat=7) and these are quite uniquely distributed as .png images. You just download these and place them inside the ~/ROMs/pico8 directory, for example: @@ -2229,16 +2247,17 @@ This is what the complete setup could look like: ~/ROMs/pico8/xzero-3.p8.png ``` -**Using the Retro8 RetroArch core** +**Using the Fake-08 and Retro8 RetroArch cores** + +On Android the Fake-08 core provides a good alternative to the official PICO-8 engine which is not available on this operating system. ES-DE also includes support for the Retro8 RetroArch core across all platforms, but it's borderline unusable and does not seem to be actively developed any longer. + +Neither Fake-08 nor Retro8 support the .png file extension, so in order to use these cores you need to remove that extension from your game files and only keep the .p8 extension, such as this: -ES-DE also includes support for the Retro8 RetroArch core but it's borderline unusable and does not seem to be actively developed any longer. If you still want to use it, then you first need to rename your game files by removing _.png_ from the end of the filenames, like this: ``` ~/ROMs/pico8/c_e_l_e_s_t_e-0.p8 ~/ROMs/pico8/xzero-3.p8 ``` -Following this just select the _Retro8_ alternative emulator and the games will (somehow) work. - ### Ports and desktop applications _The emulators system is essentially a clone of the desktop system so it's not discussed specifically in this section._ @@ -2254,7 +2273,7 @@ For the _desktop_ system specifically, you can choose to suspend ES-DE while an Shortcuts are very easy to setup, on Windows you can simply copy any .lnk file from the Start Menu into the `ports` or `desktop` system folders and then you can launch them directly from inside ES-DE. You can also create shortcuts manually to any file by right clicking on it in Explorer and selecting _Create shortcut_. -Likewise on Unix you can copy any .desktop shortcut into these system directories and they can then be launched by ES-DE. +Likewise on Linux you can copy any .desktop shortcut into these system directories and they can then be launched by ES-DE. Here's an example on Windows: ``` @@ -2262,7 +2281,7 @@ Here's an example on Windows: ~\ROMs\ports\openxcom.lnk ``` -And here's an example on Unix: +And here's an example on Linux: ``` ~/ROMs/desktop/org.libretro.RetroArch.desktop ~/ROMs/desktop/spotify.desktop @@ -2278,7 +2297,7 @@ Here's an example using alias files on macOS: **Method 2, scripts** -For more advanced setups you may want to use scripts. While it's possible to add these files directly to the root of the system directories it's instead generally recommended to setup a separate directory per game as there may be more than a single file required. For instance you may have multiple game variants or mods or you may want to keep game data files within the ROM directory tree. Only examples for Unix are provided here, but it's the same process for Windows and macOS except that in Windows .bat batch files are used instead of shell scripts. +For more advanced setups you may want to use scripts. While it's possible to add these files directly to the root of the system directories it's instead generally recommended to setup a separate directory per game as there may be more than a single file required. For instance you may have multiple game variants or mods or you may want to keep game data files within the ROM directory tree. Only examples for Linux are provided here, but it's the same process for Windows and macOS except that in Windows .bat batch files are used instead of shell scripts. Here's a setup of GZDoom and vkQuake: ``` @@ -2359,7 +2378,7 @@ Apart from this you need to install the PS3 system firmware to use the emulator, **Method 1, shortcuts** -First install your games inside RPCS3, then right click on each entry and select _Create Shortcut_ followed by _Create Desktop Shortcut_. On Windows this will create shortcuts with the .lnk extension, on macOS they will have the .app extension and on Unix/Linux they will have the .desktop extension. +First install your games inside RPCS3, then right click on each entry and select _Create Shortcut_ followed by _Create Desktop Shortcut_. On Windows this will create shortcuts with the .lnk extension, on macOS they will have the .app extension and on Linux they will have the .desktop extension. Then simply move these files from your desktop to your ~/ROMs/ps3 directory and you're done. Here's an example of what this could look like on Linux: ``` @@ -2398,7 +2417,7 @@ When using this setup method you need to set the alternative emulator to _RPCS3 Support for the PS Vita is currently experimental due to the early stages of development for the Vita3K emulator. While there's a growing list of games that are playable, integration with ES-DE is a bit rough at the moment. Hopefully this will improve as Vita3K evolves. -On Windows the Vita3K installation is straightforward, but on Linux you may need to place the emulator in a location recognized by ES-DE. See the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details. If using a Linux distribution that provides Vita3K via the repository (such as the AUR on Arch/Manjaro) then you can skip this step and install the emulator using your OS package manager. +On Android and Windows the Vita3K installation is straightforward, but on Linux you may need to place the emulator in a location recognized by ES-DE. See the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details. If using a Linux distribution that provides Vita3K via the repository (such as the AUR on Arch/Manjaro) then you can skip this step and install the emulator using your OS package manager. Although a macOS release of Vita3K seems to be in the works this does not seem to be readily available for download so there is currently no macOS support for this system in ES-DE. @@ -2428,7 +2447,7 @@ Simply copy the Start Menu entries for your Steam games into the ~\ROMs\steam di ~\ROMs\steam\Undertale.url ``` -**Unix/Linux** +**Linux** Copy the .desktop shortcuts for your games into the ~/ROMs/steam directory. If your desktop environment does not allow you to copy them directly from the application menu then you may need to navigate to `~/.local/share/applications` using your file manager and copy the .desktop files from there. Alternatively you can also create shortcuts from inside Steam by right clicking on a game, selecting _Manage_ and then _Add desktop shortcut_. These file can then be moved from your desktop to your ~/ROMs/steam directory. This is an example of what you could end up with: @@ -2452,6 +2471,19 @@ On macOS the shortcuts come with the .app extension and are actually directories As the Nokia N-Gage was running Symbian it may seem like the _ngage_ and _symbian_ systems would be identical. There is however a difference in that N-Gage games were shipped on MMC memory cards while regular Symbian games were packaged as _Software Installation Script_ files with the .sis or .sisx extension. Although the EKA2L1 emulator is used for both systems the setup is quite different, as detailed below. +**Android** + +Unfortunately there does not seem to be a way to launch individual games from ES-DE on Android specifically, so instead the EKA2L1 user interface will open on game launch and you need to manually start your game from inside the emulator. As games need to be installed upfront in the emulator as described below it's probably a good idea to just setup dummy game files with the .symbian or .ngage file extensions inside the ES-DE ROMs directory tree. These will then appear as indvidual games inside ES-DE and you can add metadata to them, scrape them etc. + +Here's an example setup: +``` +/storage/emulated/0/ROMs/ngage/Asphalt 2.ngage +/storage/emulated/0/ROMs/ngage/Bomberman.ngage +/storage/emulated/0/ROMs/ngage/CallofDuty.ngage +/storage/emulated/0/ROMs/symbian/Animal Farm.symbian +/storage/emulated/0/ROMs/symbian/AnotherWorld.symbian +``` + **General setup** The EKA2L1 installation should be fairly straightforward, for Linux there is an official AppImage, for macOS there is a DMG installer and for Windows a zip archive release. Just be aware that the AppImage has the very generic name `ubuntu-latest.AppImage` and needs to be renamed and moved to `~/Applications/EKA2L1.AppImage` in order for ES-DE to find it. @@ -2539,9 +2571,9 @@ Finally there's an emulator entry named _EKA2L1 [Custom device] (Standalone)_ wh This computer (which is confusingly also known as _TRS-80 Color Computer_ even though it's a completely different machine than the _TRS-80_) is emulated using the [XRoar](http://www.6809.org.uk/xroar) emulator. -This emulator is available for Unix/Linux, macOS and Windows, although on Linux you may need to build it from source code depending on which distribution you're using. Refer to the XRoar website for more information. If you manually download or build the emulator yourself then see the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details on where you need to install it. +This emulator is available for Linux, macOS and Windows, although on Linux you may need to build it from source code depending on which distribution you're using. Refer to the XRoar website for more information. If you manually download or build the emulator yourself then see the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details on where you need to install it. -In order for XRoar to work correctly you need the ROM files `bas13.rom`, `disk11.rom` and `extbas11.rom`. Even without these files the emulator will probably start, but you will likely see random character on screen and few if any games will run correctly. On Unix/Linux these files need to be placed into the `~/.xroar/roms` directory and on macOS you need to place them in `~/Library/XRoar/roms`. Note that neither of these directories are automatically created by the emulator so you need to create them yourself. On Windows you simply place the ROM files into the emulator installation directory next to the xroar.exe binary. +In order for XRoar to work correctly you need the ROM files `bas13.rom`, `disk11.rom` and `extbas11.rom`. Even without these files the emulator will probably start, but you will likely see random character on screen and few if any games will run correctly. On Linux these files need to be placed into the `~/.xroar/roms` directory and on macOS you need to place them in `~/Library/XRoar/roms`. Note that neither of these directories are automatically created by the emulator so you need to create them yourself. On Windows you simply place the ROM files into the emulator installation directory next to the xroar.exe binary. Following this setup there is not much to it, launching a cartridge or cassette image file will automatically run the game. If launching a diskette image you will probably need to manually run the game file from inside the emulated operating system. Such commands are beyond the scope of this document, but the following [quick reference PDF](https://colorcomputerarchive.com/repo/Documents/Manuals/Hardware/Color%20Computer%20Disk%20System%20-%20Quick%20Reference%20Guide%20(Tandy).pdf) provides a good command overview. @@ -2553,7 +2585,7 @@ Two emulator entries are available for this system, _XRoar CoCo 2 NTSC (Standalo Tandy Corporation made the somewhat dumb decision of naming several unrelated computers as TRS-80 which has caused decades of confusion. The _Tandy TRS-80_ system in ES-DE emulates the original black-and-white TRS-80 Model I. If you want to emulate the TRS-80 Color Computer then you'll want to use the _Tandy Color Computer_ system instead. -The TRS-80 is emulated using [sdl2trs](https://gitlab.com/jengun/sdltrs) which is available for Unix/Linux and Windows, seemingly there is no macOS port. If you use a Debian-based Linux distribution there is a .deb package made by the developers and if you're using an Arch-based distribution you can install it using the AUR. For other distributions you may have to build from source code or download a pre-built binary from some other location. See the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details on where sdl2trs will need to be installed in that case. +The TRS-80 is emulated using [sdl2trs](https://gitlab.com/jengun/sdltrs) which is available for Linux and Windows, seemingly there is no macOS port. If you use a Debian-based Linux distribution there is a .deb package made by the developers and if you're using an Arch-based distribution you can install it using the AUR. For other distributions you may have to build from source code or download a pre-built binary from some other location. See the [Using manually downloaded emulators on Linux](USERGUIDE.md#using-manually-downloaded-emulators-on-linux) section of this guide for more details on where sdl2trs will need to be installed in that case. On Windows only the 64-bit release of the emulator is supported, with the filename `sdl2trs64.exe`. @@ -2586,11 +2618,11 @@ Here's what a complete setup could look like: ### Tangerine Computer Systems Oric -These games are executed using the Oricutron emulator which is readily available on Windows but quite problematic to get hold on for Unix and macOS. +These games are executed using the Oricutron emulator which is readily available on Windows but quite problematic to get hold on for Linux and macOS. Although there is a macOS build available at the Oricutron [download page](http://www.petergordon.org.uk/oricutron/) this seems to not work properly, or it's unclear how it should be used. As such this system is unsupported on macOS, but the configuration entries still exist in the bundled es_find_rules.xml and es_systems.xml files so if you manage to get the emulator to run, ES-DE should work with these games. -Likewise on Unix there seems to be no binaries available for download so you need to build the emulator yourself. As multiple files like images and roms are needed to run this emulator, it's easiest to download and extract the Windows version which contains all this data and then build from source code and simply copy over the `Oricutron` binary (example below using Ubuntu): +Likewise on Linux there seems to be no binaries available for download so you need to build the emulator yourself. As multiple files like images and roms are needed to run this emulator, it's easiest to download and extract the Windows version which contains all this data and then build from source code and simply copy over the `Oricutron` binary (example below using Ubuntu): ``` mkdir -p ~/Applications/oricutron @@ -2759,33 +2791,33 @@ Apart from this, hopefully the scraping process should be self-explanatory. If you already have a library of game media (images, videos and PDF manuals) you can manually copy these files into ES-DE. The same procedure applies if you want to add media for individual games, for instance when the scraper did not return any results or if you didn't like the media it provided. -The default media directory is `~/.emulationstation/downloaded_media//` +The default media directory is `~/ES-DE/downloaded_media//` This directory can however be changed using the _Game media directory_ setting in the _Other settings_ menu so make sure to check this setting before attempting to follow the instructions below. If the setting is blank, then the default directory is in use. See the [Supported game systems](USERGUIDE.md#supported-game-systems) table at the bottom of this guide for a list of all system names. -An example on Unix: +An example on Linux: ``` -/home/myusername/.emulationstation/downloaded_media/c64/screenshots/ +/home/myusername/ES-DE/downloaded_media/c64/screenshots/ ``` An example on macOS: ``` -/Users/myusername/.emulationstation/downloaded_media/c64/screenshots/ +/Users/myusername/ES-DE/downloaded_media/c64/screenshots/ ``` An example on Windows (installer release): ``` -C:\Users\Myusername\.emulationstation\downloaded_media\c64\screenshots\ +C:\Users\Myusername\ES-DE\downloaded_media\c64\screenshots\ ``` An example on Windows (portable release): ``` -EmulationStation-DE\.emulationstation\downloaded_media\c64\screenshots\ +ES-DE\ES-DE\downloaded_media\c64\screenshots\ ``` The media directories per game system are: @@ -2816,8 +2848,8 @@ The media files must correspond exactly to the game files. Take for example this For this example, the filename structure needs to look like the following: ``` -~/.emulationstation/downloaded_media/c64/screenshots/Multidisk/Last Ninja 2/Last Ninja 2.jpg -~/.emulationstation/downloaded_media/c64/videos/Multidisk/Last Ninja 2/Last Ninja 2.mp4 +~/ES-DE/downloaded_media/c64/screenshots/Multidisk/Last Ninja 2/Last Ninja 2.jpg +~/ES-DE/downloaded_media/c64/videos/Multidisk/Last Ninja 2/Last Ninja 2.mp4 ``` Note that there is seemingly an exception to this logic if the _Directories interpreted as files_ functionality has been used, in which case the "file extension" added to the directory is also included in the game media filenames. Take for example the following ScummVM game: @@ -2828,15 +2860,15 @@ Note that there is seemingly an exception to this logic if the _Directories inte The media files for this directory which is interpreted as a file will be: ``` -~/.emulationstation/downloaded_media/scummvm/screenshots/dig.scummvm.png -~/.emulationstation/downloaded_media/scummvm/videos/dig.scummvm.mp4 +~/ES-DE/downloaded_media/scummvm/screenshots/dig.scummvm.png +~/ES-DE/downloaded_media/scummvm/videos/dig.scummvm.mp4 ``` This is not a bug as these are not really file extensions after all, it's just a directory with a dot in the filename that happens to look like a file extension because that's how the _Directories interpreted as files_ logic works. For images .jpg and .png file extensions are supported and for videos .avi, .mkv, .mov, .mp4 and .wmv are supported. -Remember that on Unix filenames are case sensitive, and as well the file extensions must be in lower case, such as .png instead of .PNG or .Png or the file won't be found. +Remember that on Linux filenames are case sensitive, and as well the file extensions must be in lower case, such as .png instead of .PNG or .Png or the file won't be found. It's possible to change the game media directory location from within ES-DE, for this see the option _Game media directory_ in the _Other settings_ menu. @@ -3047,10 +3079,6 @@ If file hash searching is enabled, then this specifies the maximum allowed file Affects both overwriting of metadata as well as actual game media files on the filesystem. Even with this option disabled, metadata entries which are set to their default values will be populated by the scraper. In other words, this option only affects overwriting of previously scraped data, or data manually entered via the metadata editor. Game names are considered as set to their default values if either corresponding to the physical game file on disk minus the extension (e.g. the entry _Commando_ if the file is named _Commando.zip_), or for arcade games if corresponding to the MAME names as defined in the bundled mamenames.xml. Note that this setting does not affect generated miximages, that is instead controlled by the setting _Overwrite miximages (scraper/offline generator)_ found in the miximage settings menu. -**Halt on invalid media files** - -With this setting enabled, if any media files returned by the scraper seem to be invalid, the scraping is halted and an error message is presented where it's possible to retry or cancel the scraping of the specific game. In the case of multi-scraping it's also possible to skip the game and proceed to the next one in the queue. With this setting disabled, all media files will always be accepted and saved to disk. The file verification is quite basic and future versions may improve on this by using file checksums or other file integrity checks. There is an exception in place for box back covers when using ScreenScraper. As many of these specific images are broken, there is an automatic filter built in that is always active and which removes blank images and those containing only a few lines of pixels. - **Search using file hashes (non-interactive mode)** _(ScreenScraper only)_ When running the non-interactive scraper it's possible to search using a hash value calculated from the actual game file. Assuming ScreenScraper has a match for your file in their database, this will lead to 100% accuracy as the game name will be completely ignored. If there is no match for the hash value, then a fallback will be made to the game name and the normal search logic applies. The maximum allowed file size to apply this type of search to can be set using the _Hash searches max file size_ slider. Note that file hash searching can increase scraping times significantly if applied to large game files as the entire file needs to be read and processed to calculate its hash value. And obviously file hash searching will not work for directories, scripts, shortcuts, .m3u files and so on which will have no matching entries in the ScreenScraper database. @@ -3111,6 +3139,10 @@ Themes optionally support variants which are a type of theme profiles defined by If the theme author has included multiple color schemes, then these can be selected between using this menu option. +**Theme font size** + +If the theme author has included support for multiple font/text sizes, then these can be selected between using this menu option. Possible choices are _medium, large, small, extra large_ and _extra small_. What layout changes these font size options actually make is completely up to the theme author. + **Theme aspect ratio** Themes could optionally be optimized for different screen aspect ratios. ES-DE supports 16:9, 16:10, 3:2, 4:3, 5:4, 21:9 and 32:9 in both horizontal and vertical orientation, but it's completely up to the theme author which of these are actually supported by the theme. It's normally best to leave this setting at _Automatic_ in which case ES-DE will automatically select the aspect ratio that most closely matches the screen resolution. The _Automatic_ option is however only available if the theme supports at least two aspect ratios. @@ -3129,7 +3161,7 @@ If set to _None_, the system view will be displayed on startup. Any other value **Systems sorting** -The order in which to sort the game systems. The default option is _Full names or custom_ which will sort by full system names, unless there is a ~/.emulationstation/custom_systems/es_systems_sorting.xml file present which will then be used instead. The other options are using the bundled sorting configuration files for _Release year_ or _Manufacturer, release year_ or _HW type, release year_ or _Manufacturer, HW type, release year_. If using any of these bundled sorting files, then any ~/.emulationstation/custom_systems/es_systems_sorting.xml will be ignored. When changing this setting ES-DE will automatically reload. +The order in which to sort the game systems. The default option is _Full names or custom_ which will sort by full system names, unless there is a ~/ES-DE/custom_systems/es_systems_sorting.xml file present which will then be used instead. The other options are using the bundled sorting configuration files for _Release year_ or _Manufacturer, release year_ or _HW type, release year_ or _Manufacturer, HW type, release year_. If using any of these bundled sorting files, then any ~/ES-DE/custom_systems/es_systems_sorting.xml will be ignored. When changing this setting ES-DE will automatically reload. **Game default sort order** @@ -3189,7 +3221,7 @@ With this option enabled, there will be an overlay displayed when quickly scroll **Enable virtual keyboard** -This enables a virtual (on-screen) keyboard that can be used at various places throughout the application to input text and numbers using a controller. The Shift and Alt keys can be toggled individually or combined to access many special characters. The general use of the virtual keyboard should hopefully be self-explanatory. +This enables a virtual (on-screen) keyboard that can be used at various places throughout the application to input text and numbers using a controller. The Shift and Alt keys can be toggled individually or combined to access many special characters. The general use of the virtual keyboard should hopefully be self-explanatory. On Android the virtual keyboard from the operating system will be used if this setting has been disabled. **Enable toggle favorites button** @@ -3285,7 +3317,7 @@ Whether to search the custom image directory recursively. **Custom image directory** -The directory for custom images. The tilde `~` symbol can be used which will expand to the user home directory. It's also possible to use the %ESPATH% and %ROMPATH% variables which will set the directory relative to the ES-DE binary directory or the ROM directory. +The directory for custom images. The tilde `~` symbol can be used which will expand to the user home directory. It's also possible to use the %ESPATH% and %ROMPATH% variables which will set the directory relative to the ES-DE binary directory or the ROM directory. Images in the .jpg, .png, .webp, .svg and unanimated .gif formats are supported. #### Video screensaver settings @@ -3355,13 +3387,33 @@ Settings related to the input devices, i.e. the keyboard and controllers. This setting gives the ability to choose between the controller types _Xbox, Xbox 360, PlayStation 1/2/3, PlayStation 4, PlayStation 5, Switch Pro_ and _SNES_. Doing so alters the help icons and help text as well as the icons and text for the input device configurator. The setting is only cosmetic and does not change the controller behavior or the controller button mappings. +**Touch overlay size** _(Android only)_ + +If the touch input overlay has been enabled, then this setting makes it possible to select between a _medium, large, small_ or _extra small_ overlay size. + +**Touch overlay opacity** _(Android only)_ + +Sets the opacity of the input overlay to _normal, low_ or _very low_. + +**Touch overlay fade-out time** _(Android only)_ + +How long, in seconds, to display the overlay before fading it. Tapping anywhere on the screen will bring back the overlay if it's been faded out. + +**Enable touch overlay** _(Android only)_ + +The touch overlay applies a layer of virtual buttons on top of the ES-DE window. This makes it possible to use the application on devices that lack physical buttons, such as a mobile phone or tablet. Be careful to not accidentally disable this setting as you may lock yourself out of the application. If you do that, you'll need to temporarily plug in a controller or keyboard to enable the setting again, or you could clear the ES-DE storage in the Android App settings which will force the configurator to run on next startup. + **Only accept input from first controller** If enabling this option, only the first controller detected during startup will send its input to ES-DE (the keyboard input is unaffected by this setting and will be enabled regardless). This is a good way to limit potential chaos with multiple persons fighting over which games to play. Note that disconnecting and reconnecting controllers while ES-DE is running may change what is considered the first controller. This setting does not affect the emulators in any way, it's only applied to ES-DE. Another issue is that some wireless controllers have buggy drivers and will register as two devices, meaning all button presses will be registered twice inside ES-DE. Using this option is one solution to the problem, although it's also possible to blacklist the extra controller entry, as described [here](INSTALL.md#adding-custom-controller-profiles). +**Swap the A/B and X/Y buttons** + +When enabling this setting the functions for the A/B and X/Y buttons will be swapped and the helpsystem will be updated accordingly. The primary purpose of this setting is for using controllers like Nintendo Switch Pro and some handhelds which have swapped the physical positions of these buttons. With this setting enabled you'll be able to rely on your muscle memory from using any other controller type with a normal button layout. Note that the button swap does not apply to the keyboard which leads to a slight inconsistency as the helpsystem will only match the controller and not the keyboard. + **Ignore keyboard input** -If this setting is enabled then all keyboard input will be ignored, except the quit shortcut used to shut down the application. The main reason for ignoring keyboard input is if running Steam in parallel to ES-DE and you need to use the Steam Input's _Desktop Layout_ functionality to send keyboard input using the controller. In this case double or conflicting input will be sent to ES-DE as both the controller and keyboard events are read by the application. It's however generally a better idea to disable this functionality altogether in Steam and leave the ES-DE setting untouched. If you accidentally enable this setting when using a keyboard as input device, then you'll either need to plug in a controller to disable it again, or you'll need to modify the _InputIgnoreKeyboard_ entry in the ~/.emulationstation/es_settings.xml configuration file. +If this setting is enabled then all keyboard input will be ignored, except the quit shortcut used to shut down the application. The main reason for ignoring keyboard input is if running Steam in parallel to ES-DE and you need to use the Steam Input's _Desktop Layout_ functionality to send keyboard input using the controller. In this case double or conflicting input will be sent to ES-DE as both the controller and keyboard events are read by the application. It's however generally a better idea to disable this functionality altogether in Steam and leave the ES-DE setting untouched. If you accidentally enable this setting when using a keyboard as input device, then you'll either need to plug in a controller to disable it again, or you'll need to modify the _InputIgnoreKeyboard_ entry in the ~/ES-DE/settings/es_settings.xml configuration file. **Configure keyboard and controllers** @@ -3420,13 +3472,13 @@ _The system-wide alternative emulators interface. An entry in bold and with a ge **Game media directory** -This setting defines the directory for game media, i.e. images, videos and PDF manuals that have normally been downloaded by the scraper. The default location is _~/.emulationstation/downloaded_media_ +This setting defines the directory for game media, i.e. images, videos and PDF manuals that have normally been downloaded by the scraper. The default location is _~/ES-DE/downloaded_media_ **VRAM limit** The amount of video RAM to use for the application. Defaults to 512 MiB (192 MiB on the Raspberry Pi) which works fine most of the time when using moderately demanding themes with medium-sized collections at up to 4K display resolution. For large collections (as in many different systems rather than many games per system) in combination with demanding themes which use lots of full-screen images and similar it's recommended to increase this number to 1024 MiB or possibly higher to avoid stuttering and texture pop-in. Enabling the GPU statistics overlay gives some indications regarding the amount of texture memory currently used, which is helpful to determine a reasonable value for this setting. The allowed range for the settings is 128 to 2048 MiB. If you try to set it lower or higher than this by passing such values as command line parameters or by editing the es_settings.xml file manually, ES-DE will log a warning and automatically adjust to a value within the allowable range. -**Anti-aliasing (MSAA) (requires restart)** +**Anti-aliasing (MSAA) (requires restart)** _(All operating systems except Android)_ Sets the level of anti-aliasing for the application. You can select between _disabled_, _2x_ or _4x_. Note that this is a potentially dangerous option which may prevent the application from starting altogether with some GPU drivers. If you're unable to run the application after changing this option then you can reset it via the `--anti-aliasing 0` command line option. Be aware that enabling anti-aliasing has a slight to moderate performance impact. @@ -3458,7 +3510,7 @@ For platforms and package formats where the previous setting above is available With this setting enabled, the taskbar will be hidden when launching ES-DE, and it will be restored when the application exits. This can make for a more seamless experience as the taskbar could otherwise flash by briefly when launching and returning from games. -**Run in background (while game is launched)** +**Run in background (while game is launched)** _(All operating systems except Android)_ Enabling this option makes ES-DE continue to run while a game is launched. This is normally not recommended as it leads to a slightly strange application behavior and it also removes the ability to capture return codes and log output from the emulators. Generally this option should only be enabled if there are issues with launching games while suspending ES-DE. Note however that some systems like Valve Steam will always keep ES-DE running in the background because they require it for technical reasons (i.e. those systems will override this menu option). @@ -3472,7 +3524,7 @@ If enabled, you will be able to select alternative emulators per game using the **Show hidden files and folders** -If this option is disabled, hidden files and folders within the ROM directory tree are excluded from ES-DE. On Unix and macOS this means those starting with a dot, and on Windows it's those set as hidden by using an NTFS attribute. This setting is only intended for special situations and is not to be confused with the next option below which hides files based on metadata configuration within ES-DE. When changing this setting ES-DE will automatically reload. +If this option is disabled, hidden files and folders within the ROM directory tree are excluded from ES-DE. On Linux and macOS this means those starting with a dot, and on Windows it's those set as hidden by using an NTFS attribute. This setting is only intended for special situations and is not to be confused with the next option below which hides files based on metadata configuration within ES-DE. When changing this setting ES-DE will automatically reload. **Show hidden games** @@ -3490,7 +3542,7 @@ If enabled, only games that have metadata saved to the gamelist.xml files will b MAME software list names for all arcade systems are automatically expanded to their full game names using a bundled MAME name translation file. By default any extra information from this file that is located inside brackets is removed. This includes information like region, version/revision, license, release date and more. By setting this option to disabled that information is retained. Note that this is only applicable for any game names which have not been scraped as the scaper will overwrite the expanded information with whatever value the scraper service returns. It's however possible to disable scraping of game names altogether as covered elsewhere in this guide. -**Disable desktop composition (requires restart)** _(Unix and X11/Xorg only)_ +**Disable desktop composition (requires restart)** _(Linux and X11/Xorg only)_ The window manager desktop composition can adversely affect the framerate of ES-DE, especially on weaker graphics cards and when running at higher resolution. As such the desktop compositor can be disabled when running ES-DE, although the window manager has to be configured to allow applications to do this for the option to have any effect. Note that enabling this setting can cause problems with some graphics drivers so if you experience strange flickering and similar, then make sure to keep this setting disabled. In case of such issues, make sure that the emulator is also not blocking the composition (e.g. RetroArch has a corresponding option). This setting has no effect if using Wayland, it only applies to X11/Xorg. @@ -3506,7 +3558,7 @@ Displays the framerate and VRAM statistics as an overlay. This can be useful to Enabling or disabling the menu when the UI mode is set to _Kid_. Mostly intended for testing purposes as it's not recommended to enable the menu in this restricted mode. -**Show quit menu (reboot and power off entries)** _(All operating systems except macOS)_ +**Show quit menu (reboot and power off entries)** _(All operating systems except macOS and Android)_ With this setting enabled, there is a Quit menu shown as the last entry on the main menu which provides options to quit ES-DE, to reboot the computer or to power off the computer. With this setting disabled, there will simply be an entry to quit the application instead of the complete quit menu. @@ -3526,21 +3578,21 @@ This utility will create all game system directories inside your ROM directory t This utility will rescan the ROM directory for any changes such as added or removed games and systems without having to restart the application. But don't use this utility to reload changes to gamelist.xml files that you have made outside ES-DE as this can lead to data corruption. If you need to manually edit your gamelist.xml files then do this while ES-DE is shut down. -### Quit / Quit EmulationStation +### Quit / Quit ES-DE -The _Quit_ menu or _Quit EmulationStation_ entry as described by the _Show quit menu (reboot and power off entries)_ option above. +The _Quit_ menu or _Quit ES-DE_ entry as described by the _Show quit menu (reboot and power off entries)_ option above. If the menu is enabled, these are its entries: -**Quit EmulationStation** +**Quit ES-DE** -If the option _When to save game metadata_ has been set to _On exit_, the gamelist.xml files will be updated at this point. This applies also if the Quit menu is disabled and replaced by the _Quit EmulationStation_ entry. +If the option _When to save game metadata_ has been set to _On exit_, the gamelist.xml files will be updated at this point. This applies also if the Quit menu is disabled and replaced by the _Quit ES-DE_ entry. -**Reboot system** _(All operating systems except macOS)_ +**Reboot system** _(All operating systems except macOS and Android)_ Self explanatory. -**Power off system** _(All operating systems except macOS)_ +**Power off system** _(All operating systems except macOS and Android)_ Self explanatory. @@ -3842,9 +3894,9 @@ _Example of custom collections, here configured as genres._ _When editing a custom collection and the theme uses a textlist, then a tick symbol will be displayed for any game that is part of the collection._ -The way that custom collections are implemented is very simple. There is a single configuration file per collection inside the folder `~/.emulationstation/collections` +The way that custom collections are implemented is very simple. There is a single configuration file per collection inside the folder `~/ES-DE/collections` -For this example a file will have been created named `~/.emulationstation/collections/custom-Platform.cfg` +For this example a file will have been created named `~/ES-DE/collections/custom-Platform.cfg` The file contents is simply a list of ROM files, such as the following: @@ -3860,7 +3912,7 @@ The file contents is simply a list of ROM files, such as the following: Any changes to custom collections, for example adding or removing a game, will be immediately written to the corresponding collection configuration file. -If you copy or migrate a collection from a previous version of EmulationStation or if you're setting up ES-DE on a new computer, the collection will not be enabled by just copying its configuration file to the `~/.emulationstation/collections` directory. You always need to explicitly enable each collection via the menu. +If you copy or migrate a collection from a previous version of EmulationStation or if you're setting up ES-DE on a new computer, the collection will not be enabled by just copying its configuration file to the `~/ES-DE/collections` directory. You always need to explicitly enable each collection via the menu. If you're migrating from a previous version of EmulationStation that has absolute paths in the collection files, then these will be rewritten with the %ROMPATH% variable the first time you make a change to the collection. @@ -3880,9 +3932,9 @@ The **System name** column corresponds to the directory where you should put you For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name. -The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. +The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Linux, macOS and Windows then it's specified in square brackets, such as [LW] for Linux and Windows and [M] for macOS. -The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. +The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game. In the same manner as the _Default emulator_ column, differences between Linux, macOS and Windows are marked using square brackets. The **Needs BIOS** column indicates if any BIOS/system ROMs are required. Additional details should be covered by the emulator documentation. @@ -3908,7 +3960,7 @@ On Windows the following emulators provide a way to inform ES-DE where they have * Yuzu Default emulator/Alternative emulators columns: \ -**[U]**: Unix/Linux, **[M]**: macOS, **[W]**: Windows +**[L]**: Linux, **[M]**: macOS, **[W]**: Windows All emulators are RetroArch cores unless marked as **(Standalone)**, **(Wine)** or **(Proton)** @@ -3919,170 +3971,170 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | 3do | 3DO Interactive Multiplayer | Opera | | Yes | | | adam | Coleco Adam | MAME [Diskette] **(Standalone)** | MAME [Tape] **(Standalone)**,
MAME [Cartridge] **(Standalone)**,
MAME [Software list] **(Standalone)** | Yes | | | ags | Adventure Game Studio Game Engine | _Shortcut or script_ | | No | | -| amiga | Commodore Amiga | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [UM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | -| amiga1200 | Commodore Amiga 1200 | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [UM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | -| amiga600 | Commodore Amiga 600 | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [UM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | -| amigacd32 | Commodore Amiga CD32 | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [UM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | +| amiga | Commodore Amiga | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [LM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | +| amiga1200 | Commodore Amiga 1200 | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [LM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | +| amiga600 | Commodore Amiga 600 | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [LM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | +| amigacd32 | Commodore Amiga CD32 | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [LM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | | amstradcpc | Amstrad CPC | Caprice32 | CrocoDS,
CPCemu **(Standalone)**,
MAME **(Standalone)** | Yes for MAME | Single archive or disk file | | android | Google Android | BlueStacks **(Standalone)** [W] | | No | Shortcut (.lnk) file | -| apple2 | Apple II | LinApple **(Standalone)** [U],
Mednafen **(Standalone)** [M],
AppleWin **(Standalone)** [W] | Mednafen **(Standalone)** [UW],
MAME - Current,
MAME **(Standalone)** | Yes for Mednafen and MAME | See the specific _Apple II_ section elsewhere in this guide | +| apple2 | Apple II | LinApple **(Standalone)** [L],
Mednafen **(Standalone)** [M],
AppleWin **(Standalone)** [W] | Mednafen **(Standalone)** [LW],
MAME - Current,
MAME **(Standalone)** | Yes for Mednafen and MAME | See the specific _Apple II_ section elsewhere in this guide | | apple2gs | Apple IIGS | MAME - Current | MAME **(Standalone)** | Yes | See the specific _Apple IIGS_ section elsewhere in this guide | -| arcade | Arcade | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [UW],
FB Alpha 2012,
Flycast,
Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Kronos [UW],
Model 2 Emulator **(Standalone)** [W],
Model 2 Emulator [Suspend ES-DE] **(Standalone)** [W],
Supermodel **(Standalone)** [UW],
_Shortcut or script_ | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| arcade | Arcade | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [LW],
FB Alpha 2012,
Flycast,
Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Kronos [LW],
Model 2 Emulator **(Standalone)** [W],
Model 2 Emulator [Suspend ES-DE] **(Standalone)** [W],
Supermodel **(Standalone)** [LW],
_Shortcut or script_ | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | | arcadia | Emerson Arcadia 2001 | MAME - Current | MAME **(Standalone)** | No | Single archive or ROM file | | archimedes | Acorn Archimedes | MAME [Model A440/1] **(Standalone)** | MAME [Model A3000] **(Standalone)**,
MAME [Model A310] **(Standalone)**,
MAME [Model A540] **(Standalone)** | Yes | | | arduboy | Arduboy Miniature Game System | Arduous | | No | Single archive or .hex file | | astrocde | Bally Astrocade | MAME - Current | MAME **(Standalone)** | Yes | Single archive or ROM file | -| atari2600 | Atari 2600 | Stella | Stella 2014,
Stella **(Standalone)**,
Gopher2600 **(Standalone)** [UW],
ares **(Standalone)** | No | Single archive or ROM file | +| atari2600 | Atari 2600 | Stella | Stella 2014,
Stella **(Standalone)**,
Gopher2600 **(Standalone)** [LW],
ares **(Standalone)** | No | Single archive or ROM file | | atari5200 | Atari 5200 | a5200 | Atari800,
Atari800 **(Standalone)**,
Altirra **(Standalone)** [W] | Yes except for Altirra | Single archive or ROM file | | atari7800 | Atari 7800 ProSystem | ProSystem | MAME - Current,
MAME **(Standalone)** | Yes | Single archive or ROM file | | atari800 | Atari 800 | Atari800 | Atari800 **(Standalone)**,
Altirra **(Standalone)** [W] | Yes except for Altirra | | -| atarijaguar | Atari Jaguar | Virtual Jaguar | BigPEmu **(Standalone)** [W],
BigPEmu **(Wine)** [U],
BigPEmu **(Proton)** [U],
MAME **(Standalone)** | Yes for MAME | See the specific _Atari Jaguar and Atari Jaguar CD_ section elsewhere in this guide | -| atarijaguarcd | Atari Jaguar CD | BigPEmu **(Standalone)** [W],
BigPEmu **(Wine)** [U] | BigPEmu **(Proton)** [U] | No | See the specific _Atari Jaguar and Atari Jaguar CD_ section elsewhere in this guide | -| atarilynx | Atari Lynx | Handy | Beetle Lynx,
Mednafen **(Standalone)** | | | +| atarijaguar | Atari Jaguar | Virtual Jaguar | BigPEmu **(Standalone)** [W],
BigPEmu **(Wine)** [L],
BigPEmu **(Proton)** [L],
MAME **(Standalone)** | Yes for MAME | See the specific _Atari Jaguar and Atari Jaguar CD_ section elsewhere in this guide | +| atarijaguarcd | Atari Jaguar CD | BigPEmu **(Standalone)** [W],
BigPEmu **(Wine)** [L] | BigPEmu **(Proton)** [L] | No | See the specific _Atari Jaguar and Atari Jaguar CD_ section elsewhere in this guide | +| atarilynx | Atari Lynx | Handy | Beetle Lynx,
Mednafen **(Standalone)** | No | Single archive or ROM file | | atarist | Atari ST [also STE and Falcon] | Hatari | Hatari **(Standalone)** | Yes | Single archive or image file for single-diskette games, .m3u playlist for multi-diskette games | | atarixe | Atari XE | Atari800 | Atari800 **(Standalone)**,
Altirra **(Standalone)** [W] | Yes except for Altirra | | | atomiswave | Sammy Corporation Atomiswave | Flycast | Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Demul **(Standalone)** [W] | Depends | Single archive 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)**,
VICE x64 Fast,
VICE x64 SuperCPU,
VICE x128,
Frodo | No | Single archive or image file for tape, cartridge or single-diskette games, .m3u playlist for multi-diskette games | | cdimono1 | Philips CD-i | SAME CDi | CDi 2015 @,
MAME **(Standalone)** | Yes | Single .bin/.cue pair | -| cdtv | Commodore CDTV | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [UM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | +| cdtv | Commodore CDTV | PUAE | PUAE 2021,
FS-UAE **(Standalone)**,
Amiberry **(Standalone)** [LM] | Yes | See the specific _Commodore Amiga and CDTV_ section elsewhere in this guide | | chailove | ChaiLove Game Engine | ChaiLove | | | | | channelf | Fairchild Channel F | FreeChaF | MAME - Current,
MAME **(Standalone)** | Yes | Single archive or ROM file | | coco | Tandy Color Computer | XRoar CoCo 2 NTSC **(Standalone)** | XRoar CoCo 2 PAL **(Standalone)** | Yes | See the specific _Tandy Color Computer_ section elsewhere in this guide | | colecovision | Coleco ColecoVision | blueMSX | Gearcoleco,
openMSX **(Standalone)**,
ares **(Standalone)** | Yes | Single archive or ROM file | -| consolearcade | Console Arcade Systems | MAME - Current | MAME **(Standalone)**,
Flycast,
Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Kronos [UW],
Mednafen [Sega Saturn] **(Standalone)**,
Play! **(Standalone)**,
RPCS3 Shortcut **(Standalone)**,
Triforce **(Standalone)** [UW],
xemu **(Standalone)**,
Cxbx-Reloaded **(Standalone)** [W],
_Shortcut or script_ | Depends | See the specific _Console Arcade Systems_ section elsewhere in this guide | -| cps | Capcom Play System | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [UW],
FB Alpha 2012,
FB Alpha 2012 CPS-1,
FB Alpha 2012 CPS-2,
FB Alpha 2012 CPS-3 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| cps1 | Capcom Play System I | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [UW],
FB Alpha 2012,
FB Alpha 2012 CPS-1 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| cps2 | Capcom Play System II | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [UW],
FB Alpha 2012,
FB Alpha 2012 CPS-2 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| cps3 | Capcom Play System III | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [UW],
FB Alpha 2012,
FB Alpha 2012 CPS-3 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| consolearcade | Console Arcade Systems | MAME - Current | MAME **(Standalone)**,
Flycast,
Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Kronos [LW],
Mednafen [Sega Saturn] **(Standalone)**,
Play! **(Standalone)**,
RPCS3 Shortcut **(Standalone)**,
Triforce **(Standalone)** [LW],
xemu **(Standalone)**,
Cxbx-Reloaded **(Standalone)** [W],
_Shortcut or script_ | Depends | See the specific _Console Arcade Systems_ section elsewhere in this guide | +| cps | Capcom Play System | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [LW],
FB Alpha 2012,
FB Alpha 2012 CPS-1,
FB Alpha 2012 CPS-2,
FB Alpha 2012 CPS-3 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| cps1 | Capcom Play System I | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [LW],
FB Alpha 2012,
FB Alpha 2012 CPS-1 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| cps2 | Capcom Play System II | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [LW],
FB Alpha 2012,
FB Alpha 2012 CPS-2 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| cps3 | Capcom Play System III | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [LW],
FB Alpha 2012,
FB Alpha 2012 CPS-3 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | | crvision | VTech CreatiVision | MAME - Current | MAME **(Standalone)** | Yes | Single archive or ROM file | | daphne | Daphne Arcade LaserDisc Emulator | Hypseus [Daphne] **(Standalone)** | Hypseus [Singe] **(Standalone)**,
MAME - Current,
MAME **(Standalone)**,
DirkSimple | Depends | See the specific _LaserDisc Games_ section elsewhere in this guide | -| desktop | Desktop Applications | _Suspend ES-DE_ | _Keep ES-DE running_,
_AppImage (Suspend ES-DE)_ [U],
_AppImage (Keep ES-DE running)_ [U] | No | See the specific _Ports and desktop applications_ section elsewhere in this guide | -| doom | Doom | PrBoom | PrBoom+ **(Standalone)**,
Boom 3 [UW],
Boom 3 xp [UW],
_Shortcut or script_ | No | | +| desktop | Desktop Applications | _Suspend ES-DE_ | _Keep ES-DE running_,
_AppImage (Suspend ES-DE)_ [L],
_AppImage (Keep ES-DE running)_ [L] | No | See the specific _Ports and desktop applications_ section elsewhere in this guide | +| doom | Doom | PrBoom | PrBoom+ **(Standalone)**,
Boom 3 [LW],
Boom 3 xp [LW],
_Shortcut or script_ | No | | | dos | DOS (PC) | DOSBox-Pure | DOSBox-Core,
DOSBox-SVN,
DOSBox-X **(Standalone)**,
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 | | dreamcast | Sega Dreamcast | Flycast | Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Redream **(Standalone)**,
Demul **(Standalone)** [W] | 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 | | electron | Acorn Electron | MAME [Tape] **(Standalone)** | MAME [Diskette DFS] **(Standalone)**,
MAME [Diskette ADFS] **(Standalone)** | Yes | Single archive, or single tape or diskette image file | -| emulators | Emulators | _Suspend ES-DE_ | _Keep ES-DE running_,
_AppImage (Suspend ES-DE)_ [U],
_AppImage (Keep ES-DE running)_ [U] | No | See the specific _Ports and desktop applications_ section elsewhere in this guide | +| emulators | Emulators | _Suspend ES-DE_ | _Keep ES-DE running_,
_AppImage (Suspend ES-DE)_ [L],
_AppImage (Keep ES-DE running)_ [L] | 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 | -| famicom | Nintendo Family Computer | Mesen | Mesen **(Standalone)** [UW],
Nestopia UE,
Nestopia UE **(Standalone)** [U],
FCEUmm,
QuickNES,
puNES **(Standalone)** [UW],
Mednafen **(Standalone)**,
ares **(Standalone)**,
ares FDS **(Standalone)**,
3dSen **(Wine)** [U],
3dSen **(Proton)** [U],
3dSen **(Standalone)** [W] | No | Single archive or ROM file. For Famicom games in 3D see the specific _Nintendo NES and Famicom in 3D_ section elsewhere in this guide | +| famicom | Nintendo Family Computer | Mesen | Mesen **(Standalone)** [LW],
Nestopia UE,
Nestopia UE **(Standalone)** [L],
FCEUmm,
QuickNES,
puNES **(Standalone)** [LW],
Mednafen **(Standalone)**,
ares **(Standalone)**,
ares FDS **(Standalone)**,
3dSen **(Wine)** [L],
3dSen **(Proton)** [L],
3dSen **(Standalone)** [W] | No | Single archive or ROM file. For Famicom games in 3D see the specific _Nintendo NES and Famicom in 3D_ section elsewhere in this guide | | fba | FinalBurn Alpha | FB Alpha 2012 | FB Alpha 2012 Neo Geo,
FB Alpha 2012 CPS-1,
FB Alpha 2012 CPS-2,
FB Alpha 2012 CPS-3 | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| fbneo | FinalBurn Neo | FinalBurn Neo | FinalBurn Neo **(Standalone)** [UW] | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| fds | Nintendo Famicom Disk System | Mesen | Mesen **(Standalone)** [UW],
Nestopia UE,
Nestopia UE **(Standalone)** [U],
FCEUmm,
Mednafen **(Standalone)**,
ares **(Standalone)** | Yes | Single archive or ROM file | -| flash | Adobe Flash | Ruffle **(Standalone)** | Lightspark **(Standalone)** [U],
ArcadeFlashWeb **(Standalone)** [W] | No | Single .swf file | +| fbneo | FinalBurn Neo | FinalBurn Neo | FinalBurn Neo **(Standalone)** [LW] | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| fds | Nintendo Famicom Disk System | Mesen | Mesen **(Standalone)** [LW],
Nestopia UE,
Nestopia UE **(Standalone)** [L],
FCEUmm,
Mednafen **(Standalone)**,
ares **(Standalone)** | Yes | Single archive or ROM file | +| flash | Adobe Flash | Ruffle **(Standalone)** | Lightspark **(Standalone)** [L],
ArcadeFlashWeb **(Standalone)** [W] | No | Single .swf file | | fm7 | Fujitsu FM-7 | MAME [FM-7 Diskette] **(Standalone)** | MAME [FM-7 Tape] **(Standalone)**,
MAME [FM-7 Software list] **(Standalone)**,
MAME [FM77AV Diskette] **(Standalone)**,
MAME [FM77AV Tape] **(Standalone)**,
MAME [FM77AV Software list] **(Standalone)** | Yes | For tape files you need to manually start the cassette player from the MAME menu after the "load" command, as well as entering the "run" command after loading is complete | -| fmtowns | Fujitsu FM Towns | MAME - Current,
MAME **(Standalone)** | Tsugaru **(Standalone)** [UW] | Yes | See the specific _Fujitsu FM Towns_ section elsewhere in this guide | +| fmtowns | Fujitsu FM Towns | MAME - Current,
MAME **(Standalone)** | Tsugaru **(Standalone)** [LW] | Yes | See the specific _Fujitsu FM Towns_ section elsewhere in this guide | | fpinball | Future Pinball | Future Pinball **(Standalone)** [W] | | No | | | gamate | Bit Corporation Gamate | MAME - Current | MAME **(Standalone)** | Yes | Single archive or ROM file | -| gameandwatch | Nintendo Game and Watch | MAME Local Artwork **(Standalone)** | MAME **(Standalone)**,
Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | +| gameandwatch | Nintendo Game and Watch | MAME - Current | MAME Local Artwork **(Standalone)**,
MAME **(Standalone)**,
Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | | gamecom | Tiger Electronics Game.com | MAME - Current | MAME **(Standalone)** | Yes | Single archive or ROM file | -| gamegear | Sega Game Gear | Genesis Plus GX | Genesis Plus GX Wide,
Gearsystem,
SMS Plus GX,
PicoDrive,
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | -| gb | Nintendo Game Boy | Gambatte | SameBoy,
SameBoy **(Standalone)**,
Gearboy,
Gearboy **(Standalone)** [UW],
TGB Dual,
Mesen-S,
Mesen **(Standalone)** [UW],
bsnes,
mGBA,
mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)**,
ares **(Standalone)**,
SkyEmu **(Standalone)** | No | Single archive or ROM file | -| gba | Nintendo Game Boy Advance | mGBA | mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)**,
VBA Next,
gpSP,
ares **(Standalone)**,
SkyEmu **(Standalone)** | Yes for ares | Single archive or ROM file | -| gbc | Nintendo Game Boy Color | Gambatte | SameBoy,
SameBoy **(Standalone)**,
Gearboy,
Gearboy **(Standalone)** [UW],
TGB Dual,
Mesen-S,
Mesen **(Standalone)** [UW],
bsnes,
mGBA,
mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)**,
ares **(Standalone)**,
SkyEmu **(Standalone)** | No | Single archive or ROM file | -| gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)**,
PrimeHack **(Standalone)** [UW],
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,
PicoDrive,
BlastEm,
BlastEm **(Standalone)** [U],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | +| gamegear | Sega Game Gear | Genesis Plus GX | Genesis Plus GX Wide,
Gearsystem,
SMS Plus GX,
PicoDrive,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | No | Single archive or ROM file | +| gb | Nintendo Game Boy | Gambatte | SameBoy,
SameBoy **(Standalone)**,
Gearboy,
Gearboy **(Standalone)** [LW],
TGB Dual,
DoubleCherryGB [LW],
Mesen-S,
Mesen **(Standalone)** [LW],
bsnes,
mGBA,
mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)**,
Mednafen **(Standalone)**,
ares **(Standalone)**,
SkyEmu **(Standalone)** | No | Single archive or ROM file | +| gba | Nintendo Game Boy Advance | mGBA | mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)**,
VBA Next,
gpSP,
Mednafen **(Standalone)**,
ares **(Standalone)**,
SkyEmu **(Standalone)** | Yes for ares | Single archive or ROM file | +| gbc | Nintendo Game Boy Color | Gambatte | SameBoy,
SameBoy **(Standalone)**,
Gearboy,
Gearboy **(Standalone)** [LW],
TGB Dual,
DoubleCherryGB [LW],
Mesen-S,
Mesen **(Standalone)** [LW],
bsnes,
mGBA,
mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)**,
Mednafen **(Standalone)**,
ares **(Standalone)**,
SkyEmu **(Standalone)** | No | Single archive or ROM file | +| gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)**,
PrimeHack **(Standalone)** [LW],
Triforce **(Standalone)** [LW] | No | Disc image file for single-disc games, .m3u playlist for multi-disc games | +| genesis | Sega Genesis | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm,
BlastEm **(Standalone)** [L],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | | gmaster | Hartung Game Master | MAME - Current | MAME **(Standalone)** | Yes | Single archive or ROM file | | gx4000 | Amstrad GX4000 | Caprice32 | CrocoDS,
MAME **(Standalone)** | No | Single archive or ROM file | | intellivision | Mattel Electronics Intellivision | FreeIntv | MAME - Current,
MAME **(Standalone)** | Yes | Single archive or ROM 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 | | laserdisc | LaserDisc Games | Hypseus [Daphne] **(Standalone)** | Hypseus [Singe] **(Standalone)**,
MAME - Current,
MAME **(Standalone)**,
DirkSimple | Depends | See the specific _LaserDisc Games_ section elsewhere in this guide | -| lcdgames | LCD Handheld Games | MAME Local Artwork **(Standalone)** | MAME **(Standalone)**,
Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | +| lcdgames | LCD Handheld Games | MAME - Current | MAME Local Artwork **(Standalone)**,
MAME **(Standalone)**,
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)** [L] | | No | See the specific _Lutris_ section elsewhere in this guide | | lutro | Lutro Game Engine | Lutro | | | | | macintosh | Apple Macintosh | MAME Mac SE Bootable **(Standalone)** | MAME Mac SE Boot Disk **(Standalone)**,
MAME Mac Plus Bootable **(Standalone)**,
MAME Mac Plus Boot Disk **(Standalone)**,
Basilisk II **(Standalone)**,
SheepShaver **(Standalone)** | Yes | See the specific _Apple Macintosh_ section elsewhere in this guide | -| mame | Multiple Arcade Machine Emulator | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [UW],
FB Alpha 2012,
Flycast,
Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Kronos [UW],
Model 2 Emulator **(Standalone)** [W],
Model 2 Emulator [Suspend ES-DE] **(Standalone)** [W],
Supermodel **(Standalone)** [UW],
_Shortcut or script_ | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| mame-advmame | AdvanceMAME | AdvanceMAME **(Standalone)** [UW] | | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| mastersystem | Sega Master System | Genesis Plus GX | Genesis Plus GX Wide,
SMS Plus GX,
Gearsystem,
PicoDrive,
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | +| mame | Multiple Arcade Machine Emulator | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)**,
FinalBurn Neo,
FinalBurn Neo **(Standalone)** [LW],
FB Alpha 2012,
Flycast,
Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Kronos [LW],
Model 2 Emulator **(Standalone)** [W],
Model 2 Emulator [Suspend ES-DE] **(Standalone)** [W],
Supermodel **(Standalone)** [LW],
_Shortcut or script_ | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| mame-advmame | AdvanceMAME | AdvanceMAME **(Standalone)** [LW] | | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| mastersystem | Sega Master System | Genesis Plus GX | Genesis Plus GX Wide,
SMS Plus GX,
Gearsystem,
PicoDrive,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | No | Single archive or ROM file | | megacd | Sega Mega-CD | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
ares **(Standalone)** | Yes | | | megacdjp | Sega Mega-CD [Japan] | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
ares **(Standalone)** | Yes | | -| megadrive | Sega Mega Drive | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm,
BlastEm **(Standalone)** [U],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | -| megadrivejp | Sega Mega Drive [Japan] | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm,
BlastEm **(Standalone)** [U],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | +| megadrive | Sega Mega Drive | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm,
BlastEm **(Standalone)** [L],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | +| megadrivejp | Sega Mega Drive [Japan] | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm,
BlastEm **(Standalone)** [L],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | | megaduck | Creatronic Mega Duck | SameDuck | MAME - Current,
MAME **(Standalone)** | No | Single archive or ROM file | | mess | Multi Emulator Super System | MESS 2015 | | | | -| model2 | Sega Model 2 | Model 2 Emulator **(Standalone)** [W],
MAME - Current [UM] | Model 2 Emulator [Suspend ES-DE] **(Standalone)** [W],
MAME - Current [W],
MAME **(Standalone)**,
Model 2 Emulator **(Wine)** [U],
Model 2 Emulator **(Proton)** [U] | Yes for MAME | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| model3 | Sega Model 3 | Supermodel **(Standalone)** [UW] | | No | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| model2 | Sega Model 2 | Model 2 Emulator **(Standalone)** [W],
MAME - Current [LM] | Model 2 Emulator [Suspend ES-DE] **(Standalone)** [W],
MAME - Current [W],
MAME **(Standalone)**,
Model 2 Emulator **(Wine)** [L],
Model 2 Emulator **(Proton)** [L] | Yes for MAME | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| model3 | Sega Model 3 | Supermodel **(Standalone)** [LW] | | No | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | | moto | Thomson MO/TO Series | Theodore | | | | | msx | MSX | blueMSX | fMSX,
openMSX **(Standalone)**,
openMSX No Machine **(Standalone)**,
ares **(Standalone)** | Yes | | | msx1 | MSX1 | blueMSX | fMSX,
openMSX **(Standalone)**,
openMSX No Machine **(Standalone)**,
ares **(Standalone)** | Yes | | | msx2 | MSX2 | blueMSX | fMSX,
openMSX **(Standalone)**,
openMSX No Machine **(Standalone)**,
ares **(Standalone)** | Yes | | | msxturbor | MSX Turbo R | blueMSX | openMSX **(Standalone)**,
openMSX No Machine **(Standalone)** | Yes | | | mugen | M.U.G.E.N Game Engine | Ikemen GO **(Standalone)** | | No | See the specific _M.U.G.E.N Game Engine_ section elsewhere in this guide | -| multivision | Othello Multivision | Gearsystem | | | | +| multivision | Othello Multivision | Gearsystem | Mesen **(Standalone)** [LW] | No | Single archive or ROM file | | naomi | Sega NAOMI | Flycast | Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Demul **(Standalone)** [W] | Yes | Single archive file + .chd file in subdirectory if GD-ROM game | | naomi2 | Sega NAOMI 2 | Flycast | Flycast **(Standalone)**,
Flycast Dojo **(Standalone)**,
Demul **(Standalone)** [W] | Yes | Single archive file + .chd file in subdirectory if GD-ROM game | | naomigd | Sega NAOMI GD-ROM | Flycast | Flycast **(Standalone)**,
Flycast Dojo **(Standalone)** | Yes | Single archive file + .chd file in subdirectory if GD-ROM game | -| n3ds | Nintendo 3DS | Citra [UW],
Citra **(Standalone)** [M] | Citra 2018 [UW],
Citra **(Standalone)** [UW] | No | Single ROM file | -| n64 | Nintendo 64 | Mupen64Plus-Next | Mupen64Plus **(Standalone)**,
ParaLLEl N64,
simple64 **(Standalone)** [UW],
Rosalie's Mupen GUI **(Standalone)** [UW],
Project64 **(Standalone)** [W],
ares **(Standalone)**,
sixtyforce **(Standalone)** [M] | No | Single archive or ROM file | -| n64dd | Nintendo 64DD | ParaLLEl N64 [UW],
Mupen64Plus-Next [M] | Mupen64Plus-Next [UW],
ParaLLEl N64 [M],
Rosalie's Mupen GUI **(Standalone)** [UW],
ares **(Standalone)** | Yes | See the specific _Nintendo 64DD_ section elsewhere in this guide | -| nds | Nintendo DS | DeSmuME | DeSmuME 2015,
DeSmuME **(Standalone)** [U],
melonDS,
melonDS **(Standalone)**,
SkyEmu **(Standalone)** | No | Single archive or ROM file | -| neogeo | SNK Neo Geo | FinalBurn Neo | FinalBurn Neo **(Standalone)** [UW],
MAME **(Standalone)** | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | -| neogeocd | SNK Neo Geo CD | NeoCD | FinalBurn Neo,
FinalBurn Neo **(Standalone)** [U],
MAME **(Standalone)** | Yes | .chd (NeoCD and MAME only) or .cue file | -| neogeocdjp | SNK Neo Geo CD [Japan] | NeoCD | FinalBurn Neo,
FinalBurn Neo **(Standalone)** [U],
MAME **(Standalone)** | Yes | .chd (NeoCD and MAME only) or .cue file | -| nes | Nintendo Entertainment System | Mesen | Mesen **(Standalone)** [UW],
Nestopia UE,
Nestopia UE **(Standalone)** [U],
FCEUmm,
QuickNES,
puNES **(Standalone)** [UW],
Mednafen **(Standalone)**,
ares **(Standalone)**,
ares FDS **(Standalone)**,
3dSen **(Wine)** [U],
3dSen **(Proton)** [U],
3dSen **(Standalone)** [W] | No | Single archive or ROM file. For NES games in 3D see the specific _Nintendo NES and Famicom in 3D_ section elsewhere in this guide | -| ngage | Nokia N-Gage | EKA2L1 [Mounted] **(Standalone)** | EKA2L1 [Installed] **(Standalone)**,
EKA2L1 [Mounted] **(Wine)** [U],
EKA2L1 [Installed] **(Wine)** [U] | Yes | See the specific _Symbian and Nokia N-Gage_ section elsewhere in this guide | -| ngp | SNK Neo Geo Pocket | Beetle NeoPop | RACE,
Mednafen **(Standalone)**,
ares **(Standalone)** | | | -| ngpc | SNK Neo Geo Pocket Color | Beetle NeoPop | RACE,
Mednafen **(Standalone)**,
ares **(Standalone)** | | | +| n3ds | Nintendo 3DS | Citra [LW],
Citra **(Standalone)** [M] | Citra 2018 [LW],
Citra **(Standalone)** [LW] | No | Single ROM file | +| n64 | Nintendo 64 | Mupen64Plus-Next | Mupen64Plus **(Standalone)**,
ParaLLEl N64,
simple64 **(Standalone)** [LW],
Rosalie's Mupen GUI **(Standalone)** [LW],
Project64 **(Standalone)** [W],
ares **(Standalone)**,
sixtyforce **(Standalone)** [M] | No | Single archive or ROM file | +| n64dd | Nintendo 64DD | ParaLLEl N64 [LW],
Mupen64Plus-Next [M] | Mupen64Plus-Next [LW],
ParaLLEl N64 [M],
Rosalie's Mupen GUI **(Standalone)** [LW],
ares **(Standalone)** | Yes | See the specific _Nintendo 64DD_ section elsewhere in this guide | +| nds | Nintendo DS | melonDS DS | melonDS @,
melonDS **(Standalone)**,
DeSmuME,
DeSmuME 2015,
DeSmuME **(Standalone)** [L],
SkyEmu **(Standalone)** | No | Single archive or ROM file | +| neogeo | SNK Neo Geo | FinalBurn Neo | FinalBurn Neo **(Standalone)** [LW],
MAME **(Standalone)** | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | +| neogeocd | SNK Neo Geo CD | NeoCD | FinalBurn Neo,
FinalBurn Neo **(Standalone)** [L],
MAME **(Standalone)** | Yes | .chd (NeoCD and MAME only) or .cue file | +| neogeocdjp | SNK Neo Geo CD [Japan] | NeoCD | FinalBurn Neo,
FinalBurn Neo **(Standalone)** [L],
MAME **(Standalone)** | Yes | .chd (NeoCD and MAME only) or .cue file | +| nes | Nintendo Entertainment System | Mesen | Mesen **(Standalone)** [LW],
Nestopia UE,
Nestopia UE **(Standalone)** [L],
FCEUmm,
QuickNES,
puNES **(Standalone)** [LW],
Mednafen **(Standalone)**,
ares **(Standalone)**,
ares FDS **(Standalone)**,
3dSen **(Wine)** [L],
3dSen **(Proton)** [L],
3dSen **(Standalone)** [W] | No | Single archive or ROM file. For NES games in 3D see the specific _Nintendo NES and Famicom in 3D_ section elsewhere in this guide | +| ngage | Nokia N-Gage | EKA2L1 [Mounted] **(Standalone)** | EKA2L1 [Installed] **(Standalone)**,
EKA2L1 [Mounted] **(Wine)** [L],
EKA2L1 [Installed] **(Wine)** [L] | Yes | See the specific _Symbian and Nokia N-Gage_ section elsewhere in this guide | +| ngp | SNK Neo Geo Pocket | Beetle NeoPop | RACE,
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | +| ngpc | SNK Neo Geo Pocket Color | Beetle NeoPop | RACE,
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | | odyssey2 | Magnavox Odyssey 2 | O2EM | MAME - Current,
MAME **(Standalone)** | Yes | Single archive or ROM file | -| openbor | OpenBOR Game Engine | OpenBOR **(Standalone)** [UW] | | No | See the specific _OpenBOR_ section elsewhere in this guide | -| oric | Tangerine Computer Systems Oric | Oricutron **(Standalone)** [UW] | | | See the specific _Tangerine Computer Systems Oric_ section elsewhere in this guide | +| openbor | OpenBOR Game Engine | OpenBOR **(Standalone)** [LW] | | No | See the specific _OpenBOR_ section elsewhere in this guide | +| oric | Tangerine Computer Systems Oric | Oricutron **(Standalone)** [LW] | | | See the specific _Tangerine Computer Systems Oric_ section elsewhere in this guide | | palm | Palm OS | Mu | | | | | pc | IBM PC | DOSBox-Pure | DOSBox-Core,
DOSBox-SVN,
DOSBox-X **(Standalone)**,
DOSBox Staging **(Standalone)** | No | See the specific _DOS / PC_ section elsewhere in this guide | | pc88 | NEC PC-8800 Series | QUASI88 | QUASI88 **(Standalone)** | Yes | | | pc98 | NEC PC-9800 Series | Neko Project II Kai | Neko Project II | | | -| pcarcade | PC Arcade Systems | Wine **(Standalone)** [U],
_Shortcut or script_ [MW] | Proton **(Standalone)** [U],
_AppImage_ [U],
_Shortcut or script_ [U] | No | | -| pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [UW],
ares **(Standalone)** | No | Single archive or ROM file | -| pcenginecd | NEC PC Engine CD | Beetle PCE | Beetle PCE FAST,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [UW],
ares **(Standalone)** | Yes | | +| pcarcade | PC Arcade Systems | Wine **(Standalone)** [L],
_Shortcut or script_ [MW] | Proton **(Standalone)** [L],
_AppImage_ [L],
_Shortcut or script_ [L] | No | | +| pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | No | Single archive or ROM file | +| pcenginecd | NEC PC Engine CD | Beetle PCE | Beetle PCE FAST,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | Yes | | | pcfx | NEC PC-FX | Beetle PC-FX | Mednafen **(Standalone)** | Yes | | | pico8 | PICO-8 Fantasy Console | PICO-8 **(Standalone)** | PICO-8 Splore **(Standalone)**,
Retro8 | No | See the specific _PICO-8_ section elsewhere in this guide | | plus4 | Commodore Plus/4 | VICE xplus4 | VICE xplus4 **(Standalone)** | No | Single archive or image file for tape, cartridge or single-diskette games, .m3u playlist for multi-diskette games | | pokemini | Nintendo Pokémon Mini | PokeMini | | No | | -| ports | Ports | _Shortcut or script_ | _AppImage_ [U],
ECWolf (Wolfenstein 3D),
NXEngine (Cave Story),
OpenLara (Tomb Raider) [UW],
Super Bros War | Yes for ECWolf | See the specific _Ports and desktop applications_ section elsewhere in this guide | -| ps2 | Sony PlayStation 2 | LRPS2 [UW],
PCSX2 **(Standalone)** [M] | PCSX2 [UW] @,
PCSX2 **(Standalone)** [UW],
PCSX2 Legacy **(Standalone)** @,
Play! **(Standalone)**,
AetherSX2 **(Standalone)** [M] | Yes except for Play! | | +| ports | Ports | _Shortcut or script_ | _AppImage_ [L],
ECWolf (Wolfenstein 3D),
NXEngine (Cave Story),
OpenLara (Tomb Raider) [LW],
Super Bros War | Yes for ECWolf | See the specific _Ports and desktop applications_ section elsewhere in this guide | +| ps2 | Sony PlayStation 2 | LRPS2 [LW],
PCSX2 **(Standalone)** [M] | PCSX2 [LW] @,
PCSX2 **(Standalone)** [LW],
PCSX2 Legacy **(Standalone)** @,
Play! **(Standalone)**,
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 | | ps4 | Sony PlayStation 4 | _Placeholder_ | | | | | psp | Sony PlayStation Portable | PPSSPP | PPSSPP **(Standalone)** | No | Single disc image file | -| psvita | Sony PlayStation Vita | Vita3K **(Standalone)** [UW] | | Yes | See the specific _Sony PlayStation Vita_ section elsewhere in this guide | +| psvita | Sony PlayStation Vita | Vita3K **(Standalone)** [LW] | | Yes | See the specific _Sony PlayStation Vita_ section elsewhere in this guide | | psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,
PCSX ReARMed,
SwanStation,
DuckStation **(Standalone)**,
Mednafen **(Standalone)** | Yes | .chd file for single-disc games, .m3u playlist for multi-disc games | | pv1000 | Casio PV-1000 | MAME - Current | MAME **(Standalone)** | No | Single archive or ROM file | -| quake | Quake | TyrQuake | vitaQuake 2,
vitaQuake 2 [Rogue],
vitaQuake 2 [Xatrix],
vitaQuake 2 [Zaero],
vitaQuake 3 [UW],
_Shortcut or script_ | No | | +| quake | Quake | TyrQuake | vitaQuake 2,
vitaQuake 2 [Rogue],
vitaQuake 2 [Xatrix],
vitaQuake 2 [Zaero],
vitaQuake 3 [LW],
_Shortcut or script_ | No | | | samcoupe | MGT SAM Coupé | SimCoupé **(Standalone)** | | No | Single archive or ROM file | -| satellaview | Nintendo Satellaview | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [UW],
Mesen-S,
Mesen **(Standalone)** [UW],
ares **(Standalone)** | | | -| saturn | Sega Saturn | Beetle Saturn | Kronos [UW],
YabaSanshiro [UW],
Yabause,
Mednafen **(Standalone)**,
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],
YabaSanshiro [UW],
Yabause,
Mednafen **(Standalone)**,
SSF **(Standalone)** [W] | Yes | In separate folder interpreted as a file, with .m3u playlist if multi-disc game | +| satellaview | Nintendo Satellaview | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [LW],
Mesen-S,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | | | +| saturn | Sega Saturn | Beetle Saturn | Kronos [LW],
YabaSanshiro [LW],
Yabause,
Mednafen **(Standalone)**,
SSF **(Standalone)** [W] | Yes | .chd file for single-disc games, .m3u playlist for multi-disc games | +| saturnjp | Sega Saturn [Japan] | Beetle Saturn | Kronos [LW],
YabaSanshiro [LW],
Yabause,
Mednafen **(Standalone)**,
SSF **(Standalone)** [W] | Yes | .chd file for single-disc games, .m3u playlist for multi-disc games | | scummvm | ScummVM Game Engine | ScummVM | ScummVM **(Standalone)** | No | See the specific _ScummVM_ section elsewhere in this guide | | scv | Epoch Super Cassette Vision | MAME - Current | MAME **(Standalone)** | Yes | 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 | | 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,
PicoDrive,
ares **(Standalone)** | Yes | | -| sfc | Nintendo SFC (Super Famicom) | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [UW],
Beetle Supafaust [UW],
Mesen-S,
Mesen **(Standalone)** [UW],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | -| sg-1000 | Sega SG-1000 | Genesis Plus GX | Genesis Plus GX Wide,
Gearsystem,
blueMSX,
ares **(Standalone)** | No | | -| sgb | Nintendo Super Game Boy | Mesen-S | Mesen **(Standalone)** [UW],
SameBoy,
mGBA,
mGBA **(Standalone)** | | Single archive or ROM file | -| snes | Nintendo SNES (Super Nintendo) | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [UW],
Beetle Supafaust [UW],
Mesen-S,
Mesen **(Standalone)** [UW],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | -| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [UW],
Beetle Supafaust [UW],
Mesen-S,
Mesen **(Standalone)** [UW],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | +| sfc | Nintendo SFC (Super Famicom) | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [LW],
Beetle Supafaust [LW],
Mesen-S,
Mesen **(Standalone)** [LW],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | +| sg-1000 | Sega SG-1000 | Genesis Plus GX | Genesis Plus GX Wide,
Gearsystem,
blueMSX,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | No | Single archive or ROM file | +| sgb | Nintendo Super Game Boy | Mesen-S | Mesen **(Standalone)** [LW],
SameBoy,
mGBA,
mGBA **(Standalone)** | | Single archive or ROM file | +| snes | Nintendo SNES (Super Nintendo) | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [LW],
Beetle Supafaust [LW],
Mesen-S,
Mesen **(Standalone)** [LW],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | +| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [LW],
Beetle Supafaust [LW],
Mesen-S,
Mesen **(Standalone)** [LW],
Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | | solarus | Solarus Game Engine | Solarus **(Standalone)** | | No | Single .solarus game file | | spectravideo | Spectravideo | blueMSX | | | | | steam | Valve Steam | Steam **(Standalone)** | | No | See the specific _Steam_ section elsewhere in this guide | -| stv | Sega Titan Video Game System | Kronos [UW],
MAME - Current [M] | MAME - Current [UW],
MAME **(Standalone)**,
Mednafen **(Standalone)** | Yes | Single archive file | -| sufami | Bandai SuFami Turbo | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [UW],
ares **(Standalone)** | | | -| supergrafx | NEC SuperGrafx | Beetle SuperGrafx | Beetle PCE,
ares **(Standalone)** | | | +| stv | Sega Titan Video Game System | Kronos [LW],
MAME - Current [M] | MAME - Current [LW],
MAME **(Standalone)**,
Mednafen **(Standalone)** | Yes | Single archive file | +| sufami | Bandai SuFami Turbo | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)**,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
bsnes **(Standalone)** [LW],
ares **(Standalone)** | | | +| supergrafx | NEC SuperGrafx | Beetle SuperGrafx | Beetle PCE,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | No | Single archive or ROM file | | supervision | Watara Supervision | Potator | MAME - Current,
MAME **(Standalone)** | No | Single archive or ROM file | | supracan | Funtech Super A'Can | MAME - Current | MAME **(Standalone)** | Yes/No | Single archive or ROM file. To make MAME start these games create an empty file named internal_68k.bin and zip it into supracan.zip | -| switch | Nintendo Switch | Yuzu **(Standalone)** [UW],
Ryujinx **(Standalone)** [M] | Ryujinx **(Standalone)** [UW] | Yes | | +| switch | Nintendo Switch | Yuzu **(Standalone)** [LW],
Ryujinx **(Standalone)** [M] | Ryujinx **(Standalone)** [LW] | Yes | | | symbian | Symbian | EKA2L1 [Nokia N-Gage] **(Standalone)** | EKA2L1 [Nokia N70] **(Standalone)**,
EKA2L1 [Nokia N97] **(Standalone)**,
EKA2L1 [Custom device] **(Standalone)** | Yes | See the specific _Symbian and Nokia N-Gage_ section elsewhere in this guide | | tanodragon | Tano Dragon | XRoar **(Standalone)** | | Yes | See the specific _Dragon 32 and Tano Dragon_ section elsewhere in this guide | -| tg16 | NEC TurboGrafx-16 | Beetle PCE | Beetle PCE FAST,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [UW],
ares **(Standalone)** | No | Single archive or ROM file | -| tg-cd | NEC TurboGrafx-CD | Beetle PCE | Beetle PCE FAST,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [UW],
ares **(Standalone)** | Yes | | +| tg16 | NEC TurboGrafx-16 | Beetle PCE | Beetle PCE FAST,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | No | Single archive or ROM file | +| tg-cd | NEC TurboGrafx-CD | Beetle PCE | Beetle PCE FAST,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | Yes | | | ti99 | Texas Instruments TI-99 | MAME **(Standalone)** | | Yes | See the specific _Texas Instruments TI-99_ section elsewhere in this guide | | tic80 | TIC-80 Fantasy Computer | TIC-80 | TIC-80 **(Standalone)** | No | Single .tic file | | to8 | Thomson TO8 | Theodore | | | | -| triforce | Namco-Sega-Nintendo Triforce | Triforce **(Standalone)** [UW] | | No | | -| trs-80 | Tandy TRS-80 | sdl2trs DOS Diskette **(Standalone)** [UW] | sdl2trs Bootable Diskette **(Standalone)** [UW],
sdl2trs CMD File **(Standalone)** [UW] | Yes | See the specific _Tandy TRS-80_ section elsewhere in this guide | -| type-x | Taito Type X | Wine **(Standalone)** [U],
_Shortcut or script_ [MW] | Proton **(Standalone)** [U],
_AppImage_ [U],
_Shortcut or script_ [U] | No | | +| triforce | Namco-Sega-Nintendo Triforce | Triforce **(Standalone)** [LW] | | No | | +| trs-80 | Tandy TRS-80 | sdl2trs DOS Diskette **(Standalone)** [LW] | sdl2trs Bootable Diskette **(Standalone)** [LW],
sdl2trs CMD File **(Standalone)** [LW] | Yes | See the specific _Tandy TRS-80_ section elsewhere in this guide | +| type-x | Taito Type X | Wine **(Standalone)** [L],
_Shortcut or script_ [MW] | Proton **(Standalone)** [L],
_AppImage_ [L],
_Shortcut or script_ [L] | No | | | uzebox | Uzebox Open Source Console | Uzem | | | | | vectrex | GCE Vectrex | vecx | MAME - Current,
MAME **(Standalone)** | Yes for MAME | Single archive or ROM file | | vic20 | Commodore VIC-20 | VICE xvic | VICE xvic **(Standalone)** | No | Single archive or tape, cartridge or diskette image file | @@ -4091,18 +4143,18 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | vpinball | Visual Pinball | Visual Pinball **(Standalone)** | | No | See the specific _Visual Pinball_ section elsewhere in this guide | | vsmile | VTech V.Smile | MAME - Current | MAME **(Standalone)** | Yes | Single archive or ROM file | | wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file | -| wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,
PrimeHack **(Standalone)** [UW] | No | | +| wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,
PrimeHack **(Standalone)** [LW] | No | | | 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_,
_AppImage (Suspend ES-DE)_ [U],
_AppImage (Keep ES-DE running)_ [U] | No | Shortcut (.desktop/.app/.lnk) file, script or AppImage | -| windows3x | Microsoft Windows 3.x | DOSBox-X **(Standalone)** | DOSBox-Pure,
_Shortcut or script (Suspend ES-DE)_,
_Shortcut or script (Keep ES-DE running)_,
_AppImage (Suspend ES-DE)_ [U],
_AppImage (Keep ES-DE running)_ [U] | No | See the specific _Microsoft Windows 3.x and 9x_ section elsewhere in this guide | -| windows9x | Microsoft Windows 9x | DOSBox-X **(Standalone)** | DOSBox-Pure,
_Shortcut or script (Suspend ES-DE)_,
_Shortcut or script (Keep ES-DE running)_,
_AppImage (Suspend ES-DE)_ [U],
_AppImage (Keep ES-DE running)_ [U] | No | See the specific _Microsoft Windows 3.x and 9x_ section elsewhere in this guide | +| windows | Microsoft Windows | _Suspend ES-DE_ | _Keep ES-DE running_,
_AppImage (Suspend ES-DE)_ [L],
_AppImage (Keep ES-DE running)_ [L] | No | Shortcut (.desktop/.app/.lnk) file, script or AppImage | +| windows3x | Microsoft Windows 3.x | DOSBox-X **(Standalone)** | DOSBox-Pure,
_Shortcut or script (Suspend ES-DE)_,
_Shortcut or script (Keep ES-DE running)_,
_AppImage (Suspend ES-DE)_ [L],
_AppImage (Keep ES-DE running)_ [L] | No | See the specific _Microsoft Windows 3.x and 9x_ section elsewhere in this guide | +| windows9x | Microsoft Windows 9x | DOSBox-X **(Standalone)** | DOSBox-Pure,
_Shortcut or script (Suspend ES-DE)_,
_Shortcut or script (Keep ES-DE running)_,
_AppImage (Suspend ES-DE)_ [L],
_AppImage (Keep ES-DE running)_ [L] | No | See the specific _Microsoft Windows 3.x and 9x_ section elsewhere in this guide | | wonderswan | Bandai WonderSwan | Beetle Cygne | Mednafen **(Standalone)**,
ares **(Standalone)**,
ares [Benesse Pocket Challenge V2] **(Standalone)** | No | Single archive or ROM file | | wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | Mednafen **(Standalone)**,
ares **(Standalone)** | No | Single archive or ROM file | | x1 | Sharp X1 | X Millennium | MAME [Diskette] **(Standalone)**,
MAME [Tape] **(Standalone)** | Yes for MAME | Single archive or diskette/tape file | | 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 | -| xbox360 | Microsoft Xbox 360 | xenia **(Standalone)** [W],
xenia **(Wine)** [U] | xenia **(Proton)** [U],
_Shortcut or script_ [U] | No | See the specific _Microsoft Xbox 360_ section elsewhere in this guide | +| xbox360 | Microsoft Xbox 360 | xenia **(Standalone)** [W],
xenia **(Wine)** [L] | xenia **(Proton)** [L],
_Shortcut or script_ [L] | No | See the specific _Microsoft Xbox 360_ section elsewhere in this guide | | zmachine | Infocom Z-machine | Gargoyle **(Standalone)** | | No | | | zx81 | Sinclair ZX81 | EightyOne | | | | -| zxnext | Sinclair ZX Spectrum Next | #CSpect **(Standalone)** [UW],
ZEsarUX **(Standalone)** [M] | ZEsarUX **(Standalone)** [UW] | No | In separate folder interpreted as a file | -| zxspectrum | Sinclair ZX Spectrum | Fuse | Fuse **(Standalone)** | No | | +| zxnext | Sinclair ZX Spectrum Next | #CSpect **(Standalone)** [LW],
ZEsarUX **(Standalone)** [M] | ZEsarUX **(Standalone)** [LW] | No | In separate folder interpreted as a file | +| zxspectrum | Sinclair ZX Spectrum | Fuse | Fuse **(Standalone)** | No | Single archive or ROM file | diff --git a/es-app/assets/org.es_de.frontend.appdata.xml b/es-app/assets/org.es_de.frontend.appdata.xml index 6a26e499b..99e7e381b 100644 --- a/es-app/assets/org.es_de.frontend.appdata.xml +++ b/es-app/assets/org.es_de.frontend.appdata.xml @@ -38,6 +38,9 @@ + + https://gitlab.com/es-de/emulationstation-de/-/releases + https://gitlab.com/es-de/emulationstation-de/-/releases diff --git a/images/es-de_application_updater.png b/images/es-de_application_updater.png index 7dec9b832..8ec997227 100644 Binary files a/images/es-de_application_updater.png and b/images/es-de_application_updater.png differ