Skip to content

Latest commit

 

History

History
142 lines (103 loc) · 8.3 KB

IMPORT.md

File metadata and controls

142 lines (103 loc) · 8.3 KB
Raw

Custom Data Import

The following describes how to import your own custom textual, artwork and / or video data into the resource cache for later use when generating game lists (enable game list generation mode simply by leaving out the -s command line option).

!!! tip

For any path in the following description, you can also add a platform subfolder. Skyscraper will auto-detect this and use it instead of the base import folder. For instance, you can create the folder `/home/<USER>/.skyscraper/import/amiga` and it will use that as base instead of `/home/<USER>/.skyscraper/import/` when importing for the `amiga` platform.

!!! info

Be sure to also check the `--cache edit` option [here](CLIHELP.md#--cache-editnewtype).

Images, Videos and Game Manuals

To import videos or images into the resource cache, use the following procedure:

  • Name your image or video file with the exact base name of the rom you wish to connect it to. Example: Bubble Bobble.nes will import images with a filename of Bubble Bobble.jpg or Bubble Bobble.png or other well-known image formats. As long as the base name is an exact match. Same goes for video files. I recommend only making use of well-known video formats since Skyscraper imports them directly without conversion (unless you convert them as described here), so they need to be supported directly by the frontend you plan to use.
  • Game manuals are expected to use PDF format and have the extension .pdf. The base name must match the ROM file, thus the game manual of the example is Bubble Bobble.pdf.
  • Place all of your images, videos or game manuals in the /home/<USER>/.skyscraper/import/<PLATFORM>/screenshots, covers, wheels, marquees, videos or manuals folders.
  • Now run Skyscraper with Skyscraper -p <PLATFORM> -s import. If you named your files correctly, they will now be imported. Look for the green 'YES' in the output at the rom(s) you've placed files for. This will tell you if it succeeded or not.
  • The data is now imported into the resource cache. To make use of if read here.

Special Note for Videos

If you are importing videos, you also need to add the command line flag --flags videos for this to work. Videos aren't imported or scraped by default, since it is considered a huge disk space hog. So keep this in mind if you want to import videos into the cache. If you plan on always using videos, consider adding this option to the config.ini instead.

Textual Data (Publisher, Players, Rating, ...)

Skyscraper also allows you to import textual data for any rom you have in your collection. All you need to do is to prepare files for each rom with an exactly matching base name. For instance Bubble Bobble.nes should have a file called Bubble Bobble.txt or Bubble Bobble.xml or whatever suffix you want to use. The suffix is not important. What is important is that you place all of these raw data files into the /home/<USER>/.skyscraper/import/textual folder. And then you need to make a definitions file so Skyscraper has a recipe for these files.

Textual data definitions file

In order for Skyscraper to understand your textual data files, it needs a recipe. Or a definition of your format if you like. The format is completely up to you. The file must be placed at /home/<USER>/.skyscraper/import/definitions.dat. Here follows a few examples with a matching data file for comparison:

Example 1

Definitions file: /home/<USER>/.skyscraper/import/definitions.dat

<game>
  <title>###TITLE###</title>
  <description>###DESCRIPTION###</description>
  <developer>###DEVELOPER###</developer>
  <publisher>###PUBLISHER###</publisher>
  <players>###PLAYERS###</players>
  <rating>###RATING###</rating>
  <ages>###AGES###</ages>
  <genre>###TAGS###</genre>
  <releasedate>###RELEASEDATE###</releasedate>
</game>

Import file: /home/<USER>/.skyscraper/import/textual/<EXACT ROM BASE NAME>.xml

<game>
  <title>The Game Title</title>
  <description>This game is about yada, yada yada.</description>
  <developer>The game developer</developer>
  <publisher>The game publisher</publisher>
  <players>Maximum number of players supported (example '4')</players>
  <rating>The game rating 0-5 (example '3.5')</rating>
  <ages>Minimum age restriction as integer (example '16')</ages>
  <genre>Genres, Comma-separated</genre>
  <releasedate>The game release date (example '1985-06-01')</releasedate>
</game>

!!! tip

As with Skyscraper 3.9.2 onwards you are no longer required to have the same indention or whitespace (hard tabs, spaces) as in the XML-like `definitions.dat`. Matching is solely done via XML elements (e.g. `<title>`), which saves you headache in identifiying whitespace mismatch between the XML template and your XML import file. If you use a custom XML-like `definitions.dat`: Keep the opening and closing XML element on one line and use one line per `###tag###` as in the example definition shown above. This is the default in the provided `definitions.dat`. In your import file just assure to use also closing elements (`</title>`) and the same caSiNg in the elements between template and import file, ie. provide a valid XML file.

Example 2

Definitions file: /home/<USER>/.skyscraper/import/definitions.dat

Title      : ###TITLE###
Description: ###DESCRIPTION###
Developer  : ###DEVELOPER###
Publisher  : ###PUBLISHER###
Players    : ###PLAYERS###
Rating     : ###RATING###
Rating     : ###AGES###
Genre      : ###TAGS###
Date       : ###RELEASEDATE###

Import file: /home/<USER>/.skyscraper/import/textual/<EXACT ROM BASE NAME>.txt

Title      : Game Title
Description: This game is about yada, yada yada.
Developer  : The game developer
Publisher  : The game publisher
Players    : Maximum number of players supported (example '4')
Rating     : The game rating 0-5 (example '3.5')
Ages       : Minimum age restriction as integer (example '16')
Genre      : Genres, Comma-separated
Date       : The game release date (example '1985-06-01')

!!! warning

Make sure any line matches _exactly_ with the line in the recipe **including white-space characters such as newline characters, spaces and tabs!** Otherwise Skyscraper won't recognize it. Especially for newline characters this can be difficult to debug. Newline characters appear the same in an editor so you won't notice the problem until you load it up in a hex editor.

List of known tags

From the examples above you'll notice the ###SOMETHING### tags. This is what Skyscraper recognizes your data from. The supported tags are:

  • ###TITLE###
  • ###DESCRIPTION###
  • ###DEVELOPER###
  • ###PUBLISHER###
  • ###PLAYERS###
  • ###AGES###
  • ###RATING###
  • ###TAGS###
  • ###RELEASEDATE###

Resource formats

For ###PLAYERS###, ###AGES###, ###RELEASEDATE### and ###RATING### a certain format is required.

  • Players must contain just the maximum number of players as an integer such as '4'.

  • Ages must be an integer between 1 and 18 (for instance "16" means it is suitable from ages 16 and up).

  • Release date must be of one of the following formats:

    • yyyy
    • yyyy-MM
    • yyyy-MM-dd (full ISO 8601 date)
    • yyyy-MMM-dd (MMM is Jan, Feb and so on...)
    • MM/dd/yyyy
    • MMM, yyyy (MMM is Jan, Feb and so on...)
    • MMM dd, yyyy (MMM is Jan, Feb and so on...)

  • Rating can be either a number between 0 and 5, use as fraction only .5. Examples: 3 or 4.5 but not 4.25 or 1.0. This value will be divided by five to match the scale of the rating in a gamelist. Additionally, a value between 0.0 and 1.0 can be used. This value will not be recalculated. If you want to use 0.5 in this metric, provide it as .5 (note the missing zero). Do add a fraction of zero explicitly to denote a rating of 1.0 (100%), without this trailing fraction it will be interpreted as if it would be in the range of 0 to 5 (thus 20% for 1).

How to actually use the data?

When you've imported all of your data into the resource cache, you can make use of it by enabling Skyscrapers game list generation mode simply by leaving out the -s command line option (eg. Skyscraper -p <PLATFORM>). The game list generator will then make use of your imported data. If you don't know what the resource cache is, read more about it here.