From 4c82d55aec888e8b6b53818582237115c6db8112 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Mon, 27 Dec 2021 16:52:21 +0100 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 23 +++++++++++++---------- CONTRIBUTING.md | 14 +++++++------- INSTALL-DEV.md | 4 ++-- USERGUIDE-DEV.md | 20 ++++++++++++++------ 4 files changed, 36 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ef9d90d91..c348a6322 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ ### Release overview -The 1.2 release introduces multiple new features and brings extensive bug fixing and lots of other small improvements. Support for alternative emulators has been added which can be selected system-wide or per game. These alternative emulators are added to the es_systems.xml file, making it easy to expand or customize the configuration. For this release, most of the available RetroArch cores have been preconfigured. +The 1.2 release introduces multiple new features and brings extensive bug fixing and lots of other small improvements. Support for alternative emulators has been added which can be selected system-wide or per game. These alternative emulators are added to the es_systems.xml file, making it easy to expand or customize the configuration. For this release most of the available RetroArch cores have been preconfigured, and a couple of standalone emulators have been included as well. A virtual keyboard has been added (some code borrowed from Batocera.linux) which is fully integrated and can be used to input text via a game controller. By introducing this feature, a keyboard should now be completely optional for day-to-day use. @@ -33,7 +33,7 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac * Added an option to rotate horizontally oriented game boxes 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) -* Bundled the new alternative theme "modern-DE" which supports all the latest features from this release +* Bundled a new alternative theme "modern-DE" which supports all the latest features from this release * Changed the Unix fullscreen mode and removed the --windowed, --fullscreen-normal and --fullscreen-borderless command line options * Removed the Unix-specific menu option "Fullscreen mode (requires restart)" * Changed the Windows fullscreen mode and removed the "AMD and Intel GPU game launch workaround" menu option @@ -77,20 +77,20 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac * Made large optimizations to the SVG rendering which reduces application startup time dramatically when many systems are populated * Changed to loading the default theme set rbsimple-DE instead of the first available theme if the currently configured theme set is missing * Added support for displaying the left and right trigger buttons in the help prompts -* Removed the "Choose" entry from the help prompts in the gamelist view +* Removed the "Choose" entry from the gamelist view help prompts * Replaced a number of help prompt hacks with proper solutions * Changed the "Toggle screensaver" help entry in the system view to simply "Screensaver" * 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 -* 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 gamelist views * Made the window corners slightly more rounded * 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 ScreenScraper account toggle to the bottom of the scraper account settings menu * 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 -* (macOS) Disabled the application startup animations as they were very choppy and looked bad after moving to SDL 2.0.18 -* Changed the filter description "Text filter (game name)" to simply "Game name" +* Disabled the application startup animations on macOS as they were very choppy and looked bad after moving to SDL 2.0.18 +* Changed the filter description "Text filter (game name)" to simply "Game name" and a keyboard icon * Removed a margin hack from 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 @@ -124,11 +124,12 @@ 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 * Added CMake options to build with AddressSanitizer, ThreadSanitizer and UndefinedBehaviorSanitizer * Changed two clang-format rules related to braced lists and reformatted the codebase -* Upgraded the bundled SDL version 2.0.14 to 2.0.18 for Windows and macOS +* Upgraded the bundled SDL version 2.0.14 to 2.0.18 on Windows and macOS * 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 -* rbsimple-DE: Added some missing graphics for the xbox360 and residualvm systems -* rbsimple-DE: Improved existing graphics for the dos, pc, residualvm and scummvm systems +* rbsimple-DE: Added some missing graphics for the xbox360 system +* rbsimple-DE: Improved existing graphics for the dos, pc and scummvm systems +* rbsimple-DE: Updated the info text for most systems ### Bug fixes @@ -149,14 +150,16 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac * (Windows) Launching a game that changed the screen resolution would offset the ES-DE application window when exiting * (Windows) Enabling the option to hide the taskbar would sometimes not focus the application window on startup (possibly only an issue on Windows 8.1) * If there were gamelist.xml entries for existing files whose extensions were not setup in es_systems.xml, these would still get loaded and displayed -* Fixed multiple minor rendering issues where graphics would be slightly cut off or incorrectly resized +* Fixed multiple minor rendering issues where graphics would be slightly cut off or incorrectly sized * Under some circumstances ScrollableContainer (used for the game descriptions) would contain a partially rendered bottom line * If the TextListComponent height was not evenly dividable by the font height + line spacing, a partial bottom row would get rendered * The line spacing for TextListComponent was incorrectly calculated for some resolutions such as 2560x1440 * Fixed multiple issues with scaling of images which led to various inconsistencies and sometimes cut-off graphics * The system time zone was not taken into consideration when using the Unix epoch which lead to various strange problems in the metadata editor * Removing games from custom collections did not remove their filter index entries +* Enabling the All Games collection lead to a potentially large memory leak under some circumstances * Input consisting of only whitespace characters would get accepted by TextEditComponent which led to various strange behaviors +* Leading and trailing whitespace characters would not get trimmed from the ROM directory when entering this during initial setup * Leading and trailing whitespace characters would not get trimmed from the collection name when creating a new custom collection * Leading and trailing whitespace characters would get included in scraper search refines and TheGamesDB searches * Leading and trailing whitespace characters would get included in game name filters diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a23ad47b..1651a49ff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,13 +50,13 @@ The roadmap is under constant review so expect it to change from time to time. S #### _v1.2_ -* Support for pre-defined alternative emulators and cores (configured in es_systems.xml) -* Badges highlighting things like favorite games, completed games etc. (will require theme support) -* Virtual (on-screen) keyboard -* Support for the Raspberry Pi 4 (Raspberry Pi OS) -* Improve fullscreen support and make game launching more seamless, remove the temporary fullscreen hacks -* Add GLM library dependency for matrix and vector operations, decommission the built-in functions -* AppImage and AUR releases on Linux +* _Support for pre-defined alternative emulators and cores (configured in es_systems.xml)_ +* _Badges highlighting things like favorite games, completed games etc. (will require theme support)_ +* _Virtual (on-screen) keyboard_ +* _Support for the Raspberry Pi 4 (Raspberry Pi OS)_ +* _Improve fullscreen support and make game launching more seamless, remove the temporary fullscreen hacks_ +* _Add GLM library dependency for matrix and vector operations, decommission the built-in functions_ +* _AppImage and AUR releases on Linux_ #### v1.3 diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index b4dbdd880..d138fa085 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -1717,7 +1717,7 @@ Of course this makes it possible to add any number of emulators to the configura 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 `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. In addition to this it's posssible to append an arbitrary string to the key value if it's found and use that as the emulator binary path. This is accomplished by using the pipe sign, so for example the entry `SOFTWARE\PCSX2\Install_Dir|\pcsx2.exe` will look for the key `SOFTWARE\PCSX2\Install_Dir` and if it's found it will take the value of that key and append the string `\pcsx2.exe` to it. This could for example result in `C:\Program Files (x86)\PCSX2\pcsx2.exe`. Also for this setup, ES-DE will check that the emulator binary actually exists, or it will proceed to the next rule. 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. @@ -2066,7 +2066,7 @@ We'll go through two examples: * Creating a log file that will record the start and end time for each game we play, letting us see how much time we spend on retro-gaming * Changing the system resolution when launching and returning from a game in order to run the emulator at a lower resolution than ES-DE -**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 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 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. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index f763e5519..2c47e4a9b 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -234,8 +234,11 @@ If the Snap version of RetroArch will be fixed in the future, it can be installe ``` sudo apt-get install snapd sudo snap install retroarch +sudo snap connect retroarch:removable-media ``` +(The last line is only required if you intend to place your ROMs on an external device such as a USB-connected hard drive.) + 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. @@ -347,7 +350,7 @@ The application can also be forced into any of the three modes via the command l There is a help system available throughout the application that provides an overview of the possible actions and buttons that can be used. But some general actions are never shown, such as the ability to quick jump in gamelists, menus and text input fields using the shoulder and trigger buttons. It's also possible to disable the help system using a menu option for a somewhat cleaner look. ![alt text](images/es-de_folder_support.png "ES-DE Help System") -_The help system is displayed at the bottom of the screen, showing the various actions currently available._ +_The help system is displayed at the bottom of the screen, indicating the various actions currently available._ ## General navigation @@ -797,6 +800,11 @@ Keep in mind that ES-DE will not install any RetroArch cores, you need to do thi A general recommendation regarding installation on Linux is to try to avoid the RetroArch releases included in the OS repositories as they're usually quite limited with regards to the number of available cores, and they're usually older versions. Instead go for either the Snap, Flatpak or AppImage distributions or build from source. +If using the Snap distribution you need to run the following command if you intend to place your ROMs on a removable device such as a USB-connected hard drive: +``` +sudo snap connect retroarch:removable-media +``` + The default es_systems.xml file is paired with a file named es_find_rules.xml which tries to find the emulators and cores using some predefined rules. For Windows this should normally just work, and for macOS too as long as RetroArch is installed at the default location /Applications/RetroArch.app. For Unix/Linux there is one exception that is problematic which is AppImages as there is no standardized directory for storing these images. ES-DE will look for the RetroArch AppImage in the following locations in addition to searching the PATH variable: ``` @@ -907,13 +915,13 @@ The media directories per game system are: The miximages are generated by ES-DE. Normally that takes place automatically when scraping, but in this example of manually copying existing media files, the miximage offline generator should be used instead. This tool can generate the miximages for the complete game collection in one go. How that works is explained elsewhere in this guide. -The media files must correspond exactly to the game files. For example the following game: +The media files must correspond exactly to the game files. Take for example this game: ``` ~/ROMs/c64/Multidisk/Last Ninja 2/Last Ninja 2.m3u ``` -Must have corresponding filenames for its media files in this fashion: +For this example, the filename structure needs to look like the following: ``` ~/.emulationstation/downloaded_media/c64/screenshots/Multidisk/Last Ninja 2/Last Ninja 2.jpg @@ -932,7 +940,7 @@ It's possible to change the game media directory location from within ES-DE, for This menu can be accessed from both the system view and gamelist view. It contains the scraper, application settings and various tools such as the input configurator and the miximage generator. Settings are saved when navigating back from any menu screen, assuming at least one setting was changed. Pressing the application exit key (F4 by default) will also save any pending changes. ![alt text](images/es-de_main_menu.png "ES-DE Main Menu") -_The ES-DE main menu._ +_The main menu with its multiple submenus._ Following is a breakdown of the main menu entries. @@ -1439,7 +1447,7 @@ These are mostly technical settings. Using this interface it's possible to select alternative emulators to use per game system, which requires that these alternatives have been defined in the es_systems.xml file. Note that only systems that you have currently populated will be listed. To change to an alternative emulator, you simply select a system from the list and choose which alternative to use from the presented options. If you select an alternative emulator and later remove its corresponding entry from the es_systems.xml file, an error message will be shown on application startup telling you to review your invalid emulator selection. Games will still launch, but the default emulator will be used in this case. How to clear an invalid entry should be self-explanatory once you access the interface. It's also possible to set alternative emulators per game using the metadata editor. If this is done, it will take precedence and override the system-wide emulator selection for the specific game. The alternative emulator badges and the corresponding gamelist filter are controlled by these per-game alternative emulator values and not by the system-wide option. ![alt text](images/es-de_alternative_emulators.png "ES-DE Scraper Settings") -_The system-wide alternative emulators interface._ +_The system-wide alternative emulators interface. An entry in bold and with a gear symbol indicates that an alternative emulator has been selected. The other entries are using the default emulators._ **Game media directory** @@ -1868,7 +1876,7 @@ https://gitlab.com/recalbox/recalbox-themes https://wiki.batocera.org/themes ![alt text](images/es-de_ui_theme_support.png "ES-DE Theme Support") -_An example of a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme applied to ES-DE._ +_This is a screenshot of the modern-DE theme that is bundled with ES-DE (in addition to the default rbsimple-DE theme)._ ## Custom event scripts