Introduction

RP9 files were first introduced in the 2009.0 versions of Amiga Forever and C64 Forever, which were based on version 2.0 of the RetroPlatform Player framework. Version 2.2 of RetroPlatform Player extended the original RP9 specification to include user-editable configuration data (<configuration>, <media> and <startup> elements). These new components are part of the 2009.2 versions of Amiga Forever and C64 Forever, and of 2010 and newer versions.

RetroPlatform Player

RetroPlatform Player is not only a playback tool, but it also features RP9 Manager, which can import, export and rescan RP9 files. The rescan operation regenerates the configuration data by comparing the RP9 media content with data stored in RetroPlatform Library (a database of known content).

RetroPlatform Player and RP9 Manager comply with RP9 design goals which include:

• RP9 files should not be unnecessarily different if they contain substantially the same data (exporting from RP9 to individual files and back to RP9 should produce a file identical to the original, if the same RetroPlatform Library was available for automated content recognition)
• Manifest data generated by newer RetroPlatform Library should not be overwritten on the basis of older data (the RP9 ecosystem should improve over time, not get worse)
• Configuration data that was manually created by a user should generally be respected, unless the user expressly decides (e.g. by disabling the "Protect user-modified configuration tags" option in RP9 Manager) to rescan the file, and newer RetroPlatform Library data is available for that file

Achieving some of these goals was not trivial. For example, a simple export and import of an RP9 file set results in a new XML manifest file being written, with a new (current) file timestamp. Because RP9 files are ZIP-based containers, their content also changes to reflect properties such as file dates. RP9 Manager overcomes this by setting the manifest file date to the same date of the newest file in the set (e.g. an existing disk image file).

Third-Party Players

While the up-to-date description and configuration data provided by RetroPlatform Library helps RetroPlatform Player implementations to accurately visualize and play back RP9 content, third-party players can use RP9 files without loading additional data. The RP9 file name and the XML manifest respectively contain sufficient description and configuration data for most playback purposes.

With respect to third parties, RP9 design goals include:

• Adoption of the RP9 format by third parties is encouraged for all purposes, including editing and playback
• RP9 files should be playable on third-party players even without RetroPlatform Library

XML Manifest: Required Elements

The following elements are required in the rp9-manifest.xml file.

<rp9>

This is the outer container element.

<requirements>

This element contains <host> and <playerversion>. It is essential for graceful forward-compatibility notifications to the user (e.g. required updates).

<host>

 If this is missing, RetroPlatform Player will show an error message.

<playerversion>

May be safely set to 2.2.0.0, which is supported by all generations of RetroPlatform Player (including the oldest ones, via free updates). Should be increased with extreme care, because it indicates an absolute requirement. If the version of the player application opening the file is older than the indicated version, the player displays a message indicating that a newer player version is required.

<application>

This element contains all content-specific elements (description, configuration, media, etc.), as well as the OID attribute.

<configuration>

This element became required as of version 2.2 of the RetroPlatform framework. It may contain a copy of configuration data sourced from RetroPlatform Library, or heuristic data, or user-edited data.

<media>

This element became required as of version 2.2 of the RetroPlatform framework. It references the media images (e.g. disks or tapes) referred to by the configuration.

XML Manifest: Optional Elements and Attributes

The following elements and attributes are optional in the rp9-manifest.xml file. This is not an exhaustive list, but merely a selection of what is more relevant to the topic discussed here (playback scenarios and user-edited data).

<application oid="1.2.3.4.5" libraryversion="1.3.0.0" score="100" user-edited="true">

The oid attribute indicates the unique application OID (inclusive of application variant), based on RetroPlatform Library data (the above "1.2.3.4.5" is only a fictitious example). It helps applications that have access to RetroPlatform Library data access additional, accurate and up-to-date description information, and configuration information (unless the RP9 file contains newer or user-edited configuration data). The oid is also required for purposes such as associating "star rating" data, and for keeping track of saved states.

The libraryversion and score attributes indicate the RetroPlatform Library version that was used to identify the application, and the score with which the application was recognized (100 indicates an exact match). These attributes help express the version and the quality of the data, so that, for example, it is not overwritten by older data.

The optional user-edited attribute is set in the <application> tag whenever the data in the element is created or modified manually. This helps appreciate and protect user contributions and preferences (both for playback purposes and during rescans that might otherwise reset all data). If the attribute is missing, it is assumed to be False.

If the data does not come from RetroPlatform Library, the oid, libraryversion and score attributes are omitted. If the data comes from RetroPlatform Library and is later edited, the attributes should be retained (adding the user-edited attribute), unless the edited content references a different title.

<description>

Within RetroPlatform Library, <description> data contains information for visualization and presentation purposes, not for playback (configuration) purposes. As of 2.x versions of the RetroPlatform framework, this element contains a subset of the description data that is otherwise stored in RetroPlatform Library for display purposes (i.e. not for configuration or playback purposes), including some information such as the publisher name and application title that is usually also found in the RP9 file name (where however it may be damaged by file naming constraints).

Playback - Common Scenarios

For applications that have access to RetroPlatform Library data (e.g. RetroPlatform Player implementations like Amiga Forever and C64 Forever):

• If the application OID is present and found in the available RetroPlatform Library data, look up the description information in RetroPlatform Library
• If the application OID is missing or unusable, scan the media to recognize it, and see if an OID can be generated for a temporary lookup (the RP9 is not modified)
• If an application OID is still unavailable after the previous steps, extract the publisher, application title and other details from the RP9 <description> element, or, as a last resort, from the file name
• If user-edited="true", or if the "libraryversion" attribute references a library newer than the one that is available to the application, always use the configuration from the RP9 data
• In all other cases, use configuration data from RetroPlatform Library, or heuristic configuration

For applications that do not have access to RetroPlatform Library data (e.g. third-party players):

• Extract the publisher, application title and other details from the RP9 file name
• Use the configuration from the RP9 data

Playback - Special Cases

• Missing <playerversion> or <host>, or <playerversion> referencing a version newer than the current player implementation version: blocking condition
• "oid" attribute present, but missing "libraryversion" attribute: take description and configuration from RP9 file (it is up to the rescan to regenerate/repair the data, if so desired)
• "oid" attribute present, but "libraryversion" references a library that is newer than the one installed: treat as if "libraryversion" is missing and display warning message encouraging to check for library updates (with "Do not show again option")
• "oid" attribute missing, or "oid" present but no match found in library: scan the media to recognize it, and see if an application OID can be generated for a temporary lookup (the RP9 is not modified)
• "user-edited" attribute set: always use description and configuration data from RP9 elements (not from RetroPlatform Library, regardless of versions - if the user wishes to override this, the RP9 must be edited or rescanned in RP9 Manager with the desired "Protect user-edited configuration tags" setting)

Rescan - Common Scenarios

A rescan operation rebuilds the OID, description and configuration data in RP9 files based on (ideally) the most current RetroPlatform Library data. The version information in the RP9 file helps to make sure that newer data is never overwritten by older data. The media in the RP9 file is always rescanned, even if the RP9 contains an existing application OID reference.

As user-edited data is marked as such ("user-edited" attribute), it is also possible to choose whether to preserve such data. In RetroPlatform Player implementations like Amiga Forever and C64 Forever an option in RP9 Manager named "Protect user-edited configuration tags" makes it possible to choose whether older RP9 configuration data (based on the "libraryversion" attribute) may be overwritten by newer RetroPlatform Library data, if such data is available. This is generally acceptable, because individual RetroPlatform Library data changes originate from expert users and, over time, passes additional verifications and reputation-based mechanisms.

In all cases:

• If the application performing the RP9 rescan has an older version of RetroPlatform Library than the one referenced in the RP9 file, then no changes are applied to that file (if it is the same version, the rescan takes place), because it is assumed that the RP9 already contains newer data
• Lack of version information in the RP9 <application> tag is always treated as "older version"

If "Protect user-edited configuration tags" is False:

• If the media is recognized, the RP9 elements are rebuilt, with "oid" and "libraryversion" attributes referencing the current RetroPlatform Library; any user-edited data is reset with library-sourced data, and the "user-edited" attribute, if present, is cleared

If "Protect user-edited configuration tags" is True:

• If the "user-edited" attribute is set, do nothing; otherwise, proceed as when "Protect user-edited configuration tags" is False

Checklist for Authoring Tools

• Make sure you that you consider the common playback and rescan scenarios, and the special cases
• If your application allows the user to edit the RP9 data, it should preserve the original "oid" and "libraryversion" information, and set the "user-edited" attribute; if the application "oid" attribute itself is reset, "libraryversion" may be omitted if the application does not use data compatible with the RetroPlatform Library versioning system
• Test playback of your custom RP9 files with a RetroPlatform Player implementation, ideally also doing a rescan and comparing the original and updated manifests

Related Links

• RP9 File Format Information
• RetroPlatform Media Recognition
• RP9 and TOSEC File Names
• RetroPlatform OIDs