From 2de5ae8cfba0c389eb252d3ee0cca415eeeb8b81 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Sun, 20 Jun 2021 14:38:10 +0200 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 17 ++- INSTALL-DEV.md | 154 ++++++++++++++++++-- USERGUIDE-DEV.md | 6 +- resources/systems/windows/es_find_rules.xml | 2 +- 4 files changed, 152 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1da9b210b..7f2975c5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,12 @@ ### Release overview +The 1.1 release brings several large changes including a fullscreen media viewer, a game launch screen, a miximage generator, a new video player, a new controller API featuring automatic controller configuration and controller profiles, and a better mechanism to find emulators and emulator cores. + +Refer to the User guide for in-depth explanations of the new functionality. + +Apart from this, many small improvements and bug fixes are part of the release, as detailed below. + ### Detailed list of changes * Added a miximage generator that can be run automatically from the scraper and which includes comprehensive options, configurable from the menu @@ -16,8 +22,10 @@ * Added a game launch screen that displays the marquee image, the game name and the system name * Added a new video player based on FFmpeg * Added a 60 FPS frame rate upscaler option to the video player which results in slightly smoother playback for low frame rate videos (e.g. 24 and 30 FPS) +* Implemented a new mechanism for locating emulators and cores, with configurable find rules (this eliminates some hacks such as the separate Flatpak es_systems.cfg file) +* Removed the deprecated %COREPATH% setting and corresponding menu entry * Moved to the SDL GameController API which gives numerous improvements to the controller handling -* Default controller configuration is now applied, input configuration should rarely if ever be required any longer except for deliberate button customization +* Default controller configuration is now automatically applied, input configuration should rarely if ever be required any longer except for deliberate button customization * Added support for selecting the controller type (Xbox, Xbox 360, PS4, PS5 and SNES), which changes the help icons, help text and the input configuration tool icons and text * Added an option to limit the input in ES-DE to only the first controller (does not affect the emulators) * Removed the startup notification regarding default keyboard mappings being in use, instead default mappings are now considered the recommended input configuration @@ -32,15 +40,14 @@ * Moved the video screensaver audio setting to the sound settings menu * Created a new main menu entry for input device settings * Moved the input device configuration tool to the input device settings menu -* Added a utilities menu entry to the main menu * Adjusted the size and position of the various menus to accomodate one additional entry on the screen * The quit menu is now disabled by default, instead showing the "Quit EmulationStation" entry unless configured otherwise * Renamed es_systems.cfg, es_settings.cfg and es_input.cfg to es_systems.xml, es_settings.xml and es_input.xml * Changed the es_systems.xml logic so it loads from the program resources directory by default (a customized file can be placed in ~/.emulationstation/custom_systems) * Removed the marquee image from rbsimple-DE as it's now baked into the miximages -* Set the gamelist video scanline rendering option as disabled by default +* Set the gamelist video scanline rendering option to disabled by default * Changed the setting description for the favorites game toggling button -* Added the CImg library as a Git subtree and created some utility functions for it (used primarily by the miximage generator) +* Added the CImg library as a Git subtree and created some utility functions for it (used by the miximage generator and the game launch screen) * Added a function to ImageComponent to crop fully transparent areas around an image * Added the NanoSVG library as a proper Git subtree * Changed the language standard from C++11 to C++14 @@ -49,7 +56,7 @@ * On Windows, images with Unicode characters in the game name that were resized when scraping would not be saved with valid filenames * The glitches when configuring trigger buttons in GuiInputConfig have been fixed -* GuiDetectDevice wouldn't detect controller input that was of the 'axis' type (i.e. analog inputs) +* GuiDetectDevice wouldn't detect controller input that was of the "axis" type (i.e. analog inputs) * GuiInputConfig didn't correctly inform which buttons could be skipped for some rows * The scraper would sometimes consider very small images to be invalid * The Quick System Select help prompt was shown even when there was only a single game system present diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index d88a99ce3..32773497d 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -1316,9 +1316,11 @@ The es_systems.xml file contains the system configuration data for ES-DE, writte ES-DE ships with a comprehensive `es_systems.xml` configuration file and normally you shouldn't need to modify this. However there may be special circumstances such as wanting to use alternative emulators for some game systems or perhaps you need to add additional systems altogether. -To make a customized version of the systems configuration file, it first needs to be copied to `~/.emulationstation/custom_systems/es_systems.xml`. The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows. +To make a customized version of the systems configuration file, it first needs to be copied to `~/.emulationstation/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows.) -The bundled es_systems.xml file which is used by default is located in the resources directory that is part of the application installation. For example this could be `/usr/share/emulationstation/resources/systems/unix/es_systems.xml` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/systems/macos/es_systems.xml` on macOS and `C:\Program Files\EmulationStation-DE\resources\systems\windows\es_systems.xml` on Windows. The actual location may differ from these examples of course, depending on where ES-DE has been installed. +The bundled es_systems.xml file is located in the resources directory that is part of the application installation. For example this could be `/usr/share/emulationstation/resources/systems/unix/es_systems.xml` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/systems/macos/es_systems.xml` on macOS and `C:\Program Files\EmulationStation-DE\resources\systems\windows\es_systems.xml` on Windows. The actual location may differ from these examples of course, depending on where ES-DE has been installed. + +Note that when copying the bundled es_systems.xml file to ~/.emulationstation/custom_systems/, it will completely replace the default file. So when upgrading to future ES-DE versions, any modifications such as additional game systems will not be enabled until the customized configuration file has been manually updated. It doesn't matter in which order you define the systems as they will be sorted by the full system name inside the application, but it's still probably a good idea to add them in alphabetical order to make the file easier to maintain. @@ -1345,21 +1347,25 @@ Below is an overview of the file layout with various examples. For a real system %ROMPATH%/snes + You must include the period at the start of the extension and it's also case sensitive. --> .smc .SMC .sfc .SFC .swc .SWC .fig .FIG .bs .BS .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% + + retroarch -L ~/.config/retroarch/cores/snes9x_libretro.so %ROM% - - retroarch -L %COREPATH%/snes9x_libretro.so %ROM% + + retroarch -L %CORE_RETROARCH%/snes9x_libretro.so %ROM% - - /Applications/RetroArch.app/Contents/MacOS/RetroArch -L %COREPATH%/snes9x_libretro.dylib %ROM% + + /Applications/RetroArch.app/Contents/MacOS/RetroArch -L %CORE_RETROARCH%/snes9x_libretro.dylib %ROM% + + + + retroarch + + + /var/lib/flatpak/exports/bin/org.libretro.RetroArch + + + + + + ~/.config/retroarch/cores + + ~/snap/retroarch/current/.config/retroarch/cores + + ~/.var/app/org.libretro.RetroArch/config/retroarch/cores + + /usr/lib/x86_64-linux-gnu/libretro + + /usr/lib64/libretro + + /usr/lib/libretro + + /usr/local/lib/libretro + + /usr/pkg/lib/libretro + + + +``` + +It's pretty straightforward, there are currently two rules supported for finding emulators, `systempath` and `staticpath` and there is one rule supported for finding the emulator cores, `corepath`. More advanced find rules may be added in future ES-DE versions. + +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% +``` + +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 nice). + +Of course this makes it possible to add any number of emulators to the configuration file if not only using RetroArch. + +The rules are probably self-explanatory with `systempath` searching the PATH environment variable for the binary names defined by the `` tags and `staticpath` defining absolute paths to the emulator. For staticpath, the actual emulator binary must also be included in the entry tag. + +The `corepath` rule is simply a path to search for the emulator core. + +Each rule supports multiple entry tags which are tried in the order that they are defined in the file until there is a match. + +The %EMUPATH% and %ESPATH% variables can also be used inside the entry tags, making for quite powerful find rules. + +The tilde symbol `~` is supported and will expand to the user home directory. + +For reference, here are also example es_find_rules.xml files for macOS and Windows: + +```xml + + + + + + /Applications/RetroArch.app/Contents/MacOS/RetroArch + + + + + + ~/Library/Application Support/RetroArch/cores + + /Applications/RetroArch.app/Contents/Resources/cores + + + +``` + +```xml + + + + + + + retroarch.exe + + + + C:\RetroArch-Win64\retroarch.exe + C:\RetroArch\retroarch.exe + C:\Program Files\RetroArch-Win64\retroarch.exe + C:\Program Files\RetroArch\retroarch.exe + C:\Program Files (x86)\RetroArch-Win64\retroarch.exe + C:\Program Files (x86)\RetroArch\retroarch.exe + + %ESPATH%\..\RetroArch\retroarch.exe + + + + + %EMUPATH%\cores + + + ``` diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 8fd913c69..e2e4ed0ba 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -300,7 +300,7 @@ Here is the snippet from the unix/es_systems.xml file: Nintendo Entertainment System %ROMPATH%/nes .nes .NES .unf .UNF .unif .UNIF .7z .7Z .zip .ZIP - retroarch -L %COREPATH%/nestopia_libretro.so %ROM% + %EMULATOR_RETROARCH% -L %CORE_RETROARCH%/nestopia_libretro.so %ROM% nes nes @@ -1152,10 +1152,6 @@ The metadata for a game is updated by scraping and by manual editing (using the This setting defines the directory for the game media, i.e. game images and videos. The default location is _~/.emulationstation/downloaded_media_ -**Emulator core path** - -This setting defines the path for which to search for emulator cores. This is used by the variable %COREPATH% which can be included in the systems configuration file es_systems.xml. For example it is used on Unix where the core path may vary depending on the operating system, how the emulator was packaged etc. For example the default RetroArch core directory is ~/.config/retroarch/cores if compiled from source code but if installed as a Snap package or as part of the OS repository the cores could be stored elsewhere. The setting is primarily intended for RetroArch but it can be used for any emulator that utilizes discrete emulator cores. When attempting to launch a game, the core for the game system will be searched in each of the defined directories until the first match occurs. Multiple directories can be defined by separating them using colons on Unix and macOS and by semicolons on Windows. Please see [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml) for more information about this. - **Hide taskbar (requires restart)** _(Windows only)_ With this setting enabled, the taskbar will be hidden when launching ES-DE, and it will be restored when the application exits. This can make for a more seamless experience as the taskbar could otherwise flash by briefly when launching games and when returning from games. It could potentially cause some issues on some Windows installations though, so the option is disabled by default. diff --git a/resources/systems/windows/es_find_rules.xml b/resources/systems/windows/es_find_rules.xml index a42bbb564..88219f349 100644 --- a/resources/systems/windows/es_find_rules.xml +++ b/resources/systems/windows/es_find_rules.xml @@ -3,7 +3,7 @@ - + retroarch.exe