Frontends
Overview¶
When generating a game list with Skyscraper you have the option of generating it for several different frontends. A frontend is the graphical interface that lists and launches your games.
Setting a frontend when generating a game list is done by setting the -f <FRONTEND>
command-line parameter as explained in the commandline documentation or by setting it in /home/<USER>/.skyscraper/config.ini
as explained config file documentation. Use for the <FRONTEND>
value the frontend name all lowercase and with alphabetical characters only: emulationstation
, esde
, pegasus
, retrobat
, attractmode
. Some frontends have further options that are either optional or required. Check the frontend sections below for more information on this.
Warning
Skyscraper will overwrite your game list (obviously). So if you have spend a lot of time hand-crafting metadata in a game list for any frontend, please remember to create a backup before overwriting it with Skyscraper. You can also tell Skyscraper to auto-backup old game lists prior to overwriting them. Read more about the gamelistbackup
config option.
When generating a game list for any frontend, Skyscraper will try to preserve certain metadata. Check the frontend sections below for more information on what metadata is preserved per frontend.
EmulationStation (default)¶
- Default game list location:
/home/<USER>/RetroPie/roms/<PLATFORM>
- Default game list filename:
gamelist.xml
This is the default frontend used when generating a game list with Skyscraper. If no frontend is defined on command-line or in config.ini
it will fall back to generating for EmulationStation. By default the <USER>
is pi
on RetroPie setups.
Metadata preservation¶
Skyscraper will preserve the following metadata when re-generating a game list for EmulationStation: favorite
, hidden
, kidgame
, lastplayed
, playcount
, sortname
. Also existing <folder/>
elements of a gamelist file will be preserved. The user editable sub-XML elements for a folder are listed in the Metadata.cpp
of EmulationStation.
Warning
Folder data is not cached by Skyscraper, thus if you delete your gamelist.xml
, Skyscraper can not restore the edited folder elements from cache.
Automatic addition of folder elements if addFolder
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<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
Consider this folder structure below snes
, whereas each lowest folder contains at least one ROM:
gamelist.xml
and only if addFolders
is set true:
[...]
<folder>
<path>./Retail</path>
<name>Retail</name>
</folder>
<folder>
<path>./Retail/USA</path>
<name>USA</name>
</folder>
<folder>
<path>./Retail/JP</path>
<name>JP</name>
</folder>
<folder>
<path>./Retail/EUR</path>
<name>EUR</name>
</folder>
[...]
Retail
folder is added even if it does not contain a ROM because it is part of the path to the ROMs in the lowest folders.
EmulationStation Desktop Edition (ES-DE)¶
This is very similar to the default EmulationStation. This section only highlights the differences.
- Default game list location:
/home/<USER>/ES-DE/gamelists/<PLATFORM>
- Default game list filename:
gamelist.xml
ROMs are expected to be in the input folder /home/<USER>/ROMs/<PLATFORM>
for
every <PLATFORM>
you scrape.
Media filepaths (screenshots, marquees, videos, aso.) are not held in the
gamelist file. This is ES-DE default. However, Skyscraper will put the media
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.
Tip
You may override the default storage folder of ES-DE (/home/<USER>/ES-DE
)
on a non-Windows build by setting the environment variable ESDE_APPDATA_DIR
to a different folder as documented in the ES-DE documentation.
All the gory details of ES-DE's gamelist file format you can find in the section "Gamelist Reference" in the [ES-DE documentation] (https://gitlab.com/es-de/emulationstation-de/-/blob/master/INSTALL.md?ref_type=heads#gamelistxml).
Metadata preservation¶
Skyscraper will, additionally to EmulationStation preserved metadata, retain the
following metadata when re-generating a game list for ES-DE: altemulator
,
broken
, collectionsortname
, completed
, controller
, hidemetadata
,
nogamecount
, nomultiscrape
. Also existing <folder/>
elements of a gamelist
file will be preserved: For these on top is the folderlink
element is preserved.
RetroBat¶
- Default game list location:
/home/<USER>/RetroPie/roms/<PLATFORM>
- Default game list filename:
gamelist.xml
This is modeled after EmualtionStation as it uses it with slight differences.
Batocera¶
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.
Skyscraper aims to cover the most frequent used elements for scraping, currently
fanarts, manuals and videos. See the scraping
modules for support of these
mediafiles.
This is the complete set of scraping binary data supported by Skyscraper:
Batocera Gamelist XML-Element | Skyscraper support |
---|---|
boxart | ✓ |
fanart | ✓ |
image (in game Screenshot) | ✓ |
manual | ✓ |
marquee | ✓ |
video | ✓ |
wheel | ✓ |
ROMs are expected to be in the input folder /userdata/roms/<PLATFORM>
for
every <PLATFORM>
you scrape.
- Default game list location:
/userdata/roms/<PLATFORM>
- Default game list filename:
gamelist.xml
- Default media file location:
/userdata/roms/<PLATFORM>/{images,videos,manuals}
Metadata preservation¶
These extra elements are preserved.
Batocera Gamelist XML-Element | When present in Gamelist |
---|---|
bezel |
Preserved |
boxback |
Preserved |
cartridge |
Preserved |
magazine |
Preserved |
map |
Preserved |
mix |
Preserved |
music |
Preserved |
thumbnail |
Preserved |
titleshot |
Preserved |
Also all other non scrapable elements are preserved (Batocera EmulationStation
adds those on occasion) like: cheevosHash
, cheevosId
, scrap
, ...
Usage of Skyscraper for Batocera¶
It is possible to compile Skyscraper on Batocera supported systems but you will
need the build-toolchain (at least GCC, make and Qt). Additionally, the
configuration files must be installed in a defined location (see the PREFIX
option in the top-level README.md
, if you are keen to compile Skyscraper on
Batocera).
A more convienient way is to use Skyscraper from you Desktop system: Below you can find a step-by-step guide for Linux systems, macOS should be similar. Windows desktop users can use SMB shares and can adapt the following steps.
- For a pass-through of the screenshot without any artwork do copy the
batocera-artwork.xml
alongside to yourconfig.ini
. Add the artwork file in your configuration file as seen in theconfig.ini.example
. - Mount the root folder of Batocera in your Desktop system. Let the mountpoint
be
/home/mylogin/bato_sshfs
in this example: - Change to the platform folder (in this case
snes
) you want to scrape: - Then run on your Desktop system to scrape data from screenscraper and put it
into the Skyscraper cache on your Desktop system:
You can also set the values for input- (
Skyscraper -s screenscraper -p snes --flags fanarts,manuals,videos -i "$(pwd)" -g "$(pwd)" -o "$(pwd)"
-i
), gamelist- (-g
) und media-folder (-o
) permanently in the Skyscraper config file. - Afterwards run the gamelist creation and media file deployment from cache:
- Do a SSH login to your Batocera system and restart the EmulationStation Leave the SSH shell open to reload EmulationStation with Ctrl+C for subsequent gamelist reloads. You can also restart the whole system, however it takes longer.
- Navigate to the system/platform you just scraped to review the scraping result.
New to Skyscraper?
For starters I suggest to enable (set true
) these settings:
unattended
,
unattendedSktip
and most importantly
gameListBackup
. If you have precious media
files which you may want to keep make also a manual backup of the media folders
of. Also you will have to add your credentials for Screenscraper for example in
the config file of Skyscraper.
For general advise on SSH usage see the Batocera documentation.
Attract-Mode¶
- Default game list location:
/home/<USER>/.attract/romlists
- Default game list filename:
<EMULATOR/PLATFORM>.txt
Attract-Mode is a bit more abstract when it comes to how it saves its game lists and media. To export for Attract-Mode you need to, in addition to setting the frontend, set -e <EMULATOR>
on command-line or in config.ini
. The <EMULATOR>
is a file that describes the platform / emulator you are generating a game list for. The file contains everything needed to tell Attract-Mode how to launch games for the platform, and even where to find the media files for the games (such as screenshots and videos).
If you are running RetroPie most of the <EMULATOR>
files will have been auto-generated for you. They are usually named the same as the platform you are generating a game list for. So, if you are generating for snes
you simply use Skyscraper -p snes -f attractmode -e snes
and that should work just fine. The <EMULATOR>
files are usually located at /home/<USER>/.attract/emulators/
. Check them out if you are curious.
Metadata preservation¶
Skyscraper will preserve the following metadata when re-generating a game list for Attract-Mode: altromname
, alttitle
, buttons
, cloneof
, control
, displaycount
, displaytype
, extra
, rotation
, status
.
Pegasus¶
- Default game list location:
/home/<USER>/RetroPie/roms/<PLATFORM>
- Default game list filename:
metadata.pegasus.txt
Pegasus is easy and simple to generate a game list for. Simply do Skyscraper -p <PLATFORM> -f pegasus
. If you want to specify a custom launch command (if you are using RetroPie you don't have to, a default one will be used), you can set it on command-line with -e "<COMMAND>"
or in config.ini
with:
You need to add the individual platform rom directories to Pegasus (if they are not already defined) before any of them will show up! Start the Pegasus frontend, press ESC on the keyboard and choose Settings -> Set game directories. Simply point it to each individual platform sub-directory. For RetroPie you should have a path for each platform (eg. /home/<USER>/RetroPie/roms/snes
, /home/<USER>/RetroPie/roms/megadrive
etc.).
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.
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¶
Skyscraper will preserve any metadata key-value pairs added to the header and / or individual game list entries.