Documentation update.

This commit is contained in:
Leon Styhre 2021-11-23 21:51:06 +01:00
parent d61218a24f
commit 8f2311da4b
3 changed files with 74 additions and 33 deletions

View file

@ -36,6 +36,8 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac
* 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
* 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 %RUNINBACKGROUND% es_systems.xml variable and removed the hardcoded run in background logic for the Valve Steam system
* Added menu scroll indicators showing if there are additional entries available below or above what's currently shown on screen * Added menu scroll indicators showing if there are additional entries available below or above what's currently shown on screen
* Added scraping of controller metadata (only for ScreenScraper and only for arcade systems) * Added scraping of controller metadata (only for ScreenScraper and only for arcade systems)
* Improved the layout of the scraper GUIs (single-game scraper and multi-scraper) * Improved the layout of the scraper GUIs (single-game scraper and multi-scraper)

View file

@ -47,7 +47,7 @@ https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -
Then you can use dnf to install all the required packages: Then you can use dnf to install all the required packages:
``` ```
sudo dnf install gcc-c++ clang-tools-extra cmake SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel sudo dnf install gcc-c++ clang-tools-extra cmake rpm-build SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel
``` ```
If building with the optional VLC video player, the following packages are also needed: If building with the optional VLC video player, the following packages are also needed:
@ -1555,12 +1555,14 @@ Below is an overview of the file layout with various examples. For the command t
expanded to the directory of the ES-DE executable. --> expanded to the directory of the ES-DE executable. -->
<command>"%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM%</command> <command>"%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM%</command>
<!-- An example on Unix which launches a script, this is for example used by source ports, Steam games etc. --> <!-- An example on Unix which launches a script, this is for example used by source ports, Steam games etc. The %RUNINBACKGROUND%
<command>bash %ROM%</command> variable does exactly what it sounds like, it keeps ES-DE running in the background while a game is launched. This is required
for launching Steam games properly. -->
<command>%RUNINBACKGROUND% bash %ROM%</command>
<!-- The equivalent configuration as above, but for Windows. <!-- The equivalent configuration as above, but for Windows.
The optional %HIDEWINDOW% variable is used to hide the console window, which would otherwise be visible when launching the game. --> The optional %HIDEWINDOW% variable is used to hide the console window, which would otherwise be visible when launching games. -->
<command>%HIDEWINDOW% cmd /C %ROM%</command> <command>%HIDEWINDOW% %RUNINBACKGROUND% cmd.exe /C %ROM%</command>
<!-- The platform(s) to use when scraping. You can see the full list of supported platforms in es-app/src/PlatformId.cpp. <!-- The platform(s) to use when scraping. You can see the full list of supported platforms in es-app/src/PlatformId.cpp.
The entry is case insensitive as it will be converted to lower case during startup. The entry is case insensitive as it will be converted to lower case during startup.
@ -1597,7 +1599,9 @@ The following variables are expanded for the `command` tag:
`%CORE_` - This utilizes the core find rules as defined in `es_find_rules.xml`. This is the recommended way to configure the launch command. `%CORE_` - This utilizes the core find rules as defined in `es_find_rules.xml`. This is the recommended way to configure 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 the game. It needs to be placed first in the command tag. `%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.
Here are some additional real world examples of system entries, the first one for Unix: Here are some additional real world examples of system entries, the first one for Unix:
@ -1734,20 +1738,6 @@ Here's an example es_find_rules.xml file for Unix:
<entry>~/bin/RetroArch-Linux-x86_64.AppImage</entry> <entry>~/bin/RetroArch-Linux-x86_64.AppImage</entry>
</rule> </rule>
</emulator> </emulator>
<emulator name="YUZU">
<!-- Nintendo Switch emulator Yuzu -->
<rule type="systempath">
<entry>yuzu</entry>
<entry>org.yuzu_emu.yuzu</entry>
<entry>yuzu.AppImage</entry>
</rule>
<rule type="staticpath">
<entry>/var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu</entry>
<entry>~/Applications/yuzu.AppImage</entry>
<entry>~/.local/bin/yuzu.AppImage</entry>
<entry>~/bin/yuzu.AppImage</entry>
</rule>
</emulator>
<core name="RETROARCH"> <core name="RETROARCH">
<rule type="corepath"> <rule type="corepath">
<!-- Snap package --> <!-- Snap package -->
@ -1768,29 +1758,53 @@ Here's an example es_find_rules.xml file for Unix:
<entry>/usr/pkg/lib/libretro</entry> <entry>/usr/pkg/lib/libretro</entry>
</rule> </rule>
</core> </core>
<emulator name="DOSBOX_STAGING">
<rule type="systempath">
<entry>dosbox-staging</entry>
<entry>io.github.dosbox-staging</entry>
</rule>
<rule type="staticpath">
<entry>/var/lib/flatpak/exports/bin/io.github.dosbox-staging</entry>
</rule>
</emulator>
<emulator name="YUZU">
<!-- Nintendo Switch emulator Yuzu -->
<rule type="systempath">
<entry>yuzu</entry>
<entry>org.yuzu_emu.yuzu</entry>
<entry>yuzu.AppImage</entry>
</rule>
<rule type="staticpath">
<entry>/var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu</entry>
<entry>~/Applications/yuzu.AppImage</entry>
<entry>~/.local/bin/yuzu.AppImage</entry>
<entry>~/bin/yuzu.AppImage</entry>
</rule>
</emulator>
</ruleList> </ruleList>
``` ```
It's pretty straightforward, there are currently three rules supported for finding emulators, `winregistrypath`, `systempath` and `staticpath` and there is one rule supported for finding the emulator cores, `corepath`. It's pretty straightforward, there are currently four rules supported for finding emulators, `winregistrypath`, `winregistryvalue`, `systempath` and `staticpath` and there is one rule supported for finding the emulator cores, `corepath`.
Of these, `winregistrypath` is only available on Windows, and attempting to use the rule on any other operating system will generate a warning in the log file when processing the es_find_fules.xml file. Of these, `winregistrypath` and `winregistryvalue` are only available on Windows, and attempting to use the rule on any other operating system will generate a warning in the log file when processing the es_find_rules.xml file.
The `name` attribute must correspond to the command tags in es_systems.xml, take for example this line: The `name` attribute must correspond to the command tags in es_systems.xml, take for example this line:
```xml ```xml
<command>%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM%</command> <command label="DOSBox-Core">%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM%</command>
``` ```
Here %EMULATOR_ and %CORE_ are followed by the string RETROARCH which corresponds to the name attribute in es_find_rules.xml. The name is case sensitive but it's recommended to use uppercase names to make the variables feel consistent (%EMULATOR_retroarch% doesn't look so pretty). Here %EMULATOR_ and %CORE_ are followed by the string RETROARCH which corresponds to the name attribute in es_find_rules.xml. The name is case sensitive but it's recommended to use uppercase names to make the variables feel consistent (%EMULATOR_retroarch% doesn't look so pretty).
Of course this makes it possible to add any number of emulators to the configuration file. Of course this makes it possible to add any number of emulators to the configuration file.
The `winregistrypath` rule searches the Windows Registry "App Paths" keys for the emulators defined in the `<entry>` tags. If for example this tag is set to `retroarch.exe`, the key `SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\retroarch.exe` will be searched for. HKEY_CURRENT_USER is tried first, and if no key is found there, HKEY_LOCAL_MACHINE is tried as well. In addition to this, ES-DE will check that the binary defined in the key actually exists, and if not, it will proceed with the next rule. Be aware that the App Paths keys are added by the emulators during their installation, and although RetroArch does add this key, not all emulators do. The `winregistrypath` rule searches the Windows Registry "App Paths" keys for the emulators defined in the `<entry>` tags. If for example this tag is set to `retroarch.exe`, a search will be performed for the key `SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\retroarch.exe`. HKEY_CURRENT_USER is tried first, and if no key is found there, HKEY_LOCAL_MACHINE is tried as well. In addition to this, ES-DE will check that the binary defined in the default value for the key actually exists. If not, it will proceed with the next rule. Be aware that the App Paths keys are added by the emulators during their installation, and although RetroArch does add this key, not all emulators do.
The `winregistryvalue` rule will search for the specific registry value, and if it exists, it will use that value as the path to the emulator binary. HKEY_CURRENT_USER will be tried first, followed by HKEY_LOCAL_MACHINE. In the same manner as `winregistrypath`, ES-DE will check that the binary defined in the registry value actually exists. If not, it will proceed with the next rule. For example, if setting the `<entry>` tag for this rule to `SOFTWARE\Valve\Steam\SteamExe`, the emulator binary would be set to `c:\program files (x86)\steam\steam.exe`, assuming that's where Steam has been installed. As this rule can be used to query any value in the Registry, it's a quite powerful tool to locate various emulators and applications.
The other rules are probably self-explanatory with `systempath` searching the PATH environment variable for the binary names defined by the `<entry>` tags and `staticpath` defines absolute paths to the emulators. For staticpath, the actual emulator binary must be included in the entry tag. The other rules are probably self-explanatory with `systempath` searching the PATH environment variable for the binary names defined by the `<entry>` tags and `staticpath` defines absolute paths to the emulators. For staticpath, the actual emulator binary must be included in the entry tag.
The winregistrypath rules are always processed first, followed by systempath and then staticpath. This is done regardless of which order they are defined in the es_find_rules.xml file. The winregistrypath rules are always processed first, followed by winregistryvalue, then systempath and finally staticpath. This is done regardless of which order they are defined in the es_find_rules.xml file.
As for `corepath` this rule is simply a path to search for the emulator core. As for `corepath` this rule is simply a path to search for the emulator core.
@ -1821,6 +1835,11 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
<entry>/Applications/RetroArch.app/Contents/Resources/cores</entry> <entry>/Applications/RetroArch.app/Contents/Resources/cores</entry>
</rule> </rule>
</core> </core>
<emulator name="DOSBOX_STAGING">
<rule type="staticpath">
<entry>/Applications/dosbox-staging.app/Contents/MacOS/dosbox</entry>
</rule>
</emulator>
</ruleList> </ruleList>
``` ```
@ -1846,6 +1865,11 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
<entry>C:\Program Files\RetroArch\retroarch.exe</entry> <entry>C:\Program Files\RetroArch\retroarch.exe</entry>
<entry>C:\Program Files (x86)\RetroArch-Win64\retroarch.exe</entry> <entry>C:\Program Files (x86)\RetroArch-Win64\retroarch.exe</entry>
<entry>C:\Program Files (x86)\RetroArch\retroarch.exe</entry> <entry>C:\Program Files (x86)\RetroArch\retroarch.exe</entry>
<!-- Steam release at some default locations -->
<entry>C:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe</entry>
<entry>D:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe</entry>
<entry>C:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe</entry>
<entry>D:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe</entry>
<!-- Portable installation --> <!-- Portable installation -->
<entry>%ESPATH%\RetroArch-Win64\retroarch.exe</entry> <entry>%ESPATH%\RetroArch-Win64\retroarch.exe</entry>
<entry>%ESPATH%\RetroArch\retroarch.exe</entry> <entry>%ESPATH%\RetroArch\retroarch.exe</entry>
@ -1853,6 +1877,11 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
<entry>%ESPATH%\..\RetroArch\retroarch.exe</entry> <entry>%ESPATH%\..\RetroArch\retroarch.exe</entry>
</rule> </rule>
</emulator> </emulator>
<core name="RETROARCH">
<rule type="corepath">
<entry>%EMUPATH%\cores</entry>
</rule>
</core>
<emulator name="YUZU"> <emulator name="YUZU">
<!-- Nintendo Switch emulator Yuzu --> <!-- Nintendo Switch emulator Yuzu -->
<rule type="systempath"> <rule type="systempath">
@ -1865,11 +1894,6 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
<entry>%ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe</entry> <entry>%ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
</rule> </rule>
</emulator> </emulator>
<core name="RETROARCH">
<rule type="corepath">
<entry>%EMUPATH%\cores</entry>
</rule>
</core>
</ruleList> </ruleList>
``` ```

View file

@ -143,6 +143,21 @@ There will be a lot of directories created if using the es_systems.xml file bund
_This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._ _This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._
## Using the Steam release of RetroArch
On Windows it's no problem to use the Steam release of RetroArch although you may have to add the location manually to your Path environment variable. By default the following locations will be searched:
```
C:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
D:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
C:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
D:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
```
If you have installed RetroArch at another location, simply start the Settings application, search for _path_ in the _Find a setting_ field and choose _Edit environment variables for your account_. Edit the _Path_ variable and add the directory where RetroArch is installed. This is required as there is no apparent way for ES-DE to find where RetroArch has been installed by the Steam application.
Unfortunately on Linux it's at the moment not possible to run the Steam release of RetroArch due to technical reasons. This RetroArch release runs as a type of container which can't be executed from ES-DE while correctly passing the necessary core and game options. Similarly it's not possible to launch RetroArch via the Steam application either as there seems to be a bug in Steam or RetroArch that prevents blankspaces from being present in game ROM files when passed as arguments (this works fine on Windows so it's definitely a Linux-specific issue and as well the same problem occurs if attempting to manually enter the launch command from a terminal window).
## Specific notes for macOS ## Specific notes for macOS
On macOS, the first time you launch a game from within ES-DE, the operating system will present you with a security option with the following description: On macOS, the first time you launch a game from within ES-DE, the operating system will present you with a security option with the following description:
@ -1246,7 +1261,7 @@ This setting gives the ability to choose between the controller types _Xbox, Xbo
**Only accept input from first controller** **Only accept input from first controller**
If enabling this option, only the first controller detected during startup will send its input to ES-DE. This is a good way to limit potential chaos with mutliple users fighting over which games to start. 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. 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 start. 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.
**Configure keyboard and controllers** **Configure keyboard and controllers**
@ -1844,7 +1859,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 | 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)** [UM] | 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 |
@ -1896,7 +1911,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 | 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)** [UM] | 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 |