Documentation update.

CHANGELOG.md

@@ -148,6 +148,7 @@ v1.2 maintenance release.
 
 ### Detailed list of changes
 
+* Added configuration for the Daphne arcade LaserDisc system using the emulator Hypseus Singe
 * Added configuration for the OpenBOR game engine on Linux and Windows
 * Added emulator configuration for the astrocde (Bally Astrocade) system
 * Added scraper support for the astrocde system (ScreenScraper and TheGamesDB)
@@ -171,12 +172,13 @@ v1.2 maintenance release.
 * Added a --create-system-dirs command line option to generate the game system directories
 * Added an Xbox Kinect controller badge icon
 * (macOS) Categorized the application as a game so it shows up in the Launchpad games section
-* Replaced the explicit shell commands in es_systems.xml with %EMULATOR_OS-SHELL% find rules
+* Added an %INJECT% variable for injecting launch arguments from game config files (required by Hypseus Singe)
 * Added a %GAMEDIR% variable that expands to the game directory (required by Hypseus Singe)
 * Made the %GAMEDIR% variable usable with the %STARTDIR% variable (required by OpenBOR)
 * (Windows) Set %RUNINBACKGROUND% when launching MAME standalone as this emulator may otherwise hang on exit
 * (Windows) Added an %ESCAPESPECIALS% variable that escapes the special characters &()^=;,
 * (Windows) Added %ESCAPESPECIALS% to the desktop, epic, kodi, ports and steam systems
+* Replaced the explicit shell commands in es_systems.xml with %EMULATOR_OS-SHELL% find rules
 * Added experimental support for folder flattening
 * Updated the StringUtil::replace function as the old function was dangerous and could run into an endless loop
 

FAQ.md

@@ -28,6 +28,10 @@ See the _Supported game systems_ section at the bottom of the [User guide](USERG
 
 ES-DE comes preconfigured with support for many alternative emulators, see the [What's new in ES-DE v1.2](https://www.youtube.com/watch?v=rpnMJqceSNk) video on the ES-DE YouTube channel for a brief overview of how this works. More emulators are continuously being added with each release.
 
+## Why can't I press the up button in menus to jump to the bottom row and vice versa?
+
+Menus in ES-DE are not lists but grids, sometimes there is only a list but sometimes there are buttons beneath the list. Enabling the up and down buttons to wrap around would therefore not work consistently as it would sometimes jump to the last row of the list and sometimes to a button, depending on the menu layout. This type of contextual navigation feels very weird and inconsistent in practice. The solution is instead to use the shoulder buttons (which will jump six rows), or the trigger buttons (which will jump to the first and last row). These buttons work consistently throughout the application and avoid the strange side effects just mentioned. If you observe this more closely you will also realize that "wrap around" is very rare in GUI design, you don't jump to the top of a web page when you scroll to the bottom and likewise the settings menus of your mobile phone will not wrap around.
+
 ## I'm on Windows and ES-DE can't find my emulators, what is wrong?
 
 On Windows ES-DE is shipped as a portable installation and as a regular installer. If you're using the portable installation you need to drop your emulators inside the Emulators directory. Make sure to read the README.txt file directly in the EmulationStation-DE folder for more details. For the regular installer many emulators do not provide a method to inform ES-DE where they are installed, so you will need to add their installation directories to the Path environment variable in Windows. It's strongly recommended to read the _Specific notes for Windows_ section of the [User guide](USERGUIDE.md#specific-notes-for-windows) before attempting to setup and use ES-DE on Windows.

INSTALL-DEV.md

@@ -1230,7 +1230,9 @@ The following variables are expanded for the `command` tag:
 
 `%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.
 
-`%STARTDIR%` - The directory to start in when launching the emulator. Must be defined as a pair separated by an equal sign. This is normally not required, but some emulators and game engines like standalone MAME and OpenBOR will not work properly unless you're in the correct directory when launching a game. Either an absolute path can be used with this variable, such as `%STARTDIR%=C:\Games\mame` or the `%EMUDIR%` variable can be used to start in the directory where the emulator binary is located, i.e. `%STARTDIR%=%EMUDIR%` or the the `%GAMEDIR%` variable can be used to start in the directory where the game file is located, i.e. `%STARTDIR%=%GAMEDIR%`. If an absolute path is set that contains blankspaces, then it must be surrounded by quotation marks, for example `%STARTDIR%="C:\Retro games\mame"`. If the directory defined by this variable does not exist, it will be created on game launch. The variable can be placed anywhere in the launch command if the %EMULATOR_ variable is used, otherwise it has to be placed after the emulator binary.
+`%STARTDIR%` - The directory to start in when launching the emulator. Must be defined as a pair separated by an equal sign. This is normally not required, but some emulators and game engines like standalone MAME and OpenBOR will not work properly unless you're in the correct directory when launching a game. Either an absolute path can be used with this variable, such as `%STARTDIR%=C:\Games\mame` or the `%EMUDIR%` variable can be used to start in the directory where the emulator binary is located, i.e. `%STARTDIR%=%EMUDIR%` or the `%GAMEDIR%` variable can be used to start in the directory where the game file is located, i.e. `%STARTDIR%=%GAMEDIR%`. If an absolute path is set that contains blankspaces, then it must be surrounded by quotation marks, for example `%STARTDIR%="C:\Retro games\mame"`. If the directory defined by this variable does not exist, it will be created on game launch. The variable can be placed anywhere in the launch command if the %EMULATOR_ variable is used, otherwise it has to be placed after the emulator binary.
+
+`%INJECT%` - This allows the injection of launch arguments stored in a text file on the filesystem. This is for example required by Hypseus Singe (arcade LaserDisc) games. The variable must be defined as a pair separated by an equal sign, for example `%INJECT%=game.commands`. The `%BASENAME%` variable can also be used in conjunction with this variable, such as `%INJECT%=%BASENAME%.commands`. By default a path relative to the game file will be assumed but it's also possible to use an absolute path or the tilde ~ symbol which will expand to the home directory. If a path contains spaces it needs to be surrounded by quotation marks, such as `%INJECT%="C:\My games\ROMs\daphne\%BASENAME%.daphne\%BASENAME%.commands"` The variable can be placed anywhere in the launch command and the arguments will be injected at that position. The specified file is optional, if it does not exist or if there are insufficient permissions to read the file content, then it will simply be skipped. For safety reasons the arguments file can only have a maximum size of 4096 bytes and if it's larger than this it will be skipped.
 
 `%EMUPATH%` - Replaced with the path to the emulator binary. This variable is used for manually specifying emulator core locations, and a check for the existence of the core file will be done on game launch and an error displayed if it can't be found. Normally %EMUPATH% should not be used as the %CORE_ variable is the recommended method for defining core locations.
 

THEMES-LEGACY.md

@@ -894,12 +894,6 @@ The help system is a special element that displays a context-sensitive list of a
 
 ## Example theme sets
 
-To see some example EmulationStation themes, the following resources are recommended:
+To see some example EmulationStation themes, the following resource is recommended:
 
-https://aloshi.com/emulationstation#themes
+https://retropie.org.uk/docs/Themes
-
-https://github.com/RetroPie
-
-https://gitlab.com/recalbox/recalbox-themes
-
-https://wiki.batocera.org/themes

THEMES.md

@@ -989,12 +989,6 @@ The help system is a special element that displays a context-sensitive list of a
 
 ## Example theme sets
 
-To see some example EmulationStation themes, the following resources are recommended:
+To see some example EmulationStation themes, the following resource is recommended:
 
-https://aloshi.com/emulationstation#themes
+https://retropie.org.uk/docs/Themes
-
-https://github.com/RetroPie
-
-https://gitlab.com/recalbox/recalbox-themes
-
-https://wiki.batocera.org/themes

USERGUIDE-DEV.md

@@ -602,10 +602,11 @@ So placing a manually downloaded emulator binary in either of these directories
 
 The following manually downloaded emulators are supported when using the bundled configuration:
 
-| System name  | Emulator    | Filename configuration          |
+| System name  | Emulator      | Filename configuration          |
-| :----------- | :---------- | :------------------------------ |
+| :----------- | :------------ | :------------------------------ |
-| dreamcast    | Redream     | redream                         |
+| daphne       | Hypseus Singe | hypseus-singe/hypseus.bin       |
-| switch       | Ryujinx     | publish/Ryujinx                 |
+| dreamcast    | Redream       | redream                         |
+| switch       | Ryujinx       | publish/Ryujinx                 |
 
 Note that the Ryujinx binary is not set as executable after unpacking the archive, so you need to do that once before ES-DE can run it:
 ```
@@ -613,6 +614,8 @@ cd ~/Applications/publish
 chmod +x ./Ryujinx
 ```
 
+Hypseus Singe is also a special case as you may have to compile this emulator yourself as mentioned elsewhere in this guide.
+
 ## Running emulators in fullscreen mode
 
 In general ES-DE does not pass command line parameters to emulators to start them in fullscreen mode. This is so as for most (if not all) emulators, command line arguments overrides the settings the user has defined. This means that windowed mode would have become impossible to achieve without creating custom systems configuration entries if ES-DE enforced fullscreen mode. There are only a very few exceptions for emulators where there is no other way to enter fullscreen mode than by passing such options during game launch.
@@ -715,7 +718,7 @@ This setup is of course entirely optional, you can also leave the directories as
 
 There are two scenarios where it's useful to interpret directories as files inside ES-DE. The first one is to hide the directory structure for multi-file/multi-disc games while still being able to directly launch files inside these folders, and the second is that some emulators support passing a directory rather than an individual file as the game ROM argument.
 
-In both cases, renaming a directory to one of the supported file extensions will automatically make ES-DE interpret it as a file. This means that the directory can be part of the automatic collections and any custom collections.
+In both cases, renaming a directory to one of the supported file extensions will automatically make ES-DE interpret it as a file. This also means that the directory can be part of the automatic collections and any custom collections.
 
 The only difference between a real file and a directory interpreted as a file is that the _Delete_ button in the metadata editor will be disabled as ES-DE does not support deletion of directories for safety reasons.
 
@@ -741,7 +744,7 @@ Here's another example when using .m3u files:
 ~/ROMs/psx/Final Fantasy VII.m3u/Final Fantasy VII.m3u
 ```
 
-In exactly the same manner, the file `~/ROMs/psx/Final Fantasy VII.m3u/Final Fantasy VII.m3u` will be passed to the emulator on game launch. See the section just above this one, _Multiple game files installation_ for details on how .m3u files work.
+In exactly the same manner, the file `~/ROMs/psx/Final Fantasy VII.m3u/Final Fantasy VII.m3u` will be passed to the emulator on game launch. See the section just above this one, _Multiple game files installation_ for an explanations of how .m3u files work.
 
 The second scenario is when an emulator supports passing a directory rather than a file to launch a game. Such an example is the PlayStation 3 emulator RPCS3.
 
@@ -750,7 +753,7 @@ For PS3 games the extension in es_systems.xml is .ps3 so this is what a game dir
 ~/ROMs/ps3/Gran Turismo 5.ps3
 ```
 
-It's also possible to combine these types of special directories with normal directories, for a setup like this:
+It's possible to combine these types of special directories with normal directories, for a setup like this:
 ```
 ~/ROMs/ps3/racing/Gran Turismo 5.ps3
 ```
@@ -1148,6 +1151,114 @@ This of course assumes that you have menu entries setup for your Steam games.
 
 To greatly simplify this setup, automatic Steam library import is planned for a future ES-DE release.
 
+#### Hypseus Singe (Daphne)
+
+Hypseus Singe is a fork of the Daphne arcade LaserDisc emulator that is still maintained. The setup is very particular so make sure to read this section thoroughly to get it to work.
+
+The first step is to even get the emulator to run. On Windows it's straightforward, just download the win64 release from [https://github.com/DirtBagXon/hypseus-singe](https://github.com/DirtBagXon/hypseus-singe) and unpack it and you're good to go.
+
+For Linux there does not seem to be any precompiled release that is working reliably so you will need to compile it yourself. If running a distribution with access to the AUR, there is a Hypseus Singe release available but this seems to be broken somehow and does not seem to be usable. If the AUR release doesn't work for you, then make sure to uninstall it as it will otherwise be tried first and you'll never get LaserDisc games to work.
+
+Fortunately compiling Hypseus Singe is easy, just make sure that you have the necessary dependencies installed and then follow these steps:
+```
+git clone https://github.com/DirtBagXon/hypseus-singe.git
+cd hypseus-singe/src
+cmake .
+make -j
+mkdir -p ~/Applications/hypseus-singe
+cp -r ../fonts ~/Applications/hypseus-singe
+cp -r ../roms ~/Applications/hypseus-singe
+cp -r ../sound ~/Applications/hypseus-singe
+cp -r ../pics ~/Applications/hypseus-singe
+cp hypseus ~/Applications/hypseus-singe/hypseus.bin
+```
+
+Although there is an official Hypseus Singe release available for macOS M1 this appears somehow broken so you may need to compile it yourself. This is a bit more involved than compiling code on Linux so it's beyond the scope of this document to describe it. For this reason macOS is not listed as supported but the configuration is still bundled so if you're persistent and manage to get the emulator to work, it will hopefully work from within ES-DE as well.
+
+After the emlulator is installed, copy the required BIOS ROMs into `Hypseus Singe\roms\` on Windows or `~/Applications/hypseus-singe/roms/` on Linux.
+
+There are two types of games supported by Hypseus and these are _Daphne_ and _Singe_. It's beyond the scope of this document to describe these game formats in detail but there are many resources available online for this. The setup differs a bit between these two types however, and you need to use an alternative emulator entry in ES-DE to launch Singe games.
+
+**Daphne games**
+
+For Daphne games the structure will look something like the following, which is for the game _Dragon's Lair_:
+
+```
+~/ROMs/daphne/lair.daphne/
+~/ROMs/daphne/lair.daphne/lair.dat
+~/ROMs/daphne/lair.daphne/lair.m2v
+~/ROMs/daphne/lair.daphne/lair.m2v.bf
+~/ROMs/daphne/lair.daphne/lair.ogg
+~/ROMs/daphne/lair.daphne/lair.ogg.bf
+~/ROMs/daphne/lair.daphne/lair.txt
+```
+
+The directory name has to keep this naming convention with the name consisting of the Daphne game type (_lair_ for this example) followed by the .daphne extension. This name logic with a short name per game is similar to how it works in MAME and ScummVM. A list of available games can be found here: \
+[http://www.daphne-emu.com/mediawiki/index.php/CmdLine](http://www.daphne-emu.com/mediawiki/index.php/CmdLine)
+
+In order to get the games to work, simply create an empty file named _\<game\>.daphne_ inside the game directory, for example `lair.daphne` in this case. The _Directories interpreted as files_ functionality will then allow the game to be launched even though it shows up as a single entry inside ES-DE.
+
+There is also the option to add command line parameters for each game which is somehow important as different games may require different DIP switches to be set and you may also want to apply general options like fullscreen mode.
+
+To accomplish this, create a file named _\<game\>.commands_ such as `lair.commands` for this example. The content of this file could look something like the following:
+```
+-fastboot -fullscreen
+```
+
+The -fastboot option is recommended in particular since it leads to a much shorter startup time for those games that support it. All command line options are described at the daphne-emu.com URL posted above.
+
+With these files in place, the game directory should look something like this:
+
+```
+~/ROMs/daphne/lair.daphne/
+~/ROMs/daphne/lair.daphne/lair.commands
+~/ROMs/daphne/lair.daphne/lair.daphne
+~/ROMs/daphne/lair.daphne/lair.dat
+~/ROMs/daphne/lair.daphne/lair.m2v
+~/ROMs/daphne/lair.daphne/lair.m2v.bf
+~/ROMs/daphne/lair.daphne/lair.ogg
+~/ROMs/daphne/lair.daphne/lair.ogg.bf
+~/ROMs/daphne/lair.daphne/lair.txt
+```
+
+**Singe games**
+
+Singe games work a bit differently compared to Daphne games. They come packaged with a lot of files and the game directories normally just consist of the game names, such as:
+```
+~/ROMs/daphne/fireandice/
+~/ROMs/daphne/mononoke/
+```
+
+To make these games work, rename the directories by appending the .singe extension, such as:
+```
+~/ROMs/daphne/fireandice.singe/
+~/ROMs/daphne/mononoke.singe/
+```
+
+You could optionally create a .commands file as well to specify some additional command line parameters, as described above in the Daphne section.
+
+The next step is to modify the _\<game\>.singe_ file to point to the exact game directory.
+
+So for example on Unix, modify the file `~/ROMs/daphne/mononoke.singe/mononoke.singe` by changing the following line:
+```
+MYDIR = "singe/mononoke/"
+```
+To this:
+```
+MYDIR = "/home/myusername/ROMs/daphne/mononoke.singe/"
+```
+
+Note that the tilde ~ character can not be used inside this file to point to your home directory, you have to set the absolute path. And you should of course replace _myusername_ with your own username. The forward slash at the end of the path is also required.
+
+If on Windows, it could look like the following instead:
+```
+MYDIR = "C:\\Users\\myusername\\ROMs\\daphne\\mononoke.singe\\"
+```
+
+You have to put double backslash characters as shown above (including at the end of the path), otherwise the game won't start.
+
+The last step to get Singe games to work is to assign the alternative emulator _Hypseus [Singe] (Standalone)_ to these games. This is done via the _Alternative emulator_ entry in the metadata editor. Attempting to launch a Singe game using the default emulator will not work.
+
 #### OpenBOR
 
 The Open Beats of Rage (OpenBOR) game engine is available on Windows and Linux. Unfortunately the macOS ports seems to have been abandoned.
@@ -2296,16 +2407,9 @@ Although you place additional themes in your ES-DE home directory, the default s
 
 So if you would like to customize the slate-DE or modern-DE theme sets, simply make a copy of their directories to ~/.emulationstation/themes and then those copies will take precedence over the ones in the application installation directory.
 
+Here is a good resource with a list of themes (although you will have to search online for the download location for each theme set):
 
-Here are some resources where additional theme sets can be downloaded.
+https://retropie.org.uk/docs/Themes
-
-https://aloshi.com/emulationstation#themes
-
-https://github.com/RetroPie
-
-https://gitlab.com/recalbox/recalbox-themes
-
-https://wiki.batocera.org/themes
 
 ![alt text](images/es-de_ui_theme_support.png "ES-DE Theme Support")
 _This is a screenshot of the modern-DE theme that is bundled with ES-DE (in addition to the default slate-DE theme)._
@@ -2395,7 +2499,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
 | channelf              | Fairchild Channel F                            | FreeChaF                          |                                   |              |                                      |
 | coco                  | Tandy Color Computer                           | _Placeholder_                     |                                   |              |                                      |
 | colecovision          | ColecoVision                                   | Gearcoleco                        | blueMSX                           |              |                                      |
-| daphne                | Daphne Arcade LaserDisc Emulator               | _Placeholder_                     |                                   |              |                                      |
+| daphne                | Daphne Arcade LaserDisc Emulator               | Hypseus [Daphne] **(Standalone)** [UW*] | Hypseus [Singe] **(Standalone)** [UW*] | Yes (Daphne games) | See the specific _Hypseus Singe (Daphne)_ section elsewhere in this guide |
 | desktop               | Desktop Applications                           | N/A                               |                                   | No           |                                      |
 | doom                  | Doom                                           | PrBoom                            |                                   |              |                                      |
 | dos                   | DOS (PC)                                       | DOSBox-Pure                       | DOSBox-Core,<br>DOSBox-SVN,<br>DOSBox-X **(Standalone)**,<br>DOSBox Staging **(Standalone)** [UMW*] | No           | In separate folder (one folder per game with complete file structure retained) |
@@ -2447,7 +2551,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
 | ngp                   | SNK Neo Geo Pocket                             | Beetle NeoPop                     | RACE                              |              |                                      |
 | ngpc                  | SNK Neo Geo Pocket Color                       | Beetle NeoPop                     | RACE                              |              |                                      |
 | odyssey2              | Magnavox Odyssey2                              | O2EM                              |                                   |              |                                      |
-| openbor               | OpenBOR Game Engine                            | OpenBOR **(Standalone)** [UW]     |                                   |              | See the specific OpenBOR section elsewhere in this guide |
+| openbor               | OpenBOR Game Engine                            | OpenBOR **(Standalone)** [UW]     |                                   |              | See the specific _OpenBOR_ section elsewhere in this guide |
 | oric                  | Tangerine Computer Systems Oric                | _Placeholder_                     |                                   |              |                                      |
 | palm                  | Palm OS                                        | Mu                                |                                   |              |                                      |
 | pc                    | IBM PC                                         | DOSBox-Pure                       | DOSBox-Core,<br>DOSBox-SVN,<br>DOSBox-X **(Standalone)**,<br>DOSBox Staging **(Standalone)** [UMW*] | No           | In separate folder (one folder per game with complete file structure retained) |

USERGUIDE.md

@@ -731,7 +731,7 @@ This setup is of course entirely optional, you can also leave the directories as
 
 There are two scenarios where it's useful to interpret directories as files inside ES-DE. The first one is to hide the directory structure for multi-file/multi-disc games while still being able to directly launch files inside these folders, and the second is that some emulators support passing a directory rather than an individual file as the game ROM argument.
 
-In both cases, renaming a directory to one of the supported file extensions will automatically make ES-DE interpret it as a file. This means that the directory can be part of the automatic collections and any custom collections.
+In both cases, renaming a directory to one of the supported file extensions will automatically make ES-DE interpret it as a file. This also means that the directory can be part of the automatic collections and any custom collections.
 
 The only difference between a real file and a directory interpreted as a file is that the _Delete_ button in the metadata editor will be disabled as ES-DE does not support deletion of directories for safety reasons.
 
@@ -757,7 +757,7 @@ Here's another example when using .m3u files:
 ~/ROMs/psx/Final Fantasy VII.m3u/Final Fantasy VII.m3u
 ```
 
-In exactly the same manner, the file `~/ROMs/psx/Final Fantasy VII.m3u/Final Fantasy VII.m3u` will be passed to the emulator on game launch. See the section just above this one, _Multiple game files installation_ for details on how .m3u files work.
+In exactly the same manner, the file `~/ROMs/psx/Final Fantasy VII.m3u/Final Fantasy VII.m3u` will be passed to the emulator on game launch. See the section just above this one, _Multiple game files installation_ for an explanations of how .m3u files work.
 
 The second scenario is when an emulator supports passing a directory rather than a file to launch a game. Such an example is the PlayStation 3 emulator RPCS3.
 
@@ -766,7 +766,7 @@ For PS3 games the extension in es_systems.xml is .ps3 so this is what a game dir
 ~/ROMs/ps3/Gran Turismo 5.ps3
 ```
 
-It's also possible to combine these types of special directories with normal directories, for a setup like this:
+It's possible to combine these types of special directories with normal directories, for a setup like this:
 ```
 ~/ROMs/ps3/racing/Gran Turismo 5.ps3
 ```
@@ -2163,16 +2163,9 @@ Although you place additional themes in your ES-DE home directory, the default r
 
 So if you would like to customize the rbsimple-DE or modern-DE theme sets, simply make a copy of their directories to ~/.emulationstation/themes and then those copies will take precedence over the ones in the application installation directory.
 
+Here is a good resource with a list of themes (although you will have to search online for the download location for each theme set):
 
-Here are some resources where additional theme sets can be downloaded.
+https://retropie.org.uk/docs/Themes
-
-https://aloshi.com/emulationstation#themes
-
-https://github.com/RetroPie
-
-https://gitlab.com/recalbox/recalbox-themes
-
-https://wiki.batocera.org/themes
 
 ![alt text](images/es-de_ui_theme_support.png "ES-DE Theme Support")
 _This is a screenshot of the modern-DE theme that is bundled with ES-DE (in addition to the default rbsimple-DE theme)._

es-app/assets/Windows_Portable_README.txt

@@ -33,6 +33,7 @@ Emulators\DOSBox-X\dosbox-x.exe
 Emulators\duckstation\duckstation-nogui-x64-ReleaseLTCG.exe
 Emulators\duckstation\duckstation-qt-x64-ReleaseLTCG.exe
 Emulators\flycast\flycast.exe
+Emulators\Hypseus Singe\hypseus.exe
 Emulators\mame\mame.exe
 Emulators\melonDS\melonDS.exe
 Emulators\mGBA\mGBA.exe