RetroPlatform Simple Storage Format
This document explains a format formerly used by RetroPlatform implementations like Amiga Forever and C64 Forever when syncing data to storage devices like SD cards.
As of 2016, native RP9 format support is being embraced by growing numbers of third-party devices and players, making the simplified format described here unnecessary. It is therefore being discontinued. New features are added to the RP9 format and to the related authoring and processing tools (e.g. as included in Amiga Forever and C64 Forever).
Version 2.1 of the RetroPlatform engine, as used in "2009.1" versions of Amiga Forever and C64 Forever, introduced a new Export to Device command in RP9 Toolbox. This command exports and indexes the selected content in a way that can be accessed in a simple and documented fashion.
Technical requirements for reader applications:
- FAT file system ("8.3" names, with directories)
- INI parsing functionality
- Support for uncompressed media images (D64, T64, ADF, HDF, etc.)
- Support for RetroPlatform system ROMs (.ROM files with ROM.KEY, etc.)
- Font able to render shared ISO 8859-1/Windows 1252/Amiga characters (including accented letters)
- Support for true color BMP image data (to display preview thumbnails)
The format is called "simple" because it can be accessed without requiring code to handle XML, compressed disk images, PNG graphics or "long file names".
For feedback, or if you need additional details, please feel free to contact us.
Third-party content and devices are supported by the format. In order to appropriately detect device types and to separate private data from multiple vendors, a text tag, referenced here as <PID>, is used.
A <PID> is a text string of up to 8 characters (uppercase A-Z, 0-9). The <PID> may be something like "MAXIMIGA", or "CLOANTO", etc. It should be broad enough to be meaningful across different products by the same entity. If there is a doubt that the entity name may change over time, it might be prudent to consider a numeric-only <PID>.
When you are ready to write data to a RetroPlatform-enabled medium, please let us know what <PID> you would like to use, so that it can be assigned in a unique way.
Organization of Files
The following is a sample set of files as might be found after exporting data to a medium:
RP-INDEX.INI RP-MEDIA.ID /APPS/ /APPS/GAME1/DISK1.ADF /APPS/GAME1/DISK2.ADF /APPS/GAME1/PREVIEW1.BMP /APPS/GAME1/PREVIEW2.BMP /SHARED/ /SHARED/ADF/ /SHARED/ADF/AWB134.ADF /SHARED/HDF/ /SHARED/HDF/AWB310.HDF /SHARED/ROM/ /SHARED/ROM/A130.ROM /SHARED/ROM/A310.ROM /SHARED/ROM/CDTV-EXT.ROM /SHARED/ROM/ROM.KEY /PRIVATE/ /PRIVATE/<PID>/ /PRIVATE/<PID>/MODEL1/ /PRIVATE/<PID>/MODEL1/CORE1.BIN /PRIVATE/<PID>/MODEL1/CORE2.BIN /PRIVATE/<PID>/MODEL1/FIRMWARE.BIN /PRIVATE/<PID>/MODEL2/ /PRIVATE/<PID>/MODEL2/CORE1.BIN /PRIVATE/<PID>/MODEL2/CORE2.BIN /PRIVATE/<PID>/MODEL2/FIRMWARE.BIN
System files (ROMs, ROM.KEY, floppy disk images, hard disk images, etc.) are in the "SHARED" folder, rather than being duplicated with each application instance. Compared to an Amiga Forever or C64 Forever installation on Windows, where applications are grouped by type, all applications, including games and demoscene productions, are in a single "APPS" folder.
The "PRIVATE" directory is for third-party use. Multiple <PID> directories may co-exist on the same medium (e.g. if the same SD card is used on different devices).
Preview thumbnails are included in the game directory in BMP format, 160x120 and 320x240 square pixels (two files), true color.
This file is an index of the exported system and application data content, referencing both the short (8.3) and the long names of the exported files. In this way, a single RP-INDEX.INI file may be used by devices with different file system capabilities. Additionally, the file provides configuration information and human-readable application details.
The RP-INDEX.INI file is in INI format. This format was chosen because it is simpler to parse than XML. An INI file consists of sections ("[Section]") and keys ("Key=..."). Applications other than RetroPlatform Player instances generally only need to read this file, not write it.
The current format uses only one section type, namely [Application]. Each [Application] section describes an emulated computer system and the related files, including any application-specific disks. Information is included to select and configure supported computer models, and to group applications by type (games, demos, barebone computer systems, etc.) and genre (game categories, etc.)
[Application] Type=game ; types: game, demo, application, system, etc. Genre=platform Title="Asteroid Invader II" Entity="Acme Games" Year=1986 OID=22.214.171.124.126.96.36.199.9 Preview160="APPS\ASTEROID\PREVIEW1.BMP","APPS\Asteroid Invader II\Preview160.bmp" Preview320="APPS\ASTEROID\PREVIEW2.BMP","APPS\Asteroid Invader II\Preview320.bmp" System=a-500 Video=ntsc Port=0,mouse ; Port numbers are 0/1 for Amiga, but 1/2 for C64 Port=1,joystick AddExpansion=a-501 AddRAM=1048576,fast AddDrive=1,dd ; Add floppy units 1 and 2 (0 is built-in on A500) AddDrive=2,dd ROM="SHARED\ROM\A130.ROM","SHARED\ROM\A130.ROM" ROMKey="SHARED\ROM\ROM.KEY","SHARED\ROM\ROM.KEY" Harddrive="SHARED\HDF\TEST.HDF","SHARED\HDF\Test Long Name.HDF",1 Floppy="APPS\ASTEROID\DISK1.ADF","APPS\Asteroid Invader II\Disk 1.adf",1 Floppy="APPS\ASTEROID\DISK2.ADF","APPS\Asteroid Invader II\Disk 2.adf",1
- References to file names always list the short name followed by the long name
- The long names may include ISO 8859-1 characters that are not part of the 7-bit ASCII set (e.g. "APPS\CD³²\preview160.bmp")
- Port settings and additional peripherals are always relative to the canonical system configuration (which for example may already include a floppy drive)
- Preview images in both 160x120 and 320x240 format are provided (if in doubt, consider that 160x120 may be smaller but better quality, as 320x240 sometimes is the result of upsampling)
This optional, short, fixed-width text file serves to uniquely identify a medium (e.g. an SD card) and the devices to which the medium was exposed (and therefore may need to work with).
Sample RP-MEDIA.ID file:
15C3FA0D-D4D2-11DE-9DEF-0050C2490000 MAXIMIGA-2___-0123456789AB-1___-1___ CLOANTO_-RP9X-0123456789AB-2009-1___
Recognizing a medium (GUID in line 1 of RP-MEDIA.ID file) is helpful for synchronization purposes. (For example, Windows Media Player uses a file named SMPInfo.xml, and Windows Backup uses MediaID.bin for similar purposes.)
Having additional device information (after line 1, one additional line per device) can help RetroPlatform Player understand what application types and data formats are most suitable for export. In line 2 of the above example, the medium was tagged by device "2" (e.g. it could refer to the second product) of manufacturer "MAXIMIGA", having a device ID of "0123456789AB" (which could be a MAC address), and a version of "1.1". Underscore characters may be used for padding at the end of a field, and are ignored when parsing. Hyphen characters are inherited by the GUID syntax, and are similarly used to visually separate fields in the other lines, at fixed positions as in the example.
Devices are encouraged, but not required to use the RP-MEDIA.ID file. If the file does not exist (or if it is empty), RetroPlatform Player will create it. A typical file used on only one device is expected to only consist of two lines of text (one line to identify the medium, one line to identify the device). However, the format is designed to support cross-device portability and compatibility, so multiple devices can add one line each.
Because RP-MEDIA.ID is the most likely file that even the simplest devices may want to not only read, but also create (e.g. when formatting the medium), it is structured with a priority on easy seek and edit. More in detail:
- All lines consist of 36 characters followed by a CR+LF (0x13+0x10) pair
- The only valid characers are: uppercase letters A-Z, numbers 0-9, hyphen and underscore characters
- Hyphen characters (0x2D) are used for visual separation at fixed positions, which are skipped when reading data
- Underscore characters (0x5F) at the end of a group are only used for padding, and are ignored when reading data
For the first line:
- This line is required
- The line contains the 16-byte unique medium identifier GUID in uppercase hexadecimal notation (data is grouped as 8+4+4+4+12 characters, with a "-" separator between each group)
- The GUID may, but does not need to, strictly conform to a specific GUID version guideline. Any sequence of random or pseudorandom data is OK.
For the other lines:
- Each line after the first line is optional
- Each line is device-specific (only one line per device)
- The hex data is grouped as 8+4+12+4+4 characters, with a "-" separator between each group
- The fields are: <PID> (8 characters), product ID (4 characters, decided by owner of <PID>), unique product-specific serial number or other instance (12 characters, e.g. MAC address), product-specific (e.g. firmware) major version (4 characters) and minor version (4 characters)
- Once a device recognizes a line as belonging to that device (by combining the <PID>, the product ID and the product-specific serial number), it may edit that line (e.g. to update the version fields)
- If a device does not find a line that references that device, it may append a line to the end of the file
- If a device needs to delete a line, it may fill it with underscore characters (if moving all data is too complex)
- A line consisting of 36 underscore characters can either be ignored or be considered available for reuse by any applications that needs a line
Devices that support RP-MEDIA.ID are encouraged to look for the file and create it if necessary. If the file is present, devices should scan the file, see if there already is an entry for that device, and add a line if not. If the device is listed, but the version information is incorrect, the line should be updated.
It is safe to link to this page.