diff --git a/CHANGELOG.md b/CHANGELOG.md index 1226c4a9c..6720a4597 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -147,6 +147,9 @@ v1.2 maintenance release. ### Detailed list of changes +* 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) * Removed the --escape-exit command line option for the PPSSPP standalone emulator as it caused issues for some users * Changed the default emulator for the famicom, fds and nes systems from Nestopia UE to Mesen * Changed the default emulator for the gb and gbc systems from SameBoy to Gambatte @@ -155,7 +158,10 @@ v1.2 maintenance release. * Changed the default emulator for the mame system from MAME 2003-Plus to MAME - Current * Added DOSBox-X standalone as an alternative emulator for the dos and pc systems * Added AetherSX2 standalone as an alternative emulator for the ps2 system on macOS +* 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 a new %GAMEDIR% variable to be used in conjunction 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7edd60ede..b59b75cbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,7 +96,6 @@ The roadmap is under constant review so expect it to change from time to time. S * Vulkan renderer for all supported operating systems * Localization/multi-language support * Dependency on MoltenVK to get Metal support on macOS -* Decommission of the OpenGL 2.1 and OpenGL ES renderers (or keep as legacy mode/legacy build?) * Better and more accurate GPU and memory usage statistics overlay * Bulk metadata editor * Improve multi-threading diff --git a/FAQ.md b/FAQ.md index 7ec054bbb..c41dc9e95 100644 --- a/FAQ.md +++ b/FAQ.md @@ -60,6 +60,10 @@ See the question above for a possible solution. Another approach would be to hid No, by default games are not removed from the gamelists when they are hidden and are instead only marked with a much lower text opacity. You need to disable the setting _Show hidden games (requires restart)_ from the _Other settings_ menu to make them disappear entirely. The reason this option is not disabled by default is that new users could very easily make a mistake by hiding some files accidentally without realizing it, only to have the entries being immediately removed from the gamelist view. It's also good practice to hide all your games with this option enabled and verify that it's all correct before going ahead and disabling it. +## I'm using Linux or macOS and I can't find the .emulationstation directory, where is it located? + +The .emulationstation directory is normally located in your home directory, but on these Unix-based operating systems files and directories starting with a dot are hidden by default. So you need to enable hidden files and directories in your file manager. On macOS this is done in Finder using the Shift + Command + . (a dot) keyboard combination. On Linux it depends on which file manager you're using, but in Dolphin it's accomplished by using the Alt + . (a dot) keyboard combination or via the corresponding entry in the hamburger menu. + ## Is there a way to customize existing systems, and/or to add more systems than those shipped by default? Yes it's possible to both customize existing systems that are part of the bundled configuration as well as to add more systems than those shipped with ES-DE. Almost nothing is hardcoded in the application so there is a huge flexibility when it comes to such configuration. How this is done is covered in the _Game system customizations_ section of the [User guide](USERGUIDE.md#game-system-customizations). Just make sure to never modify the es_systems.xml and es_find_rules.xml files included in the application installation directory as these will be overwritten when upgrading ES-DE in the future. Always place your customizations in ~/.emulationstation/custom_systems/ as is also described in the user guide. diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 854f4f921..902344e55 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -1227,7 +1227,7 @@ 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 like standalone MAME 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%`. 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. +`%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. `%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. diff --git a/THEMES-DEV.md b/THEMES-DEV.md index f0a746ddd..c9b05e557 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -1069,6 +1069,7 @@ Properties: `wii_remote_and_nunchuk_nintendo`, `joycon_left_or_right_nintendo`, `joycon_pair_nintendo`, + `xbox_kinect`, `unknown` * `folderLinkPos` - type: NORMALIZED_PAIR - The position of the folder link icon relative to the parent `folder` badge. diff --git a/THEMES-LEGACY.md b/THEMES-LEGACY.md index e0456444f..3edd2230d 100644 --- a/THEMES-LEGACY.md +++ b/THEMES-LEGACY.md @@ -848,7 +848,7 @@ It's strongly recommended to use the same image dimensions for all badges as var - A badge icon override. Specify the badge type in the attribute `badge`. The available badges are the ones listed above. * `customControllerIcon` - type: PATH. - A controller icon override. Specify the controller type in the attribute `controller`. These are the available types: - - `gamepad_generic`, `gamepad_nintendo_nes`, `gamepad_nintendo_snes`, `gamepad_nintendo_64`, `gamepad_playstation`, `gamepad_sega_md_3_buttons`, `gamepad_sega_md_6_buttons`, `gamepad_xbox`, `joystick_generic`, `joystick_arcade_no_buttons`, `joystick_arcade_1_button`, `joystick_arcade_2_buttons`, `joystick_arcade_3_buttons`, `joystick_arcade_4_buttons`, `joystick_arcade_5_buttons`, `joystick_arcade_6_buttons`, `keyboard_generic`, `keyboard_and_mouse_generic`, `mouse_generic`, `mouse_amiga`, `lightgun_generic`, `lightgun_nintendo`, `steering_wheel_generic`, `flight_stick_generic`, `spinner_generic`, `trackball_generic`, `wii_remote_nintendo`, `wii_remote_and_nunchuk_nintendo`, `joycon_left_or_right_nintendo`, `joycon_pair_nintendo`, `unknown`. + - `gamepad_generic`, `gamepad_nintendo_nes`, `gamepad_nintendo_snes`, `gamepad_nintendo_64`, `gamepad_playstation`, `gamepad_sega_md_3_buttons`, `gamepad_sega_md_6_buttons`, `gamepad_xbox`, `joystick_generic`, `joystick_arcade_no_buttons`, `joystick_arcade_1_button`, `joystick_arcade_2_buttons`, `joystick_arcade_3_buttons`, `joystick_arcade_4_buttons`, `joystick_arcade_5_buttons`, `joystick_arcade_6_buttons`, `keyboard_generic`, `keyboard_and_mouse_generic`, `mouse_generic`, `mouse_amiga`, `lightgun_generic`, `lightgun_nintendo`, `steering_wheel_generic`, `flight_stick_generic`, `spinner_generic`, `trackball_generic`, `wii_remote_nintendo`, `wii_remote_and_nunchuk_nintendo`, `joycon_left_or_right_nintendo`, `joycon_pair_nintendo`, `xbox_kinect`, `unknown`. * `visible` - type: BOOLEAN. - If true, element will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. * `zIndex` - type: FLOAT. diff --git a/THEMES.md b/THEMES.md index 65ee5e1e6..64e2c8905 100644 --- a/THEMES.md +++ b/THEMES.md @@ -943,7 +943,7 @@ It's strongly recommended to use the same image dimensions for all badges as var - A badge icon override. Specify the badge type in the attribute `badge`. The available badges are the ones listed above. * `customControllerIcon` - type: PATH. - A controller icon override. Specify the controller type in the attribute `controller`. These are the available types: - - `gamepad_generic`, `gamepad_nintendo_nes`, `gamepad_nintendo_snes`, `gamepad_nintendo_64`, `gamepad_playstation`, `gamepad_sega_md_3_buttons`, `gamepad_sega_md_6_buttons`, `gamepad_xbox`, `joystick_generic`, `joystick_arcade_no_buttons`, `joystick_arcade_1_button`, `joystick_arcade_2_buttons`, `joystick_arcade_3_buttons`, `joystick_arcade_4_buttons`, `joystick_arcade_5_buttons`, `joystick_arcade_6_buttons`, `keyboard_generic`, `keyboard_and_mouse_generic`, `mouse_generic`, `mouse_amiga`, `lightgun_generic`, `lightgun_nintendo`, `steering_wheel_generic`, `flight_stick_generic`, `spinner_generic`, `trackball_generic`, `wii_remote_nintendo`, `wii_remote_and_nunchuk_nintendo`, `joycon_left_or_right_nintendo`, `joycon_pair_nintendo`, `unknown`. + - `gamepad_generic`, `gamepad_nintendo_nes`, `gamepad_nintendo_snes`, `gamepad_nintendo_64`, `gamepad_playstation`, `gamepad_sega_md_3_buttons`, `gamepad_sega_md_6_buttons`, `gamepad_xbox`, `joystick_generic`, `joystick_arcade_no_buttons`, `joystick_arcade_1_button`, `joystick_arcade_2_buttons`, `joystick_arcade_3_buttons`, `joystick_arcade_4_buttons`, `joystick_arcade_5_buttons`, `joystick_arcade_6_buttons`, `keyboard_generic`, `keyboard_and_mouse_generic`, `mouse_generic`, `mouse_amiga`, `lightgun_generic`, `lightgun_nintendo`, `steering_wheel_generic`, `flight_stick_generic`, `spinner_generic`, `trackball_generic`, `wii_remote_nintendo`, `wii_remote_and_nunchuk_nintendo`, `joycon_left_or_right_nintendo`, `joycon_pair_nintendo`, `xbox_kinect`, `unknown`. * `visible` - type: BOOLEAN. - If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. * `zIndex` - type: FLOAT. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index c7eac4929..b170da4bf 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -232,13 +232,13 @@ If you want to create your own portable intallation from scratch or customize th ## Specific notes for macOS -As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. As well many emulators available for download are not codesigned and notarized which requires 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, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under 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. +As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. But emulator support is steadily improving and native M1/ARM releases are also getting more common. One issue though is that some emulators are not codesigned and notarized so macOS refuses to run them by default. You can override the operating system's security settings however, which will work around this problem. Some emulators are also available via the [Homebrew](https://brew.sh) package manager and in many instances ES-DE includes support for these releases using the bundled configuration. -Lack of controller support is a problem though, 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. +Lack of controller support is a bit of a problem on macOS, 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 investigate the macOS support as it seems to differ quite a lot. -ES-DE is available both as an Intel/x86 build and as a native M1 build. If running on an M1 Mac it's possible to launch either M1 or Intel emulators from ES-DE and in some instances it's recommended to go for the Intel versions. The reason is that some emulators are not yet working properly on the M1 architecture, and for RetroArch some cores are only available for the x86 platform. So investigate what makes most sense for your setup. Over time this situation should improve as M1 support matures. +ES-DE is available both as an Intel/x86 build and as a native M1/ARM build. If running on an M1 Mac it's possible to launch either M1 or Intel emulators from ES-DE and it's sometimes recommended to go for the Intel versions. The reason is that some emulators are not yet working properly on the M1 architecture, and for RetroArch some cores are only available for the x86 platform. So investigate what makes most sense for your setup. Over time this situation should improve as M1 support matures. -A macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" is set as enabled or ES-DE will not be able to switch to the emulator window when launching games. 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 unclear if only RetroArch is affected by this issue, at least it has not been observed for any other emulators so far. 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 a game. +One macOS-specific requirement is that the RetroArch setting _Start in Fullscreen mode_ is enabled or ES-DE will not be able to switch to the emulator window when launching games. 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 unclear if only RetroArch is affected by this issue, at least it has not been observed for any other emulators so far. 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 a game. If using an M1 Mac then the AetherSX2 emulator is recommended instead of PCSX2. The first time you launch a RetroArch-emulated game from within ES-DE the operating system will present you with a security option with the following description: @@ -248,6 +248,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_. +By default files and directories starting with a dot are hidden on macOS, so to show the .emulationstation directory in your home directory you need to enable hidden files in Finder. You do this using the keyboard combination Shift + Command + . (a dot). + 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. @@ -735,6 +737,19 @@ For instance `topgunnr.7z` will be expanded to `Top Gunner`. This is required by the TheGamesDB scraper where the expanded filenames are used for game searches. (Screenscraper natively supports searches using the MAME names). It's also quite nice to have the gamelist populated with the expanded game names even before any scraping has taken place. +#### Vintage systems emulated using MAME + +**Bally Astrocade:** + +Place the ROMs in the astrocde directory, the files must have the short MAME names such as _astrobat.zip_ and _conan.zip_. If using MAME standalone then no further setup is required and the games should just launch. But if using the _MAME - Current_ RetroArch core, then a hash file must be added to the RetroArch system directory at this location: + +``` +system/mame/hash/astrocde.xml +``` + +The file is available from the MAME GitHub repository (make sure to save it as a raw file): \ +https://github.com/mamedev/mame/blob/master/hash/astrocde.xml + #### Nintendo Switch The Nintendo Switch emulator Yuzu is distributed as a Snap package, Flatpak package or AppImage on Linux and as a regular installer on Windows. At the moment there is unfortunately no macOS release of this emulator and it's unclear if it can run on BSD Unix. @@ -751,14 +766,26 @@ Apart from the potential difficulty in locating the emulator binary, there are s This section is specific to Windows as Cemu is currently only supported on this operating system. -Cemu works a bit different compared to most other emulators, with games stored in an unpacked format. The content of each game is divided into the three directories _code, content_ and _meta_. +Recently Cemu added support for the .wua archive format which is much easier to use than the unpacked game format. Therefore this is now the recommended approach. But both this and the traditional method of adding unpacked games are covered here. + +.wud and .wux files are also supported, but these two formats are not discussed here as the .wua format is clearly the way to go in the future. + +Method 1, using .wua files: + +Start Cemu and install the game, any updates as well as optional DLCs to the Cemu NAND. After the installation is completed, open the _Title Manager_ from the _Tools_ menu, select your game, right click and select _Convert to compressed Wii U archive (.wua)_ and select your `wiiu` ROMs directory as the target. You can modify the file name if you want to, or keep it at its default value. Press the _Save_ button and the game will be automatically packaged as a .wua file. + +Following this just start ES-DE and the game should be shown as a single entry that can be launched using Cemu. + +Method 2, unpacked games: + +Using this unpacked approach, the content of each game is divided into the three directories _code, content_ and _meta_. The first step is to prepare the target directory in the `wiiu` ROMs directory, for this example we'll go for the game _Super Mario 3D World_. So simply create a directory with this name inside the wiiu folder. It should look something like the following: ``` C:\Users\myusername\ROMs\wiiu\Super Mario 3D World\ ``` -The next step is done inside the emulator user interface. You should install the game, any updates as well as optional DLCs to the Cemu NAND. After the installation is completed, right click on the game and choose _Game directory_. An Explorer window should now open showing the content of the game. Here's the game directory for our example: +The next step is done inside the Cemu user interface. You should install the game, any updates as well as optional DLCs to the Cemu NAND. After the installation is completed, right click on the game and choose _Game directory_. An Explorer window should now open showing the content of the game. Here's the game directory for our example: ``` C:\Games\cemu\mlc01\usr\title\00050000\10145d00\code ``` @@ -1048,6 +1075,78 @@ 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. +### OpenBOR + +The Open Beats of Rage (OpenBOR) game engine is available on Windows and Linux. Unfortunately the macOS ports seems to have been abandoned. + +These games are often but not always distributed together with the game engine as specific engine versions may be required for some games. The setup is slightly different between Windows and Linux so they are described separately here. + +**Windows:** + +There are two different OpenBOR setup methods supported on Windows, either to place the game directories directly inside the ROMs\openbor directory or to place the games somewhere else on the filesystems and create .lnk shortcuts and place these inside the ROMs\openbor directory. + +Let's use the game _Knights & Dragons The Endless Quest_ as an example. When the game archive has been uncompressed it looks like the following: + +``` +~\ROMs\openbor\D&D - K&D - The Endless Quest LNS\ +~\ROMs\openbor\D&D - K&D - The Endless Quest LNS\Logs\ +~\ROMs\openbor\D&D - K&D - The Endless Quest LNS\Paks\ +~\ROMs\openbor\D&D - K&D - The Endless Quest LNS\Saves\ +~\ROMs\openbor\D&D - K&D - The Endless Quest LNS\ScreenShots\ +~\ROMs\openbor\D&D - K&D - The Endless Quest LNS\OpenBOR.exe +``` + +Starting ES-DE with this setup actually works fine, you can enter the game folder and launch the OpenBOR.exe file which will run the game. But to make it a bit tidier you can rename the OpenBOR.exe file to the name of the game, such as: +``` +~\ROMs\openbor\D&D - K&D - The Endless Quest LNS\The Endless Quest.exe +``` + +This will make the game show up with that name inside ES-DE and it will also make it easy to scrape. A further improvement is to use the _directories interpreted as files_ functionality to display the game as a single entry instead of a directory. To accomplish this, simply rename the game directory to the same name as the .exe file, for example: + +``` +~\ROMs\openbor\The Endless Quest.exe\The Endless Quest.exe +``` + +Doing this will make the game show up as if it was a single file inside ES-DE and it can be included in automatic collections, custom collections and so on. + +The second option on Windows is to unpack the game somewhere outside the ROMs directory tree and make a shortcut to the OpenBOR.exe binary. Just right click on this file in Explorer and select _Create shortcut_. You can then rename this .lnk file to the name of the game and move it to the ROMs\openbor directory, for example: + +``` +~\ROMs\openbor\The Endless Quest.lnk +``` + +**Linux:** + +On Linux you need to supply your own game engine binary as few (if any) games are distributed with the Linux release of OpenBOR. Download the .7z archive from the [https://github.com/DCurrent/openbor](https://github.com/DCurrent/openbor) repository. The file you want is _OpenBOR_3.0_6391.AppImage_ which is located inside the LINUX/OpenBOR folder. + +Copy this file to the game directory and make it executable using the command `chmod +x OpenBOR_3.0_6391.AppImage` + +Using the same game example as for the Windows instructions above, the directory structure should look like the following: + +``` +~/ROMs/openbor/D&D - K&D - The Endless Quest LNS/ +~/ROMs/openbor/D&D - K&D - The Endless Quest LNS/Logs/ +~/ROMs/openbor/D&D - K&D - The Endless Quest LNS/Paks/ +~/ROMs/openbor/D&D - K&D - The Endless Quest LNS/Saves/ +~/ROMs/openbor/D&D - K&D - The Endless Quest LNS/ScreenShots/ +~/ROMs/openbor/D&D - K&D - The Endless Quest LNS/OpenBOR_3.0_6391.AppImage +~/ROMs/openbor/D&D - K&D - The Endless Quest LNS/OpenBOR.exe +``` + +You can delete the OpenBOR.exe file since you don't need it, and it's recommended to rename the OpenBOR_3.0_6391.AppImage file to the name of the game, such as: + +``` +~/ROMs/openbor/D&D - K&D - The Endless Quest LNS/The Endless Quest.AppImage +``` + +Starting ES-DE and launching the game should now work fine, but a further improvement is to use the _directories interpreted as files_ functionality to display the game as a single entry instead of a directory. To accomplish this, simply rename the game directory to the same name as the .AppImage file, such as: + +``` +~/ROMs/openbor/The Endless Quest.AppImage/The Endless Quest.AppImage +``` + +Doing this will make the game show up as if it was a single file inside ES-DE and it can be included in automatic collections, custom collections and so on. + ## Scraping Scraping means downloading metadata and game media files (images and videos) for the games in your collection. @@ -2189,7 +2288,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | apple2 | Apple II | _Placeholder_ | | | | | apple2gs | Apple IIGS | _Placeholder_ | | | | | arcade | Arcade | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)** [UMW*],
FinalBurn Neo,
FB Alpha 2012 | Depends | Single archive file following MAME name standard in root folder | -| astrocade | Bally Astrocade | _Placeholder_ | | | | +| astrocde | Bally Astrocade | MAME - Current | MAME **(Standalone)** [UMW*] | | Single archive in root folder | | atari2600 | Atari 2600 | Stella | Stella 2014 | No | Single archive or ROM file in root folder | | atari5200 | Atari 5200 | a5200 | Atari800 | | | | atari7800 | Atari 7800 ProSystem | ProSystem | | | | @@ -2261,7 +2360,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 | _Placeholder_ | | | | +| 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,
DOSBox-SVN,
DOSBox-X **(Standalone)**,
DOSBox Staging **(Standalone)** [UMW*] | No | In separate folder (one folder per game with complete file structure retained) | diff --git a/USERGUIDE.md b/USERGUIDE.md index 9c57659dd..43110bf42 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -230,13 +230,13 @@ If you want to create your own portable intallation from scratch or customize th ## Specific notes for macOS -As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. As well many emulators available for download are not codesigned and notarized which requires 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, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under 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. +As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. But emulator support is steadily improving and native M1/ARM releases are also getting more common. One issue though is that some emulators are not codesigned and notarized so macOS refuses to run them by default. You can override the operating system's security settings however, which will work around this problem. Some emulators are also available via the [Homebrew](https://brew.sh) package manager and in many instances ES-DE includes support for these releases using the bundled configuration. -Lack of controller support is a problem though, 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. +Lack of controller support is a bit of a problem on macOS, 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 investigate the macOS support as it seems to differ quite a lot. -ES-DE is available both as an Intel/x86 build and as a native M1 build. If running on an M1 Mac it's possible to launch either M1 or Intel emulators from ES-DE and in some instances it's recommended to go for the Intel versions. The reason is that some emulators are not yet working properly on the M1 architecture, and for RetroArch some cores are only available for the x86 platform. So investigate what makes most sense for your setup. Over time this situation should improve as M1 support matures. +ES-DE is available both as an Intel/x86 build and as a native M1/ARM build. If running on an M1 Mac it's possible to launch either M1 or Intel emulators from ES-DE and it's sometimes recommended to go for the Intel versions. The reason is that some emulators are not yet working properly on the M1 architecture, and for RetroArch some cores are only available for the x86 platform. So investigate what makes most sense for your setup. Over time this situation should improve as M1 support matures. -A macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" is set as enabled or ES-DE will not be able to switch to the emulator window when launching games. 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 unclear if only RetroArch is affected by this issue, at least it has not been observed for any other emulators so far. 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 a game. +One macOS-specific requirement is that the RetroArch setting _Start in Fullscreen mode_ is enabled or ES-DE will not be able to switch to the emulator window when launching games. 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 unclear if only RetroArch is affected by this issue, at least it has not been observed for any other emulators so far. 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 a game. If using an M1 Mac then the AetherSX2 emulator is recommended instead of PCSX2. The first time you launch a RetroArch-emulated game from within ES-DE the operating system will present you with a security option with the following description: @@ -246,6 +246,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_. +By default files and directories starting with a dot are hidden on macOS, so to show the .emulationstation directory in your home directory you need to enable hidden files in Finder. You do this using the keyboard combination Shift + Command + . (a dot). + 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. @@ -767,14 +769,26 @@ Apart from the potential difficulty in locating the emulator binary, there are s This section is specific to Windows as Cemu is currently only supported on this operating system. -Cemu works a bit different compared to most other emulators, with games stored in an unpacked format. The content of each game is divided into the three directories _code, content_ and _meta_. +Recently Cemu added support for the .wua archive format which is much easier to use than the unpacked game format. Therefore this is now the recommended approach. But both this and the traditional method of adding unpacked games are covered here. + +.wud and .wux files are also supported, but these two formats are not discussed here as the .wua format is clearly the way to go in the future. + +Method 1, using .wua files: + +Start Cemu and install the game, any updates as well as optional DLCs to the Cemu NAND. After the installation is completed, open the _Title Manager_ from the _Tools_ menu, select your game, right click and select _Convert to compressed Wii U archive (.wua)_ and select your `wiiu` ROMs directory as the target. You can modify the file name if you want to, or keep it at its default value. Press the _Save_ button and the game will be automatically packaged as a .wua file. + +Following this just start ES-DE and the game should be shown as a single entry that can be launched using Cemu. + +Method 2, unpacked games: + +Using this unpacked approach, the content of each game is divided into the three directories _code, content_ and _meta_. The first step is to prepare the target directory in the `wiiu` ROMs directory, for this example we'll go for the game _Super Mario 3D World_. So simply create a directory with this name inside the wiiu folder. It should look something like the following: ``` C:\Users\myusername\ROMs\wiiu\Super Mario 3D World\ ``` -The next step is done inside the emulator user interface. You should install the game, any updates as well as optional DLCs to the Cemu NAND. After the installation is completed, right click on the game and choose _Game directory_. An Explorer window should now open showing the content of the game. Here's the game directory for our example: +The next step is done inside the Cemu user interface. You should install the game, any updates as well as optional DLCs to the Cemu NAND. After the installation is completed, right click on the game and choose _Game directory_. An Explorer window should now open showing the content of the game. Here's the game directory for our example: ``` C:\Games\cemu\mlc01\usr\title\00050000\10145d00\code ```