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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2021-12-23 13:40:14 +01:00
parent d199554d86
commit 678a1e0fc9
3 changed files with 48 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
CHANGELOG.md
View file

@ -89,6 +89,7 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac
* Moved the ScreenScraper account toggle to the bottom of the scraper account settings menu
* Lowered the default volumes slightly for videos and navigation sounds
* Added loading of the System view to the ViewController preload function to decrease theme extras texture pop-in
* (macOS) Disabled the application startup animations as they were very choppy and looked bad after moving to SDL 2.0.18
* Changed the filter description "Text filter (game name)" to simply "Game name"
* Removed a margin hack from TextComponent
* If abbreviated strings end with a space character, that space is now removed (TextComponent)
@ -147,6 +148,7 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac
* Multi-scraping and aborting before any games were fully scraped but after some game media was downloaded did not trigger a gamelist reload
* (Windows) Launching a game that changed the screen resolution would offset the ES-DE application window when exiting
* (Windows) Enabling the option to hide the taskbar would sometimes not focus the application window on startup (possibly only an issue on Windows 8.1)
* If there were gamelist.xml entries for existing files whose extensions were not setup in es_systems.xml, these would still get loaded and displayed
* Fixed multiple minor rendering issues where graphics would be slightly cut off or incorrectly resized
* Under some circumstances ScrollableContainer (used for the game descriptions) would contain a partially rendered bottom line
* If the TextListComponent height was not evenly dividable by the font height + line spacing, a partial bottom row would get rendered
@ -475,3 +477,5 @@ Many bugs have been fixed, and numerous features that were only partially implem
* There is some screen tearing present on Unix/Linux which is especially visible during horizontal slide transitions. The problem exists on both x86 and ARM as well as on Intel, AMD and Nvidia GPUs and on the Broadcom VideoCore. The problem seems to be Xorg-related as tearing has not been observed when using Wayland, and it's not present on macOS or Windows either.
* Sometimes when RetroArch has been upgraded to a newer version, it apparently requires a startup to get properly initialized. When ES-DE starts RetroArch it always does so by passing some specific emulator core parameters, which does not seem to initialize RetroArch after such an upgrade. What happens in this case is that the RetroArch loading screen will be shown and then it will quit right back to ES-DE. If confirmed to be the case, this is not an ES-DE issue but a RetroArch issue and starting RetroArch separately once should fix the problem (at least until the next upgrade).
* There are problems with starting the standalone version of the PCSX2 PlayStation 2 emulator using some GPUs. What happens is that the emulator window does not get focused when launching a game which requires a manual Alt + Tab (or Command + Tab on macOS) to switch to the PCSX2 window. The RetroArch version of PCSX2 does not have this issue.

26
INSTALL-DEV.md
View file

@ -626,7 +626,7 @@ Assuming the code signing ceritificate is properly setup in Keychain Access, the
Normally ES-DE is meant to be built for macOS 10.14 and higher, but a legacy build for earlier operating system versions can be enabled. This has been tested with a minimum version of 10.11. It's unclear if it works with even older macOS releases.
To enable a legacy build, change the CMAKE_OSX_DEPLOYMENT_TARGET variable in CMakeLists.txt from 10.14 to whatever version you would like to build for. This will disable Hardened Runtime if signing is enabled and it will add "legacy" to the DMG installer file name when running CPack. It will also enable the bundled TLS/SSL certificates. As these older macOS releases are no longer receiving patches from Apple, certificates have likely expired which would break the scraper.
To enable a legacy build, change the CMAKE_OSX_DEPLOYMENT_TARGET variable in CMakeLists.txt from 10.14 to whatever version you would like to build for. This will disable Hardened Runtime if signing is enabled and it will add "legacy" to the DMG installer filename when running CPack. It will also enable the bundled TLS/SSL certificates. As these older macOS releases are no longer receiving patches from Apple, certificates have likely expired meaning the scraper would not work if the bundled certificates were not used.
You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the key SMinimumSystemVersion to the version you're building for. And finally CMAKE_OSX_DEPLOYMENT_TARGET needs to be updated in tools/macOS_dependencies_build.sh. This script then needs to be executed to rebuild all dependencies for the configured macOS version.
@ -1753,17 +1753,27 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
</rule>
</core>
<emulator name="DOSBOX_STAGING">
<!-- DOS emulator DOSBox Staging, Homebrew version -->
<!-- DOS emulator DOSBox Staging -->
<rule type="staticpath">
<entry>/Applications/dosbox-staging.app/Contents/MacOS/dosbox</entry>
<!-- Homebrew version -->
<entry>/usr/local/bin/dosbox-staging</entry>
</rule>
</emulator>
<emulator name="MUPEN64PLUS">
<!-- Nintendo 64 emulator Mupen64Plus, Homebrew version -->
<!-- Nintendo 64 emulator Mupen64Plus -->
<rule type="staticpath">
<entry>/Applications/mupen64plus.app/Contents/MacOS/mupen64plus</entry>
<!-- Homebrew version -->
<entry>/usr/local/bin/mupen64plus</entry>
</rule>
</emulator>
<emulator name="PCSX2">
<!-- Sony PlayStation 2 emulator PCSX2 -->
<rule type="staticpath">
<entry>/Applications/PCSX2.app/Contents/MacOS/PCSX2</entry>
</rule>
</emulator>
</ruleList>
```
@ -1989,12 +1999,14 @@ These are the steps to perform:
You should end up with something like this:
```
F:\EmulationStation-DE\
F:\EmulationStation-DE\dosbox-staging\
F:\EmulationStation-DE\PCSX2\
F:\EmulationStation-DE\RetroArch-Win64\
F:\EmulationStation-DE\yuzu\
F:\EmulationStation-DE\ROMs\
F:\EmulationStation-DE\RPCS3\
F:\EmulationStation-DE\xemu\
F:\EmulationStation-DE\xenia\
F:\EmulationStation-DE\ROMs\
F:\EmulationStation-DE\yuzu\
F:\EmulationStation-DE\portable.txt
```
@ -2009,12 +2021,16 @@ By default the emulators that will be automatically searched for by ES-DE are (r
```
RetroArch-Win64\retroarch.exe
RetroArch\retroarch.exe
dosbox-staging\dosbox.exe
PCSX2\pcsx2.exe
RPCS3\rpcs3.exe
xemu\xemu.exe
xenia\xenia.exe
yuzu\yuzu-windows-msvc\yuzu.exe
..\RetroArch-Win64\retroarch.exe
..\RetroArch\retroarch.exe
..\dosbox-staging\dosbox.exe
..\PCSX2\pcsx2.exe
..\RPCS3\rpcs3.exe
..\xemu\xemu.exe
..\xenia\xenia.exe

27
USERGUIDE-DEV.md
View file

@ -175,11 +175,15 @@ Unfortunately on Linux it's at the moment not possible to run the Steam release
## Specific notes for macOS
The main issue with macOS is the somewhat sorry state of emulator support. Many emulators are simply not available on this operating system, or the precompiled binaries have not been notarized meaning they will not run on anything newer than macOS 10.14.5. Using the Homebrew package manager partly compensates for this as some additional emulators are available there, but Apple's lack of support for Vulkan means some emulators simply can't be used. Most RetroArch cores are available though.
The main issue with macOS is lack of emulator support and missing (or buggy) controller drivers.
As Apple refuses to support Vulkan some emulators are simply not available, and other emulators exist but have not been updated for macOS in recent years. As well many emulators are available for download but are not codesigned or notarized which require you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, then go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button in the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions.
Lack of controller support is another issue, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot.
ES-DE currently ships only as an x86/Intel binary so if you run it on an M1 Mac, you need to also install x86 versions of all emulators including RetroArch. That's also the case for any emulators installed via Homebrew. The reason this is needed is that the Rosetta 2 translation environment does not support mixing of ARM and x86 architectures.
Another macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" must be enabled or ES-DE will not be able to switch to the emulator window. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. It's currently unclear if other emulators than RetroArch are affected by this issue, at least some are confirmed to not having this problem.
Another macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" must be enabled or ES-DE will not be able to switch to the emulator window. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. It's currently unclear if other emulators than RetroArch are affected by this issue, at least until now none of the other emulators tested have displayed this behavior. The standalone PlayStation 2 emulator PCSX2 has a similar issue but that seems to be GPU driver related and is problematic also on other operating systems. If using this emulator you need to manually switch to the PCSX2 window using Command + Tab after launching the game from ES-DE.
The first time you launch a game from within ES-DE, the operating system will present you with a security option with the following description:
@ -189,6 +193,8 @@ If you don't allow this, you will not be able to place system BIOS ROMs in the R
If you accidentally refused ES-DE the folder access, you can fix this by opening _System Preferences_, selecting _Security & Privacy_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _EmulationStation Desktop Edition_.
A minor annoyance is that macOS creates metadata files starting with ._ in the filename when placing game/ROM files on some filesystem types such as exFAT. This means that you will see double entries inside ES-DE for all such games. To hide these extra files, the option _Show hidden files and folders (requires restart)_ in the _Other settings_ menu can be set to disabled.
Another problem on macOS 11 Big Sur (and possibly older OS versions) is that when connecting a Sony DualShock 4 controller either via Bluetooth or using a USB cable, two separate controller devices are registered in parallel. This is a bug in either macOS or the DualShock driver and it makes it seem as if ES-DE is registering double button presses when actually two separate controller devices are generating identical input. A workaround if using Bluetooth mode is to plug in the USB cable just after connecting the controller, wait a second or two and then remove the cable again. This will remove the cabled device, leaving only the Bluetooth device active. Another workaround is to enable the setting _Only accept input from first controller_ in the ES-DE input device settings. The reason why this bug may not be visible in some other games and applications is that ES-DE enables and auto-configures all connected controllers. The issue appears to be resolved in macOS Monterey.
@ -1896,7 +1902,7 @@ Sometimes the name of the console is (more or less) the same for multiple region
For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name.
The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a _[U]_. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. The [M+] indication for macOS means that the Homebrew package manager version of the emulator needs to be installed. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup.
The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup.
The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core.
@ -1917,17 +1923,14 @@ In general .zip or .7z files are recommended for smaller-sized games like those
Consider the table below a work in progress as it's obvioulsy not fully populated yet!
Default emulator/Alternative emulators columns: \
**[U]**: Unix, **[M]**: macOS, **[W]**: Windows
Special indications: \
**[M+]**: macOS, Homebrew package manager version, **[W\*]**: Windows, needs manual Path environment variable entry
**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs manual Path environment variable entry
All emulators are RetroArch cores unless marked as **(Standalone**)
| System name | Full name | Default emulator | Alternative emulators | Needs BIOS | Recommended game setup |
| :-------------------- | :--------------------------------------------- | :-------------------------------- | :-------------------------------- | :----------- | :----------------------------------- |
| 3do | 3DO | 4DO | | | |
| 64dd | Nintendo 64DD | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | ParaLLEl N64 [UW],<br>Mupen64Plus **(Standalone)** [M+] | | |
| 64dd | Nintendo 64DD | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | ParaLLEl N64 [UW],<br>Mupen64Plus **(Standalone)** [M] | | |
| ags | Adventure Game Studio Game Engine | _Placeholder_ | | | |
| amiga | Commodore Amiga | PUAE | | Yes | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disc, or in separate folder with .m3u playlist if multi-disc |
| amiga600 | Commodore Amiga 600 | PUAE | | Yes | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disc, or in separate folder with .m3u playlist if multi-disc |
@ -1961,7 +1964,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| daphne | Daphne Arcade LaserDisc Emulator | _Placeholder_ | | | |
| desktop | Desktop Applications | N/A | | No | |
| doom | Doom | PrBoom | | | |
| dos | DOS (PC) | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [UM+] | No | In separate folder (one folder per game with complete file structure retained) |
| dos | DOS (PC) | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [UMW*] | No | In separate folder (one folder per game with complete file structure retained) |
| dragon32 | Dragon 32 | _Placeholder_ | | | |
| dreamcast | Sega Dreamcast | Flycast | | | |
| epic | Epic Games Store | Epic Games Store application **(Standalone)** | | No | Shell script/batch file in root folder |
@ -2001,7 +2004,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| naomi | Sega NAOMI | Flycast | | | |
| naomigd | Sega NAOMI GD-ROM | Flycast | | | |
| n3ds | Nintendo 3DS | Citra [UW] | Citra 2018 [UW] | | |
| n64 | Nintendo 64 | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | ParaLLEl N64 [UW],<br>Mupen64Plus **(Standalone)** [M+] | No | Single archive or ROM file in root folder |
| n64 | Nintendo 64 | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | ParaLLEl N64 [UW],<br>Mupen64Plus **(Standalone)** [M] | No | Single archive or ROM file in root folder |
| nds | Nintendo DS | DeSmuME | DeSmuME 2015,<br>melonDS | | |
| neogeo | SNK Neo Geo | FinalBurn Neo | | Yes | Single archive file following MAME name standard in root folder |
| neogeocd | SNK Neo Geo CD | NeoCD | | Yes | Single archive in root folder (which includes the CD image and ripped audio) |
@ -2013,7 +2016,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| openbor | OpenBOR Game Engine | _Placeholder_ | | | |
| oric | Tangerine Computer Systems Oric | _Placeholder_ | | | |
| palm | Palm OS | Mu | | | |
| pc | IBM PC | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [UM+] | No | In separate folder (one folder per game with complete file structure retained) |
| pc | IBM PC | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [UMW*] | No | In separate folder (one folder per game with complete file structure retained) |
| pc88 | NEC PC-8800 Series | QUASI88 | | | |
| pc98 | NEC PC-9800 Series | Neko Project II Kai | Neko Project II | | |
| pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST | No | Single archive or ROM file in root folder |
@ -2021,7 +2024,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| pcfx | NEC PC-FX | Beetle PC-FX | | | |
| pokemini | Nintendo Pokémon Mini | PokeMini | | No | |
| ports | Ports | N/A | | No | Shell/batch script in separate folder (possibly combined with game data) |
| ps2 | Sony PlayStation 2 | PCSX2 [UW] | | | |
| ps2 | Sony PlayStation 2 | PCSX2 [UW],<br>PCSX2 **(Standalone)** [M] | PCSX2 **(Standalone)** [UW] | Yes | |
| ps3 | Sony PlayStation 3 | RPCS3 **(Standalone)** [UW*] | | Yes | In separate folder (one folder per game with complete file structure retained, renamed to the .ps3dir extension) |
| ps4 | Sony PlayStation 4 | _Placeholder_ | | | |
| psp | Sony PlayStation Portable | PPSSPP | | | |