diff --git a/ANDROID-DEV.md b/ANDROID-DEV.md index 5296a463a..088450060 100644 --- a/ANDROID-DEV.md +++ b/ANDROID-DEV.md @@ -76,6 +76,91 @@ The following emulators have partial FileProvider access support but are current * M64Plus FZ (the FileProvider interface doesn't work reliably and game launching randomly fails when using it) * PPSSPP (the FileProvider interface doesn't work with .chd files specifically) +## Splitting system directories across multiple storage devices (not recommended) + +While it's possible to split the game system directories across multiple storage devices this is definitely not recommended. First it's tedious to setup, but more importantly it breaks portability for the installation. For instance you can't easily migrate between the different operating systems that ES-DE support and your custom collections will not be portable at all, as they will instead contain absolute paths to your games. + +The way ES-DE works is that you have a defined ROMs directory which corresponds to the %ROMPATH% variable that is used throughout the es_systems.xml file and the custom collections files. For example this is the system configuration for the samcoupe system: +```xml + + samcoupe + MGT SAM Coupé + %ROMPATH%/samcoupe + .dsk .DSK .mgt .MGT .sad .SAD .sbt .SBT .7z .7Z .zip .ZIP + %EMULATOR_SPECCY% %ACTION%=android.intent.action.VIEW %DATA%=%ROMSAF% + samcoupe + samcoupe + +``` + +Here the path tag is using the %ROMPATH% variable to keep it relative to the base ROMs directory as selected via the onboarding configurator when you first installed ES-DE. If you relocate your ROMs directory to a different storage device, or to another device altogether or if you synchronize your games across Android and Linux, macOS or Windows then everything will still work correctly. + +Similarly custom collection files contain the %ROMPATH% variable too, such as this: +``` +%ROMPATH%/amiga/OoopsUp.lha +%ROMPATH%/amiga/PacMania.lha +%ROMPATH%/samcoupe/Manic Miner.zip +%ROMPATH%/samcoupe/Prince of Persia.zip +``` + +This makes your custom collections portable if you move your ROMs directory and you can also transfer the collections between various devices and operating systems while keeping everything working seamlessly. + +If you still insist on relocating some game system directories to another storage device then you need to make custom system configuration entries for them. See the _Game system customization_ section of the [User guide](USERGUIDE.md#game-system-customizations) for details on how this is accomplished. In short you need to create an es_systems.xml file in the ES-DE/custom_systems directory and replace the %ROMPATH% variable with an absolute path for the specific systems you want to relocate. + +You can find the bundled es_systems.xml file for Android here (which contains configuration for all supported systems):\ +https://gitlab.com/es-de/emulationstation-de/-/tree/stable-3.0/resources/systems/android + +Here's an example of a custom es_systems.xml file that relocates the samcoupe system: + +```xml + + + + samcoupe + MGT SAM Coupé + /storage/719F-3A7F/ROMs/samcoupe + .dsk .DSK .mgt .MGT .sad .SAD .sbt .SBT .7z .7Z .zip .ZIP + %EMULATOR_SPECCY% %ACTION%=android.intent.action.VIEW %DATA%=%ROMSAF% + samcoupe + samcoupe + + +``` + +This example points the samcoupe directory to the external storage device /storage/719F-3A7F which may for instance be an SD card. + +Note that doing the opposite, i.e. placing your primary ROMs directory on external storage and relocating a specific system to internal storage requires you to use the /storage/emulated/0 path, you can't use /sdcard in the path tag. + +Here's again an example for the samcoupe system: + +```xml + + + + samcoupe + MGT SAM Coupé + /storage/emulated/0/ROMs/samcoupe + .dsk .DSK .mgt .MGT .sad .SAD .sbt .SBT .7z .7Z .zip .ZIP + %EMULATOR_SPECCY% %ACTION%=android.intent.action.VIEW %DATA%=%ROMSAF% + samcoupe + samcoupe + + +``` + +If going for this configuration, adding samcoupe games to a custom collection would end up with something like the following: + +``` +%ROMPATH%/amiga/OoopsUp.lha +%ROMPATH%/amiga/PacMania.lha +/storage/emulated/0/ROMs/samcoupe/Manic Miner.zip +/storage/emulated/0/ROMs/samcoupe/Prince of Persia.zip +``` + +This is obviously a non-portable collection. + +You can relocate as many systems as you want, you just need to place them all within the systemList tag pairs in ES-DE/custom_systems/es_systems.xml. + ## Issues with the Ayn Odin 2 There are two serious issues that seem to be specific to the Ayn Odin 2, although it remains to be seen whether the problem exists also on other devices. diff --git a/ANDROID.md b/ANDROID.md index 6b9e11eb7..5730044a0 100644 --- a/ANDROID.md +++ b/ANDROID.md @@ -76,6 +76,91 @@ The following emulators have partial FileProvider access support but are current * M64Plus FZ (the FileProvider interface doesn't work reliably and game launching randomly fails when using it) * PPSSPP (the FileProvider interface doesn't work with .chd files specifically) +## Splitting system directories across multiple storage devices (not recommended) + +While it's possible to split the game system directories across multiple storage devices this is definitely not recommended. First it's tedious to setup, but more importantly it breaks portability for the installation. For instance you can't easily migrate between the different operating systems that ES-DE support and your custom collections will not be portable at all, as they will instead contain absolute paths to your games. + +The way ES-DE works is that you have a defined ROMs directory which corresponds to the %ROMPATH% variable that is used throughout the es_systems.xml file and the custom collections files. For example this is the system configuration for the samcoupe system: +```xml + + samcoupe + MGT SAM Coupé + %ROMPATH%/samcoupe + .dsk .DSK .mgt .MGT .sad .SAD .sbt .SBT .7z .7Z .zip .ZIP + %EMULATOR_SPECCY% %ACTION%=android.intent.action.VIEW %DATA%=%ROMSAF% + samcoupe + samcoupe + +``` + +Here the path tag is using the %ROMPATH% variable to keep it relative to the base ROMs directory as selected via the onboarding configurator when you first installed ES-DE. If you relocate your ROMs directory to a different storage device, or to another device altogether or if you synchronize your games across Android and Linux, macOS or Windows then everything will still work correctly. + +Similarly custom collection files contain the %ROMPATH% variable too, such as this: +``` +%ROMPATH%/amiga/OoopsUp.lha +%ROMPATH%/amiga/PacMania.lha +%ROMPATH%/samcoupe/Manic Miner.zip +%ROMPATH%/samcoupe/Prince of Persia.zip +``` + +This makes your custom collections portable if you move your ROMs directory and you can also transfer the collections between various devices and operating systems while keeping everything working seamlessly. + +If you still insist on relocating some game system directories to another storage device then you need to make custom system configuration entries for them. See the _Game system customization_ section of the [User guide](USERGUIDE.md#game-system-customizations) for details on how this is accomplished. In short you need to create an es_systems.xml file in the ES-DE/custom_systems directory and replace the %ROMPATH% variable with an absolute path for the specific systems you want to relocate. + +You can find the bundled es_systems.xml file for Android here (which contains configuration for all supported systems):\ +https://gitlab.com/es-de/emulationstation-de/-/tree/stable-3.0/resources/systems/android + +Here's an example of a custom es_systems.xml file that relocates the samcoupe system: + +```xml + + + + samcoupe + MGT SAM Coupé + /storage/719F-3A7F/ROMs/samcoupe + .dsk .DSK .mgt .MGT .sad .SAD .sbt .SBT .7z .7Z .zip .ZIP + %EMULATOR_SPECCY% %ACTION%=android.intent.action.VIEW %DATA%=%ROMSAF% + samcoupe + samcoupe + + +``` + +This example points the samcoupe directory to the external storage device /storage/719F-3A7F which may for instance be an SD card. + +Note that doing the opposite, i.e. placing your primary ROMs directory on external storage and relocating a specific system to internal storage requires you to use the /storage/emulated/0 path, you can't use /sdcard in the path tag. + +Here's again an example for the samcoupe system: + +```xml + + + + samcoupe + MGT SAM Coupé + /storage/emulated/0/ROMs/samcoupe + .dsk .DSK .mgt .MGT .sad .SAD .sbt .SBT .7z .7Z .zip .ZIP + %EMULATOR_SPECCY% %ACTION%=android.intent.action.VIEW %DATA%=%ROMSAF% + samcoupe + samcoupe + + +``` + +If going for this configuration, adding samcoupe games to a custom collection would end up with something like the following: + +``` +%ROMPATH%/amiga/OoopsUp.lha +%ROMPATH%/amiga/PacMania.lha +/storage/emulated/0/ROMs/samcoupe/Manic Miner.zip +/storage/emulated/0/ROMs/samcoupe/Prince of Persia.zip +``` + +This is obviously a non-portable collection. + +You can relocate as many systems as you want, you just need to place them all within the systemList tag pairs in ES-DE/custom_systems/es_systems.xml. + ## Issues with the Ayn Odin 2 There are two serious issues that seem to be specific to the Ayn Odin 2, although it remains to be seen whether the problem exists also on other devices. diff --git a/FAQ-ANDROID.md b/FAQ-ANDROID.md index 96c74fea4..7c9e3a1e2 100644 --- a/FAQ-ANDROID.md +++ b/FAQ-ANDROID.md @@ -20,7 +20,7 @@ That is a question for Google. They are have done everything in their power to o ## How do I update ES-DE when there is a new release -When a new release is available you will be sent a download link to the email address you used to sign up for Patreon, and we will post it directly on Patreon as well. You can use that link to download the latest version, sideload it on your device and then update. We will explore other options to make this easier in the future. +When a new release is available you will be sent a download link to the email address you used to sign up for Patreon, and we will post it directly on Patreon as well. You can use that link to download the latest version, sideload it on your device and then update. All your settings and data will be retained when you apply the update. ## Can I use ES-DE on more than a single Android device or do I need to buy it multiple times? @@ -49,6 +49,10 @@ Not at the moment. Although there is an _android_ system in ES-DE it's not in us See the _Supported game systems_ section at the bottom of the [Android documentation](ANDROID.md#supported-game-systems) where there's a table listing all supported systems/platforms and emulators. +## Can I split my game system directories across multiple storage devices? + +Yes but this is not recommended. It's tedious to setup and not how ES-DE is intended to be used. If you still insist on doing it you can read the _Splitting system directories across multiple storage devices (not recommended)_ section in the [Android documentation](ANDROID.md#splitting-system-directories-across-multiple-storage-devices-not-recommended). + ## When I launch a game using RetroArch I just see a black screen, what is wrong? RetroArch on Android is very unforgiving, if you haven't installed the necessary core or BIOS files it's a high chance that you just see a black screen and it will hang there, possibly until you kill it. And due to the security model in Android it's not possible for ES-DE to check if a core is actually installed prior to attempting to launch RetroArch (on Linux, macOS and Windows a popup is shown if the core file is missing and the game is never actually launched in this case).