Libretro Core Descriptor Specification Tentative Design

The current stable version of this specification can be found here.

Introduction

This is a playground for a tentative design for a Libretro core descriptor specification to submit to the Libretro community. These descriptor specification's goal is to help Libretro frontends to know the capabilities and requirements of a Libretro core, avoiding the user to manually select one or to hardcode this information.

This specification is mainly thought for Libretro cores installed system-wide in $(libdir)/libretro, where the Libretro core descriptor files are expected to be found with the .libretro suffix.

Why Not RetroArch .info Files?

RetroArch .info files have a few problems like lacking:

  • order and readability;
  • a specification;
  • some information necessary to help Games picking the right core for the game to run.

Their syntax also feels a bit out of place in the realm of GNOME.

It's problably the NIH syndrome hitting again, but better can probably be done for Games with this Libretro core descriptor specification by focusing on improving readability and extensibility, by making the files blend better into the GNOME environment and by supporting the needs of Games better.

Basic Format of the File

The basic format of the file is the same as the Freedesktop desktop entries, which is implemented in the GLib as GKeyFile.

Recognized Libretro Core Descriptor Keys

Types

The Libretro cores can be of different types, different types don't have access to the same sections.

The current version of the Libretro core description specification recognize these types:

  • Game: represents a standalone game; games should only contain the Libretro section and must be run without a game file;

  • Emulator: represents a video game console emulator; emulators must be run with a game, they must support at least one platform and the platforms may require firmwares.

Libretro Entry

Key

Value Type

Required

Description

Type

string

Yes

To allow the addition of new types in the future (such as Engine), implementations should ignore descriptors with an unknown type.

Version

string

No

Version of the Libretro Core Descriptor Specification that the descriptor conforms with. Descriptors that conform with this version of the specification should use 1.0. Note that the version field is not required to be present.

Name

localestring

Yes

Specific name of the Libretro core, for example "Nestopia".

Icon

localestring

No

Icon to display in the Libretro frontend, etc. If the name is an absolute path, the given file will be used. If the name is not an absolute path, the algorithm described in the Icon Theme Specification will be used to locate the icon.

Module

string

Yes

Module file containing the Libretro core this descriptor is describing.

LibretroVersion

string

Yes

The version of Libretro implemented by this core.

Authors

localestring(s)

No

The authors names in the form "My Name" or "My Name <myname@email.com>".

Categories

string(s)

No

ProjectLicense

string(s)

No

The license of the described project: an identifier from the SPDX License List or MAME.

MetadataLicense

string(s)

No

The license of the file itself: an identifier from the SPDX License List.

License (deprecated)

string(s)

No

The license of the described project: an identifier from the SPDX License List or MAME.

Platforms

Only available to the Emulator type.

Key

Value Type

Required

Description

MimeType

string(s)

Yes

The MIME type(s) supported by this Libretro core.

Firmwares

string(s)

No

The firmwares used for this platform.

Firmwares

Only available to the Emulator type.

Key

Value Type

Required

Description

Path

string

Yes

The path to the firmware file. If relative, it is from the "system" directory (cf. the Libretro API).

MD5

string

No

The SHA-512 checksum of the firmware file.

SHA-512

string

No

The MD5 checksum of the firmware file.

Mandatory

boolean

Yes

Whether the firmware is mandatory to run the games or not. All mandatory firmwares for a platform must exist in order to run a game from that platform, even if not all are actually needed: being stricter than needed helps solving complex cases like per-region firmwares or requiring multiple firmwares.

Known Platforms

To help Libretro cores advertise which platforms they support and to help Libretro frontends find a core for a specific platform, it is better to have a unique known name per platform.

To ensure consistency in the names, here are the rules to set the name of a platform:

  • regional variants of a platform are not different platforms;
  • subsystems can be considered different platforms;
  • if a platform has been officially released in the USA then use its name there, otherwise use its name in the country it has first been released to;
  • put the name in CamelCase, using only ASCII letters and digits (no hyphenation, no spaces…).

Following is a list of well known platforms, feel free to expand it as long as you follow the previous rules.

  • Amiga
  • Atari2600
  • Atari5200
  • Atari7800
  • DOOM
  • Dreamcast
  • FamicomDiskSystem

  • GameBoy

  • GameBoyColor

  • GameBoyAdvance

  • GameCube

  • GameGear

  • MAME
  • NeoGeoPocket

  • NintendoEntertainmentSystem

  • Nintendo64
  • NintendoDS
  • Nintendo3DS
  • PlayStation

  • PlayStation2

  • PlayStation3

  • PlayStation4

  • PlayStationPortable

  • PlayStationVita

  • Sega32X
  • SegaCD
  • SegaCD32X
  • SegaGenesis

  • SegaMasterSystem

  • SegaPico

  • SegaSaturn

  • SG1000
  • SuperNintendoEntertainmentSystem

  • TurboGrafx16

  • TurboGrafxCD
  • Wii
  • WiiU
  • WiiWare

Extending the Format

It is possible to add custom keys, to do so the key must have the form X-PRODUCT-KEY, where PRODUCT is the name of the party adding the key in CamelCase and KEY is the actual key in CamelCase; for example: X-RetroArch-CustomKey.

It is also possible to add custom groups, to do so the group must have the form [X-PRODUCT GROUPNAME], where PRODUCT is the name of the party adding the key in CamelCase and GROUPNAME is the actual group name; for example: [X-RetroArch CustomGroup].

These rules are necessary to avoid name clashes between keys and group added by different products. See https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html for more information.

Example

An example Libretro descriptor entry for a standalone game:

[Libretro]
Type=Game
Version=1.0
Name=My Game
Icon=my-game
Module=my-game_libretro.so
LibretroVersion=1
Authors=John Smith;Jane Doe <janedoe@example.com>;
ProjectLicense=GPL-3.0+;
MetadataLicense=CC0-1.0;

An example Libretro descriptor entry for a Sega Genesis emulator:

[Libretro]
Type=Emulator
Version=1.0
Name=My Genesis Emulator
Icon=my-genesis-emulator
Module=my-genesis-emulator_libretro.so
LibretroVersion=1
Authors=John Smith;Jane Doe <janedoe@example.com>;
ProjectLicense=GPL-3.0+;
MetadataLicense=CC0-1.0;

[Platform:SegaGenesis]
MimeType=application/x-genesis-rom;

[Platform:Sega32X]
MimeType=application/x-genesis-32x-rom;

[Platform:SegaCD]
MimeType=application/x-cue;application/x-sega-cd-rom;
Firmwares=SegaCDE;SegaCDJ;SegaCDU;

[Firmware:SegaCDE]
Path=bios_CD_E.bin
MD5=e66fa1dc5820d254611fdcdba0662372
SHA-512=b3725b0577260d8e2b12b782869573824741f5cbe09f2bc49fd8b2346229d1b308a9f54ef08177aa26be7a3580fa8317d0426a2ef7f6bb5103ce039c8e25148f
Mandatory=true

[Firmware:SegaCDJ]
Path=bios_CD_J.bin
MD5=2efd74e3232ff260e371b99f84024f7f
SHA-512=abdaecbc7222392ba4c0c25bc700316ec0a80fcf3e3080a49d6b736fea58e6ec750ac8c477b8ae016c76cf536c1442d834c243fab939d17b856fbc9ed8db8fde
Mandatory=true

[Firmware:SegaCDU]
Path=bios_CD_U.bin
MD5=278a9397d192149e84e820ac621a8edd
SHA-512=abc4347551b6b8a9b4b913b333c8bc35f47cc85e35be1155c7a7287dad05373d0e497f2b73fde56f7ed43fae6d1287faaed3cbf338700a21396262e4180b9158
Mandatory=true

Questions and Ideas

  • What about the Engine type?

References

Design/Playground/Games/LibretroCores/DescriptorSpec (last edited 2017-04-09 15:13:42 by AdrienPlazas)