Changes after review #2:

- read retroarch_dbname from peas.json instead from platforms_idmap.csv
- config.ini parameter fixed to accept -e from CLI as raExtra=
- always write PNG for cover/boxart, screenshot and wheel/logo, by using a compositor artwork file
- change "path" in target JSON from / to \\ for Windows
- display of Textures in CLI summary output hidden for frontend RA
- doc FRONTENDS,md updated
- fixed unit tests
- marked further FIXMEs in retroarch.cpp

Author: Gemba

docs/CLIHELP.md

@@ -84,12 +84,14 @@ This sets the extra command (or emulator command) for some frontends.
 
 !!! info
 
-    This option is applicable _only_ when using the `-f attractmode` or the `-f pegasus` option.
+    This option is applicable _only_ when using the `-f attractmode`, the `-f pegasus` or the `-f retroarch` option.
 
 When using `-f attractmode` it is **required** to set the _emulator_ to be used when generating the `attractmode` game list. On RetroPie the emulator name is mostly the same as the platform. Consider setting this in [`config.ini`](CONFIGINI.md#emulator) instead.
 
 The extra command can **optionally** be used with `-f pegasus` to set the launch command used by the Pegasus game list. On RetroPie this defaults to the RetroPie launch command which works with RetroPie, if this parameter is unset. Consider setting this in [`config.ini`](CONFIGINI.md#launch) instead.
 
+The extra command can **optionally** be used with `-f retroarch` with `-e "<CORE_PATH>;<CORE_NAME>"` to set a default core (path,name) pair for the playlist. Consider setting this in [`config.ini`](CONFIGINI.md#emulator) instead.
+
 **Example(s)**
 
 ```

docs/CONFIGINI.md

@@ -121,6 +121,7 @@ This is an alphabetical index of all configuration options their usage level and
 | [onlyMissing](CONFIGINI.md#onlymissing)                     | Advanced       |    Y     |       Y        |                |       Y       |
 | [platform](CONFIGINI.md#platform)                           | Basic          |    Y     |                |                |               |
 | [pretend](CONFIGINI.md#pretend)                             | Basic          |    Y     |       Y        |                |               |
+| [raExtra](CONFIGINI.md#raextra)                             | Advanced       |          |       Y        |       Y        |               |
 | [region](CONFIGINI.md#region)                               | Basic          |    Y     |       Y        |                |               |
 | [regionPrios](CONFIGINI.md#regionprios)                     | Expert         |    Y     |       Y        |                |               |
 | [relativePaths](CONFIGINI.md#relativepaths)                 | Basic          |    Y     |       Y        |                |               |
@@ -460,6 +461,15 @@ Allowed in sections: `[main]`, `[<PLATFORM>]`, `[<FRONTEND>]`
 
 ---
 
+#### raExtra
+
+This option is _only_ applicable when also setting the `frontend="retroarch"` option. With this setting you can define a default core (path,name) pair for the playlist.
+
+Default value: unset  
+Allowed in sections: `[<PLATFORM>]`, `[retroarch]`
+
+---
+
 #### videos
 
 By default Skyscraper does not scrape and cache video resources because of the significant disk space required to save them. You can enable videos using this option. If your frontend supports video display also explicitly set this option to true. See also the option to [symlink video files](#symlink) instead of copying, if space is a premium.

docs/FRONTENDS.md

@@ -25,7 +25,7 @@ Skyscraper will preserve the following metadata when re-generating a game list f
 
     Folder data is not cached by Skyscraper, thus if you delete your `gamelist.xml`, Skyscraper cannot restore the edited folder elements from cache.
 
-Automatic addition of folder elements if [`addFolder`](CONFIGINI.md#addfolders) is true:
+Automatic addition of folder elements if [`addFolder`](CONFIGINI.md#addfolders) is true:  
 If at least one ROM is within a subfolder and this subfolder is not yet part of the `gamelist.xml` file, it will be added with two mandatory subelements:
 
 -  `<path/>` reflects the relative subpath from the system folder and
@@ -81,7 +81,7 @@ files into the `downloaded_media` folder (e.g.
 `~/ES-DE/downloaded_media/<PLATFORM>/screenshots/` for screenshots) from where
 ES-DE will pick them up. ES-DE does not support textures currently. Any manual
 or fanart data present in the cache will be put automagically into
-`~/ES-DE/downloaded_media/<PLATFORM>` where ES-DE will load it.
+`~/ES-DE/downloaded_media/<PLATFORM>` where ES-DE will load it.  
 This frontend automatically enables the output of backcovers, fanart and manuals
 during gamelist creation, whenever cached data is present for a game.
 
@@ -116,7 +116,7 @@ Over time the fork of EmulationStation in Batocera has diverted stark from the
 initial EmulationStation. Thus, the gamelist format is somewhat different, but
 the textual scraping elements are still the same. Most notably Batocera
 EmulationStation stores a lot of additional information in the gamelist, and the
-set of information may differ for each game.
+set of information may differ for each game.  
 Skyscraper aims to cover the most frequent used elements for scraping, currently
 fanarts, manuals and videos. See the [scraping
 modules](SCRAPINGMODULES.md#capabilities-of-scrapers) for support of these
@@ -143,7 +143,7 @@ every `<PLATFORM>` you scrape.
 -   Default media file location: `/userdata/roms/<PLATFORM>/{images,videos,manuals}`
 
 If you set a game list location and do not specifiy the ROM folder (input
-folder) and media folder, then these are set relatively to the game list folder.
+folder) and media folder, then these are set relatively to the game list folder.  
 This frontend automatically enables the output of backcovers, fanart and manuals
 whenever cached data is present for a game.
 
@@ -217,7 +217,7 @@ Windows desktop users can use SMB shares and can adapt the following steps.
    ```
    You may also set the default [frontend in the
    configuration](CONFIGINI.md#frontend), then you can even drop the `-f` CLI
-   parameter.
+   parameter.  
    If you want to use your existing Batocera gamelist and mediafiles (to save
    some online scrape cycles), you can do so by using the
    [esgamelist](SCRAPINGMODULES.md#emulationstation-style-gamelists) scraping
@@ -283,7 +283,7 @@ You need to add the individual platform rom directories to Pegasus (if they are
 
 !!! info
 
-    If you are generating game lists for Pegasus, it is highly recommended to disable third-party game list data sources! Otherwise you will have a mish-mash or different sources showing up in Pegasus. Start the Pegasus frontend, press ESC on the keyboard and choose _Settings_ -> _Enable/disable data sources_ and disable everything in that submenu.
+    If you are generating game lists for Pegasus, it is highly recommended to disable third-party game list data sources! Otherwise you will have a mish-mash or different sources showing up in Pegasus. Start the Pegasus frontend, press ESC on the keyboard and choose _Settings_ -> _Enable/disable data sources_ and disable everything in that submenu.  
     Then reload the game lists or restart Pegasus, and all of the platforms should show up with media and game information generated by Skyscraper.
 
 #### Metadata preservation
@@ -292,37 +292,66 @@ Skyscraper will preserve any metadata key-value pairs added to the header and /
 
 ### RetroArch
 
--   Default game list location: `/opt/retropie/configs/all/retroarch/playlists`
--   Default game list filename: `<DB_NAME>.lpl` (using its own platform name format)
--   Default media dir location: `/opt/retropie/configs/all/retroarch/thumbnails/<DB_NAME>/Named_*`
+-   Default game list location: `~/.config/retroarch/playlists`
+-   Default game list filename: `<DB_NAME>.lpl` (using its own platform name format, defined in Skyscraper's `peas.json`)
+-   Default media dir location: `~/.config/retroarch/thumbnails/<DB_NAME>/Named_*` (see table below)
 
-Despite the presence of all of these other fancy frontends, the lower-level RetroArch layer that manages most of your emulator cores has a perfectly-capable GUI in the form of a playlist creator/viewer.  The playlists contain each platform's game list, and the playlist viewer has support for covers, screenshots, and logos for each ROM.
+RetroArch structuring element on the GUI is build around playlists. Each
+playlist contains each platform's game list, and the playlist viewer suports
+covers, screenshots, and logos for each game.
 
 #### Configuration
 
-When generating for RetroArch, Skyscraper uses a built-in mapping of platform names to RetroArch database names (e.g., `nes` → `Nintendo - Nintendo Entertainment System`).  If we don't have it in our system, this can be easily added in `platforms_idmap.csv`.
+When generating for RetroArch, Skyscraper uses a configurable mapping of
+platform names to RetroArch database names (e.g., `nes` (folder) → `Nintendo -
+Nintendo Entertainment System` (core name), see file `~/.skyscraper/peas.json`).
+If you want to add a platform to RetroArch DB-Name mapping, please file an
+issue. That way it will be of use for every Skyscraper user. Any setting
+specific to your setup you can define in `~/.skyscraper/peas_local.json`. This
+file uses the same format as the `peas.json`.
 
-You can optionally use the `-e` parameter with `frontendExtra="<CORE_PATH>;<CORE_NAME>"` to set a default core path/name for the playlist.  Or set it in `config.ini`:
+You can optionally use the `-e` parameter with `"<CORE_PATH>;<CORE_NAME>"` to
+set a default core path/name for the playlist. Or set it in `config.ini` like:
 
 ```ini
 [retroarch]
-frontendExtra="<CORE_PATH>;<CORE_NAME>"
+raExtra="<CORE_PATH>;<CORE_NAME>"
 ```
 
+You will most likely have to adjust the game list folder (`gameListFolder=`) and
+the media files folder (`mediaFolder=`) by persisting them in your `config.ini`
+in the `[retroarch]` section. Also you may want to set the
+`artworkXml=retroarch-artwork.xml` in your configuration to assure every media
+file is in PNG format.
+
 #### Media Support
 
 RetroArch supports the following media types:
 
-| Media Type | RetroArch Directory |
-| :---------- | :-------------- |
-| Covers (Box Art) | `Named_Boxarts` |
-| Screenshots | `Named_Snaps` |
-| Marquees/Wheels (Logos) | `Named_Logos` |
-
-All media files are matched to games by their sanitized game title, not by ROM filename.  Title screenshots (`Named_Titles`) are not currently supported.
+| Media Type              | RetroArch Directory |
+| :---------------------- | :------------------ |
+| Covers (Box Art)        | `Named_Boxarts`     |
+| Screenshots             | `Named_Snaps`       |
+| Marquees/Wheels (Logos) | `Named_Logos`       |
 
-Media may not all be in PNG formats.  You should turn on the _Settings_ -> _Playlists_ -> _Allow All Supported Image Types for Thumbnails_ option in your RetroArch config to support JPEG image displays.
+Title screenshots (`Named_Titles`) are not currently supported.  
+All media files are matched to games by their [sanitized game
+title](https://docs.libretro.com/guides/roms-playlists-thumbnails/#custom-thumbnails),
+not by ROM filename.
 
 #### Metadata preservation
 
-Skyscraper will preserve existing game titles and paths when re-generating a game list for RetroArch. If an existing playlist file is found and you choose to skip existing entries, Skyscraper will use the old game list as a reference.
+Skyscraper will preserve existing game titles and paths when re-generating a
+game list for RetroArch. If an existing playlist file is found and you choose to
+skip existing entries, Skyscraper will use the old game list as a reference.
+
+#### Known Limitations
+
+1. Initial generation of a RetroArch playlist does not work for folders resp.
+   platforms which may require a different RetroArch core per game (for example
+   `arcade/` on RetroPie). However, updating an existing playlist file for such
+   folder works, as the existing entry of `"db_name"` per each game is
+   preserved.
+2. Any RetroArch configuration is not evaluated, thus if you changed your
+   RetroArch configuration (e.g., by using non-default file paths) the produced
+   JSON/lpl file might not display correctly in RetroArch frontend.