diff --git a/.clang-format b/.clang-format
index 5041249e9..5a5d0edec 100644
--- a/.clang-format
+++ b/.clang-format
@@ -1,10 +1,9 @@
# SPDX-License-Identifier: MIT
#
-# EmulationStation Desktop Edition
+# ES-DE
# .clang-format
#
-# Style configuration file for automatic C++ code formatting using clang-format.
-# This file requires at least clang-format version 11.0.
+# Style configuration file for automatic C++ and Java code formatting using clang-format.
#
---
@@ -141,3 +140,17 @@ TabWidth: 8
UseCRLF: false
UseTab: Never
...
+---
+Language: Java
+BraceWrapping:
+ AfterClass: true
+ AfterFunction: true
+ BeforeCatch: true
+ BeforeElse: true
+ IndentBraces: false
+BreakBeforeBraces: Custom
+ColumnLimit: 100
+IndentWidth: 4
+TabWidth: 8
+UseCRLF: false
+UseTab: Never
diff --git a/.gitignore b/.gitignore
index bca68e074..48b3a92b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,27 +18,33 @@
*.d
# Compiled executable
-emulationstation
-EmulationStation
-EmulationStation.exe
-es-pdf-convert
-es-pdf-convert.exe
+/es-de
+/ES-DE
+/ES-DE.exe
+/es-pdf-convert
+/es-pdf-converter/es-pdf-convert.exe
# Emscripten build
-emulationstation.data
-emulationstation.html
-emulationstation.js
-emulationstation.wasm
-emulationstation.worker.js
+es-de.data
+es-de.html
+es-de.js
+es-de.wasm
+es-de.worker.js
/index.html
/ROMs
+# Android
+/android
+/logback.log
+es-core/src/InputOverlay.*
+es-core/src/utils/PlatformUtilAndroid.*
+
# AppImage
AppDir
*.AppImage
# Core dumps
-emulationstation.core
+es-de.core
# Profiling data
callgrind.out.*
@@ -60,21 +66,21 @@ CMakeFiles
cmake_install.cmake
Makefile
install_manifest.txt
-EmulationStation.exe.manifest
+ES-DE.exe.manifest
# CPack
_CPack_Packages
-emulationstation-de*.deb
-emulationstation-de*.rpm
-EmulationStation-DE*.dmg
-EmulationStation-DE*.exe
+es-de*.deb
+es-de*.rpm
+ES-DE*.dmg
+ES-DE*.exe
# macOS
.DS_Store
# MSVC
-EmulationStation.ilk
-EmulationStation.pdb
+ES-DE.ilk
+ES-DE.pdb
es-pdf-convert.ilk
es-pdf-convert.pdb
lunasvg.exp
diff --git a/ANDROID.md b/ANDROID.md
new file mode 100644
index 000000000..0c7e8bf1b
--- /dev/null
+++ b/ANDROID.md
@@ -0,0 +1,532 @@
+# ES-DE (EmulationStation Desktop Edition) v3.0 (development version) - Android documentation
+
+This document contains information specific to the Android release, for more general ES-DE documentation refer to the [User guide](USERGUIDE-DEV.md).
+
+Table of contents:
+
+[[_TOC_]]
+
+## First startup and onboarding
+
+When you first start ES-DE you will be greeted by a welcome screen, this is part of the _configurator_, the ES-DE onboarding interface. The configurator is easy to use and will guide you through the necessary setup steps.
+
+As a first step you need to give ES-DE the required storage access permission or it will not be able to function. Just enable the setting and the configurator will proceed to the next step. Next you will need to define a application data directory where your settings, scraped media, custom collections and so on will be stored. By default this will be placed in the _ES-DE_ directory in the root of your device's internal storage, and this directory will be created for you automatically.
+
+After this step you need to select a ROMs directory where your game files will be stored, by default this will be named _ROMs_ and will be located in the root of you device's internal storage. You can however choose to place this on an SD card if you want to, just change the path using the Android file selector GUI. If you do change the path to the SD card you will however need to manually create the ROMs directory as well as to delete the empty directory that was created for you in the built-in storage.
+
+The next step is optional, and it's whether to create the game systems directory structure inside your ROMs folder. Performing this will also create _systeminfo.txt_ files in each system directory. These files contain information about the system such as what file extensions and emulators that are supported. They are not mandatory for the app to function, they are only there for your convenience. In general it's recommended to create the system directories, although you could remove the ones you don't need afterwards for a slightly faster app startup speed.
+
+This is basically the onboarding process, and ES-DE should now start up. Just be aware that you need to place at least one game with a supported file extension in the ROMs directory tree or ES-DE will only show an information dialog about missing games.
+
+Also note that ES-DE does not install any emulators, you need to install those separately. There is more information about that topic later in this document.
+
+If you need to re-run the configurator for some reason then the easiest way is to go into the Android Apps setting screen and revoke the storage access permissions under _Special app access_. This will make the configurator run automatically next time you start ES-DE. Another way to force it to start is to clear the app's storage under _Storage & cache_ but this is normally not recommended as it also deletes all themes you have downloaded using the theme downloader. A third option would be to rename either the ES-DE or ROMs directory as this will also trigger the configurator on next app startup.
+
+## Touch input overlay
+
+By default the touch input overlay will be enabled which makes it possible to use ES-DE without a controller or physical keyboard by overlaying virtual buttons on top of the ES-DE interface. If you are using a device which has a built-in controller you may however want to disable this feature. That is done via the _Enable touch overlay_ option in the _Input device settings_ menu on the main menu. Just be aware that disabling this option on a device where you have no other input method than touch will lock you out of the application.
+
+If you accidentally disable the touch overlay you can force the configurator to run as explained in the previous section above, this will always reset the touch overlay setting. Another option would of course be to temporarily plug in a controller or keyboard to enable the setting via its menu entry. A third option would be to manually edit the es_settings.xml file in the ES-DE application data directory. The setting you are after is named _InputTouchOverlay_ which should be changed from _false_ to _true_.
+
+Apart from this there are numerous options for the touch overlay, like the ability to change its size, opacity and fade-out time. Setting the fade-out to zero will make it permanently visible. See the [User guide](USERGUIDE-DEV.md) for a complete reference of all app settings and features.
+
+## Retention of files and data
+
+Almost all files saved and used by ES-DE are kept in the shared storage on either the device's built-in storage or on the SD card. This means that uninstalling the ES-DE app will not remove any of that data. The only thing that will be deleted are themes that have been downloaded using the built-in theme downloader, as it's not possible to store these in the ES-DE application data directory for technical reasons.
+
+## Emulation on Android in general
+
+There are some challenges with emulation on Android. Some emulators on the Google Play store have not been updated for a long time, or like in the case with RetroArch they are crippled to comply with Google's rules and policies. And some emulators are not available on the Play store at all. For these reasons you will need to sideload some manually downloaded APKs for a good emulation setup. There is a section later in this document describing the best place to get hold of each supported emulator.
+
+Thankfully sideloading emulators is not very difficult to do, the exact producedure for how to install APKs manually is not covered here but there are many resources available online on how to accomplish this.
+
+There is also the [F-Droid](https://f-droid.org/) app store as an alternative to Google Play, and this service contains a couple of emulators that are not present on the Play store, or that are present there but haven't been updated for a very long time.
+
+A number of emulators support the [FileProvider](https://developer.android.com/reference/androidx/core/content/FileProvider) API which makes it possible for ES-DE to temporarily provide storage access to the game ROMs on launch. This means that no access permission needs to be setup in the emulator upfront. For those emulators which do not support the FileProvider API, you will generally need to manually provide scoped storage access to each game system directory. Note that it's not supported to give access to the root of the entire ROM directory for emulators that use scoped storage, it has to be for the specific system. For instance `/storage/emulated/0/ROMs/n64` rather than `/storage/emulated/0/ROMs`.
+
+Some emulators like RetroArch are still using an older storage access method and for those emulators this is not something you need to consider.
+
+The following emulators are configured for FileProvider access:
+* 2600.emu
+* C64.emu
+* GBA.emu
+* GBC.emu
+* Lynx.emu
+* MD.emu
+* MAME4droid 2024
+* MAME4droid
+* NES.emu
+* NGP.emu
+* PCE.emu
+* Play!
+* Ruffle
+* Saturn.emu
+* Swan.emu
+* Yuzu
+
+Some of these emulators still require BIOS files, so not all of them will be completely free from manual configuration.
+
+The following emulators have partial FileProvider access support but are currently not configured for that in ES-DE:
+* Dolphin (the FileProvider interface is broken on some devices)
+* M64Plus FZ (the FileProvider interface doesn't work reliably and game launching randomly fails when using it)
+* PPSSPP (the FileProvider interface doesn't work with .chd files specifically)
+
+## Issues with the Ayn Odin 2
+
+There are two serious issues that seem to be specific to the Ayn Odin 2, although it remains to be seen whether the problem exists also on other devices.
+
+The first problem is that some emulators refuse to run games that you place inside directories that contain dots in their names. This is quite problematic as the [directories interpreted as files](USERGUIDE.md#directories-interpreted-as-files) functionality depends on the ability to add file extensions to directory names.
+
+This has been observed with M64Plus FZ, Play!, Saturn.emu, FPse and FPseNG and it's working fine with RetroArch, NetherSX2, ePSXe, DuckStation and Yuzu. Note however that this is not a complete list as not all emulators have been tested for this problem.
+
+If you run into this issue you can use the _folder link_ functionality as an alternative to the _directories interpreted as files_ functionality. How to use folder links is described in the [User guide](USERGUIDE.md).
+
+The second problem is that a number of emulators can't be launched from ES-DE at all. When attempting to run such an emulator an error popup with the game name followed by "ERROR CODE -1" is displayed. The affected emulators are ColEm, fMSX, iNES, MasterGear, My Boy!, My OldBoy!, Redream and Speccy.
+
+The following devices have been tested and do **not** experience either of these two problems:
+
+* Ayn Odin Lite (Android 11)
+* Retroid Pocket 4 Pro (Android 13)
+* Google Pixel 4a (Android 13)
+* Google Pixel Tablet (Android 14)
+
+There are also some issues with sound quality on the Odin 2, such as large fluctuations in volume where some sounds are quite loud and some are quite silent. There are also some strange aliasing effects when playing samples rapidly.
+
+## Known ES-DE problems
+
+In addition to the issues specific to the Ayn Odin 2 there are a couple of other problems that will hopefully be resolved in the near future:
+
+* Poor performance/low frame rate after startup on some devices, which seems to happen randomly and is usually resolved by itself within 10 to 30 seconds.
+* The Android soft keyboard causes rendering issues when navigating using a controller or physical keyboard, as such the ES-DE built-in keyboard is enabled by default for the time being. For testing purposes the Android soft keyboard can be enabled via the _Enable virtual keyboard_ option in the _UI settings_ menu. If only using touch input the issue is not present. This problem is believed to be caused by a bug in the SDL library so it probably needs to be resolved there.
+
+## Emulator installation and setup
+
+Below are specific instructions and considerations for all supported emulators.
+
+### RetroArch
+
+The RetroArch release in the Play Store is not very good and is therefore not recommended. To get access to all cores make sure to instead manually download and install the 64-bit/aarch64 APK from their website.
+
+https://retroarch.com/
+
+Or you could alternatively install their release on the F-Droid store.
+
+https://f-droid.org/en/packages/com.retroarch
+
+Be aware that you need to manually install every core you want to use from inside the RetroArch user interface, and you also need to install all necessary BIOS files. The Android release of RetroArch is pretty unforgiving and will usually just present a black screen on game launch if the core file or the BIOS file is missing, and it will hang there until Android realizes the app is not responding and displays a popup where you can choose to kill the process.
+
+### AetherSX2 / NetherSX2
+
+Although the emulator entry is named AetherSX2 the recommended release of this emulator is actually the NetherSX2 patched version as the AetherSX2 release on the Google Play store doesn't work correctly and probably can't be used with ES-DE at all. You'll need to search for this APK online, the filename you'll want is `15210-v1.5-4248-noads.apk`
+
+If you prefer to apply the NetherSX2 patch yourself (i.e. build the APK) then you can find all relevant information here:
+
+https://github.com/Trixarian/NetherSX2-patch
+
+### Citra
+
+The version of Citra on the Google Play store is very old and barely works. Instead download either the Canary or Nightly builds from the Citra website or use the Citra MMJ fork:
+
+https://citra-emu.org/download \
+https://github.com/weihuoya/citra/releases
+
+### ColEm
+
+This emulator can be installed from the Play store. There is a paid version as well named ColEm Deluxe (ColEm+ ColecoVision Emulator is the store listing name).
+
+Although this emulator supports both the Adam and ColecoVision systems it can unfortunately not do both interchangeably. In order to play Adam games you need to go into the Emulation settings in ColEm and tick the _Coleco Adam_ box. And likewise you'll need to untick it any time you want to play a ColecoVision game. This is true for launching games from ES-DE as well as starting them from inside the emulator GUI.
+
+https://play.google.com/store/apps/details?id=com.fms.colem \
+https://play.google.com/store/apps/details?id=com.fms.colem.deluxe
+
+### Dolphin
+
+The Play store version is somehow up to date and could be used, otherwise the F-Droid store version is up to date, or you could download the latest release directly from their website.
+
+https://play.google.com/store/apps/details?id=org.dolphinemu.dolphinemu \
+https://f-droid.org/en/packages/org.dolphinemu.dolphinemu \
+https://dolphin-emu.org/download/
+
+In the past there were multiple unofficial ports, but these are not really recommended any longer as most of them don't seem to have been updated in a long time and are likely to have been surpassed by the official Dolphin release.
+
+### DraStic
+
+This emulator can be installed from the Play store as a paid app. Note that it does not support launching of zipped game files.
+
+https://play.google.com/store/apps/details?id=com.dsemu.drastic
+
+### DuckStation
+
+The Play store version of this emulator is getting frequent updates and is therefore recommended.
+
+https://play.google.com/store/apps/details?id=com.github.stenzek.duckstation
+
+### EKA2L1
+
+This emulator can be downloaded from their GitHub site.
+
+https://github.com/EKA2L1/EKA2L1/releases
+
+There does not seem to be a way to launch individual EKA2L1 games from a frontend application on Android, instead ES-DE will simply launch the EKA2L1 user interface and you'll have to manually start your game from there.
+
+### ePSXe
+
+This emulator can be installed from the Play store as a paid app.
+
+https://play.google.com/store/apps/details?id=com.epsxe.ePSXe
+
+### EX Plus Alpha emulators
+
+These set of emulators also known as the "Robert Broglia" emulators consist of 2600.emu, C64.emu, GBA.emu, GBC.emu, Lynx.emu, NEO.emu, NES.emu, NGP.emu, MD.emu, MSX.emu, PCE.emu, Snes9x EX+, Saturn.emu and Swan.emu
+
+You can install them via Google Play (as paid apps) or download them from their GitHub automatic build system.
+
+https://play.google.com/store/apps/developer?id=Robert+Broglia \
+https://github.com/Rakashazi/emu-ex-plus-alpha/actions
+
+There are also some BIOS files and similar that are needed to run these emulators, and which can be downloaded from their website.
+
+https://www.explusalpha.com/
+
+### Fake-08
+
+This RetroArch core is a good port of the official PICO-8 game engine which does not exist on Android. It's not shipped with RetroArch by default though so you need to manaully install it. After download you'll need to place it inside's RetroArch's downloads directory and then install it from the RetroArch app. Details on how to accomplish this can be found on the Internet. Fake-08 can be downloaded from their GitHub site.
+
+https://github.com/jtothebell/fake-08/releases
+
+### Flycast
+
+Flycast is not available on the Play store or the F-Droid store, but it can be downloaded from their GitHub site.
+
+https://github.com/flyinghead/flycast/releases
+
+### fMSX
+
+This emulator can be installed from the Play store. There is a paid version as well named fMSX Deluxe (fMSX+ MSX/MSX2 Emulator is the store listing name).
+
+https://play.google.com/store/apps/details?id=com.fms.fmsx \
+https://play.google.com/store/apps/details?id=com.fms.fmsx.deluxe
+
+### FPseNG and FPse
+
+These emulators can be installed from the Play store as a paid apps. FPseNG is the more modern version so it's probably best to go for that. Note that these emulators do not support .chd files.
+
+https://play.google.com/store/apps/details?id=com.emulator.fpse64 \
+https://play.google.com/store/apps/details?id=com.emulator.fpse
+
+### iNES
+
+This emulator can be installed from the Play store.
+
+https://play.google.com/store/apps/details?id=com.fms.ines.free
+
+### MAME4droid 2024 and MAME4droid
+
+These emulators can be installed from the Play store. It's strongly recommended to go for the _MAME4droid 2024_ version as this is updated with a frequent MAME release while the older _MAME4droid_ is using an ancient MAME release.
+
+https://play.google.com/store/apps/details?id=com.seleuco.mame4d2024 \
+https://play.google.com/store/apps/details?id=com.seleuco.mame4droid
+
+### MasterGear
+
+This emulator can be installed from the Play store as a paid app.
+
+https://play.google.com/store/apps/details?id=com.fms.mg
+
+### melonDS
+
+This emulator can be installed from the Play store but it's quite buggy. Every time you add a new game to the ROM directory you need to start the emulator and manually refresh the game list or you won't be able to launch the game from ES-DE. Filenames containing parentheses also don't work and need to be renamed or they can't be launched from ES-DE. The same is probably true for a number of additional characters.
+
+https://play.google.com/store/apps/details?id=me.magnum.melonds
+
+### M64Plus FZ
+
+This emulator can be installed from the Play store. The Pro version is recommended to avoid annoying ads.
+
+https://play.google.com/store/apps/details?id=org.mupen64plusae.v3.fzurita.pro \
+https://play.google.com/store/apps/details?id=org.mupen64plusae.v3.fzurita
+
+### My Boy! and My OldBoy!
+
+These emulators can be installed from the Play store as paid apps. There are also free/Lite versions availble for these emulators but they have not been updated in years and don't run on modern devices. As such they are not supported by ES-DE.
+
+https://play.google.com/store/apps/details?id=com.fastemulator.gba \
+https://play.google.com/store/apps/details?id=com.fastemulator.gbc
+
+### Nesoid
+
+Nesoid is not available on the Play store but it can be installed from the F-Droid store, or it can be downloaded from their GitHub site.
+
+https://f-droid.org/en/packages/com.androidemu.nes \
+https://github.com/proninyaroslav/nesoid/releases
+
+### OpenBOR
+
+Although OpenBOR is working fine on Android it's not possible to properly integrate it with a frontend, you'll instead need to install your game PAKs into the `/sdcard/OpenBOR/Paks` directory and create dummy .openbor files for your games in `ROMs/openbor` and after launching a game from ES-DE you need to manually start it from inside the OpenBOR GUI. There are more detailed setup instructions in the _OpenBOR_ section of the [User guide](USERGUIDE-DEV.md#openbor).
+
+You can download OpenBOR from their GitHub site, the version named _OpenBOR v3.0 Build 6391_ has for example been proven to work well.
+
+https://github.com/DCurrent/openbor/releases
+
+### Pizza Boy GBA and Pizza Boy GBC
+
+The Pizza Boy GBA and Pizza Boy GBC emulators can be installed from the Play store. There are Basic (free) versions and Pro (paid) versions available.
+
+As of writing this, the Basic version of the GBA emulator does not seem to be able to launch games from ES-DE, but the Pro version is working fine. Both the Basic and Pro versions of the GBC emulator are working correctly.
+
+https://play.google.com/store/apps/details?id=it.dbtecno.pizzaboygba \
+https://play.google.com/store/apps/details?id=it.dbtecno.pizzaboygbapro \
+https://play.google.com/store/apps/details?id=it.dbtecno.pizzaboy \
+https://play.google.com/store/apps/details?id=it.dbtecno.pizzaboypro
+
+### Play!
+
+This PlayStation 2 emulator can be downloaded from their website.
+
+https://www.purei.org/downloads.php
+
+### PPSSPP
+
+The Play store version of this emulator is getting frequent updates and is therefore recommended. There is a paid Gold version as well which is functionally identical to the free version.
+
+https://play.google.com/store/apps/details?id=org.ppsspp.ppsspp \
+https://play.google.com/store/apps/details?id=org.ppsspp.ppssppgold
+
+### Ruffle
+
+This emulator can be downloaded from their GitHub site.
+
+https://github.com/torokati44/ruffle-android/releases
+
+### Real3DOPlayer
+
+This 3DO Interactive Multiplayer emulator can be downloaded from their website.
+
+http://www.arts-union.ru/node/23
+
+### Redream
+
+This emulator can be installed for free from the Play store and can later be upgraded to the Premium version from inside the application.
+
+https://play.google.com/store/apps/details?id=io.recompiled.redream
+
+### Speccy
+
+This emulator can be installed from the Play store. There is a paid version as well named Speccy Deluxe (Speccy+ ZX Spectrum Emulator is the store listing name).
+
+Although this emulator supports both the Sinclar ZX Spectrum and MGT SAM Coupé systems it can unfortunately not do both interchangeably. In order to play SAM Coupé games you need to go into the Emulation settings in Speccy and select _Sam Coupe_ from the _Computer Model_ selection screen. And likewise you'll need to change it back any time you want to play a ZX Spectrum game. This is true for launching games from ES-DE as well as starting them from inside the emulator GUI.
+
+https://play.google.com/store/apps/details?id=com.fms.speccy \
+https://play.google.com/store/apps/details?id=com.fms.speccy.deluxe
+
+### Vita3K
+
+This PlayStation Vita emulator can be downloaded from their GitHub site. Refer to the User guide for detailed game setup instructions.
+
+https://github.com/Vita3K/Vita3K-Android/releases
+
+### Yuzu
+
+The Play store version of this emulator is getting frequent updates and is therefore recommended. There's an Early Access version as well which is also recommended.
+
+https://play.google.com/store/apps/details?id=org.yuzu.yuzu_emu \
+https://play.google.com/store/apps/details?id=org.yuzu.yuzu_emu.ea
+
+## Supported game systems
+
+All emulators are RetroArch cores unless marked as **(Standalone)**
+
+The **@** symbol indicates that the emulator is _deprecated_ and will be removed in a future ES-DE release.
+
+| System name | Full name | Default emulator | Alternative emulators | Needs BIOS | Recommended game setup |
+| :-------------------- | :--------------------------------------------- | :-------------------------------- | :-------------------------------- | :----------- | :----------------------------------- |
+| 3do | 3DO Interactive Multiplayer | Opera | Real3DOPlayer **(Standalone)** | Yes | |
+| adam | Coleco Adam | ColEm **(Standalone)** | | No | |
+| ags | Adventure Game Studio Game Engine | _Placeholder_ | | | |
+| amiga | Commodore Amiga | PUAE | PUAE 2021 | Yes | |
+| amiga1200 | Commodore Amiga 1200 | PUAE | PUAE 2021 | Yes | |
+| amiga600 | Commodore Amiga 600 | PUAE | PUAE 2021 | Yes | |
+| amigacd32 | Commodore Amiga CD32 | PUAE | PUAE 2021 | Yes | |
+| amstradcpc | Amstrad CPC | Caprice32 | CrocoDS | No | Single archive or disk file |
+| android | Google Android | _Placeholder_ | | | |
+| apple2 | Apple II | _Placeholder_ | | | |
+| apple2gs | Apple IIGS | _Placeholder_ | | | |
+| arcade | Arcade | MAME - Current | MAME 2010, MAME 2003-Plus, MAME 2000, MAME4droid 2024 **(Standalone)**, MAME4droid **(Standalone)**, NEO.emu **(Standalone)**, FinalBurn Neo, FB Alpha 2012, Flycast, Flycast **(Standalone)** | Depends | |
+| arcadia | Emerson Arcadia 2001 | _Placeholder_ | | | |
+| archimedes | Acorn Archimedes | _Placeholder_ | | | |
+| arduboy | Arduboy Miniature Game System | Arduous | | No | Single archive or .hex file |
+| astrocde | Bally Astrocade | _Placeholder_ | | | |
+| atari2600 | Atari 2600 | Stella | Stella 2014, 2600.emu **(Standalone)** | No | Single archive or ROM file |
+| atari5200 | Atari 5200 | a5200 | Atari800 | Yes | Single archive or ROM file |
+| atari7800 | Atari 7800 ProSystem | ProSystem | | Yes | Single archive or ROM file |
+| atari800 | Atari 800 | Atari800 | | Yes | |
+| atarijaguar | Atari Jaguar | Virtual Jaguar | | No | |
+| atarijaguarcd | Atari Jaguar CD | _Placeholder_ | | | |
+| atarilynx | Atari Lynx | Handy | Beetle Lynx, Lynx.emu **(Standalone)** | No | Single archive or ROM file |
+| atarist | Atari ST [also STE and Falcon] | Hatari | | Yes | Single archive or image file for single-diskette games, .m3u playlist for multi-diskette games |
+| atarixe | Atari XE | Atari800 | | Yes | |
+| atomiswave | Sammy Corporation Atomiswave | Flycast | Flycast **(Standalone)** | Depends | Single archive file |
+| bbcmicro | Acorn Computers BBC Micro | _Placeholder_ | | | |
+| c64 | Commodore 64 | VICE x64sc Accurate | VICE x64 Fast, VICE x64 SuperCPU, VICE x128, C64.emu **(Standalone)** | 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 | | Yes | Single .bin/.cue pair |
+| cdtv | Commodore CDTV | PUAE | PUAE 2021 | Yes | |
+| chailove | ChaiLove Game Engine | ChaiLove | | | |
+| channelf | Fairchild Channel F | FreeChaF | | Yes | Single archive or ROM file |
+| coco | Tandy Color Computer | _Placeholder_ | | | |
+| colecovision | Coleco ColecoVision | blueMSX | Gearcoleco, MSX.emu **(Standalone)**, ColEm **(Standalone)** | Yes | Single archive or ROM file |
+| consolearcade | Console Arcade Systems | _Placeholder_ | | | |
+| cps | Capcom Play System | MAME - Current | MAME 2010, MAME 2003-Plus, MAME 2000, MAME4droid 2024 **(Standalone)**, MAME4droid **(Standalone)**, FinalBurn Neo, FB Alpha 2012, FB Alpha 2012 CPS-1, FB Alpha 2012 CPS-2, FB Alpha 2012 CPS-3 | Depends | |
+| cps1 | Capcom Play System I | MAME - Current | MAME 2010, MAME 2003-Plus, MAME 2000, MAME4droid 2024 **(Standalone)**, MAME4droid **(Standalone)**, FinalBurn Neo, FB Alpha 2012, FB Alpha 2012 CPS-1 | Depends | |
+| cps2 | Capcom Play System II | MAME - Current | MAME 2010, MAME 2003-Plus, MAME 2000, MAME4droid 2024 **(Standalone)**, MAME4droid **(Standalone)**, FB Alpha 2012, FB Alpha 2012 CPS-2 | Depends | |
+| cps3 | Capcom Play System III | MAME - Current | MAME 2010, MAME 2003-Plus, MAME 2000, MAME4droid 2024 **(Standalone)**, MAME4droid **(Standalone)**, FB Alpha 2012, FB Alpha 2012 CPS-3 | Depends | |
+| crvision | VTech CreatiVision | _Placeholder_ | | | |
+| daphne | Daphne Arcade LaserDisc Emulator | DirkSimple | | No | |
+| desktop | Desktop Applications | _Placeholder_ | | | |
+| doom | Doom | PrBoom | | No | |
+| dos | DOS (PC) | DOSBox-Pure | DOSBox-Core, DOSBox-SVN | No | |
+| dragon32 | Dragon Data Dragon 32 | _Placeholder_ | | | |
+| dreamcast | Sega Dreamcast | Flycast | Flycast **(Standalone)**, Redream **(Standalone)** | No | In separate folder interpreted as a file, with .m3u playlist if multi-disc game |
+| easyrpg | EasyRPG Game Engine | EasyRPG | | No | |
+| electron | Acorn Electron | _Placeholder_ | | | |
+| emulators | Emulators | _Placeholder_ | | | |
+| epic | Epic Games Store | _Placeholder_ | | | |
+| famicom | Nintendo Family Computer | Mesen | Nestopia UE, FCEUmm, QuickNES, NES.emu **(Standalone)**, iNES **(Standalone)**, Nesoid **(Standalone)** | No | Single archive or ROM file |
+| 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 | |
+| fbneo | FinalBurn Neo | FinalBurn Neo | | Yes | |
+| fds | Nintendo Famicom Disk System | Mesen | Nestopia UE, FCEUmm, NES.emu **(Standalone)**, iNES **(Standalone)**, Nesoid **(Standalone)** | Yes | Single archive or ROM file |
+| flash | Adobe Flash | Ruffle **(Standalone)** | | No | Single .swf file |
+| fm7 | Fujitsu FM-7 | _Placeholder_ | | | |
+| fmtowns | Fujitsu FM Towns | _Placeholder_ | | | |
+| fpinball | Future Pinball | _Placeholder_ | | | |
+| gamate | Bit Corporation Gamate | _Placeholder_ | | | |
+| gameandwatch | Nintendo Game and Watch | Multi (MESS) | MAME4droid 2024 **(Standalone)**, Handheld Electronic (GW) | No | Single archive or ROM file |
+| gamecom | Tiger Electronics Game.com | _Placeholder_ | | | |
+| gamegear | Sega Game Gear | Genesis Plus GX | Genesis Plus GX Wide, Gearsystem, SMS Plus GX, PicoDrive, MasterGear **(Standalone)** | No | Single archive or ROM file |
+| gb | Nintendo Game Boy | Gambatte | SameBoy, Gearboy, TGB Dual, DoubleCherryGB, Mesen-S, bsnes, mGBA, VBA-M, GBC.emu **(Standalone)**, My OldBoy! **(Standalone**), Pizza Boy GBC **(Standalone)** | No | Single archive or ROM file |
+| gba | Nintendo Game Boy Advance | mGBA | VBA-M, VBA Next, gpSP, GBA.emu **(Standalone)**, My Boy! **(Standalone)**, Pizza Boy GBA **(Standalone)** | No | Single archive or ROM file |
+| gbc | Nintendo Game Boy Color | Gambatte | SameBoy, Gearboy, TGB Dual, DoubleCherryGB, Mesen-S, bsnes, mGBA, VBA-M, GBC.emu **(Standalone)**, My OldBoy! **(Standalone**), Pizza Boy GBC **(Standalone)** | No | Single archive or ROM file |
+| gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)** | 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, MD.emu **(Standalone)** | No | Single archive or ROM file |
+| gmaster | Hartung Game Master | _Placeholder_ | | | |
+| gx4000 | Amstrad GX4000 | Caprice32 | CrocoDS | No | Single archive or ROM file |
+| intellivision | Mattel Electronics Intellivision | FreeIntv | | Yes | Single archive or ROM file |
+| j2me | Java 2 Micro Edition (J2ME) | SquirrelJME | | No | Single .jar file |
+| kodi | Kodi Home Theatre Software | _Placeholder_ | | | |
+| laserdisc | LaserDisc Games | DirkSimple | | No | |
+| lcdgames | LCD Handheld Games | Multi (MESS) | MAME4droid 2024 **(Standalone)**, Handheld Electronic (GW) | No | Single archive or ROM file |
+| lowresnx | LowRes NX Fantasy Console | LowRes NX | | No | Single ROM file |
+| lutris | Lutris Open Gaming Platform | _Placeholder_ | | | |
+| lutro | Lutro Game Engine | Lutro | | | |
+| macintosh | Apple Macintosh | _Placeholder_ | | | |
+| mame | Multiple Arcade Machine Emulator | MAME - Current | MAME 2010, MAME 2003-Plus, MAME 2000, MAME4droid 2024 **(Standalone)**, MAME4droid **(Standalone)**, NEO.emu **(Standalone)**, FinalBurn Neo, FB Alpha 2012, Flycast, Flycast **(Standalone)** | Depends | |
+| mame-advmame | AdvanceMAME | _Placeholder_ | | | |
+| mastersystem | Sega Master System | Genesis Plus GX | Genesis Plus GX Wide, SMS Plus GX, Gearsystem, PicoDrive, MD.emu **(Standalone)**, MasterGear **(Standalone)** | No | Single archive or ROM file |
+| megacd | Sega Mega-CD | Genesis Plus GX | Genesis Plus GX Wide, PicoDrive, MD.emu **(Standalone)** | Yes | |
+| megacdjp | Sega Mega-CD [Japan] | Genesis Plus GX | Genesis Plus GX Wide, PicoDrive, MD.emu **(Standalone)** | Yes | |
+| megadrive | Sega Mega Drive | Genesis Plus GX | Genesis Plus GX Wide, PicoDrive, MD.emu **(Standalone)** | No | Single archive or ROM file |
+| megadrivejp | Sega Mega Drive [Japan] | Genesis Plus GX | Genesis Plus GX Wide, PicoDrive, MD.emu **(Standalone)** | No | Single archive or ROM file |
+| megaduck | Creatronic Mega Duck | SameDuck | | No | Single archive or ROM file |
+| mess | Multi Emulator Super System | Multi (MESS) | | | |
+| model2 | Sega Model 2 | MAME - Current | | Yes | |
+| model3 | Sega Model 3 | _Placeholder_ | | | |
+| moto | Thomson MO/TO Series | Theodore | | | |
+| msx | MSX | blueMSX | fMSX, fMSX **(Standalone)**, MSX.emu **(Standalone)** | Yes except for fMSX standalone | |
+| msx1 | MSX1 | blueMSX | fMSX, fMSX **(Standalone)**, MSX.emu **(Standalone)** | Yes except for fMSX standalone | |
+| msx2 | MSX2 | blueMSX | fMSX, fMSX **(Standalone)**, MSX.emu **(Standalone)** | Yes except for fMSX standalone | |
+| msxturbor | MSX Turbo R | blueMSX | fMSX, MSX.emu **(Standalone)** | Yes | |
+| mugen | M.U.G.E.N Game Engine | _Placeholder_ | | Yes | |
+| multivision | Othello Multivision | Gearsystem | MasterGear **(Standalone)** | No | Single archive or ROM file |
+| naomi | Sega NAOMI | Flycast | Flycast **(Standalone)** | Yes | Single archive file + .chd file in subdirectory if GD-ROM game |
+| naomi2 | Sega NAOMI 2 | Flycast | Flycast **(Standalone)** | Yes | Single archive file + .chd file in subdirectory if GD-ROM game |
+| naomigd | Sega NAOMI GD-ROM | Flycast | Flycast **(Standalone)** | Yes | Single archive file + .chd file in subdirectory if GD-ROM game |
+| n3ds | Nintendo 3DS | Citra | Citra **(Standalone)** [Play store version or Nightly], Citra Canary **(Standalone)**, Citra MMJ **(Standalone)** | No | Single ROM file |
+| n64 | Nintendo 64 | Mupen64Plus-Next | M64Plus FZ **(Standalone)**, ParaLLEl N64 | No | Single archive or ROM file |
+| n64dd | Nintendo 64DD | Mupen64Plus-Next | M64Plus FZ **(Standalone)**, ParaLLEl N64 | Yes | |
+| nds | Nintendo DS | melonDS DS | melonDS **(Standalone)**, DeSmuME, DeSmuME 2015, DraStic **(Standalone)** | No | Single archive or ROM file |
+| neogeo | SNK Neo Geo | FinalBurn Neo | NEO.emu **(Standalone)**, MAME4droid 2024 **(Standalone)**, MAME4droid **(Standalone)** | Yes | Single archive or ROM file |
+| neogeocd | SNK Neo Geo CD | NeoCD | FinalBurn Neo | Yes | |
+| neogeocdjp | SNK Neo Geo CD [Japan] | NeoCD | FinalBurn Neo | Yes | |
+| nes | Nintendo Entertainment System | Mesen | Nestopia UE, FCEUmm, QuickNES, NES.emu **(Standalone)**, iNES **(Standalone)**, Nesoid **(Standalone)** | No | Single archive or ROM file |
+| ngage | Nokia N-Gage | EKA2L1 **(Standalone)** | | Yes | See the specific _Symbian and Nokia N-Gage_ section in the User guide |
+| ngp | SNK Neo Geo Pocket | Beetle NeoPop | RACE, NGP.emu **(Standalone)** | No | Single archive or ROM file |
+| ngpc | SNK Neo Geo Pocket Color | Beetle NeoPop | RACE, NGP.emu **(Standalone)** | No | Single archive or ROM file |
+| odyssey2 | Magnavox Odyssey 2 | O2EM | | Yes | Single archive or ROM file |
+| openbor | OpenBOR Game Engine | OpenBOR **(Standalone)** | | No | See the specific _OpenBOR_ section in the User guide |
+| oric | Tangerine Computer Systems Oric | _Placeholder_ | | | |
+| palm | Palm OS | Mu | | | |
+| pc | IBM PC | DOSBox-Pure | DOSBox-Core, DOSBox-SVN | No | |
+| pc88 | NEC PC-8800 Series | QUASI88 | | Yes | |
+| pc98 | NEC PC-9800 Series | Neko Project II Kai | Neko Project II | | |
+| pcarcade | PC Arcade Systems | _Placeholder_ | | | | |
+| pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST, PCE.emu **(Standalone)** | No | Single archive or ROM file |
+| pcenginecd | NEC PC Engine CD | Beetle PCE | Beetle PCE FAST, PCE.emu **(Standalone)** | Yes | |
+| pcfx | NEC PC-FX | Beetle PC-FX | | Yes | |
+| pico8 | PICO-8 Fantasy Console | Fake-08 | Retro8 | No | See the specific _PICO-8_ section in the User guide |
+| plus4 | Commodore Plus/4 | VICE xplus4 | | 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 | ECWolf (Wolfenstein 3D) | NXEngine (Cave Story), OpenLara (Tomb Raider), Super Bros War | Yes for ECWolf | |
+| ps2 | Sony PlayStation 2 | AetherSX2 **(Standalone)** | Play! **(Standalone)** | Yes for AetherSX2 | |
+| ps3 | Sony PlayStation 3 | _Placeholder_ | | | |
+| ps4 | Sony PlayStation 4 | _Placeholder_ | | | |
+| psp | Sony PlayStation Portable | PPSSPP | PPSSPP **(Standalone)** | No | Single disc image file |
+| psvita | Sony PlayStation Vita | Vita3K **(Standalone)** | | Yes | See the specific _Sony PlayStation Vita_ section in the User guide |
+| psx | Sony PlayStation | Beetle PSX | Beetle PSX HW, PCSX ReARMed, SwanStation, DuckStation **(Standalone)**, ePSXe **(Standalone)**, FPseNG **(Standalone)**, FPse **(Standalone)** | Yes | .chd file for single-disc games, .m3u playlist for multi-disc games |
+| pv1000 | Casio PV-1000 | _Placeholder_ | | | |
+| quake | Quake | TyrQuake | vitaQuake 2, vitaQuake 2 [Rogue], vitaQuake 2 [Xatrix], vitaQuake 2 [Zaero] | No | |
+| samcoupe | MGT SAM Coupé | Speccy **(Standalone)** | | No | Single archive or ROM file |
+| satellaview | Nintendo Satellaview | Snes9x - Current | Snes9x 2010, Snes9x EX+ **(Standalone)**, bsnes, bsnes-hd, bsnes-mercury Accuracy, Mesen-S | | |
+| saturn | Sega Saturn | Beetle Saturn | YabaSanshiro, Yabause, Saturn.emu **(Standalone)** | Yes | .chd file for single-disc games, .m3u playlist for multi-disc games |
+| saturnjp | Sega Saturn [Japan] | Beetle Saturn | YabaSanshiro, Yabause, Saturn.emu **(Standalone)** | Yes | .chd file for single-disc games, .m3u playlist for multi-disc games |
+| scummvm | ScummVM Game Engine | ScummVM | | No | |
+| scv | Epoch Super Cassette Vision | _Placeholder_ | | | |
+| sega32x | Sega Mega Drive 32X | PicoDrive | | No | Single archive or ROM file |
+| sega32xjp | Sega Super 32X [Japan] | PicoDrive | | No | Single archive or ROM file |
+| sega32xna | Sega Genesis 32X [North America] | PicoDrive | | No | Single archive or ROM file |
+| segacd | Sega CD | Genesis Plus GX | Genesis Plus GX Wide, PicoDrive, MD.emu **(Standalone)** | Yes | |
+| sfc | Nintendo SFC (Super Famicom) | Snes9x - Current | Snes9x 2010, Snes9x EX+ **(Standalone)**, bsnes, bsnes-hd, bsnes-mercury Accuracy, Beetle Supafaust, Mesen-S | No | Single archive or ROM file |
+| sg-1000 | Sega SG-1000 | Genesis Plus GX | Genesis Plus GX Wide, Gearsystem, blueMSX, MasterGear **(Standalone)** | No | Single archive or ROM file |
+| sgb | Nintendo Super Game Boy | Mesen-S | SameBoy, mGBA | | Single archive or ROM file |
+| snes | Nintendo SNES (Super Nintendo) | Snes9x - Current | Snes9x 2010, Snes9x EX+ **(Standalone)**, bsnes, bsnes-hd, bsnes-mercury Accuracy, Beetle Supafaust, Mesen-S | No | Single archive or ROM file |
+| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010, Snes9x EX+ **(Standalone)**, bsnes, bsnes-hd, bsnes-mercury Accuracy, Beetle Supafaust, Mesen-S | No | Single archive or ROM file |
+| solarus | Solarus Game Engine | _Placeholder_ | | | |
+| spectravideo | Spectravideo | blueMSX | | | |
+| steam | Valve Steam | _Placeholder_ | | | |
+| stv | Sega Titan Video Game System | MAME - Current | MAME4droid 2024 **(Standalone)**, MAME4droid **(Standalone)** | Yes | Single archive file |
+| sufami | Bandai SuFami Turbo | Snes9x - Current | Snes9x 2010, Snes9x EX+ **(Standalone)**, bsnes, bsnes-hd, bsnes-mercury Accuracy | | |
+| supergrafx | NEC SuperGrafx | Beetle SuperGrafx | Beetle PCE, PCE.emu **(Standalone)** | No | Single archive or ROM file |
+| supervision | Watara Supervision | Potator | | No | Single archive or ROM file |
+| supracan | Funtech Super A'Can | _Placeholder_ | | | |
+| switch | Nintendo Switch | Yuzu **(Standalone)** | | Yes | |
+| symbian | Symbian | EKA2L1 **(Standalone)** | | Yes | See the specific _Symbian and Nokia N-Gage_ section in the User guide |
+| tanodragon | Tano Dragon | _Placeholder_ | | | |
+| tg16 | NEC TurboGrafx-16 | Beetle PCE | Beetle PCE FAST, PCE.emu **(Standalone)** | No | Single archive or ROM file |
+| tg-cd | NEC TurboGrafx-CD | Beetle PCE | Beetle PCE FAST, PCE.emu **(Standalone)** | Yes | |
+| ti99 | Texas Instruments TI-99 | _Placeholder_ | | | |
+| tic80 | TIC-80 Fantasy Computer | TIC-80 | | No | Single .tic file |
+| to8 | Thomson TO8 | Theodore | | | |
+| triforce | Namco-Sega-Nintendo Triforce | _Placeholder_ | | | |
+| trs-80 | Tandy TRS-80 | _Placeholder_ | | | |
+| type-x | Taito Type X | _Placeholder_ | | | |
+| uzebox | Uzebox Open Source Console | Uzem | | | |
+| vectrex | GCE Vectrex | vecx | | No | Single archive or ROM file |
+| vic20 | Commodore VIC-20 | VICE xvic | | No | Single archive or tape, cartridge or diskette image file |
+| videopac | Philips Videopac G7000 | O2EM | | Yes | Single archive or ROM file |
+| virtualboy | Nintendo Virtual Boy | Beetle VB | | No | |
+| vpinball | Visual Pinball | _Placeholder_ | | | |
+| vsmile | VTech V.Smile | _Placeholder_ | | | |
+| wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file |
+| wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)** | No | |
+| wiiu | Nintendo Wii U | _Placeholder_ | | | |
+| windows | Microsoft Windows | _Placeholder_ | | | |
+| windows3x | Microsoft Windows 3.x | DOSBox-Pure | | No | |
+| windows9x | Microsoft Windows 9x | DOSBox-Pure | | No | |
+| wonderswan | Bandai WonderSwan | Beetle Cygne | Swan.emu **(Standalone)** | No | Single archive or ROM file |
+| wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | Swan.emu **(Standalone)** | No | Single archive or ROM file |
+| x1 | Sharp X1 | X Millennium | | No | Single archive or diskette/tape file |
+| x68000 | Sharp X68000 | PX68k | | Yes | |
+| xbox | Microsoft Xbox | _Placeholder_ | | | |
+| xbox360 | Microsoft Xbox 360 | _Placeholder_ | | | |
+| zmachine | Infocom Z-machine | _Placeholder_ | | | |
+| zx81 | Sinclair ZX81 | EightyOne | | | |
+| zxnext | Sinclair ZX Spectrum Next | _Placeholder_ | | | |
+| zxspectrum | Sinclair ZX Spectrum | Fuse | Speccy **(Standalone)** | No | Single archive or ROM file |
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e4894ca69..9e0bad016 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,84 @@
-# EmulationStation Desktop Edition (ES-DE) - Changelog
+# ES-DE (EmulationStation Desktop Edition) - Changelog
+
+## Version 3.0.0
+
+**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
+* Renamed the application data directory from .emulationstation to ES-DE
+* Updated the splash screen to reflect the new application name
+* Added a new default theme named "Linear"
+* Split the es_find_rules.xml and es_systems.xml files for Linux and BSD Unix into separate directories
+* Added support for defining font sizes from the theme configuration and selecting these from the UI settings menu
+* Added the theme font sizes count to the theme downloader interface
+* Added support for medium and large font sizes to the Slate and Modern themes
+* Added an option to the Input device settings menu to swap the A/B and X/Y buttons
+* Added support for .webp, .svg and unanimated .gif files to the slideshow screensaver when using a custom image directory
+* Changed the default slideshow custom image directory from slideshow/custom_images to screensavers/custom_slideshow
+* 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 (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
+* Set Mesen standalone to specifically run in Super Game Boy mode for the sgb system on Linux, Unix and Windows
+* Added the DoubleCherryGB RetroArch core as an alternative emulator for the gb and gbc systems on Linux, Unix and Windows
+* Added the MAME - Current RetroArch core as the default emulator for the gameandwatch and lcdgames systems
+* Added the melonDS DS RetroArch core as the default emulator for the nds system
+* (Linux) Added support for the AppImage release of Vita3K
+* (Linux) Added support for the Flatpak release of puNES
+* Added the .zso file extension to the ps2 system
+* Added the .zar file extension to the xbox360 system on Linux and Windows
+* Added the .pk3 and .ipk3 file extensions to the doom system on Linux, Unix and Windows
+* Added the .dirksimple file extension to the daphne and laserdisc systems
+* (Unix) Removed the -Minimized flag from the Visual Pinball launch command
+* (Windows) Updated the find rules for Visual Pinball to match the actual filenames of the official releases
+* (Windows) Added the %RUNINBACKGROUND% variable for the epic system
+* When scraping using ScreenScraper, the wheel and wheel-hd media types are now considered equivalent
+* Added conversion of an additional HTML character code when scraping using ScreenScraper
+* Added a "renderDuringTransitions" property to the image element
+* Added a "selectorWidth" property to the textlist element
+* Added a "hideIfZero" property to the rating element
+* Putting the computer to sleep while a video is playing will no longer result in a massive fast-forward on resume
+* Combining video pillarboxes with rounded corners will no longer round corners for the actual video frame (except for extreme values)
+* Made the text element "defaultValue" property usable with the metadata types systemName, systemFullname, sourceSystemName and sourceSystemFullname
+* Replaced the default d-pad helpsystem images to make them more legible when using smaller screen sizes
+* Placeholder entries in es_systems.xml are now skipped by default when creating the system directories and systeminfo.txt files
+* Added a CreatePlaceholderSystemDirectories option that can be manually set in es_settings.xml to still create placeholder directories
+* Changed the ScreenScraper URL from https://www.screenscraper.fr/api2 to https://api.screenscraper.fr/api2
+* Added support for more extreme vertical resolutions than previously allowed
+* Added support for the 19.5:9, 20:9 and 1:1 display aspect ratios
+* If any legacy theme configuration is encountered the error messages now simply state that the config is unsupported
+* (Windows) Removed support for building the application using MinGW
+* 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
+
+* Attempting to create the system directories with invalid entries in es_systems.xml could crash the application
+* Sometimes controllers were not added correctly when there was a mix of supported and unsupported devices present
+* The last grid row would sometimes not render correctly if fractionalRows was set to true
+* Stationary image elements could sometimes glitch out during carousel navigation
+* Videos were sometimes positioned incorrectly if combining pillarboxes with rounded corners while using an origin value higher than 0.5
+* An extra space character was appended to text elements when setting the systemdata property to gamecountGames or gamecountGamesNoText
+* Theme loading debug output would sometimes print incorrect paths when the configuration included files using variables
+* Font textures were sometimes updated with empty glyhps which generated OpenGL errors on some mobile GPUs
+* The custom collection editing popup did not show the correct button name if the controller type was a PlayStation variant
+* The UI mode confirmation dialog did not show the correct button descriptions if the controller type was PlayStation 1/2/3
## Version 2.2.1
@@ -18,6 +98,8 @@ Some improvements were also made to the systems sorting functionality.
* The Orphaned data cleanup utility will now skip any system where a flatten.txt file is present
* Changed a number of error messages in the Orphaned data cleanup utility from uppercase to lowercase
* The application release number is now tracked on startup instead of the application version
+* (macOS) Reclassified the application as a non-game to disable Game Mode on macOS 14 Sonoma
+* (macOS) Added support for the Visual Pinball (vpinball) game system
* (slate-es-de) Added console graphics for the adam system
* Changed the systems sorting platform from "Peripheral" to "Console" for the fds, megacd, megacdjp, n64dd, pcenginecd and satellaview systems
* Changed the systems sorting platform from "Peripheral" to "Console" for the sega32x, sega32xjp, sega32xna, segacd, sgb, sufami and tg-cd systems
diff --git a/CMake/Packages/FindOpenGLES3.cmake b/CMake/Packages/FindOpenGLES3.cmake
new file mode 100644
index 000000000..5370cdd6e
--- /dev/null
+++ b/CMake/Packages/FindOpenGLES3.cmake
@@ -0,0 +1,32 @@
+# FindOpenGLES
+# ------------
+# Finds the OpenGLES3 library
+#
+# This will define the following variables::
+#
+# OPENGLES3_FOUND - system has OpenGLES
+# OPENGLES3_INCLUDE_DIRS - the OpenGLES include directory
+# OPENGLES3_LIBRARIES - the OpenGLES libraries
+
+if(NOT HINT_GLES_LIBNAME)
+ set(HINT_GLES_LIBNAME GLESv3)
+endif()
+
+find_path(OPENGLES3_INCLUDE_DIR GLES3/gl3.h
+ PATHS "${CMAKE_FIND_ROOT_PATH}/usr/include"
+ HINTS ${HINT_GLES_INCDIR}
+)
+
+find_library(OPENGLES3_gl_LIBRARY
+ NAMES ${HINT_GLES_LIBNAME}
+ HINTS ${HINT_GLES_LIBDIR}
+)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(OpenGLES3 REQUIRED_VARS OPENGLES3_gl_LIBRARY OPENGLES3_INCLUDE_DIR)
+
+if(OPENGLES3_FOUND)
+ set(OPENGLES3_LIBRARIES ${OPENGLES3_gl_LIBRARY})
+ set(OPENGLES3_INCLUDE_DIRS ${OPENGLES3_INCLUDE_DIR})
+ mark_as_advanced(OPENGLES3_INCLUDE_DIR OPENGLES3_gl_LIBRARY)
+endif()
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 4aeec12e7..be3672282 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,6 +1,6 @@
# SPDX-License-Identifier: MIT
#
-# EmulationStation Desktop Edition
+# ES-DE
# CMakeLists.txt
#
# Main CMake configuration file.
@@ -11,15 +11,15 @@
cmake_minimum_required(VERSION 3.13)
if(APPLE)
# Set this to the minimum supported macOS version, and also update
- # es-app/assets/EmulationStation-DE_Info.plist accordingly.
+ # es-app/assets/ES-DE_Info.plist accordingly.
set(CMAKE_OSX_DEPLOYMENT_TARGET 10.15 CACHE STRING "macOS deployment target")
# This optional variable is used for code signing the DMG installer.
set(MACOS_CODESIGN_IDENTITY "" CACHE STRING "macOS code signing certificate identity")
endif()
-project(emulationstation-de)
+project(es-de)
# Application version, update this when making a new release.
-set(ES_VERSION 2.2.1)
+set(ES_VERSION 3.0.0)
# Set this to ON to show verbose compiler output (e.g. compiler flags, include directories etc.)
set(CMAKE_VERBOSE_MAKEFILE OFF CACHE BOOL "Show verbose compiler output" FORCE)
@@ -114,6 +114,8 @@ set_property(CACHE GLSYSTEM PROPERTY STRINGS "Desktop OpenGL" "Embedded OpenGL")
if(GLSYSTEM MATCHES "Desktop OpenGL")
set(OpenGL_GL_PREFERENCE GLVND)
find_package(OpenGL REQUIRED)
+elseif(ANDROID)
+ find_package(OpenGLES3 REQUIRED)
elseif(GLES AND NOT EMSCRIPTEN)
find_package(OpenGLES2 REQUIRED)
endif()
@@ -125,11 +127,10 @@ if(APPLE)
endif()
find_package(CURL REQUIRED)
elseif(WIN32)
- if(NOT EXISTS ${PROJECT_SOURCE_DIR}/external/pugixml/libpugixml.dll AND # MinGW
- NOT EXISTS ${PROJECT_SOURCE_DIR}/external/pugixml/pugixml.dll) # MSVC
+ if(NOT EXISTS ${PROJECT_SOURCE_DIR}/external/pugixml/pugixml.dll)
message(FATAL_ERROR "-- You need to build the dependencies in ./external first")
endif()
-elseif(NOT EMSCRIPTEN)
+elseif(NOT EMSCRIPTEN AND NOT ANDROID)
find_package(CURL REQUIRED)
find_package(FFmpeg REQUIRED)
find_package(FreeImage REQUIRED)
@@ -155,19 +156,16 @@ endif()
if(CMAKE_CXX_COMPILER_ID MATCHES Clang)
message("-- Compiler is Clang/LLVM")
if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.0.0)
- message(SEND_ERROR "You need at least Clang 5.0.0 to compile EmulationStation-DE")
+ message(SEND_ERROR "You need at least Clang 5.0.0 to compile ES-DE")
endif()
elseif(CMAKE_CXX_COMPILER_ID MATCHES GNU)
message("-- Compiler is GNU/GCC")
if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 7.1)
- message(SEND_ERROR "You need at least GCC 7.1 to compile EmulationStation-DE")
- endif()
- if(WIN32)
- set(CMAKE_CXX_FLAGS "-mwindows ${CMAKE_CXX_FLAGS}")
+ message(SEND_ERROR "You need at least GCC 7.1 to compile ES-DE")
endif()
elseif(CMAKE_CXX_COMPILER_ID MATCHES MSVC)
message("-- Compiler is MSVC")
- # If using the MSVC compiler on Windows, disable the built-in min() and max() macros.
+ # Disable the built-in min() and max() macros.
add_compile_definitions(NOMINMAX)
endif()
@@ -218,12 +216,17 @@ if(APPLE AND CMAKE_CXX_COMPILER_VERSION GREATER_EQUAL 15.0.0)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-invalid-utf8")
endif()
+if(ANDROID)
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fvisibility=hidden")
+ set(CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS} -llog")
+endif()
+
if(EMSCRIPTEN)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -s USE_SDL=2 -pthread")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s INITIAL_MEMORY=33554432 -s ALLOW_MEMORY_GROWTH=1 -s WASM=1 -s ASSERTIONS=1 -s EXIT_RUNTIME=1 -s USE_SDL=2 \
-pthread -s PTHREAD_POOL_SIZE=4 -s DEMANGLE_SUPPORT=1 -s USE_WEBGL2=1 -s FULL_ES3=1 -s ERROR_ON_UNDEFINED_SYMBOLS=1 -s ASYNCIFY \
- --preload-file ${PROJECT_SOURCE_DIR}/resources@/home/web_user/.emulationstation/resources/ \
- --preload-file ${PROJECT_SOURCE_DIR}/themes/slate-es-de@/home/web_user/.emulationstation/themes/slate-es-de/ \
+ --preload-file ${PROJECT_SOURCE_DIR}/resources@/home/web_user/ES-DE/resources/ \
+ --preload-file ${PROJECT_SOURCE_DIR}/themes/slate-es-de@/home/web_user/ES-DE/themes/slate-es-de/ \
--preload-file ${PROJECT_SOURCE_DIR}/ROMs@/home/web_user/ROMs/")
endif()
@@ -278,6 +281,16 @@ if(APPLE)
endif()
endif()
+if(ANDROID)
+ set(BUNDLED_CERTS ON)
+ if(ANDROID_LITE_RELEASE)
+ add_compile_definitions(ANDROID_APPLICATION_ID="org.es_de.frontend.lite")
+ add_compile_definitions(ANDROID_LITE_RELEASE)
+ else()
+ add_compile_definitions(ANDROID_APPLICATION_ID="org.es_de.frontend")
+ endif()
+endif()
+
if(WIN32)
set(BUNDLED_CERTS ON)
add_compile_definitions(UNICODE)
@@ -348,7 +361,7 @@ if(VIDEO_HW_DECODING)
message("-- Building with FFmpeg HW decoding")
endif()
-if(AUR_BUILD OR FLATPAK_BUILD OR RETRODECK OR RPI)
+if(AUR_BUILD OR FLATPAK_BUILD OR RETRODECK OR RPI OR ANDROID)
set(APPLICATION_UPDATER OFF)
endif()
@@ -379,6 +392,23 @@ if(APPLE)
endif()
endif()
+if(ANDROID)
+ if(ANDROID_ABI MATCHES arm64-v8a)
+ message("-- Building for Android arm64-v8a on API level ${ANDROID_PLATFORM}")
+ set(ANDROID_CPU_ARCH arm64-v8a)
+ elseif(ANDROID_ABI MATCHES x86_64)
+ message("-- Building for Android x86_64 on API level ${ANDROID_PLATFORM}")
+ set(ANDROID_CPU_ARCH x86_64)
+ else()
+ message(FATAL_ERROR "-- Unsupported Android ABI: " ${ANDROID_ABI})
+ endif()
+ if(ANDROID_LITE_RELEASE)
+ message("-- Building Lite release")
+ else()
+ message("-- Building full release")
+ endif()
+endif()
+
# Affects the application updater and is used for displaying version info in the main menu.
if(ES_VERSION MATCHES alpha OR ES_VERSION MATCHES beta OR ES_VERSION MATCHES dev)
add_compile_definitions(IS_PRERELEASE)
@@ -390,7 +420,7 @@ add_compile_definitions(GLM_FORCE_XYZW_ONLY)
# For Unix systems, assign the installation prefix. If it's not explicitly set,
# we use /usr on Linux, /usr/pkg on NetBSD and /usr/local on FreeBSD and OpenBSD.
-if(NOT WIN32 AND NOT APPLE)
+if(NOT WIN32 AND NOT APPLE AND NOT ANDROID)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
if(CMAKE_SYSTEM_NAME MATCHES Linux)
set(CMAKE_INSTALL_PREFIX /usr CACHE INTERNAL CMAKE_INSTALL_PREFIX)
@@ -419,7 +449,9 @@ set(COMMON_INCLUDE_DIRS ${CURL_INCLUDE_DIR}
${CMAKE_CURRENT_SOURCE_DIR}/external/lunasvg/include
${CMAKE_CURRENT_SOURCE_DIR}/external/rapidjson/include
${CMAKE_CURRENT_SOURCE_DIR}/external/rlottie/inc
- ${CMAKE_CURRENT_SOURCE_DIR}/es-core/src)
+ ${CMAKE_CURRENT_SOURCE_DIR}/external/utfcpp/source
+ ${CMAKE_CURRENT_SOURCE_DIR}/es-core/src
+ ${CMAKE_CURRENT_SOURCE_DIR}/es-pdf-converter/src)
if(APPLE)
set(COMMON_INCLUDE_DIRS ${COMMON_INCLUDE_DIRS}
@@ -446,6 +478,15 @@ elseif(EMSCRIPTEN)
${CMAKE_CURRENT_SOURCE_DIR}/external/FreeImage-CMake/FreeImage/Source
${CMAKE_CURRENT_SOURCE_DIR}/external/freetype/include
${CMAKE_CURRENT_SOURCE_DIR}/external/pugixml/src)
+elseif(ANDROID)
+ set(COMMON_INCLUDE_DIRS ${COMMON_INCLUDE_DIRS}
+ ${CMAKE_CURRENT_SOURCE_DIR}/external/curl/include
+ ${CMAKE_CURRENT_SOURCE_DIR}/external/ffmpeg-kit/src/ffmpeg
+ ${CMAKE_CURRENT_SOURCE_DIR}/external/freeimage/FreeImage/Source
+ ${CMAKE_CURRENT_SOURCE_DIR}/external/freetype/include
+ ${CMAKE_CURRENT_SOURCE_DIR}/external/libgit2/include
+ ${CMAKE_CURRENT_SOURCE_DIR}/external/pugixml/src
+ ${CMAKE_CURRENT_SOURCE_DIR}/external/SDL_Android)
else()
set(COMMON_INCLUDE_DIRS ${COMMON_INCLUDE_DIRS}
${FFMPEG_INCLUDE_DIRS}
@@ -491,44 +532,43 @@ if(APPLE)
${PROJECT_SOURCE_DIR}/libpugixml.a
${PROJECT_SOURCE_DIR}/libSDL2-2.0.0.dylib)
elseif(WIN32)
- if(CMAKE_CXX_COMPILER_ID MATCHES MSVC)
- set(COMMON_LIBRARIES ${PROJECT_SOURCE_DIR}/avcodec.lib
- ${PROJECT_SOURCE_DIR}/avfilter.lib
- ${PROJECT_SOURCE_DIR}/avformat.lib
- ${PROJECT_SOURCE_DIR}/avutil.lib
- ${PROJECT_SOURCE_DIR}/swresample.lib
- ${PROJECT_SOURCE_DIR}/swscale.lib
- ${PROJECT_SOURCE_DIR}/FreeImage.lib
- ${PROJECT_SOURCE_DIR}/git2.lib
- ${PROJECT_SOURCE_DIR}/glew32.lib
- ${PROJECT_SOURCE_DIR}/libcurl-x64.lib
- ${PROJECT_SOURCE_DIR}/freetype.lib
- ${PROJECT_SOURCE_DIR}/lunasvg.lib
- ${PROJECT_SOURCE_DIR}/pugixml.lib
- ${PROJECT_SOURCE_DIR}/rlottie.lib
- ${PROJECT_SOURCE_DIR}/SDL2main.lib
- ${PROJECT_SOURCE_DIR}/SDL2.lib
- Winmm.dll)
- else()
- set(COMMON_LIBRARIES ${PROJECT_SOURCE_DIR}/avcodec-60.dll
- ${PROJECT_SOURCE_DIR}/avfilter-9.dll
- ${PROJECT_SOURCE_DIR}/avformat-60.dll
- ${PROJECT_SOURCE_DIR}/avutil-58.dll
- ${PROJECT_SOURCE_DIR}/swresample-4.dll
- ${PROJECT_SOURCE_DIR}/swscale-7.dll
- ${PROJECT_SOURCE_DIR}/FreeImage.dll
- ${PROJECT_SOURCE_DIR}/libgit2.dll
- ${PROJECT_SOURCE_DIR}/glew32.dll
- ${PROJECT_SOURCE_DIR}/libcurl-x64.dll
- ${PROJECT_SOURCE_DIR}/libfreetype.dll
- ${PROJECT_SOURCE_DIR}/liblunasvg.dll
- ${PROJECT_SOURCE_DIR}/libpugixml.dll
- ${PROJECT_SOURCE_DIR}/libSDL2main.a
- ${PROJECT_SOURCE_DIR}/librlottie.dll
- ${PROJECT_SOURCE_DIR}/SDL2.dll
- mingw32
- Winmm.dll)
- endif()
+ set(COMMON_LIBRARIES ${PROJECT_SOURCE_DIR}/avcodec.lib
+ ${PROJECT_SOURCE_DIR}/avfilter.lib
+ ${PROJECT_SOURCE_DIR}/avformat.lib
+ ${PROJECT_SOURCE_DIR}/avutil.lib
+ ${PROJECT_SOURCE_DIR}/swresample.lib
+ ${PROJECT_SOURCE_DIR}/swscale.lib
+ ${PROJECT_SOURCE_DIR}/FreeImage.lib
+ ${PROJECT_SOURCE_DIR}/git2.lib
+ ${PROJECT_SOURCE_DIR}/glew32.lib
+ ${PROJECT_SOURCE_DIR}/libcurl-x64.lib
+ ${PROJECT_SOURCE_DIR}/freetype.lib
+ ${PROJECT_SOURCE_DIR}/lunasvg.lib
+ ${PROJECT_SOURCE_DIR}/pugixml.lib
+ ${PROJECT_SOURCE_DIR}/rlottie.lib
+ ${PROJECT_SOURCE_DIR}/SDL2main.lib
+ ${PROJECT_SOURCE_DIR}/SDL2.lib
+ Winmm.dll)
+elseif(ANDROID)
+ set(COMMON_LIBRARIES ${COMMON_LIBRARIES}
+ # FFmpeg libraries.
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libavcodec.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libavfilter.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libavformat.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libavutil.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libswresample.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libswscale.so
+ # Other dependencies.
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libcurl.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libcrypto.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libfreeimage.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libfreetype.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libgit2.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libjpeg.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libpoppler.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libpugixml.a
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libSDL2.so
+ ${PROJECT_SOURCE_DIR}/android/libs/${ANDROID_CPU_ARCH}/libssl.so)
elseif(EMSCRIPTEN)
set(COMMON_LIBRARIES ${COMMON_LIBRARIES}
# FFmpeg core libraries.
@@ -573,16 +613,25 @@ else()
endif()
if(NOT WIN32)
- # SVG rendering library LunaSVG.
- set(COMMON_LIBRARIES ${COMMON_LIBRARIES} ${PROJECT_SOURCE_DIR}/liblunasvg.a)
- # Lottie animation library rlottie.
- set(COMMON_LIBRARIES ${COMMON_LIBRARIES} ${PROJECT_SOURCE_DIR}/librlottie.a)
+ # SVG rendering library LunaSVG and Lottie animation library rlottie.
+ if(ANDROID)
+ if(ANDROID_LITE_RELEASE)
+ set(COMMON_LIBRARIES ${COMMON_LIBRARIES} ${PROJECT_SOURCE_DIR}/android_lite_${ANDROID_ABI}/liblunasvg.a)
+ set(COMMON_LIBRARIES ${COMMON_LIBRARIES} ${PROJECT_SOURCE_DIR}/android_lite_${ANDROID_ABI}/librlottie.a)
+ else()
+ set(COMMON_LIBRARIES ${COMMON_LIBRARIES} ${PROJECT_SOURCE_DIR}/android_${ANDROID_ABI}/liblunasvg.a)
+ set(COMMON_LIBRARIES ${COMMON_LIBRARIES} ${PROJECT_SOURCE_DIR}/android_${ANDROID_ABI}/librlottie.a)
+ endif()
+ else()
+ set(COMMON_LIBRARIES ${COMMON_LIBRARIES} ${PROJECT_SOURCE_DIR}/liblunasvg.a)
+ set(COMMON_LIBRARIES ${COMMON_LIBRARIES} ${PROJECT_SOURCE_DIR}/librlottie.a)
+ endif()
endif()
if(APPLE)
# See es-app/CMakeLists.txt for an explation for why an extra "Resources" directory
# has been added to the install prefix.
- set(CMAKE_INSTALL_PREFIX "/Applications/EmulationStation Desktop Edition.app/Contents/Resources")
+ set(CMAKE_INSTALL_PREFIX "/Applications/ES-DE.app/Contents/Resources")
# Set the same rpath links for the install executable as for the build executable.
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
@@ -611,6 +660,8 @@ endif()
# OpenGL.
if(GLSYSTEM MATCHES "Desktop OpenGL")
list(APPEND COMMON_LIBRARIES ${OPENGL_LIBRARIES})
+elseif(GLES AND ANDROID)
+ list(APPEND COMMON_LIBRARIES ${OPENGLES3_LIBRARIES})
elseif(GLES)
list(APPEND COMMON_LIBRARIES ${OPENGLES2_LIBRARIES})
endif()
@@ -631,5 +682,6 @@ add_subdirectory(es-app)
# Make sure that es-pdf-convert is built first, and then that rlottie is built before es-core.
# Also set lottie2gif to not be built.
add_dependencies(lunasvg es-pdf-convert)
+
add_dependencies(es-core rlottie)
set_target_properties(lottie2gif PROPERTIES EXCLUDE_FROM_ALL 1 EXCLUDE_FROM_DEFAULT_BUILD 1)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 66fd2d33d..aeeb03431 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) - Contributing
+# ES-DE (EmulationStation Desktop Edition) - Contributing
### Help needed
diff --git a/CREDITS.md b/CREDITS.md
index 60df4ea0a..02c14c5a9 100644
--- a/CREDITS.md
+++ b/CREDITS.md
@@ -1,11 +1,10 @@
-# EmulationStation Desktop Edition (ES-DE) - Credits
+# ES-DE (EmulationStation Desktop Edition) - Credits
# Programming
-**Desktop Edition**\
+**ES-DE**\
Leon Styhre \
-Sophia Hadash \
-Joseph Geumlek
+Sophia Hadash
**RetroPie fork**\
RetroPie community
@@ -74,6 +73,9 @@ https://github.com/Samsung/rlottie
SDL \
https://www.libsdl.org
+UTF8-CPP \
+https://github.com/nemtrif/utfcpp
+
Vorbis \
https://gitlab.xiph.org/xiph/vorbis
diff --git a/FAQ.md b/FAQ.md
index f97782154..594b8ac05 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -1,20 +1,16 @@
-# EmulationStation Desktop Edition (ES-DE) - Frequently Asked Questions
+# 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-DEV.md b/INSTALL-DEV.md
index 3c33c97af..614b80ff3 100644
--- a/INSTALL-DEV.md
+++ b/INSTALL-DEV.md
@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) v2.2 (development version) - Building and advanced configuration
+# ES-DE (EmulationStation Desktop Edition) v3.0 (development version) - Building and advanced configuration
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 [INSTALL.md](INSTALL.md) instead.
@@ -162,7 +162,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.
@@ -175,7 +175,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:
@@ -196,17 +196,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.
@@ -215,7 +215,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.
@@ -303,35 +303,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.
@@ -346,23 +346,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:
@@ -377,11 +377,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:
@@ -391,17 +391,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**
@@ -576,37 +576,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/
@@ -614,7 +614,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/
@@ -630,19 +630,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**
@@ -679,21 +675,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: \
@@ -709,7 +690,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-DEV.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**
@@ -726,29 +707,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.
@@ -777,31 +750,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**
@@ -829,24 +778,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.
@@ -1017,9 +966,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.
@@ -1051,16 +1000,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-DEV.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.
```
@@ -1091,13 +1042,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:
```
@@ -1118,6 +1069,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.
@@ -1132,7 +1087,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**
@@ -1154,369 +1109,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.
-
-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 _Other 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_.
+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
-
+
@@ -1552,10 +1166,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
@@ -1765,14 +1375,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:
@@ -1781,17 +1874,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-DEV.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**
@@ -1922,7 +2015,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
@@ -1932,7 +2025,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)
```
@@ -1954,26 +2047,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.
@@ -1982,12 +2075,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!
@@ -2030,7 +2123,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**
@@ -2041,7 +2134,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:
@@ -2049,14 +2142,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").
@@ -2065,15 +2158,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
@@ -2101,7 +2193,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.
@@ -2109,8 +2201,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/INSTALL.md b/INSTALL.md
index ab1ec48a2..95c18a21f 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) 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 _Other 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/LICENSE b/LICENSE
index 5f27c157e..84a609b0d 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2020-2023 Leon Styhre
+Copyright (c) 2020-2024 Leon Styhre
Copyright (c) 2014 Alec Lofquist
Permission is hereby granted, free of charge, to any person obtaining a copy
diff --git a/README.md b/README.md
index f5dbb1713..6f207fde1 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE)
+# ES-DE (EmulationStation Desktop Edition)
EmulationStation Desktop Edition is a frontend for browsing and launching games from your multi-platform game collection.
diff --git a/ROADMAP.md b/ROADMAP.md
index 6e6584f42..6f2898e06 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) - Feature roadmap
+# ES-DE (EmulationStation Desktop Edition) - Feature roadmap
ES-DE is developed using an agile methodology so which features to include per release is reviewed and adjusted continuously. As such this document is basically a list of the main features that are planned to be added eventually.
diff --git a/THEMES-DEV.md b/THEMES-DEV.md
index cf3e2b108..cf78e75de 100644
--- a/THEMES-DEV.md
+++ b/THEMES-DEV.md
@@ -1,8 +1,8 @@
-# EmulationStation Desktop Edition (ES-DE) v2.2 (development version) - Themes
+# ES-DE (EmulationStation Desktop Edition) v3.0 (development version) - Themes
**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:
@@ -18,7 +18,7 @@ https://github.com/lilbud/es-de-theme-stuff
To test whether your theme includes support for all ES-DE systems, download one of the following archives which contain ROM directory trees fully populated with dummy files:
-[ROMs_ALL_Unix.zip](tools/system-dirs-dummy-files/ROMs_ALL_Unix.zip)\
+[ROMs_ALL_Linux.zip](tools/system-dirs-dummy-files/ROMs_ALL_Linux.zip)\
[ROMs_ALL_macOS.zip](tools/system-dirs-dummy-files/ROMs_ALL_macOS.zip)\
[ROMs_ALL_Windows.zip](tools/system-dirs-dummy-files/ROMs_ALL_Windows.zip)
@@ -158,17 +158,19 @@ Note that the legacy theme engine had quite inaccurate text sizing and font rend
* The defined line spacing was not always applied for automatically sized text elements
* Font sizes were rounded to integers, leading to imprecise text sizing across different resolutions (the rounding was also done incorrectly)
-## System metadata and logo repositories
+## Theme assets repositories
-There are two useful repositories hosted by the ES-DE project that provide system metadata and system logotypes. This greatly simplifies the work of adding support for all systems that ES-DE supports.
+There are several useful repositories hosted by the ES-DE project that provide system metadata and system graphics files. Using these greatly simplifies the work of adding support for all ES-DE systems to your theme.
-**Metadata**
+Make sure to regularly check for updates in these repositories as corrections, improvements and additions of new systems are made continuously.
+
+### Metadata
The metadata repository provides descriptions, release dates, per-system color palettes etc. and it can be found here:
https://gitlab.com/es-de/themes/system-metadata
-By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Make sure to regularly check for updates as corrections and additions of new systems are done continuously. Also check the README.md file in the repository for more details on how to actually use the variables.
+By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Check the README.md file in the repository for details on how to actually use the variables.
Here's how to add this repository as a subtree inside your theme's Git repository:
```
@@ -183,9 +185,47 @@ git subtree pull --prefix=system-metadata --squash system-metadata master
The directory name can be changed to whatever you like using the --prefix flag.
-**Logos**
+### Controller outline graphics
-Likewise there's a repository of system logotypes that can also be added and used in the same fashion as the metadata. It can be found here:
+This repository provides controller graphics files for each system in an outline style and it can be found here:
+
+https://gitlab.com/es-de/themes/system-controllers-outline
+
+Here's how to add this repository as a subtree inside your theme's Git repository:
+```
+git remote add system-controllers-outline https://gitlab.com/es-de/themes/system-controllers-outline.git
+git subtree add --prefix=system-controllers-outline --squash system-controllers-outline master
+```
+
+To later pull in repository updates you'll run the following:
+```
+git subtree pull --prefix=system-controllers-outline --squash system-controllers-outline master
+```
+
+The directory name can be changed to whatever you like using the --prefix flag.
+
+### Mini system graphics
+
+This repository provides graphics files for each system in a "mini" style and it can be found here:
+
+https://gitlab.com/es-de/themes/system-graphics-mini
+
+Here's how to add this repository as a subtree inside your theme's Git repository:
+```
+git remote add system-graphics-mini https://gitlab.com/es-de/themes/system-graphics-mini.git
+git subtree add --prefix=system-graphics-mini --squash system-graphics-mini master
+```
+
+To later pull in repository updates you'll run the following:
+```
+git subtree pull --prefix=system-graphics-mini --squash system-graphics-mini master
+```
+
+The directory name can be changed to whatever you like using the --prefix flag.
+
+### Logos
+
+This repository provides logos for each system in color and white (the latter for use with color shifting) and it can be found here:
https://gitlab.com/es-de/themes/system-logos
@@ -202,11 +242,13 @@ git subtree pull --prefix=system-logos --squash system-logos master
The directory name can be changed to whatever you like using the --prefix flag.
-**Adding remotes**
+### Adding remotes
-Note that the remotes are only setup for your local repository, so if you clone a theme you'll need to manually add the system-metadata and/or system-logos remotes to be able to pull to these subtrees. That means you'll need to run the following commands on a freshly cloned theme repository:
+Note that the remotes are only setup for your local repository, so if you clone a theme you'll need to manually add the repository remotes to be able to pull from these subtrees. That means you'll need to run one or more of the following commands on a freshly cloned theme repository:
```
git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git
+git remote add system-controllers-outline https://gitlab.com/es-de/themes/system-controllers-outline.git
+git remote add system-graphics-mini https://gitlab.com/es-de/themes/system-graphics-mini.git
git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git
```
After doing this you'll be able to pull repository updates as described above.
@@ -611,6 +653,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.
@@ -836,15 +967,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.
@@ -1287,10 +1421,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.
@@ -1299,7 +1434,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
@@ -1872,6 +2007,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`
@@ -2033,6 +2172,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`
@@ -2603,7 +2746,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`
@@ -2884,6 +3027,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
@@ -2946,7 +3092,7 @@ Properties:
#### helpsystem
-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.
+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.
diff --git a/THEMES.md b/THEMES.md
index b503af69a..28dea259d 100644
--- a/THEMES.md
+++ b/THEMES.md
@@ -1,6 +1,6 @@
-# EmulationStation Desktop Edition (ES-DE) 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:
@@ -16,7 +16,7 @@ https://github.com/lilbud/es-de-theme-stuff
To test whether your theme includes support for all ES-DE systems, download one of the following archives which contain ROM directory trees fully populated with dummy files:
-[ROMs_ALL_Unix.zip](tools/system-dirs-dummy-files/ROMs_ALL_Unix.zip)\
+[ROMs_ALL_Linux.zip](tools/system-dirs-dummy-files/ROMs_ALL_Linux.zip)\
[ROMs_ALL_macOS.zip](tools/system-dirs-dummy-files/ROMs_ALL_macOS.zip)\
[ROMs_ALL_Windows.zip](tools/system-dirs-dummy-files/ROMs_ALL_Windows.zip)
@@ -156,17 +156,19 @@ Note that the legacy theme engine had quite inaccurate text sizing and font rend
* The defined line spacing was not always applied for automatically sized text elements
* Font sizes were rounded to integers, leading to imprecise text sizing across different resolutions (the rounding was also done incorrectly)
-## System metadata and logo repositories
+## Theme assets repositories
-There are two useful repositories hosted by the ES-DE project that provide system metadata and system logotypes. This greatly simplifies the work of adding support for all systems that ES-DE supports.
+There are several useful repositories hosted by the ES-DE project that provide system metadata and system graphics files. Using these greatly simplifies the work of adding support for all ES-DE systems to your theme.
-**Metadata**
+Make sure to regularly check for updates in these repositories as corrections, improvements and additions of new systems are made continuously.
+
+### Metadata
The metadata repository provides descriptions, release dates, per-system color palettes etc. and it can be found here:
https://gitlab.com/es-de/themes/system-metadata
-By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Make sure to regularly check for updates as corrections and additions of new systems are done continuously. Also check the README.md file in the repository for more details on how to actually use the variables.
+By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Check the README.md file in the repository for details on how to actually use the variables.
Here's how to add this repository as a subtree inside your theme's Git repository:
```
@@ -181,9 +183,47 @@ git subtree pull --prefix=system-metadata --squash system-metadata master
The directory name can be changed to whatever you like using the --prefix flag.
-**Logos**
+### Controller outline graphics
-Likewise there's a repository of system logotypes that can also be added and used in the same fashion as the metadata. It can be found here:
+This repository provides controller graphics files for each system in an outline style and it can be found here:
+
+https://gitlab.com/es-de/themes/system-controllers-outline
+
+Here's how to add this repository as a subtree inside your theme's Git repository:
+```
+git remote add system-controllers-outline https://gitlab.com/es-de/themes/system-controllers-outline.git
+git subtree add --prefix=system-controllers-outline --squash system-controllers-outline master
+```
+
+To later pull in repository updates you'll run the following:
+```
+git subtree pull --prefix=system-controllers-outline --squash system-controllers-outline master
+```
+
+The directory name can be changed to whatever you like using the --prefix flag.
+
+### Mini system graphics
+
+This repository provides graphics files for each system in a "mini" style and it can be found here:
+
+https://gitlab.com/es-de/themes/system-graphics-mini
+
+Here's how to add this repository as a subtree inside your theme's Git repository:
+```
+git remote add system-graphics-mini https://gitlab.com/es-de/themes/system-graphics-mini.git
+git subtree add --prefix=system-graphics-mini --squash system-graphics-mini master
+```
+
+To later pull in repository updates you'll run the following:
+```
+git subtree pull --prefix=system-graphics-mini --squash system-graphics-mini master
+```
+
+The directory name can be changed to whatever you like using the --prefix flag.
+
+### Logos
+
+This repository provides logos for each system in color and white (the latter for use with color shifting) and it can be found here:
https://gitlab.com/es-de/themes/system-logos
@@ -200,11 +240,13 @@ git subtree pull --prefix=system-logos --squash system-logos master
The directory name can be changed to whatever you like using the --prefix flag.
-**Adding remotes**
+### Adding remotes
-Note that the remotes are only setup for your local repository, so if you clone a theme you'll need to manually add the system-metadata and/or system-logos remotes to be able to pull to these subtrees. That means you'll need to run the following commands on a freshly cloned theme repository:
+Note that the remotes are only setup for your local repository, so if you clone a theme you'll need to manually add the repository remotes to be able to pull from these subtrees. That means you'll need to run one or more of the following commands on a freshly cloned theme repository:
```
git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git
+git remote add system-controllers-outline https://gitlab.com/es-de/themes/system-controllers-outline.git
+git remote add system-graphics-mini https://gitlab.com/es-de/themes/system-graphics-mini.git
git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git
```
After doing this you'll be able to pull repository updates as described above.
@@ -609,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.
@@ -834,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.
@@ -1285,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.
@@ -1297,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
@@ -1870,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`
@@ -2031,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`
@@ -2601,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`
@@ -2882,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
@@ -2944,7 +3090,7 @@ Properties:
#### helpsystem
-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.
+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.
diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md
index 4c40abd59..18a62fe3f 100644
--- a/USERGUIDE-DEV.md
+++ b/USERGUIDE-DEV.md
@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) v2.2 (development version) - User guide
+# ES-DE (EmulationStation Desktop Edition) v3.0 (development version) - User guide
This version of the user guide is only relevant for the current ES-DE development version, if you are using the latest stable release, refer to [USERGUIDE.md](USERGUIDE.md) instead.
@@ -38,12 +38,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:
@@ -59,11 +59,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.
@@ -71,7 +71,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
@@ -113,18 +113,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.
_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.
@@ -145,7 +145,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**
@@ -166,7 +166,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
@@ -191,7 +191,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.
@@ -233,7 +233,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.
@@ -254,6 +254,8 @@ 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 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
As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. But emulator support is steadily improving and native ARM releases ("Apple Silicon") are also getting more common. One issue though is that some emulators are not codesigned and notarized so macOS refuses to run them by default. You can override the operating system's security settings however, which will work around this problem. Some emulators are also available via the [Homebrew](https://brew.sh) package manager and in many instances ES-DE includes support for these releases using the bundled configuration.
@@ -268,13 +270,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 +288,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 +312,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 +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:
-
-```
-~/.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-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:
```
@@ -351,11 +342,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-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.
-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 +361,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 +384,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-DEV.md](INSTALL-DEV.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-DEV.md](INSTALL-DEV.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 +398,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 +426,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 +484,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 +537,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 +553,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 +581,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 +682,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 +729,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 +811,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 +923,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 +948,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 +969,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 +1100,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-DEV.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-DEV.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 +1279,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-DEV.md#running-windows-emulators-on-linux-using-wine-or-proton) section.
@@ -1473,9 +1478,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-DEV.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-DEV.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 +1734,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 +1762,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 +1777,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 +2141,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 +2228,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-DEV.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 +2249,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 +2275,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 +2283,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 +2299,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 +2380,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 +2419,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-DEV.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-DEV.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 +2449,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 +2473,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 +2573,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-DEV.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-DEV.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 +2587,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-DEV.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-DEV.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 +2620,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
@@ -2620,6 +2654,76 @@ https://docs.mamedev.org/usingmame/defaultkeys.html
Scraping can also be a bit challenging as MAME software list names are used and neither ScreenScraper nor TheGamesDB can parse these names. So it's recommended to run the scraper in interactive mode and refine the searches for all games that are not properly identified.
+### Visual Pinball
+
+The pinball simulator Visual Pinball can be a bit tricky to setup as it supports a wide range of tables. Some of these require [PinMAME](https://github.com/vpinball/pinmame) and some don't. Some simulated tables are older electromechnical design and some are of more modern solid state designs. Some are recreations of real physical games and some are purely virtual and don't exist in physical form. In many cases there is not a definitive release for a table and you may need to assemble various files to get to a fully working game.
+
+As pinball games is a complex topic it will only be covered briefly here, refer to the official Visual Pinball [documentation](https://github.com/vpinball/vpinball/blob/standalone/standalone/README.md) for more details.
+
+The Windows release of Visual Pinball can be downloaded here (make sure to get the GL version):\
+https://github.com/vpinball/vpinball/releases
+
+Apart from this the Windows-specific setup is not covered in this document, but you should be able to find a lot of resources online on this topic.
+
+The Linux and macOS releases need to be downloaded from the GitHub Actions page for the time being:\
+https://github.com/vpinball/vpinball/actions
+
+On Linux simply unpack the archive into `~/Applications/VPinballX` and make sure to give the binary executable permissions:
+```
+cd ~/Applications/VPinballX
+chmod +x VPinballX_GL
+```
+
+On macOS there is a DMG package that you simply install.
+
+Once you've installed Visual Pinball start it once outside ES-DE and its .ini configuration file will be created. On Linux and macOS this is `~/.vpinball/VPinballX.ini`
+
+Set the following entries in this file:
+```
+VPRegPath = ./
+PinMAMEPath = ./
+PinMAMEIniPath = ./
+```
+
+If you don't do this the table may still start but won't work properly and you'll not be able to actually start a game.
+
+ES-DE launches .vpx and .vpt files for the vpinball system, but most tables come shipped with multiple additional files that are needed for the table to work, for example:
+```
+~/ROMs/vpinball/fh/pinmame/
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.directb2s
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.ini
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.vbs
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx
+```
+
+Assembling the necessary files to run a table is beyond the scope of this guide but there are various resources available online for this.
+
+This specific table requires PinMAME to run, and the _fh_ directory name is an example of the abbreviations commonly used in the pinball community. You can for instance find these names in the [Internet Pinball Database](https://www.ipdb.org/) where they are referred to as _Common Abbreviations_.
+
+If you don't need to retain these abbreviations then you can simply setup your games using the _directories interpreted as files_ functionality:
+```
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/pinmame/
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/Funhouse (Williams 1990)_Bigus(MOD)1.6.directb2s
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/Funhouse (Williams 1990)_Bigus(MOD)1.6.ini
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/Funhouse (Williams 1990)_Bigus(MOD)1.6.vbs
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx
+```
+
+If you however insist on retaining the abbreviations then you could use folder links to launch the .vpx or .vpt file inside the fh directory by editing the folder in the metadata editor and selecting the game file via the _Folder link_ entry.
+
+A final option would be to use the _folder flattening_ functionality, although this has many negative side effects that you need to be aware of. If going for this approach make sure to thoroughly read the [Folder flattening](USERGUIDE-DEV.md#folder-flattening) section of this document.
+
+```
+~/ROMs/vpinball/fh/pinmame/
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.directb2s
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.ini
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.vbs
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx
+~/ROMs/vpinball/flatten.txt
+```
+
+With folder flattening in place the .vpx and .vpt files will show up as file entries directly in the root of the gamelist.
+
## Scraping
Scraping means downloading metadata and game media files (images and videos) for the games in your collection.
@@ -2689,33 +2793,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-DEV.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:
@@ -2746,8 +2850,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:
@@ -2758,15 +2862,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.
@@ -2977,10 +3081,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.
@@ -3041,6 +3141,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.
@@ -3059,7 +3163,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**
@@ -3119,7 +3223,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**
@@ -3215,7 +3319,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
@@ -3285,13 +3389,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-DEV.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**
@@ -3350,13 +3474,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.
@@ -3388,7 +3512,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).
@@ -3402,7 +3526,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**
@@ -3420,7 +3544,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.
@@ -3436,7 +3560,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.
@@ -3456,21 +3580,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.
@@ -3772,9 +3896,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:
@@ -3790,7 +3914,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.
@@ -3810,9 +3934,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.
@@ -3838,7 +3962,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)**
@@ -3849,190 +3973,190 @@ 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 |
| videopac | Philips Videopac G7000 | O2EM | MAME - Current, MAME **(Standalone)** | Yes | Single archive or ROM file | |
| virtualboy | Nintendo Virtual Boy | Beetle VB | Mednafen **(Standalone)** | No | |
-| vpinball | Visual Pinball | Visual Pinball **(Standalone)** [UW] | | No | In separate folder interpreted as a file |
+| 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/USERGUIDE.md b/USERGUIDE.md
index 983e45050..deb4a9e09 100644
--- a/USERGUIDE.md
+++ b/USERGUIDE.md
@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) 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.
_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,6 +252,8 @@ 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 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
As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. But emulator support is steadily improving and native ARM releases ("Apple Silicon") are also getting more common. One issue though is that some emulators are not codesigned and notarized so macOS refuses to run them by default. You can override the operating system's security settings however, which will work around this problem. Some emulators are also available via the [Homebrew](https://brew.sh) package manager and in many instances ES-DE includes support for these releases using the bundled configuration.
@@ -266,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.
@@ -286,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.
@@ -306,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.
@@ -318,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:
```
@@ -349,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.
@@ -363,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.
@@ -386,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.
@@ -400,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
@@ -428,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)
@@ -486,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)_
@@ -537,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.
@@ -553,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
@@ -581,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.
@@ -682,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 |
@@ -728,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.
@@ -810,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.
@@ -916,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
@@ -941,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
@@ -962,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.
@@ -1093,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.
@@ -1219,7 +1224,7 @@ The EMULATOR.INI file is found in the _Model 2 Emulator_ installation directory.
Note that Model 2 Emulator is a bit broken and on Windows most GPU drivers it will only work correctly if ES-DE keeps running in the background while the game is launched. However, for some GPU drivers the opposite is true and the emulator will only work if ES-DE is suspended. To use the latter setup, switch to the alternative emulator entry _Model 2 Emulator [Suspend ES-DE] (Standalone)_.
-To run Model 2 Emulator on Linux you need Wine or Proton, how to setup this is covered in the [Running Windows emulators on Linux using Wine or Proton](USERGUIDE-DEV.md#running-windows-emulators-on-linux-using-wine-or-proton) section.
+To run Model 2 Emulator on Linux you need Wine or Proton, how to setup this 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.
After Wine or Proton has been installed, unpack the emulator files into the `~/Applications/m2emulator/` directory.
@@ -1272,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.
@@ -1471,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.
@@ -1727,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/"
```
@@ -1755,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
@@ -1768,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**
@@ -2132,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.
@@ -2208,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:
@@ -2227,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._
@@ -2252,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:
```
@@ -2260,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
@@ -2276,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:
```
@@ -2357,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:
```
@@ -2396,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.
@@ -2426,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:
@@ -2450,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.
@@ -2537,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.
@@ -2551,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`.
@@ -2584,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
@@ -2618,6 +2652,76 @@ https://docs.mamedev.org/usingmame/defaultkeys.html
Scraping can also be a bit challenging as MAME software list names are used and neither ScreenScraper nor TheGamesDB can parse these names. So it's recommended to run the scraper in interactive mode and refine the searches for all games that are not properly identified.
+### Visual Pinball
+
+The pinball simulator Visual Pinball can be a bit tricky to setup as it supports a wide range of tables. Some of these require [PinMAME](https://github.com/vpinball/pinmame) and some don't. Some simulated tables are older electromechnical design and some are of more modern solid state designs. Some are recreations of real physical games and some are purely virtual and don't exist in physical form. In many cases there is not a definitive release for a table and you may need to assemble various files to get to a fully working game.
+
+As pinball games is a complex topic it will only be covered briefly here, refer to the official Visual Pinball [documentation](https://github.com/vpinball/vpinball/blob/standalone/standalone/README.md) for more details.
+
+The Windows release of Visual Pinball can be downloaded here (make sure to get the GL version):\
+https://github.com/vpinball/vpinball/releases
+
+Apart from this the Windows-specific setup is not covered in this document, but you should be able to find a lot of resources online on this topic.
+
+The Linux and macOS releases need to be downloaded from the GitHub Actions page for the time being:\
+https://github.com/vpinball/vpinball/actions
+
+On Linux simply unpack the archive into `~/Applications/VPinballX` and make sure to give the binary executable permissions:
+```
+cd ~/Applications/VPinballX
+chmod +x VPinballX_GL
+```
+
+On macOS there is a DMG package that you simply install.
+
+Once you've installed Visual Pinball start it once outside ES-DE and its .ini configuration file will be created. On Linux and macOS this is `~/.vpinball/VPinballX.ini`
+
+Set the following entries in this file:
+```
+VPRegPath = ./
+PinMAMEPath = ./
+PinMAMEIniPath = ./
+```
+
+If you don't do this the table may still start but won't work properly and you'll not be able to actually start a game.
+
+ES-DE launches .vpx and .vpt files for the vpinball system, but most tables come shipped with multiple additional files that are needed for the table to work, for example:
+```
+~/ROMs/vpinball/fh/pinmame/
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.directb2s
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.ini
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.vbs
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx
+```
+
+Assembling the necessary files to run a table is beyond the scope of this guide but there are various resources available online for this.
+
+This specific table requires PinMAME to run, and the _fh_ directory name is an example of the abbreviations commonly used in the pinball community. You can for instance find these names in the [Internet Pinball Database](https://www.ipdb.org/) where they are referred to as _Common Abbreviations_.
+
+If you don't need to retain these abbreviations then you can simply setup your games using the _directories interpreted as files_ functionality:
+```
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/pinmame/
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/Funhouse (Williams 1990)_Bigus(MOD)1.6.directb2s
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/Funhouse (Williams 1990)_Bigus(MOD)1.6.ini
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/Funhouse (Williams 1990)_Bigus(MOD)1.6.vbs
+~/ROMs/vpinball/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx
+```
+
+If you however insist on retaining the abbreviations then you could use folder links to launch the .vpx or .vpt file inside the fh directory by editing the folder in the metadata editor and selecting the game file via the _Folder link_ entry.
+
+A final option would be to use the _folder flattening_ functionality, although this has many negative side effects that you need to be aware of. If going for this approach make sure to thoroughly read the [Folder flattening](USERGUIDE.md#folder-flattening) section of this document.
+
+```
+~/ROMs/vpinball/fh/pinmame/
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.directb2s
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.ini
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.vbs
+~/ROMs/vpinball/fh/Funhouse (Williams 1990)_Bigus(MOD)1.6.vpx
+~/ROMs/vpinball/flatten.txt
+```
+
+With folder flattening in place the .vpx and .vpt files will show up as file entries directly in the root of the gamelist.
+
## Scraping
Scraping means downloading metadata and game media files (images and videos) for the games in your collection.
@@ -2687,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:
@@ -2744,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:
@@ -2756,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.
@@ -2975,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.
@@ -3039,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.
@@ -3057,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**
@@ -3117,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**
@@ -3213,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
@@ -3283,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**
@@ -3348,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.
@@ -3386,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).
@@ -3400,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**
@@ -3418,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.
@@ -3434,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.
@@ -3454,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.
@@ -3770,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:
@@ -3788,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.
@@ -3808,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.
@@ -3836,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)**
@@ -3847,190 +3971,190 @@ 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 |
| videopac | Philips Videopac G7000 | O2EM | MAME - Current, MAME **(Standalone)** | Yes | Single archive or ROM file | |
| virtualboy | Nintendo Virtual Boy | Beetle VB | Mednafen **(Standalone)** | No | |
-| vpinball | Visual Pinball | Visual Pinball **(Standalone)** [UW] | | No | In separate folder interpreted as a file |
+| 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/CMakeLists.txt b/es-app/CMakeLists.txt
index 99bdfd5ff..13373765c 100644
--- a/es-app/CMakeLists.txt
+++ b/es-app/CMakeLists.txt
@@ -1,18 +1,18 @@
# SPDX-License-Identifier: MIT
#
-# EmulationStation Desktop Edition
+# ES-DE
# CMakeLists.txt (es-app)
#
# CMake configuration for es-app
# Also contains the application packaging configuration.
#
-project(emulationstation-de)
+project(es-de)
set(ES_HEADERS
${CMAKE_CURRENT_SOURCE_DIR}/src/ApplicationUpdater.h
+ ${CMAKE_CURRENT_SOURCE_DIR}/src/ApplicationVersion.h
${CMAKE_CURRENT_SOURCE_DIR}/src/CollectionSystemsManager.h
- ${CMAKE_CURRENT_SOURCE_DIR}/src/EmulationStation.h
${CMAKE_CURRENT_SOURCE_DIR}/src/FileData.h
${CMAKE_CURRENT_SOURCE_DIR}/src/FileFilterIndex.h
${CMAKE_CURRENT_SOURCE_DIR}/src/FileSorts.h
@@ -112,7 +112,7 @@ set(ES_SOURCES
)
if(WIN32)
- LIST(APPEND ES_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation.rc)
+ LIST(APPEND ES_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE.rc)
endif()
#---------------------------------------------------------------------------------------------------
@@ -121,149 +121,79 @@ endif()
# Define target.
if(APPLE)
include_directories(${COMMON_INCLUDE_DIRS} ${CMAKE_CURRENT_SOURCE_DIR}/src)
- add_executable(EmulationStation ${ES_SOURCES} ${ES_HEADERS})
- target_link_libraries(EmulationStation ${COMMON_LIBRARIES} es-core)
- set_target_properties(EmulationStation PROPERTIES INSTALL_RPATH_USE_LINK_PATH TRUE)
+ add_executable(ES-DE ${ES_SOURCES} ${ES_HEADERS})
+ target_link_libraries(ES-DE ${COMMON_LIBRARIES} es-core)
+ set_target_properties(ES-DE PROPERTIES INSTALL_RPATH_USE_LINK_PATH TRUE)
if(CMAKE_CXX_COMPILER_VERSION GREATER_EQUAL 15.0.0)
- target_link_options(EmulationStation PRIVATE LINKER:-no_warn_duplicate_libraries)
+ target_link_options(ES-DE PRIVATE LINKER:-no_warn_duplicate_libraries)
endif()
elseif(WIN32)
include_directories(${COMMON_INCLUDE_DIRS} ${CMAKE_CURRENT_SOURCE_DIR}/src)
- add_executable(EmulationStation WIN32 ${ES_SOURCES} ${ES_HEADERS})
- target_link_libraries(EmulationStation ${COMMON_LIBRARIES} es-core)
- set_target_properties(EmulationStation PROPERTIES INSTALL_RPATH_USE_LINK_PATH TRUE)
+ add_executable(ES-DE WIN32 ${ES_SOURCES} ${ES_HEADERS})
+ target_link_libraries(ES-DE ${COMMON_LIBRARIES} es-core)
+ set_target_properties(ES-DE PROPERTIES INSTALL_RPATH_USE_LINK_PATH TRUE)
+elseif(ANDROID)
+ include_directories(${COMMON_INCLUDE_DIRS} ${CMAKE_CURRENT_SOURCE_DIR}/src)
+ add_library(main MODULE ${ES_SOURCES} ${ES_HEADERS})
+ target_link_libraries(main PRIVATE ${COMMON_LIBRARIES} ${CMAKE_DL_LIBS} es-core es-pdf-convert)
else()
include_directories(${COMMON_INCLUDE_DIRS} ${CMAKE_CURRENT_SOURCE_DIR}/src)
- add_executable(emulationstation ${ES_SOURCES} ${ES_HEADERS})
- target_link_libraries(emulationstation ${COMMON_LIBRARIES} ${CMAKE_DL_LIBS} es-core)
- set_target_properties(emulationstation PROPERTIES INSTALL_RPATH_USE_LINK_PATH TRUE)
+ add_executable(es-de ${ES_SOURCES} ${ES_HEADERS})
+ target_link_libraries(es-de ${COMMON_LIBRARIES} ${CMAKE_DL_LIBS} es-core)
+ set_target_properties(es-de PROPERTIES INSTALL_RPATH_USE_LINK_PATH TRUE)
endif()
# Setup for installation and package generation.
if(WIN32)
- install(TARGETS EmulationStation RUNTIME DESTINATION .)
+ install(TARGETS ES-DE RUNTIME DESTINATION .)
install(TARGETS es-pdf-convert RUNTIME DESTINATION es-pdf-converter)
- if(CMAKE_CXX_COMPILER_ID MATCHES MSVC)
- set(CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION .)
- if(CMAKE_BUILD_TYPE MATCHES Debug)
- set(CMAKE_INSTALL_DEBUG_LIBRARIES TRUE)
- endif()
- install(FILES ../avcodec-60.dll
- ../avfilter-9.dll
- ../avformat-60.dll
- ../avutil-58.dll
- ../postproc-57.dll
- ../swresample-4.dll
- ../swscale-7.dll
- ../FreeImage.dll
- ../freetype.dll
- ../git2.dll
- ../glew32.dll
- ../libcrypto-1_1-x64.dll
- ../libcurl-x64.dll
- ../libssl-1_1-x64.dll
- ../lunasvg.dll
- ../pugixml.dll
- ../rlottie.dll
- ../SDL2.dll
- ../vcomp140.dll
- DESTINATION .)
- install(FILES ../es-pdf-converter/charset.dll
- ../es-pdf-converter/deflate.dll
- ../es-pdf-converter/freetype.dll
- ../es-pdf-converter/iconv.dll
- ../es-pdf-converter/jpeg8.dll
- ../es-pdf-converter/lcms2.dll
- ../es-pdf-converter/Lerc.dll
- ../es-pdf-converter/libcrypto-3-x64.dll
- ../es-pdf-converter/libcurl.dll
- ../es-pdf-converter/liblzma.dll
- ../es-pdf-converter/libpng16.dll
- ../es-pdf-converter/libssh2.dll
- ../es-pdf-converter/openjp2.dll
- ../es-pdf-converter/poppler.dll
- ../es-pdf-converter/poppler-cpp.dll
- ../es-pdf-converter/tiff.dll
- ../es-pdf-converter/zlib.dll
- ../es-pdf-converter/zstd.dll
- DESTINATION es-pdf-converter)
- else()
- install(FILES ../avcodec-60.dll
- ../avfilter-9.dll
- ../avformat-60.dll
- ../avutil-58.dll
- ../postproc-57.dll
- ../swresample-4.dll
- ../swscale-7.dll
- ../FreeImage.dll
- ../glew32.dll
- ../libcrypto-1_1-x64.dll
- ../libcurl-x64.dll
- ../libfreetype.dll
- ../libgit2.dll
- ../liblunasvg.dll
- ../libpugixml.dll
- ../librlottie.dll
- ../libssl-1_1-x64.dll
- ../SDL2.dll
- ../vcomp140.dll
- DESTINATION .)
- install(FILES ../es-pdf-converter/libbrotlicommon.dll
- ../es-pdf-converter/libbrotlidec.dll
- ../es-pdf-converter/libbz2-1.dll
- ../es-pdf-converter/libcairo-2.dll
- ../es-pdf-converter/libcrypto-3-x64.dll
- ../es-pdf-converter/libcurl-4.dll
- ../es-pdf-converter/libdeflate.dll
- ../es-pdf-converter/libexpat-1.dll
- ../es-pdf-converter/libffi-8.dll
- ../es-pdf-converter/libfontconfig-1.dll
- ../es-pdf-converter/libfreetype-6.dll
- ../es-pdf-converter/libgcc_s_seh-1.dll
- ../es-pdf-converter/libgio-2.0-0.dll
- ../es-pdf-converter/libglib-2.0-0.dll
- ../es-pdf-converter/libgmodule-2.0-0.dll
- ../es-pdf-converter/libgobject-2.0-0.dll
- ../es-pdf-converter/libgraphite2.dll
- ../es-pdf-converter/libharfbuzz-0.dll
- ../es-pdf-converter/libiconv-2.dll
- ../es-pdf-converter/libidn2-0.dll
- ../es-pdf-converter/libintl-8.dll
- ../es-pdf-converter/libjbig-0.dll
- ../es-pdf-converter/libjpeg-8.dll
- ../es-pdf-converter/liblcms2-2.dll
- ../es-pdf-converter/libLerc.dll
- ../es-pdf-converter/liblzma-5.dll
- ../es-pdf-converter/libnghttp2-14.dll
- ../es-pdf-converter/libnspr4.dll
- ../es-pdf-converter/libopenjp2-7.dll
- ../es-pdf-converter/libpcre2-8-0.dll
- ../es-pdf-converter/libpixman-1-0.dll
- ../es-pdf-converter/libplc4.dll
- ../es-pdf-converter/libplds4.dll
- ../es-pdf-converter/libpng16-16.dll
- ../es-pdf-converter/libpoppler-129.dll
- ../es-pdf-converter/libpoppler-cpp-0.dll
- ../es-pdf-converter/libpoppler-glib-8.dll
- ../es-pdf-converter/libpsl-5.dll
- ../es-pdf-converter/libsharpyuv-0.dll
- ../es-pdf-converter/libssh2-1.dll
- ../es-pdf-converter/libssl-3-x64.dll
- ../es-pdf-converter/libstdc++-6.dll
- ../es-pdf-converter/libtiff-6.dll
- ../es-pdf-converter/libunistring-5.dll
- ../es-pdf-converter/libwebp-7.dll
- ../es-pdf-converter/libwinpthread-1.dll
- ../es-pdf-converter/libzstd.dll
- ../es-pdf-converter/nss3.dll
- ../es-pdf-converter/nssutil3.dll
- ../es-pdf-converter/smime3.dll
- ../es-pdf-converter/zlib1.dll
- DESTINATION es-pdf-converter)
+ set(CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION .)
+ if(CMAKE_BUILD_TYPE MATCHES Debug)
+ set(CMAKE_INSTALL_DEBUG_LIBRARIES TRUE)
endif()
+ install(FILES ../avcodec-60.dll
+ ../avfilter-9.dll
+ ../avformat-60.dll
+ ../avutil-58.dll
+ ../postproc-57.dll
+ ../swresample-4.dll
+ ../swscale-7.dll
+ ../FreeImage.dll
+ ../freetype.dll
+ ../git2.dll
+ ../glew32.dll
+ ../libcrypto-1_1-x64.dll
+ ../libcurl-x64.dll
+ ../libssl-1_1-x64.dll
+ ../lunasvg.dll
+ ../pugixml.dll
+ ../rlottie.dll
+ ../SDL2.dll
+ ../vcomp140.dll
+ DESTINATION .)
+ install(FILES ../es-pdf-converter/charset.dll
+ ../es-pdf-converter/deflate.dll
+ ../es-pdf-converter/freetype.dll
+ ../es-pdf-converter/iconv.dll
+ ../es-pdf-converter/jpeg8.dll
+ ../es-pdf-converter/lcms2.dll
+ ../es-pdf-converter/Lerc.dll
+ ../es-pdf-converter/libcrypto-3-x64.dll
+ ../es-pdf-converter/libcurl.dll
+ ../es-pdf-converter/liblzma.dll
+ ../es-pdf-converter/libpng16.dll
+ ../es-pdf-converter/libssh2.dll
+ ../es-pdf-converter/openjp2.dll
+ ../es-pdf-converter/poppler.dll
+ ../es-pdf-converter/poppler-cpp.dll
+ ../es-pdf-converter/tiff.dll
+ ../es-pdf-converter/zlib.dll
+ ../es-pdf-converter/zstd.dll
+ DESTINATION es-pdf-converter)
install(FILES ../LICENSE DESTINATION .)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/licenses DESTINATION .)
+ install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/linear-es-de DESTINATION themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/modern-es-de DESTINATION themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/slate-es-de DESTINATION themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/resources DESTINATION .)
@@ -274,10 +204,10 @@ elseif(APPLE)
# So an extra 'Resources' directory was added to the CMAKE_INSTALL_PREFIX variable as well
# to compensate for this. It's a bad solution to the problem and there must surely be a
# better way to fix this.
- install(TARGETS EmulationStation RUNTIME DESTINATION ../MacOS)
+ install(TARGETS ES-DE RUNTIME DESTINATION ../MacOS)
install(TARGETS es-pdf-convert RUNTIME DESTINATION ../MacOS)
- install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation-DE.icns DESTINATION ../Resources)
- install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation-DE_Info.plist DESTINATION .. RENAME Info.plist)
+ install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE.icns DESTINATION ../Resources)
+ install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE_Info.plist DESTINATION .. RENAME Info.plist)
set(APPLE_DYLIB_PERMISSIONS OWNER_WRITE OWNER_READ OWNER_EXECUTE
GROUP_READ GROUP_EXECUTE
@@ -322,37 +252,40 @@ elseif(APPLE)
install(FILES ${CMAKE_SOURCE_DIR}/LICENSE DESTINATION ../Resources)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/resources DESTINATION ../Resources)
+ install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/linear-es-de DESTINATION ../Resources/themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/modern-es-de DESTINATION ../Resources/themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/slate-es-de DESTINATION ../Resources/themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/licenses DESTINATION ../Resources)
-else()
- install(TARGETS emulationstation RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX}/bin)
+elseif(NOT ANDROID)
+ install(TARGETS es-de RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX}/bin)
install(TARGETS es-pdf-convert RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX}/bin)
if(CMAKE_SYSTEM_NAME MATCHES Linux)
- install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/emulationstation.6.gz
+ install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/es-de.6.gz
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man6)
else()
- install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/emulationstation.6.gz
+ install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/es-de.6.gz
DESTINATION ${CMAKE_INSTALL_PREFIX}/man/man6)
endif()
install(FILES ${CMAKE_SOURCE_DIR}/LICENSE
- DESTINATION ${CMAKE_INSTALL_PREFIX}/share/emulationstation)
- install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/org.es_de.emulationstation-de.desktop
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/share/es-de)
+ install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/org.es_de.frontend.desktop
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/applications)
- install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/org.es_de.emulationstation-de.svg
+ install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/org.es_de.frontend.svg
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/pixmaps)
- install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/org.es_de.emulationstation-de.svg
+ install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/org.es_de.frontend.svg
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/icons/hicolor/scalable/apps)
- install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/org.es_de.emulationstation-de.appdata.xml
+ install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/assets/org.es_de.frontend.appdata.xml
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/metainfo)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/licenses
- DESTINATION ${CMAKE_INSTALL_PREFIX}/share/emulationstation)
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/share/es-de)
+ install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/linear-es-de
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/share/es-de/themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/modern-es-de
- DESTINATION ${CMAKE_INSTALL_PREFIX}/share/emulationstation/themes)
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/share/es-de/themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/themes/slate-es-de
- DESTINATION ${CMAKE_INSTALL_PREFIX}/share/emulationstation/themes)
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/share/es-de/themes)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/resources
- DESTINATION ${CMAKE_INSTALL_PREFIX}/share/emulationstation)
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/share/es-de)
endif()
include(InstallRequiredSystemLibraries)
@@ -360,17 +293,17 @@ include(InstallRequiredSystemLibraries)
#---------------------------------------------------------------------------------------------------
# General CPack settings.
-set(CPACK_PACKAGE_NAME emulationstation-de)
+set(CPACK_PACKAGE_NAME es-de)
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "Emulator frontend")
-set(CPACK_PACKAGE_DESCRIPTION "EmulationStation Desktop Edition (ES-DE) is a frontend for browsing and launching games from your multi-platform game collection.")
+set(CPACK_PACKAGE_DESCRIPTION "ES-DE (EmulationStation Desktop Edition) is a frontend for browsing and launching games from your multi-platform game collection.")
set(CPACK_PACKAGE_VERSION ${ES_VERSION})
if(APPLE)
# Shorter line length license file to be able to fit inside the drag-and-drop installer window without introducing extra line breaks.
- set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation-DE_LICENSE_macOS)
+ set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE_LICENSE_macOS)
elseif(WIN32)
# The installer window looks a bit different on Windows so a specific file for this OS is required.
- set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation-DE_LICENSE_Windows)
+ set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE_LICENSE_Windows)
else()
set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_SOURCE_DIR}/LICENSE)
endif()
@@ -386,40 +319,40 @@ endif()
# Settings per operating system and generator type.
if(APPLE)
set(CPACK_GENERATOR Bundle)
- set(CPACK_PACKAGE_FILE_NAME EmulationStation-DE-${CPACK_PACKAGE_VERSION}-${CPU_ARCHITECTURE})
- set(CPACK_DMG_VOLUME_NAME "EmulationStation Desktop Edition ${CPACK_PACKAGE_VERSION}")
- set(CPACK_PACKAGE_ICON ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation-DE.icns)
- set(CPACK_DMG_DS_STORE ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation-DE_DS_Store)
- set(CPACK_BUNDLE_NAME "EmulationStation Desktop Edition")
- set(CPACK_BUNDLE_ICON ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation-DE.icns)
- set(CPACK_BUNDLE_PLIST ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation-DE_Info.plist)
+ set(CPACK_PACKAGE_FILE_NAME ES-DE_${CPACK_PACKAGE_VERSION}-${CPU_ARCHITECTURE})
+ set(CPACK_DMG_VOLUME_NAME "ES-DE ${CPACK_PACKAGE_VERSION}")
+ set(CPACK_PACKAGE_ICON ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE.icns)
+ set(CPACK_DMG_DS_STORE ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE_DS_Store)
+ set(CPACK_BUNDLE_NAME "ES-DE")
+ set(CPACK_BUNDLE_ICON ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE.icns)
+ set(CPACK_BUNDLE_PLIST ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE_Info.plist)
if(MACOS_CODESIGN_IDENTITY)
set(CPACK_BUNDLE_APPLE_CERT_APP "Developer ID Application: ${MACOS_CODESIGN_IDENTITY}")
set(CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER "--deep --force --options runtime")
endif()
elseif(WIN32)
set(CPACK_GENERATOR NSIS)
- set(CPACK_PACKAGE_FILE_NAME EmulationStation-DE-${CPACK_PACKAGE_VERSION}-${CPU_ARCHITECTURE})
- set(CPACK_PACKAGE_INSTALL_DIRECTORY EmulationStation-DE)
- set(CPACK_PACKAGE_EXECUTABLES EmulationStation EmulationStation)
+ set(CPACK_PACKAGE_FILE_NAME ES-DE_${CPACK_PACKAGE_VERSION}-${CPU_ARCHITECTURE})
+ set(CPACK_PACKAGE_INSTALL_DIRECTORY ES-DE)
+ set(CPACK_PACKAGE_EXECUTABLES ES-DE ES-DE)
set(CPACK_NSIS_INSTALL_ROOT ${PROGRAMFILES64})
set(CPACK_NSIS_EXECUTABLES_DIRECTORY .)
- set(CPACK_NSIS_MUI_ICON ${CMAKE_CURRENT_SOURCE_DIR}/assets/EmulationStation.ico)
+ set(CPACK_NSIS_MUI_ICON ${CMAKE_CURRENT_SOURCE_DIR}/assets/ES-DE.ico)
set(CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL ON)
- set(CPACK_NSIS_DISPLAY_NAME "EmulationStation Desktop Edition ${CPACK_PACKAGE_VERSION}")
- set(CPACK_NSIS_PACKAGE_NAME "EmulationStation Desktop Edition")
- set(CPACK_NSIS_INSTALLED_ICON_NAME EmulationStation.exe)
- set(CPACK_NSIS_WELCOME_TITLE "EmulationStation Desktop Edition Installer")
- set(CPACK_NSIS_FINISH_TITLE "EmulationStation Desktop Edition Installation Completed")
+ set(CPACK_NSIS_DISPLAY_NAME "ES-DE ${CPACK_PACKAGE_VERSION}")
+ set(CPACK_NSIS_PACKAGE_NAME "ES-DE")
+ set(CPACK_NSIS_INSTALLED_ICON_NAME ES-DE.exe)
+ set(CPACK_NSIS_WELCOME_TITLE "ES-DE Installer")
+ set(CPACK_NSIS_FINISH_TITLE "ES-DE Installation Completed")
set(CPACK_NSIS_MANIFEST_DPI_AWARE ON)
- set(CPACK_NSIS_MENU_LINKS "https://es-de.org" "ES-DE Website" "https://es-de.org" "Please Donate")
+ set(CPACK_NSIS_MENU_LINKS "https://es-de.org" "ES-DE Website")
else()
- set(CPACK_PACKAGE_INSTALL_DIRECTORY emulationstation_${CMAKE_PACKAGE_VERSION})
- set(CPACK_PACKAGE_EXECUTABLES emulationstation emulationstation)
+ set(CPACK_PACKAGE_INSTALL_DIRECTORY es-de_${CMAKE_PACKAGE_VERSION})
+ set(CPACK_PACKAGE_EXECUTABLES es-de es-de)
if(LINUX_CPACK_GENERATOR MATCHES DEB)
set(CPACK_GENERATOR DEB)
endif()
- set(CPACK_DEBIAN_FILE_NAME emulationstation-de-${CPACK_PACKAGE_VERSION}-${CPU_ARCHITECTURE}.deb)
+ set(CPACK_DEBIAN_FILE_NAME es-de_${CPACK_PACKAGE_VERSION}-${CPU_ARCHITECTURE}.deb)
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Leon Styhre ")
set(CPACK_DEBIAN_PACKAGE_HOMEPAGE https://es-de.org)
set(CPACK_DEBIAN_PACKAGE_SECTION games)
@@ -428,7 +361,7 @@ else()
if(LINUX_CPACK_GENERATOR MATCHES RPM)
set(CPACK_GENERATOR RPM)
endif()
- set(CPACK_RPM_FILE_NAME emulationstation-de-${CPACK_PACKAGE_VERSION}-${CPU_ARCHITECTURE}.rpm)
+ set(CPACK_RPM_FILE_NAME es-de_${CPACK_PACKAGE_VERSION}-${CPU_ARCHITECTURE}.rpm)
set(CPACK_RPM_PACKAGE_DESCRIPTION ${CPACK_PACKAGE_DESCRIPTION})
set(CPACK_RPM_PACKAGE_LICENSE MIT)
list(APPEND CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION ${CMAKE_INSTALL_PREFIX})
diff --git a/es-app/assets/EmulationStation-DE.icns b/es-app/assets/ES-DE.icns
similarity index 100%
rename from es-app/assets/EmulationStation-DE.icns
rename to es-app/assets/ES-DE.icns
diff --git a/es-app/assets/EmulationStation.ico b/es-app/assets/ES-DE.ico
similarity index 100%
rename from es-app/assets/EmulationStation.ico
rename to es-app/assets/ES-DE.ico
diff --git a/es-app/assets/EmulationStation.rc b/es-app/assets/ES-DE.rc
similarity index 64%
rename from es-app/assets/EmulationStation.rc
rename to es-app/assets/ES-DE.rc
index 1bda4149b..584408efa 100644
--- a/es-app/assets/EmulationStation.rc
+++ b/es-app/assets/ES-DE.rc
@@ -1,4 +1,4 @@
-#include "EmulationStation.h"
+#include "ApplicationVersion.h"
#include "windows.h"
@@ -21,13 +21,13 @@ BEGIN
BEGIN
VALUE "Comments", "\0"
VALUE "CompanyName", "es-de.org\0"
- VALUE "FileDescription", "EmulationStation\0"
+ VALUE "FileDescription", "ES-DE\0"
VALUE "FileVersion", RESOURCE_VERSION_STRING
- VALUE "InternalName", "emulationstation.exe\0"
- VALUE "LegalCopyright", "Copyright (c) 2020-2023 Leon Styhre\0"
+ VALUE "InternalName", "ES-DE.exe\0"
+ VALUE "LegalCopyright", "Copyright (c) 2020-2024 Leon Styhre\0"
VALUE "LegalTrademarks", "\0"
- VALUE "OriginalFilename", "emulationstation.exe\0"
- VALUE "ProductName", "EmulationStation\0"
+ VALUE "OriginalFilename", "ES-DE.exe\0"
+ VALUE "ProductName", "ES-DE\0"
VALUE "ProductVersion", PROGRAM_VERSION_STRING
END
END
@@ -37,4 +37,4 @@ BEGIN
END
END
-IDI_ES_LOGO ICON DISCARDABLE "EmulationStation.ico"
+IDI_ES_LOGO ICON DISCARDABLE "ES-DE.ico"
diff --git a/es-app/assets/EmulationStation-DE_DS_Store b/es-app/assets/ES-DE_DS_Store
similarity index 90%
rename from es-app/assets/EmulationStation-DE_DS_Store
rename to es-app/assets/ES-DE_DS_Store
index c7dd91e90..b449f2df0 100644
Binary files a/es-app/assets/EmulationStation-DE_DS_Store and b/es-app/assets/ES-DE_DS_Store differ
diff --git a/es-app/assets/EmulationStation-DE_Info.plist b/es-app/assets/ES-DE_Info.plist
similarity index 70%
rename from es-app/assets/EmulationStation-DE_Info.plist
rename to es-app/assets/ES-DE_Info.plist
index ffcd40a02..ecba4019d 100644
--- a/es-app/assets/EmulationStation-DE_Info.plist
+++ b/es-app/assets/ES-DE_Info.plist
@@ -3,31 +3,31 @@
CFBundleIdentifier
- org.es-de.EmulationStation
+ 3.0.0CFBundleDevelopmentRegionEnglishCFBundleDisplayName
- EmulationStation Desktop Edition
+ ES-DECFBundleExecutable
- EmulationStation
+ ES-DECFBundleGetInfoString
- EmulationStation Desktop Edition 2.2.1
+ ES-DE 3.0.0CFBundleIconFile
- EmulationStation-DE.icns
+ ES-DE.icnsCFBundleName
- EmulationStation Desktop Edition
+ ES-DECFBundlePackageTypeAPPLCFBundleSignatureESDECFBundleShortVersionString
- 2.2.1
+ 3.0.0-alphaCFBundleVersion
- 2.2.1
+ 3.0.0-alphaCFBundleInfoDictionaryVersion6.0LSApplicationCategoryType
- public.app-category.games
+ public.app-category.educationLSMinimumSystemVersion10.15.0LSUIPresentationMode
@@ -37,9 +37,9 @@
NSPrincipalClassNSApplicationNSMainNibFile
- EmulationStation
+ ES-DENSHumanReadableCopyright
- Copyright (c) 2020-2023 Leon Styhre
+ Copyright (c) 2020-2024 Leon Styhre
Copyright (c) 2014 Alec Lofquist
Licensed under the MIT license
diff --git a/es-app/assets/EmulationStation-DE_LICENSE_Windows b/es-app/assets/ES-DE_LICENSE_Windows
similarity index 96%
rename from es-app/assets/EmulationStation-DE_LICENSE_Windows
rename to es-app/assets/ES-DE_LICENSE_Windows
index 9469ee561..13deba166 100644
--- a/es-app/assets/EmulationStation-DE_LICENSE_Windows
+++ b/es-app/assets/ES-DE_LICENSE_Windows
@@ -1,4 +1,4 @@
-Copyright (c) 2020-2023 Leon Styhre
+Copyright (c) 2020-2024 Leon Styhre
Copyright (c) 2014 Alec Lofquist
Permission is hereby granted, free of charge, to any person obtaining a copy
diff --git a/es-app/assets/EmulationStation-DE_LICENSE_macOS b/es-app/assets/ES-DE_LICENSE_macOS
similarity index 96%
rename from es-app/assets/EmulationStation-DE_LICENSE_macOS
rename to es-app/assets/ES-DE_LICENSE_macOS
index f81c6fbe7..de376f344 100644
--- a/es-app/assets/EmulationStation-DE_LICENSE_macOS
+++ b/es-app/assets/ES-DE_LICENSE_macOS
@@ -1,6 +1,6 @@
-Copyright (c) 2020-2023 Leon Styhre
+Copyright (c) 2020-2024 Leon Styhre
Copyright (c) 2014 Alec Lofquist
-
+
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
@@ -9,10 +9,10 @@ copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom
the Software is furnished to do so, subject to the following
conditions:
-
+
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
-
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
diff --git a/es-app/assets/Windows_Portable_DO_NOT_PLACE_YOUR_THEMES_HERE.txt b/es-app/assets/Windows_Portable_DO_NOT_PLACE_YOUR_THEMES_HERE.txt
index eb79d74e2..b07d916c9 100644
--- a/es-app/assets/Windows_Portable_DO_NOT_PLACE_YOUR_THEMES_HERE.txt
+++ b/es-app/assets/Windows_Portable_DO_NOT_PLACE_YOUR_THEMES_HERE.txt
@@ -1 +1 @@
-Place manually downloaded or modified themes into .emulationstation\themes\ and not into this directory
+Place manually downloaded or modified themes into ES-DE\ES-DE\themes\ and not into this directory
diff --git a/es-app/assets/Windows_Portable_README.txt b/es-app/assets/Windows_Portable_README.txt
index f295a7f0c..55130be90 100644
--- a/es-app/assets/Windows_Portable_README.txt
+++ b/es-app/assets/Windows_Portable_README.txt
@@ -1,11 +1,10 @@
-EmulationStation Desktop Edition (ES-DE) - Portable installation on Windows
+ES-DE (EmulationStation Desktop Edition) - Portable installation on Windows
---------------------------------------------------------------------------
ES-DE release:
-2.2.1
+3.0.0
The latest version can be downloaded from https://es-de.org
-Please also consider donating to the project, links for that can be found on the ES-DE website just mentioned.
Instructions:
@@ -15,18 +14,18 @@ New installation:
1) The ROMs_ALL directory contains all the systems that ES-DE supports, but to decrease application startup time only copy the folders you need to the ROMs directory
2) Place your games into their respective folders in the ROMs directory tree
3) Place your emulators inside the Emulators directory
-4) Start ES-DE using EmulationStation.exe and enjoy some retrogaming!
+4) Start ES-DE using ES-DE.exe and enjoy some retrogaming!
Upgrading from an older release:
-1) Rename your old EmulationStation-DE directory, for example to EmulationStation-DE_OLD
-2) Move your games from EmulationStation-DE_OLD\ROMs\ to EmulationStation-DE\ROMs\
-3) Move your emulators from EmulationStation-DE_OLD\Emulators\ to EmulationStation-DE\Emulators\
-4) Move the contents of EmulationStation-DE_OLD\.emulationstation\ to EmulationStation-DE\.emulationstation\
+1) Rename your old ES-DE directory, for example to ES-DE_OLD
+2) Move your games from ES-DE_OLD\ROMs\ to ES-DE\ROMs\
+3) Move your emulators from ES-DE_OLD\Emulators\ to ES-DE\Emulators\
+4) Move the contents of ES-DE_OLD\ES-DE\ to ES-DE\ES-DE\
This last step includes your settings, custom collections, custom systems, scraped/downloaded media, gamelist.xml files, scripts and themes
5) Update your themes using the theme downloader to get support for all the latest systems and features
-In case of issues, check .emulationstation\es_log.txt for clues as to what went wrong.
-Enabling the "Debug mode" setting in the "Other settings" menu or starting EmulationStation.exe with the --debug flag will provide additional details.
+In case of issues, check ES-DE\es_log.txt for clues as to what went wrong.
+Enabling the "Debug mode" setting in the "Other settings" menu or starting ES-DE.exe with the --debug flag will provide additional details.
Refer to the FAQ and user guide for more detailed instructions and documentation:
https://gitlab.com/es-de/emulationstation-de/-/blob/master/FAQ.md
@@ -128,7 +127,8 @@ Emulators\VICE\xplus4.exe
Emulators\VICE\bin\xplus4.exe
Emulators\VICE\xvic.exe
Emulators\VICE\bin\xvic.exe
-Emulators\Visual Pinball\VPinballX.exe
+Emulators\VPinballX\VPinballX_GL64.exe
+Emulators\VPinballX\VPinballX64.exe
Emulators\Vita3K\Vita3K.exe
Emulators\xemu\xemu.exe
Emulators\xenia\xenia.exe
diff --git a/es-app/assets/emulationstation.6.gz b/es-app/assets/emulationstation.6.gz
deleted file mode 100644
index f86bcabbb..000000000
Binary files a/es-app/assets/emulationstation.6.gz and /dev/null differ
diff --git a/es-app/assets/es-de.6.gz b/es-app/assets/es-de.6.gz
new file mode 100644
index 000000000..d730d5313
Binary files /dev/null and b/es-app/assets/es-de.6.gz differ
diff --git a/es-app/assets/org.es_de.emulationstation-de.appdata.xml b/es-app/assets/org.es_de.frontend.appdata.xml
similarity index 92%
rename from es-app/assets/org.es_de.emulationstation-de.appdata.xml
rename to es-app/assets/org.es_de.frontend.appdata.xml
index e2f20ea64..99e7e381b 100644
--- a/es-app/assets/org.es_de.emulationstation-de.appdata.xml
+++ b/es-app/assets/org.es_de.frontend.appdata.xml
@@ -1,13 +1,13 @@
- org.es_de.emulationstation-de
- EmulationStation Desktop Edition
+ org.es_de.frontend
+ ES-DEEmulator frontend
-
EmulationStation Desktop Edition (ES-DE) is a frontend for browsing and
+
ES-DE (EmulationStation Desktop Edition) is a frontend for browsing and
launching games from your multi-platform game collection.
- org.es_de.emulationstation-de.desktop
+ org.es_de.frontend.desktopGameEmulator
@@ -38,6 +38,9 @@
+
+ https://gitlab.com/es-de/emulationstation-de/-/releases
+ https://gitlab.com/es-de/emulationstation-de/-/releases
diff --git a/es-app/assets/org.es_de.emulationstation-de.desktop b/es-app/assets/org.es_de.frontend.desktop
similarity index 67%
rename from es-app/assets/org.es_de.emulationstation-de.desktop
rename to es-app/assets/org.es_de.frontend.desktop
index 287e61bbb..194ac3f3a 100644
--- a/es-app/assets/org.es_de.emulationstation-de.desktop
+++ b/es-app/assets/org.es_de.frontend.desktop
@@ -1,12 +1,12 @@
[Desktop Entry]
Version=1.0
-Exec=emulationstation
-Icon=org.es_de.emulationstation-de
+Exec=es-de
+Icon=org.es_de.frontend
Terminal=false
Type=Application
StartupNotify=true
Hidden=false
Categories=Game;Emulator;
-Name=EmulationStation Desktop Edition
+Name=ES-DE
GenericName=Emulator Frontend
Keywords=emulator;emulation;front-end;frontend;
diff --git a/es-app/assets/org.es_de.emulationstation-de.svg b/es-app/assets/org.es_de.frontend.svg
similarity index 100%
rename from es-app/assets/org.es_de.emulationstation-de.svg
rename to es-app/assets/org.es_de.frontend.svg
diff --git a/es-app/assets/org.es_de.emulationstation-de.yml b/es-app/assets/org.es_de.frontend.yml
similarity index 92%
rename from es-app/assets/org.es_de.emulationstation-de.yml
rename to es-app/assets/org.es_de.frontend.yml
index 721cab5a0..34cd0c60c 100644
--- a/es-app/assets/org.es_de.emulationstation-de.yml
+++ b/es-app/assets/org.es_de.frontend.yml
@@ -1,16 +1,16 @@
# SPDX-License-Identifier: MIT
#
-# EmulationStation Desktop Edition
-# org.es_de.emulationstation-de.yml
+# ES-DE
+# org.es_de.frontend.yml
#
# Flatpak manifest file for use with flatpak-builder.
#
-app-id: org.es_de.emulationstation-de
+app-id: org.es_de.frontend-de
sdk: org.freedesktop.Sdk
runtime: org.freedesktop.Platform
runtime-version: '21.08'
-command: emulationstation
+command: es-de
finish-args:
- --share=ipc
- --socket=x11
@@ -74,7 +74,7 @@ modules:
url: https://github.com/zeux/pugixml/releases/download/v1.11.4/pugixml-1.11.4.tar.gz
sha256: 8ddf57b65fb860416979a3f0640c2ad45ddddbbafa82508ef0a0af3ce7061716
- - name: emulationstation
+ - name: es-de
buildsystem: cmake-ninja
config-opts:
- -DFLATPAK_BUILD=on
diff --git a/es-app/src/ApplicationUpdater.cpp b/es-app/src/ApplicationUpdater.cpp
index 49e2f77d9..e1f9b20a6 100644
--- a/es-app/src/ApplicationUpdater.cpp
+++ b/es-app/src/ApplicationUpdater.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// ApplicationUpdater.cpp
//
// Checks for application updates.
@@ -9,7 +9,7 @@
#include "ApplicationUpdater.h"
-#include "EmulationStation.h"
+#include "ApplicationVersion.h"
#include "Log.h"
#include "Settings.h"
#include "resources/ResourceManager.h"
@@ -211,8 +211,8 @@ void ApplicationUpdater::parseFile()
#if (LOCAL_TESTING_FILE)
LOG(LogWarning) << "ApplicationUpdater: Using local \"latest_release.json\" testing file";
- const std::string localReleaseFile {Utils::FileSystem::getHomePath() +
- "/.emulationstation/latest_release.json"};
+ const std::string localReleaseFile {Utils::FileSystem::getAppDataDirectory() +
+ "/latest_release.json"};
if (!Utils::FileSystem::exists(localReleaseFile))
throw std::runtime_error("Local testing file not found");
diff --git a/es-app/src/ApplicationUpdater.h b/es-app/src/ApplicationUpdater.h
index 23b1bb48b..17e2ebd8a 100644
--- a/es-app/src/ApplicationUpdater.h
+++ b/es-app/src/ApplicationUpdater.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// ApplicationUpdater.h
//
// Checks for application updates.
diff --git a/es-app/src/ApplicationVersion.h b/es-app/src/ApplicationVersion.h
new file mode 100644
index 000000000..dcb861360
--- /dev/null
+++ b/es-app/src/ApplicationVersion.h
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+//
+// ES-DE
+// ApplicationVersion.h
+//
+
+#ifndef ES_APP_APPLICATION_VERSION_H
+#define ES_APP_APPLICATION_VERSION_H
+
+// These numbers and strings need to be manually updated for a new version.
+// Do this version number update as the very last commit for the new release version.
+// clang-format off
+#define PROGRAM_VERSION_MAJOR 3
+#define PROGRAM_VERSION_MINOR 0
+#define PROGRAM_VERSION_MAINTENANCE 0
+#define PROGRAM_RELEASE_NUMBER 41
+// clang-format on
+#define PROGRAM_VERSION_STRING "3.0.0"
+
+#define PROGRAM_BUILT_STRING __DATE__ " - " __TIME__
+
+#define RESOURCE_VERSION_STRING "3,0,0\0"
+#define RESOURCE_VERSION PROGRAM_VERSION_MAJOR, PROGRAM_VERSION_MINOR, PROGRAM_VERSION_MAINTENANCE
+
+#endif // ES_APP_APPLICATION_VERSION_H
diff --git a/es-app/src/CollectionSystemsManager.cpp b/es-app/src/CollectionSystemsManager.cpp
index 0f9491a15..300cd600c 100644
--- a/es-app/src/CollectionSystemsManager.cpp
+++ b/es-app/src/CollectionSystemsManager.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// CollectionSystemsManager.cpp
//
// Manages collections of the following two types:
@@ -634,8 +634,31 @@ void CollectionSystemsManager::setEditMode(const std::string& collectionName, bo
mEditingCollectionSystemData = sysData;
if (showPopup) {
+ const std::string controllerType {
+ Settings::getInstance()->getString("InputControllerType")};
+ std::string editButton;
+
+ if (controllerType == "ps123" || controllerType == "ps4" || controllerType == "ps5") {
+#if defined(_MSC_VER) // MSVC compiler.
+ if (Settings::getInstance()->getBool("InputSwapButtons"))
+ editButton = Utils::String::wideStringToString(L"\uF04D"); // Square.
+ else
+ editButton = Utils::String::wideStringToString(L"\uF0D8"); // Triangle.
+#else
+ if (Settings::getInstance()->getBool("InputSwapButtons"))
+ editButton = "\uF04D"; // Square.
+ else
+ editButton = "\uF0D8"; // Triangle.
+#endif
+ }
+ else {
+ if (Settings::getInstance()->getBool("InputSwapButtons"))
+ editButton = "'X'";
+ else
+ editButton = "'Y'";
+ }
mWindow->queueInfoPopup("EDITING '" + Utils::String::toUpper(collectionName) +
- "' COLLECTION, ADD/REMOVE GAMES WITH 'Y'",
+ "' COLLECTION, ADD/REMOVE GAMES WITH " + editButton,
10000);
}
}
@@ -1437,7 +1460,7 @@ std::vector CollectionSystemsManager::getSystemsFromConfig()
std::vector configPaths {SystemData::getConfigPath()};
// Here we don't honor the tag which may be present in the custom es_systems.xml
- // file under ~/.emulationstation/custom_systems as we really want to include all the themes
+ // file under /custom_systems as we really want to include all the themes
// supported by ES-DE. Otherwise a user may accidentally create a custom collection that
// corresponds to a supported theme.
for (auto path : configPaths) {
@@ -1625,6 +1648,6 @@ std::string CollectionSystemsManager::getCustomCollectionConfigPath(
std::string CollectionSystemsManager::getCollectionsFolder()
{
- return Utils::FileSystem::getGenericPath(Utils::FileSystem::getHomePath() +
- "/.emulationstation/collections");
+ return Utils::FileSystem::getGenericPath(Utils::FileSystem::getAppDataDirectory() +
+ "/collections");
}
diff --git a/es-app/src/CollectionSystemsManager.h b/es-app/src/CollectionSystemsManager.h
index 344fb969b..35162271e 100644
--- a/es-app/src/CollectionSystemsManager.h
+++ b/es-app/src/CollectionSystemsManager.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// CollectionSystemsManager.h
//
// Manages collections of the following two types:
diff --git a/es-app/src/EmulationStation.h b/es-app/src/EmulationStation.h
deleted file mode 100644
index 1333dc3f6..000000000
--- a/es-app/src/EmulationStation.h
+++ /dev/null
@@ -1,26 +0,0 @@
-// SPDX-License-Identifier: MIT
-//
-// EmulationStation.h
-//
-// Version and build information.
-//
-
-#ifndef ES_APP_EMULATION_STATION_H
-#define ES_APP_EMULATION_STATION_H
-
-// These numbers and strings need to be manually updated for a new version.
-// Do this version number update as the very last commit for the new release version.
-// clang-format off
-#define PROGRAM_VERSION_MAJOR 2
-#define PROGRAM_VERSION_MINOR 2
-#define PROGRAM_VERSION_MAINTENANCE 1
-#define PROGRAM_RELEASE_NUMBER 40
-// clang-format on
-#define PROGRAM_VERSION_STRING "2.2.1"
-
-#define PROGRAM_BUILT_STRING __DATE__ " - " __TIME__
-
-#define RESOURCE_VERSION_STRING "2,2,1\0"
-#define RESOURCE_VERSION PROGRAM_VERSION_MAJOR, PROGRAM_VERSION_MINOR, PROGRAM_VERSION_MAINTENANCE
-
-#endif // ES_APP_EMULATION_STATION_H
diff --git a/es-app/src/FileData.cpp b/es-app/src/FileData.cpp
index 69eb22899..468489440 100644
--- a/es-app/src/FileData.cpp
+++ b/es-app/src/FileData.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// FileData.cpp
//
// Provides game file data structures and functions to access and sort this information.
@@ -25,6 +25,10 @@
#include "views/GamelistView.h"
#include "views/ViewController.h"
+#if defined(__ANDROID__)
+#include "utils/PlatformUtilAndroid.h"
+#endif
+
#include
#include
@@ -148,6 +152,10 @@ const std::vector FileData::getChildrenRecursive() const
const std::string FileData::getROMDirectory()
{
+#if defined(__ANDROID__)
+ return AndroidVariables::sROMDirectory;
+#endif
+
const std::string& romDirSetting {Settings::getInstance()->getString("ROMDirectory")};
std::string romDirPath;
@@ -180,8 +188,8 @@ const std::string FileData::getMediaDirectory()
const std::string& mediaDirSetting {Settings::getInstance()->getString("MediaDirectory")};
std::string mediaDirPath;
- if (mediaDirSetting == "") {
- mediaDirPath = Utils::FileSystem::getHomePath() + "/.emulationstation/downloaded_media/";
+ if (mediaDirSetting.empty()) {
+ mediaDirPath = Utils::FileSystem::getAppDataDirectory() + "/downloaded_media/";
}
else {
mediaDirPath = mediaDirSetting;
@@ -202,7 +210,6 @@ const std::string FileData::getMediaDirectory()
const std::string FileData::getMediafilePath(const std::string& subdirectory) const
{
- const std::vector extList {".png", ".jpg"};
std::string subFolders;
// Extract possible subfolders from the path.
@@ -214,8 +221,8 @@ const std::string FileData::getMediafilePath(const std::string& subdirectory) co
subFolders + "/" + getDisplayName()};
// Look for an image file in the media directory.
- for (size_t i {0}; i < extList.size(); ++i) {
- std::string mediaPath {tempPath + extList[i]};
+ for (auto& extension : sImageExtensions) {
+ const std::string mediaPath {tempPath + extension};
if (Utils::FileSystem::exists(mediaPath))
return mediaPath;
}
@@ -307,7 +314,6 @@ const std::string FileData::getCustomImagePath() const
const std::string FileData::getVideoPath() const
{
- const std::vector extList {".avi", ".mkv", ".mov", ".mp4", ".wmv"};
std::string subFolders;
// Extract possible subfolders from the path.
@@ -319,8 +325,8 @@ const std::string FileData::getVideoPath() const
getDisplayName()};
// Look for media in the media directory.
- for (size_t i {0}; i < extList.size(); ++i) {
- std::string mediaPath {tempPath + extList[i]};
+ for (auto& extension : sVideoExtensions) {
+ const std::string mediaPath {tempPath + extension};
if (Utils::FileSystem::exists(mediaPath))
return mediaPath;
}
@@ -872,8 +878,13 @@ void FileData::launchGame()
}
}
else {
- LOG(LogDebug) << "FileData::launchGame(): Using default emulator \""
- << mEnvData->mLaunchCommands.front().second << "\"";
+ if (!mEnvData->mLaunchCommands.front().second.empty()) {
+ LOG(LogDebug) << "FileData::launchGame(): Using default emulator \""
+ << mEnvData->mLaunchCommands.front().second << "\"";
+ }
+ else {
+ LOG(LogDebug) << "FileData::launchGame(): Using default emulator";
+ }
}
if (command.empty())
@@ -882,6 +893,7 @@ void FileData::launchGame()
std::string commandRaw {command};
std::string romPath {Utils::FileSystem::getEscapedPath(mPath)};
std::string baseName {Utils::FileSystem::getStem(mPath)};
+ std::string romRaw {Utils::FileSystem::getPreferredPath(mPath)};
// For the special case where a directory has a supported file extension and is therefore
// interpreted as a file, check if there is a matching filename inside the directory.
@@ -890,7 +902,11 @@ void FileData::launchGame()
for (std::string& file : Utils::FileSystem::getDirContent(mPath)) {
if (Utils::FileSystem::getFileName(file) == Utils::FileSystem::getFileName(mPath) &&
(Utils::FileSystem::isRegularFile(file) || Utils::FileSystem::isSymlink(file))) {
+#if defined(__ANDROID__)
+ romRaw = file;
+#else
romPath = Utils::FileSystem::getEscapedPath(file);
+#endif
baseName = baseName.substr(0, baseName.find("."));
break;
}
@@ -898,8 +914,13 @@ void FileData::launchGame()
}
const std::string fileName {baseName + Utils::FileSystem::getExtension(romPath)};
- const std::string romRaw {Utils::FileSystem::getPreferredPath(mPath)};
const std::string esPath {Utils::FileSystem::getExePath()};
+
+#if defined(__ANDROID__)
+ // On Android we always run in the background, although the logic is a bit different
+ // as we don't need to wake up the application manually.
+ bool runInBackground {true};
+#else
bool runInBackground {false};
// In addition to the global RunInBackground setting it's possible to define this flag
@@ -918,6 +939,7 @@ void FileData::launchGame()
// The global setting always applies.
if (Settings::getInstance()->getBool("RunInBackground"))
runInBackground = true;
+#endif
#if !defined(_WIN64)
// Whether to parse .desktop files on Unix or open apps or alias files on macOS.
@@ -947,6 +969,19 @@ void FileData::launchGame()
bool foundCoreFile {false};
std::vector emulatorCorePaths;
+#if defined(__ANDROID__)
+ std::string androidPackage;
+ std::string androidActivity;
+ std::string androidAction;
+ std::string androidCategory;
+ std::string androidMimeType;
+ std::string androidData;
+ std::map androidExtrasString;
+ std::map androidExtrasStringArray;
+ std::map androidExtrasBool;
+ std::vector androidActivityFlags;
+#endif
+
#if defined(_WIN64)
bool hideWindow {false};
@@ -997,30 +1032,27 @@ void FileData::launchGame()
// Expand home path if ~ is used.
command = Utils::FileSystem::expandHomePath(command);
- std::string preCommandPath;
-
// Check for any pre-command entry, and if it exists then expand it using the find rules.
if (command.find("%PRECOMMAND_") != std::string::npos) {
- preCommandPath = findEmulatorPath(command, true);
+ const std::pair preCommand {
+ findEmulator(command, true)};
// Show an error message if there was no matching emulator entry in es_find_rules.xml.
- if (preCommandPath.substr(0, 18) == "NO EMULATOR RULE: ") {
- const std::string& preCommandEntry {
- preCommandPath.substr(18, preCommandPath.size() - 18)};
+ if (preCommand.second == FileData::findEmulatorResult::NO_RULES) {
LOG(LogError)
<< "Couldn't launch game, either there is no emulator entry for pre-command \""
- << preCommandEntry << "\" in es_find_rules.xml or there are no rules defined";
+ << preCommand.first << "\" in es_find_rules.xml or there are no rules defined";
LOG(LogError) << "Raw emulator launch command:";
LOG(LogError) << commandRaw;
window->queueInfoPopup("ERROR: MISSING PRE-COMMAND FIND RULES CONFIGURATION FOR '" +
- preCommandEntry + "'",
+ preCommand.first + "'",
6000);
window->setAllowTextScrolling(true);
window->setAllowFileAnimation(true);
return;
}
- else if (preCommandPath.empty()) {
- LOG(LogError) << "Couldn't launch game, pre-command binary not found";
+ else if (preCommand.first.empty()) {
+ LOG(LogError) << "Couldn't launch game, pre-command not found";
LOG(LogError) << "Raw emulator launch command:";
LOG(LogError) << commandRaw;
@@ -1047,30 +1079,30 @@ void FileData::launchGame()
return;
}
else {
- LOG(LogDebug) << "FileData::launchGame(): Pre-command binary set to \""
- << preCommandPath << "\"";
+ LOG(LogDebug) << "FileData::launchGame(): Pre-command set to \"" << preCommand.first
+ << "\"";
}
}
- // Check that the emulator binary actually exists, and if so, get its path.
- const std::string& binaryPath {findEmulatorPath(command, false)};
+ // Check that the emulator actually exists, and if so, get its path.
+ const std::pair emulator {
+ findEmulator(command, false)};
// Show an error message if there was no matching emulator entry in es_find_rules.xml.
- if (binaryPath.substr(0, 18) == "NO EMULATOR RULE: ") {
- const std::string& emulatorEntry {binaryPath.substr(18, binaryPath.size() - 18)};
+ if (emulator.second == FileData::findEmulatorResult::NO_RULES) {
LOG(LogError) << "Couldn't launch game, either there is no emulator entry for \""
- << emulatorEntry << "\" in es_find_rules.xml or there are no rules defined";
+ << emulator.first << "\" in es_find_rules.xml or there are no rules defined";
LOG(LogError) << "Raw emulator launch command:";
LOG(LogError) << commandRaw;
window->queueInfoPopup(
- "ERROR: MISSING EMULATOR FIND RULES CONFIGURATION FOR '" + emulatorEntry + "'", 6000);
+ "ERROR: MISSING EMULATOR FIND RULES CONFIGURATION FOR '" + emulator.first + "'", 6000);
window->setAllowTextScrolling(true);
window->setAllowFileAnimation(true);
return;
}
- else if (binaryPath.empty()) {
- LOG(LogError) << "Couldn't launch game, emulator binary not found";
+ else if (emulator.second == FileData::findEmulatorResult::NOT_FOUND) {
+ LOG(LogError) << "Couldn't launch game, emulator not found";
LOG(LogError) << "Raw emulator launch command:";
LOG(LogError) << commandRaw;
@@ -1098,15 +1130,29 @@ void FileData::launchGame()
}
#if defined(_WIN64)
else {
- std::string binaryLogPath {Utils::String::replace(
- Utils::String::replace(binaryPath, "%ESPATH%", esPath), "/", "\\")};
- if (binaryLogPath.front() != '\"' && binaryLogPath.back() != '\"')
- binaryLogPath = "\"" + binaryLogPath + "\"";
- LOG(LogDebug) << "FileData::launchGame(): Emulator binary set to " << binaryLogPath;
+ std::string emulatorLogPath {Utils::String::replace(
+ Utils::String::replace(emulator.first, "%ESPATH%", esPath), "/", "\\")};
+ if (emulatorLogPath.front() != '\"' && emulatorLogPath.back() != '\"')
+ emulatorLogPath = "\"" + emulatorLogPath + "\"";
+ LOG(LogDebug) << "FileData::launchGame(): Emulator set to " << emulatorLogPath;
#else
+#if defined(__ANDROID__)
+ else if (emulator.second == FileData::findEmulatorResult::FOUND_ANDROID_PACKAGE) {
+ androidPackage = emulator.first;
+ size_t separatorPos {androidPackage.find('/')};
+
+ if (separatorPos != std::string::npos) {
+ androidActivity = androidPackage.substr(separatorPos + 1);
+ androidPackage = androidPackage.substr(0, separatorPos);
+ }
+
+ LOG(LogDebug) << "FileData::launchGame(): Found emulator package \"" << androidPackage
+ << "\"";
+ }
+#endif
else if (!isShortcut) {
- LOG(LogDebug) << "FileData::launchGame(): Emulator binary set to \""
- << Utils::String::replace(binaryPath, "%ESPATH%", esPath) << "\"";
+ LOG(LogDebug) << "FileData::launchGame(): Emulator set to \""
+ << Utils::String::replace(emulator.first, "%ESPATH%", esPath) << "\"";
#endif
}
@@ -1127,11 +1173,12 @@ void FileData::launchGame()
if (spacePos != std::string::npos) {
coreRaw = command.substr(emuPathPos, spacePos - emuPathPos);
#if defined(_WIN64)
- coreFile = Utils::FileSystem::getParent(Utils::String::replace(binaryPath, "\"", "")) +
- command.substr(emuPathPos + 9, spacePos - emuPathPos - 9);
+ coreFile =
+ Utils::FileSystem::getParent(Utils::String::replace(emulator.first, "\"", "")) +
+ command.substr(emuPathPos + 9, spacePos - emuPathPos - 9);
coreFile = Utils::String::replace(coreFile, "/", "\\");
#else
- coreFile = Utils::FileSystem::getParent(binaryPath) +
+ coreFile = Utils::FileSystem::getParent(emulator.first) +
command.substr(emuPathPos + 9, spacePos - emuPathPos - 9);
#endif
if (hasQuotationMark) {
@@ -1192,7 +1239,7 @@ void FileData::launchGame()
// the emulator core using the rules defined in es_find_rules.xml.
for (std::string& path : emulatorCorePaths) {
// The position of the %CORE_ variable could have changed as there may have been an
- // %EMULATOR_ variable that was substituted for the actual emulator binary.
+ // %EMULATOR_ variable that was substituted for the actual emulator.
coreEntryPos = command.find("%CORE_");
coreFilePos = command.find("%", coreEntryPos + 6);
@@ -1218,10 +1265,11 @@ void FileData::launchGame()
#if defined(_WIN64)
coreFile = coreFile.replace(
stringPos, 9,
- Utils::FileSystem::getParent(Utils::String::replace(binaryPath, "\"", "")));
+ Utils::FileSystem::getParent(Utils::String::replace(emulator.first, "\"", "")));
coreFile = Utils::String::replace(coreFile, "/", "\\");
#else
- coreFile = coreFile.replace(stringPos, 9, Utils::FileSystem::getParent(binaryPath));
+ coreFile =
+ coreFile.replace(stringPos, 9, Utils::FileSystem::getParent(emulator.first));
#endif
}
@@ -1325,7 +1373,7 @@ void FileData::launchGame()
#if defined(_WIN64)
startDirectory = Utils::String::replace(
startDirectory, "%EMUDIR%",
- Utils::FileSystem::getParent(Utils::String::replace(binaryPath, "\"", "")));
+ Utils::FileSystem::getParent(Utils::String::replace(emulator.first, "\"", "")));
startDirectory = Utils::String::replace(
startDirectory, "%GAMEDIR%",
@@ -1336,7 +1384,7 @@ void FileData::launchGame()
#else
startDirectory = Utils::String::replace(
startDirectory, "%EMUDIR%",
- Utils::FileSystem::getParent(Utils::String::replace(binaryPath, "\\", "")));
+ Utils::FileSystem::getParent(Utils::String::replace(emulator.first, "\\", "")));
startDirectory = Utils::String::replace(
startDirectory, "%GAMEDIR%",
@@ -1500,7 +1548,7 @@ void FileData::launchGame()
if (Utils::FileSystem::exists(Utils::String::replace(romPath, "\\", ""))) {
LOG(LogInfo) << "Opening app or alias file \""
<< Utils::String::replace(romPath, "\\", "") << "\"";
- command = Utils::String::replace(command, binaryPath, "open -W -a");
+ command = Utils::String::replace(command, emulator.first, "open -W -a");
}
else {
LOG(LogError) << "App or alias file \"" << romPath
@@ -1551,7 +1599,7 @@ void FileData::launchGame()
}
romPath = Utils::String::replace(romPath, "%%", "%");
romPath = Utils::String::trim(romPath);
- command = Utils::String::replace(command, binaryPath, "");
+ command = Utils::String::replace(command, emulator.first, "");
execEntry = true;
break;
}
@@ -1576,6 +1624,7 @@ void FileData::launchGame()
#endif
#endif
+#if !defined(__ANDROID__)
// Replace the remaining variables with their actual values.
command = Utils::String::replace(command, "%ROM%", romPath);
command = Utils::String::replace(command, "%BASENAME%", baseName);
@@ -1583,12 +1632,142 @@ void FileData::launchGame()
command = Utils::String::replace(command, "%ROMRAW%", romRaw);
command = Utils::String::replace(command, "%ROMPATH%",
Utils::FileSystem::getEscapedPath(getROMDirectory()));
+#else
+ command = Utils::String::replace(command, "%ANDROIDPACKAGE%", androidPackage);
+
+ const std::vector androidVariabels {
+ "%ACTION%=", "%CATEGORY%=", "%MIMETYPE%=", "%DATA%="};
+
+ for (std::string variable : androidVariabels) {
+ size_t dataPos {command.find(variable)};
+ if (dataPos != std::string::npos) {
+ bool invalidEntry {false};
+ bool isQuoted {(command.length() > dataPos + variable.length() &&
+ command[dataPos + variable.length()] == '\"')};
+ std::string value;
+
+ if (isQuoted) {
+ const size_t closeQuotePos {command.find("\"", dataPos + variable.length() + 1)};
+ if (closeQuotePos != std::string::npos)
+ value = command.substr(dataPos + variable.length() + 1,
+ closeQuotePos - (dataPos + variable.length() + 1));
+ else
+ invalidEntry = true;
+ }
+ else {
+ const size_t spacePos {command.find(" ", dataPos)};
+ if (spacePos != std::string::npos)
+ value = command.substr(dataPos + variable.length(),
+ spacePos - (dataPos + variable.length()));
+ else
+ value = command.substr(dataPos + variable.length(),
+ command.size() - dataPos + variable.length());
+ }
+
+ if (invalidEntry) {
+ LOG(LogError) << "Invalid entry in systems configuration file es_systems.xml";
+ LOG(LogError) << "Raw emulator launch command:";
+ LOG(LogError) << commandRaw;
+
+ window->queueInfoPopup("ERROR: INVALID ENTRY IN SYSTEMS CONFIGURATION FILE", 6000);
+ window->setAllowTextScrolling(true);
+ window->setAllowFileAnimation(true);
+ return;
+ }
+
+ if (variable == "%ACTION%=")
+ androidAction = value;
+ else if (variable == "%DATA%=")
+ androidData = value;
+ else if (variable == "%CATEGORY%=")
+ androidCategory = value;
+ else if (variable == "%MIMETYPE%=")
+ androidMimeType = value;
+ }
+ }
+
+ std::vector extraVariabels {"%EXTRA_", "%EXTRAARRAY_", "%EXTRABOOL_"};
+
+ for (std::string variable : extraVariabels) {
+ size_t extraPos {command.find(variable)};
+ while (extraPos != std::string::npos) {
+ if (extraPos != std::string::npos) {
+ bool invalidEntry {false};
+ bool isQuoted {false};
+ std::string extraName;
+ std::string extraValue;
+
+ size_t equalPos {command.find("=", extraPos)};
+ if (equalPos == std::string::npos)
+ invalidEntry = true;
+
+ if (!invalidEntry && extraPos + variable.length() + 1 >= command.size())
+ invalidEntry = true;
+
+ if (!invalidEntry) {
+ if (command.length() > equalPos && command[equalPos + 1] == '\"')
+ isQuoted = true;
+
+ extraName = command.substr(extraPos + variable.length(),
+ equalPos - (extraPos + variable.length() + 1));
+
+ if (isQuoted) {
+ const size_t closeQuotePos {command.find("\"", equalPos + 2)};
+ if (closeQuotePos != std::string::npos)
+ extraValue =
+ command.substr(equalPos + 2, closeQuotePos - (equalPos + 2));
+ else
+ invalidEntry = true;
+ }
+ else {
+ const size_t spacePos {command.find(" ", extraPos)};
+ if (spacePos != std::string::npos)
+ extraValue = command.substr(equalPos + 1, spacePos - (equalPos + 1));
+ else
+ extraValue = command.substr(equalPos + 1, command.size() - equalPos);
+ }
+
+ if (invalidEntry) {
+ LOG(LogError)
+ << "Invalid entry in systems configuration file es_systems.xml";
+ LOG(LogError) << "Raw emulator launch command:";
+ LOG(LogError) << commandRaw;
+
+ window->queueInfoPopup("ERROR: INVALID ENTRY IN SYSTEMS CONFIGURATION FILE",
+ 6000);
+ window->setAllowTextScrolling(true);
+ window->setAllowFileAnimation(true);
+ return;
+ }
+
+ if (extraName != "" && extraValue != "") {
+ if (variable == "%EXTRA_")
+ androidExtrasString[extraName] = extraValue;
+ else if (variable == "%EXTRAARRAY_")
+ androidExtrasStringArray[extraName] = extraValue;
+ else if (variable == "%EXTRABOOL_")
+ androidExtrasBool[extraName] = extraValue;
+ }
+ }
+ }
+ extraPos = command.find(variable, extraPos + 1);
+ }
+ }
+
+ if (command.find("%ACTIVITY_CLEAR_TASK%") != std::string::npos)
+ androidActivityFlags.emplace_back("%ACTIVITY_CLEAR_TASK%");
+ if (command.find("%ACTIVITY_CLEAR_TOP%") != std::string::npos)
+ androidActivityFlags.emplace_back("%ACTIVITY_CLEAR_TOP%");
+ if (command.find("%ACTIVITY_NO_HISTORY%") != std::string::npos)
+ androidActivityFlags.emplace_back("%ACTIVITY_NO_HISTORY%");
+#endif
+
#if defined(_WIN64)
command = Utils::String::replace(
command, "%ESPATH%", Utils::String::replace(Utils::FileSystem::getExePath(), "/", "\\"));
command = Utils::String::replace(command, "%EMUDIR%",
Utils::FileSystem::getEscapedPath(Utils::FileSystem::getParent(
- Utils::String::replace(binaryPath, "\"", ""))));
+ Utils::String::replace(emulator.first, "\"", ""))));
command = Utils::String::replace(command, "%GAMEDIR%",
Utils::FileSystem::getEscapedPath(Utils::FileSystem::getParent(
Utils::String::replace(romPath, "\"", ""))));
@@ -1600,7 +1779,7 @@ void FileData::launchGame()
command = Utils::String::replace(command, "%ESPATH%", Utils::FileSystem::getExePath());
command = Utils::String::replace(command, "%EMUDIR%",
Utils::FileSystem::getEscapedPath(Utils::FileSystem::getParent(
- Utils::String::replace(binaryPath, "\\", ""))));
+ Utils::String::replace(emulator.first, "\\", ""))));
command = Utils::String::replace(command, "%GAMEDIR%",
Utils::FileSystem::getEscapedPath(Utils::FileSystem::getParent(
Utils::String::replace(romPath, "\\", ""))));
@@ -1625,8 +1804,40 @@ void FileData::launchGame()
LOG(LogDebug) << "Raw emulator launch command:";
LOG(LogDebug) << commandRaw;
+#if defined(__ANDROID__)
+ LOG(LogInfo) << "Expanded emulator launch arguments:";
+ LOG(LogInfo) << "Package: " << androidPackage;
+ if (androidActivity != "") {
+ LOG(LogInfo) << "Activity: " << androidActivity;
+ }
+ if (androidAction != "") {
+ LOG(LogInfo) << "Action: " << androidAction;
+ }
+ if (androidCategory != "") {
+ LOG(LogInfo) << "Category: " << androidCategory;
+ }
+ if (androidMimeType != "") {
+ LOG(LogInfo) << "MIME type: " << androidMimeType;
+ }
+ if (androidData != "") {
+ LOG(LogInfo) << "Data: " << androidData;
+ }
+ for (auto& extra : androidExtrasString) {
+ LOG(LogInfo) << "Extra name: " << extra.first;
+ LOG(LogInfo) << "Extra value: " << extra.second;
+ }
+ for (auto& extra : androidExtrasStringArray) {
+ LOG(LogInfo) << "Extra array name: " << extra.first;
+ LOG(LogInfo) << "Extra array value: " << extra.second;
+ }
+ for (auto& extra : androidExtrasBool) {
+ LOG(LogInfo) << "Extra bool name: " << extra.first;
+ LOG(LogInfo) << "Extra bool value: " << extra.second;
+ }
+#else
LOG(LogInfo) << "Expanded emulator launch command:";
LOG(LogInfo) << command;
+#endif
#if defined(FLATPAK_BUILD)
// Break out of the sandbox.
@@ -1645,12 +1856,17 @@ void FileData::launchGame()
returnValue = Utils::Platform::launchGameWindows(
Utils::String::stringToWideString(command),
Utils::String::stringToWideString(startDirectory), runInBackground, hideWindow);
+#elif defined(__ANDROID__)
+ returnValue = Utils::Platform::Android::launchGame(
+ androidPackage, androidActivity, androidAction, androidCategory, androidMimeType,
+ androidData, romRaw, androidExtrasString, androidExtrasStringArray, androidExtrasBool,
+ androidActivityFlags);
#else
- returnValue = Utils::Platform::launchGameUnix(command, startDirectory, runInBackground);
+returnValue = Utils::Platform::launchGameUnix(command, startDirectory, runInBackground);
#endif
// Notify the user in case of a failed game launch using a popup window.
if (returnValue != 0) {
- LOG(LogWarning) << "...launch terminated with nonzero return value " << returnValue;
+ LOG(LogWarning) << "Launch terminated with nonzero return value " << returnValue;
window->queueInfoPopup("ERROR LAUNCHING GAME '" +
Utils::String::toUpper(metadata.get("name")) + "' (ERROR CODE " +
@@ -1692,8 +1908,7 @@ void FileData::launchGame()
getSourceFileData()->getSystem()->getFullName());
}
else {
- std::vector& gameEndParams {
- ViewController::getInstance()->getGameEndEventParams()};
+ std::vector& gameEndParams {window->getGameEndEventParams()};
gameEndParams.emplace_back("game-end");
gameEndParams.emplace_back(romPath);
gameEndParams.emplace_back(getSourceFileData()->metadata.get("name"));
@@ -1737,23 +1952,27 @@ void FileData::launchGame()
gameToUpdate->mSystem->onMetaDataSavePoint();
}
-const std::string FileData::findEmulatorPath(std::string& command, const bool preCommand)
+const std::pair FileData::findEmulator(
+ std::string& command, const bool preCommand)
{
// Extract the emulator executable from the launch command string. There are two ways
// that the emulator can be defined in es_systems.xml, either using the find rules in
- // es_find_rules.xml or via the explicit emulator binary name. In the former case, we
+ // es_find_rules.xml or via the explicit emulator name. In the former case, we
// need to process any configured systempath and staticpath rules (and for Windows also
// winregistrypath and winregistryvalue rules), and in the latter case we simply search
- // for the emulator binary in the system path.
+ // for the emulator in the system path.
std::string emuExecutable;
std::string exePath;
- // Method 1, emulator binary is defined using find rules:
+ // Method 1, emulator is defined using find rules:
#if defined(_WIN64)
std::vector emulatorWinRegistryPaths;
std::vector emulatorWinRegistryValues;
+#endif
+#if defined(__ANDROID__)
+ std::vector emulatorAndroidPackages;
#endif
std::vector emulatorSystemPaths;
std::vector emulatorStaticPaths;
@@ -1782,6 +2001,10 @@ const std::string FileData::findEmulatorPath(std::string& command, const bool pr
SystemData::sFindRules.get()->mEmulators[emulatorEntry].winRegistryPaths;
emulatorWinRegistryValues =
SystemData::sFindRules.get()->mEmulators[emulatorEntry].winRegistryValues;
+#endif
+#if defined(__ANDROID__)
+ emulatorAndroidPackages =
+ SystemData::sFindRules.get()->mEmulators[emulatorEntry].androidPackages;
#endif
emulatorSystemPaths = SystemData::sFindRules.get()->mEmulators[emulatorEntry].systemPaths;
@@ -1793,10 +2016,13 @@ const std::string FileData::findEmulatorPath(std::string& command, const bool pr
if (emulatorEntry != "" && emulatorWinRegistryPaths.empty() &&
emulatorWinRegistryValues.empty() && emulatorSystemPaths.empty() &&
emulatorStaticPaths.empty())
+#elif defined(__ANDROID__)
+ if (emulatorEntry != "" && emulatorAndroidPackages.empty() && emulatorSystemPaths.empty() &&
+ emulatorStaticPaths.empty())
#else
if (emulatorEntry != "" && emulatorSystemPaths.empty() && emulatorStaticPaths.empty())
#endif
- return "NO EMULATOR RULE: " + emulatorEntry;
+ return std::make_pair(emulatorEntry, FileData::findEmulatorResult::NO_RULES);
#if defined(_WIN64)
for (std::string& path : emulatorWinRegistryPaths) {
@@ -1834,19 +2060,19 @@ const std::string FileData::findEmulatorPath(std::string& command, const bool pr
continue;
}
- // That a value was found does not guarantee that the emulator binary actually exists,
- // so check for that as well.
+ // That a value was found does not guarantee that the emulator actually exists, so
+ // check for that as well.
if (pathStatus == ERROR_SUCCESS) {
if (Utils::FileSystem::isRegularFile(Utils::String::wideStringToString(registryPath)) ||
Utils::FileSystem::isSymlink(Utils::String::wideStringToString(registryPath))) {
- LOG(LogDebug) << "FileData::findEmulatorPath(): "
- << (preCommand ? "Pre-command binary" : "Emulator binary")
+ LOG(LogDebug) << "FileData::findEmulator(): "
+ << (preCommand ? "Pre-command" : "Emulator")
<< " found via winregistrypath rule";
exePath = Utils::FileSystem::getEscapedPath(
Utils::String::wideStringToString(registryPath));
command.replace(startPos, endPos - startPos + 1, exePath);
RegCloseKey(registryKey);
- return exePath;
+ return std::make_pair(exePath, FileData::findEmulatorResult::FOUND_FILE);
}
}
RegCloseKey(registryKey);
@@ -1906,25 +2132,47 @@ const std::string FileData::findEmulatorPath(std::string& command, const bool pr
if (!appendString.empty())
path.append(Utils::String::stringToWideString(appendString));
- // That a value was found does not guarantee that the emulator binary actually exists,
+ // That a value was found does not guarantee that the emulator actually exists,
// so check for that as well.
if (pathStatus == ERROR_SUCCESS) {
if (Utils::FileSystem::isRegularFile(Utils::String::wideStringToString(path)) ||
Utils::FileSystem::isSymlink(Utils::String::wideStringToString(path))) {
- LOG(LogDebug) << "FileData::findEmulatorPath(): "
- << (preCommand ? "Pre-command binary" : "Emulator binary")
+ LOG(LogDebug) << "FileData::findEmulator(): "
+ << (preCommand ? "Pre-command" : "Emulator")
<< " found via winregistryvalue rule";
exePath =
Utils::FileSystem::getEscapedPath(Utils::String::wideStringToString(path));
command.replace(startPos, endPos - startPos + 1, exePath);
RegCloseKey(registryKey);
- return exePath;
+ return std::make_pair(exePath, FileData::findEmulatorResult::FOUND_FILE);
}
}
RegCloseKey(registryKey);
}
#endif
+#if defined(__ANDROID__)
+ for (std::string& androidpackage : emulatorAndroidPackages) {
+ // If a forward slash character is present in the androidpackage entry it means an explicit
+ // Intent activity should be used rather than the default one. The checkEmulatorInstalled()
+ // Java function will check for the activity as well and if it's not found it flags the
+ // overall emulator entry as not found.
+ std::string packageName {androidpackage};
+ std::string activity;
+ size_t separatorPos {packageName.find('/')};
+
+ if (separatorPos != std::string::npos) {
+ activity = packageName.substr(separatorPos + 1);
+ packageName = packageName.substr(0, separatorPos);
+ }
+
+ if (Utils::Platform::Android::checkEmulatorInstalled(packageName, activity)) {
+ return std::make_pair(androidpackage,
+ FileData::findEmulatorResult::FOUND_ANDROID_PACKAGE);
+ }
+ }
+#endif
+
for (std::string& path : emulatorSystemPaths) {
#if defined(_WIN64)
std::wstring pathWide {Utils::String::stringToWideString(path)};
@@ -1945,30 +2193,30 @@ const std::string FileData::findEmulatorPath(std::string& command, const bool pr
}
}
if (exePath != "") {
- LOG(LogDebug) << "FileData::findEmulatorPath(): "
- << (preCommand ? "Pre-command binary" : "Emulator binary")
+ LOG(LogDebug) << "FileData::findEmulator(): "
+ << (preCommand ? "Pre-command" : "Emulator")
<< " found via systempath rule";
exePath += "\\" + path;
exePath = Utils::FileSystem::getEscapedPath(exePath);
command.replace(startPos, endPos - startPos + 1, exePath);
- return exePath;
+ return std::make_pair(exePath, FileData::findEmulatorResult::FOUND_FILE);
}
#else
exePath = Utils::FileSystem::getPathToBinary(path);
if (exePath != "") {
- LOG(LogDebug) << "FileData::findEmulatorPath(): "
- << (preCommand ? "Pre-command binary" : "Emulator binary")
+ LOG(LogDebug) << "FileData::findEmulator(): "
+ << (preCommand ? "Pre-command" : "Emulator")
<< " found via systempath rule";
exePath += "/" + path;
command.replace(startPos, endPos - startPos + 1, exePath);
- return exePath;
+ return std::make_pair(exePath, FileData::findEmulatorResult::FOUND_FILE);
}
#endif
}
for (std::string& path : emulatorStaticPaths) {
// If a pipe character is present in the staticpath entry it means we should substitute
- // the emulator binary with whatever is defined after the pipe character.
+ // the emulator with whatever is defined after the pipe character.
std::string replaceCommand;
const size_t pipePos {path.find('|')};
@@ -1998,23 +2246,23 @@ const std::string FileData::findEmulatorPath(std::string& command, const bool pr
}
if (Utils::FileSystem::isRegularFile(path) || Utils::FileSystem::isSymlink(path)) {
- LOG(LogDebug) << "FileData::findEmulatorPath(): "
- << (preCommand ? "Pre-command binary" : "Emulator binary")
+ LOG(LogDebug) << "FileData::findEmulator(): "
+ << (preCommand ? "Pre-command" : "Emulator")
<< " found via staticpath rule";
if (replaceCommand == "") {
exePath = Utils::FileSystem::getEscapedPath(path);
}
else {
- LOG(LogDebug) << "FileData::findEmulatorPath(): Replacing emulator binary in "
+ LOG(LogDebug) << "FileData::findEmulator(): Replacing emulator in "
"staticpath rule with explicitly defined command";
exePath = replaceCommand;
}
command.replace(startPos, endPos - startPos + 1, exePath);
- return exePath;
+ return std::make_pair(exePath, FileData::findEmulatorResult::FOUND_FILE);
}
}
- // Method 2, exact emulator binary name:
+ // Method 2, exact emulator name:
// If %ESPATH% is used, then expand it to the binary directory of ES-DE.
command = Utils::String::replace(command, "%ESPATH%", Utils::FileSystem::getExePath());
@@ -2052,7 +2300,7 @@ const std::string FileData::findEmulatorPath(std::string& command, const bool pr
exePath = Utils::String::wideStringToString(pathBuffer.data());
}
-#else
+#elif !defined(__ANDROID__)
if (Utils::FileSystem::isRegularFile(emuExecutable) ||
Utils::FileSystem::isSymlink(emuExecutable)) {
exePath = Utils::FileSystem::getEscapedPath(emuExecutable);
@@ -2065,7 +2313,10 @@ const std::string FileData::findEmulatorPath(std::string& command, const bool pr
}
#endif
- return exePath;
+ if (exePath.empty())
+ return std::make_pair("", FileData::findEmulatorResult::NOT_FOUND);
+ else
+ return std::make_pair(exePath, FileData::findEmulatorResult::FOUND_FILE);
}
CollectionFileData::CollectionFileData(FileData* file, SystemData* system)
diff --git a/es-app/src/FileData.h b/es-app/src/FileData.h
index 46aed47e3..a12e5613d 100644
--- a/es-app/src/FileData.h
+++ b/es-app/src/FileData.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// FileData.h
//
// Provides game file data structures and functions to access and sort this information.
@@ -40,11 +40,7 @@ public:
const std::string& getName() { return metadata.get("name"); }
const std::string& getSortName();
// Returns our best guess at the "real" name for this file.
- std::string getDisplayName() const
- {
- const std::string& stem {Utils::FileSystem::getStem(mPath)};
- return stem;
- }
+ std::string getDisplayName() const { return Utils::FileSystem::getStem(mPath); }
std::string getCleanName() const
{
return Utils::String::removeParenthesis(this->getDisplayName());
@@ -112,8 +108,8 @@ public:
bool excludeRecursively,
bool respectExclusions) const;
- void addChild(FileData* file); // Error if mType != FOLDER
- void removeChild(FileData* file); // Error if mType != FOLDER
+ void addChild(FileData* file);
+ void removeChild(FileData* file);
virtual std::string getKey() { return getFileName(); }
const bool isArcadeAsset() const;
@@ -123,8 +119,16 @@ public:
virtual FileData* getSourceFileData() { return this; }
const std::string& getSystemName() const { return mSystemName; }
+ enum class findEmulatorResult {
+ FOUND_FILE,
+ FOUND_ANDROID_PACKAGE,
+ NOT_FOUND,
+ NO_RULES
+ };
+
void launchGame();
- const std::string findEmulatorPath(std::string& command, const bool preCommand);
+ const std::pair findEmulator(std::string& command,
+ const bool preCommand);
using ComparisonFunction = bool(const FileData* a, const FileData* b);
struct SortType {
@@ -167,6 +171,9 @@ private:
std::vector mChildrenLastPlayed;
std::vector mChildrenMostPlayed;
std::function mUpdateListCallback;
+ static inline std::vector sImageExtensions {".png", ".jpg"};
+ static inline std::vector sVideoExtensions {".mp4", ".mkv", ".avi",
+ ".mp4", ".wmv", ".mov"};
// The pair includes all games, and favorite games.
std::pair mGameCount;
bool mOnlyFolders;
diff --git a/es-app/src/FileFilterIndex.cpp b/es-app/src/FileFilterIndex.cpp
index 3c63f03bf..760fb6ef6 100644
--- a/es-app/src/FileFilterIndex.cpp
+++ b/es-app/src/FileFilterIndex.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// FileFilterIndex.cpp
//
// Gamelist filters.
diff --git a/es-app/src/FileFilterIndex.h b/es-app/src/FileFilterIndex.h
index a034a361e..10dc6e98f 100644
--- a/es-app/src/FileFilterIndex.h
+++ b/es-app/src/FileFilterIndex.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// FileFilterIndex.h
//
// Gamelist filters.
diff --git a/es-app/src/FileSorts.cpp b/es-app/src/FileSorts.cpp
index 7db7f2e64..48b8b057e 100644
--- a/es-app/src/FileSorts.cpp
+++ b/es-app/src/FileSorts.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// FileSorts.cpp
//
// Gamelist sorting functions.
diff --git a/es-app/src/FileSorts.h b/es-app/src/FileSorts.h
index e7f84346d..d12725d57 100644
--- a/es-app/src/FileSorts.h
+++ b/es-app/src/FileSorts.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// FileSorts.h
//
// Gamelist sorting functions.
diff --git a/es-app/src/GamelistFileParser.cpp b/es-app/src/GamelistFileParser.cpp
index 35563cf6e..7958637ba 100644
--- a/es-app/src/GamelistFileParser.cpp
+++ b/es-app/src/GamelistFileParser.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GamelistFileParser.cpp
//
// Parses and updates the gamelist.xml files.
diff --git a/es-app/src/GamelistFileParser.h b/es-app/src/GamelistFileParser.h
index 465c3e462..b53670711 100644
--- a/es-app/src/GamelistFileParser.h
+++ b/es-app/src/GamelistFileParser.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GamelistFileParser.h
//
// Parses and updates the gamelist.xml files.
diff --git a/es-app/src/MediaViewer.cpp b/es-app/src/MediaViewer.cpp
index a975f7516..a682ce637 100644
--- a/es-app/src/MediaViewer.cpp
+++ b/es-app/src/MediaViewer.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// MediaViewer.cpp
//
// Fullscreen game media viewer.
diff --git a/es-app/src/MediaViewer.h b/es-app/src/MediaViewer.h
index d1a8789ec..fb36559cc 100644
--- a/es-app/src/MediaViewer.h
+++ b/es-app/src/MediaViewer.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// MediaViewer.h
//
// Fullscreen game media viewer.
diff --git a/es-app/src/MetaData.cpp b/es-app/src/MetaData.cpp
index 79d8a9efd..15072160a 100644
--- a/es-app/src/MetaData.cpp
+++ b/es-app/src/MetaData.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// MetaData.cpp
//
// Static data for default metadata values as well as functions
diff --git a/es-app/src/MetaData.h b/es-app/src/MetaData.h
index 4ae9fabe6..2384e165f 100644
--- a/es-app/src/MetaData.h
+++ b/es-app/src/MetaData.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// MetaData.h
//
// Static data for default metadata values as well as functions
diff --git a/es-app/src/MiximageGenerator.cpp b/es-app/src/MiximageGenerator.cpp
index 73a39ea0c..a2714643e 100644
--- a/es-app/src/MiximageGenerator.cpp
+++ b/es-app/src/MiximageGenerator.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// MiximageGenerator.cpp
//
// Generates miximages from screenshots, marquees, 3D boxes/covers and physical media images.
@@ -895,6 +895,17 @@ std::string MiximageGenerator::getSavePath() const
if (!Utils::FileSystem::exists(path))
Utils::FileSystem::createDirectory(path);
+#if defined(__ANDROID__)
+ if (!Utils::FileSystem::exists(path + ".nomedia")) {
+ LOG(LogInfo) << "Creating \"no media\" file \"" << path + ".nomedia"
+ << "\"...";
+ Utils::FileSystem::createEmptyFile(path + ".nomedia");
+ if (!Utils::FileSystem::exists(path + ".nomedia")) {
+ LOG(LogWarning) << "Couldn't create file, permission problems?";
+ }
+ }
+#endif
+
path += mGame->getSystemName() + "/miximages" + subFolders + "/";
if (!Utils::FileSystem::exists(path))
diff --git a/es-app/src/MiximageGenerator.h b/es-app/src/MiximageGenerator.h
index ffc7a7cfa..a1f501bcc 100644
--- a/es-app/src/MiximageGenerator.h
+++ b/es-app/src/MiximageGenerator.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// MiximageGenerator.h
//
// Generates miximages from screenshots, marquees, 3D boxes/covers and physical media images.
diff --git a/es-app/src/PDFViewer.cpp b/es-app/src/PDFViewer.cpp
index 6f59e98f0..81cfb3dad 100644
--- a/es-app/src/PDFViewer.cpp
+++ b/es-app/src/PDFViewer.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// PDFViewer.cpp
//
// Parses and renders pages using the Poppler library via the external es-pdf-convert binary.
@@ -20,6 +20,10 @@
#include
#endif
+#if defined(__ANDROID__)
+#include "ConvertPDF.h"
+#endif
+
#define DEBUG_PDF_CONVERSION false
#define KEY_REPEAT_START_DELAY 600
@@ -51,6 +55,7 @@ bool PDFViewer::startPDFViewer(FileData* game)
{
ViewController::getInstance()->pauseViewVideos();
+#if !defined(__ANDROID__)
#if defined(_WIN64)
const std::string convertBinary {"/es-pdf-converter/es-pdf-convert.exe"};
#else
@@ -67,6 +72,7 @@ bool PDFViewer::startPDFViewer(FileData* game)
ViewController::getInstance()->startViewVideos();
return false;
}
+#endif // !__ANDROID__
mGame = game;
mManualPath = mGame->getManualPath();
@@ -298,6 +304,9 @@ bool PDFViewer::getDocumentInfo()
// Close process and thread handles.
CloseHandle(pi.hProcess);
CloseHandle(pi.hThread);
+#elif defined(__ANDROID__)
+ if (ConvertPDF::processFile(mManualPath, "-fileinfo", 0, 0, 0, commandOutput) == -1)
+ return false;
#else
FILE* commandPipe;
std::array buffer {};
@@ -439,6 +448,13 @@ void PDFViewer::convertPage(int pageNum)
CloseHandle(childStdoutRead);
WaitForSingleObject(pi.hThread, INFINITE);
WaitForSingleObject(pi.hProcess, INFINITE);
+#elif (__ANDROID__)
+ ConvertPDF::processFile(mManualPath, "-convert", pageNum,
+ static_cast(mPages[pageNum].width),
+ static_cast(mPages[pageNum].height), imageData);
+ mPages[pageNum].imageData.insert(mPages[pageNum].imageData.end(),
+ std::make_move_iterator(imageData.begin()),
+ std::make_move_iterator(imageData.end()));
#else
FILE* commandPipe;
std::array buffer {};
@@ -461,6 +477,8 @@ void PDFViewer::convertPage(int pageNum)
#if defined(_WIN64)
if (!processReturnValue || (static_cast(imageDataSize) <
mPages[pageNum].width * mPages[pageNum].height * 4)) {
+#elif defined(__ANDROID__)
+ if (static_cast(imageDataSize) < mPages[pageNum].width * mPages[pageNum].height * 4) {
#else
if (returnValue != 0 || (static_cast(imageDataSize) <
mPages[pageNum].width * mPages[pageNum].height * 4)) {
diff --git a/es-app/src/PDFViewer.h b/es-app/src/PDFViewer.h
index 8a1d82eba..735009a17 100644
--- a/es-app/src/PDFViewer.h
+++ b/es-app/src/PDFViewer.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// PDFViewer.h
//
// Parses and renders pages using the Poppler library via the external es-pdf-convert binary.
diff --git a/es-app/src/PlatformId.cpp b/es-app/src/PlatformId.cpp
index 9b76d08e5..b427bbd78 100644
--- a/es-app/src/PlatformId.cpp
+++ b/es-app/src/PlatformId.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// PlatformId.cpp
//
// Index of all supported systems/platforms.
diff --git a/es-app/src/PlatformId.h b/es-app/src/PlatformId.h
index dccaf987f..3520a090c 100644
--- a/es-app/src/PlatformId.h
+++ b/es-app/src/PlatformId.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// PlatformId.h
//
// Index of all supported systems/platforms.
diff --git a/es-app/src/Screensaver.cpp b/es-app/src/Screensaver.cpp
index 3319922a7..be15e5088 100644
--- a/es-app/src/Screensaver.cpp
+++ b/es-app/src/Screensaver.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// Screensaver.cpp
//
// Screensaver, supporting the following types:
@@ -464,8 +464,11 @@ void Screensaver::generateVideoList()
void Screensaver::generateCustomImageList()
{
- std::string imageDir = Utils::FileSystem::expandHomePath(
- Settings::getInstance()->getString("ScreensaverSlideshowImageDir"));
+ std::string imageDir {Utils::FileSystem::expandHomePath(
+ Settings::getInstance()->getString("ScreensaverSlideshowCustomDir"))};
+
+ if (imageDir.empty())
+ imageDir = Utils::FileSystem::getAppDataDirectory() + "/screensavers/custom_slideshow";
// This makes it possible to set the custom image directory relative to the ES-DE binary
// directory or the ROM directory.
@@ -473,19 +476,23 @@ void Screensaver::generateCustomImageList()
imageDir = Utils::String::replace(imageDir, "%ROMPATH%", FileData::getROMDirectory());
if (imageDir != "" && Utils::FileSystem::isDirectory(imageDir)) {
- std::string imageFilter {".jpg, .JPG, .png, .PNG"};
- Utils::FileSystem::StringList dirContent = Utils::FileSystem::getDirContent(
- imageDir, Settings::getInstance()->getBool("ScreensaverSlideshowRecurse"));
+ const std::vector extList {".jpg", ".JPG", ".png", ".PNG", ".gif",
+ ".GIF", ".webp", ".WEBP", ".svg", ".SVG"};
+
+ Utils::FileSystem::StringList dirContent {Utils::FileSystem::getDirContent(
+ imageDir, Settings::getInstance()->getBool("ScreensaverSlideshowRecurse"))};
for (auto it = dirContent.begin(); it != dirContent.end(); ++it) {
if (Utils::FileSystem::isRegularFile(*it)) {
- if (imageFilter.find(Utils::FileSystem::getExtension(*it)) != std::string::npos)
+ if (std::find(extList.cbegin(), extList.cend(),
+ Utils::FileSystem::getExtension(*it)) != extList.cend())
mImageCustomFiles.push_back(*it);
}
}
}
else {
- LOG(LogWarning) << "Custom screensaver image directory '" << imageDir << "' does not exist";
+ LOG(LogWarning) << "Custom screensaver image directory \"" << imageDir
+ << "\" does not exist";
}
mCustomFilesInventory.insert(mCustomFilesInventory.begin(), mImageCustomFiles.begin(),
diff --git a/es-app/src/Screensaver.h b/es-app/src/Screensaver.h
index 30d123ba9..62b8134a8 100644
--- a/es-app/src/Screensaver.h
+++ b/es-app/src/Screensaver.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// Screensaver.h
//
// Screensaver, supporting the following types:
diff --git a/es-app/src/SystemData.cpp b/es-app/src/SystemData.cpp
index b54e0b487..81c340a17 100644
--- a/es-app/src/SystemData.cpp
+++ b/es-app/src/SystemData.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// SystemData.cpp
//
// Provides data structures for the game systems and populates and indexes them based
@@ -42,15 +42,20 @@ FindRules::FindRules()
void FindRules::loadFindRules()
{
std::vector paths;
- std::string filePath {Utils::FileSystem::getHomePath() + "/.emulationstation/custom_systems" +
- "/es_find_rules.xml"};
-
+ std::string filePath {Utils::FileSystem::getAppDataDirectory() +
+ "/custom_systems/es_find_rules.xml"};
if (Utils::FileSystem::exists(filePath)) {
paths.emplace_back(filePath);
LOG(LogInfo) << "Found custom find rules configuration file";
}
-#if defined(_WIN64)
+#if defined(__ANDROID__)
+ filePath = ResourceManager::getInstance().getResourcePath(":/systems/android/es_find_rules.xml",
+ false);
+#elif defined(__linux__)
+ filePath =
+ ResourceManager::getInstance().getResourcePath(":/systems/linux/es_find_rules.xml", false);
+#elif defined(_WIN64)
filePath = ResourceManager::getInstance().getResourcePath(":/systems/windows/es_find_rules.xml",
false);
#elif defined(__APPLE__)
@@ -61,12 +66,12 @@ void FindRules::loadFindRules()
ResourceManager::getInstance().getResourcePath(":/systems/unix/es_find_rules.xml", false);
#endif
- if (filePath == "" && paths.empty()) {
+ if (filePath.empty() && paths.empty()) {
LOG(LogWarning) << "No find rules configuration file found";
return;
}
- if (filePath != "")
+ if (!filePath.empty())
paths.emplace_back(filePath);
for (auto& path : paths) {
@@ -84,7 +89,6 @@ void FindRules::loadFindRules()
#else
const pugi::xml_parse_result& res {doc.load_file(path.c_str())};
#endif
-
if (!res) {
LOG(LogError) << "Couldn't parse es_find_rules.xml: " << res.description();
continue;
@@ -126,6 +130,9 @@ void FindRules::loadFindRules()
#if defined(_WIN64)
if (ruleType != "winregistrypath" && ruleType != "winregistryvalue" &&
ruleType != "systempath" && ruleType != "staticpath") {
+#elif defined(__ANDROID__)
+ if (ruleType != "androidpackage" && ruleType != "systempath" &&
+ ruleType != "staticpath") {
#else
if (ruleType != "systempath" && ruleType != "staticpath") {
#endif
@@ -145,6 +152,9 @@ void FindRules::loadFindRules()
emulatorRules.winRegistryPaths.emplace_back(entryValue);
else if (ruleType == "winregistryvalue")
emulatorRules.winRegistryValues.emplace_back(entryValue);
+#elif defined(__ANDROID__)
+ else if (ruleType == "androidpackage")
+ emulatorRules.androidPackages.emplace_back(entryValue);
#endif
}
}
@@ -154,6 +164,8 @@ void FindRules::loadFindRules()
#if defined(_WIN64)
emulatorRules.winRegistryPaths.clear();
emulatorRules.winRegistryValues.clear();
+#elif defined(__ANDROID__)
+ emulatorRules.androidPackages.clear();
#endif
}
@@ -838,9 +850,8 @@ bool SystemData::loadConfig()
void SystemData::loadSortingConfig()
{
const std::string sortSetting {Settings::getInstance()->getString("SystemsSorting")};
- const std::string customFilePath {Utils::FileSystem::getHomePath() +
- "/.emulationstation/custom_systems" +
- "/es_systems_sorting.xml"};
+ const std::string customFilePath {Utils::FileSystem::getAppDataDirectory() +
+ "/custom_systems/es_systems_sorting.xml"};
const bool customFileExists {Utils::FileSystem::exists(customFilePath)};
std::string path;
@@ -875,7 +886,7 @@ void SystemData::loadSortingConfig()
path = customFilePath;
}
- if (path == "") {
+ if (path.empty()) {
LOG(LogDebug) << "No systems sorting file loaded";
return;
}
@@ -947,8 +958,8 @@ std::vector SystemData::getConfigPath()
{
std::vector paths;
- const std::string& customSystemsDirectory {Utils::FileSystem::getHomePath() +
- "/.emulationstation/custom_systems"};
+ const std::string customSystemsDirectory {Utils::FileSystem::getAppDataDirectory() +
+ "/custom_systems"};
if (!Utils::FileSystem::exists(customSystemsDirectory)) {
LOG(LogInfo) << "Creating custom systems directory \"" << customSystemsDirectory << "\"...";
@@ -965,7 +976,11 @@ std::vector SystemData::getConfigPath()
paths.emplace_back(path);
}
-#if defined(_WIN64)
+#if defined(__ANDROID__)
+ path = ResourceManager::getInstance().getResourcePath(":/systems/android/es_systems.xml", true);
+#elif defined(__linux__)
+ path = ResourceManager::getInstance().getResourcePath(":/systems/linux/es_systems.xml", true);
+#elif defined(_WIN64)
path = ResourceManager::getInstance().getResourcePath(":/systems/windows/es_systems.xml", true);
#elif defined(__APPLE__)
path = ResourceManager::getInstance().getResourcePath(":/systems/macos/es_systems.xml", true);
@@ -1107,6 +1122,31 @@ bool SystemData::createSystemDirectories()
return (std::isspace(character) || character == ',');
}) != platform.cend()};
+ if (name.empty()) {
+ LOG(LogError)
+ << "A system in the es_systems.xml file has no name defined, skipping entry";
+ continue;
+ }
+ else if (fullname.empty() || path.empty() || extensions.empty() || commands.empty()) {
+ LOG(LogError) << "System \"" << name
+ << "\" is missing the fullname, path, "
+ "extension, or command tag, skipping entry";
+ continue;
+ }
+
+ if (commands.size() == 1 &&
+ Utils::String::toLower(commands.front()).find("placeholder") != std::string::npos) {
+ if (Settings::getInstance()->getBool("CreatePlaceholderSystemDirectories")) {
+ LOG(LogInfo) << "System \"" << name
+ << "\" is a placeholder but creating directory anyway as "
+ "CreatePlaceholderSystemDirectories is set to true";
+ }
+ else {
+ LOG(LogInfo) << "System \"" << name << "\" is a placeholder, skipping entry";
+ continue;
+ }
+ }
+
themeFolder = system.child("theme").text().as_string(name.c_str());
// Check that the %ROMPATH% variable is actually used for the path element.
@@ -1188,7 +1228,10 @@ bool SystemData::createSystemDirectories()
}
systemInfoFile << "Platform" << (multiplePlatforms ? "s" : "")
<< " (for scraping):" << std::endl;
- systemInfoFile << platform << std::endl << std::endl;
+ if (platform.empty())
+ systemInfoFile << "None defined" << std::endl << std::endl;
+ else
+ systemInfoFile << platform << std::endl << std::endl;
systemInfoFile << "Theme folder:" << std::endl;
systemInfoFile << themeFolder << std::endl;
systemInfoFile.close();
@@ -1296,8 +1339,8 @@ SystemData* SystemData::getPrev() const
std::string SystemData::getGamelistPath(bool forWrite) const
{
std::string filePath {mRootFolder->getPath() + "/gamelist.xml"};
- const std::string gamelistPath {Utils::FileSystem::getHomePath() +
- "/.emulationstation/gamelists/" + mName};
+ const std::string gamelistPath {Utils::FileSystem::getAppDataDirectory() + "/gamelists/" +
+ mName};
if (Utils::FileSystem::exists(filePath)) {
if (Settings::getInstance()->getBool("LegacyGamelistFileLocation")) {
@@ -1307,8 +1350,7 @@ std::string SystemData::getGamelistPath(bool forWrite) const
#if defined(_WIN64)
LOG(LogWarning) << "Found a gamelist.xml file in \""
<< Utils::String::replace(mRootFolder->getPath(), "/", "\\")
- << "\\\" which will not get loaded, move it to \""
- << Utils::String::replace(gamelistPath, "/", "\\")
+ << "\\\" which will not get loaded, move it to \"" << gamelistPath
<< "\\\" or otherwise delete it";
#else
LOG(LogWarning) << "Found a gamelist.xml file in \"" << mRootFolder->getPath()
diff --git a/es-app/src/SystemData.h b/es-app/src/SystemData.h
index c72889b56..53b636213 100644
--- a/es-app/src/SystemData.h
+++ b/es-app/src/SystemData.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// SystemData.h
//
// Provides data structures for the game systems and populates and indexes them based
@@ -44,6 +44,8 @@ private:
#if defined(_WIN64)
std::vector winRegistryPaths;
std::vector winRegistryValues;
+#elif defined(__ANDROID__)
+ std::vector androidPackages;
#endif
std::vector systemPaths;
std::vector staticPaths;
diff --git a/es-app/src/UIModeController.cpp b/es-app/src/UIModeController.cpp
index 38af8c110..7ce20065c 100644
--- a/es-app/src/UIModeController.cpp
+++ b/es-app/src/UIModeController.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// UIModeController.cpp
//
// Handling of application user interface modes (full, kiosk and kid).
@@ -127,13 +127,13 @@ std::string UIModeController::getFormattedPassKeyStr()
std::string symbolX;
std::string symbolY;
- if (controllerType == "snes") {
+ if (Settings::getInstance()->getBool("InputSwapButtons") || controllerType == "snes") {
symbolA = "B";
symbolB = "A";
symbolX = "Y";
symbolY = "X";
}
- else if (controllerType == "ps4" || controllerType == "ps5") {
+ else if (controllerType == "ps123" || controllerType == "ps4" || controllerType == "ps5") {
#if defined(_MSC_VER) // MSVC compiler.
// These symbols are far from perfect but you can at least understand what
// they are supposed to depict.
diff --git a/es-app/src/UIModeController.h b/es-app/src/UIModeController.h
index ccb7e78db..22d22133e 100644
--- a/es-app/src/UIModeController.h
+++ b/es-app/src/UIModeController.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// UIModeController.h
//
// Handling of application user interface modes (full, kiosk and kid).
diff --git a/es-app/src/VolumeControl.cpp b/es-app/src/VolumeControl.cpp
index e3fd447a2..3bf54b914 100644
--- a/es-app/src/VolumeControl.cpp
+++ b/es-app/src/VolumeControl.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// VolumeControl.cpp
//
// Controls system audio volume.
@@ -15,14 +15,14 @@
#include
#endif
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
std::string VolumeControl::mixerName = "Master";
std::string VolumeControl::mixerCard = "default";
#endif
VolumeControl::VolumeControl()
// clang-format off
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
: mixerIndex {0}
, mixerHandle {nullptr}
, mixerElem {nullptr}
@@ -39,7 +39,7 @@ VolumeControl::VolumeControl()
VolumeControl::~VolumeControl()
{
deinit();
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
snd_config_update_free_global();
#endif
}
@@ -48,7 +48,7 @@ void VolumeControl::init()
{
// Initialize audio mixer interface.
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
// Try to open mixer device.
if (mixerHandle == nullptr) {
snd_mixer_selem_id_alloca(&mixerSelemId);
@@ -139,7 +139,7 @@ void VolumeControl::deinit()
{
// Deinitialize audio mixer interface.
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
if (mixerHandle != nullptr) {
snd_mixer_detach(mixerHandle, mixerCard.c_str());
snd_mixer_free(mixerHandle);
@@ -160,7 +160,7 @@ int VolumeControl::getVolume() const
{
int volume = 0;
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
if (mixerElem != nullptr) {
// Get volume range.
long minVolume;
@@ -204,7 +204,7 @@ void VolumeControl::setVolume(int volume)
{
volume = glm::clamp(volume, 0, 100);
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
if (mixerElem != nullptr) {
// Get volume range.
long minVolume;
diff --git a/es-app/src/VolumeControl.h b/es-app/src/VolumeControl.h
index 8a002e569..e0526c34b 100644
--- a/es-app/src/VolumeControl.h
+++ b/es-app/src/VolumeControl.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// VolumeControl.h
//
// Controls system audio volume.
@@ -11,7 +11,7 @@
#include
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
#include
#include
#include
@@ -33,7 +33,7 @@ public:
int getVolume() const;
void setVolume(int volume);
-#if defined(__linux__)
+#if defined(__linux__) && !defined(__ANDROID__)
static std::string mixerName;
static std::string mixerCard;
int mixerIndex;
diff --git a/es-app/src/guis/GuiAlternativeEmulators.cpp b/es-app/src/guis/GuiAlternativeEmulators.cpp
index ff504845c..264fd8622 100644
--- a/es-app/src/guis/GuiAlternativeEmulators.cpp
+++ b/es-app/src/guis/GuiAlternativeEmulators.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiAlternativeEmulators.cpp
//
// User interface to select between alternative emulators per system
diff --git a/es-app/src/guis/GuiAlternativeEmulators.h b/es-app/src/guis/GuiAlternativeEmulators.h
index 9ac0bed92..c4b5c68f0 100644
--- a/es-app/src/guis/GuiAlternativeEmulators.h
+++ b/es-app/src/guis/GuiAlternativeEmulators.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiAlternativeEmulators.h
//
// User interface to select between alternative emulators per system
diff --git a/es-app/src/guis/GuiApplicationUpdater.cpp b/es-app/src/guis/GuiApplicationUpdater.cpp
index cad6fca54..39a47e489 100644
--- a/es-app/src/guis/GuiApplicationUpdater.cpp
+++ b/es-app/src/guis/GuiApplicationUpdater.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiApplicationUpdater.cpp
//
// Installs application updates.
@@ -9,7 +9,7 @@
#include "guis/GuiApplicationUpdater.h"
-#include "EmulationStation.h"
+#include "ApplicationVersion.h"
#include "guis/GuiTextEditKeyboardPopup.h"
#include "guis/GuiTextEditPopup.h"
#include "utils/PlatformUtil.h"
diff --git a/es-app/src/guis/GuiApplicationUpdater.h b/es-app/src/guis/GuiApplicationUpdater.h
index ec6dcb82b..f410052b5 100644
--- a/es-app/src/guis/GuiApplicationUpdater.h
+++ b/es-app/src/guis/GuiApplicationUpdater.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiApplicationUpdater.h
//
// Installs application updates.
diff --git a/es-app/src/guis/GuiCollectionSystemsOptions.cpp b/es-app/src/guis/GuiCollectionSystemsOptions.cpp
index 675ebe266..9c356c97a 100644
--- a/es-app/src/guis/GuiCollectionSystemsOptions.cpp
+++ b/es-app/src/guis/GuiCollectionSystemsOptions.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiCollectionSystemsOptions.cpp
//
// User interface for the game collection settings.
diff --git a/es-app/src/guis/GuiCollectionSystemsOptions.h b/es-app/src/guis/GuiCollectionSystemsOptions.h
index 25317ddbf..2cf478989 100644
--- a/es-app/src/guis/GuiCollectionSystemsOptions.h
+++ b/es-app/src/guis/GuiCollectionSystemsOptions.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiCollectionSystemsOptions.h
//
// User interface for the game collection settings.
diff --git a/es-app/src/guis/GuiGamelistFilter.cpp b/es-app/src/guis/GuiGamelistFilter.cpp
index fad712ec7..3964c36a0 100644
--- a/es-app/src/guis/GuiGamelistFilter.cpp
+++ b/es-app/src/guis/GuiGamelistFilter.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiGamelistFilter.cpp
//
// User interface for the gamelist filters.
diff --git a/es-app/src/guis/GuiGamelistFilter.h b/es-app/src/guis/GuiGamelistFilter.h
index 4ba3f92a2..5ed1a1bb9 100644
--- a/es-app/src/guis/GuiGamelistFilter.h
+++ b/es-app/src/guis/GuiGamelistFilter.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiGamelistFilter.h
//
// User interface for the gamelist filters.
diff --git a/es-app/src/guis/GuiGamelistOptions.cpp b/es-app/src/guis/GuiGamelistOptions.cpp
index e901779b4..e7c1e6a1e 100644
--- a/es-app/src/guis/GuiGamelistOptions.cpp
+++ b/es-app/src/guis/GuiGamelistOptions.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiGamelistOptions.cpp
//
// Gamelist options menu for the 'Jump to...' quick selector,
diff --git a/es-app/src/guis/GuiGamelistOptions.h b/es-app/src/guis/GuiGamelistOptions.h
index a8292d91f..6cc01f9ba 100644
--- a/es-app/src/guis/GuiGamelistOptions.h
+++ b/es-app/src/guis/GuiGamelistOptions.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiGamelistOptions.h
//
// Gamelist options menu for the 'Jump to...' quick selector,
diff --git a/es-app/src/guis/GuiLaunchScreen.cpp b/es-app/src/guis/GuiLaunchScreen.cpp
index 3c165b539..d9fc11f68 100644
--- a/es-app/src/guis/GuiLaunchScreen.cpp
+++ b/es-app/src/guis/GuiLaunchScreen.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiLaunchScreen.cpp
//
// Screen shown when launching a game.
diff --git a/es-app/src/guis/GuiLaunchScreen.h b/es-app/src/guis/GuiLaunchScreen.h
index af24f4329..7f6590a50 100644
--- a/es-app/src/guis/GuiLaunchScreen.h
+++ b/es-app/src/guis/GuiLaunchScreen.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiLaunchScreen.h
//
// Screen shown when launching a game.
diff --git a/es-app/src/guis/GuiMediaViewerOptions.cpp b/es-app/src/guis/GuiMediaViewerOptions.cpp
index 299471ed5..c6ba51c5b 100644
--- a/es-app/src/guis/GuiMediaViewerOptions.cpp
+++ b/es-app/src/guis/GuiMediaViewerOptions.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiMediaViewerOptions.cpp
//
// User interface for the media viewer options.
diff --git a/es-app/src/guis/GuiMediaViewerOptions.h b/es-app/src/guis/GuiMediaViewerOptions.h
index 686c6ea12..dda7c362d 100644
--- a/es-app/src/guis/GuiMediaViewerOptions.h
+++ b/es-app/src/guis/GuiMediaViewerOptions.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiMediaViewerOptions.h
//
// User interface for the media viewer options.
diff --git a/es-app/src/guis/GuiMenu.cpp b/es-app/src/guis/GuiMenu.cpp
index d73c94e6b..65eb1da6b 100644
--- a/es-app/src/guis/GuiMenu.cpp
+++ b/es-app/src/guis/GuiMenu.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiMenu.cpp
//
// Main menu.
@@ -14,8 +14,8 @@
#include
#endif
+#include "ApplicationVersion.h"
#include "CollectionSystemsManager.h"
-#include "EmulationStation.h"
#include "FileFilterIndex.h"
#include "FileSorts.h"
#include "Scripting.h"
@@ -38,6 +38,10 @@
#include "guis/GuiThemeDownloader.h"
#include "utils/PlatformUtil.h"
+#if defined(__ANDROID__)
+#include "InputOverlay.h"
+#endif
+
#include
#include
@@ -164,12 +168,12 @@ void GuiMenu::openUIOptions()
Scripting::fireEvent("theme-changed", theme->getSelected(),
Settings::getInstance()->getString("Theme"));
// Handle the situation where the previously selected theme has been deleted
- // using the theme downloader. In this case attempt to fall back to slate-es-de
+ // using the theme downloader. In this case attempt to fall back to linear-es-de
// and if this theme doesn't exist then select the first available one.
auto themes = ThemeData::getThemes();
if (themes.find(theme->getSelected()) == themes.end()) {
- if (themes.find("slate-es-de") != themes.end())
- Settings::getInstance()->setString("Theme", "slate-es-de");
+ if (themes.find("linear-es-de") != themes.end())
+ Settings::getInstance()->setString("Theme", "linear-es-de");
else
Settings::getInstance()->setString("Theme", themes.begin()->first);
}
@@ -288,6 +292,47 @@ void GuiMenu::openUIOptions()
themeColorSchemesFunc(Settings::getInstance()->getString("Theme"),
Settings::getInstance()->getString("ThemeColorScheme"));
+ // Theme font sizes.
+ auto themeFontSize = std::make_shared>(
+ getHelpStyle(), "THEME FONT SIZE", false);
+ s->addWithLabel("THEME FONT SIZE", themeFontSize);
+ s->addSaveFunc([themeFontSize, s] {
+ if (themeFontSize->getSelected() != Settings::getInstance()->getString("ThemeFontSize")) {
+ Settings::getInstance()->setString("ThemeFontSize", themeFontSize->getSelected());
+ s->setNeedsSaving();
+ s->setNeedsReloading();
+ s->setInvalidateCachedBackground();
+ }
+ });
+
+ auto themeFontSizeFunc = [=](const std::string& selectedTheme,
+ const std::string& selectedFontSize) {
+ std::map::const_iterator
+ currentSet {themes.find(selectedTheme)};
+ if (currentSet == themes.cend())
+ return;
+ // We need to recreate the OptionListComponent entries.
+ themeFontSize->clearEntries();
+ if (currentSet->second.capabilities.fontSizes.size() > 0) {
+ for (auto& fontSize : currentSet->second.capabilities.fontSizes)
+ themeFontSize->add(ThemeData::getFontSizeLabel(fontSize), fontSize,
+ fontSize == selectedFontSize);
+ if (themeFontSize->getSelectedObjects().size() == 0)
+ themeFontSize->selectEntry(0);
+ }
+ else {
+ themeFontSize->add("None defined", "none", true);
+ themeFontSize->setEnabled(false);
+ themeFontSize->setOpacity(DISABLED_OPACITY);
+ themeFontSize->getParent()
+ ->getChild(themeFontSize->getChildIndex() - 1)
+ ->setOpacity(DISABLED_OPACITY);
+ }
+ };
+
+ themeFontSizeFunc(Settings::getInstance()->getString("Theme"),
+ Settings::getInstance()->getString("ThemeFontSize"));
+
// Theme aspect ratios.
auto themeAspectRatio = std::make_shared>(
getHelpStyle(), "THEME ASPECT RATIO", false);
@@ -845,6 +890,12 @@ void GuiMenu::openUIOptions()
Settings::getInstance()->setBool("VirtualKeyboard", virtualKeyboard->getState());
s->setNeedsSaving();
s->setInvalidateCachedBackground();
+#if defined(__ANDROID__)
+ if (Settings::getInstance()->getBool("VirtualKeyboard"))
+ SDL_SetHint(SDL_HINT_ENABLE_SCREEN_KEYBOARD, "0");
+ else
+ SDL_SetHint(SDL_HINT_ENABLE_SCREEN_KEYBOARD, "1");
+#endif
}
});
@@ -891,6 +942,7 @@ void GuiMenu::openUIOptions()
if (!firstRun) {
themeVariantsFunc(themeName, themeVariant->getSelected());
themeColorSchemesFunc(themeName, themeColorScheme->getSelected());
+ themeFontSizeFunc(themeName, themeFontSize->getSelected());
themeAspectRatiosFunc(themeName, themeAspectRatio->getSelected());
themeTransitionsFunc(themeName, themeTransitions->getSelected());
}
@@ -927,6 +979,20 @@ void GuiMenu::openUIOptions()
->getChild(themeColorScheme->getChildIndex() - 1)
->setOpacity(DISABLED_OPACITY);
}
+ if (selectedTheme->second.capabilities.fontSizes.size() > 0) {
+ themeFontSize->setEnabled(true);
+ themeFontSize->setOpacity(1.0f);
+ themeFontSize->getParent()
+ ->getChild(themeFontSize->getChildIndex() - 1)
+ ->setOpacity(1.0f);
+ }
+ else {
+ themeFontSize->setEnabled(false);
+ themeFontSize->setOpacity(DISABLED_OPACITY);
+ themeFontSize->getParent()
+ ->getChild(themeFontSize->getChildIndex() - 1)
+ ->setOpacity(DISABLED_OPACITY);
+ }
if (selectedTheme->second.capabilities.aspectRatios.size() > 0) {
themeAspectRatio->setEnabled(true);
themeAspectRatio->setOpacity(1.0f);
@@ -954,9 +1020,9 @@ void GuiMenu::openSoundOptions()
{
auto s = new GuiSettings("SOUND SETTINGS");
-// TODO: Hide the volume slider on macOS and BSD Unix until the volume control logic has been
-// implemented for these operating systems.
-#if !defined(__APPLE__) && !defined(__FreeBSD__) && !defined(__OpenBSD__) && !defined(__NetBSD__)
+// TODO: Implement system volume support for macOS and Android.
+#if !defined(__APPLE__) && !defined(__ANDROID__) && !defined(__FreeBSD__) && \
+ !defined(__OpenBSD__) && !defined(__NetBSD__)
// System volume.
// The reason to create the VolumeControl object every time instead of making it a singleton
// is that this is the easiest way to detect new default audio devices or changes to the
@@ -1090,6 +1156,166 @@ void GuiMenu::openInputDeviceOptions()
}
});
+#if defined(__ANDROID__)
+ // Touch overlay size.
+ auto touchOverlaySize = std::make_shared>(
+ getHelpStyle(), "TOUCH OVERLAY SIZE", false);
+ std::string selectedOverlaySize {Settings::getInstance()->getString("InputTouchOverlaySize")};
+ touchOverlaySize->add("MEDIUM", "medium", selectedOverlaySize == "medium");
+ touchOverlaySize->add("LARGE", "large", selectedOverlaySize == "large");
+ touchOverlaySize->add("SMALL", "small", selectedOverlaySize == "small");
+ touchOverlaySize->add("EXTRA SMALL", "x-small", selectedOverlaySize == "x-small");
+ // If there are no objects returned, then there must be a manually modified entry in the
+ // configuration file. Simply set the overlay size to "medium" in this case.
+ if (touchOverlaySize->getSelectedObjects().size() == 0)
+ touchOverlaySize->selectEntry(0);
+ s->addWithLabel("TOUCH OVERLAY SIZE", touchOverlaySize);
+ s->addSaveFunc([touchOverlaySize, s] {
+ if (touchOverlaySize->getSelected() !=
+ Settings::getInstance()->getString("InputTouchOverlaySize")) {
+ Settings::getInstance()->setString("InputTouchOverlaySize",
+ touchOverlaySize->getSelected());
+ s->setNeedsSaving();
+ InputOverlay::getInstance().createButtons();
+ }
+ });
+
+ // Touch overlay opacity.
+ auto touchOverlayOpacity = std::make_shared>(
+ getHelpStyle(), "TOUCH OVERLAY OPACITY", false);
+ std::string selectedOverlayOpacity {
+ Settings::getInstance()->getString("InputTouchOverlayOpacity")};
+ touchOverlayOpacity->add("NORMAL", "normal", selectedOverlayOpacity == "normal");
+ touchOverlayOpacity->add("LOW", "low", selectedOverlayOpacity == "low");
+ touchOverlayOpacity->add("VERY LOW", "verylow", selectedOverlayOpacity == "verylow");
+ // If there are no objects returned, then there must be a manually modified entry in the
+ // configuration file. Simply set the overlay opacity to "normal" in this case.
+ if (touchOverlayOpacity->getSelectedObjects().size() == 0)
+ touchOverlayOpacity->selectEntry(0);
+ s->addWithLabel("TOUCH OVERLAY OPACITY", touchOverlayOpacity);
+ s->addSaveFunc([touchOverlayOpacity, s] {
+ if (touchOverlayOpacity->getSelected() !=
+ Settings::getInstance()->getString("InputTouchOverlayOpacity")) {
+ Settings::getInstance()->setString("InputTouchOverlayOpacity",
+ touchOverlayOpacity->getSelected());
+ s->setNeedsSaving();
+ InputOverlay::getInstance().createButtons();
+ }
+ });
+
+ // Touch overlay fade-out timer.
+ auto touchOverlayFadeTime = std::make_shared(0.0f, 20.0f, 1.0f, "s");
+ touchOverlayFadeTime->setValue(
+ static_cast(Settings::getInstance()->getInt("InputTouchOverlayFadeTime")));
+ s->addWithLabel("TOUCH OVERLAY FADE-OUT TIME", touchOverlayFadeTime);
+ s->addSaveFunc([touchOverlayFadeTime, s] {
+ if (touchOverlayFadeTime->getValue() !=
+ static_cast(Settings::getInstance()->getInt("InputTouchOverlayFadeTime"))) {
+ Settings::getInstance()->setInt("InputTouchOverlayFadeTime",
+ static_cast(touchOverlayFadeTime->getValue()));
+ InputOverlay::getInstance().resetFadeTimer();
+ s->setNeedsSaving();
+ }
+ });
+
+ // Whether to enable the touch overlay.
+ auto inputTouchOverlay = std::make_shared();
+ inputTouchOverlay->setState(Settings::getInstance()->getBool("InputTouchOverlay"));
+ s->addWithLabel("ENABLE TOUCH OVERLAY", inputTouchOverlay);
+ s->addSaveFunc([inputTouchOverlay, s] {
+ if (Settings::getInstance()->getBool("InputTouchOverlay") !=
+ inputTouchOverlay->getState()) {
+ Settings::getInstance()->setBool("InputTouchOverlay", inputTouchOverlay->getState());
+ if (Settings::getInstance()->getBool("InputTouchOverlay"))
+ InputOverlay::getInstance().createButtons();
+ else
+ InputOverlay::getInstance().clearButtons();
+ s->setNeedsSaving();
+ }
+ });
+
+ if (!Settings::getInstance()->getBool("InputTouchOverlay")) {
+ touchOverlaySize->setEnabled(false);
+ touchOverlaySize->setOpacity(DISABLED_OPACITY);
+ touchOverlaySize->getParent()
+ ->getChild(touchOverlaySize->getChildIndex() - 1)
+ ->setOpacity(DISABLED_OPACITY);
+
+ touchOverlayOpacity->setEnabled(false);
+ touchOverlayOpacity->setOpacity(DISABLED_OPACITY);
+ touchOverlayOpacity->getParent()
+ ->getChild(touchOverlayOpacity->getChildIndex() - 1)
+ ->setOpacity(DISABLED_OPACITY);
+
+ touchOverlayFadeTime->setEnabled(false);
+ touchOverlayFadeTime->setOpacity(DISABLED_OPACITY);
+ touchOverlayFadeTime->getParent()
+ ->getChild(touchOverlayFadeTime->getChildIndex() - 1)
+ ->setOpacity(DISABLED_OPACITY);
+ }
+
+ auto inputTouchOverlayCallback = [this, inputTouchOverlay, touchOverlaySize,
+ touchOverlayOpacity, touchOverlayFadeTime]() {
+ if (!inputTouchOverlay->getState()) {
+ const std::string message {
+ "DON'T DISABLE THE TOUCH OVERLAY UNLESS YOU ARE USING A CONTROLLER OR YOU WILL "
+ "LOCK YOURSELF OUT OF THE APP. IF THIS HAPPENS YOU WILL NEED TO TEMPORARILY "
+ "PLUG IN A CONTROLLER OR A KEYBOARD TO ENABLE THIS SETTING AGAIN, OR YOU "
+ "COULD CLEAR THE ES-DE STORAGE IN THE ANDROID APP SETTINGS TO FORCE THE "
+ "CONFIGURATOR TO RUN ON NEXT STARTUP"};
+
+ Window* window {mWindow};
+ window->pushGui(
+ new GuiMsgBox(getHelpStyle(), message, "OK", nullptr, "", nullptr, "", nullptr,
+ nullptr, true, true,
+ (mRenderer->getIsVerticalOrientation() ?
+ 0.84f :
+ 0.54f * (1.778f / mRenderer->getScreenAspectRatio()))));
+ }
+
+ if (touchOverlaySize->getEnabled()) {
+ touchOverlaySize->setEnabled(false);
+ touchOverlaySize->setOpacity(DISABLED_OPACITY);
+ touchOverlaySize->getParent()
+ ->getChild(touchOverlaySize->getChildIndex() - 1)
+ ->setOpacity(DISABLED_OPACITY);
+
+ touchOverlayOpacity->setEnabled(false);
+ touchOverlayOpacity->setOpacity(DISABLED_OPACITY);
+ touchOverlayOpacity->getParent()
+ ->getChild(touchOverlayOpacity->getChildIndex() - 1)
+ ->setOpacity(DISABLED_OPACITY);
+
+ touchOverlayFadeTime->setEnabled(false);
+ touchOverlayFadeTime->setOpacity(DISABLED_OPACITY);
+ touchOverlayFadeTime->getParent()
+ ->getChild(touchOverlayFadeTime->getChildIndex() - 1)
+ ->setOpacity(DISABLED_OPACITY);
+ }
+ else {
+ touchOverlaySize->setEnabled(true);
+ touchOverlaySize->setOpacity(1.0f);
+ touchOverlaySize->getParent()
+ ->getChild(touchOverlaySize->getChildIndex() - 1)
+ ->setOpacity(1.0f);
+
+ touchOverlayOpacity->setEnabled(true);
+ touchOverlayOpacity->setOpacity(1.0f);
+ touchOverlayOpacity->getParent()
+ ->getChild(touchOverlayOpacity->getChildIndex() - 1)
+ ->setOpacity(1.0f);
+
+ touchOverlayFadeTime->setEnabled(true);
+ touchOverlayFadeTime->setOpacity(1.0f);
+ touchOverlayFadeTime->getParent()
+ ->getChild(touchOverlayFadeTime->getChildIndex() - 1)
+ ->setOpacity(1.0f);
+ }
+ };
+
+ inputTouchOverlay->setCallback(inputTouchOverlayCallback);
+#endif
+
// Whether to only accept input from the first controller.
auto inputOnlyFirstController = std::make_shared();
inputOnlyFirstController->setState(
@@ -1104,6 +1330,17 @@ void GuiMenu::openInputDeviceOptions()
}
});
+ // Whether to swap the A/B and X/Y buttons.
+ auto inputSwapButtons = std::make_shared();
+ inputSwapButtons->setState(Settings::getInstance()->getBool("InputSwapButtons"));
+ s->addWithLabel("SWAP THE A/B AND X/Y BUTTONS", inputSwapButtons);
+ s->addSaveFunc([inputSwapButtons, s] {
+ if (Settings::getInstance()->getBool("InputSwapButtons") != inputSwapButtons->getState()) {
+ Settings::getInstance()->setBool("InputSwapButtons", inputSwapButtons->getState());
+ s->setNeedsSaving();
+ }
+ });
+
// Whether to ignore keyboard input (except the quit shortcut).
auto inputIgnoreKeyboard = std::make_shared();
inputIgnoreKeyboard->setState(Settings::getInstance()->getBool("InputIgnoreKeyboard"));
@@ -1185,7 +1422,8 @@ void GuiMenu::openOtherOptions()
rowMediaDir.addElement(bracketMediaDirectory, false);
std::string titleMediaDir {"ENTER GAME MEDIA DIRECTORY"};
std::string mediaDirectoryStaticText {"Default directory:"};
- std::string defaultDirectoryText {"~/.emulationstation/downloaded_media/"};
+ std::string defaultDirectoryText {Utils::FileSystem::getAppDataDirectory() +
+ "/downloaded_media"};
std::string initValueMediaDir {Settings::getInstance()->getString("MediaDirectory")};
bool multiLineMediaDir {false};
auto updateValMediaDir = [this](const std::string& newVal) {
@@ -1417,6 +1655,7 @@ void GuiMenu::openOtherOptions()
});
#endif
+#if !defined(__ANDROID__)
// Run ES in the background when a game has been launched.
auto runInBackground = std::make_shared();
runInBackground->setState(Settings::getInstance()->getBool("RunInBackground"));
@@ -1427,6 +1666,7 @@ void GuiMenu::openOtherOptions()
s->setNeedsSaving();
}
});
+#endif
#if defined(VIDEO_HW_DECODING)
// Whether to enable hardware decoding for the FFmpeg video player.
@@ -1538,7 +1778,7 @@ void GuiMenu::openOtherOptions()
}
});
-#if defined(__unix__)
+#if defined(__unix__) && !defined(__ANDROID__)
// Whether to disable desktop composition.
auto disableComposition = std::make_shared();
disableComposition->setState(Settings::getInstance()->getBool("DisableComposition"));
@@ -1612,7 +1852,7 @@ void GuiMenu::openOtherOptions()
// macOS requires root privileges to reboot and power off so it doesn't make much
// sense to enable this setting and menu entry for that operating system.
-#if !defined(__APPLE__)
+#if !defined(__APPLE__) && !defined(__ANDROID__)
// Whether to show the quit menu with the options to reboot and shutdown the computer.
auto showQuitMenu = std::make_shared();
showQuitMenu->setState(Settings::getInstance()->getBool("ShowQuitMenu"));
@@ -1661,12 +1901,23 @@ void GuiMenu::openUtilities()
ComponentListRow row;
+#if defined(ANDROID_LITE_RELEASE)
+ auto orphanedDataCleanup =
+ std::make_shared("ORPHANED DATA CLEANUP (FULL VERSION ONLY)",
+ Font::get(FONT_SIZE_MEDIUM), mMenuColorPrimary);
+ orphanedDataCleanup->setOpacity(DISABLED_OPACITY);
+ row.addElement(orphanedDataCleanup, true);
+ auto orphanedDataCleanupArrow = mMenu.makeArrow();
+ orphanedDataCleanupArrow->setOpacity(DISABLED_OPACITY);
+ row.addElement(orphanedDataCleanupArrow, false);
+#else
row.addElement(std::make_shared("ORPHANED DATA CLEANUP",
Font::get(FONT_SIZE_MEDIUM), mMenuColorPrimary),
true);
row.addElement(mMenu.makeArrow(), false);
row.makeAcceptInputHandler(std::bind(
[this] { mWindow->pushGui(new GuiOrphanedDataCleanup([&]() { close(true); })); }));
+#endif
s->addRow(row);
row.elements.clear();
@@ -1764,7 +2015,11 @@ void GuiMenu::openUtilities()
void GuiMenu::openQuitMenu()
{
+#if defined(__APPLE__) || defined(__ANDROID__)
+ if (true) {
+#else
if (!Settings::getInstance()->getBool("ShowQuitMenu")) {
+#endif
mWindow->pushGui(new GuiMsgBox(
this->getHelpStyle(), "REALLY QUIT?", "YES",
[this] {
@@ -1790,8 +2045,8 @@ void GuiMenu::openQuitMenu()
},
"NO", nullptr));
});
- auto quitText = std::make_shared(
- "QUIT RETRODECK", Font::get(FONT_SIZE_MEDIUM), mMenuColorPrimary);
+ auto quitText = std::make_shared("QUIT RETRODECK", Font::get(FONT_SIZE_MEDIUM),
+ mMenuColorPrimary);
quitText->setSelectable(true);
row.addElement(quitText, true);
s->addRow(row);
@@ -1840,11 +2095,17 @@ void GuiMenu::addVersionInfo()
mVersion.setFont(Font::get(FONT_SIZE_SMALL));
mVersion.setColor(mMenuColorTertiary);
+#if defined(ANDROID_LITE_RELEASE)
+ const std::string applicationName {"ES-DE LITE"};
+#else
+ const std::string applicationName {"ES-DE"};
+#endif
+
#if defined(IS_PRERELEASE)
- mVersion.setText("EMULATIONSTATION-DE V" + Utils::String::toUpper(PROGRAM_VERSION_STRING) +
+ mVersion.setText(applicationName + " V" + Utils::String::toUpper(PROGRAM_VERSION_STRING) +
" (Built " + __DATE__ + ")");
#else
- mVersion.setText("EMULATIONSTATION-DE V" + Utils::String::toUpper(PROGRAM_VERSION_STRING));
+ mVersion.setText(applicationName + " V" + Utils::String::toUpper(PROGRAM_VERSION_STRING));
#endif
mVersion.setHorizontalAlignment(ALIGN_CENTER);
diff --git a/es-app/src/guis/GuiMenu.h b/es-app/src/guis/GuiMenu.h
index e41cd9801..dd9b42d8d 100644
--- a/es-app/src/guis/GuiMenu.h
+++ b/es-app/src/guis/GuiMenu.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiMenu.h
//
// Main menu.
diff --git a/es-app/src/guis/GuiMetaDataEd.cpp b/es-app/src/guis/GuiMetaDataEd.cpp
index b302cd9b0..fffbed815 100644
--- a/es-app/src/guis/GuiMetaDataEd.cpp
+++ b/es-app/src/guis/GuiMetaDataEd.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiMetaDataEd.cpp
//
// Game metadata edit user interface.
diff --git a/es-app/src/guis/GuiMetaDataEd.h b/es-app/src/guis/GuiMetaDataEd.h
index ca401ba46..f90410f08 100644
--- a/es-app/src/guis/GuiMetaDataEd.h
+++ b/es-app/src/guis/GuiMetaDataEd.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiMetaDataEd.h
//
// Game metadata edit user interface.
diff --git a/es-app/src/guis/GuiOfflineGenerator.cpp b/es-app/src/guis/GuiOfflineGenerator.cpp
index f90cf8f81..98cde683d 100644
--- a/es-app/src/guis/GuiOfflineGenerator.cpp
+++ b/es-app/src/guis/GuiOfflineGenerator.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiOfflineGenerator.cpp
//
// User interface for the miximage offline generator.
diff --git a/es-app/src/guis/GuiOfflineGenerator.h b/es-app/src/guis/GuiOfflineGenerator.h
index ff65e2dfc..f1dbd4174 100644
--- a/es-app/src/guis/GuiOfflineGenerator.h
+++ b/es-app/src/guis/GuiOfflineGenerator.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiOfflineGenerator.h
//
// User interface for the miximage offline generator.
diff --git a/es-app/src/guis/GuiOrphanedDataCleanup.cpp b/es-app/src/guis/GuiOrphanedDataCleanup.cpp
index 7279826f9..5281e2ad3 100644
--- a/es-app/src/guis/GuiOrphanedDataCleanup.cpp
+++ b/es-app/src/guis/GuiOrphanedDataCleanup.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE Frontend
// GuiOrphanedDataCleanup.cpp
//
// Removes orphaned game media, gamelist.xml entries and custom collections entries.
@@ -39,7 +39,7 @@ GuiOrphanedDataCleanup::GuiOrphanedDataCleanup(std::function reloadCallb
addChild(&mBackground);
addChild(&mGrid);
-#if defined(_WIN64) || defined(__APPLE__)
+#if defined(_WIN64) || defined(__APPLE__) || defined(__ANDROID__)
// Although macOS may have filesystem case-sensitivity enabled it's rare and in worst case
// this will just leave some extra media files on the filesystem.
mCaseSensitiveFilesystem = false;
diff --git a/es-app/src/guis/GuiOrphanedDataCleanup.h b/es-app/src/guis/GuiOrphanedDataCleanup.h
index 6523da643..0170868b5 100644
--- a/es-app/src/guis/GuiOrphanedDataCleanup.h
+++ b/es-app/src/guis/GuiOrphanedDataCleanup.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE Frontend
// GuiOrphanedDataCleanup.h
//
// Removes orphaned game media, gamelist.xml entries and custom collections entries.
diff --git a/es-app/src/guis/GuiScraperMenu.cpp b/es-app/src/guis/GuiScraperMenu.cpp
index 2e5dc4036..5d3974bf4 100644
--- a/es-app/src/guis/GuiScraperMenu.cpp
+++ b/es-app/src/guis/GuiScraperMenu.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScraperMenu.cpp
//
// Game media scraper, including settings as well as the scraping start button.
@@ -950,20 +950,6 @@ void GuiScraperMenu::openOtherOptions()
}
});
- // Halt scraping on invalid media files.
- auto scraperHaltOnInvalidMedia = std::make_shared();
- scraperHaltOnInvalidMedia->setState(
- Settings::getInstance()->getBool("ScraperHaltOnInvalidMedia"));
- s->addWithLabel("HALT ON INVALID MEDIA FILES", scraperHaltOnInvalidMedia);
- s->addSaveFunc([scraperHaltOnInvalidMedia, s] {
- if (scraperHaltOnInvalidMedia->getState() !=
- Settings::getInstance()->getBool("ScraperHaltOnInvalidMedia")) {
- Settings::getInstance()->setBool("ScraperHaltOnInvalidMedia",
- scraperHaltOnInvalidMedia->getState());
- s->setNeedsSaving();
- }
- });
-
// Search using file hashes for non-interactive mode.
auto scraperSearchFileHash = std::make_shared();
scraperSearchFileHash->setState(Settings::getInstance()->getBool("ScraperSearchFileHash"));
diff --git a/es-app/src/guis/GuiScraperMenu.h b/es-app/src/guis/GuiScraperMenu.h
index 096adffaf..4b2f5d717 100644
--- a/es-app/src/guis/GuiScraperMenu.h
+++ b/es-app/src/guis/GuiScraperMenu.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScraperMenu.h
//
// Game media scraper, including settings as well as the scraping start button.
diff --git a/es-app/src/guis/GuiScraperMulti.cpp b/es-app/src/guis/GuiScraperMulti.cpp
index db6aa0aa6..72a42e6e7 100644
--- a/es-app/src/guis/GuiScraperMulti.cpp
+++ b/es-app/src/guis/GuiScraperMulti.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScraperMulti.cpp
//
// Multiple game scraping user interface.
diff --git a/es-app/src/guis/GuiScraperMulti.h b/es-app/src/guis/GuiScraperMulti.h
index 1cb8ac4ad..ae0eadf14 100644
--- a/es-app/src/guis/GuiScraperMulti.h
+++ b/es-app/src/guis/GuiScraperMulti.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScraperMulti.h
//
// Multiple game scraping user interface.
diff --git a/es-app/src/guis/GuiScraperSearch.cpp b/es-app/src/guis/GuiScraperSearch.cpp
index 694b87f0d..905626eb4 100644
--- a/es-app/src/guis/GuiScraperSearch.cpp
+++ b/es-app/src/guis/GuiScraperSearch.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScraperSearch.cpp
//
// User interface for the scraper where the user is able to see an overview
diff --git a/es-app/src/guis/GuiScraperSearch.h b/es-app/src/guis/GuiScraperSearch.h
index 62ecc476d..69675ca46 100644
--- a/es-app/src/guis/GuiScraperSearch.h
+++ b/es-app/src/guis/GuiScraperSearch.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScraperSearch.h
//
// User interface for the scraper where the user is able to see an overview
diff --git a/es-app/src/guis/GuiScraperSingle.cpp b/es-app/src/guis/GuiScraperSingle.cpp
index 3675ee75e..00edf0cb6 100644
--- a/es-app/src/guis/GuiScraperSingle.cpp
+++ b/es-app/src/guis/GuiScraperSingle.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScraperSingle.cpp
//
// Single game scraping user interface.
diff --git a/es-app/src/guis/GuiScraperSingle.h b/es-app/src/guis/GuiScraperSingle.h
index 293b808e1..6f9b5093c 100644
--- a/es-app/src/guis/GuiScraperSingle.h
+++ b/es-app/src/guis/GuiScraperSingle.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScraperSingle.h
//
// Single game scraping user interface.
diff --git a/es-app/src/guis/GuiScreensaverOptions.cpp b/es-app/src/guis/GuiScreensaverOptions.cpp
index 30b4b8ead..f97af6e1f 100644
--- a/es-app/src/guis/GuiScreensaverOptions.cpp
+++ b/es-app/src/guis/GuiScreensaverOptions.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScreensaverOptions.cpp
//
// User interface for the screensaver options.
@@ -15,6 +15,8 @@
#include "components/SliderComponent.h"
#include "components/SwitchComponent.h"
#include "guis/GuiMsgBox.h"
+#include "guis/GuiTextEditKeyboardPopup.h"
+#include "guis/GuiTextEditPopup.h"
GuiScreensaverOptions::GuiScreensaverOptions(const std::string& title)
: GuiSettings {title}
@@ -196,20 +198,45 @@ void GuiScreensaverOptions::openSlideshowScreensaverOptions()
});
// Custom image directory.
- auto screensaverSlideshowImageDir = std::make_shared(
- "", Font::get(FONT_SIZE_SMALL), mMenuColorPrimary, ALIGN_RIGHT);
- s->addEditableTextComponent(
- "CUSTOM IMAGE DIRECTORY", screensaverSlideshowImageDir,
- Settings::getInstance()->getString("ScreensaverSlideshowImageDir"),
- Settings::getInstance()->getDefaultString("ScreensaverSlideshowImageDir"));
- s->addSaveFunc([screensaverSlideshowImageDir, s] {
- if (screensaverSlideshowImageDir->getValue() !=
- Settings::getInstance()->getString("ScreensaverSlideshowImageDir")) {
- Settings::getInstance()->setString("ScreensaverSlideshowImageDir",
- screensaverSlideshowImageDir->getValue());
- s->setNeedsSaving();
+ ComponentListRow rowCustomImageDir;
+ auto ScreensaverSlideshowCustomDir = std::make_shared(
+ "CUSTOM IMAGE DIRECTORY", Font::get(FONT_SIZE_MEDIUM), mMenuColorPrimary);
+ auto bracketCustomImageDir = std::make_shared();
+ bracketCustomImageDir->setResize(
+ glm::vec2 {0.0f, Font::get(FONT_SIZE_MEDIUM)->getLetterHeight()});
+ bracketCustomImageDir->setImage(":/graphics/arrow.svg");
+ bracketCustomImageDir->setColorShift(mMenuColorPrimary);
+ rowCustomImageDir.addElement(ScreensaverSlideshowCustomDir, true);
+ rowCustomImageDir.addElement(bracketCustomImageDir, false);
+ const std::string titleCustomImageDir {"CUSTOM IMAGE DIRECTORY"};
+ const std::string defaultImageDirStaticText {"Default directory:"};
+ const std::string defaultImageDirText {Utils::FileSystem::getAppDataDirectory() +
+ "/screensavers/custom_slideshow"};
+ const std::string initValueMediaDir {
+ Settings::getInstance()->getString("ScreensaverSlideshowCustomDir")};
+ auto updateValMediaDir = [s](const std::string& newVal) {
+ Settings::getInstance()->setString("ScreensaverSlideshowCustomDir", newVal);
+ s->setNeedsSaving();
+ };
+ rowCustomImageDir.makeAcceptInputHandler([this, s, titleCustomImageDir,
+ defaultImageDirStaticText, defaultImageDirText,
+ initValueMediaDir, updateValMediaDir] {
+ if (Settings::getInstance()->getBool("VirtualKeyboard")) {
+ mWindow->pushGui(new GuiTextEditKeyboardPopup(
+ getHelpStyle(), s->getMenu().getPosition().y, titleCustomImageDir,
+ Settings::getInstance()->getString("ScreensaverSlideshowCustomDir"),
+ updateValMediaDir, false, "SAVE", "SAVE CHANGES?", defaultImageDirStaticText,
+ defaultImageDirText, "load default directory"));
+ }
+ else {
+ mWindow->pushGui(new GuiTextEditPopup(
+ getHelpStyle(), titleCustomImageDir,
+ Settings::getInstance()->getString("ScreensaverSlideshowCustomDir"),
+ updateValMediaDir, false, "SAVE", "SAVE CHANGES?", defaultImageDirStaticText,
+ defaultImageDirText, "load default directory"));
}
});
+ s->addRow(rowCustomImageDir);
s->setSize(mSize);
mWindow->pushGui(s);
diff --git a/es-app/src/guis/GuiScreensaverOptions.h b/es-app/src/guis/GuiScreensaverOptions.h
index 74f47112f..a14be386e 100644
--- a/es-app/src/guis/GuiScreensaverOptions.h
+++ b/es-app/src/guis/GuiScreensaverOptions.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiScreensaverOptions.h
//
// User interface for the screensaver options.
diff --git a/es-app/src/guis/GuiSettings.cpp b/es-app/src/guis/GuiSettings.cpp
index f2ae13079..013042cdb 100644
--- a/es-app/src/guis/GuiSettings.cpp
+++ b/es-app/src/guis/GuiSettings.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiSettings.cpp
//
// User interface template for a settings GUI.
diff --git a/es-app/src/guis/GuiSettings.h b/es-app/src/guis/GuiSettings.h
index f8a24bf84..b27b85a28 100644
--- a/es-app/src/guis/GuiSettings.h
+++ b/es-app/src/guis/GuiSettings.h
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiSettings.h
//
// User interface template for a settings GUI.
diff --git a/es-app/src/guis/GuiThemeDownloader.cpp b/es-app/src/guis/GuiThemeDownloader.cpp
index 771ea5aca..1b09f217a 100644
--- a/es-app/src/guis/GuiThemeDownloader.cpp
+++ b/es-app/src/guis/GuiThemeDownloader.cpp
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: MIT
//
-// EmulationStation Desktop Edition
+// ES-DE
// GuiThemeDownloader.cpp
//
// Theme downloader.
@@ -8,7 +8,7 @@
#include "guis/GuiThemeDownloader.h"
-#include "EmulationStation.h"
+#include "ApplicationVersion.h"
#include "ThemeData.h"
#include "components/MenuComponent.h"
#include "resources/ResourceManager.h"
@@ -67,9 +67,9 @@ GuiThemeDownloader::GuiThemeDownloader(std::function updateCallback)
std::make_shared("", Font::get(fontSizeSmall), mMenuColorTitle, ALIGN_LEFT);
mCenterGrid->setEntry(mAspectRatiosLabel, glm::ivec2 {3, 0}, false, true, glm::ivec2 {1, 1});
- mFutureUseLabel =
+ mFontSizesLabel =
std::make_shared("", Font::get(fontSizeSmall), mMenuColorTitle, ALIGN_LEFT);
- mCenterGrid->setEntry(mFutureUseLabel, glm::ivec2 {3, 1}, false, true, glm::ivec2 {1, 1});
+ mCenterGrid->setEntry(mFontSizesLabel, glm::ivec2 {3, 1}, false, true, glm::ivec2 {1, 1});
mCenterGrid->setEntry(std::make_shared(), glm::ivec2 {5, 0}, false, false,
glm::ivec2 {1, 5});
@@ -86,9 +86,9 @@ GuiThemeDownloader::GuiThemeDownloader(std::function updateCallback)
"", Font::get(fontSizeSmall, FONT_PATH_LIGHT), mMenuColorTitle, ALIGN_LEFT);
mCenterGrid->setEntry(mAspectRatiosCount, glm::ivec2 {4, 0}, false, true, glm::ivec2 {1, 1});
- mFutureUseCount = std::make_shared("", Font::get(fontSizeSmall, FONT_PATH_LIGHT),
+ mFontSizesCount = std::make_shared("", Font::get(fontSizeSmall, FONT_PATH_LIGHT),
mMenuColorTitle, ALIGN_LEFT);
- mCenterGrid->setEntry(mFutureUseCount, glm::ivec2 {4, 1}, false, true, glm::ivec2 {1, 1});
+ mCenterGrid->setEntry(mFontSizesCount, glm::ivec2 {4, 1}, false, true, glm::ivec2 {1, 1});
mDownloadStatus = std::make_shared("", Font::get(fontSizeSmall, FONT_PATH_BOLD),
mMenuColorTitle, ALIGN_LEFT);
@@ -162,20 +162,29 @@ GuiThemeDownloader::GuiThemeDownloader(std::function updateCallback)
git_libgit2_init();
+#if defined(__ANDROID__) && defined(USE_BUNDLED_CERTIFICATES)
+ git_libgit2_opts(
+ GIT_OPT_SET_SSL_CERT_LOCATIONS,
+ ResourceManager::getInstance().getResourcePath(":/certificates/curl-ca-bundle.crt").c_str(),
+ nullptr);
+#endif
+
// The promise/future mechanism is used as signaling for the thread to indicate that
// repository fetching has been completed.
std::promise().swap(mPromise);
mFuture = mPromise.get_future();
- const std::string defaultUserThemeDir {Utils::FileSystem::getHomePath() +
- "/.emulationstation/themes"};
- std::string userThemeDirSetting {Utils::FileSystem::expandHomePath(
+#if defined(__ANDROID__)
+ mThemeDirectory = Utils::FileSystem::getInternalAppDataDirectory() + "/themes";
+#else
+ const std::string defaultUserThemeDir {Utils::FileSystem::getAppDataDirectory() + "/themes"};
+ const std::string userThemeDirSetting {Utils::FileSystem::expandHomePath(
Settings::getInstance()->getString("UserThemeDirectory"))};
+
#if defined(_WIN64)
mThemeDirectory = Utils::String::replace(mThemeDirectory, "\\", "/");
#endif
-
- if (userThemeDirSetting == "") {
+ if (userThemeDirSetting.empty()) {
mThemeDirectory = defaultUserThemeDir;
}
else if (Utils::FileSystem::isDirectory(userThemeDirSetting) ||
@@ -189,6 +198,7 @@ GuiThemeDownloader::GuiThemeDownloader(std::function updateCallback)
<< defaultUserThemeDir << "\"";
mThemeDirectory = defaultUserThemeDir;
}
+#endif
if (mThemeDirectory.back() != '/')
mThemeDirectory.append("/");
@@ -470,7 +480,10 @@ void GuiThemeDownloader::resetRepository(git_repository* repository)
void GuiThemeDownloader::makeInventory()
{
+ const auto totalInventoryTime {std::chrono::system_clock::now()};
+
for (auto& theme : mThemes) {
+ const auto themeInventoryTime {std::chrono::system_clock::now()};
const std::string path {mThemeDirectory + theme.reponame};
theme.invalidRepository = false;
theme.corruptRepository = false;
@@ -519,8 +532,25 @@ void GuiThemeDownloader::makeInventory()
theme.hasLocalChanges = true;
git_repository_free(repository);
+
+ LOG(LogDebug) << "GuiThemeDownloader::makeInventory(): Theme \""
+#if defined(_WIN64)
+ << Utils::String::replace(path, "/", "\\")
+ << "\" inventory completed in: "
+#else
+ << path << "\" inventory completed in: "
+#endif
+ << std::chrono::duration_cast(
+ std::chrono::system_clock::now() - themeInventoryTime)
+ .count()
+ << " ms";
}
}
+ LOG(LogDebug) << "GuiThemeDownloader::makeInventory(): Total theme inventory time: "
+ << std::chrono::duration_cast(
+ std::chrono::system_clock::now() - totalInventoryTime)
+ .count()
+ << " ms";
}
bool GuiThemeDownloader::renameDirectory(const std::string& path, const std::string& extension)
@@ -561,8 +591,7 @@ void GuiThemeDownloader::parseThemesList()
#if (LOCAL_TESTING_FILE)
LOG(LogWarning) << "GuiThemeDownloader: Using local \"themes.json\" testing file";
- const std::string themesFile {Utils::FileSystem::getHomePath() +
- "/.emulationstation/themes.json"};
+ const std::string themesFile {Utils::FileSystem::getAppDataDirectory() + "/themes.json"};
#else
const std::string themesFile {mThemeDirectory + "themes-list/themes.json"};
#endif
@@ -606,70 +635,92 @@ void GuiThemeDownloader::parseThemesList()
}
}
- if (doc.HasMember("themes") && doc["themes"].IsArray()) {
- const rapidjson::Value& themes {doc["themes"]};
- for (int i {0}; i < static_cast(themes.Size()); ++i) {
- ThemeEntry themeEntry;
- const rapidjson::Value& theme {themes[i]};
+#if defined(__ANDROID__)
+ const std::vector themeKeys {"themes", "themesAndroid"};
+#else
+ const std::vector themeKeys {"themes"};
+#endif
- if (theme.HasMember("name") && theme["name"].IsString())
- themeEntry.name = theme["name"].GetString();
+ for (auto& themeKey : themeKeys) {
+ if (doc.HasMember(themeKey.c_str()) && doc[themeKey.c_str()].IsArray()) {
+ const rapidjson::Value& themes {doc[themeKey.c_str()]};
+ for (int i {0}; i < static_cast(themes.Size()); ++i) {
+ ThemeEntry themeEntry;
+ const rapidjson::Value& theme {themes[i]};
- if (theme.HasMember("reponame") && theme["reponame"].IsString())
- themeEntry.reponame = theme["reponame"].GetString();
+ if (theme.HasMember("name") && theme["name"].IsString())
+ themeEntry.name = theme["name"].GetString();
- if (theme.HasMember("url") && theme["url"].IsString())
- themeEntry.url = theme["url"].GetString();
+ if (theme.HasMember("reponame") && theme["reponame"].IsString())
+ themeEntry.reponame = theme["reponame"].GetString();
- if (theme.HasMember("author") && theme["author"].IsString())
- themeEntry.author = theme["author"].GetString();
+ if (theme.HasMember("url") && theme["url"].IsString())
+ themeEntry.url = theme["url"].GetString();
- if (theme.HasMember("newEntry") && theme["newEntry"].IsBool())
- themeEntry.newEntry = theme["newEntry"].GetBool();
+ if (theme.HasMember("author") && theme["author"].IsString())
+ themeEntry.author = theme["author"].GetString();
- if (theme.HasMember("variants") && theme["variants"].IsArray()) {
- const rapidjson::Value& variants {theme["variants"]};
- for (int i {0}; i < static_cast