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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2022-04-10 20:36:07 +02:00
parent 9a0db6c01d
commit 74ce3fa08a
6 changed files with 99 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
CHANGELOG.md
View file

@ -15,7 +15,9 @@
* Made gamelist theming much more flexible by allowing any number of elements of any types to be defined
* Deprecated multiple older theming concepts like features, extras and hardcoded metadata attributes
* Modernized the OpenGL renderer by replacing the fixed function pipeline with shaders
* Unified the desktop OpenGL and OpenGL ES renderers and upgraded to OpenGL 3.3 and OpenGL ES 3.0 respectively
* Unified the desktop OpenGL and OpenGL ES renderers and upgraded to OpenGL 3.3 (as default) and OpenGL ES 3.0 respectively
* OpenGL: Added an OpenGLVersion setting for choosing between OpenGL 3.3, 4.2 and 4.6 (has to be manually set in es_settings.xml)
* OpenGL ES: Added an OpenGLVersion setting for choosing between OpenGL ES 3.0, 3.1 and 3.2 (has to be manually set in es_settings.xml)
* Greatly improved the performance of shader post-processing such as scanlines and blur rendering
* Added support for asterisks/wildcards for emulator name matching, usable both in es_find_rules.xml and es_systems.xml
* The actual names for emulators with find rule entries are now displayed in the error popup window if they're not found during game launch
@ -37,6 +39,8 @@
* Added theme support for enabling and disabling video pillarboxes and scanline rendering
* Added theme support for enabling or disabling audio playback for videos
* Added theme support for setting separate textColorDimmed and iconColorDimmed properties for the system and gamelist views
* Added support for nesting of theme variables
* Prevented loading of theme sets using the "resolution" tag introduced by RetroPie in 2020 as it's a very bad idea to use this logic
* Disabled the pillarboxes and scanline rendering menu options when using a non-legacy theme set
* Improved theme element placement by replacing the "alignment" and "logoAlignment" properties with specific horizontal and vertical properties
* Made it possible to use almost all game metadata field when theming text elements
@ -55,6 +59,7 @@
* Added support for dimming components (fade to black)
* Added logging of the display refresh rate on startup
* Added a command line option to rotate the application screen 180 degrees
* Added support for the platform pico8 (only platform and scraper support, no system or theme configuration added yet)
* Improved the theme loading error logging to make it consistent and easier to understand
* Added a log warning for unthemed systems during theme set loading
* Changed the warning log level for missing theme files to debug level if the paths are set using variables
@ -71,6 +76,7 @@
* Large refactoring to improve thread safety and improve singleton pattern usage
* Moved all Platform functions to the utility namespace instead of using the global namespace
* Implemented proper XML attribute support in ThemeData that eliminates the risk of name collisions
* Added size restrictions to images and fonts so incorrect theme configuration would not lead to crashes or excessive memory utilization
* Migrated the carousel code from SystemView to a separate new CarouselComponent
* Changed all occurances of "GameList" to "Gamelist" throughout the codebase
* Removed a huge amount of unnecessary Window* function parameters throughout the codebase
@ -110,9 +116,30 @@
* Text opacity did not work correctly in some places, such as for the help prompts
* ScrollableContainer faded semi-transparent text to fully opaque when resetting
* ScrollableContainer faded in the background text color in addition to the text color when resetting
* Theme sets were not always sorted correctly (as seen when mixing uppercase and lowercase in theme names)
* The device text flickered in GuiDetectDevice when configuring a controller
* The selector bar was not aligned correctly during menu scale-up animations
## Version 1.2.3 (in development)
**Release date:** TBD
### Release overview
v1.2 maintenance release.
### Detailed list of changes
* Added a scraper setting to convert underscores _ to spaces when searching
* Replaced the RetroArch core 4DO with Opera for the 3do system
* Added the .wud and .wux file extensions for the wiiu system on Windows
* Added missing scraper entries for samcoupe and zx81 for TheGamesDB and zmachine for ScreenScraper
* neogeocd is now scraped specifically as "Neo Geo CD" instead of the more generic "Neo Geo"
### Bug fixes
* Navigating the list of alternative emulators would sometimes lead to an incorrect row positioning
## Version 1.2.2
**Release date:** 2022-04-07

8
CONTRIBUTING.md
View file

@ -4,13 +4,17 @@
Contributions are very much appreciated as there are many things that need to be implemented and improved.
There are basically three areas where help is needed:
In addition to the information below about work on ES-DE itself, the project is currently looking for a developer to create a configuration utility for customizing systems (i.e. to avoid having to manually edit XML configuration files). For various reasons this should be a standalone application, and it needs to be cross-platform with support for Windows, macOS and Linux. Get in touch if you would be interested in working on this!
Apart from the above there are basically four areas where help is needed:
* Programming: If you are experienced with developing cross-platform client applications in C++ then ES-DE could be an interesting project! Although the application does not have a huge codebase, it is still fairly complex as it covers many different areas like OpenGL rendering, audio playback, video playback, controller input, network access, XML and JSON parsing etc. To work on the project you need to be able to test your code on Linux, macOS and Windows, but apart from that it should hopefully be fairly straightforward.
* Graphics: There are a few different areas where help is needed, but primarily it would be to create game systems vector graphics for the default rbsimple-DE theme as it's missing a lot of assets today. Check out [MISSING.md](themes/rbsimple-DE/MISSING.md) for more details about this.
* Emulator configuration and testing: As one of the main goals of ES-DE is easy setup, the application needs to ship with all game systems preconfigured. This means that the es_systems.xml files have to be populated with both primary and alternative emulators for all supported operating systems. There could also be a need to add additional platforms that ES-DE does not support today. Please refer to [USERGUIDE-DEV.md](USERGUIDE-DEV.md#supported-game-systems) for the current game systems status. You can also review the es_systems.xml files directly: [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).
* Emulator configuration and testing: As one of the main goals of ES-DE is easy setup, the application needs to ship with all game systems preconfigured. This means that the es_systems.xml files have to be populated with both default and alternative emulators for all supported operating systems. There could also be a need to add additional platforms that ES-DE does not support today. Please refer to [USERGUIDE-DEV.md](USERGUIDE-DEV.md#supported-game-systems) for the current game systems status. You can also review the es_systems.xml files directly: [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).
* Theme creation. With ES-DE v2.0 a new theme engine will be introduced with improved capabilities compared to the current engine. Existing themes would need to be ported over to the new engine, potentially also from other frontends than RetroPie EmulationStation. Completely new themes would also be nice to showcase the new engine.
Another specific area where help is needed is to research and potentially develop a usable web version of ES-DE. A proof of concept compilation to WebAssembly (using Emscripten) has been done and the application actually runs somehow correctly in a browser. But it needs to be investigated whether games/emulators can actually be launched when running in this environment and there are many improvements to be completed before the WebAssembly build is usable.

8
THEMES-DEV.md
View file

@ -726,6 +726,14 @@ It can also be used to specify only a portion of the value of a theme property:
<path>./core/images/${system.theme}.svg</path>
````
Nesting of variables is supported, so the following could be done:
```
<variables>
<colorRed>8b0000</colorRed>
<themeColor>${colorRed}</themeColor>
</variables>
```
## Reference
This section describes each element and their properties in detail and also contains example configuration snippets.

10
THEMES-LEGACY.md
View file

@ -2,7 +2,7 @@
**This document covers the creation of legacy themes only, which is a theme structure that is backward compatible with RetroPie EmulationStation. As ES-DE v2.0 and later has a new theme engine with much improved theming capabilities, this document is mostly intended for historical reference. For creating or porting themes to ES-DE the documentation in [THEMES.md](THEMES.md) should be used instead.**
In general ES-DE is backward compatible with RetroPie theme sets with the notable exception of the _Grid_ view style which is not supported. Themes with grid view styles included will still load correctly, but you can't actually use this view style.
In general ES-DE is backward compatible with RetroPie theme sets with the notable exception of the _Grid_ view style which is not supported. Themes with grid view styles included will still load correctly, but you can't actually use this view style. As well, any RetroPie theme using the `<resolution>` tag introduced in 2020 will not get loaded. This tag was a very bad idea as it changes sizing of components from relative values to absolute pixel values.
Table of contents:
@ -402,6 +402,14 @@ or to specify only a portion of the value of a theme property:
<path>./art/logo/${system.theme}.svg</path>
````
Nesting of variables is supported, so the following could be done:
```
<variables>
<colorRed>8b0000</colorRed>
<themeColor>${colorRed}</themeColor>
</variables>
```
## Reference

46
USERGUIDE-DEV.md
View file

@ -78,14 +78,14 @@ sudo dnf install ./emulationstation-de-1.2.0-x64.rpm
Of course the filename will differ slightly depending on the architecture, the example above is for the x64/x86 platform.
**Running the Linux AppImage file**
**Running the Linux AppImage**
In addition to the .deb and .rpm packages covered above, ES-DE is also available as an AppImage which should be usable on most modern x86 64-bit Linux distributions. After download you have to set the file as executable, such as this:
In addition to the .deb and .rpm packages covered above, ES-DE is also available as an AppImage which 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-2.0.0-x64.AppImage
chmod +x EmulationStation-DE-x64.AppImage
```
Following this you can launch ES-DE by double-clicking on the AppImage using your file manager. It's also possible to run it from a terminal window, in which case all command line options work the same way as if installed as an ordinary package.
But in some desktop environments this is not required and you can simply launch the file by double-clicking on it using your file manager. The first time you do this you will be required to confirm that you actually want to execute the file. Running the AppImage works exactly as if you would launch ES-DE if installed as a .deb or .rpm package. It's also possible to run it from a terminal window, in which case all command line options work the same way as if installed as an ordinary package.
For a better desktop integration it's recommended to install [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher) which will add an ES-DE entry to the application menu and move the AppImage file to the `~/Applications` directory (which is the recommended location for all AppImages).
@ -301,7 +301,9 @@ On Raspberry Pi OS 11 there are various graphics issues and sometimes the applic
## Game system customizations
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, i.e. `~/.emulationstation/custom_systems/es_systems.xml`.
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/\<username\>/.emulationstation/custom_systems/es_systems.xml, on macOS /Users/\<username\>/.emulationstation/custom_systems/es_systems.xml and on Windows C:\Users\\<username\>\\.emulationstation\custom_systems\es_systems.xml
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 done. 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.
@ -718,7 +720,6 @@ The RPCS3 emulator requires a bit of special setup.
On Windows RPCS3 does not ship with an installer but rather as a zip file that contains all application files. You will need to unzip the content and manually add that directory to your environment Path variable so that ES-DE will be able to find the emulator binary rpcs3.exe, or you can optionally place the RPCS3 directory inside the ES-DE installation directory in which case it will be found when launching a game. Both these options are described in more detail [here](USERGUIDE-DEV.md#specific-notes-for-windows)
The macOS release ships as a regular DMG file that is installed as usual.
On Linux RPCS3 is shipped as a Snap package, Flatpak package or AppImage. If installed as a Snap or Flatpak or if built from source code, ES-DE should be able to easily locate the emulator binary.
@ -903,7 +904,9 @@ As an alternative, you can add the Lutris games to the Ports game system, if you
**Note:** Launching Steam games currently has some limitations such as missing error messages when a game fails to start as well as missing game output logging. ES-DE also needs to keep running in the background for technical reasons, which has some minor side effects.
As for the setup, it's recommended to place shell scripts/batch files directly in the steam system directory, with the filenames of these scripts corresponding to the game names.
On Windows it's straightforward to add Steam games to ES-DE, simply copy the Start Menu entries for your Steam games into the ~\ROMs\steam directory. These files have the .url extension and can be launched directly from within ES-DE.
For Linux and macOS it's a bit more complicated. For these platforms it's recommended to place shell scripts directly in the steam system directory, with filenames corresponding to the game names.
Add the game information to each shell script using the syntax `<steam binary> steam://rungameid/<game ID>`
@ -918,11 +921,6 @@ And on macOS with the filename `Broforce.sh`:
/Applications/Steam.app/Contents/MacOS/steam_osx steam://rungameid/274190
```
And finally on Windows with the filename `Broforce.bat`:
```
"c:\Program Files (x86)\Steam\steam.exe" steam://rungameid/274190
```
The game ID can be found by going to [https://store.steampowered.com](https://store.steampowered.com) and searching for a game. The Broforce example would have an URL such as this:
https://store.steampowered.com/app/274190/Broforce
@ -990,13 +988,13 @@ The multi-scraper is accessed from the main menu by entering the **Scraper** men
### Scraping process
Assuming the default _Interactive mode_ option is enabled, the process of scraping games is basically identical between the single-game scraper and the multi-scraper. You're presented with the returned scraper results, and you're able to refine the search if the scraper could not find your game. Sometimes small changes like adding or removing a colon or a minus sign can yield better results. Note that searches are handled entirely by the scraper service, ES-DE just presents the results returned from the service.
The default mode for the scraper is _Non-interactive_ mode, also referred to as _Automatic_ mode. When using this mode the selected systems are scraped without requiring any user input. This is quite convenient, but has the drawback of not asking for input if multiple matching games are returned by the scraper service. This could lead to the wrong game metadata and media being downloaded, but in practice this is quite rare so it's generally recommended to keep the automatic mode enabled. If no result is found for a game, the scraper will skip to the next one in queue.
It's generally recommended to keep the _Auto-accept single game matches_ option enabled as it will run the scraper in semi-automatic mode, only stopping to ask for user input if there are multiple results returned or if no game was found. If this option is disabled, the scraper will stop and ask for confirmation for every game.
If _interactive mode_ is instead enabled, the process of scraping games is basically identical between the single-game scraper and the multi-scraper. You're presented with the returned scraper results, and you're able to refine the search if the scraper could not find your game. Sometimes small changes like adding or removing a colon or a minus sign can yield better results. Note that searches are handled entirely by the scraper service, ES-DE just presents the results returned from the service.
But by disabling the _Interactive mode_ option, the multi-scraper will run in a fully automatic mode, selecting the first game in case of multiple results and skipping to the next game if no results were returned. This is quite convenient for large game libraries but if the correct game is not the first one returned by the scraper service, the wrong game data will be scraped which will require manual correction using the single-game scraper.
When scraping in interactive mode it's recommended to keep the _Auto-accept single game matches_ option enabled as it will run the scraper in semi-automatic mode, only stopping to ask for user input if there are multiple results returned or if no game was found. If this option is disabled, the scraper will stop and ask for confirmation for every game.
Under normal circumstances the scraper service will only return games for the platforms used for searching, but sometimes when it's not sure about the results it will also include games from other platforms. If this happens, these additional platform names will be displayed within square brackets after the game name in the result list. And if a game system is configured for multiple platforms, then the specific platform returned per result will always be displayed within square brackets. The exception for these two scenarios is if the multi-scraper is running in fully automatic mode as the additional platform information is then always omitted. Note that additional platform information will not affect the scraped game name, it's only used for clarification within the scraper result list.
Under normal circumstances the scraper service will only return games for the platforms used for searching, but sometimes when it's not sure about the results it will also include games from other platforms. If this happens, these additional platform names will be displayed within square brackets after the game name in the result list. And if a game system is configured for multiple platforms, then the specific platform returned per result will always be displayed within square brackets. The exception for these two scenarios is if the multi-scraper is running in fully automatic mode as the additional platform information is then always omitted. Note that the additional platform information will not be included in the scraped game name, it's only used for clarification within the scraper result list.
By default, ES-DE will search using the metadata name of the game. If no name has previously been defined via scraping or via manually entering it using the metadata editor, the name used for searching will correspond to the physical filename minus all text inside either normal brackets `()` or square brackets `[]`. So for example the physical filename `Mygame (U) [v2].zip` will be stripped to simply `Mygame` when performing the scraper search.
@ -1267,6 +1265,10 @@ It's possible to set a flag per game file or folder using the metadata editor to
If this setting is enabled and a folder has its flag set to be excluded from the scraper, then the entire folder contents are skipped when running the multi-scraper.
**Convert underscores to spaces when searching**
With this option enabled underscores _ in game names are converted to spaces when performing scraper searches. This affects both the single-game scraper and the multi-scraper and it will also be applied automatically to the _Refine search_ dialog.
**Auto-retry on peer verification errors** _(ScreenScraper only)_
ScreenScraper sometimes has issues with its TLS certificates which causes searches to randomly fail. It's normally resolved within a few days, but in the meanwhile activating this setting will have the scraper automatically make up to eight additional attempts when this error occurs. That is normally enough to complete the search, but if not, just press _Retry_ in the error dialog and ES-DE will try eight more times. This setting applies to both the single-game scraper and the multi-scraper. The following error notification dialog and corresponding es_log.txt entry is displayed when this error occurs: "Error downloading thumbnail: SSL peer certificate or SSH remote key was not OK".
@ -2064,9 +2066,11 @@ Default emulator/Alternative emulators columns: \
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 | 4DO | | | |
| 3do | 3DO | Opera | | | |
| 64dd | Nintendo 64DD | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | ParaLLEl N64 [UW],<br>Mupen64Plus **(Standalone)** [UMW*],<br>sixtyforce **(Standalone)** [M] | | |
| ags | Adventure Game Studio Game Engine | _Placeholder_ | | | |
| amiga | Commodore Amiga | PUAE | | Yes | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disc, or in separate folder with .m3u playlist if multi-disc |
@ -2111,9 +2115,9 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| fds | Nintendo Famicom Disk System | Nestopia UE | FCEUmm,<br>Mesen | Yes | Single archive or ROM file in root folder |
| gameandwatch | Nintendo Game and Watch | GW | | | |
| gamegear | Sega Game Gear | Gearsystem | SMS Plus GX,<br>Genesis Plus GX,<br>Genesis Plus GX Wide | | |
| gb | Nintendo Game Boy | SameBoy | Gambatte,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | | Single archive or ROM file in root folder |
| gb | Nintendo Game Boy | SameBoy | Gambatte,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | No | Single archive or ROM file in root folder |
| gba | Nintendo Game Boy Advance | mGBA | mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** [UMW*],<br>VBA Next,<br>gpSP | No | Single archive or ROM file in root folder |
| gbc | Nintendo Game Boy Color | SameBoy | Gambatte,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | | Single archive or ROM file in root folder |
| gbc | Nintendo Game Boy Color | SameBoy | Gambatte,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | No | Single archive or ROM file in root folder |
| gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)** [UMW*], PrimeHack **(Standalone)** [U] | No | Single ISO file in root folder |
| genesis | Sega Genesis | Genesis Plus GX | Genesis Plus GX Wide,<br>PicoDrive,<br>BlastEm | No | Single archive or ROM file in root folder |
| gx4000 | Amstrad GX4000 | _Placeholder_ | | | |
@ -2166,7 +2170,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| ps4 | Sony PlayStation 4 | _Placeholder_ | | | |
| psp | Sony PlayStation Portable | PPSSPP | PPSSPP **(Standalone)** | No | Single ISO file in root folder |
| psvita | Sony PlayStation Vita | _Placeholder_ | | | |
| psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,<br>PCSX ReARMed,<br>SwanStation,<br>DuckStation [UW],<br>DuckStation **(Standalone)** [UMW*] | Yes | .chd file in root folder for single-disc games, .m3u playlist in root folder for multi-disc games |
| psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,<br>PCSX ReARMed,<br>SwanStation,<br>DuckStation@ [UW],<br>DuckStation **(Standalone)** [UMW*] | Yes | .chd file in root folder for single-disc games, .m3u playlist in root folder for multi-disc games |
| samcoupe | SAM Coupé | SimCoupe | | | |
| satellaview | Nintendo Satellaview | Snes9x - Current | Snes9x 2010,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>Mesen-S | | |
| saturn | Sega Saturn | Beetle Saturn | Kronos [UW],<br>YabaSanshiro [UW],<br>Yabause | | |
@ -2182,7 +2186,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>Beetle Supafaust [UW],<br>Mesen-S | No | Single archive or ROM file in root folder |
| solarus | Solarus Game Engine | _Placeholder_ | | | |
| spectravideo | Spectravideo | blueMSX | | | |
| steam | Valve Steam | Steam application **(Standalone)** | | No | Shell script/batch file in root folder |
| steam | Valve Steam | Steam application **(Standalone)** | | No | Shell script/batch file in root folder (and .url files supported on Windows) |
| stratagus | Stratagus Game Engine | _Placeholder_ | | | |
| sufami | Bandai SuFami Turbo | Snes9x - Current | Snes9x 2010,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy | | |
| supergrafx | NEC SuperGrafx | Beetle SuperGrafx | Beetle PCE | | |

43
USERGUIDE.md
View file

@ -76,14 +76,14 @@ sudo dnf install ./emulationstation-de-1.2.0-x64.rpm
Of course the filename will differ slightly depending on the architecture, the example above is for the x64/x86 platform.
**Running the Linux AppImage file**
**Running the Linux AppImage**
In addition to the .deb and .rpm packages covered above, ES-DE is also available as an AppImage which should be usable on most modern x86 64-bit Linux distributions. After download you have to set the file as executable, such as this:
In addition to the .deb and .rpm packages covered above, ES-DE is also available as an AppImage which 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-1.2.0-x64.AppImage
chmod +x EmulationStation-DE-x64.AppImage
```
Following this you can launch ES-DE by double-clicking on the AppImage using your file manager. It's also possible to run it from a terminal window, in which case all command line options work the same way as if installed as an ordinary package.
But in some desktop environments this is not required and you can simply launch the file by double-clicking on it using your file manager. The first time you do this you will be required to confirm that you actually want to execute the file. Running the AppImage works exactly as if you would launch ES-DE if installed as a .deb or .rpm package. It's also possible to run it from a terminal window, in which case all command line options work the same way as if installed as an ordinary package.
For a better desktop integration it's recommended to install [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher) which will add an ES-DE entry to the application menu and move the AppImage file to the `~/Applications` directory (which is the recommended location for all AppImages).
@ -299,7 +299,9 @@ On Raspberry Pi OS 11 there are various graphics issues and sometimes the applic
## Game system customizations
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, i.e. `~/.emulationstation/custom_systems/es_systems.xml`.
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/\<username\>/.emulationstation/custom_systems/es_systems.xml, on macOS /Users/\<username\>/.emulationstation/custom_systems/es_systems.xml and on Windows C:\Users\\<username\>\\.emulationstation\custom_systems\es_systems.xml
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 done. 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.
@ -734,13 +736,15 @@ The RPCS3 emulator requires a bit of special setup.
On Windows RPCS3 does not ship with an installer but rather as a zip file that contains all application files. You will need to unzip the content and manually add that directory to your environment Path variable so that ES-DE will be able to find the emulator binary rpcs3.exe, or you can optionally place the RPCS3 directory inside the ES-DE installation directory in which case it will be found when launching a game. Both these options are described in more detail [here](USERGUIDE.md#specific-notes-for-windows)
The macOS release ships as a regular DMG file that is installed as usual.
On Linux RPCS3 is shipped as a Snap package, Flatpak package or AppImage. If installed as a Snap or Flatpak or if built from source code, ES-DE should be able to easily locate the emulator binary.
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#using-emulators-in-appimage-format-on-linux) for more information on how to get it to work.
If using the Flatpak release and your games are stored on an external device (such as a memory card if using a Steam Deck), you need to give RPCS3 the necessary permissions. 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 _All system files_ in the _Filesystem_ section.
As for the game installation on both Windows and Linux, you need to retain the directory structure of the Blu-ray disc or the directory created by installing the .pkg file. Each directory needs to be renamed by adding the .ps3dir extension, which will make ES-DE interpret the directory as if it were a file and pass that directory to the emulator when launching a game.
As for the game installation on both Windows and Linux as well as on macOS, you need to retain the directory structure of the Blu-ray disc or the directory created by installing the .pkg file. Each directory needs to be renamed by adding the .ps3dir extension, which will make ES-DE interpret the directory as if it were a file and pass that directory to the emulator when launching a game.
Here's an example of what a Blu-ray disc directory could look like:
```
@ -749,7 +753,7 @@ Here's an example of what a Blu-ray disc directory could look like:
It's possible to create a symlink instead, and in this case only the symlink needs to have the .ps3dir extension.
Here's how to do it on Linux:
Here's how to do it on Linux and macOS:
```
cd ~/ROMs
ln -s ~/games/PS3/Gran\ Turismo\ 5 Gran\ Turismo\ 5.ps3dir
@ -916,7 +920,9 @@ As an alternative, you can add the Lutris games to the Ports game system, if you
**Note:** Launching Steam games currently has some limitations such as missing error messages when a game fails to start as well as missing game output logging. ES-DE also needs to keep running in the background for technical reasons, which has some minor side effects.
As for the setup, it's recommended to place shell scripts/batch files directly in the steam system directory, with the filenames of these scripts corresponding to the game names.
On Windows it's straightforward to add Steam games to ES-DE, simply copy the Start Menu entries for your Steam games into the ~\ROMs\steam directory. These files have the .url extension and can be launched directly from within ES-DE.
For Linux and macOS it's a bit more complicated. For these platforms it's recommended to place shell scripts directly in the steam system directory, with filenames corresponding to the game names.
Add the game information to each shell script using the syntax `<steam binary> steam://rungameid/<game ID>`
@ -931,11 +937,6 @@ And on macOS with the filename `Broforce.sh`:
/Applications/Steam.app/Contents/MacOS/steam_osx steam://rungameid/274190
```
And finally on Windows with the filename `Broforce.bat`:
```
"c:\Program Files (x86)\Steam\steam.exe" steam://rungameid/274190
```
The game ID can be found by going to [https://store.steampowered.com](https://store.steampowered.com) and searching for a game. The Broforce example would have an URL such as this:
https://store.steampowered.com/app/274190/Broforce
@ -1002,11 +1003,11 @@ The multi-scraper is accessed from the main menu by entering the **Scraper** men
### Scraping process
Assuming the default _Interactive mode_ option is enabled, the process of scraping games is basically identical between the single-game scraper and the multi-scraper. You're presented with the returned scraper results, and you're able to refine the search if the scraper could not find your game. Sometimes small changes like adding or removing a colon or a minus sign can yield better results. Note that searches are handled entirely by the scraper service, ES-DE just presents the results returned from the service.
The default mode for the scraper is _Non-interactive_ mode, also referred to as _Automatic_ mode. When using this mode the selected systems are scraped without requiring any user input. This is quite convenient, but has the drawback of not asking for input if multiple matching games are returned by the scraper service. This could lead to the wrong game metadata and media being downloaded, but in practice this is quite rare so it's generally recommended to keep the automatic mode enabled. If no result is found for a game, the scraper will skip to the next one in queue.
It's generally recommended to keep the _Auto-accept single game matches_ option enabled as it will run the scraper in semi-automatic mode, only stopping to ask for user input if there are multiple results returned or if no game was found. If this option is disabled, the scraper will stop and ask for confirmation for every game.
If _interactive mode_ is instead enabled, the process of scraping games is basically identical between the single-game scraper and the multi-scraper. You're presented with the returned scraper results, and you're able to refine the search if the scraper could not find your game. Sometimes small changes like adding or removing a colon or a minus sign can yield better results. Note that searches are handled entirely by the scraper service, ES-DE just presents the results returned from the service.
But by disabling the _Interactive mode_ option, the multi-scraper will run in a fully automatic mode, selecting the first game in case of multiple results and skipping to the next game if no results were returned. This is quite convenient for large game libraries but if the correct game is not the first one returned by the scraper service, the wrong game data will be scraped which will require manual correction using the single-game scraper.
When scraping in interactive mode it's recommended to keep the _Auto-accept single game matches_ option enabled as it will run the scraper in semi-automatic mode, only stopping to ask for user input if there are multiple results returned or if no game was found. If this option is disabled, the scraper will stop and ask for confirmation for every game.
By default, ES-DE will search using the metadata name of the game. If no name has previously been defined via scraping or via manually entering it using the metadata editor, the name used for searching will correspond to the physical filename minus all text inside either normal brackets `()` or square brackets `[]`. So for example the physical filename `Mygame (U) [v2].zip` will be stripped to simply `Mygame` when performing the scraper search.
@ -2062,6 +2063,8 @@ Default emulator/Alternative emulators columns: \
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 | 4DO | | | |
@ -2109,9 +2112,9 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| fds | Nintendo Famicom Disk System | Nestopia UE | FCEUmm,<br>Mesen | Yes | Single archive or ROM file in root folder |
| gameandwatch | Nintendo Game and Watch | GW | | | |
| gamegear | Sega Game Gear | Gearsystem | SMS Plus GX,<br>Genesis Plus GX,<br>Genesis Plus GX Wide | | |
| gb | Nintendo Game Boy | SameBoy | Gambatte,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | | Single archive or ROM file in root folder |
| gb | Nintendo Game Boy | SameBoy | Gambatte,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | No | Single archive or ROM file in root folder |
| gba | Nintendo Game Boy Advance | mGBA | mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** [UMW*],<br>VBA Next,<br>gpSP | No | Single archive or ROM file in root folder |
| gbc | Nintendo Game Boy Color | SameBoy | Gambatte,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | | Single archive or ROM file in root folder |
| gbc | Nintendo Game Boy Color | SameBoy | Gambatte,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | No | Single archive or ROM file in root folder |
| gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)** [UMW*], PrimeHack **(Standalone)** [U] | No | Single ISO file in root folder |
| genesis | Sega Genesis | Genesis Plus GX | Genesis Plus GX Wide,<br>PicoDrive,<br>BlastEm | No | Single archive or ROM file in root folder |
| gx4000 | Amstrad GX4000 | _Placeholder_ | | | |
@ -2164,7 +2167,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| ps4 | Sony PlayStation 4 | _Placeholder_ | | | |
| psp | Sony PlayStation Portable | PPSSPP | PPSSPP **(Standalone)** | No | Single ISO file in root folder |
| psvita | Sony PlayStation Vita | _Placeholder_ | | | |
| psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,<br>PCSX ReARMed,<br>SwanStation,<br>DuckStation [UW],<br>DuckStation **(Standalone)** [UMW*] | Yes | .chd file in root folder for single-disc games, .m3u playlist in root folder for multi-disc games |
| psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,<br>PCSX ReARMed,<br>SwanStation,<br>DuckStation@ [UW],<br>DuckStation **(Standalone)** [UMW*] | Yes | .chd file in root folder for single-disc games, .m3u playlist in root folder for multi-disc games |
| samcoupe | SAM Coupé | SimCoupe | | | |
| satellaview | Nintendo Satellaview | Snes9x - Current | Snes9x 2010,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>Mesen-S | | |
| saturn | Sega Saturn | Beetle Saturn | Kronos [UW],<br>YabaSanshiro [UW],<br>Yabause | | |
@ -2180,7 +2183,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>Beetle Supafaust [UW],<br>Mesen-S | No | Single archive or ROM file in root folder |
| solarus | Solarus Game Engine | _Placeholder_ | | | |
| spectravideo | Spectravideo | blueMSX | | | |
| steam | Valve Steam | Steam application **(Standalone)** | | No | Shell script/batch file in root folder |
| steam | Valve Steam | Steam application **(Standalone)** | | No | Shell script/batch file in root folder (and .url files supported on Windows) |
| stratagus | Stratagus Game Engine | _Placeholder_ | | | |
| sufami | Bandai SuFami Turbo | Snes9x - Current | Snes9x 2010,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy | | |
| supergrafx | NEC SuperGrafx | Beetle SuperGrafx | Beetle PCE | | |