diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index 7aaf292a33..d6eb3beca3 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -1,7 +1,9 @@ # ROMs, Playlists, and Thumbnails ## Storing games and other content -Game ROMs should be placed within the `roms` folder as configured in RetroArch. Many users sort their ROMs into subfolders named after the system which the ROMs belong to, which results in a folder arrangement such as: +Game ROMs are the source media of the games that can be played using RetroArch cores, they can be actual dumps of read-only memory, but also tape/floppy/compact disc images or some other format. The ROM files may be placed anywhere in the file system where RetroArch has access - note that some platforms (notably Android) are not able to browse the full storage. It is practical if the file browser start directory is configured to the directory where ROMs are stored. + +Many users sort their ROMs into subfolders named after the system which the ROMs belong to, which results in a folder arrangement such as: roms/ @@ -19,8 +21,10 @@ Game ROMs should be placed within the `roms` folder as configured in RetroArch. This arrangement is not required and you are free to organize your ROMs as you prefer. +Also, as a general guideline, content from disc-based systems (Compact Disc images, etc.) should not be zipped for RetroArch use. + ## Working with Playlists -Playlists (or Collections as they are sometimes referred to) are the lists of games and other content that can be generated automatically by the RetroArch playlist scanner, generated by a third-party playlist utility or script, or edited by hand in a text editor. +Playlists are the lists of games and other content that can be generated automatically by the RetroArch playlist scanner, generated by a third-party playlist utility or script, or edited by hand in a text editor. ### RetroArch Playlist Scanner @@ -28,18 +32,45 @@ RetroArch incorporates a ROM scanning system to automatically produce playlists. In order for content to be correctly scanned, you must: - - Have a compatible core already downloaded and installed + - Have a compatible core already downloaded and installed (note: Scan Without Core Match setting removes this requirement) - Update `Core Info Files` via `Online Updater` - Update `Databases` via `Online Updater` - Restart RetroArch if any of the above was just done -Finally, the content must match existing databases from the [libretro-database README](#sources). If those conditions are met but content is still not being added automatically to a playlist, consider submitting an issue report on [github](https://www.github.com/libretro/RetroArch/issues). +For a normal scan, the content must match existing databases from the [libretro-database README](https://github.com/libretro/libretro-database#retroarch-database). If those conditions are met but content is still not being added automatically to a playlist, consider submitting an issue report on [github](https://www.github.com/libretro/RetroArch/issues). -#### Designating which core to use +There is an option to do manual scan, which does not require a database, and just needs the file names to match. Results from the manual scan will be playable (as long as the respective core supports them), but may lack thumbnails and do not appear in the Explore menu. + +### Designating which core to use RetroArch will attempt to detect and use the correct core for use with the ROMs that are used as part of a playlist. Under some circumstances, it may be useful to manually set a particular core for one of its playlists. This can be accomplished within the Playlists submenu in the RetroArch settings. -### Playlist File Overview +## The Explore menu + +RetroArch provides an Explore menu which can be used for browsing all content that were added to playlists using any database attribute - release year, genre, etc. + +## Thumbnails + +RetroArch can display three types of thumbnails (small still pictures) for games in playlists: + +* In-game snapshots +* Title screen snapshots +* Boxart + +![An in-game snapshot displayed with a Sega - 32X playlist.](http://www.lakka.tv/doc/images/thumbnails.png "An in-game snapshot displayed with a Sega - 32X playlist.") + +Most menu drivers support displaying two pictures when browsing the playlist. Displayed thumbnail types can be configured system-wide and also per playlist. +All menu drivers can display fullscreen thumbnails when pressing Start, and Y button (left) can be used to cycle between available pictures. + +Thumbnails can be retrieved multiple ways: + +* Playlist thumbnail downloader (recommended): under Online Updater menu, all available thumbnails can be downloaded for a playlist. RetroArch will connect to http://thumbnails.libretro.com. +* Individual thumbnail downloader: there is a Download Thumbnails option for each entry in playlists. For RetroArch versions later than 1.16.0, you may hit download up to 3 times to try the flexible matches. +* On-demand thumbnail downloader: if the respective option is enabled, RetroArch will try to download each thumbnail as the playlist is browsed. For RetroArch versions later than 1.16.0, you may try flicking back and forth between entries up to 3 times to try the flexible matches. + +Thumbnail packs are no longer available, use one of the above methods, or see Custom thumbnails section below. + +## Playlist File Format Details Each playlist is a plain text file with an extension of `.lpl`. RetroArch 1.7.5 and later uses a JSON playlist format, although the backwards compatibility remains for the deprecated "6-Line" playlist format. @@ -48,7 +79,7 @@ Each playlist is a plain text file with an extension of `.lpl`. RetroArch 1.7.5 !!! Hint "Hint for Windows Users" The built-in Notepad editor cannot work with cross-platform text files such as RetroArch playlist files. Many users and developers recommend the free [Notepad++](https://notepad-plus-plus.org/) as a replacement although most alternative text editors will also work. -#### JSON Playlist Format +### JSON Playlist Format The following example is a single-entry MAME 2003-Plus playlist for [Alien Arena](https://www.arcade-museum.com/game_detail.php?game_id=6850) -- the silent version of this game is available through the RetroArch **Content Downloader** found in the **Online Updater** menu. @@ -56,7 +87,7 @@ The romset with the `label` **Alien Arena** is located at `path` being `C:\retro The ROM's corresponding `db_name` is `MAME 2003-Plus.lpl` which tells the menu driver which ROM database to use for looking up the game's metadata, thumbnails and game-system-specific icon-type. Menu drivers which implement playlist icons will use it to display it next to the ROM's name. -##### `MAME 2003-Plus.lpl` +#### `MAME 2003-Plus.lpl` ```json { "version": "1.0", @@ -76,14 +107,14 @@ The ROM's corresponding `db_name` is `MAME 2003-Plus.lpl` which tells the menu d !!! Alert You can omit the CRC or Serial for a manually created playlist entry by using the word `DETECT` instead, although it may limit your ability to use netplay for this playlist entry. -#### 6-Line Playlist Format (Deprecated) +### 6-Line Playlist Format (Deprecated) !!! Warning This playlist format is deprecated and may not always be supported by RetroArch in the future. New playlists should be created in the JSON format. **Each entry in a playlist must be composed of 6 lines:** -##### `MAME 2003-Plus.lpl` +#### `MAME 2003-Plus.lpl` ``` C:\retroarch\downloads\alienar.zip" Alien Arena @@ -140,44 +171,30 @@ Since playlists are managed in text-only JSON format, there are a few third-part - [RetroArch Playlist Editor](https://www.marcrobledo.com/retroarch-playlist-editor/) ([Source](https://github.com/marcrobledo/retroarch-playlist-editor)) - [RetroArch Playlist Buddy](https://forums.libretro.com/t/retroarch-playlist-buddy-playlist-and-thumbnail-generation-app/8417) ([Source](https://github.com/markwkidd/ahk-retroarch-playlist-helpers)) -## Thumbnails - -RetroArch can display three types of thumbnails for games in playlists, depending on the specific RetroArch menu driver in use: -* In-game snapshots -* Title screen snapshots -* Boxart - -![An in-game snapshot displayed with a Sega - 32X playlist.](http://www.lakka.tv/doc/images/thumbnails.png "An in-game snapshot displayed with a Sega - 32X playlist.") - -### RetroArch thumbnail packs -RetroArch provides packs of thumbnails suitable for use with many emulated systems. These thumbnail packs are recommended for most users and can be installed connecting to the internet and using the built-in thumbnails updater, available from the online update menu within the RetroArch settings interface. - -These packs can be downloaded manually from http://thumbnailpacks.libretro.com and individual thumbnails from within the packs can be downloaded from http://thumbnails.libretro.com. - -### Custom thumbnails +## Custom thumbnails Users who wish to use their own thumbnails can do so by naming PNG image files according to the RetroArch naming convention. -#### Thumbnail paths and filenames +### Thumbnail paths and filenames Thumbnails should be stored in subfolders within the configured RetroArch `thumbnails` directory within a subfolder named exactly the same as the playlist, except without `.lpl` at the end. **Example: If your playlist is named `Atari - 2600.lpl`, then your Atari 2600 root thumbnail folder should be called `thumbnails/Atari - 2600/`.** Within this root thumbnail folder called `Atari - 2600`, you should then create subfolders named `Named_Boxarts`, `Named_Snaps`, or `Named_Titles` for boxart/cover art, in-game snapshots, and title screens, respectively. The thumbnail filename should exactly match the game's title as listed in the playlist with an important exception. **The following characters in playlist titles must be replaced with `_` in the corresponding thumbnail filename:** `` &*/:`<>?\| `` -**Example: If your content is named `Q*bert's Qubes` in the playlist, then its thumbnails should be named `Q_bert's Qubes.png` and stored at these paths:** +**Example: If your content is named `Q*bert's Qubes (USA)` in the playlist, then its thumbnails should be named `Q_bert's Qubes (USA).png` and stored at these paths:** ``` thumbnails/ Atari - 2600/ Named_Boxarts/ - Q_bert's Qubes.png + Q_bert's Qubes (USA).png Named_Snaps/ - Q_bert's Qubes.png + Q_bert's Qubes (USA).png Named_Titles/ - Q_bert's Qubes.png + Q_bert's Qubes (USA).png ``` - - -### Changing the displayed thumbnail type -Regardless of whether you download the RetroArch thumbnail packs or use your own custom thumbnails, you can use the RetroArch GUI to set which type of thumbnail to display. In order to change this setting, go to `Menu Settings,` and change the `Thumbnails` option to reflect the type of thumbnail you wish to display. +For RetroArch versions later than 1.16.0, flexible naming is applied, up to 3 options are tried for each playlist entry, in the following order: +- ROM file name with .png extension: `Q-Bert's Qubes (1983)(Parker Bros)[b].png` +- Database entry / playlist label with .png extension, as explained above: `Q_Bert's Qubes (USA).png` +- Short name: same as previous, but only up to first round bracket: `Q_Bert's Qubes.png`