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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2021-06-26 12:32:25 +02:00
parent a230883122
commit 10a2b72063
3 changed files with 42 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
CHANGELOG.md
View file

@ -8,11 +8,13 @@
### Release overview ### 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. The 1.1 release brings many large changes including a fullscreen media viewer, a game launch screen, a miximage generator, a new video player and a new controller API featuring automatic controller configuration and controller profiles.
Refer to the User guide for in-depth explanations of the new functionality. A much better mechanism to find emulators and emulator cores has been implemented as well, which among other things removes the need to manually modify the Path variable on Windows to find RetroArch. It also eliminates the requirement for a separate Flatpak-specific es_systems.xml file on Linux.
Apart from this, many small improvements and bug fixes are part of the release, as detailed below. The User guide contains additional in-depth explanations of the new functionality.
Apart from this, many small improvements and bug fixes are part of the release, as listed below.
### Detailed list of changes ### Detailed list of changes
@ -23,6 +25,7 @@ Apart from this, many small improvements and bug fixes are part of the release,
* Added a new video player based on FFmpeg * 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) * 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) * 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)
* Added a Windows-specific find rule that searches the Registry for the App Paths keys, which should eliminate the need to modify the Path manually to find RetroArch
* Removed the deprecated %COREPATH% setting and corresponding menu entry * Removed the deprecated %COREPATH% setting and corresponding menu entry
* Moved to the SDL GameController API which gives numerous improvements to the controller handling * Moved to the SDL GameController API which gives numerous improvements to the controller handling
* Default controller configuration is now automatically 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
@ -52,6 +55,8 @@ Apart from this, many small improvements and bug fixes are part of the release,
* Removed the marquee image from rbsimple-DE as it's now baked into the miximages * Removed the marquee image from rbsimple-DE as it's now baked into the miximages
* Set the gamelist video scanline rendering option to disabled by default * Set the gamelist video scanline rendering option to disabled by default
* Changed the setting description for the favorites game toggling button * Changed the setting description for the favorites game toggling button
* Simplified the setup of portable installations on Windows
* Converted all navigation sound files to stereo as previously it was a mix of mono and stereo files (done for rbsimple-DE and the fallback sounds)
* The themes and scripts directories are now automatically created during startup * The themes and scripts directories are now automatically created during startup
* Cleaned up some application startup messages * Cleaned up some application startup messages
* The application version is now saved to es_settings.xml, which can be used in the future to notify the user after upgrades to a newer release * The application version is now saved to es_settings.xml, which can be used in the future to notify the user after upgrades to a newer release
@ -59,6 +64,7 @@ Apart from this, many small improvements and bug fixes are part of the release,
* 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 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 a function to ImageComponent to crop fully transparent areas around an image
* Added a CMake option to control whether the VLC video player should be built, and set this to off by default * Added a CMake option to control whether the VLC video player should be built, and set this to off by default
* Removed the pointless APPLE_SKIP_INSTALL_LIBS CMake option
* Added the NanoSVG library as a proper Git subtree * Added the NanoSVG library as a proper Git subtree
* Changed the language standard from C++11 to C++14 * Changed the language standard from C++11 to C++14
@ -68,7 +74,7 @@ Apart from this, many small improvements and bug fixes are part of the release,
* Games that were filtered out were included in the random game selection for the grouped custom collections view * Games that were filtered out were included in the random game selection for the grouped custom collections view
* After switching theme sets with only a single system available, diagonal slide transitions would sometimes play when moving to the system view * After switching theme sets with only a single system available, diagonal slide transitions would sometimes play when moving to the system view
* Ongoing slide transition animations would continue to play after switching theme sets * Ongoing slide transition animations would continue to play after switching theme sets
* On Windows, images with Unicode characters in the game name that were resized when scraping would not be saved with valid filenames * On Windows, images with Unicode characters in the game name that were resized when scraping would not get saved with valid filenames
* The glitches when configuring trigger buttons in GuiInputConfig have been fixed * 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 * GuiInputConfig didn't correctly inform which buttons could be skipped for some rows

47
INSTALL-DEV.md
View file

@ -597,14 +597,6 @@ libx264_plugin.dylib
libx265_plugin.dylib libx265_plugin.dylib
``` ```
If you only want to build ES-DE to be used on your own computer, there's the option to skip the entire bundling of the libraries and use the ones already installed using Homebrew, meaning you can skip the previous .dylib copying. To do so, run CMake with the following option:
```
cmake -DAPPLE_SKIP_INSTALL_LIBS=ON .
```
This also affects the .dmg package generation using cpack, so if this option is enabled, the package will be unusable for anyone but yourself as the required libraries will not be bundled with the application.
On macOS you can install the application as a normal user, i.e. no root privileges are required. Simply run the following: On macOS you can install the application as a normal user, i.e. no root privileges are required. Simply run the following:
``` ```
@ -1519,7 +1511,7 @@ The file is located in the resources directory at the same location as the es_sy
Here's an example es_find_rules.xml file for Unix: Here's an example es_find_rules.xml file for Unix:
```xml ```xml
<?xml version="1.0"?> <?xml version="1.0"?>
<!-- This is the ES-DE find rules configuration file for Unix. --> <!-- This is the ES-DE find rules configuration file for Unix -->
<ruleList> <ruleList>
<emulator name="RETROARCH"> <emulator name="RETROARCH">
<rule type="systempath"> <rule type="systempath">
@ -1535,7 +1527,7 @@ Here's an example es_find_rules.xml file for Unix:
</rule> </rule>
</emulator> </emulator>
<emulator name="YUZU"> <emulator name="YUZU">
<!-- Nintendo Switch emulator Yuzu. --> <!-- Nintendo Switch emulator Yuzu -->
<rule type="systempath"> <rule type="systempath">
<entry>yuzu</entry> <entry>yuzu</entry>
<entry>org.yuzu_emu.yuzu</entry> <entry>org.yuzu_emu.yuzu</entry>
@ -1571,7 +1563,9 @@ Here's an example es_find_rules.xml file for Unix:
</ruleList> </ruleList>
``` ```
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. 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`.
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.
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:
@ -1579,25 +1573,30 @@ The `name` attribute must correspond to the command tags in es_systems.xml, take
<command>%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM%</command> <command>%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 nice). 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 if not only using RetroArch. 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 `<entry>` tags and `staticpath` defining absolute paths to the emulator. For staticpath, the actual emulator binary must also be included in the entry tag. 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, processing 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 `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 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 also 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.
As for `corepath` this 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.
The %EMUPATH% and %ESPATH% variables can also be used inside the entry tags, making for quite powerful find rules. 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. Be aware that if ES-DE has been started with the --home command line option, the home directory is considered to be whatever path was passed as an argument to this option. The tilde symbol `~` is supported and will expand to the user home directory. Be aware that if ES-DE has been started with the --home command line option, the home directory is considered to be whatever path was passed as an argument to that option.
For reference, here are also example es_find_rules.xml files for macOS and Windows: For reference, here are also example es_find_rules.xml files for macOS and Windows:
```xml ```xml
<?xml version="1.0"?> <?xml version="1.0"?>
<!-- This is the ES-DE find rules configuration file for macOS. --> <!-- This is the ES-DE find rules configuration file for macOS -->
<ruleList> <ruleList>
<emulator name="RETROARCH"> <emulator name="RETROARCH">
<rule type="staticpath"> <rule type="staticpath">
@ -1617,32 +1616,40 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
```xml ```xml
<?xml version="1.0"?> <?xml version="1.0"?>
<!-- This is the ES-DE find rules configuration file for Windows. --> <!-- This is the ES-DE find rules configuration file for Windows -->
<ruleList> <ruleList>
<emulator name="RETROARCH"> <emulator name="RETROARCH">
<rule type="winregistrypath">
<!-- Check for an App Paths entry in the Windows Registry -->
<entry>retroarch.exe</entry>
</rule>
<rule type="systempath"> <rule type="systempath">
<!-- This requires that the user has manually updated the Path variable --> <!-- This requires that the user has manually updated the Path variable -->
<entry>retroarch.exe</entry> <entry>retroarch.exe</entry>
</rule> </rule>
<rule type="staticpath"> <rule type="staticpath">
<!-- Some reasonable installation locations --> <!-- Some reasonable installation locations as fallback -->
<entry>C:\RetroArch-Win64\retroarch.exe</entry> <entry>C:\RetroArch-Win64\retroarch.exe</entry>
<entry>C:\RetroArch\retroarch.exe</entry> <entry>C:\RetroArch\retroarch.exe</entry>
<entry>~\AppData\Roaming\RetroArch\retroarch.exe</entry>
<entry>C:\Program Files\RetroArch-Win64\retroarch.exe</entry> <entry>C:\Program Files\RetroArch-Win64\retroarch.exe</entry>
<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>
<!-- Portable installation --> <!-- Portable installation -->
<entry>%ESPATH%\..\RetroArch-Win64\retroarch.exe</entry>
<entry>%ESPATH%\..\RetroArch\retroarch.exe</entry> <entry>%ESPATH%\..\RetroArch\retroarch.exe</entry>
</rule> </rule>
</emulator> </emulator>
<emulator name="YUZU"> <emulator name="YUZU">
<!-- Nintendo Switch emulator Yuzu. --> <!-- Nintendo Switch emulator Yuzu -->
<rule type="systempath"> <rule type="systempath">
<entry>yuzu.exe</entry> <entry>yuzu.exe</entry>
</rule> </rule>
<rule type="staticpath"> <rule type="staticpath">
<entry>~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe</entry> <entry>~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
<!-- Portable installation -->
<entry>%ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
</rule> </rule>
</emulator> </emulator>
<core name="RETROARCH"> <core name="RETROARCH">

24
USERGUIDE-DEV.md
View file

@ -16,9 +16,8 @@ If you just want to get started as quickly as possible, simply follow these step
2) Start the application and press the _Create directories_ button to generate the ROMs directory structure 2) Start the application and press the _Create directories_ button to generate the ROMs directory structure
3) Put your game ROMs in the directories created by the previous step, or see [here](USERGUIDE-DEV.md#supported-game-systems) for additional details 3) Put your game ROMs in the directories created by the previous step, or see [here](USERGUIDE-DEV.md#supported-game-systems) for additional details
4) Install and configure [RetroArch](https://www.retroarch.com) 4) Install and configure [RetroArch](https://www.retroarch.com)
5) _Windows only: add the RetroArch directory to your system path environmental variable_ 5) Start RetroArch and install the required emulator cores - to see which ones you need look in the systeminfo.txt files in the directories created by step 2, or again see [here](USERGUIDE-DEV.md#supported-game-systems)
6) Start RetroArch and install the required emulator cores - to see which ones you need look in the systeminfo.txt files in the directories created by step 2, or again see [here](USERGUIDE-DEV.md#supported-game-systems) 6) Start ES-DE, scrape game media for your collection and play some games!
7) Start ES-DE, scrape game media for your collection and play some games!
You can always press F4 to close the application. You can always press F4 to close the application.
@ -566,22 +565,11 @@ ES-DE is a game browsing frontend and does not provide any emulation by itself.
Installation and configuration of RetroArch and other emulators is beyond the scope of this guide, but many good resources can be found online on how to do this. Installation and configuration of RetroArch and other emulators is beyond the scope of this guide, but many good resources can be found online on how to do this.
A general recommendation regarding installation on Linux though 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. Keep in mind that ES-DE will not install any RetroArch cores, you need to do this manually from within the RetroArch user interface.
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 Unix/Linux this should normally just work (except for AppImage, see below), and for macOS it will work as long as RetroArch is installed at the default location /Applications/RetroArch.app. For Windows it's a bit more complicated as there is really no standard location where applications are installed on this operating system, and RetroArch does not add itself to the Path environment variable during installation. In general it's therefore recommended to manually add the RetroArch directory to your Path variable (tip: open Settings from the Start menu and search for _path_). 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.
However the following directories are defined in es_find_rules.xml for Windows, so if you've installed RetroArch to any of these, ES-DE will be able to find it: 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 as well 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 real standardized directory for storing these images. ES-DE will look for the RetroArch AppImage in the following locations in addition to searching the system PATH:
```
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
```
There is also a special case on Linux if using the AppImage release of RetroArch as there is no real standardized directory for storing these images. ES-DE will look for the RetroArch AppImage in the following locations in addition to searching the system PATH:
``` ```
~/Applications/RetroArch-Linux-x86_64.AppImage ~/Applications/RetroArch-Linux-x86_64.AppImage
@ -589,8 +577,6 @@ There is also a special case on Linux if using the AppImage release of RetroArch
~/bin/RetroArch-Linux-x86_64.AppImage ~/bin/RetroArch-Linux-x86_64.AppImage
``` ```
As an alternative, if the emulator is not in your search path, you can either hardcode an absolute path in es_systems.xml or use the %ESPATH% variable to set the emulator relative to the ES-DE binary location. Again, please refer to [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml) for details regarding this.
In any instance, ES-DE will display an error notification if attempting to launch a game where the emulator binary is not found. Likewise it will notify if the defined emulator core is not installed. The es_log.txt file will also provide additional details. In any instance, ES-DE will display an error notification if attempting to launch a game where the emulator binary is not found. Likewise it will notify if the defined emulator core is not installed. The es_log.txt file will also provide additional details.