Obsolete Article
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).
Overview
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.
<PID> Tag
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.
RP-INDEX.INI
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.)
For example:
[Application]
Type=game ; types: game, demo, application, system, etc.
Genre=platform
Title="Asteroid Invader II"
Entity="Acme Games"
Year=1986
OID=1.2.3.4.5.6.7.8.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
Notes:
- 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)
RP-MEDIA.ID
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.
Related Links