mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-21 13:45:38 +00:00
Restructured the user guide a bit.
This commit is contained in:
Leon Styhre
parent
e4e165942a
commit
e7de2ab861
213
USERGUIDE-DEV.md
213
USERGUIDE-DEV.md
|
|
@ -26,7 +26,6 @@ For additional details, read on below.
|
|||
There are also installation videos available at the ES-DE YouTube channel:\
|
||||
[https://www.youtube.com/channel/UCosLuC9yIMQPKFBJXgDpvVQ](https://www.youtube.com/channel/UCosLuC9yIMQPKFBJXgDpvVQ)
|
||||
|
||||
|
||||
## Installation and first startup
|
||||
|
||||
To install ES-DE, just download the package or installer from [https://es-de.org](https://es-de.org) and follow the brief instructions below.
|
||||
|
|
@ -151,27 +150,10 @@ There will be a lot of directories created if using the es_systems.xml file bund
|
|||
|
||||
_This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._
|
||||
|
||||
|
||||
## Disabling game systems
|
||||
|
||||
The way ES-DE works is that it will always try to load any system for which there are game files available, so to disable a system it needs to be hidden from ES-DE. This is easily accomplished by renaming the game directory to something that is not recognized, for example changing `~/ROMs/c64` to `~/ROMs/c64_DISABLED`. Another approach is to create a subdirectory named DISABLED (or whatever name you prefer that is not matching a supported system) in the ROMs directory and move the game folder there, such as `~/ROMs/DISABLED/c64`. This makes it easy to disable and re-enable game systems in ES-DE. Note that the gamelist.xml file and any game media files are retained while the system is disabled so this is an entirely safe thing to do.
|
||||
|
||||
|
||||
## Using the Steam release of RetroArch
|
||||
|
||||
On Windows it's no problem to use the Steam release of RetroArch although you may have to add the installation location manually to your Path environment variable. By default the following locations will be searched:
|
||||
```
|
||||
C:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
D:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
C:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
D:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
```
|
||||
|
||||
If you have installed RetroArch at another location, simply start the Settings application, search for _path_ in the _Find a setting_ field and choose _Edit environment variables for your account_. Edit the _Path_ variable and add the directory where RetroArch is installed. This is required as there is no apparent way for ES-DE to find where RetroArch has been installed by the Steam application.
|
||||
|
||||
Unfortunately on Linux it's at the moment not possible to run the Steam release of RetroArch due to technical reasons. This RetroArch release runs as a type of container which can't be executed from ES-DE while correctly passing the necessary core and game options. Similarly it's not possible to launch RetroArch via the Steam application either as there seems to be a bug in Steam or RetroArch that prevents blankspaces from being present in game ROM files when passed as arguments (this works fine on Windows so it's definitely a Linux-specific issue and as well the same problem occurs if attempting to manually enter the launch command from a terminal window).
|
||||
|
||||
|
||||
## Specific notes for Windows
|
||||
|
||||
In general it should be straightforward to run ES-DE on Windows. Almost all emulators are available on this operating system and driver quality and controller support is normally very good.
|
||||
|
|
@ -193,7 +175,6 @@ Another possibility is that OpenGL drivers are actually installed but the GPU do
|
|||
|
||||
An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem. So in order for ES-DE to find them, the directories need to be manually added to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after changing the variable, but following this the emulator should be found when launching a game.
|
||||
|
||||
|
||||
## Specific notes for macOS
|
||||
|
||||
As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. As well many emulators available for download are not codesigned and notarized which requires you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions.
|
||||
|
|
@ -216,7 +197,6 @@ A minor annoyance is that macOS creates metadata files starting with ._ in the f
|
|||
|
||||
Another problem on macOS 11 Big Sur (and possibly older OS versions) is that when connecting a Sony 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. The issue appears to be resolved in macOS Monterey.
|
||||
|
||||
|
||||
## Specific notes for Raspberry Pi
|
||||
|
||||
ES-DE on the Raspberry Pi requires a desktop environment, or more specifically a window manager and a sound server (like PulseAudio or PipeWire). There are no plans to add support for direct hardware access to the framebuffer or to ALSA. If you want to use your Raspberry Pi as an appliance, take a look at [RetroPie](https://retropie.org.uk), [Recalbox](https://www.recalbox.com) or [Batocera](https://batocera.org) instead.
|
||||
|
|
@ -262,7 +242,6 @@ On Raspberry Pi OS 10 Sony DualShock 4 controllers have problems with some butto
|
|||
|
||||
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 so for now this older OS version is recommended.
|
||||
|
||||
|
||||
## Game system customizations
|
||||
|
||||
The game systems configuration file `es_systems.xml` is located in the ES-DE resources directory which is part of the application installation. As such this file is not intended to be modified directly. If system customizations are required, a separate es_systems.xml file should instead be placed in the `custom_systems` folder in the ES-DE home directory, i.e. `~/.emulationstation/custom_systems/es_systems.xml`.
|
||||
|
|
@ -273,7 +252,6 @@ For example you may want to replace the emulator launch command, modify the full
|
|||
|
||||
The instructions for how to customize the es_systems.xml file can be found in [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml). There you can also find some examples of custom files that you can copy into ~/.emulationstation/custom_systems/ and modify as required.
|
||||
|
||||
|
||||
## Migrating from other EmulationStation forks
|
||||
|
||||
**IMPORTANT!!! IMPORTANT!!! IMPORTANT!!!**
|
||||
|
|
@ -291,7 +269,6 @@ It's also strongly adviced to not rename an old es_settings.cfg file to es_setti
|
|||
|
||||
If migrating from Batocera or Recalbox, be aware that ES-DE follows the RetroPie naming conventions for game systems. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera and Recalbox has the _sg1000_ system name, but is _sg-1000_ in RetroPie and ES-DE. See the [Supported game systems](USERGUIDE-DEV.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE. This issue also means that theme sets that were written or adapted specifically for Batocera or Recalbox may display unthemed systems in ES-DE. All RetroPie theme sets should however work fine (of course assuming that all your systems are actually supported by the theme set).
|
||||
|
||||
|
||||
## Running on high resolution displays
|
||||
|
||||
ES-DE fully supports high resolution displays such as 1440p, 4K, 6K, 8K, ultrawide monitors etc. But many emulators (e.g. RetroArch) will also run using the same resolution which may cause performance problems on slower machines or when using resource intensive shaders. Although some emulator cores will have options to set their internal resolution, they still need to be scaled up to the screen resolution.
|
||||
|
|
@ -300,7 +277,6 @@ A solution to this is to use the custom event scripts functionality to set a tem
|
|||
|
||||
On macOS it's problematic to change screen resolutions on the fly or on a per-application basis as Apple has seemingly disabled most of this functionality in recent operating system releases. The only real option here is to lower the display resolution prior to launching ES-DE.
|
||||
|
||||
|
||||
## Input device configuration
|
||||
|
||||
ES-DE automatically configures the keyboard and any connected controllers using default button mappings, and normally no additional setup is required. But if you would like to apply custom button mappings for your devices or if you have an unusual device which isn't automatically configured, you can run the _Configure keyboard and controllers_ tool from the _Input device settings_ entry on the main menu.
|
||||
|
|
@ -313,7 +289,6 @@ Any custom configuration is applied per unique device ID (GUID). So if two ident
|
|||
|
||||
If you have issues with your input configuration, as a last resort you can reset all the mappings by deleting or renaming the file ~/.emulationstation/es_input.xml.
|
||||
|
||||
|
||||
## System view (main screen)
|
||||
|
||||
When starting ES-DE with the default settings, you will see the System view first. From here you can navigate your game systems and enter their respective gamelists.
|
||||
|
|
@ -325,7 +300,6 @@ The game systems are sorted by their full names by default, as defined in the es
|
|||
|
||||
_The **System view** is the default starting point for the application, it's here that you browse through your game systems._
|
||||
|
||||
|
||||
## Gamelist view
|
||||
|
||||
The gamelist view is where you browse and start your games, and it's where you will spend most of your time using ES-DE.
|
||||
|
|
@ -348,7 +322,6 @@ _The **Gamelist view** is where you browse the games for a specific system._
|
|||
|
||||
_Here's an example of what the Basic view style looks like. Needless to say, ES-DE is not intended to be used like this. After scraping some game media for the system, the view style will automatically change to Detailed or Video (assuming the Automatic view style option has been selected)._
|
||||
|
||||
|
||||
## UI modes
|
||||
|
||||
ES-DE supports three separate modes, **Full**, **Kiosk** and **Kid**.
|
||||
|
|
@ -363,7 +336,6 @@ There is an unlock code available to revert to the Full mode from the Kiosk or K
|
|||
|
||||
The application can also be forced into any of the three modes via the command line options `--force-full`, `--force-kiosk` and `--force-kid`. This is only temporary until the restart of the application, unless the settings menu is entered and the setting is saved to the configuration file (this assumes that the main menu is available in the selected UI mode of course).
|
||||
|
||||
|
||||
## Help system
|
||||
|
||||
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.
|
||||
|
|
@ -371,7 +343,6 @@ There is a help system available throughout the application that provides an ove
|
|||
|
||||
_The help system is displayed at the bottom of the screen, indicating the various actions currently available._
|
||||
|
||||
|
||||
## General navigation
|
||||
|
||||
The built-in help system will provide a contextual summary of the available navigation options, but here's still a general overview. These are the buttons mappings automatically applied by ES-DE, but they can be customized using the input configurator as described earlier in this document. It's not an exhaustive list, but it covers most situations. The button names are based on the Xbox 360 controller as that is the naming convention used by the SDL library which handles the controller input in ES-DE.
|
||||
|
|
@ -437,6 +408,93 @@ Marks games as favorites in the gamelist view (if the _Enable toggle favorites b
|
|||
|
||||
Quits the application. This key combination can be changed using the _Exit button combo_ menu option described later in this document.
|
||||
|
||||
## RetroArch setup
|
||||
|
||||
ES-DE is a game browsing frontend and does not provide any emulation by itself. It does however come preconfigured for use with emulators as setup in the `es_systems.xml` file. By default it's primarily setup for use with [RetroArch](https://www.retroarch.com) but this can be modified if needed. If you're interested in customizing your es_systems.xml file, please refer to the [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml) document which goes into detail on the structure of this file and more advanced configuration topics in general.
|
||||
|
||||
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.
|
||||
|
||||
Keep in mind that ES-DE will not install any RetroArch cores, you need to do this manually from within the RetroArch user interface.
|
||||
|
||||
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 AppImage 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.
|
||||
|
||||
## Using the Steam release of RetroArch
|
||||
|
||||
On Windows it's no problem to use the Steam release of RetroArch although you may have to add the installation location manually to your Path environment variable. By default the following locations will be searched:
|
||||
```
|
||||
C:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
D:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
C:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
D:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
```
|
||||
|
||||
If you have installed RetroArch at another location, simply start the Settings application, search for _path_ in the _Find a setting_ field and choose _Edit environment variables for your account_. Edit the _Path_ variable and add the directory where RetroArch is installed. This is required as there is no apparent way for ES-DE to find where RetroArch has been installed by the Steam application.
|
||||
|
||||
Unfortunately on Linux it's at the moment not possible to run the Steam release of RetroArch due to technical reasons. This RetroArch release runs as a type of container which can't be executed from ES-DE while correctly passing the necessary core and game options. Similarly it's not possible to launch RetroArch via the Steam application either as there seems to be a bug in Steam or RetroArch that prevents blankspaces from being present in game ROM files when passed as arguments (this works fine on Windows so it's definitely a Linux-specific issue and as well the same problem occurs if attempting to manually enter the launch command from a terminal window).
|
||||
|
||||
## 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 where to place 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:
|
||||
|
||||
```
|
||||
~/Applications/
|
||||
~/.local/bin/
|
||||
~/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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
After taking this step, a symlink can be created:
|
||||
```
|
||||
cd ~/Applications
|
||||
ln -s rpcs3-v0.0.19-13103-cc21d1b3_linux64_54579676ed3fa60dafec7188286495e4.AppImage rpcs3.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:
|
||||
|
||||
| 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
|
||||
```
|
||||
|
||||
## Getting your games into ES-DE
|
||||
|
||||
For most systems this is straightforward, just put your game files into the folder corresponding to the platform name (these names can be found at the [end](USERGUIDE-DEV.md#supported-game-systems) of this guide.)
|
||||
|
|
@ -553,60 +611,6 @@ The only exception is that the _Delete_ button in the metadata editor will be di
|
|||
|
||||
When setting up a directory like this, make sure to not name any files or folders inside the base directory using the same extension as that will force the base directory to be processed normally, breaking the functionality.
|
||||
|
||||
### 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 where to place 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:
|
||||
|
||||
```
|
||||
~/Applications/
|
||||
~/.local/bin/
|
||||
~/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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
After taking this step, a symlink can be created:
|
||||
```
|
||||
cd ~/Applications
|
||||
ln -s rpcs3-v0.0.19-13103-cc21d1b3_linux64_54579676ed3fa60dafec7188286495e4.AppImage rpcs3.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:
|
||||
|
||||
| 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
|
||||
```
|
||||
|
||||
### Special game installation considerations
|
||||
|
||||
Not all systems are as simple as described above, or there may be multiple ways to do the configuration. Specifics for such systems will be covered here. Consider this a work in progress as there are many platforms supported by ES-DE.
|
||||
|
|
@ -625,7 +629,7 @@ The Nintendo Switch emulator Yuzu is distributed as a Snap package, Flatpak pack
|
|||
|
||||
If installed as a Snap or Flatpak package or if built from source code on Linux, ES-DE should be able to easily locate the emulator binary.
|
||||
|
||||
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#emulators-in-appimage-format-on-linux) for more information on how to get it to work.
|
||||
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#using-emulators-in-appimage-format-on-linux) for more information on how to get it to work.
|
||||
|
||||
For Windows, ES-DE will look for _yuzu.exe_ in the system Path as well as in the default installation directory `~\AppData\Local\yuzu\yuzu-windows-msvc\`
|
||||
|
||||
|
|
@ -641,7 +645,7 @@ The macOS release ships as a regular DMG file that is installed as usual.
|
|||
|
||||
On Linux RPCS3 is shipped as a Snap package, Flatpak package or AppImage. If installed as a Snap or Flatpak or if built from source code, ES-DE should be able to easily locate the emulator binary.
|
||||
|
||||
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#emulators-in-appimage-format-on-linux) for more information on how to get it to work.
|
||||
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#using-emulators-in-appimage-format-on-linux) for more information on how to get it to work.
|
||||
|
||||
As for the game installation on both Windows and Linux as well as on macOS, you need to retain the directory structure of the Blu-ray disc or the directory created by installing the .pkg file. Each directory needs to be renamed by adding the .ps3dir extension, which will make ES-DE interpret the directory as if it were a file and pass that directory to the emulator when launching a game.
|
||||
|
||||
|
|
@ -857,33 +861,6 @@ This of course assumes that you have menu entries setup for your Steam games.
|
|||
|
||||
To greatly simplify this setup, automatic Steam library import is planned for a future ES-DE release.
|
||||
|
||||
|
||||
## RetroArch setup
|
||||
|
||||
ES-DE is a game browsing frontend and does not provide any emulation by itself. It does however come preconfigured for use with emulators as setup in the `es_systems.xml` file. By default it's primarily setup for use with [RetroArch](https://www.retroarch.com) but this can be modified if needed. If you're interested in customizing your es_systems.xml file, please refer to the [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml) document which goes into detail on the structure of this file and more advanced configuration topics in general.
|
||||
|
||||
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.
|
||||
|
||||
Keep in mind that ES-DE will not install any RetroArch cores, you need to do this manually from within the RetroArch user interface.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
~/Applications/RetroArch-Linux-x86_64.AppImage
|
||||
~/.local/bin/RetroArch-Linux-x86_64.AppImage
|
||||
~/bin/RetroArch-Linux-x86_64.AppImage
|
||||
```
|
||||
|
||||
In any instance, an error notification will be displayed if attempting to launch a game where the emulator binary is not found. Likewise a notification will be shown if the defined emulator core is not installed. The es_log.txt file will also provide additional details.
|
||||
|
||||
|
||||
## Scraping
|
||||
|
||||
Scraping means downloading metadata and game media files (images and videos) for the games in your collection.
|
||||
|
|
@ -1006,7 +983,6 @@ Remember that on Unix filenames are case sensitive, and as well the file extensi
|
|||
|
||||
It's possible to change the game media directory location from within ES-DE, for this see the option _Game media directory_.
|
||||
|
||||
|
||||
## Main menu
|
||||
|
||||
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.
|
||||
|
|
@ -1427,7 +1403,6 @@ Whether to use a shader to render scanlines for the videos. Be aware that this i
|
|||
|
||||
Whether to use a shader to render a slight horizontal blur which somewhat simulates a well-used CRT monitor. Be aware that this is quite demanding for the GPU.
|
||||
|
||||
|
||||
### Sound settings
|
||||
|
||||
Various sound settings.
|
||||
|
|
@ -1460,7 +1435,6 @@ With this turned off, audio won't play for videos when using the video screensav
|
|||
|
||||
Enables or disables navigation sounds throughout the application. Sounds are played when browsing systems and lists, starting games, adding and removing games as favorites etc. The sounds can be customized per theme, but if the theme does not support navigation sounds, ES-DE will fall back to its built-in samples.
|
||||
|
||||
|
||||
### Input device settings
|
||||
|
||||
Settings related to the input devices, i.e. the keyboard and controllers.
|
||||
|
|
@ -1477,7 +1451,6 @@ If enabling this option, only the first controller detected during startup will
|
|||
|
||||
This tool provides configuration of button mappings for the keyboard and controllers, as explained [here](USERGUIDE.md#input-device-configuration). Normally this is not required as ES-DE automatically configures all input devices, but button customizations may be useful in some special situations. You may also need to run this tool if you have an unusual controller which could not be automatically configured. Be aware that custom button mappings will not change the help icons or help text.
|
||||
|
||||
|
||||
### Game collection settings
|
||||
|
||||
Handles collections, which are assembled using games present in the game systems. See the [collections](USERGUIDE-DEV.md#game-collections) section below in this document for more information.
|
||||
|
|
@ -1605,7 +1578,6 @@ Enabling or disabling the menu when the UI mode is set to Kid. Mostly intended f
|
|||
|
||||
With this setting enabled, there is a Quit menu shown as the last entry on the main menu which provides options to quit ES-DE, to reboot the computer or to power off the computer. With this setting disabled, there will simply be an entry to quit the application instead of the complete quit menu.
|
||||
|
||||
|
||||
### Quit / Quit EmulationStation
|
||||
The _Quit_ menu or _Quit EmulationStation_ entry as described by the _Show quit menu (reboot and power off entries)_ option above.
|
||||
|
||||
|
|
@ -1623,7 +1595,6 @@ Self explanatory.
|
|||
|
||||
Self explanatory.
|
||||
|
||||
|
||||
## Game options menu
|
||||
|
||||
This menu is opened from the gamelist view, and can't be accessed from the system view. The menu changes slightly depending on the context, for example if a game file or a folder is selected, or whether the current system is a collection or a normal game system.
|
||||
|
|
@ -1715,7 +1686,6 @@ This entry is only visible if the system is a custom collection and it's current
|
|||
|
||||
This opens the metadata editor for the currently selected game file or folder.
|
||||
|
||||
|
||||
## Metadata editor
|
||||
|
||||
In the metadata editor, you can modify the metadata, scrape for game info and media files, clear the entry which will delete all metadata and game media files, or delete the entire game which also removes its file on the filesystem. When manually modifying a value, it will change color from gray to blue, and if the scraper has changed a value, it will change to red. When leaving the metadata editor you will be asked whether you want to save any settings done manually or by the scraper.
|
||||
|
|
@ -1929,7 +1899,6 @@ If you copy or migrate a collection from a previous version of EmulationStation
|
|||
|
||||
If you're migrating from a previous version of EmulationStation that has absolute paths in the collection files, these will be rewritten with the %ROMPATH% variable the first time you make a change to the collection.
|
||||
|
||||
|
||||
## Themes
|
||||
|
||||
ES-DE is fully themeable, and although the application ships with the comprehensive rbsimple-DE and modern-DE theme sets, you can use any RetroPie-compatible EmulationStation themes as well. Just be aware that ES-DE has added additional theme functionality compared to the RetroPie fork and more still will be added in future versions. This means that you may not get the full benefits of the application if you're using a theme set which has not been updated specifically for ES-DE. Some themes may also look slightly different as bugs that were present in the RetroPie fork have been fixed. Also note that most Batocera and Recalbox themes are not compatible as these forks are quite different.
|
||||
|
|
@ -1966,24 +1935,20 @@ https://wiki.batocera.org/themes
|
|||
|
||||
_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
|
||||
|
||||
There are numerous locations throughout ES-DE where custom scripts will be executed if the option to do so has been enabled in the settings. By default it's deactivated so be sure to enable it to use this feature.
|
||||
|
||||
The setup for event scripts is a bit technical, so refer to the [INSTALL-DEV.md](INSTALL-DEV.md#custom-event-scripts) document to see how it's configured.
|
||||
|
||||
|
||||
## 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 retrogaming solution. The setup is somewhat technical, refer to [INSTALL-DEV.md](INSTALL-DEV.md#portable-installation-on-windows) to see how it's done.
|
||||
|
||||
|
||||
## Command line options
|
||||
|
||||
See the [INSTALL-DEV.md](INSTALL-DEV.md#command-line-options) document for a list of the command line options per operating system.
|
||||
|
||||
|
||||
## Supported game systems
|
||||
|
||||
**Note:** The following list is what the default es_systems.xml files and the rbsimple-DE and modern-DE themes support. These theme sets are very comprehensive, so if you're using another theme, it may be that some or many of these systems are not supported. ES-DE will still work but the game system will unthemed which looks very ugly.
|
||||
|
|
|
|||
211
USERGUIDE.md
211
USERGUIDE.md
|
|
@ -24,7 +24,6 @@ For additional details, read on below.
|
|||
There are also installation videos available at the ES-DE YouTube channel:\
|
||||
[https://www.youtube.com/channel/UCosLuC9yIMQPKFBJXgDpvVQ](https://www.youtube.com/channel/UCosLuC9yIMQPKFBJXgDpvVQ)
|
||||
|
||||
|
||||
## Installation and first startup
|
||||
|
||||
To install ES-DE, just download the package or installer from [https://es-de.org](https://es-de.org) and follow the brief instructions below.
|
||||
|
|
@ -149,27 +148,10 @@ There will be a lot of directories created if using the es_systems.xml file bund
|
|||
|
||||
_This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._
|
||||
|
||||
|
||||
## Disabling game systems
|
||||
|
||||
The way ES-DE works is that it will always try to load any system for which there are game files available, so to disable a system it needs to be hidden from ES-DE. This is easily accomplished by renaming the game directory to something that is not recognized, for example changing `~/ROMs/c64` to `~/ROMs/c64_DISABLED`. Another approach is to create a subdirectory named DISABLED (or whatever name you prefer that is not matching a supported system) in the ROMs directory and move the game folder there, such as `~/ROMs/DISABLED/c64`. This makes it easy to disable and re-enable game systems in ES-DE. Note that the gamelist and any game media files are retained while the system is disabled so this is an entirely safe thing to do.
|
||||
|
||||
|
||||
## Using the Steam release of RetroArch
|
||||
|
||||
On Windows it's no problem to use the Steam release of RetroArch although you may have to add the installation location manually to your Path environment variable. By default the following locations will be searched:
|
||||
```
|
||||
C:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
D:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
C:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
D:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
```
|
||||
|
||||
If you have installed RetroArch at another location, simply start the Settings application, search for _path_ in the _Find a setting_ field and choose _Edit environment variables for your account_. Edit the _Path_ variable and add the directory where RetroArch is installed. This is required as there is no apparent way for ES-DE to find where RetroArch has been installed by the Steam application.
|
||||
|
||||
Unfortunately on Linux it's at the moment not possible to run the Steam release of RetroArch due to technical reasons. This RetroArch release runs as a type of container which can't be executed from ES-DE while correctly passing the necessary core and game options. Similarly it's not possible to launch RetroArch via the Steam application either as there seems to be a bug in Steam or RetroArch that prevents blankspaces from being present in game ROM files when passed as arguments (this works fine on Windows so it's definitely a Linux-specific issue and as well the same problem occurs if attempting to manually enter the launch command from a terminal window).
|
||||
|
||||
|
||||
## Specific notes for Windows
|
||||
|
||||
In general it should be straightforward to run ES-DE on Windows. Almost all emulators are available on this operating system and driver quality and controller support is normally very good.
|
||||
|
|
@ -213,7 +195,6 @@ A minor annoyance is that macOS creates metadata files starting with ._ in the f
|
|||
|
||||
Another problem on macOS 11 Big Sur (and possibly older OS versions) is that when connecting a Sony 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. The issue appears to be resolved in macOS Monterey.
|
||||
|
||||
|
||||
## Specific notes for Raspberry Pi
|
||||
|
||||
ES-DE on the Raspberry Pi requires a desktop environment, or more specifically a window manager and a sound server (like PulseAudio or PipeWire). There are no plans to add support for direct hardware access to the framebuffer or to ALSA. If you want to use your Raspberry Pi as an appliance, take a look at [RetroPie](https://retropie.org.uk), [Recalbox](https://www.recalbox.com) or [Batocera](https://batocera.org) instead.
|
||||
|
|
@ -259,7 +240,6 @@ On Raspberry Pi OS 10 Sony DualShock 4 controllers have problems with some butto
|
|||
|
||||
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 so for now this older OS version is recommended.
|
||||
|
||||
|
||||
## Game system customizations
|
||||
|
||||
The game systems configuration file `es_systems.xml` is located in the ES-DE resources directory which is part of the application installation. As such this file is not intended to be modified directly. If system customizations are required, a separate es_systems.xml file should instead be placed in the `custom_systems` folder in the ES-DE home directory, i.e. `~/.emulationstation/custom_systems/es_systems.xml`.
|
||||
|
|
@ -270,7 +250,6 @@ For example you may want to replace the emulator launch command, modify the full
|
|||
|
||||
The instructions for how to customize the es_systems.xml file can be found in [INSTALL.md](INSTALL.md#es_systemsxml). There you can also find some examples of custom files that you can copy into ~/.emulationstation/custom_systems/ and modify as required.
|
||||
|
||||
|
||||
## Migrating from other EmulationStation forks
|
||||
|
||||
**IMPORTANT!!! IMPORTANT!!! IMPORTANT!!!**
|
||||
|
|
@ -288,7 +267,6 @@ It's also strongly adviced to not rename an old es_settings.cfg file to es_setti
|
|||
|
||||
If migrating from Batocera or Recalbox, be aware that ES-DE follows the RetroPie naming conventions for game systems. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera and Recalbox has the _sg1000_ system name, but is _sg-1000_ in RetroPie and ES-DE. See the [Supported game systems](USERGUIDE.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE. This issue also means that theme sets that were written or adapted specifically for Batocera or Recalbox may display unthemed systems in ES-DE. All RetroPie theme sets should however work fine (of course assuming that all your systems are actually supported by the theme set).
|
||||
|
||||
|
||||
## Running on high resolution displays
|
||||
|
||||
ES-DE fully supports high resolution displays such as 1440p, 4K, 6K, 8K, ultrawide monitors etc. But many emulators (e.g. RetroArch) will also run using the same resolution which may cause performance problems on slower machines or when using resource intensive shaders. Although some emulator cores will have options to set their internal resolution, they still need to be scaled up to the screen resolution.
|
||||
|
|
@ -297,7 +275,6 @@ A solution to this is to use the custom event scripts functionality to set a tem
|
|||
|
||||
On macOS it's problematic to change screen resolutions on the fly or on a per-application basis as Apple has seemingly disabled most of this functionality in recent operating system releases. The only real option here is to lower the display resolution prior to launching ES-DE.
|
||||
|
||||
|
||||
## Input device configuration
|
||||
|
||||
ES-DE automatically configures the keyboard and any connected controllers using default button mappings, and normally no additional setup is required. But if you would like to apply custom button mappings for your devices or if you have an unusual device which isn't automatically configured, you can run the _Configure keyboard and controllers_ tool from the _Input device settings_ entry on the main menu.
|
||||
|
|
@ -310,7 +287,6 @@ Any custom configuration is applied per unique device ID (GUID). So if two ident
|
|||
|
||||
If you have issues with your input configuration, as a last resort you can reset all the mappings by deleting or renaming the file ~/.emulationstation/es_input.xml.
|
||||
|
||||
|
||||
## System view (main screen)
|
||||
|
||||
When starting ES-DE with the default settings, you will see the System view first. From here you can navigate your game systems and enter their respective gamelists.
|
||||
|
|
@ -322,7 +298,6 @@ The game systems are sorted by their full names by default, as defined in the es
|
|||
|
||||
_The **System view** is the default starting point for the application, it's here that you browse through your game systems._
|
||||
|
||||
|
||||
## Gamelist view
|
||||
|
||||
The gamelist view is where you browse and start your games, and it's where you will spend most of your time using ES-DE.
|
||||
|
|
@ -345,7 +320,6 @@ _The **Gamelist view** is where you browse the games for a specific system._
|
|||
|
||||
_Here's an example of what the Basic view style looks like. Needless to say, ES-DE is not intended to be used like this. After scraping some game media for the system, the view style will automatically change to Detailed or Video (assuming the Automatic view style option has been selected)._
|
||||
|
||||
|
||||
## UI modes
|
||||
|
||||
ES-DE supports three separate modes, **Full**, **Kiosk** and **Kid**.
|
||||
|
|
@ -360,7 +334,6 @@ There is an unlock code available to revert to the Full mode from the Kiosk or K
|
|||
|
||||
The application can also be forced into any of the three modes via the command line options `--force-full`, `--force-kiosk` and `--force-kid`. This is only temporary until the restart of the application, unless the settings menu is entered and the setting is saved to the configuration file (this assumes that the main menu is available in the selected UI mode of course).
|
||||
|
||||
|
||||
## Help system
|
||||
|
||||
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.
|
||||
|
|
@ -368,7 +341,6 @@ There is a help system available throughout the application that provides an ove
|
|||
|
||||
_The help system is displayed at the bottom of the screen, indicating the various actions currently available._
|
||||
|
||||
|
||||
## General navigation
|
||||
|
||||
The built-in help system will provide a contextual summary of the available navigation options, but here's still a general overview. These are the buttons mappings automatically applied by ES-DE, but they can be customized using the input configurator as described earlier in this document. It's not an exhaustive list, but it covers most situations. The button names are based on the Xbox 360 controller as that is the naming convention used by the SDL library which handles the controller input in ES-DE.
|
||||
|
|
@ -434,6 +406,93 @@ Marks games as favorites in the gamelist view (if the _Enable toggle favorites b
|
|||
|
||||
Quits the application. This key combination can be changed using the _Exit button combo_ menu option described later in this document.
|
||||
|
||||
## RetroArch setup
|
||||
|
||||
ES-DE is a game browsing frontend and does not provide any emulation by itself. It does however come preconfigured for use with emulators as setup in the `es_systems.xml` file. By default it's primarily setup for use with [RetroArch](https://www.retroarch.com) but this can be modified if needed. If you're interested in customizing your es_systems.xml file, please refer to the [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml) document which goes into detail on the structure of this file and more advanced configuration topics in general.
|
||||
|
||||
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.
|
||||
|
||||
Keep in mind that ES-DE will not install any RetroArch cores, you need to do this manually from within the RetroArch user interface.
|
||||
|
||||
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 AppImage as there is no standardized directory for storing these files. Read more [here](USERGUIDE.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.
|
||||
|
||||
## Using the Steam release of RetroArch
|
||||
|
||||
On Windows it's no problem to use the Steam release of RetroArch although you may have to add the installation location manually to your Path environment variable. By default the following locations will be searched:
|
||||
```
|
||||
C:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
D:\Program Files (x86)\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
C:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
D:\Program Files\Steam\steamapps\common\RetroArch\retroarch.exe
|
||||
```
|
||||
|
||||
If you have installed RetroArch at another location, simply start the Settings application, search for _path_ in the _Find a setting_ field and choose _Edit environment variables for your account_. Edit the _Path_ variable and add the directory where RetroArch is installed. This is required as there is no apparent way for ES-DE to find where RetroArch has been installed by the Steam application.
|
||||
|
||||
Unfortunately on Linux it's at the moment not possible to run the Steam release of RetroArch due to technical reasons. This RetroArch release runs as a type of container which can't be executed from ES-DE while correctly passing the necessary core and game options. Similarly it's not possible to launch RetroArch via the Steam application either as there seems to be a bug in Steam or RetroArch that prevents blankspaces from being present in game ROM files when passed as arguments (this works fine on Windows so it's definitely a Linux-specific issue and as well the same problem occurs if attempting to manually enter the launch command from a terminal window).
|
||||
|
||||
## 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 where to place 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:
|
||||
|
||||
```
|
||||
~/Applications/
|
||||
~/.local/bin/
|
||||
~/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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
After taking this step, a symlink can be created:
|
||||
```
|
||||
cd ~/Applications
|
||||
ln -s rpcs3-v0.0.19-13103-cc21d1b3_linux64_54579676ed3fa60dafec7188286495e4.AppImage rpcs3.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:
|
||||
|
||||
| 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
|
||||
```
|
||||
|
||||
## Getting your games into ES-DE
|
||||
|
||||
For most systems this is straightforward, just put your game files into the folder corresponding to the platform name (these names can be found at the [end](USERGUIDE.md#supported-game-systems) of this guide.)
|
||||
|
|
@ -550,60 +609,6 @@ The only exception is that the _Delete_ button in the metadata editor will be di
|
|||
|
||||
When setting up a directory like this, make sure to not name any files or folders inside the base directory using the same extension as that will force the base directory to be processed normally, breaking the functionality.
|
||||
|
||||
### 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 where to place 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:
|
||||
|
||||
```
|
||||
~/Applications/
|
||||
~/.local/bin/
|
||||
~/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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
After taking this step, a symlink can be created:
|
||||
```
|
||||
cd ~/Applications
|
||||
ln -s rpcs3-v0.0.19-13103-cc21d1b3_linux64_54579676ed3fa60dafec7188286495e4.AppImage rpcs3.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:
|
||||
|
||||
| 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
|
||||
```
|
||||
|
||||
### Special game installation considerations
|
||||
|
||||
Not all systems are as simple as described above, or there may be multiple ways to do the configuration. Specifics for such systems will be covered here. Consider this a work in progress as there are many platforms supported by ES-DE.
|
||||
|
|
@ -622,7 +627,7 @@ The Nintendo Switch emulator Yuzu is distributed as a Snap package, Flatpak pack
|
|||
|
||||
If installed as a Snap or Flatpak package or if built from source code on Linux, ES-DE should be able to easily locate the emulator binary.
|
||||
|
||||
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#emulators-in-appimage-format-on-linux) for more information on how to get it to work.
|
||||
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#using-emulators-in-appimage-format-on-linux) for more information on how to get it to work.
|
||||
|
||||
For Windows, ES-DE will look for _yuzu.exe_ in the system Path as well as in the default installation directory `~\AppData\Local\yuzu\yuzu-windows-msvc\`
|
||||
|
||||
|
|
@ -636,7 +641,7 @@ On Windows RPCS3 does not ship with an installer but rather as a zip file that c
|
|||
|
||||
On Linux RPCS3 is shipped as a Snap package, Flatpak package or AppImage. If installed as a Snap or Flatpak or if built from source code, ES-DE should be able to easily locate the emulator binary.
|
||||
|
||||
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#emulators-in-appimage-format-on-linux) for more information on how to get it to work.
|
||||
But if using the AppImage release it's a bit more complicated. See [here](USERGUIDE.md#using-emulators-in-appimage-format-on-linux) for more information on how to get it to work.
|
||||
|
||||
As for the game installation on both Windows and Linux, you need to retain the directory structure of the Blu-ray disc or the directory created by installing the .pkg file. Each directory needs to be renamed by adding the .ps3dir extension, which will make ES-DE interpret the directory as if it were a file and pass that directory to the emulator when launching a game.
|
||||
|
||||
|
|
@ -852,33 +857,6 @@ This of course assumes that you have menu entries setup for your Steam games.
|
|||
|
||||
To greatly simplify this setup, automatic Steam library import is planned for a future ES-DE release.
|
||||
|
||||
|
||||
## RetroArch setup
|
||||
|
||||
ES-DE is a game browsing frontend and does not provide any emulation by itself. It does however come preconfigured for use with emulators as setup in the `es_systems.xml` file. By default it's primarily setup for use with [RetroArch](https://www.retroarch.com) but this can be modified if needed. If you're interested in customizing your es_systems.xml file, please refer to the [INSTALL.md](INSTALL.md#es_systemsxml) document which goes into detail on the structure of this file and more advanced configuration topics in general.
|
||||
|
||||
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.
|
||||
|
||||
Keep in mind that ES-DE will not install any RetroArch cores, you need to do this manually from within the RetroArch user interface.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
~/Applications/RetroArch-Linux-x86_64.AppImage
|
||||
~/.local/bin/RetroArch-Linux-x86_64.AppImage
|
||||
~/bin/RetroArch-Linux-x86_64.AppImage
|
||||
```
|
||||
|
||||
In any instance, an error notification will be displayed if attempting to launch a game where the emulator binary is not found. Likewise a notification will be shown if the defined emulator core is not installed. The es_log.txt file will also provide additional details.
|
||||
|
||||
|
||||
## Scraping
|
||||
|
||||
Scraping means downloading metadata and game media files (images and videos) for the games in your collection.
|
||||
|
|
@ -997,7 +975,6 @@ Remember that on Unix filenames are case sensitive, and as well the file extensi
|
|||
|
||||
It's possible to change the game media directory location from within ES-DE, for this see the option _Game media directory_.
|
||||
|
||||
|
||||
## Main menu
|
||||
|
||||
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.
|
||||
|
|
@ -1439,7 +1416,6 @@ With this turned off, audio won't play for videos when using the video screensav
|
|||
|
||||
Enables or disables navigation sounds throughout the application. Sounds are played when browsing systems and lists, starting games, adding and removing games as favorites etc. The sounds can be customized per theme, but if the theme does not support navigation sounds, ES-DE will fall back to its built-in samples.
|
||||
|
||||
|
||||
### Input device settings
|
||||
|
||||
Settings related to the input devices, i.e. the keyboard and controllers.
|
||||
|
|
@ -1456,7 +1432,6 @@ If enabling this option, only the first controller detected during startup will
|
|||
|
||||
This tool provides configuration of button mappings for the keyboard and controllers, as explained [here](USERGUIDE.md#input-device-configuration). Normally this is not required as ES-DE automatically configures all input devices, but button customizations may be useful in some special situations. You may also need to run this tool if you have an unusual controller which could not be automatically configured. Be aware that custom button mappings will not change the help icons or help text.
|
||||
|
||||
|
||||
### Game collection settings
|
||||
|
||||
Handles collections, which are assembled using games present in the game systems. See the [collections](USERGUIDE.md#game-collections) section below in this document for more information.
|
||||
|
|
@ -1584,7 +1559,6 @@ Enabling or disabling the menu when the UI mode is set to Kid. Mostly intended f
|
|||
|
||||
With this setting enabled, there is a Quit menu shown as the last entry on the main menu which provides options to quit ES-DE, to reboot the computer or to power off the computer. With this setting disabled, there will simply be an entry to quit the application instead of the complete quit menu.
|
||||
|
||||
|
||||
### Quit / Quit EmulationStation
|
||||
The _Quit_ menu or _Quit EmulationStation_ entry as described by the _Show quit menu (reboot and power off entries)_ option above.
|
||||
|
||||
|
|
@ -1602,7 +1576,6 @@ Self explanatory.
|
|||
|
||||
Self explanatory.
|
||||
|
||||
|
||||
## Game options menu
|
||||
|
||||
This menu is opened from the gamelist view, and can't be accessed from the system view. The menu changes slightly depending on the context, for example if a game file or a folder is selected, or whether the current system is a collection or a normal game system.
|
||||
|
|
@ -1694,7 +1667,6 @@ This entry is only visible if the system is a custom collection and it's current
|
|||
|
||||
This opens the metadata editor for the currently selected game file or folder.
|
||||
|
||||
|
||||
## Metadata editor
|
||||
|
||||
In the metadata editor, you can modify the metadata, scrape for game info and media files, clear the entry which will delete all metadata and game media files, or delete the entire game which also removes its file on the filesystem. When manually modifying a value, it will change color from gray to blue, and if the scraper has changed a value, it will change to red. When leaving the metadata editor you will be asked whether you want to save any settings done manually or by the scraper.
|
||||
|
|
@ -1904,7 +1876,6 @@ If you copy or migrate a collection from a previous version of EmulationStation
|
|||
|
||||
If you're migrating from a previous version of EmulationStation that has absolute paths in the collection files, these will be rewritten with the %ROMPATH% variable the first time you make a change to the collection.
|
||||
|
||||
|
||||
## Themes
|
||||
|
||||
ES-DE is fully themeable, and although the application ships with the comprehensive rbsimple-DE and modern-DE theme sets, you can use any RetroPie-compatible EmulationStation themes as well. Just be aware that ES-DE has added additional theme functionality compared to the RetroPie fork and more still will be added in future versions. This means that you may not get the full benefits of the application if you're using a theme set which has not been updated specifically for ES-DE. Some themes may also look slightly different as bugs that were present in the RetroPie fork have been fixed. Also note that most Batocera and Recalbox themes are not compatible as these forks are quite different.
|
||||
|
|
@ -1941,24 +1912,20 @@ https://wiki.batocera.org/themes
|
|||
|
||||
_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
|
||||
|
||||
There are numerous locations throughout ES-DE where custom scripts will be executed if the option to do so has been enabled in the settings. By default it's deactivated so be sure to enable it to use this feature.
|
||||
|
||||
The setup for event scripts is a bit technical, so refer to the [INSTALL.md](INSTALL.md#custom-event-scripts) document to see how it's configured.
|
||||
|
||||
|
||||
## 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 retrogaming solution. The setup is somewhat technical, refer to [INSTALL.md](INSTALL.md#portable-installation-on-windows) to see how it's done.
|
||||
|
||||
|
||||
## Command line options
|
||||
|
||||
See the [INSTALL.md](INSTALL.md#command-line-options) document for a list of the command line options per operating system.
|
||||
|
||||
|
||||
## Supported game systems
|
||||
|
||||
**Note:** The following list is what the default es_systems.xml files and the rbsimple-DE and modern-DE themes support. These theme sets are very comprehensive, so if you're using another theme, it may be that some or many of these systems are not supported. ES-DE will still work but the game system will unthemed which looks very ugly.
|
||||
|
|
|
|||
Loading…
Reference in a new issue