Game collections and metadata files

To tell Pegasus the list of directories in which it should look for games, you can use the Settings menu -- is what I'd like to say, but this isn't done yet as of alpha7. The list of directories is read from [config directory]/game_dirs.txt, one directory per line. The file might not exist at first, but you can create it and then it'll be read.

Configuration directories

Depending on your platform, the default config directory should be:

  • Linux: ~/.config/pegasus-frontend
  • Windows: C:\Users\<User Name>\AppData\Local\pegasus-frontend
  • macOS: ~/Library/Preferences/pegasus-frontend

Pegasus will then go through the directories listed in game_dirs.txt, and look for the collection and metadata file in them:

EmulationStation

If you have EmulationStation installed and set up, Pegasus will also check the directories set in es_systems.cfg, read the gamelist.xml files and use the metadata and assets defined there.

A tool for converting between ES and Pegasus files can be found HERE. Compared to ES files, the collection file is like es_systems.cfg, except it's local to the directory it's placed in, while the metadata file is mostly equal to gamelist.xml.

Steam

Pegasus is also compatible with Steam. No additional settings are necessary, installed Steam games will automatically appear in Pegasus with metadata and multimedia assets.

File names

Pegasus looks for collections.txt or collections.pegasus.txt for the collection definitions, while metadata can be defined in metadata.txt or metadata.pegasus.txt (with these exact names). Pegasus will first check for the .pegasus.txt variant (in case you wish to store something else in the one with shorter name).

You can find examples for both files below, after their format and keywords are detailed.

Common file format

Both configuration files have the same basic format; they store key: value pairs:

collection: My Games
extensions: bin
ignore-file: buggygame.bin
ignore-file: duplicategame.bin
launch: myemulator {file.path}
file: Advance Wars (USA).gba
title: Advance Wars
developer: Intelligent Games
genre: Strategy
players: 4
description: This turn-based strategy game hails back to a classic Japanese
    strategy game titled Famicom Wars. Advance Wars pits players against very
    computer AI in a number of battles involving submarines, warships, infantry,
    tanks, helicopters, and other weapons.
rating: 80%
x-id: 3782
x-source: ScreenScraper

Collection properties

The following keys can be used in the collection config files:

KeyDescription
collectionCreates a new collection with the value as name (if it was not created yet). The properties after this line will modify this colection. This is a required field.
launchA common launch command for the games in this collection. See below for the supported variables.
commandSame as launch. Use whichever you prefer.
shortnameAn optional short name for the collection, often an abbreviation (like MAME, NES, etc.). Should be lowercase.

The following fields control which files of the directory should be included in the collection:

KeyDescription
extensionA comma-separated list of file extensions, without the . dot. All files with these extensions (including those in subdirectories) will be included. This field can appear multiple times.
fileA single file to add to the collection. This field can appear multiple times.
regexA Perl-compatible regular expression string, without leading or trailing slashes. Relative file paths matching it will be included. Unicode is supported.

The fields above with the ignore- prefix control which files should be excluded:

KeyDescription
ignore-extensionSimilarly to extension above.
ignore-fileSimilarly to file above.
ignore-regexSimilarly to regex above.

Exclusion is stronger than inclusion: if both the normal and the ignore- fields match for a file, it will be excluded.

Keys starting with x- can be used to extend the format with additional data. This could be used, for example, by other softwares (eg. scrapers) to store some program-specific data.

Plural forms

Sometimes writing the plural forms of the fields feels more natural, so extensions, files, ignore-extensions and ignore-files are also supported, without any difference to their regular forms.

Multiple directories

Collections can span over multiple directories if they have the same name. This means you can create categories such as "Platformer games", for which the game files themselves might be located in different directories.

Launch command parameters

The following variables will be replaced in the launch command value:

VariableDescriptionExample
{file.path}Absolute path to the file./home/joe/games/mygame.bin
{file.name}The file name part of the pathmygame.bin
{file.basename}The file name without extension (ie. until but not including the last dot)mygame
{file.dir}The directory where the file is located./home/joe/games

Note that the variables will be replaced as-is, without additional formatting. You might need to eg. wrap them in quotes.

Example

Let's say you have Super Nintendo games under C:/games/snes. Then you'd create C:/games/snes/collections.txt with the following contents:

# Selects all files with the provided extension, except two games
collection: Super Nintendo Entertainment System
shortname: snes
extensions: 7z, bin, smc, sfc, fig, swc, mgd, zip, bin
ignore-file: buggygame.bin
ignore-file: duplicategame.bin
launch: myemulator "{file.path}"

# A collection of 3 games. They're also part of 'My Games'.
collection: Platformer games
files: mario1.bin
files: mario2.bin
files: mario3.bin

# A regex example; includes games with '[number]-in-1' in their name.
collection: Multi-game carts
regex: \d+.in.1

Then add C:/games/snes to [config directory]/game_dirs.txt in a new line. The games and categories will appear the next time you start Pegasus.

Metadata properties

The following properties can be used in the metadata files:

KeyDescription
fileRelative path to the file for which the metadata after this line will be added. If the file is not included in any collection, all properties will be ignored until the next file key. This is a required field.
titleThe proper title of the game. If it's not defined, the file name without extension will be used.
nameSame as title. Use whichever you prefer.
developerThe developer or the game. This field can appear multiple times.
publisherThe publisher or the game. This field can appear multiple times.
genreA comma-separated list of genres. This field can appear multiple times.
summaryA short description of the game in one paragraph.
descriptionA possibly longer description of the game.
playersThe number of players who can play the game. Either a single number (eg. 2) or a number range (eg. 1-4).
releaseThe date when the game was released, in YYYY-MM-DD format (eg. 1985-05-22). Month and day can be omitted if unknown (eg. 1985-05 or 1985 alone is also accepted).
ratingThe rating of the game, in percentages. Either an integer percentage in the 0-100% range (eg. 70%), or a fractional value between 0 and 1 (eg. 0.7).
launchIf this game must be launched differently than the others in the same collection, a custom launch command can be defined for it.
commandSame as launch. Use whichever you prefer.

Like with the collections, keys starting with x- can be used to extend the format with additional data. This could be used, for example, by other softwares (eg. scrapers) to store some program-specific data.

Plural forms

As with the collections, plural forms for the keys with multiple values are also supported, so developers, publishers and genres will work too.

Example

Continuing with the collection example, a file called C:/games/snes/metadata.txt could look like this:

file: Alien Hominid (Europe) (En,Fr,De,Es,It).gba
title: Alien Hominid
developer: Zoo Digital
genre: Shooter
players: 1
summary: You're a little yellow alien.  The FBI has shot down your ship
  while flying over planet Earth.  And it, quite literally, lands right on their
  doorstep.  After a series of FBI Agents swipe your ship, what option do you have
  other than to blow up everything in your path to get it back?
description:
  Alien Hominid is a 2D side-scrolling shooter with heavy references to the Metal
  Slug series of games - from the hand-drawn graphics, huge explosions, right down
  to the ability to eviscerate FBI Agents when you get up close to them.  The
  graphics are by featured artist Dan Paladin.  Your goal, is quite simply, to get
  to the end of the stage, and die as little as possible.  Which is made difficult
  due to the fact that any bullet is an instant kill.

  To help you out, you can grab a range of power-ups, such as lasers, spread
  shots, shotguns and more, as well as hijacking vehicles and using them for
  protection.  Grenades can be lobbed, and you can jump on enemy shoulders and
  choose to bite their heads off if you like, or pick them up and throw them at
  other enemies.  You can also dive underground for a short period of time to
  avoid enemies - while underground, you can drag agents into the ground to kill
  them.
rating: 50%
x-id: 4149
x-source: ScreenScraper


file: Altered Beast - Guardian of the Realms (USA).gba
title: Altered Beast : Guardian of the Realms
developer: THQ
genre: Action
rating: 60%
x-id: 4139
x-source: ScreenScraper