mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-21 21:55:38 +00:00
Documentation update.
This commit is contained in:
Leon Styhre
parent
81e90e942b
commit
b41c2d68f5
10
CHANGELOG.md
10
CHANGELOG.md
|
|
@ -27,6 +27,8 @@ Apart from this, many small improvements and bug fixes are part of the release,
|
|||
* 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
|
||||
* The "Run in background (while game is launched)" option can now be enabled on all operating systems instead of only on Windows
|
||||
* Added a workaround for a game launch issue on Windows when using AMD and Intel GPUs
|
||||
* 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
|
||||
* 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
|
||||
|
|
@ -50,14 +52,16 @@ Apart from this, many small improvements and bug fixes are part of the release,
|
|||
* 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
|
||||
* Removed the "Display game media from ROM directories" setting as it doesn't make sense to support this legacy functionality any longer
|
||||
* Added support for using the %ESPATH% and %ROMPATH% variables in the slideshow screensaver custom image directory setting
|
||||
* Removed the menu fade-in effect as it looked terrible
|
||||
* Enabled the menu scale-up effect for the OpenGL ES renderer
|
||||
* 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)
|
||||
* Added support for using the %ESPATH% variable in the media directory setting
|
||||
* 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
|
||||
* Changed the setting description for the favorites game toggling button
|
||||
* Simplified the setup of portable installations on Windows
|
||||
* Simplified and improved 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
|
||||
* Cleaned up some application startup messages
|
||||
|
|
@ -252,10 +256,10 @@ Many bugs have been fixed, and numerous features that were only partially implem
|
|||
|
||||
**The issues below are relevant for ES-DE v1.1.0**
|
||||
|
||||
* There is an issue with launching games on Windows when using AMD and Intel GPUs. This causes the emulator to just output a blank screen. There is a workaround available for this which is enabled by default and that can be disabled via the menu option "AMD and Intel GPU game launch workaround". The drawback of this workaround is that a white instead of a black screen will displayed when launching games. If using an Nvidia GPU, it should be safe to disable this option for a slightly better user experience. An alternative workaround is to enable the option "Run in background (while game is launched)".
|
||||
|
||||
* On macOS Big Sur (and possibly other OS versions) when connecting a DualShock 4 controller either via Bluetooth or using a USB cable, two separate controller devices are registered in parallel. This is a bug in either macOS or the DualShock driver and it makes it seem as if ES-DE is registering double button presses when actually two separate controller devices are generating identical input. A workaround if using Bluetooth mode is to plug in the USB cable just after connecting the controller, wait a second or two and then remove the cable again. This will remove the cabled device, leaving only the Bluetooth device active. Another workaround is to enable the setting "Only accept input from first controller" in the ES-DE input device settings. The reason why this bug may not be visible in some other games and applications is that ES-DE enables and auto-configures all connected controllers.
|
||||
|
||||
* Some screen tearing can be seen in the upper part of the screen when using the slide transitions with certain graphics drivers and resolutions. This problem will hopefully be resolved in ES-DE v1.2 when moving to the GLM library.
|
||||
|
||||
* The launching of games can freeze ES-DE on some Windows installations. It probably only occurs on Windows 8.1 but that's not confirmed. The setting "Run in background (while game is launched)" can be enabled to get around this problem, but this causes some other issues so it should only be used as a last resort. It's unclear if this problem can or will be resolved. If it's confirmed to only affect older Windows versions, then it's probably not worthwhile fixing it.
|
||||
|
||||
* On Windows when using high DPI displays, if not running ES-DE on the primary monitor and the display where it runs does not have the same scaling percentage as the primary monitor, then the ES-DE resolution will not be properly set. The application will still work and if running in fullscreen mode it may not even be noticeable. This issue is caused by a bug in SDL where the primary display scaling is always used for calculating the display bounds and as such it needs to be fixed in that library. If using the same scaling percentage across all monitors, or if not using high DPI monitors at all, then this issue will not occur.
|
||||
|
|
|
|||
|
|
@ -652,7 +652,7 @@ And it will look in the following locations for the themes, also in the listed o
|
|||
|
||||
A theme is not mandatory to start the application, but ES will be basically useless without it.
|
||||
|
||||
The home directory will always take precedence, and any resources or themes located there will override the ones in the installation path or in the path of the ES executable.
|
||||
The home directory will always take precedence, and any resources or themes located there will override the ones in the installation path or in the path of the ES-DE executable.
|
||||
|
||||
**Creating a .dmg installer:**
|
||||
|
||||
|
|
@ -1137,56 +1137,58 @@ And it will look in the following locations for the themes, also in the listed o
|
|||
|
||||
The theme is not mandatory to start the application, but ES-DE will be basically useless without it.
|
||||
|
||||
So the home directory will always take precedence, and any resources or themes located there will override the ones in the path of the ES executable.
|
||||
So the home directory will always take precedence, and any resources or themes located there will override the ones in the path of the ES-DE executable.
|
||||
|
||||
**Setting up a portable installation:**
|
||||
## Portable installation on Windows
|
||||
|
||||
It's possible to easily create a portable installation of ES-DE for Windows, for example on a USB memory stick.
|
||||
It's possible to easily create a portable installation of ES-DE for Windows, for example to place on a USB memory stick.
|
||||
|
||||
For the sake of this example, let's assume that the removable media has the device name `f:\`
|
||||
|
||||
These are the steps to perform:
|
||||
|
||||
* Copy the EmulationStation-DE installation directory to f:\
|
||||
* Copy your emulator directories to f:\
|
||||
* Create the directory `ES-DE_Home` directly under f:\
|
||||
* Copy your game ROMs into `f:\ES-DE_Home\ROMs`
|
||||
* Create the file `Start_ES-DE.bat` directly under f:\
|
||||
* Copy your emulator directories to f:\EmulationStation-DE\
|
||||
* Copy your ROMs directory to f:\EmulationStation-DE\
|
||||
* Create an empty file named portable.txt in f:\EmulationStation-DE\
|
||||
|
||||
Add the following lines to the Start_ES-DE.bat file:
|
||||
You should end up with something like this:
|
||||
```
|
||||
@echo off
|
||||
EmulationStation-DE\EmulationStation.exe --home %CD:~0,3%ES-DE_Home
|
||||
f:\EmulationStation-DE\
|
||||
f:\EmulationStation-DE\RetroArch-Win64\
|
||||
f:\EmulationStation-DE\yuzu\
|
||||
f:\EmulationStation-DE\ROMs\
|
||||
f:\EmulationStation-DE\portable.txt
|
||||
```
|
||||
|
||||
(Yuzu is an optional Nintendo Switch emulator.)
|
||||
|
||||
Of course there will be many more files and directories from the normal installation than those listed above.
|
||||
|
||||
How this works is that when ES-DE finds a file named portable.txt in its executable directory, it will locate the .emulationstation directory directly in this folder. It's however also possible to modify portable.txt with a path relative to the ES-DE executable directory. For instance if two dots `..` are placed inside the portable.txt file, then the .emulationstation directory will be located in the parent folder, which would be directly under f:\ in this example.
|
||||
|
||||
If the --home command line parameter is passed when starting ES-DE, that will override the portable.txt file.
|
||||
|
||||
The emulators that will be automatically searched for by ES-DE are (relative to the EmulationStation-DE directory):
|
||||
|
||||
```
|
||||
RetroArch-Win64\retroarch.exe
|
||||
RetroArch\retroarch.exe
|
||||
yuzu\yuzu-windows-msvc\yuzu.exe
|
||||
..\RetroArch-Win64\retroarch.exe
|
||||
..\RetroArch\retroarch.exe
|
||||
..\yuzu\yuzu-windows-msvc\yuzu.exe
|
||||
```
|
||||
|
||||
The two dots will of course resolve to the root of the device in this example, such as ..\RetroArch-Win64\retroarch.exe being the same as f:\RetroArch-Win64\retroarch.exe
|
||||
If you want to place your emulators elsewhere, you need to create a customized es_find_rules.xml file, which is explained later in this document.
|
||||
|
||||
This means that as long has you don't have any non-standard directory names for your emulators, everything should work fine with the default configuration. But if needed, these paths can be easily customized by modifying f:\EmulationStation-DE\resources\systems\windows\es_find_rules.xml
|
||||
Start ES-DE from the f:\ device and check that everything works as expected.
|
||||
|
||||
The contents of f:\ should now look something like this:
|
||||
```
|
||||
EmulationStation-DE\
|
||||
ES-DE_Home\
|
||||
RetroArch-Win64\
|
||||
yuzu\ (optional Nintendo Switch emulator)
|
||||
Start_ES-DE.bat
|
||||
```
|
||||
|
||||
Now run the batch script to start ES-DE and check that everything works as expected.
|
||||
|
||||
Following this, optionally copy any existing gamelist.xml files and game media files to the removable media. By default these should be located here:
|
||||
Following this, optionally copy any existing gamelist.xml files, game media files etc. to the removable media. For example:
|
||||
|
||||
```
|
||||
f:\ES-DE_Home\.emulationstation\gamelists\
|
||||
f:\ES-DE_Home\.emulationstation\downloaded_media\
|
||||
f:\EmulationStation-DE\.emulationstation\gamelists\
|
||||
f:\EmulationStation-DE\.emulationstation\downloaded_media\
|
||||
```
|
||||
|
||||
You now have a fully functional portable retro gaming installation!
|
||||
|
|
@ -1278,15 +1280,17 @@ pcengine
|
|||
However, if you've saved your ROMs to another directory, you need to configure the ROMDirectory setting in es_settings.xml.\
|
||||
Here's an example:
|
||||
|
||||
`<string name="ROMDirectory" value="~/games/ROMs" />`
|
||||
```xml
|
||||
<string name="ROMDirectory" value="~/games/ROMs" />
|
||||
```
|
||||
|
||||
Keep in mind that you still need to group the ROMs into directories corresponding to the `<path>` tags in es_systems.xml.
|
||||
|
||||
There is also support to add the variable %ESPATH% to the ROM directory setting, this will expand to the path where the ES executable is started from. You would normally not need this, but the option is there, should you require it for some reason.
|
||||
There is also support to add the variable %ESPATH% to the ROM directory setting, this will expand to the path where the ES-DE executable is started from. You should normally not need this, but the option is there for special cases. For example:
|
||||
|
||||
Here is such an example:
|
||||
|
||||
`<string name="ROMDirectory" value="%ESPATH%/../ROMs" />`
|
||||
```xml
|
||||
<string name="ROMDirectory" value="%ESPATH%/../ROMs" />
|
||||
```
|
||||
|
||||
**~/.emulationstation/es_input.xml:**
|
||||
|
||||
|
|
@ -1428,8 +1432,8 @@ Below is an overview of the file layout with various examples. For a real system
|
|||
<command>"C:\My Games\RetroArch\retroarch.exe" -L "%EMUPATH%\cores\snes9x_libretro.dll" %ROM%</command>
|
||||
|
||||
<!-- An example for use in a portable Windows emulator installation, for instance on a USB memory stick. The %ESPATH% variable is
|
||||
expanded to the directory of the ES executable. -->
|
||||
<command>"%ESPATH%\..\RetroArch\retroarch.exe" -L "%ESPATH%\..\RetroArch\cores\snes9x_libretro.dll" %ROM%</command>
|
||||
expanded to the directory of the ES-DE executable. -->
|
||||
<command>"%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM%</command>
|
||||
|
||||
<!-- The platform(s) to use when scraping. You can see the full list of supported platforms in es-app/src/PlatformId.cpp.
|
||||
The entry is case insensitive as it will be converted to lower case during startup.
|
||||
|
|
@ -1512,7 +1516,7 @@ And finally one for Windows:
|
|||
|
||||
This file makes it possible to define rules for where to search for the emulator binaries and emulator cores.
|
||||
|
||||
The file is located in the resources directory at the same location as the es_systems.xml file, but a customized copy can be placed in ~/.emulationstation/custom_systems, which will override the bundled file.
|
||||
The file is located in the resources directory in the same location as the es_systems.xml file, but a customized copy can be placed in ~/.emulationstation/custom_systems, which will override the bundled file.
|
||||
|
||||
Here's an example es_find_rules.xml file for Unix:
|
||||
```xml
|
||||
|
|
@ -1594,9 +1598,11 @@ 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 %ESPATH% variable can be used inside the staticpath rules and both the %EMUPATH% and %ESPATH% variables can be used inside the corepath 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 that option.
|
||||
The tilde symbol `~` is supported for the staticpath and corepath rules 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. The same is true if using a portable.txt file.
|
||||
|
||||
All these options combined makes it possible to create quite powerful find rules.
|
||||
|
||||
For reference, here are also example es_find_rules.xml files for macOS and Windows:
|
||||
|
||||
|
|
@ -1643,6 +1649,8 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
|
|||
<entry>C:\Program Files (x86)\RetroArch-Win64\retroarch.exe</entry>
|
||||
<entry>C:\Program Files (x86)\RetroArch\retroarch.exe</entry>
|
||||
<!-- Portable installation -->
|
||||
<entry>%ESPATH%\RetroArch-Win64\retroarch.exe</entry>
|
||||
<entry>%ESPATH%\RetroArch\retroarch.exe</entry>
|
||||
<entry>%ESPATH%\..\RetroArch-Win64\retroarch.exe</entry>
|
||||
<entry>%ESPATH%\..\RetroArch\retroarch.exe</entry>
|
||||
</rule>
|
||||
|
|
@ -1655,6 +1663,7 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
|
|||
<rule type="staticpath">
|
||||
<entry>~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
|
||||
<!-- Portable installation -->
|
||||
<entry>%ESPATH%\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
|
||||
<entry>%ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
|
||||
</rule>
|
||||
</emulator>
|
||||
|
|
@ -1673,11 +1682,17 @@ The gamelist.xml file for a system defines the metadata for its entries, such as
|
|||
|
||||
As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game media is configurable either manually in `es_settings.xml` or via the GUI. If configured manually in es_settings.xml, it looks something like this:
|
||||
|
||||
```
|
||||
<string name="MediaDirectory" value="~/games/images/emulationstation" />
|
||||
```xml
|
||||
<string name="MediaDirectory" value="~/games/media/emulationstation" />
|
||||
```
|
||||
|
||||
The default directory is `~/.emulationstation/downloaded_media`
|
||||
There is also support to add the variable %ESPATH% to the media directory setting, this will expand to the path where the ES-DE executable is started from. You should normally not need this, but the option is there for special cases. For example:
|
||||
|
||||
```xml
|
||||
<string name="MediaDirectory" value="%ESPATH%/../downloaded_media" />
|
||||
```
|
||||
|
||||
The default media directory is `~/.emulationstation/downloaded_media`
|
||||
|
||||
You can use ES-DE's scraping tools to populate the gamelist.xml files, or manually update individual entries using the metadata editor. All of this is explained in the [User guide](USERGUIDE.md).
|
||||
|
||||
|
|
|
|||
|
|
@ -918,7 +918,7 @@ With this setting enabled, there is a star symbol added at the beginning of the
|
|||
|
||||
**Use plain ASCII for special gamelist characters**
|
||||
|
||||
There are some special characters in ES-DE such as the favorites star, the folder icon and the tickmark (seen when editing custom collections) that are displayed using symbols from the bundled Font Awesome. This normally looks perfectly fine, but on some specific themes with very pixelated fonts such as [es-themes-snes-mini](https://github.com/ruckage/es-theme-snes-mini) and [es-themes-workbench](https://github.com/ehettervik/es-theme-workbench) these symbols look terrible. For such themes, this option is available, which will use plain ASCII characters instead of the Font Awesome symbols. For the favorites an asterisk `*` will be used, for folders a hash sign `#` will be used and for the tickmark an exclamation mark `!` will be used. This only applies to the gamelist view, at all other places in the application the Font Awesome symbols are retained. Make sure to disable this option if not using such a pixelated theme as it looks equally terrible to enable this option on themes where it's not supposed to be used.
|
||||
There are some special characters in ES-DE such as the favorites star, the folder icon and the tickmark (seen when editing custom collections) that are displayed using symbols from the bundled Font Awesome. This normally looks perfectly fine, but on some specific theme sets with very pixelated fonts such as [es-themes-snes-mini](https://github.com/ruckage/es-theme-snes-mini) and [es-themes-workbench](https://github.com/ehettervik/es-theme-workbench) these symbols look terrible. For such themes, this option is available, which will use plain ASCII characters instead of the Font Awesome symbols. For the favorites an asterisk `*` will be used, for folders a hash sign `#` will be used and for the tickmark an exclamation mark `!` will be used. This only applies to the gamelist view, in all other places in the application the Font Awesome symbols are retained. Make sure to disable this option if not using such a pixelated theme as it looks equally terrible to enable this option on themes where it's not supposed to be used.
|
||||
|
||||
**Enable quick list scrolling overlay**
|
||||
|
||||
|
|
@ -1018,7 +1018,7 @@ Whether to search the custom image directory recursively.
|
|||
|
||||
**Custom image directory**
|
||||
|
||||
The directory for the custom images.
|
||||
The directory for the custom images. The tilde `~` symbol can be used which will expand to the ES-DE home directory. It's also possible to use the %ESPATH% and %ROMPATH% variables which will set the directory relative to the ES-DE binary directory or the ROM directory.
|
||||
|
||||
#### Video screensaver settings
|
||||
|
||||
|
|
@ -1171,9 +1171,13 @@ This setting defines the directory for the game media, i.e. game images and vide
|
|||
|
||||
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.
|
||||
|
||||
**Run in background (while game is launched)** _(Windows only)_
|
||||
**Run in background (while game is launched)**
|
||||
|
||||
This is really a last-resort setting if ES-DE freezes when launching games. This issue seems to only occur on Windows 8.1 and older but that's not fully confirmed. ES-DE will behave a bit strange with this option enabled so keep it disabled unless you absolutely need it.
|
||||
Enabling this option makes ES-DE continue to run while a game is launched. This is normally not recommended as it leads to a slightly strange application behavior and also removes the ability to capture return codes and log output from the emulators. But with some graphics drivers on Windows this may be a suitable workaround if there are problems launching games (also see the next option below). Note that launching Steam games on all supported operating systems always makes ES-DE continue to run in the background for technical reasons.
|
||||
|
||||
**AMD and Intel GPU game launch workaround** _(Windows only)_
|
||||
|
||||
There is an issue with launching games on some Windows computers, seemingly on those with AMD and Intel GPUs. The emulator will start and work correctly, but the screen will be blank. Enabling this option is a workaround for that problem, with the drawback that the screen will become white instead of black when the emulator is loading. This option is enabled by default, so experiment with disabling it for a slightly better user experience. If you're using an Nvidia GPU, chances are high that it will then work fine. An alternative workaround is to enable the _Run in background (while game is launched)_ option described above, so test which gives the best result. The two options can however not be enabled at the same time. Hopefully this whole game launching issue can be resolved completely in a future ES-DE release.
|
||||
|
||||
**Upscale video frame rate to 60 FPS (FFmpeg)**
|
||||
|
||||
|
|
@ -1565,7 +1569,7 @@ The setup for event scripts is a bit technical, so please refer to the [INSTALL-
|
|||
|
||||
## Portable installation (Windows only)
|
||||
|
||||
On Windows, ES-DE can be installed to and run from a removable media device such as a USB memory stick. Together with games and emulators this makes for a fully portable retro gaming solution. The setup is somewhat technical, please refer to the [INSTALL-DEV.md](INSTALL-DEV.md#building-on-windows) document to see how it's done.
|
||||
On Windows, ES-DE can be installed to and run from a removable media device such as a USB memory stick. Together with games and emulators this makes for a fully portable retro gaming solution. The setup is somewhat technical, please refer to [INSTALL-DEV.md](INSTALL-DEV.md#portable-installation-on-windows) to see how it's done.
|
||||
|
||||
|
||||
## Command line arguments
|
||||
|
|
|
|||
Loading…
Reference in a new issue