From e7c33d8f0d24bab77bc483ea48bb1ac19416a3bd Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Tue, 6 Feb 2024 19:03:59 +0100 Subject: [PATCH] Documentation update --- ANDROID.md | 10 +++++----- CHANGELOG.md | 1 + INSTALL-DEV.md | 10 +++++++++- USERGUIDE-DEV.md | 12 +++++++----- 4 files changed, 22 insertions(+), 11 deletions(-) diff --git a/ANDROID.md b/ANDROID.md index 7a41010d0..61f85b894 100644 --- a/ANDROID.md +++ b/ANDROID.md @@ -6,7 +6,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | System name | Full name | Default emulator | Alternative emulators | Needs BIOS | Recommended game setup | | :-------------------- | :--------------------------------------------- | :-------------------------------- | :-------------------------------- | :----------- | :----------------------------------- | -| 3do | 3DO Interactive Multiplayer | Opera | | | | +| 3do | 3DO Interactive Multiplayer | Opera | Real3DOPlayer **(Standalone)** | Yes | | | adam | Coleco Adam | _Placeholder_ | | | | | ags | Adventure Game Studio Game Engine | _Placeholder_ | | | | | amiga | Commodore Amiga | PUAE | PUAE 2021 | Yes | | @@ -65,7 +65,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | fmtowns | Fujitsu FM Towns | _Placeholder_ | | | | | fpinball | Future Pinball | _Placeholder_ | | | | | gamate | Bit Corporation Gamate | _Placeholder_ | | | | -| gameandwatch | Nintendo Game and Watch | Handheld Electronic (GW) | | No | | +| gameandwatch | Nintendo Game and Watch | Multi (MESS) | Handheld Electronic (GW) | No | Single archive or ROM file | | gamecom | Tiger Electronics Game.com | _Placeholder_ | | | | | gamegear | Sega Game Gear | Genesis Plus GX | Genesis Plus GX Wide,
Gearsystem,
SMS Plus GX,
PicoDrive | No | Single archive or ROM file | | gb | Nintendo Game Boy | Gambatte | GBC.emu **(Standalone)**,
SameBoy,
Gearboy,
TGB Dual,
DoubleCherryGB,
Mesen-S,
bsnes,
mGBA,
VBA-M | No | Single archive or ROM file | @@ -79,7 +79,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | j2me | Java 2 Micro Edition (J2ME) | SquirrelJME | | No | Single .jar file | | kodi | Kodi Home Theatre Software | _Placeholder_ | | | | | laserdisc | LaserDisc Games | DirkSimple | | No | | -| lcdgames | LCD Handheld Games | Handheld Electronic (GW) | | No | | +| lcdgames | LCD Handheld Games | Multi (MESS) | Handheld Electronic (GW) | No | Single archive or ROM file | | lowresnx | LowRes NX Fantasy Console | LowRes NX | | No | Single ROM file | | lutris | Lutris Open Gaming Platform | _Placeholder_ | | | | | lutro | Lutro Game Engine | Lutro | | | | @@ -131,11 +131,11 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | plus4 | Commodore Plus/4 | VICE xplus4 | | No | Single archive or image file for tape, cartridge or single-diskette games, .m3u playlist for multi-diskette games | | pokemini | Nintendo Pokémon Mini | PokeMini | | No | | | ports | Ports | ECWolf (Wolfenstein 3D) | NXEngine (Cave Story),
OpenLara (Tomb Raider),
Super Bros War | Yes for ECWolf | | -| ps2 | Sony PlayStation 2 | AetherSX2 **(Standalone)** | | Yes | | +| ps2 | Sony PlayStation 2 | AetherSX2 **(Standalone)** | Play! **(Standalone)** | Yes for AetherSX2 | | | ps3 | Sony PlayStation 3 | _Placeholder_ | | | | | ps4 | Sony PlayStation 4 | _Placeholder_ | | | | | psp | Sony PlayStation Portable | PPSSPP | PPSSPP **(Standalone)** | No | Single disc image file | -| psvita | Sony PlayStation Vita | _Placeholder_ | | | | +| psvita | Sony PlayStation Vita | Vita3K **(Standalone)** | | Yes | | | psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,
PCSX ReARMed,
SwanStation,
DuckStation **(Standalone)** | Yes | .chd file for single-disc games, .m3u playlist for multi-disc games | | pv1000 | Casio PV-1000 | _Placeholder_ | | | | | quake | Quake | TyrQuake | vitaQuake 2,
vitaQuake 2 [Rogue],
vitaQuake 2 [Xatrix],
vitaQuake 2 [Zaero] | No | | diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ad4c99e5..0ab45989f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,7 @@ * Added Mesen standalone as an alternative emulator for the gamegear, mastersystem, multivision and sg-1000 systems on Linux, Unix and Windows * Set Mesen standalone to specifically run in Super Game Boy mode for the sgb system on Linux, Unix and Windows * Added the DoubleCherryGB RetroArch core as an alternative emulator for the gb and gbc systems on Linux, Unix and Windows +* Added the MAME - Current RetroArch core as the default emulator for the gameandwatch and lcdgames systems * Added the melonDS DS RetroArch core as the default emulator for the nds system * (Linux) Added support for the AppImage release of Vita3K * (Linux) Added support for the Flatpak release of puNES diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index dbbe57a4d..614b80ff3 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -1735,6 +1735,14 @@ The es_systems.xml file on Android utilizes variables heavily to implement the _ There are two main ways to pass options to emulators, using _extras_ or using the _data_ URI. There can only be a single data URI but there can be an arbitrary amount of extras. To understand more about the way this works, you can read about the _putExtra()_ and and _setData()_ functions here:\ https://developer.android.com/reference/android/content/Intent +`%EXTRA_` - This passes an _extra_ which contains any additional information that the emulator may support. This is provided as a key/value pair where you define the key name following the literal %EXTRA_ string and terminate it with a % sign and then assign the value using an equal sign. For example %EXTRA_LIBRETRO%=puae_libretro_android.so will pass the extra named _LIBRETRO_ with its value set to _puae_libretro_android.so_. You can pass an unlimited number of extras and you can also use various ROM variables in combination with this as described below. + +`%EXTRAARRAY_` - Defines an array of comma-separated string values following the key name. Only literal strings are supported, so this can't be used in combination with any ROM variables. As commas are used as separator characters, you'll need to escape any comma signs that you want to include in the actual value. For example %EXTRAARRAY_Parameters%=pone,p\\,two,pthree will pass the extra named _Parameters_ with the three separate array entries _pone_, _p,two_ and _pthree_. + +`%EXTRABOOL_` - Sets an extra with a boolean value, i.e. true/1 or false/0. + +`%DATA%` - Sets the data URI value for the intent using an equal sign. This is normally combined with one of the ROM variables. + There are three approaches to passing game ROMs to emulators by using the following variables: `%ROM%` - Replaced with the absolute path to the selected ROM. This is a traditional method to provide the game ROM and its use will likely decrease or go away completely long term as emulators move to more modern methods. @@ -1745,7 +1753,7 @@ https://developer.android.com/guide/topics/providers/document-provider `%ROMPROVIDER%` - This is the most modern approach to passing game ROMs to emulators. It uses the _FileProvider_ API to provide permissions to the file. This means that you don't need to setup the emulator upfront to have access to the directory where the game file is stored, access is instead temporarily granted by ES-DE. You can read more about the FileProvider API here:\ https://developer.android.com/reference/androidx/core/content/FileProvider -The `%ROM%` and `%ROMSAF%` variables can be used with both the `%DATA%` and `%EXTRA_` variables, but `%ROMPROVIDER%` can only be used with the `%DATA%` variable. For the `%DATA%` variable you'll just assign the ROM variable with an equal sign as there can only be a single _setData()_ API call per Intent. For the `%EXTRA_` variable you need to specify a name of the extra and then define it using an equal sign as an arbitrary amount of _putExtra()_ API calls can be used for an Intent. There is also a special `%EXTRABOOL_` variable that specifically passes boolean values (true/false) to emulators that support such arguments. +The `%ROM%` and `%ROMSAF%` variables can be used with both the `%DATA%` and `%EXTRA_` variables, but `%ROMPROVIDER%` can only be used with the `%DATA%` variable. For the `%DATA%` variable you'll just assign the ROM variable with an equal sign as there can only be a single _setData()_ API call per Intent. For the `%EXTRA_` variable you need to specify a name of the extra and then define it using an equal sign as an arbitrary amount of _putExtra()_ API calls can be used for an Intent. Here are some examples to clarify how this works: ``` diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index e00742dc7..0b9e36fc7 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -1770,11 +1770,13 @@ There are two ways to play these games, either via emulation or via simulation. **Method 1, emulation** -Proper emulation is done via the MAME standalone emulator. The games need to be in the MAME format and follow the MAME software list naming conventions, i.e. it will not be possible to run .mgw games with this emulator. The example game _Donkey Kong_ would have the filename `gnw_dkong.zip` and you'll place this file in the `gameandwatch` or `lcdgames` directory. +Proper emulation is done via the MAME - Current RetroArch core or the MAME standalone emulator. The games need to be in the MAME format and follow the MAME software list naming conventions, i.e. it will not be possible to run .mgw games with this emulator. The example game _Donkey Kong_ would have the filename `gnw_dkong.zip` and you'll place this file in the `gameandwatch` or `lcdgames` directory. However the game is only half of what's needed to properly emulate these games as you'll also need the artwork to see an image of the actual physical device when running the game. The artwork would also come in a .zip file with the same name as the game itself, e.g. `gnw_dkong.zip` and it must be located in the MAME artwork directory so it can be found by MAME. -For the artwork location there are two options available in the form of two separate MAME emulator entries, either the default _MAME Local Artwork (Standalone)_ entry or _MAME (Standalone)_. The former will require the artwork files to be placed in a directory inside the `gameandwatch` or `lcdgames` folder, which can be quite convenient as it's then bundled with the game files. Simply create an `artwork` subdirectory and place the files there. The second emulator entry will require the artwork files to be placed in the default MAME artwork directory. This location differs between operating systems and distributions so refer to the MAME documentation on where to find this folder. Here's an example of what _Donkey Kong_ would look like when going for the default option using the `gameandwatch` system: +For the RetroArch core this means it has to be placed in the system directory, specifically in `system/mame/artwork/` + +For MAME standalone there are two options available for the artwork location in the form of two separate MAME emulator entries, either the default _MAME Local Artwork (Standalone)_ entry or _MAME (Standalone)_. The former will require the artwork files to be placed in a directory inside the `gameandwatch` or `lcdgames` folder, which can be quite convenient as it's then bundled with the game files. Simply create an `artwork` subdirectory and place the files there. The second emulator entry will require the artwork files to be placed in the default MAME artwork directory. This location differs between operating systems and distributions so refer to the MAME documentation on where to find this folder. Here's an example of what _Donkey Kong_ would look like when going for the default option using the `gameandwatch` system: ``` ~/ROMs/gameandwatch/gnw_dkong.zip @@ -1783,7 +1785,7 @@ For the artwork location there are two options available in the form of two sepa As the artwork files also come with the .zip file extension they will show up inside ES-DE as if they were game files. So it's recommended to hide the entire artwork directory using the _Hidden_ option in the metadata editor, or alternatively exclude them from the multi-scraper using the _Exclude from multi-scraper_ option. -Be aware that neither ScreenScraper nor TheGamesDB currently support the MAME software list names natively so you'll need to refine the searches or the scraper services are unlikely to return any results at all (or very inaccurate results at best). +Be aware that neither ScreenScraper nor TheGamesDB currently support the MAME software list names natively so you'll need to refine the searches or the scraper services are unlikely to return any results at all (or very inaccurate results at best). However, if you have game files that match the MD5 hashes in the ScreenScraper database, then the games will scrape correctly regardless of their names. **Method 2, simulation** @@ -4008,7 +4010,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | fmtowns | Fujitsu FM Towns | MAME - Current,
MAME **(Standalone)** | Tsugaru **(Standalone)** [LW] | Yes | See the specific _Fujitsu FM Towns_ section elsewhere in this guide | | fpinball | Future Pinball | Future Pinball **(Standalone)** [W] | | No | | | gamate | Bit Corporation Gamate | MAME - Current | MAME **(Standalone)** | Yes | Single archive or ROM file | -| gameandwatch | Nintendo Game and Watch | MAME Local Artwork **(Standalone)** | MAME **(Standalone)**,
Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | +| gameandwatch | Nintendo Game and Watch | MAME - Current | MAME Local Artwork **(Standalone)**,
MAME **(Standalone)**,
Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | | gamecom | Tiger Electronics Game.com | MAME - Current | MAME **(Standalone)** | Yes | Single archive or ROM file | | gamegear | Sega Game Gear | Genesis Plus GX | Genesis Plus GX Wide,
Gearsystem,
SMS Plus GX,
PicoDrive,
Mednafen **(Standalone)**,
Mesen **(Standalone)** [LW],
ares **(Standalone)** | No | Single archive or ROM file | | gb | Nintendo Game Boy | Gambatte | SameBoy,
SameBoy **(Standalone)**,
Gearboy,
Gearboy **(Standalone)** [LW],
TGB Dual,
DoubleCherryGB [LW],
Mesen-S,
Mesen **(Standalone)** [LW],
bsnes,
mGBA,
mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)**,
Mednafen **(Standalone)**,
ares **(Standalone)**,
SkyEmu **(Standalone)** | No | Single archive or ROM file | @@ -4022,7 +4024,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | j2me | Java 2 Micro Edition (J2ME) | SquirrelJME | KEmulator **(Standalone)** [W] | No | Single .jar file | | kodi | Kodi Home Theatre Software | Kodi **(Standalone)** | | No | Shortcut (.desktop/.app/.lnk) file | | laserdisc | LaserDisc Games | Hypseus [Daphne] **(Standalone)** | Hypseus [Singe] **(Standalone)**,
MAME - Current,
MAME **(Standalone)**,
DirkSimple | Depends | See the specific _LaserDisc Games_ section elsewhere in this guide | -| lcdgames | LCD Handheld Games | MAME Local Artwork **(Standalone)** | MAME **(Standalone)**,
Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | +| lcdgames | LCD Handheld Games | MAME - Current | MAME Local Artwork **(Standalone)**,
MAME **(Standalone)**,
Handheld Electronic (GW) | No | See the specific _LCD handheld games_ section elsewhere in this guide | | lowresnx | LowRes NX Fantasy Console | LowRes NX | | No | Single ROM file | | lutris | Lutris Open Gaming Platform | Lutris **(Standalone)** [L] | | No | See the specific _Lutris_ section elsewhere in this guide | | lutro | Lutro Game Engine | Lutro | | | |