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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2021-12-06 20:48:47 +01:00
parent 5019d8c065
commit 7c366d776e
4 changed files with 56 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
CHANGELOG.md
View file

@ -34,6 +34,8 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac
* Added size options (small/medium/large) for the boxes/covers and physical media images when generating miximages * Added size options (small/medium/large) for the boxes/covers and physical media images when generating miximages
* Added support for the Raspberry Pi 4 (Raspberry Pi OS 32-bit/armv7l and 64-bit/aarch64) * Added support for the Raspberry Pi 4 (Raspberry Pi OS 32-bit/armv7l and 64-bit/aarch64)
* Bundled the new alternative theme "modern-DE" which supports all the latest features from this release * Bundled the new alternative theme "modern-DE" which supports all the latest features from this release
* Changed the Unix fullscreen mode to SDL_WINDOW_FULLSCREEN_DESKTOP and removed the --windowed, --fullscreen-normal and --fullscreen-borderless command line options
* Removed the Unix-specific menu option "Fullscreen mode (requires restart)"
* Added the ability to make complementary game system customizations without having to replace the entire bundled es_systems.xml file * Added the ability to make complementary game system customizations without having to replace the entire bundled es_systems.xml file
* Added support for an optional \<systemsortname\> tag for es_systems.xml that can be used to override the default \<fullname\> systems sorting * Added support for an optional \<systemsortname\> tag for es_systems.xml that can be used to override the default \<fullname\> systems sorting
* Added a "winregistryvalue" find rule for Windows which can be used to retrieve emulator installation locations from arbitrary Windows Registry keys * Added a "winregistryvalue" find rule for Windows which can be used to retrieve emulator installation locations from arbitrary Windows Registry keys
@ -55,6 +57,8 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac
* Added a menu option to change the application exit key combination * Added a menu option to change the application exit key combination
* If there are no custom collections, the "Custom game collections" menu entry is now grayed out * If there are no custom collections, the "Custom game collections" menu entry is now grayed out
* Added an option to preload the gamelists on startup which leads to smoother navigation when first entering each gamelist * Added an option to preload the gamelists on startup which leads to smoother navigation when first entering each gamelist
* Increased the amount of arguments for the custom event scripts from two to four
* Added the system name and full system name as additional arguments to the game-start and game-end custom events
* Lowered the minimum supported screen resolution from 640x480 to 224x224 to support arcade cabinet displays such as those running at 384x224 and 224x384 * Lowered the minimum supported screen resolution from 640x480 to 224x224 to support arcade cabinet displays such as those running at 384x224 and 224x384
* Added support for the Commodore VIC-20, Epic Games Store, Google Android, Java 2 Micro Edition, Philips CD-i and Symbian systems * Added support for the Commodore VIC-20, Epic Games Store, Google Android, Java 2 Micro Edition, Philips CD-i and Symbian systems
* Added support for a more advanced system view carousel logo placeholder (for unthemed systems) by allowing the combination of text and graphics * Added support for a more advanced system view carousel logo placeholder (for unthemed systems) by allowing the combination of text and graphics
@ -72,11 +76,14 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac
* Changed the font size for the custom collection deletion screen to use the same size as all other menus * Changed the font size for the custom collection deletion screen to use the same size as all other menus
* Added support for upscaling bitmap images using linear filtering * Added support for upscaling bitmap images using linear filtering
* Changed the marquee image upscale filtering from nearest neighbor to linear for the launch screen and the gamelist views * Changed the marquee image upscale filtering from nearest neighbor to linear for the launch screen and the gamelist views
* Made the window corners slightly more rounded
* Moved the Media viewer and Screensaver settings higher in the UI settings menu * Moved the Media viewer and Screensaver settings higher in the UI settings menu
* Moved the game media directory setting to the top of the Other settings menu, following the new Alternative emulators entry * Moved the game media directory setting to the top of the Other settings menu, following the new Alternative emulators entry
* Moved the ScreenScraper account toggle to the bottom of the scraper account settings menu
* Lowered the default volumes slightly for videos and navigation sounds * Lowered the default volumes slightly for videos and navigation sounds
* Added loading of the System view to the ViewController preload function to decrease theme extras texture pop-in * Added loading of the System view to the ViewController preload function to decrease theme extras texture pop-in
* Changed the filter description "Text filter (game name)" to simply "Game name" * Changed the filter description "Text filter (game name)" to simply "Game name"
* Improved the "AMD and Intel GPU game launch workaround" hack on Windows to provide more seamless game launches
* Removed a margin hack from TextComponent * Removed a margin hack from TextComponent
* If abbreviated strings end with a space character, that space is now removed (TextComponent) * If abbreviated strings end with a space character, that space is now removed (TextComponent)
* Added support for multi-select total count and exclusive multi-select to OptionListComponent * Added support for multi-select total count and exclusive multi-select to OptionListComponent
@ -110,6 +117,7 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac
* Increased the minimal required compiler version to 5.0.0 for Clang/LLVM and 7.1 for GCC * Increased the minimal required compiler version to 5.0.0 for Clang/LLVM and 7.1 for GCC
* Added CMake options to build with AddressSanitizer, ThreadSanitizer and UndefinedBehaviorSanitizer * Added CMake options to build with AddressSanitizer, ThreadSanitizer and UndefinedBehaviorSanitizer
* Changed two clang-format rules related to braced lists and reformatted the codebase * Changed two clang-format rules related to braced lists and reformatted the codebase
* Replaced the bundled SDL version 2.0.14 with 2.0.18 for the Windows release
* Bundled the October 2021 release of the Mozilla TLS/SSL certificates * Bundled the October 2021 release of the Mozilla TLS/SSL certificates
* Updated the MAME index files to include ROMs up to MAME version 0.237 * Updated the MAME index files to include ROMs up to MAME version 0.237
* rbsimple-DE: Added some missing graphics for the xbox360 and residualvm systems * rbsimple-DE: Added some missing graphics for the xbox360 and residualvm systems
@ -441,14 +449,20 @@ Many bugs have been fixed, and numerous features that were only partially implem
## Known issues ## Known issues
**The issues below are relevant for ES-DE v1.1.0** **The issues below are relevant for ES-DE v1.2.0**
* There is an issue with launching games on Windows when using AMD and Intel GPUs. This causes the emulator to just output a blank screen. There is a workaround available for this which is enabled by default and that can be disabled via the menu option "AMD and Intel GPU game launch workaround". The drawback of this workaround is that a white instead of a black screen will be displayed when launching games. If using an Nvidia GPU, it should be safe to disable this option for a slightly better user experience. An alternative workaround is to enable the option "Run in background (while game is launched)". * There is an issue with launching games on Windows when using AMD or Intel GPUs which causes the emulator to just output a blank screen. There is a workaround available for this which is enabled by default and that can be disabled via the menu option "AMD and Intel GPU game launch workaround" if using an Nvidia GPU. The workaround has the slight drawback that the screen may flicker slightly when launching a game, and there will be a single-pixel transparent line at the bottom of the screen while the emulator is loading.
* On Windows when using high DPI displays, if not running ES-DE on the primary monitor and the display where it runs does not have the same scaling percentage as the primary monitor, then the ES-DE resolution will not be properly set. The application will still work and if running in fullscreen mode it may not even be noticeable. This issue is probably caused by a bug in SDL where the primary display scaling is always used for calculating the display bounds and as such it needs to be fixed in that library. If using the same scaling percentage across all monitors, or if not using high DPI monitors at all, then this issue will not occur. * On Windows when using high DPI displays, if not running ES-DE on the primary monitor and the display where it runs does not have the same scaling percentage as the primary monitor, then the ES-DE resolution will not be properly set. The application will still work and if running in fullscreen mode it may not even be noticeable. This issue is probably caused by a bug in SDL where the primary display scaling is always used for calculating the display bounds. If using the same scaling percentage across all monitors, or if not using high DPI monitors at all, then this issue is not relevant.
* On macOS, the RetroArch setting "Start in Fullscreen mode" must be enabled or ES-DE will not be able to switch to the emulator window. * On macOS, the RetroArch setting "Start in Fullscreen mode" must be enabled or ES-DE will not be able to switch to the emulator window when a game is launched. Possibly it's the same issue with other emulators as well.
* On Fedora 35 an issue has been observed where the screen turns completely black or flickers intensely when starting ES-DE for the first time. A workaround for this is to simply exit the application with F4 or Alt+F4 and starting it again. Everything should then render correctly, and any subsequent startups will work fine including after suspending/resuming the computer. It's currently unclear if this is limited to only some graphics drivers or if it's a general issue under Fedora and/or Wayland. * On Raspberry Pi OS 10, Sony DualShock 4 controllers have problems with some button presses that don't register correctly. The issue appears resolved in Raspberry Pi OS 11.
* Sometimes when RetroArch has been upgraded to a newer version, it apparently requires a startup to get properly initialized. When ES-DE starts RetroArch it always does so by passing some specific emulator core parameters, which does not seem to initialize RetroArch after such an upgrade. What happens in this case is that the RetroArch loading screen will be shown and then it will quit right back to ES-DE. If confirmed to be the case, this is not an ES-DE issue but a RetroArch issue and starting RetroArch separately once should fix the problem. * On Raspberry Pi OS 11 there are various graphics issues and sometimes the application or emulator completely freezes which requires a power cycle of the machine. This is seemingly due to GPU driver bugs and we can only wait for OS updates to address these problems. These issues have not been encountered on Raspberry Pi OS 10.
* On Fedora 35 a problem has been observed where the screen turns completely black or flickers intensely when starting ES-DE for the first time. A workaround for this is to simply exit the application with F4 or Alt+F4 and starting it again. Everything should then render correctly, and any subsequent startups will work fine including after suspending/resuming the computer. It's currently unclear if this is limited to only Intel GPU drivers or if it's a general issue under Fedora and/or Wayland. At least Wayland on Ubuntu 21.10 does not trigger the same issue.
* There is some screen tearing present on Unix/Linux which is especially visible during horizontal slide transitions. The problem exists on both x86 and ARM as well as on Intel, AMD and Nvidia GPUs and on the Broadcom VideoCore. The problem seems to be Xorg-related as tearing has not been observed when using Wayland, and it's not present on macOS or Windows either.
* Sometimes when RetroArch has been upgraded to a newer version, it apparently requires a startup to get properly initialized. When ES-DE starts RetroArch it always does so by passing some specific emulator core parameters, which does not seem to initialize RetroArch after such an upgrade. What happens in this case is that the RetroArch loading screen will be shown and then it will quit right back to ES-DE. If confirmed to be the case, this is not an ES-DE issue but a RetroArch issue and starting RetroArch separately once should fix the problem (at least until the next upgrade).

59
INSTALL-DEV.md
View file

@ -1334,33 +1334,6 @@ The input configuration is described in the [User guide](USERGUIDE-DEV.md#input-
You can use **--help** or **-h** to view the list of command line options, as shown here. You can use **--help** or **-h** to view the list of command line options, as shown here.
### Unix
```
--display [index 1-4] Display/monitor to use
--resolution [width] [height] Application resolution
--windowed Windowed mode, should be combined with --resolution
--fullscreen-normal Normal fullscreen mode
--fullscreen-borderless Borderless fullscreen mode (always on top)
--vsync [1/on or 0/off] Turn VSync on or off (default is on)
--max-vram [size] Max VRAM to use (in mebibytes) before swapping
--no-splash Don't show the splash screen during startup
--gamelist-only Skip automatic game ROM search, only read from gamelist.xml
--ignore-gamelist Ignore the gamelist files (useful for troubleshooting)
--show-hidden-files Show hidden files and folders
--show-hidden-games Show hidden games
--force-full Force the UI mode to Full
--force-kiosk Force the UI mode to Kiosk
--force-kid Force the UI mode to Kid
--force-input-config Force configuration of input device
--home [path] Directory to use as home path
--debug Print debug information
--version, -v Display version information
--help, -h Summon a sentient, angry tuba
```
### macOS and Windows
``` ```
--display [index 1-4] Display/monitor to use --display [index 1-4] Display/monitor to use
--resolution [width] [height] Application resolution --resolution [width] [height] Application resolution
@ -1383,11 +1356,11 @@ You can use **--help** or **-h** to view the list of command line options, as sh
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 `emulationstation --home ~/games/emulation`, ES-DE will use `~/games/emulation/.emulationstation` as its application home directory. Be aware that this option completely replaces what is considered the home directory, meaning the default ROM directory ~/ROMs would be resolved to ~/games/emulation/ROMs. The same is true for the emulator core locations if es_find_rules.xml is configured to look for them relative to the home directory. So of course RetroArch and other emulators would also need to be configured to use ~/games/emulation as its base directory in this instance.
Setting the resolution to a lower or higher value than the display resolution will add a border to the application window.
For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter: For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter:
``` ```
--display --display
--fullscreen-normal
--fullscreen-borderless
--max-vram --max-vram
--show-hidden-files --show-hidden-files
--show-hidden-games --show-hidden-games
@ -2047,20 +2020,20 @@ We'll go through two examples:
**Note:** The following examples are for Unix systems, but it works the same way on macOS (which is also Unix after all), and on Windows (although .bat batch files are then used instead of shell scripts and any spaces in the parameters are not escaped as is the case on Unix). **Note:** The following examples are for Unix systems, but it works the same way on macOS (which is also Unix after all), and on Windows (although .bat batch files are then used instead of shell scripts and any spaces in the parameters are not escaped as is the case on Unix).
The events executed when a game starts and ends are called `game-start` and `game-end` respectively. Finding these event names is easily achieved by starting ES-DE with the `--debug` flag. If this is done, all attempts to execute custom event scripts will be logged to es_log.txt, including the event names. The events executed when a game starts and ends are named `game-start` and `game-end` respectively. Finding these event names is easily achieved by starting ES-DE with the `--debug` flag. If this is done, all attempts to execute custom event scripts will be logged to es_log.txt, including the event names.
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 `~/.emulationstation/scripts`
**Game log:** **Game log:**
After creating the directories, we need to create the scripts to log the actual game launch and game ending. The parameters that are passed to the scripts varies depending on the type of event, but for these events the two parameters are the absolute path to the game file, and the game name as shown in the gamelist view. After creating the directories, we need to create the scripts to log the actual game launch and game ending. The parameters that are passed to the scripts vary depending on the type of event, but for these events the four parameters are the absolute path to the game file, the game name as shown in the gamelist view, the system name and the full system name.
Let's name the start script `game_start_logging.sh` with the following contents: Let's name the start script `game_start_logging.sh` with the following contents:
``` ```
#!/bin/bash #!/bin/bash
TIMESTAMP=$(date +%Y-%m-%d' '%H:%M:%S) TIMESTAMP=$(date +%Y-%m-%d' '%H:%M:%S)
echo Starting game "\""${2}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt echo Starting game "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt
``` ```
And let's name the end script `game_end_logging.sh` with the following contents: And let's name the end script `game_end_logging.sh` with the following contents:
@ -2068,7 +2041,7 @@ And let's name the end script `game_end_logging.sh` with the following contents:
``` ```
#!/bin/bash #!/bin/bash
TIMESTAMP=$(date +%Y-%m-%d' '%H:%M:%S) TIMESTAMP=$(date +%Y-%m-%d' '%H:%M:%S)
echo "Ending game " "\""${2}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt echo "Ending game " "\""${2}"\"" "\""${4}"\"" "(\""${1}"\")" at $TIMESTAMP >> ~/.emulationstation/game_playlog.txt
``` ```
After creating the two scripts, you should have something like this on the filesystem: After creating the two scripts, you should have something like this on the filesystem:
@ -2083,24 +2056,24 @@ Don't forget to make the scripts executable (e.g. "chmod 755 ./game_start_loggin
If we now start ES-DE with the debug flag and launch a game, something like the following should show up in es_log.txt: If we now start ES-DE with the debug flag and launch a game, something like the following should show up in es_log.txt:
``` ```
Aug 05 14:19:24 Debug: Scripting::fireEvent(): game-start "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" 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" 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:27:15 Debug: Scripting::fireEvent(): game-end "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" 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" 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"
``` ```
Finally after running some games, ~/.emulationstation/game_playlog.txt should contain something like the following: Finally after running some games, ~/.emulationstation/game_playlog.txt should contain something like the following:
``` ```
Starting game "The Legend Of Zelda" ("/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip") at 2020-08-05 14:19:24 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
Ending game "The Legend Of Zelda" ("/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip") at 2020-08-05 14:27:15 Ending game "The Legend Of Zelda" "Nintendo Entertainment System" ("/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip") at 2020-08-05 14:27:15
Starting game "Quake" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 14:38:46 Starting game "Quake" "Ports" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 14:38:46
Ending game "Quake" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 15:13:58 Ending game "Quake" "Ports" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 15:13:58
Starting game "Pirates!" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:15:24 Starting game "Pirates!" "Commodore 64" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:15:24
Ending game "Pirates!" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:17:11 Ending game "Pirates!" "Commodore 64" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:17:11
``` ```
**Resolution changes:** **Resolution changes:**

2
README.md
View file

@ -28,7 +28,7 @@ The following operating systems have been tested (all for the x86 architecture u
* Manjaro 21.1 * Manjaro 21.1
* Fedora 35 Workstation * Fedora 35 Workstation
* elementary OS 6 * elementary OS 6
* Raspberry Pi OS 10 (armv7l and aarch64) * Raspberry Pi OS 10 and 11 (armv7l and aarch64)
* FreeBSD 13.0 * FreeBSD 13.0
* NetBSD 9.1 * NetBSD 9.1
* OpenBSD 6.8 * OpenBSD 6.8

39
USERGUIDE-DEV.md
View file

@ -42,7 +42,7 @@ The following operating systems have been tested (all for the x86 architecture u
* Manjaro 21.1 * Manjaro 21.1
* Fedora 35 Workstation * Fedora 35 Workstation
* elementary OS 6 * elementary OS 6
* Raspberry Pi OS 10 (armv7l and aarch64) * Raspberry Pi OS 10 and 11 (armv7l and aarch64)
* FreeBSD 13.0 * FreeBSD 13.0
* NetBSD 9.1 * NetBSD 9.1
* OpenBSD 6.8 * OpenBSD 6.8
@ -192,11 +192,13 @@ In macOS 12 Monterey there has been a quite serious OpenGL driver bug introduced
## Specific notes for Raspberry Pi ## Specific notes for Raspberry Pi
The Raspberry Pi 4/400 is the minimum recommended version and earlier boards have not been tested. The GPU memory should be set to at least 256 MiB using `raspi-config` and the GL driver must be set to `GL (Fake KMS)` or the performance will be horrible. 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.
The Raspberry Pi 4/400 is the minimum recommended version and earlier boards have not been tested. The GPU memory should be set to at least 256 MiB using `raspi-config` and the GL driver must be set to `GL (Fake KMS)` or the performance will be horrible. On Raspberry Pi OS 11 the KMS option is enabled by default.
In general, 720p works fine with the RPi 4, and 1080p is tolerable but not really a nice and smooth experience. Due to the relative weakness of the Rasperry Pi GPU, the video scanline rendering options for the screensaver and media viewer have been disabled (they're enabled by default on all other platforms). These options can be re-enabled via the menu if you don't mind lower video framerates. In general, 720p works fine with the RPi 4, and 1080p is tolerable but not really a nice and smooth experience. Due to the relative weakness of the Rasperry Pi GPU, the video scanline rendering options for the screensaver and media viewer have been disabled (they're enabled by default on all other platforms). These options can be re-enabled via the menu if you don't mind lower video framerates.
Both the 32-bit (armv7l) and 64-bit (aarch64) versions of Raspberry Pi OS are supported. Although the 64-bit version of ES-DE actually runs much better than the 32-bit version (likely due to better GPU drivers for aarch64) it's still generally recommended to go for the 32-bit OS for now. The reason is that the Raspberry Pi Foundation still has not released the 64-bit version officially so it's somewhat of a beta with some functionality apparently broken. As well there seems to be issues with installing RetroArch cores on aarch64 so you would probably need to compile them from source code. Both the 32-bit (armv7l) and 64-bit (aarch64) versions of Raspberry Pi OS are supported. Although the 64-bit version of ES-DE actually runs much better than the 32-bit version it's still generally recommended to go for the 32-bit OS for now. The reason is that the Raspberry Pi Foundation has still not officially released the 64-bit version of Raspberry Pi OS so it's somewhat of a beta with some functionality apparently broken. As well there seems to be issues with installing RetroArch cores on aarch64 so you would probably need to compile them from source code.
At the time of writing the Snap version of RetroArch appears broken and won't start on the 32-bit OS, so the Flatpak version would have to be installed. That is accomplished using these commands: At the time of writing the Snap version of RetroArch appears broken and won't start on the 32-bit OS, so the Flatpak version would have to be installed. That is accomplished using these commands:
@ -211,7 +213,7 @@ Following this you need to reboot, and then run this command:
sudo flatpak install retroarch sudo flatpak install retroarch
``` ```
This will download and install a few hundred megabytes of data as there are some dependencies. Unfortunately the Flatpak environment does not seem to be properly setup either so you will have to launch RetroArch like this to install your emulator cores: This will download and install a few hundred megabytes of data as there are some dependencies. Unfortunately the Flatpak environment does not seem to be properly setup so you will have to launch RetroArch like this to install your emulator cores:
``` ```
/var/lib/flatpak/exports/bin/org.libretro.RetroArch /var/lib/flatpak/exports/bin/org.libretro.RetroArch
@ -226,7 +228,9 @@ sudo apt-get install snapd
sudo snap install retroarch sudo snap install retroarch
``` ```
Another issue on Raspberry Pi OS is that Sony DualShock 4 controllers have problems with some button presses that don't register correctly. This has not been seen on other Linux operating systems and will hopefully be patched out in the future via an OS update. On Raspberry Pi OS 10 Sony DualShock 4 controllers have problems with some button presses that don't register correctly. The issue appears resolved on Raspberry Pi OS 11.
On Raspberry Pi OS 11 there are various graphics issues and sometimes the application or emulator completely freezes which requires a power cycle of the machine. This is seemingly due to GPU driver bugs and we can only wait for OS updates to address these problems. These issues have not been encountered on Raspberry Pi OS 10.
## Game system customizations ## Game system customizations
@ -260,9 +264,9 @@ If migrating from Batocera or Recalbox, be aware that ES-DE follows the RetroPie
## Running on high resolution displays ## Running on high resolution displays
ES-DE fully supports high resolution displays such as 1440p, 4K, 6K, 8K, ultrawide monitors etc. But some emulators such as 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. On Unix it's possible to start ES-DE with the `--resolution` option to set a lower screen resolution, which will also affect the emulators. But this is not really recommended as it's highly dependent on well-written graphics drivers for proper behavior. ES-DE fully supports high resolution displays such as 1440p, 4K, 6K, 8K, ultrawide monitors etc. But some emulators such as 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 better approach 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 macOS and Windows. 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 macOS and 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.
## Input device configuration ## Input device configuration
@ -858,10 +862,6 @@ A selection of which systems to scrape for. It's possible to automatically scrap
Setup of ScreenScraper account. Setup of ScreenScraper account.
**Use this account for ScreenScraper**
Whether to use the account that has been configured. If this is disabled, the username and password setup on this screen will be ignored during scraping. This can be useful if you have scraping issues and want to check whether it's related to your account or if it's a general problem. Note that screenscraper.fr does not seem to return a proper error message regarding incorrect username and password, but starting ES-DE with the --debug flag will indicate in the log file whether the username was included in the server response.
**ScreenScraper username** **ScreenScraper username**
Username as registered on screenscraper.fr. Username as registered on screenscraper.fr.
@ -870,6 +870,10 @@ Username as registered on screenscraper.fr.
The password as registered on screenscraper.fr. This is masked using asterisks on the screen, and the password input field will be blank when attempting to update an existing password. This is by design and not a bug. Be aware that the es_settings.xml file contains the password in clear text. The password as registered on screenscraper.fr. This is masked using asterisks on the screen, and the password input field will be blank when attempting to update an existing password. This is by design and not a bug. Be aware that the es_settings.xml file contains the password in clear text.
**Use this account for ScreenScraper**
Whether to use the account that has been configured. If this is disabled, the username and password setup on this screen will be ignored during scraping. This can be useful if you have scraping issues and want to check whether it's related to your account or if it's a general problem. Note that screenscraper.fr does not seem to return a proper error message regarding incorrect username and password, but starting ES-DE with the --debug flag will indicate in the log file whether the username was included in the server response.
#### Content settings #### Content settings
Describes the content types to include in the scraping. Describes the content types to include in the scraping.
@ -1352,10 +1356,6 @@ The amount of video RAM to use for the application. Defaults to 256 MiB (184 MiB
This option sets the display to use for ES-DE for multi-monitor setups. The possible values are the monitor index numbers 1, 2, 3 or 4. If a value is set here for a display that does not actually exist, then ES-DE will set it to 1 upon startup. Index 1 is the primary display for the computer. It's also possible to override the setting by passing the --display command line argument. Doing so will also overwrite the display index setting in es_settings.xml. The Display/monitor index option only changes the display used by ES-DE; the emulators need to be configured separately (which can easily be done globally if using RetroArch). This option sets the display to use for ES-DE for multi-monitor setups. The possible values are the monitor index numbers 1, 2, 3 or 4. If a value is set here for a display that does not actually exist, then ES-DE will set it to 1 upon startup. Index 1 is the primary display for the computer. It's also possible to override the setting by passing the --display command line argument. Doing so will also overwrite the display index setting in es_settings.xml. The Display/monitor index option only changes the display used by ES-DE; the emulators need to be configured separately (which can easily be done globally if using RetroArch).
**Fullscreen mode (requires restart)** _(Unix only)_
This gives you a choice between _Normal_ and _Borderless_ modes. With the borderless being more seamless as the ES-DE window will always stay on top of other windows so the taskbar will not be visible when launching and returning from games. It will however break the alt-tab application switching of your window manager. For normal fullscreen mode, if a lower resolution than the screen resolution has been set via the --resolution command line argument, ES-DE will render in full screen at the lower resolution (assuming the graphics drivers support this). If a higher resolution than the screen resolution has been set, ES-DE will run in a window. For the borderless mode, any changes to the resolution will make ES-DE run in a window.
**Exit button combo** **Exit button combo**
This gives the choice of which key combination to use to close the application. The default value is F4, but this can be changed to Alt + F4 on all operating systems. Additionally on macOS the Command + Q combination is selectable and on all other operating systems Alt + Q is selectable instead. Note that on Windows and most window managers on Unix/Linux, Alt + F4 will close the application regardless of the selected option as that key combination is a default which can't be restricted by ES-DE. Similarly on macOS, Command + Q always closes the application, so selecting this combination simply disables the previously selected exit button. This gives the choice of which key combination to use to close the application. The default value is F4, but this can be changed to Alt + F4 on all operating systems. Additionally on macOS the Command + Q combination is selectable and on all other operating systems Alt + Q is selectable instead. Note that on Windows and most window managers on Unix/Linux, Alt + F4 will close the application regardless of the selected option as that key combination is a default which can't be restricted by ES-DE. Similarly on macOS, Command + Q always closes the application, so selecting this combination simply disables the previously selected exit button.
@ -1378,7 +1378,7 @@ Enabling this option makes ES-DE continue to run while a game is launched. This
**AMD and Intel GPU game launch workaround** _(Windows only)_ **AMD and Intel GPU game launch workaround** _(Windows only)_
There is an issue with launching games on some Windows computers, seemingly on those with AMD and Intel GPUs. The emulator will start and work correctly, but the screen will be blank. Enabling this option is a workaround for that problem, with the drawback that the screen will become white instead of black when the emulator is loading. This option is enabled by default, so experiment with disabling it for a slightly better experience. If you're using an Nvidia GPU, chances are high that it will then work fine. An alternative workaround is to enable the _Run in background (while game is launched)_ option described above, so test which gives the best result. The two options can however not be enabled at the same time. Hopefully this whole game launching issue can be resolved completely in a future ES-DE release. There is an issue with launching games on some Windows computers, seemingly on those with AMD or Intel GPUs. The emulator will start and work correctly, but the screen will be blank. Enabling this option is a workaround for that problem, with the drawback that the screen may flicker slightly when launching a game, and there will be a single-pixel transparent line at the bottom of the screen while the emulator is loading. This option is enabled by default, so if you're using an Nvidia GPU you can probably disable this option.
**Upscale video frame rate to 60 FPS** **Upscale video frame rate to 60 FPS**
@ -1402,7 +1402,7 @@ You can mark games as hidden in the metadata editor, which is useful for instanc
**Enable custom event scripts** **Enable custom event scripts**
It's possible to trigger custom scripts for a number of actions in ES-DE, as is discussed [below](USERGUIDE-DEV.md#custom-event-scripts), and this setting decides whether this functionality is enabled. It's recommended to leave it at its default off value unless you need it as it otherwise generates unnecessary log output. It's possible to trigger custom scripts for a number of actions in ES-DE, as is discussed [below](USERGUIDE-DEV.md#custom-event-scripts), and this setting decides whether this functionality is enabled.
**Only show ROMs from gamelist.xml files** **Only show ROMs from gamelist.xml files**
@ -1782,7 +1782,6 @@ https://wiki.batocera.org/themes
_An example of a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme applied to ES-DE._ _An example of a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme applied to ES-DE._
## Custom event scripts ## Custom event scripts
There are numerous locations throughout ES-DE where custom scripts will be executed if the option to do so has been enabled in the settings. By default it's deactivated so be sure to enable it to use this feature. There are numerous locations throughout ES-DE where custom scripts will be executed if the option to do so has been enabled in the settings. By default it's deactivated so be sure to enable it to use this feature.
@ -1876,7 +1875,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| daphne | Daphne Arcade Laserdisc Emulator | | | | | | daphne | Daphne Arcade Laserdisc Emulator | | | | |
| desktop | Desktop applications | N/A | | No | | | desktop | Desktop applications | N/A | | No | |
| doom | Doom | PrBoom | | | | | doom | Doom | PrBoom | | | |
| dos | DOS (PC) | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [UM] | No | In separate folder (one folder per game, with complete file structure retained) | | dos | DOS (PC) | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [U] | No | In separate folder (one folder per game, with complete file structure retained) |
| dragon32 | Dragon 32 | | | | | | dragon32 | Dragon 32 | | | | |
| dreamcast | Sega Dreamcast | Flycast | | | | | dreamcast | Sega Dreamcast | Flycast | | | |
| epic | Epic Games Store | Epic Games Store application **(Standalone)** | | No | Shell script/batch file in root folder | | epic | Epic Games Store | Epic Games Store application **(Standalone)** | | No | Shell script/batch file in root folder |
@ -1928,7 +1927,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| openbor | OpenBOR game engine | | | | | | openbor | OpenBOR game engine | | | | |
| oric | Tangerine Computer Systems Oric | | | | | | oric | Tangerine Computer Systems Oric | | | | |
| palm | Palm OS | Mu | | | | | palm | Palm OS | Mu | | | |
| pc | IBM PC | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [UM] | No | In separate folder (one folder per game, with complete file structure retained) | | pc | IBM PC | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [U] | No | In separate folder (one folder per game, with complete file structure retained) |
| pc88 | NEC PC-8800 series | QUASI88 | | | | | pc88 | NEC PC-8800 series | QUASI88 | | | |
| pc98 | NEC PC-9800 series | Neko Project II Kai | Neko Project II | | | | pc98 | NEC PC-9800 series | Neko Project II Kai | Neko Project II | | |
| pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST | No | Single archive or ROM file in root folder | | pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST | No | Single archive or ROM file in root folder |