From 6384040d6721eb718382f42fdcd7f2756f1bfc4c Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Mon, 2 May 2022 23:21:23 +0200 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 7 ++++--- INSTALL-DEV.md | 15 ++++++++++++++- USERGUIDE-DEV.md | 41 +++++++++++++++++++++-------------------- 3 files changed, 39 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 89f215aee..570e314f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -150,9 +150,6 @@ v1.2 maintenance release. Support has been added for displaying multi-disc/multi * Made it possible to directly launch files inside directories that are interpreted as files * Added a scraper setting to convert underscores _ to spaces when searching -* The %ROMPATH% variable can now be used inside the es_systems.xml command tag -* Added a %STARTDIR% variable to set the start directory when running an emulator (required by MAME standalone) -* Added an %EMUDIR% variable that expands to the emulator binary directory * If no ScreenScraper video is found when scraping, a fallback will now be done to the normalized (low quality) video * Added support for using the manually downloaded emulators Redream and Ryujinx on Unix * Added Play! standalone as an alternative emulator for the ps2 system @@ -174,6 +171,9 @@ v1.2 maintenance release. Support has been added for displaying multi-disc/multi * Added missing scraper entries for samcoupe and zx81 for TheGamesDB and zmachine for ScreenScraper * neogeocd is now scraped specifically as "Neo Geo CD" instead of the more generic "Neo Geo" * (rbsimple-DE) Made the xbox console graphics slightly darker +* The %ROMPATH% variable can now be used inside the es_systems.xml command tag +* Added a %STARTDIR% variable to set the start directory when running an emulator (required by MAME standalone) +* Added an %EMUDIR% variable that expands to the emulator binary directory * Added a CMake flag to build as Flatpak which prefixes "flatpak-spawn --host" to all launch commands * Added some Flatpak-specific code to work around the sandbox restrictions of this package format * A check is now done on game launch that emulator binaries are actually files or symlinks @@ -184,6 +184,7 @@ v1.2 maintenance release. Support has been added for displaying multi-disc/multi * The MAME standalone emulator couldn't be launched * Using a custom image directory for the slideshow screensaver would hang the application if there was only a single image * On Unix and macOS, staticpaths rules in es_find_rules.xml containing blank spaces would not work +* %ESPATH% variables could not be used in es_systems.xml * Navigating the list of alternative emulators would sometimes lead to an incorrect row positioning * On Windows, the find rule for the Mupen64Plus standalone emulator was not setup correctly diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 2e2984c17..0894d27c8 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -1181,6 +1181,13 @@ Below is an overview of the file layout with various examples. For the command t expanded to the directory of the ES-DE executable. --> "%ESPATH%\RetroArch\retroarch.exe" -L "%ESPATH%\RetroArch\cores\snes9x_libretro.dll" %ROM% + + %HIDEWINDOW% %EMULATOR_MAME% %STARTDIR%=%EMUDIR% -rompath %ROMPATH%\arcade %BASENAME% + + + %EMULATOR_MAME% %STARTDIR%=~/.mame -rompath %ROMPATH%/arcade %BASENAME% + @@ -1215,9 +1222,15 @@ The following variables are expanded for the `command` tag: `%ROMRAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes. +`%ROMPATH%` - Replaced with the path defined in the setting ROMDirectory in es_settings.xml. If combined with a path that contains blankspaces, then it must be surrounded by quotation marks, for example `%ROMPATH%"\Arcade Games"`. Note that the quotation mark must be located before the directory separator in this case. + `%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. -`%EMUPATH%` - Replaced with the path to the emulator binary. This is expanded using either the PATH environment variable of the operating system, or using an absolute emulator path if this has been defined. +`%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. + +`%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. + +`%EMUDIR%` - Replaced with the path to the emulator binary. This is a general purpose variable as opposed to %EMUPATH% which is intended specifically for core locations. `%ESPATH%` - Replaced with the path to the ES-DE binary. Mostly useful for portable emulator installations, for example on a USB memory stick. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index eff723c47..ac89de864 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -537,11 +537,12 @@ The following emulators are supported in AppImage format when using the bundled | _Multiple_ | RetroArch | RetroArch-Linux-x86_64.AppImage | | gba | mGBA | mGBA*.AppImage | | gc | Dolphin | Dolphin_Emulator*.AppImage | +| ps2 | Play! | Play!*.AppImage | | ps3 | RPCS3 | rpcs3*.AppImage | | psx | DuckStation | duckstation-nogui-x64.AppImage | | psx | DuckStation | duckstation-qt-x64.AppImage | -| xbox | xemu | Xemu*.AppImage | | switch | Yuzu | yuzu*.AppImage | +| xbox | xemu | Xemu*.AppImage | | wii | Dolphin | Dolphin_Emulator*.AppImage | RetroArch does not embed any version information into the filename so no wildcard is required. @@ -639,9 +640,9 @@ That's it, start ES-DE and the NES game system should be populated. You can now ### Multiple game files installation -For some systems, there are sometimes (or always) multiple gamefiles per game. Such an example would be the Commodore 64 when multidisk games are being played. For such instances, simply group the files inside folders. +For some systems, there are sometimes (or always) multiple files per game. Such an example would be the Commodore 64 when multidisk games are being played. For such instances, simply group the files inside folders. -The platform name for the Commodore 64 is `c64`, so the following structure would be a possible approach: +The system name for the Commodore 64 is `c64`, so the following structure would be a possible approach: ``` ~/ROMs/c64/Cartridge @@ -2127,10 +2128,10 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | 3do | 3DO | Opera | | | | | 64dd | Nintendo 64DD | Mupen64Plus-Next [UW],
ParaLLEl N64 [M] | ParaLLEl N64 [UW],
Mupen64Plus **(Standalone)** [UMW*],
sixtyforce **(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 | -| amiga1200 | Commodore Amiga 1200 | 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 | -| amigacd32 | Commodore Amiga CD32 | PUAE | | | | +| amiga | Commodore Amiga | PUAE | PUAE 2021 | 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 | PUAE 2021 | 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 | +| amiga1200 | Commodore Amiga 1200 | PUAE | PUAE 2021 | 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 | +| amigacd32 | Commodore Amiga CD32 | PUAE | PUAE 2021 | | | | amstradcpc | Amstrad CPC | Caprice32 | CrocoDS | | | | android | Google Android | _Placeholder_ | | | | | apple2 | Apple II | _Placeholder_ | | | | @@ -2140,7 +2141,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | 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 | | | | -| atari800 | Atari 800 | Atari800 | | | | +| atari800 | Atari 800 | Atari800 | Atari800 **(Standalone)** [UMW*] | No | | | atarijaguar | Atari Jaguar | Virtual Jaguar | | | | | atarijaguarcd | Atari Jaguar CD | Virtual Jaguar | | | | | atarilynx | Atari Lynx | Handy | Beetle Lynx | | | @@ -2150,7 +2151,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | bbcmicro | BBC Micro | _Placeholder_ | | | | | c64 | Commodore 64 | VICE x64sc Accurate | VICE x64 Fast,
VICE x64 SuperCPU,
VICE x128,
Frodo | No | Single disk, tape or cartridge image in root folder and/or multi-disc images in separate folder | | cavestory | Cave Story (NXEngine) | NXEngine | | | | -| cdimono1 | Philips CD-i | _Placeholder_ | | | | +| cdimono1 | Philips CD-i | SAME CDi | CDi 2015 | Yes | Single .bin/.cue pair in root folder | | cdtv | Commodore CDTV | _Placeholder_ | | | | | chailove | ChaiLove Game Engine | ChaiLove | | | | | channelf | Fairchild Channel F | FreeChaF | | | | @@ -2172,11 +2173,11 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | gb | Nintendo Game Boy | SameBoy | Gambatte,
Gearboy,
TGB Dual,
Mesen-S,
bsnes,
mGBA,
mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)** | No | Single archive or ROM file in root folder | | gba | Nintendo Game Boy Advance | mGBA | mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)** [UMW*],
VBA Next,
gpSP | No | Single archive or ROM file in root folder | | gbc | Nintendo Game Boy Color | SameBoy | Gambatte,
Gearboy,
TGB Dual,
Mesen-S,
bsnes,
mGBA,
mGBA **(Standalone)**,
VBA-M,
VBA-M **(Standalone)** | No | Single archive or ROM file in root folder | -| gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)** [UMW*], PrimeHack **(Standalone)** [U] | No | Single ISO file in root folder | -| genesis | Sega Genesis | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm | No | Single archive or ROM file in root folder | +| gc | Nintendo GameCube | Dolphin | Dolphin **(Standalone)** [UMW*], PrimeHack **(Standalone)** [U] | No | Single .iso file in root folder | +| genesis | Sega Genesis | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm,
BlastEm **(Standalone)** [U] | No | Single archive or ROM file in root folder | | gx4000 | Amstrad GX4000 | _Placeholder_ | | | | | intellivision | Mattel Electronics Intellivision | FreeIntv | | | | -| j2me | Java 2 Micro Edition (J2ME) | SquirrelJME | | Yes | Single JAR file in root folder | +| j2me | Java 2 Micro Edition (J2ME) | SquirrelJME | | Yes | Single .jar file in root folder | | kodi | Kodi Home Theatre Software | N/A | | No | | | lutris | Lutris Open Gaming Platform | Lutris application **(Standalone)** [U] | | No | Shell script in root folder | | lutro | Lutro Game Engine | Lutro | | | | @@ -2187,7 +2188,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | mastersystem | Sega Master System | Genesis Plus GX | Genesis Plus GX Wide,
SMS Plus GX,
Gearsystem,
PicoDrive | No | Single archive or ROM file in root folder | | megacd | Sega Mega-CD | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive | | | | megacdjp | Sega Mega-CD [Japan] | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive | | | -| megadrive | Sega Mega Drive | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm | No | Single archive or ROM file in root folder | +| megadrive | Sega Mega Drive | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive,
BlastEm,
BlastEm **(Standalone)** [U] | No | Single archive or ROM file in root folder | | mess | Multi Emulator Super System | MESS 2015 | | | | | moonlight | Moonlight Game Streaming | _Placeholder_ | | | | | moto | Thomson MO/TO Series | Theodore | | | | @@ -2219,12 +2220,12 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | 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],
PCSX2 **(Standalone)** [M] | PCSX2 **(Standalone)** [UW] | Yes | | +| ps2 | Sony PlayStation 2 | PCSX2 [UW],
PCSX2 **(Standalone)** [M] | PCSX2 **(Standalone)** [UW],
Play! **(Standalone)** [UMW*] | Yes (No for Play!) | | | ps3 | Sony PlayStation 3 | RPCS3 **(Standalone)** [UMW*] | | Yes | In separate folder (one folder per game with complete file structure retained, renamed to the .ps3 extension) | | ps4 | Sony PlayStation 4 | _Placeholder_ | | | | -| psp | Sony PlayStation Portable | PPSSPP | PPSSPP **(Standalone)** | No | Single ISO file in root folder | +| psp | Sony PlayStation Portable | PPSSPP | PPSSPP **(Standalone)** | No | Single .iso file in root folder | | psvita | Sony PlayStation Vita | _Placeholder_ | | | | -| psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,
PCSX ReARMed,
SwanStation,
DuckStation@ [UW],
DuckStation **(Standalone)** [UMW*] | Yes | .chd file in root folder for single-disc games, .m3u playlist in root folder for multi-disc games | +| psx | Sony PlayStation | Beetle PSX | Beetle PSX HW,
PCSX ReARMed,
SwanStation,
DuckStation **(Standalone)** [UMW*] | Yes | .chd file in root folder for single-disc games, .m3u playlist in root folder for multi-disc games | | samcoupe | SAM Coupé | SimCoupe | | | | | satellaview | Nintendo Satellaview | Snes9x - Current | Snes9x 2010,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
Mesen-S | | | | saturn | Sega Saturn | Beetle Saturn | Kronos [UW],
YabaSanshiro [UW],
Yabause | | | @@ -2234,10 +2235,10 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | sega32xjp | Sega Super 32X [Japan] | PicoDrive | | No | Single archive or ROM file in root folder | | sega32xna | Sega Genesis 32X [North America] | PicoDrive | | No | Single archive or ROM file in root folder | | segacd | Sega CD | Genesis Plus GX | Genesis Plus GX Wide,
PicoDrive | | | -| sfc | Nintendo SFC (Super Famicom) | Snes9x - Current | Snes9x 2010,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
Beetle Supafaust [UW],
Mesen-S | No | Single archive or ROM file in root folder | +| sfc | Nintendo SFC (Super Famicom) | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)** [UMW*],
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
Beetle Supafaust [UW],
Mesen-S | No | Single archive or ROM file in root folder | | sg-1000 | Sega SG-1000 | Gearsystem | Genesis Plus GX,
Genesis Plus GX Wide,
blueMSX | | | -| snes | Nintendo SNES (Super Nintendo) | Snes9x - Current | Snes9x 2010,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
Beetle Supafaust [UW],
Mesen-S | No | Single archive or ROM file in root folder | -| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
Beetle Supafaust [UW],
Mesen-S | No | Single archive or ROM file in root folder | +| snes | Nintendo SNES (Super Nintendo) | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)** [UMW*],
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
Beetle Supafaust [UW],
Mesen-S | No | Single archive or ROM file in root folder | +| snesna | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current | Snes9x 2010,
Snes9x **(Standalone)** [UMW*],
bsnes,
bsnes-hd,
bsnes-mercury Accuracy,
Beetle Supafaust [UW],
Mesen-S | No | Single archive or ROM file in root folder | | solarus | Solarus Game Engine | _Placeholder_ | | | | | spectravideo | Spectravideo | blueMSX | | | | | steam | Valve Steam | Steam application **(Standalone)** | | No | Shell script/batch file in root folder (and .url files supported on Windows) | @@ -2264,7 +2265,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | | | | | x1 | Sharp X1 | x1 | | | Single archive or ROM file in root folder | | x68000 | Sharp X68000 | PX68k | | | | -| xbox | Microsoft Xbox | xemu **(Standalone)** [UMW*] | | Yes | Single ISO file in root folder | +| xbox | Microsoft Xbox | xemu **(Standalone)** [UMW*] | | Yes | Single .iso file in root folder | | xbox360 | Microsoft Xbox 360 | xenia **(Standalone)** [W*] | | No | | | zmachine | Infocom Z-machine | _Placeholder_ | | | | | zx81 | Sinclair ZX81 | EightyOne | | | |