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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2020-12-26 21:41:26 +01:00
parent b1bb9743f2
commit 2274995404
3 changed files with 290 additions and 231 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

483
INSTALL.md
View file

@ -1,6 +1,6 @@
# EmulationStation Desktop Edition - Installation and configuration # EmulationStation Desktop Edition (ES-DE) - Installation and configuration
**Note:** This is a quite technical document intended for those that are interested in compiling EmulationStation from source code, or would like to customize the configuration. If you just want to start using the software, check out the [User Guide](USERGUIDE.md) instead. **Note:** This is a quite technical document intended for those that are interested in compiling ES-DE from source code, or would like to customize the configuration. If you just want to start using the software, check out the [User guide](USERGUIDE.md) instead.
Table of contents: Table of contents:
@ -8,16 +8,14 @@ Table of contents:
## Development Environment ## Development Environment
EmulationStation-DE is developed and compiled using both Clang/LLVM and GCC on Unix, Clang/LLVM on macOS and GCC (MinGW) on Windows. I may try to get Clang/LLVM working on Windows as well. EmulationStation-DE is developed and compiled using both Clang/LLVM and GCC on Unix, Clang/LLVM on macOS and GCC (MinGW) on Windows.
There are more details regarding compilers later in this document.
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
The code has a few dependencies. For building, you'll need CMake and development packages for cURL, FreeImage, FreeType, libVLC, pugixml, SDL2 and RapidJSON. The code has some dependencies. For building, you'll need CMake and development packages for cURL, FreeImage, FreeType, libVLC, pugixml, SDL2 and RapidJSON.
**Installing dependencies:** **Installing dependencies:**
@ -76,7 +74,7 @@ pkg_add cmake pkgconf sdl2 freeimage vlc
In the same manner as for FreeBSD, Clang/LLVM and cURL should already be installed by default. In the same manner as for FreeBSD, Clang/LLVM and cURL should already be installed by default.
RapidJSON is not part of the OpenBSD ports/package collection as of v6.8, so you need to compile it yourself. At the time of writing, the latest release v1.1.0 does not compile on OpenBSD, so you need to compile the master branch: RapidJSON is not part of the OpenBSD ports/package collection as of v6.8, so you need to compile it yourself. At the time of writing, the latest release v1.1.0 does not compile on OpenBSD, so you need to use the master branch:
``` ```
git clone https://github.com/Tencent/rapidjson git clone https://github.com/Tencent/rapidjson
@ -118,7 +116,7 @@ To create a debug build, run this instead:
cmake -DCMAKE_BUILD_TYPE=Debug . cmake -DCMAKE_BUILD_TYPE=Debug .
make make
``` ```
Keep in mind though that a debug version will be much slower due to all compiler optimizations being disabled. Keep in mind that a debug version will be much slower due to all compiler optimizations being disabled.
To create a profiling build (optimized with debug symbols), run this: To create a profiling build (optimized with debug symbols), run this:
``` ```
@ -148,7 +146,7 @@ scan-build cmake -DCMAKE_BUILD_TYPE=Debug .
scan-build make -j6 scan-build make -j6
``` ```
You open the report with the **scan-view** command which lets you browse it using your web browser. Note that the compilation time is much higher when using the static analyzer compared to a normal compilation. As well this tool generates a lot of extra files and folders in the build tree, so it may make sense to run it on a separate copy of the ES source folder to avoid having to clean up all this extra data when the analysis has been completed. You open the report with the **scan-view** command which lets you browse it using your web browser. Note that the compilation time is much higher when using the static analyzer compared to a normal compilation. As well this tool generates a lot of extra files and folders in the build tree, so it may make sense to run it in a separate copy of the source folder to avoid having to clean up all this extra data when the analysis has been completed.
To build ES with CEC support, add the corresponding option, for example: To build ES with CEC support, add the corresponding option, for example:
@ -158,12 +156,12 @@ make
``` ```
I have however not been able to test the CEC support and I'm not entirely sure how it's supposed to work. I have however not been able to test the CEC support and I'm not entirely sure how it's supposed to work.
To build ES with the GLES renderer, run the following: To build with the GLES renderer, run the following:
``` ```
cmake -DCMAKE_BUILD_TYPE=Debug -DGLES=on . cmake -DCMAKE_BUILD_TYPE=Debug -DGLES=on .
make make
``` ```
Note that the GLES renderer is quite limited as there is no shader support for it, so ES will definitely not look as pretty as when using the default OpenGL renderer. Note that the GLES renderer is quite limited as there is no shader support for it, so ES-DE will definitely not look as pretty as when using the default OpenGL renderer.
Running multiple compile jobs in parallel is a good thing as it speeds up the build time a lot (scaling almost linearly). Here's an example telling make to run 6 parallel jobs: Running multiple compile jobs in parallel is a good thing as it speeds up the build time a lot (scaling almost linearly). Here's an example telling make to run 6 parallel jobs:
@ -171,20 +169,20 @@ Running multiple compile jobs in parallel is a good thing as it speeds up the bu
make -j6 make -j6
``` ```
By default EmulationStation will install under `/usr/local` but this can be changed by setting the `CMAKE_INSTALL_PREFIX` variable.\ By default ES-DE will install under /usr/local but this can be changed by setting the `CMAKE_INSTALL_PREFIX` variable.\
The following example will build the application for installtion under `/opt`: The following example will build the application for installtion under /opt:
``` ```
cmake -DCMAKE_INSTALL_PREFIX=/opt . cmake -DCMAKE_INSTALL_PREFIX=/opt .
``` ```
It's important to know that this is not only the directory used by the install script, the CMAKE_INSTALL_PREFIX variable also modifies code inside ES used to locate the required program resources. So it's necessary that the install prefix corresponds to the location where the application will actually be installed. It's important to know that this is not only the directory used by the install script, the CMAKE_INSTALL_PREFIX variable also modifies code inside ES-DE used to locate the required program resources. So it's necessary that the install prefix corresponds to the location where the application will actually be installed.
**Compilers** **Compilers**
Both Clang/LLVM and GCC work fine for building ES. Both Clang/LLVM and GCC work fine for building ES-DE.
I did some small benchmarks comparing Clang to GCC with the ES codebase (as of writing it's year 2020) and it's pretty interesting. I did some small benchmarks comparing Clang to GCC with the ES-DE codebase (as of writing it's year 2020) and it's pretty interesting.
Advantages with Clang (vs GCC): Advantages with Clang (vs GCC):
* 10% smaller binary size for a release build * 10% smaller binary size for a release build
@ -199,13 +197,13 @@ Advantage with GCC (vs Clang):
*Release build: Optimizations enabled, debug info disabled, binary stripped.* \ *Release build: Optimizations enabled, debug info disabled, binary stripped.* \
*Debug build: Optimizations disabled, debug info enabled, binary not stripped.* *Debug build: Optimizations disabled, debug info enabled, binary not stripped.*
This Clang debug build is LLVM "native", i.e. intended to be debugged using the LLVM project debugger LLDB. The problem is that this is still not well integrated with VSCode that I use for development so I need to keep using GDB. But this is problematic as the libstd++ data required by GDB is missing in the binary, making it impossible to see the values of for instance `std::string` variables. This Clang debug build is LLVM "native", i.e. intended to be debugged using the LLVM project debugger LLDB. The problem is that this is still not well integrated with VSCode that I use for development so I need to keep using GDB. But this is problematic as the libstd++ data required by GDB is missing in the binary, making it impossible to see the values of for instance std::string variables.
It's possible to activate the additional debug info needed by GDB by using the flag `-D_GLIBCXX_DEBUG`. I've added this to CMakeLists.txt when using Clang, but this bloats the binary and makes the code much slower. Actually, instead of a 4% faster application startup, it's now 36% slower! The same goes for the binary size, instead of 17% smaller it's now 17% larger. It's possible to activate the additional debug info needed by GDB by using the flag `-D_GLIBCXX_DEBUG`. I've added this to CMakeLists.txt when using Clang, but this bloats the binary and makes the code much slower. Actually, instead of a 4% faster application startup, it's now 36% slower! The same goes for the binary size, instead of 17% smaller it's now 17% larger.
I'm expecting this to be resolved in the near future though, and as I think Clang is an interesting compiler, I use it as the default when working on the project (I sometimes test with GCC to make sure that it still builds the software correctly). I'm expecting this to be resolved in the near future though, and as I think Clang is an interesting compiler, I use it as the default when working on the project (I sometimes test with GCC to make sure that it still builds the software correctly).
It's by the way very easy to switch between LLVM and GCC using Ubuntu, just use the `update-alternatives` command: It's by the way very easy to switch between LLVM and GCC using Ubuntu, just use the **update-alternatives** command:
``` ```
myusername@computer:~$ sudo update-alternatives --config c++ myusername@computer:~$ sudo update-alternatives --config c++
@ -232,7 +230,7 @@ Installing the software requires root permissions, the following command will in
sudo make install sudo make install
``` ```
Assuming the default installation prefix `/usr/local` has been used, this is the directory structure for the installation: Assuming the default installation prefix /usr/local has been used, this is the directory structure for the installation:
``` ```
/usr/local/bin/emulationstation /usr/local/bin/emulationstation
@ -245,27 +243,27 @@ Assuming the default installation prefix `/usr/local` has been used, this is the
/usr/local/share/pixmaps/emulationstation.svg /usr/local/share/pixmaps/emulationstation.svg
``` ```
ES will look in the following locations for the resources, in the listed order: ES-DE will look in the following locations for the resources, in the listed order:
* `[HOME]/.emulationstation/resources/` * \<home\>/.emulationstation/resources/
* `[INSTALL PREFIX]/share/emulationstation/resources/` * \<install prefix\>/share/emulationstation/resources/
* `[ES EXECUTABLE DIRECTORY]/resources/` * \<ES-DE executable directory\>/resources/
**Note:** The resources directory is critical, without it the application won't start. The resources directory is critical, without it the application won't start.
And it will look in the following locations for the themes, also in the listed order: And it will look in the following locations for the themes, also in the listed order:
* `[HOME]/.emulationstation/themes/` * \<home\>/.emulationstation/themes/
* `[INSTALL PREFIX]/share/emulationstation/themes/` * \<install prefix\>/share/emulationstation/themes/
* `[ES EXECUTABLE DIRECTORY]/themes/` * \<ES-DE executable directory\>/themes/
A theme is not mandatory to start the application, but ES will be basically useless without it. A theme is not mandatory to start the application, but ES-DE will be basically useless without it.
The home directory will always take precedence, and any resources or themes located there will override the ones in the installation path or in the path of the ES executable. The home directory will always take precedence, and any resources or themes located there will override the ones in the installation path or in the path of the ES-DE executable.
**Creating .deb and .rpm packages** **Creating .deb and .rpm packages**
Creation of Debian .deb packages is enabled by default, simply run `cpack` to generate the package: Creation of Debian .deb packages is enabled by default, simply run **cpack** to generate the package:
``` ```
myusername@computer:~/emulationstation-de$ cpack myusername@computer:~/emulationstation-de$ cpack
@ -290,7 +288,7 @@ The package can now be installed using a package manager, for example apt:
sudo apt install ./emulationstation-de-1.0.0.deb sudo apt install ./emulationstation-de-1.0.0.deb
``` ```
For RPM packages, remove the comment in the `CMakeLists.txt` accordingly, from: For RPM packages, remove the comment in CMakeLists.txt accordingly, from:
``` ```
#SET(CPACK_GENERATOR "RPM") #SET(CPACK_GENERATOR "RPM")
@ -300,7 +298,7 @@ to:
SET(CPACK_GENERATOR "RPM") SET(CPACK_GENERATOR "RPM")
``` ```
Then simply run `cpack`. Then simply run cpack.
On Fedora, you need to install rpmbuild before this command can be run though: On Fedora, you need to install rpmbuild before this command can be run though:
``` ```
@ -324,19 +322,19 @@ sudo dnf install ./emulationstation-de-1.0.0.rpm
## Building on macOS ## Building on macOS
EmulationStation for macOS is built using Clang/LLVM which is the default compiler for this operating system. It's pretty straightforward to build software on this OS. The main deficiency is that there is no native package manager, but as there are several third party package managers available, this can be partly compensated for. The use of one of them, `Homebrew`, is detailed below. EmulationStation for macOS is built using Clang/LLVM which is the default compiler for this operating system. It's pretty straightforward to build software on this OS. The main deficiency is that there is no native package manager, but as there are several third party package managers available, this can be partly compensated for. The use of one of them, [Homebrew](https://brew.sh), is detailed below.
As for code editing, I use [VSCode](https://code.visualstudio.com). I suppose Xcode could be used instead but I have no experience with this tool and no interest in it as I want to use the same tools for all the operating systems that I develop on. As for code editing, I use [VSCode](https://code.visualstudio.com). I suppose Xcode could be used instead but I have no experience with this tool and no interest in it as I want to use the same tools for all the operating systems that I develop on.
**Setting up the build tools:** **Setting up the build tools:**
Install the Command Line Tools which include Clang/LLVM, Git, make etc. Simply open a terminal and enter the command `clang`. This will open a dialog that will let you download and install the tools. Install the Command Line Tools which include Clang/LLVM, Git, make etc. Simply open a terminal and enter the command **clang**. This will open a dialog that will let you download and install the tools.
Following this, install the Homebrew package manager which will simplify the rest of the installation greatly. Install it by runing the following in a terminal window: Following this, install the Homebrew package manager which will simplify the rest of the installation greatly. Install it by runing the following in a terminal window:
``` ```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
``` ```
Be aware though that Homebrew can be really slow, especially when it compiles packages from source code. Be aware that Homebrew can be really slow, especially when it compiles packages from source code.
**Package installation with Homebrew:** **Package installation with Homebrew:**
@ -366,7 +364,7 @@ If required, define SDKROOT. This is only needed if during compilation you get e
export SDKROOT=$(xcrun --sdk macosx --show-sdk-path) export SDKROOT=$(xcrun --sdk macosx --show-sdk-path)
``` ```
I suppose you should add this to your .bash_profile or similar, but I didn't have to do this step so I'm not sure. I suppose you should add this to your shell profile file or similar, but I didn't have to do this step so I'm not sure.
**Cloning and compiling:** **Cloning and compiling:**
@ -393,11 +391,13 @@ Keep in mind though that a debug version will be much slower due to all compiler
Running `make -j6` (or whatever number of parallel jobs you prefer) speeds up the compilation time if you have cores to spare. Running `make -j6` (or whatever number of parallel jobs you prefer) speeds up the compilation time if you have cores to spare.
After building ES and trying to execute the application, there could be issues with finding the dynamic link libraries for VLC as these are not installed into a standard location but rather into the /Applications folder. As such, you may need to set the DYLD_LIBRARY_PATH environmental variable to find the VLC libraries. Note that this is not intended or required for the release build that will be shipped in a DMG installer or if you manually install ES using 'make install'. It's only needed to be able to run the ES binary from the build directory. The following will of course only be active during your session, and you need to set the variable for each terminal window that you want to start ES from, unless you add it to your shell profile file: After building ES-DE and trying to execute the application, there could be issues with finding the dynamic link libraries for VLC as these are not installed into a standard location but rather into the /Applications folder. As such, you may need to set the DYLD_LIBRARY_PATH environmental variable to find the VLC libraries. Note that this is not intended or required for the release build that will be shipped in a DMG installer or if you manually install ES-DE using 'make install'. It's only needed to be able to run the binary from the build directory. The following will of course only be active during your session, and you need to set the variable for each terminal window that you want to start ES-DE from, unless you add it to your shell profile file:
```export DYLD_LIBRARY_PATH=/Applications/VLC.app/Contents/MacOS/lib``` ```
export DYLD_LIBRARY_PATH=/Applications/VLC.app/Contents/MacOS/lib
```
**Note:** According to the SDL documentation, there could be issues with attempting to run ES from the build directory when using a High DPI display as the required NSHighResolutionCapable key is not set as there is no Info.plist file available. In this case, doing a 'make install' and running ES from the installation folder would solve the problem. I've been unable to verify if this is really required though as I don't have the necessary hardware to test it on. **Note:** According to the SDL documentation, there could be issues with attempting to run ES-DE from the build directory when using a High DPI display as the required NSHighResolutionCapable key is not set as there is no Info.plist file available. In this case, doing a 'make install' and running from the installation folder would solve the problem. I've been unable to verify if this is really required though.
**Installing:** **Installing:**
@ -436,7 +436,7 @@ libfreetype.6.dylib:
You of course only need to run this once, well at least until you replace the library in case of moving to a newer version or so. You of course only need to run this once, well at least until you replace the library in case of moving to a newer version or so.
In addition to these libraries, you need to create a `plugins` directory and copy over the following VLC libraries, which are normally located in `/Applications/VLC.app/Contents/MacOS/plugins/`: In addition to these libraries, you need to create a **plugins** directory and copy over the following VLC libraries, which are normally located in **/Applications/VLC.app/Contents/MacOS/plugins/**:
``` ```
libaudio_format_plugin.dylib libaudio_format_plugin.dylib
@ -453,15 +453,15 @@ libx264_plugin.dylib
libx265_plugin.dylib libx265_plugin.dylib
``` ```
If you only want to build EmulationStation to be used on your own computer, there's the option to skip the entire bundling of the libraries and use the ones already installed using Homebrew, meaning you can skip the previous .dylib copying. To do so, run CMake with the following option: If you only want to build ES-DE to be used on your own computer, there's the option to skip the entire bundling of the libraries and use the ones already installed using Homebrew, meaning you can skip the previous .dylib copying. To do so, run CMake with the following option:
``` ```
cmake -DAPPLE_SKIP_INSTALL_LIBS=ON . cmake -DAPPLE_SKIP_INSTALL_LIBS=ON .
``` ```
**Note:** This also affects the .dmg package generation using cpack, so if this option is enabled, the package will be unusable for anyone but yourself as the required libraries will not be bundled with the application. This also affects the .dmg package generation using cpack, so if this option is enabled, the package will be unusable for anyone but yourself as the required libraries will not be bundled with the application.
On macOS you can install the application as a normal user, i.e. no root privileges are required. Simply run the following to install ES-DE to `/Applications/EmulationStation Desktop Edition.app`: On macOS you can install the application as a normal user, i.e. no root privileges are required. Simply run the following:
``` ```
make install make install
@ -473,7 +473,6 @@ This will be the directory structure for the installation:
/Applications/EmulationStation Desktop Edition.app/Contents/Info.plist /Applications/EmulationStation Desktop Edition.app/Contents/Info.plist
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.0.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.0.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libcurl.4.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreeimage.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreeimage.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpng16.16.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpng16.16.dylib
@ -489,17 +488,17 @@ This will be the directory structure for the installation:
ES will look in the following locations for the resources, in the listed order: ES will look in the following locations for the resources, in the listed order:
* `[HOME]/.emulationstation/resources/` * \<home\>/.emulationstation/resources/
* `[ES EXECUTABLE DIRECTORY]/../Resources/resources/` * \<ES-DE executable directory\>/../Resources/resources/
* `[ES EXECUTABLE DIRECTORY]/resources/` * \<ES-DE executable directory\>/resources/
**Note:** The resources directory is critical, without it the application won't start. **Note:** The resources directory is critical, without it the application won't start.
And it will look in the following locations for the themes, also in the listed order: And it will look in the following locations for the themes, also in the listed order:
* `[HOME]/.emulationstation/themes/` * \<HOME\>/.emulationstation/themes/
* `[ES EXECUTABLE DIRECTORY]/../Resources/themes/` * \<ES-DE executable directory\>/../Resources/themes/
* `[ES EXECUTABLE DIRECTORY]/themes/` * \<ES-DE executable directory\>/themes/
A theme is not mandatory to start the application, but ES will be basically useless without it. A theme is not mandatory to start the application, but ES will be basically useless without it.
@ -507,7 +506,7 @@ The home directory will always take precedence, and any resources or themes loca
**Creating a .dmg installer:** **Creating a .dmg installer:**
Simply run `cpack` to build a .dmg disk image/installer: Simply run **cpack** to build a .dmg disk image/installer:
``` ```
myusername@computer:~/emulationstation-de$ cpack myusername@computer:~/emulationstation-de$ cpack
@ -519,7 +518,7 @@ CPack: Create package
CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.0.0.dmg generated. CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.0.0.dmg generated.
``` ```
Generating .dmg installers on older version of macOS seems to make them forward compatible to a pretty good extent, for instance building on El Capitan seems to generate an application that is usable on Catalina. The other way around does however not seem to be true, which is quite unsurprising. Generating .dmg installers on older version of macOS seems to make them forward compatible to a pretty good extent, for instance building on El Capitan seems to generate an application that is usable on Catalina and Big Sur. The other way around does however not seem to be true, which is quite unsurprising.
**Special considerations regarding run-paths:** **Special considerations regarding run-paths:**
@ -531,7 +530,7 @@ Simply run `otool -L EmulationStation` and verify that the result looks somethin
``` ```
EmulationStation: EmulationStation:
@rpath/libcurl.4.dylib (compatibility version 7.0.0, current version 8.0.0) /usr/lib/libcurl.4.dylib (compatibility version 7.0.0, current version 8.0.0)
@rpath/libfreeimage.dylib (compatibility version 3.0.0, current version 3.18.0) @rpath/libfreeimage.dylib (compatibility version 3.0.0, current version 3.18.0)
@rpath/libfreetype.6.dylib (compatibility version 24.0.0, current version 24.2.0) @rpath/libfreetype.6.dylib (compatibility version 24.0.0, current version 24.2.0)
@rpath/libSDL2-2.0.0.dylib (compatibility version 13.0.0, current version 13.0.0) @rpath/libSDL2-2.0.0.dylib (compatibility version 13.0.0, current version 13.0.0)
@ -542,17 +541,19 @@ EmulationStation:
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1226.10.1) /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1226.10.1)
``` ```
If any of the lines that should start with @rpath instead has an absolute path, then you have a problem and need to modify the install_name_tools parameters in es-app/CMakeLists.txt, for example: If any of the lines that should start with @rpath instead has an absolute path, then you have a problem and need to modify the install_name_tools parameters in es-app/CMakeLists.txt.
This is what an incorrect line would look like:
`/usr/local/opt/sdl2/lib/libSDL2-2.0.0.dylib (compatibility version 13.0.0, current version 13.0.0)` `/usr/local/opt/sdl2/lib/libSDL2-2.0.0.dylib (compatibility version 13.0.0, current version 13.0.0)`
This is the section that would need to be modified: This is the section in es-app/CMakeLists.txt that would need to be modified:
``` ```
add_custom_command(TARGET EmulationStation POST_BUILD COMMAND ${CMAKE_INSTALL_NAME_TOOL} add_custom_command(TARGET EmulationStation POST_BUILD COMMAND ${CMAKE_INSTALL_NAME_TOOL}
-change /usr/lib/libcurl.4.dylib @rpath/libcurl.4.dylib
-change /usr/local/opt/freeimage/lib/libfreeimage.dylib @rpath/libfreeimage.dylib -change /usr/local/opt/freeimage/lib/libfreeimage.dylib @rpath/libfreeimage.dylib
-change /usr/local/opt/freetype/lib/libfreetype.6.dylib @rpath/libfreetype.6.dylib -change /usr/local/opt/freetype/lib/libfreetype.6.dylib @rpath/libfreetype.6.dylib
-change /usr/local/opt/libpng/lib/libpng16.16.dylib @rpath/libpng16.16.dylib
-change /usr/local/opt/sdl2/lib/libSDL2-2.0.0.dylib @rpath/libSDL2-2.0.0.dylib -change /usr/local/opt/sdl2/lib/libSDL2-2.0.0.dylib @rpath/libSDL2-2.0.0.dylib
$<TARGET_FILE:EmulationStation>) $<TARGET_FILE:EmulationStation>)
``` ```
@ -560,7 +561,7 @@ add_custom_command(TARGET EmulationStation POST_BUILD COMMAND ${CMAKE_INSTALL_NA
## Building on Windows ## Building on Windows
At the moment I have only built the software using GCC on Windows, but I aim to get Clang/LLVM working at a later date. Up until now I have only built the software using GCC (MinGW) on Windows, but I may try to get Clang/LLVM working at a later date.
I did a brief evaluation of the Microsoft Visual C++ compiler (MSVC) but as far as I'm concerned it's an abomination so I won't cover it here and it won't be supported. I did a brief evaluation of the Microsoft Visual C++ compiler (MSVC) but as far as I'm concerned it's an abomination so I won't cover it here and it won't be supported.
@ -576,13 +577,13 @@ Anyway, here's a quite long summary of how to get a build environment up and run
[https://jmeubank.github.io/tdm-gcc](https://jmeubank.github.io/tdm-gcc) [https://jmeubank.github.io/tdm-gcc](https://jmeubank.github.io/tdm-gcc)
After installation, make a copy of `TDM-GCC-64/bin/mingw32-make` to `make` just for convenience. After installation, make a copy of **TDM-GCC-64/bin/mingw32-make** to **make** just for convenience.
I won't get into the details on how to configure Git, but there are many resources available online to support with this. The `Git Bash` shell is very useful though as it's somewhat reproducing a Unix environment using MinGW/MSYS. I won't get into the details on how to configure Git, but there are many resources available online to support with this. The **Git Bash** shell is very useful though as it's somewhat reproducing a Unix environment using MinGW/MSYS.
Install your editor of choice, I use [VSCode](https://code.visualstudio.com). Install your editor of choice, I use [VSCode](https://code.visualstudio.com).
It's strongly recommended to set line breaks to Unix-style (line feed only) directly in the editor, although it can also be configured in Git for conversion during commit. The source code for EmulationStation-DE only uses Unix-style line breaks. It's strongly recommended to set line breaks to Unix-style (line feed only) directly in the editor, although it can also be configured in Git for conversion during commits. The source code for ES-DE only uses Unix-style line breaks.
Note that most GDB builds for Windows have broken Python support so that pretty printing won't work. The MinGW installation recommended above should work fine though. Note that most GDB builds for Windows have broken Python support so that pretty printing won't work. The MinGW installation recommended above should work fine though.
@ -602,14 +603,14 @@ libVLC\
For VLC, download both the binary distribution for win64 as well as the source code package. For VLC, download both the binary distribution for win64 as well as the source code package.
Uncompress the files for the above packages to a suitable directory, for example C:\Programming\Dependencies\ Uncompress the files for the above packages to a suitable directory, for example **C:\Programming\Dependencies**
GLEW\ GLEW\
[http://glew.sourceforge.net](http://glew.sourceforge.net) [http://glew.sourceforge.net](http://glew.sourceforge.net)
This library needs to be compiled from source as the pre-built libraries don't seem to work with GCC. The GitHub repo seems to be somewhat broken as well, therefore the manual download is required. It's recommended to get the source in zip format and uncompress it to the same directory as the other libraries listed above. This library needs to be compiled from source as the pre-built libraries don't seem to work with GCC. The GitHub repo seems to be somewhat broken as well, therefore the manual download is required. It's recommended to get the source in zip format and uncompress it to the same directory as the other libraries listed above.
Now simply build the required glew32.dll library: Then simply build the required glew32.dll library:
``` ```
unzip glew-2.1.0.zip unzip glew-2.1.0.zip
@ -648,9 +649,9 @@ cd rapidjson
git checkout v1.1.0 git checkout v1.1.0
``` ```
**Clone the EmulationStation-DE repository:** **Clone the ES-DE repository:**
This works the same as in Unix or macOS, just run the following: This works the same as on Unix or macOS, just run the following:
``` ```
git clone https://gitlab.com/leonstyhre/emulationstation-de git clone https://gitlab.com/leonstyhre/emulationstation-de
@ -660,7 +661,7 @@ git clone https://gitlab.com/leonstyhre/emulationstation-de
As there is no standardized include directory structure in Windows, you need to provide the include files manually. As there is no standardized include directory structure in Windows, you need to provide the include files manually.
Make a directory in your build environment tree, for instance under C:\Programming\include\ Make a directory in your build environment tree, for instance under **C:\Programming\include**
Copy the include files from cURL, FreeImage, FreeType, GLEW, pugixml, RapidJSON, SDL2 and VLC to this directory. Copy the include files from cURL, FreeImage, FreeType, GLEW, pugixml, RapidJSON, SDL2 and VLC to this directory.
It should then look something like this: It should then look something like this:
@ -679,11 +680,11 @@ SDL2/
vlc/ vlc/
``` ```
**Copy the required DLL files to the EmulationStation build directory:** **Copy the required DLL files to the ES-DE build directory:**
As there's no package manager in Windows and no way to handle dependencies, we need to ship all the required shared libraries with the application. As there's no package manager in Windows and no way to handle dependencies, we need to ship all the required shared libraries with the application.
Copy the following files to the `emulationstation-de` build directory. Most of them will come from the packages that were provided in the previous steps of this guide: Copy the following files to the **emulationstation-de** build directory. Most of them will come from the packages that were provided in the previous steps of this guide:
``` ```
FreeImage.dll FreeImage.dll
@ -703,15 +704,13 @@ SDL2.dll
vcomp140.dll (From Visual C++ Redistributable for Visual Studio 2015, 32-bit version) vcomp140.dll (From Visual C++ Redistributable for Visual Studio 2015, 32-bit version)
``` ```
The files from the MinGW installation must correspond to the version used to compile the binary. The files from the MinGW installation must correspond to the version used to compile the binary. So if the MinGW installation is upgraded to a newer version, make sure to copy the .dll files again, overwriting the old ones.
*So if the MinGW installation is upgraded to a newer version or so, make sure to copy the .dll files again, overwriting the old ones.* In addition to these, you need to copy some libraries from the VLC **plugins** folder to be able to play video files. There is a subdirectory structure under the plugins folder but there is no requirement to retain this as libVLC apparently looks recursively for the required .dll files.
In addition to these, you need to copy some libraries from the VLC `plugins` folder to be able to play video files. There is a subdirectory structure under the plugins folder and although there is no requirement to retain these as libVLC apparently looks recursively for the required .dll files, it still makes it a bit more tidy to keep the folder names for each type of plugin. The CMake install script will however copy all the contents of this plugins folder regardless of whether subdirectories are in use or not.
It's a bit tricky to know which libraries are really needed. But as the plugins directory is around 120 MB (as of VLC version 3.0.11), we definitely only want to copy the files we need. It's a bit tricky to know which libraries are really needed. But as the plugins directory is around 120 MB (as of VLC version 3.0.11), we definitely only want to copy the files we need.
The following files seem to be required to play most video and audio formats (place them in `emulationstation-de\plugins\`): The following files seem to be required to play most video and audio formats (place them in **emulationstation-de\plugins**):
``` ```
access\libfilesystem_plugin.dll access\libfilesystem_plugin.dll
@ -742,7 +741,7 @@ Or for a debug build:
cmake -G "MinGW Makefiles" -DWIN32_INCLUDE_DIR=../include -DCMAKE_BUILD_TYPE=Debug . cmake -G "MinGW Makefiles" -DWIN32_INCLUDE_DIR=../include -DCMAKE_BUILD_TYPE=Debug .
``` ```
For some reason defining the '../include' path doesn't work when running CMake from PowerShell (and no, changing to backslash doesn't help). Instead use Bash, by running from a Git Bash shell. For some reason defining the **../include** path doesn't work when running CMake from PowerShell (and no, changing to backslash doesn't help). Instead use Bash, by running from a Git Bash shell.
The make command works fine directly in PowerShell though so it can be run from the VSCode terminal. The make command works fine directly in PowerShell though so it can be run from the VSCode terminal.
@ -762,7 +761,6 @@ Obviously this library is only intended for development and will not be shipped
To create an NSIS installer (Nullsoft Scriptable Install System) you need to first install the NSIS creation tool: To create an NSIS installer (Nullsoft Scriptable Install System) you need to first install the NSIS creation tool:
NSIS\
[https://nsis.sourceforge.io/Download](https://nsis.sourceforge.io/Download) [https://nsis.sourceforge.io/Download](https://nsis.sourceforge.io/Download)
Simply install the application using its installer. Simply install the application using its installer.
@ -776,48 +774,48 @@ CPack: Install projects
CPack: - Run preinstall target for: emulationstation-de CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPack: - package: C:/Programming/emulationstation-de/emulationstation-de-1.0.0-win64.exe generated. CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-1.0.0.exe generated.
``` ```
The default installation directory suggested by the installer is `C:\Program Files\EmulationStation`. However this can of course be changed by the user. The default installation directory suggested by the installer is **C:\Program Files\EmulationStation-DE** but this can of course be changed by the user.
ES will look in the following locations for the resources, in the listed order: ES will look in the following locations for the resources, in the listed order:
* `[HOME]\.emulationstation\resources\` * \<home\>\\.emulationstation\resources\
* `[ES EXECUTABLE DIRECTORY]\resources\` * \<ES-DE executable directory\>\resources\
**Note:** The resources directory is critical, without it the application won't start. The resources directory is critical, without it the application won't start.
And it will look in the following locations for the themes, also in the listed order: And it will look in the following locations for the themes, also in the listed order:
* `[HOME]\.emulationstation\themes\` * \<home\>\\.emulationstation\themes\
* `[ES EXECUTABLE DIRECTORY]\themes\` * \<ES-DE executable directory\>\themes\
The theme is not mandatory to start the application, but ES will be basically useless without it. The theme is not mandatory to start the application, but ES-DE will be basically useless without it.
So the home directory will always take precedence, and any resources or themes located there will override the ones in the path of the ES executable. So the home directory will always take precedence, and any resources or themes located there will override the ones in the path of the ES executable.
**Setting up a portable installation:** **Setting up a portable installation:**
It's possible to easily create a portable installation of ES for Windows, for example on a USB memory stick. It's possible to easily create a portable installation of ES-DE for Windows, for example on a USB memory stick.
For the sake of this example, let's assume that the removable media has the device name `f:\`. For the sake of this example, let's assume that the removable media has the device name `f:\`.
* Copy the EmulationStation installation directory to f:\ * Copy the EmulationStation-DE installation directory to f:\
* Create the directory `ES-Home` directly under f:\ * Create the directory **ES-Home** directly under f:\
* Copy your game ROMs into `f:\ES-Home\ROMs` * Copy your game ROMs into **f:\ES-Home\ROMs**
* Copy your emulators to f:\ (such as the RetroArch directory) * Copy your emulators to f:\ (such as the RetroArch directory)
* Create the file `start_es.bat` directly under f:\ * Create the file **start_es.bat** directly under f:\
Add the following lines to the start_es.bat file: Add the following lines to the start_es.bat file:
``` ```
@echo off @echo off
EmulationStation\emulationstation.exe --home %CD:~0,3%ES-Home EmulationStation-DE\EmulationStation.exe --home %CD:~0,3%ES-Home
``` ```
The contents of f:\ should now look something like this: The contents of f:\ should now look something like this:
``` ```
EmulationStation EmulationStation-DE
ES-Home ES-Home
RetroArch RetroArch
start_es.bat start_es.bat
@ -826,11 +824,11 @@ start_es.bat
Now run the batch script, ES should start and ask you to configure any attached controllers. Following this, check that everything works as expected, i.e. the gamelists are properly populated etc. Now run the batch script, ES should start and ask you to configure any attached controllers. Following this, check that everything works as expected, i.e. the gamelists are properly populated etc.
You can optionally skip the configuration of the controllers by copying any existing `es_input.cfg` file to `f:\ES-Home\.emulationstation\es_input.cfg`. You can optionally skip the configuration of the controllers by copying any existing es_input.cfg file to f:\ES-Home\\.emulationstation\\`
Exit ES and modify the file `f:\ES-Home\.emulationstation\es_systems.cfg` to point to the emulators on the portable media. Exit ES and modify the file **f:\ES-Home\.emulationstation\es_systems.cfg** to point to the emulators on the portable media.
Example change, from this: For example, change from this:
``` ```
<command>retroarch.exe -L "%EMUPATH%\cores\snes9x_libretro.dll" %ROM%</command> <command>retroarch.exe -L "%EMUPATH%\cores\snes9x_libretro.dll" %ROM%</command>
``` ```
@ -849,7 +847,7 @@ f:\ES-Home\.emulationstation\gamelists\
f:\ES-Home\.emulationstation\downloaded_media\ f:\ES-Home\.emulationstation\downloaded_media\
``` ```
You now have a fully functional portable emulator installation! You now have a fully functional portable retro gaming installation!
The portable installation works exactly as a normal installation, i.e. you can use the built-in scraper, edit metadata etc. The portable installation works exactly as a normal installation, i.e. you can use the built-in scraper, edit metadata etc.
@ -864,7 +862,7 @@ The CA certificates shipped with ES-DE come directly from the curl project but t
The latest version can be downloaded from [https://curl.se/docs/caextract.html](https://curl.se/docs/caextract.html) The latest version can be downloaded from [https://curl.se/docs/caextract.html](https://curl.se/docs/caextract.html)
After downloading the file, rename it from **cacert.pem** to **curl-ca-bundle.crt** and move it to the certificates directory so that it looks like this: After downloading the file, rename it from **cacert.pem** to **curl-ca-bundle.crt** and move it to the certificates directory i.e.:
``` ```
emulationstation-de/resources/certificates/curl-ca-bundle.crt emulationstation-de/resources/certificates/curl-ca-bundle.crt
@ -874,9 +872,9 @@ emulationstation-de/resources/certificates/curl-ca-bundle.crt
This is a bit tricky as the data needs to be converted to an internal format used by ES-DE. The original file is huge and most of the information is not required. This is a bit tricky as the data needs to be converted to an internal format used by ES-DE. The original file is huge and most of the information is not required.
Go to [https://www.mamedev.org/release.php](https://www.mamedev.org/release.php) and select the Windows version, but only download the driver information in XML format and not MAME itself. This file will be named someting like **mame0226lx.zip** and unzipping it will give you a file name such as **mame0226.xml**. Go to [https://www.mamedev.org/release.php](https://www.mamedev.org/release.php) and select the Windows version, but only download the driver information in XML format and not MAME itself. This file will be named something like **mame0226lx.zip** and unzipping it will give you a file name such as **mame0226.xml**.
Move the XML driver file to the resources/MAME directory and then convert it to the ES-DE internal format: Move the XML driver file to the resources/MAME directory and then convert it to the ES-DE internal files:
``` ```
cd emulationstation-de/resources/MAME cd emulationstation-de/resources/MAME
@ -894,7 +892,7 @@ rm *NEW *OLD mame0226.xml
You need **xmlstarlet** installed for these scripts to work. You need **xmlstarlet** installed for these scripts to work.
The diff command is of course used to do a sanity check that the changes look reasonable before deleting the old files. This is an example for the BIOS file when going from driver version 0221 to 0226: The diff command is used to do a sanity check that the changes look reasonable before deleting the old files. This is an example for the BIOS file when going from driver version 0.221 to 0.226:
``` ```
diff mamebioses.xml mamebioses.xml_OLD diff mamebioses.xml mamebioses.xml_OLD
1c1 1c1
@ -905,46 +903,39 @@ diff mamebioses.xml mamebioses.xml_OLD
< <bios>kpython</bios> < <bios>kpython</bios>
``` ```
The reason to not simply replace the BIOS and devices files with the new version is that we want to retain entries from all older MAME versions as otherwise older ROM sets used on older MAME versions will having missing information. This is so as the MAME project sometimes remove older entries when they're reorganizing the ROM sets. By merging the files we retain backwards compatibility but still support the latest MAME version. To clarify, this of course does not affect the emulation itself, but rather the filtering of BIOS and device files inside ES-DE. The mamenames.xml file containing the translation of MAME ROM names to the full game names does not suffer from this problem as it's cumulative, which is why it is simply overwritten. The reason to not simply replace the BIOS and devices files with the new version is that we want to retain entries from all older MAME versions as otherwise older ROM sets used on older MAME versions will have missing information. This is so as the MAME project sometimes remove older entries when they're reorganizing the ROM sets. By merging the files we retain backwards compatibility but still support the latest MAME version. To clarify, this of course does not affect the emulation itself, but rather the filtering of BIOS and device files inside ES-DE. The mamenames.xml file containing the translation of MAME ROM names to the full game names does not suffer from this problem as it's cumulative, which is why it is simply overwritten.
## Configuration ## Configuration
**~/.emulationstation/es_systems.cfg:** **~/.emulationstation/es_systems.cfg:**
EmulationStation Desktop Edition ships with a comprehensive `es_systems.cfg` configuration file, and as the logic is to use a `%ROMPATH%` variable to locate the ROM files (with a corresponding setting in `es_settings.cfg`), normally you shouldn't need to modify this file to the same extent as previous versions of EmulationStation. Still, see below in this document on how to adjust the es_systems.cfg file if required. ES-DE ships with a comprehensive **es_systems.cfg** configuration file, and as the logic is to use a `%ROMPATH%` variable to locate the ROM files (with a corresponding setting in **es_settings.cfg**), normally you shouldn't need to modify this file to the same extent as previous versions of EmulationStation. Still, see below in this document on how to adjust the es_systems.cfg file if required.
Upon first startup of the application, if there is no es_systems.cfg file present, it will be copied from the template subdirectory inside the resources directory. This directory is located in the installation path of the application, for instance `/usr/local/share/emulationstation/resources/templates` on Unix, `/Applications/EmulationStation.app/Contents/Resources/resources/templates` on macOS and `C:\Program Files\EmulationStation\resources\templates` on Windows. Upon first startup of the application, if there is no es_systems.cfg file present, it will be copied from the template subdirectory inside the resources directory. This directory is located in the installation path of the application, for instance **/usr/local/share/emulationstation/resources/templates** on Unix, **/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/templates** on macOS and **C:\Program Files\EmulationStation-DE\resources\templates** on Windows.
The template file will be copied to `~/.emulationstation/es_systems.cfg`. \ The template file will be copied to **~/.emulationstation/es_systems.cfg**.
`~` is `$HOME` on Unix and macOS, and `%HOMEPATH%` on Windows.
**Note:** Keep in mind that you have to set up your emulators separately from EmulationStation, the es_systems.cfg file assumes that your emulator environment is properly configured. The tilde symbol **~** translates to **$HOME** on Unix and macOS, and to **%HOMEPATH%** on Windows.
On Unix it's assumed that RetroArch is using the default configuration directory location, i.e. the cores should be located in ~/.config/retroarch/cores. If you've installed RetroArch via a Snap package, make a symlink from the Snap .config directory: Keep in mind that you have to set up your emulators separately from ES-DE as the es_systems.cfg file assumes that your emulator environment is properly configured.
```
ln -s ~/snap/retroarch/current/.config/retroarch ~/.config/
```
**~/.emulationstation/es_settings.cfg:** **~/.emulationstation/es_settings.cfg:**
When ES is first run, a configuration file will be created as `~/.emulationstation/es_settings.cfg`. When ES-DE is first run, a configuration file will be created as **~/.emulationstation/es_settings.cfg**.
This file contains all the settings supported by ES, at their default values. Normally you shouldn't need to modify this file manually, instead you should be able to use the menu inside ES to update all the necessary settings. This file will contain all supported settings at their default values. Normally you shouldn't need to modify this file manually, instead you should be able to use the menu inside ES-DE to update all the necessary settings.
For the ROM directory, you can either change it manually in es_settings.cfg, or use the dialog that is shown on application startup to change the path to your liking.
**Setting the ROM directory in es_settings.cfg:** **Setting the ROM directory in es_settings.cfg:**
**Note:** This complete configuration step can normally be skipped as you're presented with a dialog to change the ROM directory upon application startup if no game files are found. This complete configuration step can normally be skipped as you're presented with a dialog to change the ROM directory upon application startup if no game files are found.
By default, ES looks in `~/ROMs` for the ROM files, where they are expected to be grouped into directories corresponding to the game systems, for example: By default, ES-DE looks in **~/ROMs** for the ROM files, where they are expected to be grouped into directories corresponding to the game systems, for example:
``` ```
myusername@computer:~ROMs$ ls -1 myusername@computer:~ROMs$ ls -1
arcade c64
megadrive megadrive
pcengine pcengine
``` ```
@ -954,7 +945,7 @@ Here's an example:
`<string name="ROMDirectory" value="~/games/ROMs" />` `<string name="ROMDirectory" value="~/games/ROMs" />`
Keep in mind though that you still need to group the ROMs into directories corresponding to the \<path\> tags in es_systems.cfg. Keep in mind that you still need to group the ROMs into directories corresponding to the \<path\> tags in es_systems.cfg.
There is also support to add the variable %ESPATH% to the ROM directory setting, this will expand to the path where the ES executable is started from. You would normally not need this, but the option is there, should you require it for some reason. There is also support to add the variable %ESPATH% to the ROM directory setting, this will expand to the path where the ES executable is started from. You would normally not need this, but the option is there, should you require it for some reason.
@ -964,14 +955,14 @@ Here is such an example:
**~/.emulationstation/es_input.cfg:** **~/.emulationstation/es_input.cfg:**
You normally don't need to modify this file manually as it's created by the built-in input configuration step. This procedure is detailed in the [User Guide](USERGUIDE.md#input-device-configuration). You normally don't need to modify this file manually as it's created by the built-in input configuration step. This procedure is detailed in the [User guide](USERGUIDE.md#input-device-configuration).
If your controller and keyboard stop working, you can delete the `~/.emulationstation/es_input.cfg` file to make the input configuration screen re-appear on the next run. If your controller and keyboard stop working, you can delete the **~/.emulationstation/es_input.cfg** file to make the input configuration screen re-appear on the next startup, or you can start ES-DE with the **--force-input-config** command line argument.
## Command line arguments ## Command line arguments
You can use `--help` or `-h` to view a list of command line options, as shown here. You can use **--help** or **-h** to view the list of command line options, as shown here.
### Unix ### Unix
@ -1042,46 +1033,44 @@ You can use `--help` or `-h` to view a list of command line options, as shown he
--help, -h Summon a sentient, angry tuba --help, -h Summon a sentient, angry tuba
``` ```
As long as ES hasn't frozen, you can always press F4 to close the application. As long as ES-DE hasn't frozen, you can always press F4 to close the application.
As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `emulationstation --home ~/games/emulation`, ES will use `~/games/emulation/.emulationstation` as its base directory. As you can see above, you can override the home directory path using the **--home** flag. So by running for instance the command **emulationstation --home ~/games/emulation**, ES will use **~/games/emulation/.emulationstation** as its base directory.
## es_systems.cfg ## es_systems.cfg
The es_systems.cfg file contains the system configuration data for EmulationStation, written in XML format. \ The es_systems.cfg file contains the system configuration data for ES-DE, written in XML format. This defines the system name, the full system name, the ROM path, the allowed file extensions, the launch command, the platform (for scraping) and the theme to use.
This tells EmulationStation what systems you have, what platform they correspond to (for scraping), and where the games are located.
ES will only check in your home directory for an es_systems.cfg file, for example `~/.emulationstation/es_systems.cfg`. ES-DE will only check in your home directory for an es_systems.cfg file, for example **~/.emulationstation/es_systems.cfg**, but if this file is not present, it will attempt to install it from the systems template directory as explained earlier in this document.
The order EmulationStation displays systems reflects the order you define them in. In the case of the default es_systems.cfg file, the systems are listed in alphabetical order. It doesn't matter in which order you define the systems as they will be sorted by the full system name inside the application, but it's still probably a good idea to add them in alphabetical order to make the file easier to maintain.
**Note:** A system *must* have at least one game present in its `path` directory, or ES will ignore it! If no valid systems are found, ES will report an error and quit. Below is an overview of the file layout with various examples. For a real system entry there can of course not be multiple entries for the same tag such as the multiple \<command\> entries listed here.
Here's an overview of the file layout:
```xml ```xml
<?xml version="1.0"?> <?xml version="1.0"?>
<!-- This is the EmulationStation-DE game systems configuration file. --> <!-- This is the EmulationStation-DE game systems configuration file. -->
<systemList> <systemList>
<!-- Here's an example system to get you started. --> <!-- Any tag not explicitly described as optional in the description is mandatory.
If omitting a mandatory tag, ES-DE will skip the system entry during startup. -->
<system> <system>
<!-- A short name, used internally. --> <!-- A short name, used internally. -->
<name>snes</name> <name>snes</name>
<!-- A "pretty" name, displayed in the menus and such. This one is optional. --> <!-- The full system name, used for sorting the systems, for selecting the systems to multi-scrape etc. -->
<fullname>Super Nintendo Entertainment System</fullname> <fullname>Super Nintendo Entertainment System</fullname>
<!-- The path to start searching for ROMs in. '~' will be expanded to $HOME or %HOMEPATH%, depending on platform. <!-- The path to look for ROMs in. '~' will be expanded to $HOME or %HOMEPATH%, depending on the operating system.
The optional %ROMPATH% variable will expand to the path defined for the setting ROMDirectory in es_settings.cfg. The optional %ROMPATH% variable will expand to the path defined in the setting ROMDirectory in es_settings.cfg.
All subdirectories (and non-recursive links) will be included. --> All subdirectories (and non-recursive links) will be included. -->
<path>%ROMPATH%/snes</path> <path>%ROMPATH%/snes</path>
<!-- A list of extensions to search for, delimited by any of the whitespace characters (", \r\n\t"). <!-- A list of extensions to search for, delimited by any of the whitespace characters (", \r\n\t").
You MUST include the period at the start of the extension! It's also case sensitive. --> You must include the period at the start of the extension and it's case sensitive. -->
<extension>.smc .SMC .sfc .SFC .swc .SWC .fig .FIG .bs .BS .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP</extension> <extension>.smc .SMC .sfc .SFC .swc .SWC .fig .FIG .bs .BS .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP</extension>
<!-- The command executed when a game is launched. A few special variables are replaced if found in a command, like %ROM% (see below). <!-- The command executed when a game is launched. A few special variables are replaced if found for a command tag (see below).
This example for Unix would run RetroArch with the the snes9x_libretro core, using an absolute path to the core. This example for Unix would run RetroArch with the the snes9x_libretro core, using an absolute path to the core.
If there are spaces in the path or file name, you must enclose them in quotation marks, for example: If there are spaces in the path or file name, you must enclose them in quotation marks, for example:
retroarch -L "~/my configs/retroarch/cores/snes9x_libretro.so" %ROM% --> retroarch -L "~/my configs/retroarch/cores/snes9x_libretro.so" %ROM% -->
@ -1106,150 +1095,222 @@ Here's an overview of the file layout:
configuration as the %EMUPATH% will expand to the path of the emulator binary, which will of course also include the spaces. --> configuration as the %EMUPATH% will expand to the path of the emulator binary, which will of course also include the spaces. -->
<command>"C:\My Games\RetroArch\retroarch.exe" -L "%EMUPATH%\cores\snes9x_libretro.dll" %ROM%</command> <command>"C:\My Games\RetroArch\retroarch.exe" -L "%EMUPATH%\cores\snes9x_libretro.dll" %ROM%</command>
<!-- An example for use in a portable emulator installation, for instance on a USB memory stick. The %ESPATH% variable is <!-- An example for use in a portable Windows emulator installation, for instance on a USB memory stick. The %ESPATH% variable is
expanded to the directory of the ES executable. --> expanded to the directory of the ES executable. -->
<command>"%ESPATH%\..\RetroArch\retroarch.exe" -L "%ESPATH%\..\RetroArch\cores\snes9x_libretro.dll" %ROM%</command> <command>"%ESPATH%\..\RetroArch\retroarch.exe" -L "%ESPATH%\..\RetroArch\cores\snes9x_libretro.dll" %ROM%</command>
<!-- The platform(s) to use when scraping. You can see the full list of supported platforms in src/PlatformIds.cpp. <!-- The platform(s) to use when scraping. You can see the full list of supported platforms in es-app/src/PlatformId.cpp.
It's case sensitive, but everything is lowercase. This tag is optional. The entry is case insensitive as it will be converted to lower case during startup.
You can use multiple platforms too, delimited with any of the whitespace characters (", \r\n\t"), e.g.: "megadrive, genesis" --> This tag is optional but the system can't be scraped if it's left out.
You can use multiple platforms too, delimited with any of the whitespace characters (", \r\n\t"), e.g. "megadrive, genesis". -->
<platform>snes</platform> <platform>snes</platform>
<!-- The theme to load from the current theme set. See THEMES.md for more information. --> <!-- The theme to load from the current theme set. See THEMES.md for more information.
This tag is optional and if it doesn't exist, ES-DE will attempt to find a theme with the same name as the system name.
If no such match is made, the system will be unthemed.
It's strongly recommended to include this tag even if it's just to clarify that the theme should correspond to the system name. -->
<theme>snes</theme> <theme>snes</theme>
</system> </system>
</systemList> </systemList>
``` ```
The following variables are expanded by ES for the `command` tag: The following variable is expanded for the `path` tag:
`%ROM%` - Replaced with absolute path to the selected ROM, with most Bash special characters escaped with a backslash. `%ROMPATH%` - Replaced with the path defined in the setting ROMDirectory in es_settings.cfg.
The following variables are expanded for the `command` tag:
`%ROM%` - Replaced with the absolute path to the selected ROM, with most Bash special characters escaped with a backslash.
`%BASENAME%` - Replaced with the "base" name of the path to the selected ROM. For example, a path of `/foo/bar.rom`, this tag would be `bar`. This tag is useful for setting up AdvanceMAME. `%BASENAME%` - Replaced with the "base" name of the path to the selected ROM. For example, a path of `/foo/bar.rom`, this tag would be `bar`. This tag is useful for setting up AdvanceMAME.
`%COREPATH%` - The core file defined after this variable will be searched in each of the directories listed in the setting EmulatorCorePath (in es_settings.cfg). This is done until the first match occurs, or until the last directory is exhausted and no core file was found. This makes it possible to create a more general es_systems.cfg file but still support the variation between different operating systems and different types of emulator installations (e.g. installed via the OS repository, via Snap, compiled from source etc.). This is primarily intended for Unix as well as for RetroArch but it can also be used on macOS and Windows and for other emulators that utilizes discrete emulator cores. For macOS and Windows the EmulatorCorePath setting is blank by default, and for Unix it's set to the following value: `~/.config/retroarch/cores:~/snap/retroarch/current/.config/retroarch/cores:/usr/lib/x86_64-linux-gnu/libretro:/usr/lib64/libretro:/usr/lib/libretro:/usr/local/lib/libretro:/usr/pkg/lib/libretro`. Note that colons are used to separate the directories on Unix and macOS and semicolons are used on Windows. This path setting can be changed from within the GUI, as described in the [User Guide](USERGUIDE.md#other-settings-1). Never use quotation marks around the directories for this setting. It's strongly adviced to not add spaces to directory names, but if still done, ES-DE will handle this automatically by adding the appropriate quotation marks to the launch command. `%ROMRAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes.
`%ROM_RAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes.
`%EMUPATH%` - Replaced with the path to the emulator binary. This is expanded either using the PATH environmental variable of the operating system, or if an absolute emulator path is defined, this will be used instead. This variable is mostly useful to define the emulator core path for Windows, as this operating system does not have a standardized program installation directory structure. `%EMUPATH%` - Replaced with the path to the emulator binary. This is expanded either using the PATH environmental variable of the operating system, or if an absolute emulator path is defined, this will be used instead. This variable is mostly useful to define the emulator core path for Windows, as this operating system does not have a standardized program installation directory structure.
`%ESPATH%` - Replaced with the path to the EmulationStation binary. Mostly useful for portable emulator installations, for example on a USB memory stick. `%ESPATH%` - Replaced with the path to the EmulationStation binary. Mostly useful for portable emulator installations, for example on a USB memory stick.
For the `path` tag, the following variable is expanded by ES: `%COREPATH%` - The core file defined after this variable will be searched in each of the directories listed in the setting EmulatorCorePath in es_settings.cfg. This is done until the first match occurs, or until the directories are exhausted and no core file was found. This makes it possible to create a more general es_systems.cfg file but still support the variation between different operating systems and different types of emulator installations (e.g. installed via the OS repository, via Snap, compiled from source etc.). This is primarily intended for Unix as well as for RetroArch but it can also be used on macOS and Windows and for other emulators that utilizes discrete emulator cores. For macOS and Windows the EmulatorCorePath setting is blank by default, and for Unix it's set to the following value: `~/.config/retroarch/cores:~/snap/retroarch/current/.config/retroarch/cores:/usr/lib/x86_64-linux-gnu/libretro:/usr/lib64/libretro:/usr/lib/libretro:/usr/local/lib/libretro:/usr/pkg/lib/libretro`. Note that colons are used to separate the directories on Unix and macOS and that semicolons are used on Windows. This path setting can be changed from within the GUI, as described in the [User guide](USERGUIDE.md#other-settings-1). Never use quotation marks around the directories for this setting. It's strongly adviced to not add spaces to directory names, but if still done, ES-DE will handle this automatically by adding the appropriate quotation marks to the launch command.
`%ROMPATH%` - Replaced with the path defined for the setting ROMDirectory in es_settings.cfg. Here are some additional real world examples of system entries, the first one for Unix:
```xml
<system>
<name>dos</name>
<fullname>DOS (PC)</fullname>
<path>%ROMPATH%/dos</path>
<extension>.bat .BAT .com .COM .exe .EXE .7z .7Z .zip .ZIP</extension>
<command>retroarch -L %COREPATH%/dosbox_core_libretro.so %ROM%</command>
<platform>dos</platform>
<theme>dos</theme>
</system>
```
Then one for macOS:
```xml
<system>
<name>nes</name>
<fullname>Nintendo Entertainment System</fullname>
<path>%ROMPATH%/nes</path>
<extension>.nes .NES .unf .UNF .unif .UNIF .7z .7Z .zip .ZIP</extension>
<command>/Applications/RetroArch.app/Contents/MacOS/RetroArch -L %EMUPATH%/../Resources/cores/nestopia_libretro.dylib %ROM%</command>
<platform>nes</platform>
<theme>nes</theme>
</system>
```
And one for Windows:
```xml
<system>
<name>sega32x</name>
<fullname>Sega Mega Drive 32X</fullname>
<path>%ROMPATH%\sega32x</path>
<extension>.bin .BIN .gen .GEN .smd .SMD .md .MD .32x .32X .cue .CUE .iso .ISO .sms .SMS .68k .68K .7z .7Z .zip .ZIP</extension>
<command>retroarch.exe -L "%EMUPATH%\cores\picodrive_libretro.dll" %ROM%</command>
<platform>sega32x</platform>
<theme>sega32x</theme>
</system>
```
## gamelist.xml ## gamelist.xml
The gamelist.xml file for a system defines metadata for games, such as a name, description, release date, and rating. The gamelist.xml file for a system defines the metadata for its entries, such as the game names, descriptions, release dates and ratings.
As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game art is configurable either manually in `es_settings.cfg` or via the GUI. If configured manually in es_settings.cfg, it looks something like this: As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game media is configurable either manually in **es_settings.cfg** or via the GUI. If configured manually in es_settings.cfg, it looks something like this:
`<string name="MediaDirectory" value="~/games/images/emulationstation" />` ```
<string name="MediaDirectory" value="~/games/images/emulationstation" />
```
The default game media directory is `~/.emulationstation/downloaded_media`. The default directory is **~/.emulationstation/downloaded_media**
You can use ES's [scraping](http://en.wikipedia.org/wiki/Web_scraping) tools to populate the gamelist.xml files. There are two ways to run the scraper: You can use ES-DE's scraping tools to populate the gamelist.xml files, or manually update individual entries using the metadata editor. All of this is explained in the [User guide](USERGUIDE.md).
* **If you want to scrape multiple games:** press the Start button to open the menu and choose the "SCRAPER" option. Adjust your settings and press "START". The gamelist.xml files are searched for in the ES-DE home directory, i.e. **~/.emulationstation/gamelists/\<system name\>/gamelist.xml**
* **If you just want to scrape one game:** find the game on the game list in ES and press the Select button. Choose "EDIT THIS GAME'S METADATA" and then press the "SCRAPE" button at the bottom of the metadata editor.
You can also edit metadata within ES by using the metadata editor - just find the game you wish to edit on the gamelist, press Select, and choose "EDIT THIS GAME'S METADATA." For example:
The switch `--ignore-gamelist` can be used to ignore the gamelists upon start of the application. ```
~/.emulationstation/gamelists/c64/gamelist.xml
~/.emulationstation/gamelists/megadrive/gamelist.xml
```
**File location and structure:** **gamelist.xml file structure:**
ES checks for the `gamelist.xml` files in the user's home directory: An example gamelist.xml entry for the Commodore 64 game Popeye:
`~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
The home directory can be overridden using the `--home` option from the command line, see above in this document for details regarding that.
An example gamelist.xml:
```xml ```xml
<?xml version="1.0"?>
<gameList> <gameList>
<game> <game>
<path>./mm2.nes</path> <path>./cartridge/Popeye/Popeye.crt</path>
<name>Mega Man 2</name> <name>Popeye</name>
<desc>Mega Man 2 is a classic NES game which follows Mega Man as he murders eight robot masters in cold blood.</desc> <desc>Popeye is a conversion of the arcade action/platform game.</desc>
</game> <rating>0.7</rating>
<releasedate>19860101T000000</releasedate>
<developer>Parker Brothers</developer>
<publisher>Nintendo</publisher>
<genre>Action</genre>
<players>1-2</players>
<favorite>true</favorite>
</game>
</gameList> </gameList>
``` ```
Everything is enclosed in a `<gameList>` tag. The information for each game or folder is enclosed in a corresponding tag (`<game>` or `<folder>`). Each piece of metadata is encoded as a string. Everything is enclosed in a `<gameList>` tag, and the information for each game or folder is enclosed in a corresponding `<game>` or `<folder>` tag. Each piece of metadata is encoded as a string.
**gamelist.xml reference:** **gamelist.xml reference:**
There are a few types of metadata: There are a few different data types for the metadata which the string values in the gamelist.xml files are converted to during file loading:
* `string` - just text. * `string` - just text
* `float` - a floating-point decimal value (written as a string). * `float` - a floating-point decimal value (written as a string)
* `integer` - an integer value (written as a string). * `integer` - an integer value (written as a string)
* `datetime` - a date and, potentially, a time. These are encoded as an ISO string, in the following format: "%Y%m%dT%H%M%S%F%q". For example, the release date for Chrono Trigger is encoded as "19950311T000000" (no time specified). * `datetime` - a date and, potentially, a time. These are encoded as an ISO string, in the following format: "%Y%m%dT%H%M%S%F%q". For example, the release date for Chrono Trigger is encoded as "19950311T000000" (no time specified)
* `bool` - a true or false value
Some metadata is also marked as "statistic" - these are kept track of by ES and do not show up in the metadata editor. They are shown in certain views (for example, the detailed view and the video view both show `lastplayed`, although the label can be disabled by the theme). Some metadata is also marked as "statistic" - these are kept track of by ES-DE and do not show up in the metadata editor. They are shown in certain views (for example, the detailed view and the video view both show `lastplayed`, although the label can be disabled by the theme).
There are two basic categories of metadata, `game` and `folders` and the metdata tags for these are described in detail below.
**\<game\>** **\<game\>**
* `path` - string, the path to the game file, either relative to the %ROMPATH% variable or as an absolute path on the filesystem
* `name` - string, the displayed name for the game
* `sortname` - string, used in sorting the gamelist in a system, instead of `name`
* `desc` - string, a description of the game, longer descriptions will automatically scroll, so don't worry about the size
* `rating` - float, the rating for the game, expressed as a floating point number between 0 and 1. Fractional values will be rounded to 0.1 increments (half-stars) during processing
* `releasedate` - datetime, the date the game was released, displayed as date only, time is ignored
* `developer` - string, the developer for the game
* `publisher` - string, the publisher for the game
* `genre` - string, the genre(s) for the game
* `players` - integer, the number of players the game supports
* `favorite` - bool, indicates whether the game is a favorite
* `completed` - bool, indicates whether the game has been completed
* `kidgame` - bool, indicates whether the game is suitable for children, as used by the `Kid' UI mode
* `hidden` - bool, indicates whether the game is hidden
* `broken` - bool, indicates a game that doesn't work (useful for MAME)
* `nogamecount` - bool, indicates whether the game should be excluded from the game counter and the automatic and custom collections
* `nomultiscrape` - bool, indicates whether the game should be excluded from the multi-scraper
* `hidemetadata` - bool, indicates whether to hide most of the metadata fields when displaying the game in the gamelist view
* `launchcommand` - string, overrides the emulator and core settings on a per-game basis
* `playcount` - integer, the number of times this game has been played
* `lastplayed` - statistic, datetime, the last date and time this game was played
* `name` - string, the displayed name for the game. For folders, most of the fields are identical although some are removed. In the list below, the fields with identical function compared to the game files described above have been left without a description.
* `desc` - string, a description of the game. Longer descriptions will automatically scroll, so don't worry about size.
* `rating` - float, the rating for the game, expressed as a floating point number between 0 and 1. ES will round fractional values to half-stars.
* `releasedate` - datetime, the date the game was released. Displayed as date only, time is ignored.
* `developer` - string, the developer for the game.
* `publisher` - string, the publisher for the game.
* `genre` - string, the (primary) genre for the game.
* `players` - integer, the number of players the game supports.
* `favorite` - bool, indicates whether the game is a favorite.
* `completed`- bool, indicates whether the game has been completed.
* `broken` - bool, indicates a game that doesn't work (useful for MAME).
* `kidgame` - bool, indicates whether the game is suitable for children, used by the `kid' UI mode.
* `playcount` - integer, the number of times this game has been played.
* `lastplayed` - statistic, datetime, the last date and time this game was played.
* `sortname` - string, used in sorting the gamelist in a system, instead of `name`.
* `launchcommand` - optional tag that is used to override the emulator and core settings on a per-game basis.
**\<folder\>** **\<folder\>**
* `name` - string, the displayed name for the folder. * `path`
* `desc` - string, the description for the folder. * `name`
* `developer` - string, developer(s). * `desc`
* `publisher` - string, publisher(s). * `rating`
* `genre` - string, genre(s). * `releasedate`
* `players` - integer, the number of players the game supports. * `developer`
* `publisher`
* `genre`
* `players`
* `favorite`
* `completed`
* `hidden`
* `broken`
* `nomultiscrape`
* `hidemetadata`
* `lastplayed` - statistic, for folders this is inherited by the latest game file launched inside the folder.
**Additional gamelist.xml information:** **Additional gamelist.xml information:**
* If a value matches the default for a particular piece of metadata, ES will not write it to the gamelist.xml (for example, if `genre` isn't specified, ES won't write an empty genre tag) * If a value matches the default for a particular piece of metadata, ES-DE will not write it to the gamelist.xml file (for example, if `genre` isn't specified, an empty genre tag will not be written)
* A `game` can actually point to a folder/directory if the folder has a matching extension * A `game` can actually point to a folder/directory if the folder has a matching extension, although this is exceedingly rare
* `folder` metadata will only be used if a game is found inside of that folder * The `folder` metadata will only be used if a game file is found inside that folder, as empty folders will be skipped during startup even if they have metadata values defined for themselves
* ES will keep entries for games and folders that it can't find the game/ROM files for * ES-DE will keep entries for games and folders that it can't find the game/ROM files for, i.e. it will not clean up the gamelist.xml files automatically when game files are missing
* The switch `--gamelist-only` can be used to skip automatic searching, and only display games defined in the system's gamelist.xml * The switch `--gamelist-only` can be used to skip automatic searching, and only display games defined in the gamelist.xml files
* The switch `--ignore-gamelist` can be used to ignore the gamelist upon start of the application * The switch `--ignore-gamelist` can be used to ignore the gamelist upon start of the application (mostly useful for debugging purposes)
## Custom event scripts ## Custom event scripts
There are numerous locations throughout ES where custom scripts will be executed if the option to do so has been enabled in the settings. You'll find the option on the Main menu under **Other settings**. By default it's deactivated so be sure to enable it to use this feature. 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. You'll find the option on the Main menu under **Other settings**. By default it's deactivated so be sure to enable it to use this feature.
The approach is quite straightforward, ES will look for any files inside a script directory that correspond to the event that is triggered and execute all files located there. The approach is quite straightforward, ES-DE will look for any files inside a script directory that correspond to the event that is triggered and execute all files located there.
As an example, let's create a log that will record the start and end time for each game we play, letting us see how much time we spend on retro-gaming. As an example, let's create a log that will record the start and end time for each game we play, letting us see how much time we spend on retro-gaming.
**Note: The following example is for Unix systems, but it works the same in Windows (though .bat batch files are then used instead of shell scripts).** **Note:** The following example is for Unix systems, but it works the same way in macOS, and on Windows (although .bat batch files are then used instead of shell scripts).
The events when the game starts and ends are called **game-start** and **game-end** respectively. Finding these event names is easily achieved by starting ES with the **--debug** flag. If this is done, all attempts to execute custom event scripts will be logged to es_log.txt, including the event names. The events when the game starts and ends are called **game-start** and **game-end** respectively. Finding these event names is easily achieved by starting ES-DE with the **--debug** flag. If this is done, all attempts to execute custom event scripts will be logged to es_log.txt, including the event names.
So let's create the folders for these events in the scripts directory. The location of this directory is **~/.emulationstation/scripts/**. So let's create the folders for these events in the scripts directory. The location of this directory is **~/.emulationstation/scripts**.
After creating the directories, we need to create the scripts to log the actual game launch and game ending. The parameters that are passed to the scripts varies depending on the type of event, but for these events the two parameters are the absolute path to the game file, and the game name as shown in the gamelist. After creating the directories, we need to create the scripts to log the actual game launch and game ending. The parameters that are passed to the scripts varies depending on the type of event, but for these events the two parameters are the absolute path to the game file, and the game name as shown in the gamelist view.
Let's name the start script **game_start_logging.sh** with the following contents: Let's name the start script **game_start_logging.sh** with the following contents:
@ -1276,7 +1337,7 @@ After creating the two scripts, you should have something like this on the files
Don't forget to make the scripts executable (e.g. 'chmod 755 ./game_start_logging.sh'). Don't forget to make the scripts executable (e.g. 'chmod 755 ./game_start_logging.sh').
If we now start ES with the debug flag and launch a game, something like the following should show up in es_log.txt: If we now start ES-DE with the debug flag and launch a game, something like the following should show up in es_log.txt:
``` ```
Aug 05 14:19:24 Debug: Scripting::fireEvent(): game-start "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda" Aug 05 14:19:24 Debug: Scripting::fireEvent(): game-start "/home/myusername/ROMs/nes/Legend\ of\ Zelda,\ The.zip" "The Legend Of Zelda"

6
README.md
View file

@ -35,7 +35,7 @@ If you would like to contribute to the development of ES-DE, then that's great!
# Additional information # Additional information
[USERGUIDE.md](USERGUIDE.md) is a comprehensive guide on how to use ES-DE and it also contains a complete reference of all application settings [USERGUIDE.md](USERGUIDE.md) is a comprehensive guide on how to use ES-DE and it also contains a complete reference to all application settings.
[RELEASES.md](RELEASES.md) contains information about the current release as well as previous releases. This covers the features, improvements and bug fixes. [RELEASES.md](RELEASES.md) contains information about the current release as well as previous releases. This covers the features, improvements and bug fixes.
@ -47,7 +47,7 @@ If you would like to contribute to the development of ES-DE, then that's great!
# Some feature highlights # Some feature highlights
Here are some highlights of what EmulationStation Desktop Edition provides, displayed using the default theme set rbsimple-DE. There are of course many more features available, as covered in the [User Guide](USERGUIDE.md). Here are some highlights of what EmulationStation Desktop Edition provides, displayed using the default theme set rbsimple-DE. There are of course many more features available, as covered in the [User guide](USERGUIDE.md).
![alt text](images/current/es-de_system_view.png "ES-DE System View") ![alt text](images/current/es-de_system_view.png "ES-DE System View")
_The **System view**, which is the default starting point for the application, it's here that you browse through your game systems._ _The **System view**, which is the default starting point for the application, it's here that you browse through your game systems._
@ -71,7 +71,7 @@ _There are many settings for the scraper including options to define which type
_In addition to the scraper there is a fully-featured metadata editor that can be used to modify information on a per-game basis. Here you can also toggle some additional flags which the scraper does not set, such as if the game is a favorite or if you have completed it. Some of these flags can then be filtered in the gamelist view, letting you for instance only display games that you have not played through._ _In addition to the scraper there is a fully-featured metadata editor that can be used to modify information on a per-game basis. Here you can also toggle some additional flags which the scraper does not set, such as if the game is a favorite or if you have completed it. Some of these flags can then be filtered in the gamelist view, letting you for instance only display games that you have not played through._
![alt text](images/current/es-de_screensaver.png "ES-DE Screensaver") ![alt text](images/current/es-de_screensaver.png "ES-DE Screensaver")
_There are four types of built-in screensavers available, including a slideshow and the video screensaver showed in action above. These screensavers start after a configurable number of minutes of inactivity, and randomly display game media that you have previously scraped. If the corresponding option has been enabled, you can jump to the game from the screensaver, or even start it directly. There is shader support in ES-DE to render scanlines and screen blur on top of the videos (for the Slideshow screensaver, scanline rendering is provided)._ _There are four types of built-in screensavers available, including a slideshow and the video screensaver showed in action above. These screensavers start after a configurable number of minutes of inactivity, and randomly display game media that you have previously scraped. If the corresponding option has been enabled, you can jump to the game from the screensaver, or even start it directly. There is shader support in ES-DE to render scanlines and screen blur on top of the videos (for the slideshow screensaver, scanline rendering is provided)._
![alt text](images/current/es-de_ui_theme_support.png "ES-DE Theme Support") ![alt text](images/current/es-de_ui_theme_support.png "ES-DE Theme Support")
_ES-DE is fully themeable, so if you prefer another look than what the default theme rbsimple-DE gives you, it's possible to apply another theme set. In the example above a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme is used. Be aware though that although ES-DE is backwards compatible with older EmulationStation themes, some newer features which are specific to ES-DE will not work, at least not until the theme authors update their themes._ _ES-DE is fully themeable, so if you prefer another look than what the default theme rbsimple-DE gives you, it's possible to apply another theme set. In the example above a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme is used. Be aware though that although ES-DE is backwards compatible with older EmulationStation themes, some newer features which are specific to ES-DE will not work, at least not until the theme authors update their themes._

32
USERGUIDE.md
View file

@ -1,6 +1,6 @@
# EmulationStation Desktop Edition (ES-DE) v1.0 - User Guide # EmulationStation Desktop Edition (ES-DE) - User guide
**Note:** This document is intended as a quick start guide as well as a reference for the user interface settings and functionality. For more in-depth information and details on how to compile EmulationStation and perform more advanced configuration, please refer to [INSTALL.md](INSTALL.md). **Note:** This document is intended as a quick start guide as well as a reference for the user interface settings and functionality. For more in-depth information and details on how to compile ES-DE and perform more advanced configuration, please refer to [INSTALL.md](INSTALL.md).
Table of contents: Table of contents:
@ -8,7 +8,7 @@ Table of contents:
## Basic steps to get ES-DE up and running ## Basic steps to get ES-DE up and running
If you just want to get started as quickly as possible, just follow these steps: If you just want to get started as quickly as possible, simply follow these steps:
1) Install ES-DE 1) Install ES-DE
2) Install and configure [RetroArch](https://www.retroarch.com) 2) Install and configure [RetroArch](https://www.retroarch.com)
@ -22,7 +22,7 @@ For additional details, read on below.
## Getting started ## Getting started
Getting started with EmulationStation is easy, just make sure to install the software properly, either manually as built from source code or using one of the supplied packages. On Windows and macOS you'll use the installer instead of a package. Getting started with ES-DE is easy, just make sure to install the software properly, either manually as built from source code or using one of the supplied packages. On Windows and macOS you'll use the installer instead of a package.
The following operating systems have been tested (all for the x86 architecture): The following operating systems have been tested (all for the x86 architecture):
@ -123,7 +123,7 @@ Depending on the theme, the system navigation carousel can be either horizontal
The game systems are sorted by their full names, as defined in es_systems.cfg. The game systems are sorted by their full names, as defined in es_systems.cfg.
![alt text](images/current/es-de_system_view.png "ES-DE System View") ![alt text](images/current/es-de_system_view.png "ES-DE System View")
_The System view is the default starting point for the application, it's here that you browse through your game systems._ _The **System view** is the default starting point for the application, it's here that you browse through your game systems._
## Gamelist view ## Gamelist view
@ -140,7 +140,7 @@ In addition to the styles just described, there is a **Grid** view style as well
If the theme supports it, there's a gamelist information field displayed in the gamelist view, showing the number of games for the system (total and favorites) as well as a folder icon if a folder has been entered. When applying any filters to the gamelist, the game counter is replaced with the amount of games filtered, as in 'filtered / total games', e.g. '19 / 77'. If there are game entries in the filter result that are marked not to be counted as games, the number of such files will be indicated as 'filtered + filtered non-games / total games', for example '23 + 4 / 77' indicating 23 normal games, 4 non-games out of a total of 77. Due to this approach it's theoretically possible that the combined filtered game amount exceeds the number of counted games in the collection, for instance '69 + 11 / 77'. This is not considered a bug and is so by design. This gamelist information field functionality is specific to EmulationStation Desktop Edition so older themes will not support this. If the theme supports it, there's a gamelist information field displayed in the gamelist view, showing the number of games for the system (total and favorites) as well as a folder icon if a folder has been entered. When applying any filters to the gamelist, the game counter is replaced with the amount of games filtered, as in 'filtered / total games', e.g. '19 / 77'. If there are game entries in the filter result that are marked not to be counted as games, the number of such files will be indicated as 'filtered + filtered non-games / total games', for example '23 + 4 / 77' indicating 23 normal games, 4 non-games out of a total of 77. Due to this approach it's theoretically possible that the combined filtered game amount exceeds the number of counted games in the collection, for instance '69 + 11 / 77'. This is not considered a bug and is so by design. This gamelist information field functionality is specific to EmulationStation Desktop Edition so older themes will not support this.
![alt text](images/current/es-de_gamelist_view.png "ES-DE Gamelist View") ![alt text](images/current/es-de_gamelist_view.png "ES-DE Gamelist View")
_The Gamelist view is where you browse the games for a specific system._ _The **Gamelist view** is where you browse the games for a specific system._
## UI modes ## UI modes
@ -151,7 +151,7 @@ These modes mandate the functionalty provided by the application in the followin
* Full - This is the default mode which enables all functionality. * Full - This is the default mode which enables all functionality.
* Kiosk - The main menu will be severely restricted, only displaying the entry to change the audio volume. The game options menu will be restricted as well, removing the metadata editor and the ability to modify custom game collections. And finally the ability to flag or unflag games as favorites will be removed. Apart from this all games will be playable. * Kiosk - The main menu will be severely restricted, only displaying the entry to change the audio volume. The game options menu will be restricted as well, removing the metadata editor and the ability to modify custom game collections. And finally the ability to flag or unflag games as favorites will be removed. Apart from this all games will be playable.
* Kid - Only games marked as being suitable for children will be displayed (this flag is set manually per game using the metadata editor). Additionally, the game options menu is disabled, as well as the screensaver controls and the ability to flag and unflag games as favorites. There is also a separate option available to enable or disable the main menu when in Kid mode, see **Enable menu in kid mode** further [below](USERGUIDE.md#other-settings-1) * Kid - Only games marked as being suitable for children will be displayed (this flag is set manually per game using the metadata editor). Additionally, the game options menu is disabled, as well as the screensaver controls and the ability to flag and unflag games as favorites. There is also a separate option available to enable or disable the main menu when in Kid mode, see **Enable menu in kid mode** further [below](USERGUIDE.md#other-settings-1).
There is an unlock code available to revert to the Full mode from the Kiosk or Kid mode, as is described when changing this setting from the main menu. By default the button sequence is **Up, Up, Down, Down, Left, Right, Left, Right, B, A**. It works to use either a keyboard or a configured controller to input the passkey sequence, but it can't be entered when a menu is open. There is an unlock code available to revert to the Full mode from the Kiosk or Kid mode, as is described when changing this setting from the main menu. By default the button sequence is **Up, Up, Down, Down, Left, Right, Left, Right, B, A**. It works to use either a keyboard or a configured controller to input the passkey sequence, but it can't be entered when a menu is open.
@ -516,7 +516,7 @@ The process of scraping games is basically identical between the single-game scr
By default, ES-DE will search using the metadata name of the game. If no name has been defined via scraping or manually using the metadata editor, this name will correspond to the physical file name minus all text inside either normal brackets **()** or square brackets **[]**. So for example the physical filename **Mygame (U) [v2].zip** will be stripped to simply **Mygame** when performing the scraping. By default, ES-DE will search using the metadata name of the game. If no name has been defined via scraping or manually using the metadata editor, this name will correspond to the physical file name minus all text inside either normal brackets **()** or square brackets **[]**. So for example the physical filename **Mygame (U) [v2].zip** will be stripped to simply **Mygame** when performing the scraping.
The behavior of using the metadata name rather than the file name can be changed using the setting _Search using metadata name_ as described [below](USERGUIDE.md#other-settings). The behavior of using the metadata name rather than the file name can be changed using the setting **Search using metadata name**.
Note that there is an exception to this behavior for arcade games (MAME and Neo Geo). For ScreenScraper the short MAME names are used by default as this scraper service fully supports that. For TheGamesDB the short names are instead expanded to the full games names using a lookup in the MAME name database supplied with the ES-DE installation. It's possible to override this automatic behavior by using the _Refine Search_ button in the scraper GUI if the search did not yield any results, or if the wrong game was returned. In general though, searching for arcade games is very reliable assuming the physical game files follow the MAME name standard. Note that there is an exception to this behavior for arcade games (MAME and Neo Geo). For ScreenScraper the short MAME names are used by default as this scraper service fully supports that. For TheGamesDB the short names are instead expanded to the full games names using a lookup in the MAME name database supplied with the ES-DE installation. It's possible to override this automatic behavior by using the _Refine Search_ button in the scraper GUI if the search did not yield any results, or if the wrong game was returned. In general though, searching for arcade games is very reliable assuming the physical game files follow the MAME name standard.
@ -575,7 +575,7 @@ Remember that on Unix files are case sensitive, and as well the file extensions
As an alternative, you can also locate your game media in the ROM directory. This is explained below when covering the option **Display game media from ROM directories**. This is however not recommended and the built-in scraper will never save any game media to this folder structure. As an alternative, you can also locate your game media in the ROM directory. This is explained below when covering the option **Display game media from ROM directories**. This is however not recommended and the built-in scraper will never save any game media to this folder structure.
It's possible to change the game media directory from within ES-DE, for this see the option **Game media directory** detailed below. It's possible to change the game media directory from within ES-DE, for this see the option **Game media directory**.
## Main menu ## Main menu
@ -714,7 +714,7 @@ If set to _None_, the system view will be showed. Any other value will jump to t
**Gamelist view style** **Gamelist view style**
Sets the view style to _Automatic, Basic, Detailed, Video_ or _Grid_. See the description [earlier](USERGUIDE.md#gamelist-view) in this document for more information regarding view styles. Sets the view style to _Automatic, Basic, Detailed, Video_ or _Grid_. See the description [above](USERGUIDE.md#gamelist-view) in this document for more information regarding view styles.
**Transition style** **Transition style**
@ -726,7 +726,7 @@ The theme to use. Defaults to rbsimple-DE, the theme shipped with ES-DE.
**UI mode** **UI mode**
Sets the user interface mode for the application to _Full, Kiosk_ or _Kid_. See the description [earlier](USERGUIDE.md#ui-modes) in this document for additional information. Sets the user interface mode for the application to _Full, Kiosk_ or _Kid_. See the description [above](USERGUIDE.md#ui-modes) in this document for additional information.
**Default sort order** **Default sort order**
@ -1127,7 +1127,7 @@ A flag to indicate whether you have completed the game.
**Kidgame** _(files only)_ **Kidgame** _(files only)_
A flag to mark whether the game is suitable for children. This will be applied as a filter when starting ES-DE in _Kid mode_, as is explained [here](USERGUIDE.md#ui-modes) A flag to mark whether the game is suitable for children. This will be applied as a filter when starting ES-DE in _Kid_ mode.
**Hidden** **Hidden**
@ -1163,7 +1163,7 @@ For game files, there will be five buttons displayed on the bottom of the metada
**Scrape** **Scrape**
Opens the single-game scraper, which is explained [earlier](USERGUIDE.md#single-game-scraper) in this guide. The _Y_ button can also be used as a shortcut to start the scraper without having to navigate to this button. Opens the single-game scraper, which is explained [above](USERGUIDE.md#single-game-scraper) in this guide. The _Y_ button can also be used as a shortcut to start the scraper without having to navigate to this button.
**Save** **Save**
@ -1199,7 +1199,7 @@ _An example of what the video screensaver looks like._
ES-DE provides two types of collections, **Automatic collections** and **Custom collections**, the latter being defined by the user. Collections are as the name implies only collections of games already present in your actual game systems, so they're basically grouping your games together into convenient views. As such the use of collections is entirely optional, but it is a very nice feature and it's worth some effort to setup. ES-DE provides two types of collections, **Automatic collections** and **Custom collections**, the latter being defined by the user. Collections are as the name implies only collections of games already present in your actual game systems, so they're basically grouping your games together into convenient views. As such the use of collections is entirely optional, but it is a very nice feature and it's worth some effort to setup.
The numerous collection settings available are detailed [here](USERGUIDE.md#game-collection-settings). The numerous collection settings available are covered [here](USERGUIDE.md#game-collection-settings).
### Automatic collections ### Automatic collections
@ -1267,13 +1267,11 @@ If you're migrating from a previous version of EmulationStation that has absolut
ES-DE is fully themeable, and although the application ships with the comprehensive rbsimple-DE theme set, you can replace it with a number of themes available from various locations on the Internet. ES-DE is fully themeable, and although the application ships with the comprehensive rbsimple-DE theme set, you can replace it with a number of themes available from various locations on the Internet.
>>>
Somewhat confusingly the terms **theme** and **theme set** are used to refer to the same thing. The technically correct term for what you apply to the application to achieve a different look is actually _theme set_ as it's a collection of a number of themes for a number of game systems. The supplied rbsimple-DE is an example of such a theme set. But in this guide and in other EmulationStation resources on the Internet, the term theme is often used to refer to the same thing as a theme set. As long as you are aware of the distinction, it doesn't really matter which term is used. Somewhat confusingly the terms **theme** and **theme set** are used to refer to the same thing. The technically correct term for what you apply to the application to achieve a different look is actually _theme set_ as it's a collection of a number of themes for a number of game systems. The supplied rbsimple-DE is an example of such a theme set. But in this guide and in other EmulationStation resources on the Internet, the term theme is often used to refer to the same thing as a theme set. As long as you are aware of the distinction, it doesn't really matter which term is used.
>>>
Note that this Desktop Edition fork adds additional features to the themes 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 different theme set. But effort is spent trying to make ES-DE backwards compatible with the available themes used by other EmulationStation versions, even if the functionality they provide is limited. Note that this Desktop Edition fork adds additional features to the themes 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 different theme set. But effort is spent trying to make ES-DE backwards compatible with the available themes used by other EmulationStation versions, even if the functionality they provide is limited.
Themes are most easily installed in your ES-DE home directory, i.e. **~/.emulationstation/themes**. By just adding the theme sets there, one folder each, they will be found by ES-DE during startup and you can then choose between them via **UI Settings** on the main menu. Themes are most easily installed in your ES-DE home directory, i.e. **~/.emulationstation/themes**. By just adding the theme sets there, one folder each, they will be found by ES-DE during startup and you can then choose between them via UI Settings on the main menu.
Note that although you can put additional themes in your ES-DE home directory, the default rbsimple-DE theme is located in your installation folder. For example this could be **/usr/local/share/emulationstation/themes** on Unix, **/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes** on macOS or **C:\Program Files\EmulationStation-DE\themes** on Windows. Note that although you can put additional themes in your ES-DE home directory, the default rbsimple-DE theme is located in your installation folder. For example this could be **/usr/local/share/emulationstation/themes** on Unix, **/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes** on macOS or **C:\Program Files\EmulationStation-DE\themes** on Windows.