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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2021-12-16 22:56:23 +01:00
parent 0e1c66ccbb
commit 20ebc2003d
2 changed files with 22 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
INSTALL-DEV.md
View file

@ -1739,8 +1739,15 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
</rule> </rule>
</core> </core>
<emulator name="DOSBOX_STAGING"> <emulator name="DOSBOX_STAGING">
<!-- DOS emulator DOSBox Staging, Homebrew version -->
<rule type="staticpath"> <rule type="staticpath">
<entry>/Applications/dosbox-staging.app/Contents/MacOS/dosbox</entry> <entry>/usr/local/bin/dosbox-staging</entry>
</rule>
</emulator>
<emulator name="MUPEN64PLUS">
<!-- Nintendo 64 emulator Mupen64Plus, Homebrew version -->
<rule type="staticpath">
<entry>/usr/local/bin/mupen64plus</entry>
</rule> </rule>
</emulator> </emulator>
</ruleList> </ruleList>

23
USERGUIDE-DEV.md
View file

@ -175,7 +175,11 @@ Unfortunately on Linux it's at the moment not possible to run the Steam release
## Specific notes for macOS ## Specific notes for macOS
The main issue with macOS is the 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. But most RetroArch cores are available so in general macOS is still a viable retrogaming platform. And if you are willing to compile from source code then this gives access to a number of additional emulators. However the procedure for emulator compilation is beyond the scope of the ES-DE documentation and the systems configuration file has only been preconfigured for emulators that are readily available for download and that have been verified as working on current macOS releases. 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 emulators are available there, but underlying issues like Apple's refusal to support the Vulkan and OpenGL graphics libraries means some emulators simply can't be used. Most RetroArch cores are available though, so macOS is still a viable retrogaming platform.
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.
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: 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:
@ -185,8 +189,6 @@ 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_. 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_.
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.
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. 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.
@ -1838,7 +1840,7 @@ Sometimes the name of the console is (more or less) the same for multiple region
For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name. For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name.
The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a _[U]_. 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. 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]_. 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 **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core.
@ -1859,14 +1861,17 @@ In general .zip or .7z files are recommended for smaller-sized games like those
Consider the table below a work in progress as it's obvioulsy not fully populated yet! Consider the table below a work in progress as it's obvioulsy not fully populated yet!
Default emulator/Alternative emulators columns: \ Default emulator/Alternative emulators columns: \
**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs manual Path entry **[U]**: Unix, **[M]**: macOS, **[W]**: Windows
Special indications: \
**[M+]**: macOS, Homebrew package manager version, **[W\*]**: Windows, needs manual Path environment variable entry
All emulators are RetroArch cores unless marked as **(Standalone**) All emulators are RetroArch cores unless marked as **(Standalone**)
| System name | Full name | Default emulator | Alternative emulators | Needs BIOS | Recommended game setup | | System name | Full name | Default emulator | Alternative emulators | Needs BIOS | Recommended game setup |
| :-------------------- | :--------------------------------------------- | :-------------------------------- | :-------------------------------- | :----------- | :----------------------------------- | | :-------------------- | :--------------------------------------------- | :-------------------------------- | :-------------------------------- | :----------- | :----------------------------------- |
| 3do | 3DO | 4DO | | | | | 3do | 3DO | 4DO | | | |
| 64dd | Nintendo 64DD | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | ParaLLEl N64 [UW] | | | | 64dd | Nintendo 64DD | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | ParaLLEl N64 [UW],<br>Mupen64Plus **(Standalone)** [M+] | | |
| ags | Adventure Game Studio Game Engine | _Placeholder_ | | | | | 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 | | 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 | | 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 |
@ -1900,7 +1905,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| daphne | Daphne Arcade LaserDisc Emulator | _Placeholder_ | | | | | daphne | Daphne Arcade LaserDisc Emulator | _Placeholder_ | | | |
| desktop | Desktop Applications | N/A | | No | | | desktop | Desktop Applications | N/A | | No | |
| doom | Doom | PrBoom | | | | | doom | Doom | PrBoom | | | |
| dos | DOS (PC) | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [U] | 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)** [UM+] | No | In separate folder (one folder per game, with complete file structure retained) |
| dragon32 | Dragon 32 | _Placeholder_ | | | | | dragon32 | Dragon 32 | _Placeholder_ | | | |
| dreamcast | Sega Dreamcast | Flycast | | | | | dreamcast | Sega Dreamcast | Flycast | | | |
| epic | Epic Games Store | Epic Games Store application **(Standalone)** | | No | Shell script/batch file in root folder | | epic | Epic Games Store | Epic Games Store application **(Standalone)** | | No | Shell script/batch file in root folder |
@ -1940,7 +1945,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| naomi | Sega NAOMI | Flycast | | | | | naomi | Sega NAOMI | Flycast | | | |
| naomigd | Sega NAOMI GD-ROM | Flycast | | | | | naomigd | Sega NAOMI GD-ROM | Flycast | | | |
| n3ds | Nintendo 3DS | Citra [UW] | Citra 2018 [UW] | | | | n3ds | Nintendo 3DS | Citra [UW] | Citra 2018 [UW] | | |
| n64 | Nintendo 64 | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | ParaLLEl N64 [UW] | 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 | | | | 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 | | 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) | | neogeocd | SNK Neo Geo CD | NeoCD | | Yes | Single archive in root folder (which includes the CD image and ripped audio) |
@ -1952,7 +1957,7 @@ All emulators are RetroArch cores unless marked as **(Standalone**)
| openbor | OpenBOR Game Engine | _Placeholder_ | | | | | openbor | OpenBOR Game Engine | _Placeholder_ | | | |
| oric | Tangerine Computer Systems Oric | _Placeholder_ | | | | | oric | Tangerine Computer Systems Oric | _Placeholder_ | | | |
| palm | Palm OS | Mu | | | | | palm | Palm OS | Mu | | | |
| pc | IBM PC | DOSBox-Core | DOSBox-Pure,<br>DOSBox-SVN,<br>DOSBox Staging **(Standalone)** [U] | 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)** [UM+] | No | In separate folder (one folder per game, with complete file structure retained) |
| pc88 | NEC PC-8800 Series | QUASI88 | | | | | pc88 | NEC PC-8800 Series | QUASI88 | | | |
| pc98 | NEC PC-9800 Series | Neko Project II Kai | Neko Project II | | | | 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 | | pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST | No | Single archive or ROM file in root folder |