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:
1 2 3 4 5 6 7 8 9 10 11 12 |
|
This arrangement is not required and you are free to organize your ROMs as you prefer.
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.
RetroArch Playlist Scanner¶
RetroArch incorporates a ROM scanning system to automatically produce playlists. Each ROM that is scanned by the playlist generator is checked against a database of ROMs that are known to be good copies.
In order for content to be correctly scanned, you must:
- Have a compatible core already downloaded and installed
- Update
Core Info Files
viaOnline Updater
- Update
Databases
viaOnline Updater
- Restart RetroArch if any of the above was just done
Finally, the content must match existing databases from the libretro-database README. If those conditions are met but content is still not being added automatically to a playlist, consider submitting an issue report on github.
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¶
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.
Note: The paths in playlist files need to use the correct 'slash' character for the user's platform. Linux, OS X, and Android systems including Lakka and LudOS require forward slashes /
, while Windows and DOS systems require backslashes \
.
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++ as a replacement although most alternative text editors will also work.
JSON Playlist Format¶
The following example is a single-entry MAME 2003-Plus playlist for Alien Arena -- the silent version of this game is available through the RetroArch Content Downloader found in the Online Updater menu.
The romset with the label
Alien Arena is located at path
being C:\retroarch\downloads\alienar.zip
; note that the backslashes are doubled in JSON-formatted playlist entries so that the value of the path
entry is C:\\retroarch\\downloads\\alienar.zip
.
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
¶
{
"version": "1.0",
"items": [
{
"path": "C:\\retroarch\\downloads\\alienar.zip",
"label": "Alien Arena",
"core_path": "DETECT",
"core_name": "DETECT",
"crc32": "01ACE2AB|crc",
"db_name": "MAME 2003-Plus.lpl"
}
]
}
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)¶
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
¶
C:\retroarch\downloads\alienar.zip"
Alien Arena
/tmp/cores/mame2003_plus_libretro.so
DETECT
01ACE2AB|crc
MAME 2003-Plus.lpl
- The path to the ROM. This can either be an 'absolute' path or a path relative to the current working directory.
- The display name (you can use any name here)
- The path to the core, this libretro core will be used to launch the ROM. You can use the word DETECT in place of the core path here. Once this is done you can set the core to be used for this playlist via the RetroArch GUI.
- The displayname of the core, not really useful, we keep it there because the history list is also using this format
- CRC or Serial number for database and other matching purposes. You can omit the CRC or Serial for a manually created playlist entry by using the word DETECT here instead, although it may limit your ability to use Netplay for this playlist entry.
- The name of the system playlist to which this ROM is associated for looking up database metadata and thumbnails.
Creating custom playlists (cross-platform, cross-folders)¶
The standard playlists in RetroArch are usually platform-specific, i.e. Nintendo - Game Boy.lpl
or Sony - PlayStation.lpl
.
Maybe you want to create custom playlists not limited within game-platforms or ROM-folders, e.g. "Multiplayer Racing Games" or "Medieval Themed Games".
content_favorites.lpl
and content_history.lpl
are examples of default playlists which have this cross-platform behavior. So study them as an example first.
To create a custom playlist¶
- Copy/merge content from platform-playlists files into a fresh playlist file inside
<RetroArchRoot>/playlists/
entitledMy Sorting Prefix - My Playlist Name.lpl
. - Be sure that the ROM entries follow the syntax as described in section: JSON Playlist Format.
- The
db_name
attribute entry must be the ROM's correspondingExact Game Platform Playlists Name.lpl
(e.g.Nintendo - Game Boy.lpl
) in order to be associated with the correct metadata and thumbnails.
Customize how/where your playlists are shown¶
- Name your playlist in the scheme
My Sorting Prefix - My Playlist Name.lpl
or justMy Playlist Name.lpl
. - To tweak how playlists are displayed (with or without prefix) and how they are sorted (by prefix or by main name):
- Go to: Settings > Playlists
- Set options Truncate Playlist Names and Sort Playlists After Name Truncation to your liking.
How to set up custom playlists (Screenshots)¶
Third-Party Applications¶
Since playlists are managed in text-only JSON format, there are a few third-party applications to help manage your playlists.
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
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¶
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¶
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:
thumbnails/
Atari - 2600/
Named_Boxarts/
Q_bert's Qubes.png
Named_Snaps/
Q_bert's Qubes.png
Named_Titles/
Q_bert's Qubes.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.