Guidelines for Software Lists¶
MAME’s software lists describe known software media for emulated
systems in a form that can be used to identify media image files for
known software, verify media image file integrity, and load media
image files for emulation. Software lists are implemented as XML
files in the
hash folder. The XML structure is described in the
Philosophically, software list items should represent the original media, rather than a specific dump of the media. Ideally, it should be possible for anyone with the media to dump it and produce the same image file. Of course, this isn’t always possible in practice – in particular it’s problematic for inherently analog media, like home computer software stored on audio tape cassettes.
MAME strives to document the best available media images. It is not our intention to propagate corrupted, truncated, defaced, watermarked, or otherwise bad media images. Where possible, file structures matching the original media structure are preferred. For example we prefer individual files for separate ROM chips in cartridge media, and we use disk images rather than archives of files extracted from the original disks.
A software list is a collection of items and each item may have multiple parts. An item represents a piece of software, as distributed as a complete package. A part represents a single piece of media within the package. Parts can be mounted individually in emulated media devices. For example a piece of software distributed on three floppy disks will be a single item, while each floppy disk will be one part within that item.
Sometimes, logically separate parts of a single physical piece of media are represented as separate parts within a software item. For example each side of an audio tape cassette is represented as a separate part. However individual ROM chips within a cartridge may be separate files, but they are not separate parts, as the cartridge is mounted as a whole.
Each item is a
software element. The
software element may have
the following attributes:
- name (required)
The short name identifying the item. This is used for file names, command line arguments, database keys, URL fragments, and many other purposes. It should be terse but still recognisable. It must be unique within the software list. Valid characters are lowercase English letters, decimal digits and underscores. The maximum allowed length is sixteen characters.
- cloneof (optional)
The short name of the parent item if the item is a clone. The parent must be within the same software list – parent/clone relationships spanning multiple software lists are not supported.
- supported (optional)
One of the values
yes(fully usable in emulation),
no(not usable in emulation), or
partial(usable in emulation with limitations). If the attribute is not present, it is equivalent to
yes. Examples of partially supported software include games that are playable with graphical glitches, and office software where some but not all functionality works.
Each part is a
part element within the
software element. The
part element must have the following attributes:
- name (required)
The short name identifying the part. This is used for command line arguments, database keys, URL fragments, and many other purposes. It must be unique within the item. It is also used as the display name if a separate display name is not provided. Valid characters are lowercase English letters, decimal digits and underscores. The maximum allowed length is sixteen characters.
- interface (required)
This attribute is used to identify suitable emulated media devices for mounting the software part. Applicable values depend on the emulated system.
Software lists support various kinds of metadata. All software list items require the following metadata elements to be present:
This is the primary display name for the software item. It should be the original name of the software, transliterated into English Latin script if necessary. It must be unique within the software list. If extra text besides the title itself is required for disambiguation, use lowercase outside of proper nouns, initialisms and verbatim quotes.
The year of release or copyright year for the software. If unknown, use an estimate with a question mark. Items can be filtered by year in the software selection menu.
The publisher of the software. This may be the same as the developer if the software was self-published. Items can be filtered by published in the software selection menu.
Most user-visible software item metadata is provided using
info element must have a
name attribute and a
value attribute. The
name attribute identifies the type of
metadata, and the
value attribute is the metadata value itself.
name attributes do not need to be unique within an item.
info elements with the same
name may be present if
appropriate. This is frequently seen for software sold using different
titles in different regions.
MAME displays metadata from
info elements in the software selection
menu. The following
name attributes are recognised specifically,
and can show localised names:
Used for alternate titles. Examples are different tiles used in different languages, scripts or regions, or different titles used on the title screen and packaging. MAME searches alternate titles as well as the description.
Author of the software. Items can be filtered by author in the software selection menu.
Barcode number identifying the software package (typically an EAN).
Developer responsible for implementing the software. Items can be filtered by developer in the software selection menu.
Party responsible for distributing the software to retailers (or customers in the case of direct sales). Items can be filtered by distributor in the software selection menu.
ISBN for software included with a commercial book.
Original equipment manufacturer, typically used with customised versions of software distributed by a hardware vendor.
The original publisher, for items representing software re-released by a different publisher.
Distributor’s part number for the software.
Printed circuit board identifier, typically for cartridge media.
Programmer who wrote the code for the software.
Fine-grained release date for the software, if known. Use YYYYMMDD format with no punctuation. If only the month is know, use “xx” for the day digits. For example
Number identifying the software within a series of releases.
Version number of the software.