Gemba · SineSwiper · Mar 14, 2026 · Mar 21, 2026 · Mar 21, 2026 · Apr 26, 2026
diff --git a/docs/CLIHELP.md b/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)**
 
 ```

diff --git a/docs/CONFIGINI.md b/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.

diff --git a/docs/FRONTENDS.md b/docs/FRONTENDS.md
@@ -28,7 +28,7 @@ Skyscraper will preserve the following metadata when re-generating a game list f
 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 
+-  `<path/>` reflects the relative subpath from the system folder and
 -  `<name/>`, which represents the direct parent folder of a ROM by default. However, you may edit this to any name which should be shown in EmulationStation.
 
 !!! example
@@ -288,4 +288,82 @@ You need to add the individual platform rom directories to Pegasus (if they are
 
 #### Metadata preservation
 
-Skyscraper will preserve any metadata key-value pairs added to the header and / or individual game list entries.
+Skyscraper will preserve any metadata key-value pairs added to the header and / or individual game list entries.
+
+### RetroArch
+
+-   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)
+
+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 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 `"<CORE_PATH>;<CORE_NAME>"` to
+set a default core path/name for the playlist. Or set
+[`raExtra`](CONFIGINI.md#raextra) it in `config.ini` like:
+
+```ini
+; also allowed in [<platform>]
+[retroarch]
+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`       |
+
+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.
+
+#### Known Limitations
+
+1. RetroArch's [deprecated playlist
+   format](https://docs.libretro.com/guides/roms-playlists-thumbnails/#6-line-playlist-format-deprecated)
+   with plain six lines per game is not supported.
+2. 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.
+3. 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.
+4. Existing compressed playlists are not supported yet and will not be read by
+   Skyscraper to preserver any data, thus you may lose previous changes. Before
+   you start using Skyscraper's RetroArch playlist output you should disable the
+   playlist compression in RetroArch and save the playlist from RetroArch as
+   plain JSON.
+5. The settings of "scan_content_dir" in an existing playlist are not yet
+   preserved. 
diff --git a/docs/PATHHANDLING.md b/docs/PATHHANDLING.md
@@ -12,7 +12,11 @@ how the absolute path is calculated when a you provide a relative path.
 
 Do not get confused by the lenghty flow diagram below. It covers game list folder,
 input folder and media folder handling. You wiil notice that input folder and
-media folder are processed in the same manner.
+media folder are almost processed in the same manner.
+
+If you use generate output with Skyscraper for RetroArch as frontend you can
+stop reading as Skyscraper expects any of the three parameters input, gamelist
+and media folder to be absolute.
 
 <figure markdown style="width:100%">
   <img style="width:100%" src="../resources/path_handling_flow.svg"/>