Documentation update

This commit is contained in:
Leon Styhre 2024-03-11 18:47:56 +01:00
parent 5af4b10fb2
commit ae85d2f537
6 changed files with 44 additions and 75 deletions

View file

@ -41,18 +41,22 @@ Almost all files saved and used by ES-DE are kept in the shared storage on eithe
## Emulation on Android in general
There are some challenges with emulation on Android. Some emulators on the Google Play store have not been updated for a long time, or like in the case with RetroArch they are crippled to comply with Google's rules and policies. And some emulators are not available on the Play store at all. For these reasons you will need to sideload some manually downloaded APKs for a good emulation setup. There is a section later in this document describing the best place to get hold of each supported emulator.
There are a few challenges with emulation on Android. Some emulators on the Google Play store have not been updated for a long time, and some emulators are not available on the Play store at all. For these reasons you will need to sideload some manually downloaded APKs for a good emulation setup. There is a section later in this document describing the best place to get hold of each supported emulator.
Thankfully sideloading emulators is not very difficult to do, the exact producedure for how to install APKs manually is not covered here but there are many resources available online on how to accomplish this.
Thankfully sideloading emulators is easy to do, the exact producedure for how to install APKs manually is not covered here but there are many resources available online on how to accomplish this.
There is also the [F-Droid](https://f-droid.org/) app store as an alternative to Google Play, and this service contains a couple of emulators that are not present on the Play store, or that are present there but haven't been updated for a very long time.
A number of emulators support the [FileProvider](https://developer.android.com/reference/androidx/core/content/FileProvider) API which makes it possible for ES-DE to temporarily provide storage access to the game file on launch. This means that no access permission needs to be setup in the emulator upfront. This is however only usable for single files, so for systems that support multi-file games such as disc-based games in .bin/.cue format SAF URIs are used instead. For those emulators you will therefore generally need to manually provide scoped storage access to each game system directory. Note that it's not supported to give access to the root of the entire ROM directory for emulators that use scoped storage, it has to be for the specific system. For instance `/storage/emulated/0/ROMs/n64` rather than `/storage/emulated/0/ROMs`.
A number of emulators support the [FileProvider](https://developer.android.com/reference/androidx/core/content/FileProvider) API which makes it possible for ES-DE to temporarily provide storage access to the game file on launch. This means that most of the time no access permission needs to be setup in the emulator upfront. Access can however only be passed for single files, so for systems that support multi-file games such as disc-based games in .bin/.cue format SAF URIs are often used instead. For those emulators you will therefore generally need to manually provide scoped storage access to each game system directory. Note that it's not supported to give access to the root of the entire ROM directory for emulators that use scoped storage, it has to be for the specific system. For instance `/storage/emulated/0/ROMs/n64` rather than `/storage/emulated/0/ROMs`.
Adding to the FileProvider API confusion is the fact that some emulators will only launch games when using this API even though they need to have scoped storage access setup within the emulator upfront. FPseNG and FPse are two examples of this. So there is unfortunately no definitive rule regarding the use of the FileProvider API, it all depends on how the emulator has implemented the functionality.
Some emulators like RetroArch are still using an older storage access method and for those emulators this is not something you need to consider.
The following emulators are configured for FileProvider access:
* 2600.emu
* FPseNG (still needs scoped storage to be setup in emulator)
* FPse (still needs scoped storage to be setup in emulator)
* GBA.emu
* GBC.emu
* Lynx.emu
@ -65,16 +69,7 @@ The following emulators are configured for FileProvider access:
* Ruffle
* Swan.emu
Some of these emulators still require BIOS files, so not all of them will be completely free from manual configuration.
The following emulators have partial FileProvider access support but are currently not configured for that in ES-DE:
* C64.emu - doesn't work with multi-file games
* Dolphin - doesn't work with multi-file games
* M64Plus FZ - the FileProvider interface doesn't work reliably and game launching randomly fails when using it
* PCE.emu - doesn't work with multi-file games for the pcenginecd and tg-cd systems
* Play! - doesn't work with multi-file games
* PPSSPP - doesn't work with multi-file games and the FileProvider interface doesn't work with .chd files specifically
* Saturn.emu - doesn't work with multi-file games
Some of these emulators require BIOS files, so they still need to be configured before they can be used with ES-DE.
## Splitting system directories across multiple storage devices
@ -461,6 +456,7 @@ This is clearly not a complete list of Android devices, but rather those we know
| Retroid | Pocket 4 Pro | 13 | Yes | None | |
| Samsung | Galaxy Note 20 | 13 | No | Fails at configurator/onboarding | Has a non-standard app permission screen, possibly this breaks the configurator |
| Samsung | Galaxy S10 | 12 | Yes | None | |
| Samsung | Galaxy S22 Ultra | 14 | Yes | None | |
| Samsung | Galaxy S24 Ultra | 14 | Yes | None | |
| Wiko | Voix | 12 | No | Fails at configurator/onboarding | Probably a bug in the firmware/OS image as a libc system call fails |
| Xiaomi | Pad 5 | 13 | Yes | None | |

View file

@ -41,18 +41,22 @@ Almost all files saved and used by ES-DE are kept in the shared storage on eithe
## Emulation on Android in general
There are some challenges with emulation on Android. Some emulators on the Google Play store have not been updated for a long time, or like in the case with RetroArch they are crippled to comply with Google's rules and policies. And some emulators are not available on the Play store at all. For these reasons you will need to sideload some manually downloaded APKs for a good emulation setup. There is a section later in this document describing the best place to get hold of each supported emulator.
There are a few challenges with emulation on Android. Some emulators on the Google Play store have not been updated for a long time, and some emulators are not available on the Play store at all. For these reasons you will need to sideload some manually downloaded APKs for a good emulation setup. There is a section later in this document describing the best place to get hold of each supported emulator.
Thankfully sideloading emulators is not very difficult to do, the exact producedure for how to install APKs manually is not covered here but there are many resources available online on how to accomplish this.
Thankfully sideloading emulators is easy to do, the exact producedure for how to install APKs manually is not covered here but there are many resources available online on how to accomplish this.
There is also the [F-Droid](https://f-droid.org/) app store as an alternative to Google Play, and this service contains a couple of emulators that are not present on the Play store, or that are present there but haven't been updated for a very long time.
A number of emulators support the [FileProvider](https://developer.android.com/reference/androidx/core/content/FileProvider) API which makes it possible for ES-DE to temporarily provide storage access to the game ROMs on launch. This means that no access permission needs to be setup in the emulator upfront. For those emulators which do not support the FileProvider API, you will generally need to manually provide scoped storage access to each game system directory. Note that it's not supported to give access to the root of the entire ROM directory for emulators that use scoped storage, it has to be for the specific system. For instance `/storage/emulated/0/ROMs/n64` rather than `/storage/emulated/0/ROMs`.
A number of emulators support the [FileProvider](https://developer.android.com/reference/androidx/core/content/FileProvider) API which makes it possible for ES-DE to temporarily provide storage access to the game file on launch. This means that most of the time no access permission needs to be setup in the emulator upfront. Access can however only be passed for single files, so for systems that support multi-file games such as disc-based games in .bin/.cue format SAF URIs are often used instead. For those emulators you will therefore generally need to manually provide scoped storage access to each game system directory. Note that it's not supported to give access to the root of the entire ROM directory for emulators that use scoped storage, it has to be for the specific system. For instance `/storage/emulated/0/ROMs/n64` rather than `/storage/emulated/0/ROMs`.
Adding to the FileProvider API confusion is the fact that some emulators will only launch games when using this API even though they need to have scoped storage access setup within the emulator upfront. FPseNG and FPse are two examples of this. So there is unfortunately no definitive rule regarding the use of the FileProvider API, it all depends on how the emulator has implemented the functionality.
Some emulators like RetroArch are still using an older storage access method and for those emulators this is not something you need to consider.
The following emulators are configured for FileProvider access:
* 2600.emu
* FPseNG (still needs scoped storage to be setup in emulator)
* FPse (still needs scoped storage to be setup in emulator)
* C64.emu
* GBA.emu
* GBC.emu
@ -68,12 +72,7 @@ The following emulators are configured for FileProvider access:
* Saturn.emu
* Swan.emu
Some of these emulators still require BIOS files, so not all of them will be completely free from manual configuration.
The following emulators have partial FileProvider access support but are currently not configured for that in ES-DE:
* Dolphin (the FileProvider interface is broken on some devices)
* 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)
Some of these emulators require BIOS files, so they still need to be configured before they can be used with ES-DE.
## Splitting system directories across multiple storage devices
@ -451,6 +450,7 @@ This is clearly not a complete list of Android devices, but rather those we know
| Retroid | Pocket 4 Pro | 13 | Yes | None | |
| Samsung | Galaxy Note 20 | 13 | No | Fails at configurator/onboarding | Has a non-standard app permission screen, possibly this breaks the configurator |
| Samsung | Galaxy S10 | 12 | Yes | None | |
| Samsung | Galaxy S22 Ultra | 14 | Yes | None | |
| Samsung | Galaxy S24 Ultra | 14 | Yes | None | |
| Wiko | Voix | 12 | No | Fails at configurator/onboarding | Probably a bug in the firmware/OS image as a libc system call fails |
| Xiaomi | Pad 5 | 13 | Yes | None | |

View file

@ -1,31 +0,0 @@
# ES-DE (EmulationStation Desktop Edition) - Contributing
### Help needed
**For the time being I'm not working that actively on the project so requests for help are currently suspended since I don't have time to train and collaborate with other people.**
If you are experienced with developing cross-platform client applications in C++ then ES-DE could be an interesting project for you! Although the application does not have a huge codebase, it's fairly complex as it covers many different areas. To work on the project you need to be able to test your code on Linux, macOS and Windows.
Merge requests are only accepted from project members so if you would like to contribute to ES-DE then please get in touch and we can discuss what you would like to work on. But please only consider joining if you intend to be contributing long term as the project is quite large in scope and to train someone to be a team member is a substantial time investment.
Development is tracked using a Kanban board which is publicly visible at the project's GitLab site:
[https://gitlab.com/es-de/emulationstation-de/-/boards](https://gitlab.com/es-de/emulationstation-de/-/boards)
Development takes place in the master branch, and bug fixes/point releases are handled in the stable branches (only the latest stable version is maintained).
### Coding style
Code formatting is applied automatically using clang-format, so to understand the exact formatting rules refer to the .clang-format file in the root of the ES-DE repository. You can read in [INSTALL.md](INSTALL.md#using-clang-format-for-automatic-code-formatting) how clang-format is installed and used.
But as clang-format won't change actual code content or fix all code style choices, here are some additional key points:
* Always write comments in C++ style, i.e. `//` instead of `/* */`
* Comments should be proper sentences, starting with a capital letter and ending with a dot
* Use C++ and not C, for example `static_cast<int>(someFloatVariable)` instead of `(int)someFloatVariable`
* Always declare one variable per line, never combine multiple declarations of the same type
* Name member variables starting with an `m` such as `mMyMemberVariable` and name static variables starting with an `s` such as `sMyStaticVariable`
* Use braced initializations when possible, e.g. `float myFloat {1.5f}` as this is the safest way to do it
* Short function definitions can be placed in either the .h or .cpp file depending on situation and context
* Try to be coherent with the existing codebase regarding names, structure etc., it should not be obvious that different persons wrote different sections of the code
* For the rest, check the code and have fun :)

View file

@ -1767,7 +1767,7 @@ There are three approaches to passing game ROMs to emulators by using the follow
`%ROMSAF%` - Replaced with an Android Storage Access Framework (SAF) document URI which always starts with the _content://com.android.externalstorage.documents/_ string. You can read more about the SAF here:\
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:\
`%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 generally 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. This will however only work for games that consist of a single file, for multi-file games such as .cue/.bin and similar %ROMSAF% has to be used instead. Adding to the confusion is however the fact that some emulators like FPseNG and FPse can only be launched using %ROMPROVIDER% even though you need to setup scoped storage access in the emulator upfront. So there are unfortunately no definitive rules regarding the use of %ROMPROVIDER%, it all depends on how the emulator has implemented the functionality. 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.
@ -1799,14 +1799,15 @@ Here's an example es_systems.xml file for Android:
<!-- This is the ES-DE game systems configuration file for Android -->
<systemList>
<system>
<name>gc</name>
<fullname>Nintendo GameCube</fullname>
<path>%ROMPATH%/gc</path>
<extension>.ciso .CISO .dff .DFF .dol .DOL .elf .ELF .gcm .GCM .gcz .GCZ .iso .ISO .json .JSON .m3u .M3U .rvz .RVZ .tgc .TGC .wad .WAD .wbfs .WBFS .wia .WIA .7z .7Z .zip .ZIP</extension>
<command label="Dolphin">%EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=/data/data/%ANDROIDPACKAGE%/cores/dolphin_libretro_android.so %EXTRA_ROM%=%ROM%</command>
<command label="Dolphin (Standalone)">%EMULATOR_DOLPHIN% %ACTION%=android.intent.action.MAIN %DATA%=%ROMPROVIDER%</command>
<platform>gc</platform>
<theme>gc</theme>
<name>atari2600</name>
<fullname>Atari 2600</fullname>
<path>%ROMPATH%/atari2600</path>
<extension>.a26 .A26 .bin .BIN .7z .7Z .zip .ZIP</extension>
<command label="Stella">%EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=stella_libretro_android.so %EXTRA_ROM%=%ROM%</command>
<command label="Stella 2014">%EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=stella2014_libretro_android.so %EXTRA_ROM%=%ROM%</command>
<command label="2600.emu (Standalone)">%EMULATOR_2600-EMU% %DATA%=%ROMPROVIDER%</command>
<platform>atari2600</platform>
<theme>atari2600</theme>
</system>
<system>
<name>n3ds</name>
@ -1814,8 +1815,10 @@ Here's an example es_systems.xml file for Android:
<path>%ROMPATH%/n3ds</path>
<extension>.3ds .3DS .3dsx .3DSX .app .APP .axf .AXF .cci .CCI .cxi .CXI .elf .ELF .7z .7Z .zip .ZIP</extension>
<command label="Citra">%EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=/data/data/%ANDROIDPACKAGE%/cores/citra_libretro_android.so %EXTRA_ROM%=%ROM%</command>
<command label="Citra (Standalone)">%EMULATOR_CITRA% %ACTIVITY_NO_HISTORY% %EXTRA_SelectedGame%=%ROMSAF%</command>
<command label="Citra (Standalone)">%EMULATOR_CITRA% %ACTIVITY_CLEAR_TASK% %ACTIVITY_CLEAR_TOP% %DATA%=%ROMSAF%</command>
<command label="Citra Canary (Standalone)">%EMULATOR_CITRA-CANARY% %ACTIVITY_CLEAR_TASK% %ACTIVITY_CLEAR_TOP% %DATA%=%ROMSAF%</command>
<command label="Citra MMJ (Standalone)">%EMULATOR_CITRA-MMJ% %EXTRA_GamePath%=%ROM%</command>
<command label="Panda3DS (Standalone)">%EMULATOR_PANDA3DS% %DATA%=%ROMPROVIDER%</command>
<platform>n3ds</platform>
<theme>n3ds</theme>
</system>

View file

@ -1765,7 +1765,7 @@ There are three approaches to passing game ROMs to emulators by using the follow
`%ROMSAF%` - Replaced with an Android Storage Access Framework (SAF) document URI which always starts with the _content://com.android.externalstorage.documents/_ string. You can read more about the SAF here:\
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:\
`%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 generally 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. This will however only work for games that consist of a single file, for multi-file games such as .cue/.bin and similar %ROMSAF% has to be used instead. Adding to the confusion is however the fact that some emulators like FPseNG and FPse can only be launched using %ROMPROVIDER% even though you need to setup scoped storage access in the emulator upfront. So there are unfortunately no definitive rules regarding the use of %ROMPROVIDER%, it all depends on how the emulator has implemented the functionality. 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.
@ -1797,14 +1797,15 @@ Here's an example es_systems.xml file for Android:
<!-- This is the ES-DE game systems configuration file for Android -->
<systemList>
<system>
<name>gc</name>
<fullname>Nintendo GameCube</fullname>
<path>%ROMPATH%/gc</path>
<extension>.ciso .CISO .dff .DFF .dol .DOL .elf .ELF .gcm .GCM .gcz .GCZ .iso .ISO .json .JSON .m3u .M3U .rvz .RVZ .tgc .TGC .wad .WAD .wbfs .WBFS .wia .WIA .7z .7Z .zip .ZIP</extension>
<command label="Dolphin">%EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=/data/data/%ANDROIDPACKAGE%/cores/dolphin_libretro_android.so %EXTRA_ROM%=%ROM%</command>
<command label="Dolphin (Standalone)">%EMULATOR_DOLPHIN% %ACTION%=android.intent.action.MAIN %DATA%=%ROMPROVIDER%</command>
<platform>gc</platform>
<theme>gc</theme>
<name>atari2600</name>
<fullname>Atari 2600</fullname>
<path>%ROMPATH%/atari2600</path>
<extension>.a26 .A26 .bin .BIN .7z .7Z .zip .ZIP</extension>
<command label="Stella">%EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=stella_libretro_android.so %EXTRA_ROM%=%ROM%</command>
<command label="Stella 2014">%EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=stella2014_libretro_android.so %EXTRA_ROM%=%ROM%</command>
<command label="2600.emu (Standalone)">%EMULATOR_2600-EMU% %DATA%=%ROMPROVIDER%</command>
<platform>atari2600</platform>
<theme>atari2600</theme>
</system>
<system>
<name>n3ds</name>
@ -1812,8 +1813,10 @@ Here's an example es_systems.xml file for Android:
<path>%ROMPATH%/n3ds</path>
<extension>.3ds .3DS .3dsx .3DSX .app .APP .axf .AXF .cci .CCI .cxi .CXI .elf .ELF .7z .7Z .zip .ZIP</extension>
<command label="Citra">%EMULATOR_RETROARCH% %EXTRA_CONFIGFILE%=/storage/emulated/0/Android/data/%ANDROIDPACKAGE%/files/retroarch.cfg %EXTRA_LIBRETRO%=/data/data/%ANDROIDPACKAGE%/cores/citra_libretro_android.so %EXTRA_ROM%=%ROM%</command>
<command label="Citra (Standalone)">%EMULATOR_CITRA% %ACTIVITY_NO_HISTORY% %EXTRA_SelectedGame%=%ROMSAF%</command>
<command label="Citra (Standalone)">%EMULATOR_CITRA% %ACTIVITY_CLEAR_TASK% %ACTIVITY_CLEAR_TOP% %DATA%=%ROMSAF%</command>
<command label="Citra Canary (Standalone)">%EMULATOR_CITRA-CANARY% %ACTIVITY_CLEAR_TASK% %ACTIVITY_CLEAR_TOP% %DATA%=%ROMSAF%</command>
<command label="Citra MMJ (Standalone)">%EMULATOR_CITRA-MMJ% %EXTRA_GamePath%=%ROM%</command>
<command label="Panda3DS (Standalone)">%EMULATOR_PANDA3DS% %DATA%=%ROMPROVIDER%</command>
<platform>n3ds</platform>
<theme>n3ds</theme>
</system>

View file

@ -38,8 +38,6 @@ If you're using a Raspberry Pi or if you run FreeBSD, NetBSD or OpenBSD then you
[ROADMAP.md](ROADMAP.md) - List of major features planned to be added in the future
[CONTRIBUTING.md](CONTRIBUTING.md) - Information on how to contribute to the project
[CREDITS.md](CREDITS.md) - An attempt to credit the individuals and projects which made ES-DE possible
## Some feature highlights