From 8f2311da4b4444b5513230625e458fd2259efd7a Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Tue, 23 Nov 2021 21:51:06 +0100 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 2 ++ INSTALL-DEV.md | 84 +++++++++++++++++++++++++++++++----------------- USERGUIDE-DEV.md | 21 ++++++++++-- 3 files changed, 74 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d6174f00..214eef980 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 * 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 \ tag for es_systems.xml that can be used to override the default \ 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 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) diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 94b89ff0d..2dc34d3a5 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -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: ``` -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: @@ -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. --> "%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM% - - bash %ROM% + + %RUNINBACKGROUND% bash %ROM% - %HIDEWINDOW% cmd /C %ROM% + The optional %HIDEWINDOW% variable is used to hide the console window, which would otherwise be visible when launching games. --> + %HIDEWINDOW% %RUNINBACKGROUND% cmd.exe /C %ROM% - - yuzu - org.yuzu_emu.yuzu - yuzu.AppImage - - - /var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu - ~/Applications/yuzu.AppImage - ~/.local/bin/yuzu.AppImage - ~/bin/yuzu.AppImage - - @@ -1768,29 +1758,53 @@ Here's an example es_find_rules.xml file for Unix: /usr/pkg/lib/libretro + + + dosbox-staging + io.github.dosbox-staging + + + /var/lib/flatpak/exports/bin/io.github.dosbox-staging + + + + + + yuzu + org.yuzu_emu.yuzu + yuzu.AppImage + + + /var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu + ~/Applications/yuzu.AppImage + ~/.local/bin/yuzu.AppImage + ~/bin/yuzu.AppImage + + ``` -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: ```xml -%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% +%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% ``` 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. -The `winregistrypath` rule searches the Windows Registry "App Paths" keys for the emulators defined in the `` 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 `` 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 `` 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 `` 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. @@ -1821,6 +1835,11 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo /Applications/RetroArch.app/Contents/Resources/cores + + + /Applications/dosbox-staging.app/Contents/MacOS/dosbox + + ``` @@ -1846,6 +1865,11 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo C:\Program Files\RetroArch\retroarch.exe C:\Program Files (x86)\RetroArch-Win64\retroarch.exe C:\Program Files (x86)\RetroArch\retroarch.exe + + 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 %ESPATH%\RetroArch-Win64\retroarch.exe %ESPATH%\RetroArch\retroarch.exe @@ -1853,6 +1877,11 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo %ESPATH%\..\RetroArch\retroarch.exe + + + %EMUPATH%\cores + + @@ -1865,11 +1894,6 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo %ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe - - - %EMUPATH%\cores - - ``` diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 139d5fb51..0bd46cbe9 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -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._ +## 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 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** -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** @@ -1844,7 +1859,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**) | daphne | Daphne Arcade Laserdisc Emulator | | | | | | desktop | Desktop applications | N/A | | No | | | doom | Doom | PrBoom | | | | -| dos | DOS (PC) | DOSBox-Core | DOSBox-Pure,
DOSBox-SVN | No | In separate folder (one folder per game, with complete file structure retained) | +| dos | DOS (PC) | DOSBox-Core | DOSBox-Pure,
DOSBox-SVN,
DOSBox Staging **(Standalone)** [UM] | No | In separate folder (one folder per game, with complete file structure retained) | | dragon32 | Dragon 32 | | | | | | dreamcast | Sega Dreamcast | Flycast | | | | | 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 | | | | | | oric | Tangerine Computer Systems Oric | | | | | | palm | Palm OS | Mu | | | | -| pc | IBM PC | DOSBox-Core | DOSBox-Pure,
DOSBox-SVN | No | In separate folder (one folder per game, with complete file structure retained) | +| pc | IBM PC | DOSBox-Core | DOSBox-Pure,
DOSBox-SVN,
DOSBox Staging **(Standalone)** [UM] | No | In separate folder (one folder per game, with complete file structure retained) | | pc88 | NEC PC-8800 series | QUASI88 | | | | | 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 |