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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2022-02-21 19:28:55 +01:00
parent a6b1a8844d
commit f071284ae0
3 changed files with 48 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
CHANGELOG.md
View file

@ -14,6 +14,8 @@
* Added theme support for defining and applying different layouts for various display aspect ratios such as 16:9 and 4:3
* Made gamelist theming much more flexible by allowing any number of elements of any types to be defined
* Deprecated multiple older theming concepts like features, extras and hardcoded metadata attributes
* Added support for asterisks/wildcards for emulator name matching, usable both in es_find_rules.xml and es_systems.xml
* The actual names for emulators with find rule entries are now displayed in the error popup window if they're not found during game launch
* Reorganized the UI Settings menu a bit and added entries to set the variant and aspect ratio for newer theme sets
* Removed the "Play videos immediately (override theme)" setting
* Renamed the sound menu option "Play audio for videos in the gamelist view" to "Play audio for gamelist and system view videos"
@ -69,6 +71,7 @@
* Renamed GuiGameScraper.cpp to GuiScraperSingle.cpp
* Renamed SystemScreensaver.cpp to Screensaver.cpp
* Moved UIModeController.cpp from the es-app/views directory to es-app
* Updated the StringUtil::replace function as the old function was dangerous and could run into an endless loop
* Set the clang-format option SpaceBeforeCpp11BracedList to true and reformatted the codebase
* Removed some unnecessary typedefs and replaced the remaining ones with the more modern "using" keyword
* Greatly simplified the video controls code (play/stop/pause etc.)

33
INSTALL-DEV.md
View file

@ -1084,6 +1084,16 @@ The bundled es_systems.xml file is located in the resources directory that is pa
It doesn't matter in which order you define the systems as they will be sorted by the `<fullname>` tag or by the optional `<systemsortname>` tag when displayed inside the application. But it's still a good idea to add the systems in alphabetical order to make the configuration file easier to maintain.
Wildcards are supported for emulator binaries, but not for directories:
```xml
<!-- This is supported, first matching file will be selected -->
<command>~/Applications/yuzu*.AppImage %ROM%</command>
<!-- This is also supported -->
<command>~/Applications/yuzu*.App* %ROM%</command>
<!-- This is NOT supported -->
<command>~/App*/yuzu*.AppImage %ROM%</command>
```
Keep in mind that you have to set up your emulators separately from ES-DE as the es_systems.xml file assumes that your emulator environment is properly configured.
Below is an overview of the file layout with various examples. For the command tag, the newer es_find_rules.xml logic described later in this document removes the need for most of the legacy options, but they are still supported for special configurations and for backward compatibility with old configuration files.
@ -1142,6 +1152,10 @@ Below is an overview of the file layout with various examples. For the command t
the find rules for the emulator cores. -->
<command>retroarch -L %CORE_RETROARCH%/snes9x_libretro.so %ROM%</command>
<!-- This example for Unix uses a wildcard to find the first matching RPCS3 AppImage in the ~/Applications directory.
This is useful as AppImages often have version information embedded in the filename that may change when upgrading the package. -->
<command label="RPCS3 (Standalone)">~/Applications/rpcs3*.AppImage --no-gui %ROM%</command>
<!-- This is an example for macOS, which is very similar to the Unix example above except using an absolute path to the emulator. -->
<command>/Applications/RetroArch.app/Contents/MacOS/RetroArch -L %CORE_RETROARCH%/snes9x_libretro.dylib %ROM%</command>
@ -1382,9 +1396,9 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
</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>
<entry>~/Applications/yuzu*.AppImage</entry>
<entry>~/.local/bin/yuzu*.AppImage</entry>
<entry>~/bin/yuzu*.AppImage</entry>
</rule>
</emulator>
</ruleList>
@ -1408,7 +1422,18 @@ The `winregistrypath` rule searches the Windows Registry "App Paths" keys for th
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. 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 `<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. Wildcards (*) are supported for the emulator binary, but not for directories. Wildcards are very useful for AppImages which often embed version information into the filenames. Note that if multiple files match a wildcard pattern, the first file returned by the operating system will be selected.
```xml
<rule type="staticpath">
<!-- This is supported, first matching file will be selected -->
<entry>~/Applications/yuzu*.AppImage</entry>
<!-- This is also supported -->
<entry>~/Applications/yuzu*.App*</entry>
<!-- This is NOT supported -->
<entry>~/App*/yuzu*.AppImage</entry>
</rule>
```
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.

48
USERGUIDE-DEV.md
View file

@ -81,7 +81,7 @@ Of course the filename will differ slightly depending on the architecture, the e
In addition to the .deb and .rpm packages covered above, ES-DE is also available as an AppImage which should be usable on most modern x86 64-bit Linux distributions. After download you have to set the file as executable, such as this:
```
chmod +x emulationstation-de-1.2.0-x64.AppImage
chmod +x emulationstation-de-2.0.0-x64.AppImage
```
Following this you can launch ES-DE by double-clicking on the AppImage using your file manager. It's also possible to run it from a terminal window, in which case all command line options work the same way as if installed as an ordinary package.
@ -446,7 +446,7 @@ If using the Snap distribution you need to run the following command if you inte
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 AppImage packages as there is no standardized directory for storing these files. Read more [here](USERGUIDE-DEV.md#using-emulators-in-appimage-format-on-linux) on how to get the AppImage release of RetroArch to work.
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 slightly problematic which is AppImage packages as there is no standardized directory for storing these files. Read more [here](USERGUIDE-DEV.md#using-emulators-in-appimage-format-on-linux) on how to get the AppImage release of RetroArch to work.
If ES-DE is unable to find an emulator when a game is launched, a notification popup will be shown. Likewise a notification will be shown if the defined emulator core is not installed. The es_log.txt file will also provide additional details.
@ -466,9 +466,9 @@ Unfortunately on Linux it's at the moment not possible to run the Steam release
## Using emulators in AppImage format on Linux
AppImages are a great way to package emulators on Linux as they work across many different distributions, and launching and running them introduces virtually no overhead. There is one problem though in that there is no standardized directory for storing these files, meaning ES-DE could have issues locating them.
AppImages are a great way to package emulators on Linux as they work across many different distributions, and launching and running them introduces virtually no overhead. There is one small problem though in that there is no standardized directory for storing these files, meaning ES-DE could have issues locating them.
As such all bundled emulator configuration entries that support AppImages will look for these files in the following directories:
Therefore all bundled emulator configuration entries that support AppImages will look for these files in the following directories:
```
~/Applications/
@ -476,47 +476,31 @@ As such all bundled emulator configuration entries that support AppImages will l
~/bin/
```
But even if the directory is known, another issue is that many AppImages contain version information in the filename, such as:
```
rpcs3-v0.0.19-13103-cc21d1b3_linux64.AppImage
```
As AppImages often embed version information into the actual filename, the bundled configuration uses wildcards to locate the files, such as `rpcs3*.AppImage` which would match the filename `rpcs3-v0.0.19-13103-cc21d1b3_linux64.AppImage` for instance. Note that if multiple files match the wildcard pattern, the first file returned by the operating system will be selected.
ES-DE needs to have a specific filename to be able to find the emulator, so the easiest solution is to create a symlink to the AppImage file, such as the following:
```
cd ~/Applications
ln -s rpcs3-v0.0.19-13103-cc21d1b3_linux64.AppImage rpcs3.AppImage
```
This approach also works when using [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher) which is recommended as it properly integrates AppImages into the application menu and such. When first launching an AppImage with AppImageLauncher installed a question will be asked whether to integrate the application. If accepting this, the AppImage will be moved to the `~/Applications` directory and a hash will be added to the filename, like in this example:
```
rpcs3-v0.0.19-13103-cc21d1b3_linux64_54579676ed3fa60dafec7188286495e4.AppImage
```
Again, the wildcard matching means this filename should be found by ES-DE when launching a game so no additional setup should be required.
After taking this step, a symlink can be created:
If not using AppImageLauncher, then make sure to set the AppImages as executable or ES-DE will not be able to launch them. For example:
```
cd ~/Applications
ln -s rpcs3-v0.0.19-13103-cc21d1b3_linux64_54579676ed3fa60dafec7188286495e4.AppImage rpcs3.AppImage
chmod +x ./rpcs3-v0.0.19-13103-cc21d1b3_linux64.AppImage
```
As the hashed filename created by AppImageLauncher will be retained also after upgrading AppImages to newer versions, ES-DE will still be able to find the emulator.
At the moment the following emulators are supported in AppImage format when using the bundled configuration:
At the moment the following emulators are supported in AppImage format:
| System name | Emulator | Filename configuration |
| :----------- | :-------- | :------------------------------ |
| _Multiple_ | RetroArch | RetroArch-Linux-x86_64.AppImage |
| ps3 | RPCS3 | rpcs3*.AppImage |
| switch | Yuzu | yuzu*.AppImage |
| System name | Emulator | Required filename or symlink name |
| :----------- | :-------- | :-------------------------------- |
| _Multiple_ | RetroArch | RetroArch-Linux-x86_64.AppImage |
| ps3 | RPCS3 | rpcs3.AppImage |
| switch | Yuzu | yuzu.AppImage |
Symlinking RetroArch is only required if using AppImageLauncher as the filename is otherwise not containing any version information, instead simply being named `RetroArch-Linux-x86_64.AppImage`.
Note that the names are case sensitive, so for instance _rpcs3.appimage_ will not be found by ES-DE.
Also make sure to set the AppImage as executable or ES-DE will not be able to launch it. You do this on the actual file, not on the symlink. For example:
```
cd ~/Applications
chmod +x ./rpcs3-v0.0.19-13103-cc21d1b3_linux64_54579676ed3fa60dafec7188286495e4.AppImage
```
RetroArch does not embed any version information into the filename so no wildcard is required.
## Getting your games into ES-DE