Metadata files

Pegasus supports several gaming platforms out of the box, but other than those, you can also add your own custom games and emulators. These can be described using metadata files.

A metadata file is a human-readable text file that stores information about the individual games (title, developers, release date, etc.), and groups the games into categories (eg. "Playstation games", "Mario games", etc.). These files can be edited either via a text editor or via the graphical metadata editor for Pegasus. Here is an example (with more details below):

collection: Game Boy Advanced
extension: gba
launch: myemulator {file.path}

game: Advance Wars
file: Advance Wars (USA).gba
developer: Intelligent Games
genre: Strategy
players: 4
   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%

These files are named metadata.pegasus.txt, and Pegasus looks for them in the directories you've added under Settings menu → Set game directories.

Alternative file names

If metadata.pegasus.txt doesn't exists, Pegasus will also try to load metadata.txt. Use whichever filename you prefer.

You can also place multiple files in the same directory if their extension is .metadata.pegasus.txt or .metadata.txt (for example MarioGames.metadata.pegasus.txt)

Global config files

The metadata files are usually kept together with the games. If you prefer to have them separately in one place, that is also possible: Pegasus will also look for them in the <config dir>/metafiles, if this directory exists.

The possible config directories are listed HERE.

Third-party data sources

Pegasus is compatible with various third-party sources, such as EmulationStation and Steam, and can recognize their games automatically. You can turn on/off support for these sources in the Settings menu.

For more details, see the documentation HERE.

File format

The metadata file contains a list of name: value entries, where each entry has a name and one or more lines of values. Groups of such entries are then used to describe Collections and Games. Here is an example file:

collection: PlayStation
extension: iso
ignore-file: buggygame.iso
launch: myemulator "{file.path}"

game: Final Fantasy VII
sort_title: Final Fantasy 7
developer: Square
genre: Role-playing
players: 1
description: Final Fantasy VII is a 1997 role-playing video game developed by
  Square for the PlayStation console. It is the seventh main installment in the
  Final Fantasy series.
  The games story follows Cloud Strife, a mercenary who joins an eco-terrorist
  organization to stop a world-controlling megacorporation from using the planets
  life essence as an energy source.
rating: 92%
x-scrape-source: SomeScraper

Lines starting with # are comments and will be ignored. Empty lines are ignored too.

The name of the entries is case insensitive, so title, Title and TitLe are the same. Values can span multiple lines, but additional lines have to start with at least one space or tab. Depending on the kind of the entry, the lines will be treated as either a list of items  (eg. file list) or as flowing text T (eg. descriptions and single-value entries).

Line breaks

In flowing text, lines that contain a single dot . will be treated as paragraph breaks ("empty lines"), while the characters \n can be used for manual line breaks.


In case you're interested in writing software that would read or write such metadata files, a more detailed page about the syntax can be found HERE.

Currently there are two kinds of groups in a metadata file: Collections and Games. All entries belong to the last defined collection or game entry in metadata files. The entries recognized by Pegasus are listed below.


Collections define which files in the directory (and its subdirectories) should be treated as games, and thus appear in Pegasus. It also stores information about how to launch them (eg. open in emulator X, or run with parameter Y). All games are grouped into collections, but one game can belong to as many collections as you wish.


The following fields define some basic properties:

collectionCreates a new collection with the value as name (if it was not created yet). The properties after this line will modify this collection. This is a required field.T
launchA common launch command for the games in this collection. If a game has its own custom launch command, that will override this field. There are some placeholder variables you can use here, see below for more details.T
commandAn alternate name for launch. Use whichever you prefer.T
workdirThe default working directory used when launching a game. Defaults to the directory of the launched program.T
cwdAn alternate name for workdir. Use whichever you prefer.T

Multiple directories

Collections can span over multiple metadata files if they have the same name. This means you can create categories such as "Platformer games" in multiple locations, and the games will still belong to the same collection.

Include files

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

extension, extensionsA comma-separated list of file extensions (without the . dot), or a list of such lines. All files with these extensions (including those in subdirectories) will be included. This field can appear multiple times.
file, filesA single file or a list of files to add to the collection. You can use either absolute paths or paths relative to the metadata file. The entries don't have to be wrapped in quotes and can contain spaces. This field can appear multiple times.
regexA Perl-compatible regular expression string, without leading or trailing slashes. Relative file paths matching the regex will be included. Unicode is supported.T
directory, directoriesA single directory or a list of directories to search for matching games (see below). This field can appear multiple times.

Foreign directories

By default, a metadata file is expected to be next to the games, and files are searched in the directory of the this file. If you also want to search for matching files in other directories (eg. you prefer to keep the metadata separately), you can list them under directories (similarly to the files, one directory per line). You don't have to mention the directory the metadata file is in.

Exclude files

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

ignore-extension, ignore-extensionsSimilarly to extension above.
ignore-file, ignore-filesSimilarly to file above.
ignore-regexSimilarly to regex above.

Exclusion is stronger than inclusion

If both the regular and the ignore- fields match for a file, it will be excluded.

Plural forms

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


The following fields can tell some additional information:

shortnameAn optional short name for the collection, in lowercase. Often an abbreviation, like MAME, NES, etc. By default, matches the name of the collection.T
sort-byAn alternate name that should be used for sorting. Can be useful when the name contains eg. roman numerals or special symbols.T
summaryA short description of the collection in one paragraph.T
descriptionA possibly longer description of the collection.T

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.

Common platform names

The shortname parameter is often used by themes to show assets (eg. logo, device artwork, etc.) for a particular collection. Here is a list of the most common name–shortname pairs for game platforms:

NameShort name
Amiga CD32amigacd32
Amiga CDTVamigacdtv
Amstrad CPCamstradcpc
Apple IIapple2
Arcade (Daphne)daphne
Arcade (Final Burn Alpha)fba
Arcade (MAME)mame
Atari 800atari800
Atari 2600atari2600
Atari 5200atari5200
Atari 7800atari7800
Atari Jaguaratarijaguar
Atari Jaguar CDatarijaguarcd
Atari Lynxatarilynx
Atari STatarist
Atari XEatarixe
Commodore 64c64
Dragon 32dragon32
Famicom Disk Systemfds
Game Boy Advancegba
Game Boy Colorgbc
Game Boygb
Neo Geo CDneogeocd
Neo Geo Pocket Colorngpc
Neo Geo Pocketngp
Neo Geoneogeo
Nintendo 3DS3ds
Nintendo 64n64
Nintendo DSnds
Nintendo Entertainment Systemnes
Nintendo Game-and-Watchgameandwatch
Nintendo GameCubegc
Nintendo Switchswitch
Nintendo VirtualBoyvirtualboy
Nintendo Wiiwii
Nintendo WiiUwiiu
Odyssey 2odyssey2
PC 88pc88
PC 98pc98
PC Enginepcengine
PlayStation 2ps2
PlayStation 3ps3
PlayStation Portablepsp
PlayStation Vitapsvita
RPG Makerrpgmaker
SAM coupesamcoupe
Scumm VMscummvm
SEGA 32Xsega32x
SEGA CDsegacd
Sega Dreamcastdreamcast
SEGA GameGeargamegear
Sega Genesisgenesis
Sega Master Systemmastersystem
Sega Megadrivemegadrive
Sega Saturnsaturn
SEGA SG-1000sg1000
Sharp X1x1
Sharp X6800x68000
Super Nintendo Entertainment Systemsnes
TurboGrafx 16turbografx16
Xbox 360xbox360
ZX Spectrumzxspectrum

Launch command parameters

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

{file.path}Absolute path to the file./home/joe/games/mygame.bin
{file.uri}Absolute path to the file, in URI form.file:///home/joe/games/mygame.bin (*)
{}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
{env.MYVAR}The value of the environment variable MYVAR, if defined.launch: x11app --tty={env.TTY}

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

Android URIs

On Android some apps expect direct file paths, others only work with so called "content URIs". Depending on your use case, you can use {file.path} for raw paths, or {file.uri} for Android 30 compatible content URIs. Furhermore, on Android 30 and later, apps have a restricted access to the file system, and may require per-directory permissions. You might need to open the app first and manually give access to your game directories.

Note that Pegasus cannot grant file system access to other apps, and cannot guarantee that the app understands a particular path format. If in doubt, contact the app's developer.


Let's say you have Super Nintendo games under C:/games/snes. Then you'd create C:/games/snes/metadata.pegasus.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: snes9x "{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: \

Then add C:/games/snes to the searched game directories in the Settings menu. The games and categories will appear the next time you start Pegasus.


Game entries store additional information about the individual games, such as title, developer(s) or release date. If a game need a special way to get launched, it can also be set here.

The following properties can be used in game entries:

gameCreates a new game with the value as title. The properties after this line will modify this game. This is a required field.T
sort-byAn alternate title that should be used for sorting. Can be useful when the title contains eg. roman numerals or special symbols. sort_title and sort_name are also accepted.T
file, filesThe file or list of files (eg. disks) that belong to this game. Paths can be either absolute or relative to the metadata file. If there are multiple files, you'll be able to select which one to launch when you start the game.
developer, developersThe developer or list of developers. This field can appear multiple times.
publisher, publishersThe publisher or list of publishers. This field can appear multiple times.
genre, genresThe genre or list of genres (for example Action, Adventure, etc.). This field can appear multiple times.
tag, tagsTag or list of tags (for example Co-op, VR, etc.). This field can appear multiple times.
summaryA short description of the game in one paragraph.T
descriptionA possibly longer description of the game.T
playersThe number of players who can play the game. Either a single number (eg. 2) or a number range (eg. 1-4).T
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).T
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).T
launchIf this game must be launched differently than the others in the same collection, a custom launch command can be defined for it.T
commandAn alternate name for launch. Use whichever you prefer.T
workdirThe working directory in which the game is launched. Defaults to the directory of the launched program.T
cwdAn alternate name for workdir. Use whichever you prefer.T

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.

Game requirements

Only games that belong to at least one collection and have at least one existing file will appear in Pegasus.


Continuing with the collection example, the C:/games/snes/metadata.pegasus.txt file could be extended with game data like this:

game: Alien Hominid
file: Alien Hominid (Europe) (En,Fr,De,Es,It).gba
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?
  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.
rating: 50%
x-id: 4149
x-source: ScreenScraper

Asset files

You can add various assets (eg. cover art) for your games. This is documented HERE.

Real-world examples

You can find some more examples on the platform specific pages: