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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2022-04-14 16:50:05 +02:00
parent 3021062e2e
commit 15b42664af
4 changed files with 38 additions and 165 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

95
INSTALL-DEV.md
View file

@ -1722,6 +1722,8 @@ By default all controller input (keyboard and controller button presses) will be
## Portable installation on Windows ## Portable installation on Windows
_As there is a preconfigured portable release available for Windows, this section is mostly relevant for understanding how the setup works, as well as to provide information on how to make customizations._
It's possible to easily create a portable installation of ES-DE on Windows, for example to place on a USB memory stick. It's possible to easily create a portable installation of ES-DE on Windows, for example to place on a USB memory stick.
For this example, let's assume that the removable media has the device name `F:\` For this example, let's assume that the removable media has the device name `F:\`
@ -1730,105 +1732,28 @@ These are the steps to perform:
* Install ES-DE * Install ES-DE
* Copy the EmulationStation-DE installation directory to F:\ * Copy the EmulationStation-DE installation directory to F:\
* Copy your emulator directories to F:\EmulationStation-DE\ * Create a directory named F:\EmulationStation-DE\Emulators
* Copy your emulator directories to F:\EmulationStation-DE\Emulators\
* Copy your ROMs directory to F:\EmulationStation-DE\ * Copy your ROMs directory to F:\EmulationStation-DE\
* Create an empty file named portable.txt in F:\EmulationStation-DE\ * Create an empty file named portable.txt in F:\EmulationStation-DE\
You should end up with something like this: You should end up with something like this:
``` ```
F:\EmulationStation-DE\ F:\EmulationStation-DE\
F:\EmulationStation-DE\dosbox-staging\ F:\EmulationStation-DE\Emulators\dosbox-staging\
F:\EmulationStation-DE\RetroArch-Win64\ F:\EmulationStation-DE\Emulators\RetroArch-Win64\
F:\EmulationStation-DE\Emulators\RPCS3\
F:\EmulationStation-DE\Emulators\xemu\
F:\EmulationStation-DE\ROMs\ F:\EmulationStation-DE\ROMs\
F:\EmulationStation-DE\RPCS3\
F:\EmulationStation-DE\xemu\
F:\EmulationStation-DE\portable.txt F:\EmulationStation-DE\portable.txt
``` ```
This is just an example as you may of course not use these specific emulators. There are also many more emulators supported as described below. As well there will be many more files and directories than those listed above inside the F:\EmulationStation-DE directory. This is just an example as you may of course not use these specific emulators. There are also many more emulators supported as detailed in the `es_find_rules.xml` configuration file. As well there will be many more files and directories than those listed above inside the F:\EmulationStation-DE folder.
How the portable setup works is that when ES-DE finds a file named portable.txt in its executable directory, it will by default locate the .emulationstation directory directly inside this folder. It's 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:\ for this example. How the portable setup works is that when ES-DE finds a file named portable.txt in its executable directory, it will by default locate the .emulationstation directory directly inside this folder. It's 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:\ for this example.
If the --home command line parameter is passed when starting ES-DE, that will override the portable.txt file. If the --home command line parameter is passed when starting ES-DE, that will override the portable.txt file.
By default 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
cemu\Cemu.exe
Citra\canary-mingw\citra.exe
Citra\nightly-mingw\citra.exe
Dolphin-x64\Dolphin.exe
dosbox-staging\dosbox.exe
duckstation\duckstation-nogui-x64-ReleaseLTCG.exe
duckstation\duckstation-qt-x64-ReleaseLTCG.exe
flycast\flycast.exe
mame\mame.exe
melonDS\melonDS.exe
mGBA\mGBA.exe
mupen64plus\mupen64plus-ui-console.exe
PCSX2\pcsx2.exe
PPSSPP\PPSSPPWindows64.exe
redream\redream.exe
RPCS3\rpcs3.exe
ryujinx\Ryujinx.exe
VBA-M\visualboyadvance-m.exe
xemu\xemu.exe
xenia\xenia.exe
yuzu\yuzu-windows-msvc\yuzu.exe
Emulators\RetroArch-Win64\retroarch.exe
Emulators\RetroArch\retroarch.exe
Emulators\cemu\Cemu.exe
Emulators\Citra\canary-mingw\citra.exe
Emulators\Citra\nightly-mingw\citra.exe
Emulators\Dolphin-x64\Dolphin.exe
Emulators\dosbox-staging\dosbox.exe
Emulators\duckstation\duckstation-nogui-x64-ReleaseLTCG.exe
Emulators\duckstation\duckstation-qt-x64-ReleaseLTCG.exe
Emulators\flycast\flycast.exe
Emulators\mame\mame.exe
Emulators\melonDS\melonDS.exe
Emulators\mGBA\mGBA.exe
Emulators\mupen64plus\mupen64plus-ui-console.exe
Emulators\PCSX2\pcsx2.exe
Emulators\PPSSPP\PPSSPPWindows64.exe
Emulators\redream\redream.exe
Emulators\RPCS3\rpcs3.exe
Emulators\ryujinx\Ryujinx.exe
Emulators\VBA-M\visualboyadvance-m.exe
Emulators\xemu\xemu.exe
Emulators\xenia\xenia.exe
Emulators\yuzu\yuzu-windows-msvc\yuzu.exe
..\RetroArch-Win64\retroarch.exe
..\RetroArch\retroarch.exe
..\cemu\Cemu.exe
..\Citra\canary-mingw\citra.exe
..\Citra\nightly-mingw\citra.exe
..\Dolphin-x64\Dolphin.exe
..\dosbox-staging\dosbox.exe
..\duckstation\duckstation-nogui-x64-ReleaseLTCG.exe
..\duckstation\duckstation-qt-x64-ReleaseLTCG.exe
..\flycast\flycast.exe
..\mame\mame.exe
..\melonDS\melonDS.exe
..\mGBA\mGBA.exe
..\mupen64plus\mupen64plus-ui-console.exe
..\PCSX2\pcsx2.exe
..\PPSSPP\PPSSPPWindows64.exe
..\redream\redream.exe
..\RPCS3\rpcs3.exe
..\ryujinx\Ryujinx.exe
..\VBA-M\visualboyadvance-m.exe
..\xemu\xemu.exe
..\xenia\xenia.exe
..\yuzu\yuzu-windows-msvc\yuzu.exe
```
If you want to place your emulators elsewhere, you need to create a customized es_find_rules.xml file, which is explained earlier in this document.
Start ES-DE from the F:\ device and check that everything works as expected. Just be aware that some emulators may not play that well with a portable setup and may store their configuration files in your home directory (probably on your C: drive) or at some other location. So when using the portable installation on another computer you may need to perform some additional emulator-specific setup. Start ES-DE from the F:\ device and check that everything works as expected. Just be aware that some emulators may not play that well with a portable setup and may store their configuration files in your home directory (probably on your C: drive) or at some other location. So when using the portable installation on another computer you may need to perform some additional emulator-specific setup.
Following this, optionally copy any existing gamelist.xml files, game media files etc. to the removable media. For example: Following this, optionally copy any existing gamelist.xml files, game media files etc. to the removable media. For example:
@ -1839,7 +1764,7 @@ F:\EmulationStation-DE\.emulationstation\downloaded_media\
F:\EmulationStation-DE\.emulationstation\gamelists\ F:\EmulationStation-DE\.emulationstation\gamelists\
``` ```
You could also copy over your entire .emulationstation directory, but in this case make sure that you have no settings in es_settings.xml that point to a specific location on your local filesystem, such as the game ROMs or game media directories. You could alternatively copy over your entire .emulationstation directory, but in this case make sure that you have no settings in es_settings.xml that point to a specific location on your local filesystem, such as the game ROMs or game media directories.
You now have a fully functional portable retrogaming installation! You now have a fully functional portable retrogaming installation!

72
INSTALL.md
View file

@ -16,7 +16,6 @@ For automatic code formatting [clang-format](https://clang.llvm.org/docs/ClangFo
Any code editor can be used of course, but I recommend [VSCode](https://code.visualstudio.com). Any code editor can be used of course, but I recommend [VSCode](https://code.visualstudio.com).
## Building on Unix ## Building on Unix
There are some dependencies that need to be fulfilled in order to build ES-DE. These are detailed per operating system below. There are some dependencies that need to be fulfilled in order to build ES-DE. These are detailed per operating system below.
@ -1992,9 +1991,10 @@ This will reload either a single gamelist or all gamelists depending on where yo
By default all controller input (keyboard and controller button presses) will be logged when the --debug flag has been passed. To disable the input logging, the setting DebugSkipInputLogging kan be set to false in the es_settings.xml file. There is no menu entry to change this as it's intended for developers and not for end users. By default all controller input (keyboard and controller button presses) will be logged when the --debug flag has been passed. To disable the input logging, the setting DebugSkipInputLogging kan be set to false in the es_settings.xml file. There is no menu entry to change this as it's intended for developers and not for end users.
## Portable installation on Windows ## Portable installation on Windows
_As there is a preconfigured portable release available for Windows, this section is mostly relevant for understanding how the setup works, as well as to provide information on how to make customizations._
It's possible to easily create a portable installation of ES-DE on Windows, for example to place on a USB memory stick. It's possible to easily create a portable installation of ES-DE on Windows, for example to place on a USB memory stick.
For this example, let's assume that the removable media has the device name `F:\` For this example, let's assume that the removable media has the device name `F:\`
@ -2003,80 +2003,28 @@ These are the steps to perform:
* Install ES-DE * Install ES-DE
* Copy the EmulationStation-DE installation directory to F:\ * Copy the EmulationStation-DE installation directory to F:\
* Copy your emulator directories to F:\EmulationStation-DE\ * Create a directory named F:\EmulationStation-DE\Emulators
* Copy your emulator directories to F:\EmulationStation-DE\Emulators\
* Copy your ROMs directory to F:\EmulationStation-DE\ * Copy your ROMs directory to F:\EmulationStation-DE\
* Create an empty file named portable.txt in F:\EmulationStation-DE\ * Create an empty file named portable.txt in F:\EmulationStation-DE\
You should end up with something like this: You should end up with something like this:
``` ```
F:\EmulationStation-DE\ F:\EmulationStation-DE\
F:\EmulationStation-DE\dosbox-staging\ F:\EmulationStation-DE\Emulators\dosbox-staging\
F:\EmulationStation-DE\RetroArch-Win64\ F:\EmulationStation-DE\Emulators\RetroArch-Win64\
F:\EmulationStation-DE\Emulators\RPCS3\
F:\EmulationStation-DE\Emulators\xemu\
F:\EmulationStation-DE\ROMs\ F:\EmulationStation-DE\ROMs\
F:\EmulationStation-DE\RPCS3\
F:\EmulationStation-DE\xemu\
F:\EmulationStation-DE\portable.txt F:\EmulationStation-DE\portable.txt
``` ```
This is just an example as you may of course not use these specific emulators. There are also many more emulators supported as described below. As well there will be many more files and directories than those listed above inside the F:\EmulationStation-DE directory. This is just an example as you may of course not use these specific emulators. There are also many more emulators supported as detailed in the `es_find_rules.xml` configuration file. As well there will be many more files and directories than those listed above inside the F:\EmulationStation-DE folder.
How the portable setup works is that when ES-DE finds a file named portable.txt in its executable directory, it will by default locate the .emulationstation directory directly inside this folder. It's 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:\ for this example. How the portable setup works is that when ES-DE finds a file named portable.txt in its executable directory, it will by default locate the .emulationstation directory directly inside this folder. It's 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:\ for this example.
If the --home command line parameter is passed when starting ES-DE, that will override the portable.txt file. If the --home command line parameter is passed when starting ES-DE, that will override the portable.txt file.
By default 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
cemu\Cemu.exe
Citra\canary-mingw\citra.exe
Citra\nightly-mingw\citra.exe
Dolphin-x64\Dolphin.exe
dosbox-staging\dosbox.exe
duckstation\duckstation-nogui-x64-ReleaseLTCG.exe
duckstation\duckstation-qt-x64-ReleaseLTCG.exe
flycast\flycast.exe
mame\mame.exe
melonDS\melonDS.exe
mGBA\mGBA.exe
mupen64plus\mupen64plus-ui-console.exe
PCSX2\pcsx2.exe
PPSSPP\PPSSPPWindows64.exe
redream\redream.exe
RPCS3\rpcs3.exe
ryujinx\Ryujinx.exe
VBA-M\visualboyadvance-m.exe
xemu\xemu.exe
xenia\xenia.exe
yuzu\yuzu-windows-msvc\yuzu.exe
..\RetroArch-Win64\retroarch.exe
..\RetroArch\retroarch.exe
..\cemu\Cemu.exe
..\Citra\canary-mingw\citra.exe
..\Citra\nightly-mingw\citra.exe
..\Dolphin-x64\Dolphin.exe
..\dosbox-staging\dosbox.exe
..\duckstation\duckstation-nogui-x64-ReleaseLTCG.exe
..\duckstation\duckstation-qt-x64-ReleaseLTCG.exe
..\flycast\flycast.exe
..\mame\mame.exe
..\melonDS\melonDS.exe
..\mGBA\mGBA.exe
..\mupen64plus\mupen64plus-ui-console.exe
..\PCSX2\pcsx2.exe
..\PPSSPP\PPSSPPWindows64.exe
..\redream\redream.exe
..\RPCS3\rpcs3.exe
..\ryujinx\Ryujinx.exe
..\VBA-M\visualboyadvance-m.exe
..\xemu\xemu.exe
..\xenia\xenia.exe
..\yuzu\yuzu-windows-msvc\yuzu.exe
```
If you want to place your emulators elsewhere, you need to create a customized es_find_rules.xml file, which is explained earlier in this document.
Start ES-DE from the F:\ device and check that everything works as expected. Just be aware that some emulators may not play that well with a portable setup and may store their configuration files in your home directory (probably on your C: drive) or at some other location. So when using the portable installation on another computer you may need to perform some additional emulator-specific setup. Start ES-DE from the F:\ device and check that everything works as expected. Just be aware that some emulators may not play that well with a portable setup and may store their configuration files in your home directory (probably on your C: drive) or at some other location. So when using the portable installation on another computer you may need to perform some additional emulator-specific setup.
Following this, optionally copy any existing gamelist.xml files, game media files etc. to the removable media. For example: Following this, optionally copy any existing gamelist.xml files, game media files etc. to the removable media. For example:
@ -2087,7 +2035,7 @@ F:\EmulationStation-DE\.emulationstation\downloaded_media\
F:\EmulationStation-DE\.emulationstation\gamelists\ F:\EmulationStation-DE\.emulationstation\gamelists\
``` ```
You could also copy over your entire .emulationstation directory, but in this case make sure that you have no settings in es_settings.xml that point to a specific location on your local filesystem, such as the game ROMs or game media directories. You could alternatively copy over your entire .emulationstation directory, but in this case make sure that you have no settings in es_settings.xml that point to a specific location on your local filesystem, such as the game ROMs or game media directories.
You now have a fully functional portable retrogaming installation! You now have a fully functional portable retrogaming installation!

18
USERGUIDE-DEV.md
View file

@ -214,15 +214,19 @@ Note that the above are only examples to illustrate the general approach, you ma
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. 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.
Just make sure to not place games or other resources on network shares using the Microsoft SMB protocol as that will lead to unacceptable performance degradations. See the point above on how to setup an NFS share if you insist on placing files or other resources on network drives. Just make sure to not place games or other resources on network shares using the Microsoft SMB protocol as that will lead to unacceptable performance degradations and extremely long startup times if you have a large collection. See the point above on how to setup an NFS share if you insist on placing files or other resources on network drives.
In order for ES-DE to run, graphics drivers with OpenGL support have to be installed. If not, the application simply won't start. In order for ES-DE to run, graphics drivers with OpenGL support have to be installed. If not, the application simply won't start.
Installing DS4Windows will break controller input in ES-DE for unknown reasons. Uninstalling this software should resolve the issue. On Windows 11 both DualShock 4 (PS4) and DualSense (PS5) controllers have been tested wired and via Bluetooth and both work fine in both ES-DE and RetroArch without any special drivers or configuration. Installing DS4Windows will break controller input in ES-DE for unknown reasons. Uninstalling this software should resolve the issue. On Windows 11 both DualShock 4 (PS4) and DualSense (PS5) controllers have been tested wired and via Bluetooth and both work fine in both ES-DE and RetroArch without any special drivers or configuration.
An issue on Windows is that many 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). Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These emulators are commonly shipped as a ZIP file that can be unpacked anywhere on the filesystem. There are two ES-DE releases available for Windows; a regular installer and a portable/ZIP version. If going for the first option, an issue is that many 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 their installation path). Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These emulators are commonly shipped as a ZIP file that can be unpacked anywhere on the filesystem.
In order for ES-DE to find these emulators there are two possible solutions, the first is to manually add the emulator directories 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. If running ES-DE via Steam, you need to restart Steam as well to apply the changes to the Path variable. The second option is to place the emulators inside the ES-DE installation directory (for example `C:\Program Files\EmulationStation-DE\`) in which case they will be found when launching a game. Due to the Windows security model this could potentially cause issues for some emulators, so if you experience such problems ES-DE may need to be installed at a location where User Account Control (UAC) is not interfering. In order for ES-DE to find these emulators you need to add their directories 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. If running ES-DE via Steam, you need to restart Steam as well to apply the changes to the Path variable.
The second alternative is to use the portable/ZIP release of ES-DE. This can be unzipped anywhere, including to removable devices such as hard drives or USB memory sticks. Together with games and emulators this makes for a fully portable retrogaming solution. There is a README.txt file distributed with this release that describes the setup, but essentially you just place your games in the ROMs directory and your emulators in the Emulators directory, both of which are included in the portable release.
If you want to create your own portable intallation from scratch or customize the setup, [INSTALL-DEV.md](INSTALL-DEV.md#portable-installation-on-windows) provides additional details.
## Specific notes for macOS ## Specific notes for macOS
@ -2029,10 +2033,6 @@ There are numerous locations throughout ES-DE where custom scripts will be execu
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. 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 ## 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. See the [INSTALL-DEV.md](INSTALL-DEV.md#command-line-options) document for a list of the command line options per operating system.
@ -2051,7 +2051,7 @@ Sometimes the name of the console is (more or less) the same for multiple region
For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name. For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name.
The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable or place it inside the ES-DE installation directory. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup. The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. However, if using the portable/ZIP release of ES-DE, then this is not applicable as all emulators placed inside the `Emulators` directory will be automatically found. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup.
The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core.
@ -2072,7 +2072,7 @@ In general .zip or .7z files are recommended for smaller-sized games like those
Consider the table below a work in progress as it's obvioulsy not fully populated yet! Consider the table below a work in progress as it's obvioulsy not fully populated yet!
Default emulator/Alternative emulators columns: \ Default emulator/Alternative emulators columns: \
**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs to have a Path environment variable entry or be placed inside the ES-DE installation directory **[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs to have a Path environment variable entry (not applicable if using the portable ES-DE release)
All emulators are RetroArch cores unless marked as **(Standalone**) All emulators are RetroArch cores unless marked as **(Standalone**)

18
USERGUIDE.md
View file

@ -212,15 +212,19 @@ Note that the above are only examples to illustrate the general approach, you ma
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. 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.
Just make sure to not place games or other resources on network shares using the Microsoft SMB protocol as that will lead to unacceptable performance degradations. See the point above on how to setup an NFS share if you insist on placing files or other resources on network drives. Just make sure to not place games or other resources on network shares using the Microsoft SMB protocol as that will lead to unacceptable performance degradations and extremely long startup times if you have a large collection. See the point above on how to setup an NFS share if you insist on placing files or other resources on network drives.
In order for ES-DE to run, graphics drivers with OpenGL support have to be installed. If not, the application simply won't start. In order for ES-DE to run, graphics drivers with OpenGL support have to be installed. If not, the application simply won't start.
Installing DS4Windows will break controller input in ES-DE for unknown reasons. Uninstalling this software should resolve the issue. On Windows 11 both DualShock 4 (PS4) and DualSense (PS5) controllers have been tested wired and via Bluetooth and both work fine in both ES-DE and RetroArch without any special drivers or configuration. Installing DS4Windows will break controller input in ES-DE for unknown reasons. Uninstalling this software should resolve the issue. On Windows 11 both DualShock 4 (PS4) and DualSense (PS5) controllers have been tested wired and via Bluetooth and both work fine in both ES-DE and RetroArch without any special drivers or configuration.
An issue on Windows is that many 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). Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These emulators are commonly shipped as a ZIP file that can be unpacked anywhere on the filesystem. There are two ES-DE releases available for Windows; a regular installer and a portable/ZIP version. If going for the first option, an issue is that many 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 their installation path). Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These emulators are commonly shipped as a ZIP file that can be unpacked anywhere on the filesystem.
In order for ES-DE to find these emulators there are two possible solutions, the first is to manually add the emulator directories 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. If running ES-DE via Steam, you need to restart Steam as well to apply the changes to the Path variable. The second option is to place the emulators inside the ES-DE installation directory (for example `C:\Program Files\EmulationStation-DE\`) in which case they will be found when launching a game. Due to the Windows security model this could potentially cause issues for some emulators, so if you experience such problems ES-DE may need to be installed at a location where User Account Control (UAC) is not interfering. In order for ES-DE to find these emulators you need to add their directories 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. If running ES-DE via Steam, you need to restart Steam as well to apply the changes to the Path variable.
The second alternative is to use the portable/ZIP release of ES-DE. This can be unzipped anywhere, including to removable devices such as hard drives or USB memory sticks. Together with games and emulators this makes for a fully portable retrogaming solution. There is a README.txt file distributed with this release that describes the setup, but essentially you just place your games in the ROMs directory and your emulators in the Emulators directory, both of which are included in the portable release.
If you want to create your own portable intallation from scratch or customize the setup, [INSTALL.md](INSTALL.md#portable-installation-on-windows) provides additional details.
## Specific notes for macOS ## Specific notes for macOS
@ -2016,10 +2020,6 @@ There are numerous locations throughout ES-DE where custom scripts will be execu
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. 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 ## Command line options
See the [INSTALL.md](INSTALL.md#command-line-options) document for a list of the command line options per operating system. See the [INSTALL.md](INSTALL.md#command-line-options) document for a list of the command line options per operating system.
@ -2038,7 +2038,7 @@ Sometimes the name of the console is (more or less) the same for multiple region
For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name. For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name.
The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable or place it inside the ES-DE installation directory. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup. The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. However, if using the portable/ZIP release of ES-DE, then this is not applicable as all emulators placed inside the `Emulators` directory will be automatically found. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup.
The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core.
@ -2059,7 +2059,7 @@ In general .zip or .7z files are recommended for smaller-sized games like those
Consider the table below a work in progress as it's obvioulsy not fully populated yet! Consider the table below a work in progress as it's obvioulsy not fully populated yet!
Default emulator/Alternative emulators columns: \ Default emulator/Alternative emulators columns: \
**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs to have a Path environment variable entry or be placed inside the ES-DE installation directory **[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs to have a Path environment variable entry (not applicable if using the portable ES-DE release)
All emulators are RetroArch cores unless marked as **(Standalone**) All emulators are RetroArch cores unless marked as **(Standalone**)