Software List Format

For software lists, we have tried to keep the format as simple as possible. However, the ambitious goal of describing software items for such a wide class of systems going from gaming consoles to home computers and to calculators, has required some complexity.

This Wiki page tries to cover the basics of the format (and some not-so-basic aspects) both for frontend maintainers and list creators.

The <softwarelist> element

First of all, an xml software lists consists of a <softwarelist> </softwarelist> couple enclosing all the software entries. Attributes for the software list are a “name” and a “description”. The former should match the xml name itself, the latter can be used to better explain what kind of software the list contains. As an example, you can take snes.xml, where you can find

<softwarelist name="snes" description="Nintendo SNES cartridges">

In the following we analyze the various components that can (or must) be used in a software list.

The <software> element

The basic idea (which leads basically the whole format) is that each <software> entry should correspond to a game box you could have bought in a shop, and that each <part> entry should correspond to a piece (i.e. a cart, a disk or a tape) that you would have found in such a box.

As such, a typical software item is as follows

<software name="shortname" [cloneof="parentname"] [supported="partial"]>
	<description>Game Title (Region, vx.x, Alt)</description>
	<year>19??</year>
	<publisher>Software House</publisher>
[snip]
</software>

where 'name' is the shortname that will identify this software item at loading, the optional 'cloneof' attributes is the name of its parent (so that MESS knows where to search files if not found in shortname.zip) and the optional 'supported' attributes indicates if the game is known not to work due to missing components of the emulation (notice that this is not used for e.g. imperfect video or sound emulation, but only to mark items which require some unemulated component, like a specific bankswitch mapper or some missing add-on circuitry)

The <description> entry should uniquely identify the software item inside the list and it should match the title screen, when this is available. In the case of games with no title screen (e.g. for old console and computer games), the box title is fine, of course.

The <year> and <publisher> elements should document the release year and the software house which have published the specific game. Notice, however, that differently from MAME these might differ from the year and copyright holders appearing in the title screen. Indeed, as it happens quite often that the title screen is not updated when e.g. a localization is released a few years after the original release, see gameboy.xml and gba.xml for a few examples.

A few recommendations for list authors:

  1. Try to use MAME shortnames when it is possible: it makes easier to launch from command line
  2. For software with Unknown publisher, please use <unknown>. This matches MAME/MESS convention for systems and makes easier sorting in frontends (no conflicts with possible “Unknown Software Inc.” companies
  3. Remember that you need unique shortnames and descriptions across an xml file; and remember that shortname have to be at most 8 chars long for parent sets and 12 chars long for clones. MESS errors out at violations.
  4. Unless the system you are 'listing' requires ad-hoc handling, please try to follow the few naming guidelines below

Inside each <software> element

A typical entry for an hypothetical game consisting of a cart and a cdrom is like the following

<part name="cart" interface="xxx_cart">
	[snip]
	<dataarea name="rom" size="1310720">
		<rom name="romname.bin" size="262144" crc="aaaaaaaa" sha1="aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee" offset="000000" loadflag="load16_word_swap" />
		<rom size="262144" offset="0x100000" loadflag="continue" />
	</dataarea>
</part>

<part name="cdrom" interface="xxx_cdrom">
	[snip]
	<diskarea name="cdrom">
		<disk name="diskname.chd" sha1="aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee" />
	</dataarea>
</part>

As you can see, we have <part>s, <dataarea>s and <rom>s (resp. <part>s, <diskarea>s and <disk>s, for CHD) A few comments are in order here: first, you should basically have one <part> for each physical item that you could find inside the game box! E.g. for a game consiting of two CD-ROM, you would find two parts (probably named “cdrom1” and “cdrom2”), and for a game consisting of 5 floppies, you would find five parts (probably named “flop1”,…,”flop5”).

Then, inside the <part> you have to put the rom/disk data that MESS have to load. In order to match MAME conventions (so that we can share the necessary code), we have split this into two separate entities: <dataarea> and <rom>. <dataarea> is a translation of ROM_REGION and <rom> is an almost 1:1 translation of ROM_LOAD, with the some minor differences related to FILL/RELOAD/CONTINUE usage…

If you are used to work on MAME drivers, you should feel at home. Otherwise, you might appreciate the presence of both <dataarea> and <rom> with the following cartridge examples (disks, tapes and cdroms do not heavily use multiple dataareas). If you are trying to emulate a cartridge for a system like SNES, whose CPU reads the data as a single block of memory, no matter if contained in one or more chips, then you can use a single <dataarea> and fully load it/access it at start like a real cart would be. But if you are trying to represent a cartridge for a system like NES or Vic20, where the CPU can separately access the content of different chips (or different groups of chips), then it is easier to split the data into multiple dataarea and load them separately in memory. In the NES case, for example, we have a dataarea for PRG data, a dataarea for CHR and possibly a dataarea for SRAM (be it PRGRAM or CHRRAM, depending on the mapper).

Concerning the <rom> and <disk> elements, they basically match MAME macros ROM_LOAD and DISK_LOAD: for each rom/disk you have to specify

  • a filename (possibly in the format “chip label”.location or “disk label”, like in MAME)
  • size, CRC32 and SHA1 of the uncompressed file (only the internal SHA1 for CHD disks)
  • an offset (not necessary for CHD) to specify at which position in the dataarea the file should be loaded

A few recommendations for list authors:

  • for part name attribute, please chose names corresponding to the media switch that you need to use at command line (i.e. -cartN, -flopN, -cassN, -cdromN…): it makes easier to load specific parts from the command line without checking the attribute in the xml each time
  • for part interface attribute, in the case of floppy disks please stick to standard “floppy_3_5”, “floppy_5_25” and “floppy_8”. This allows loading of disks which contain multiple data formats (e.g. hybrid PC and C64 disks etc.)
  • for dataarea name attribute, please stick to tags which resemble media (rom, flop, cdrom). this ensures that there will be no conflicts with the memory region tas used for the system itself

Emulation/Frontend info elements

The format also has three different kinds of 'extrainfo' that can be used for several different goals: <feature>, <sharedfeat> and <info>.

<feature> elements: these are linked to a specific <part> element, e.g. a cart or a floppy, and got introduced to store info necessary for the emulation itself. Typical examples are given e.g. the pcb_type of the cart, or the kind of SRAM on the cart, or the presence of additional CPUs (see e.g. nes.xml, aes.xml or megadriv.xml). At loading time such features can be checked and MESS can setup the emulation accordingly. In addition to this usage, <feature> can be also used to store other kind of info which specifically belongs to the part. E.g. a list of the pcb components with respective locations (see snes.xml) or a specific label which identify the floppy or cdrom in a multi-disc game (see cdi.xml or x1_flop.xml).

Examples:

<feature name="pcb_type" value="MMC3C"/>
<feature name="u3" value="SRAM-64M"/>
<feature name="part_id" value="Map Disk"/>

<sharedfeat> elements: these are basically the same as <feature> elements (and indeed MESS stores them internally in the same way as features) but can be listed in the main <software> entry, rather than in the single <part>s. As the name suggest, you can use a <sharedfeat> to prescribe a feature to be added to each <part> of your software. E.g. if your software entry consists of 9 floppies, you can define a single “compatibility” <sharedfeat> which will be inherited by *all* the disks instead of manually adding nine <feature>s, one per disk. You can consider this as a shortcut for <feature> when you have multidisk software.

Examples:

<sharedfeat name="compatibility" value="EUR-JPN"/>  (the values have to be parsed on a per-driver base, there is no compatibility check in the core)
<sharedfeat name="addon" value="DVC"/>

<info> elements: these can be added to the main <software> entry, like the <sharedfeat>, but they should be used for more general information than shared feature. In simple terms, <sharedfeat> should be used for info required by the emulation itself, while <info> should be used for info that can help frontends and users. They can be used to store the serial ID of the games, or alternative titles (like the Japanese one, or the title on the box if different from the title screen), or the name of the developer studio (e.g. Treasure for Gunstar Heroes) or small usage instructions. However, mind that <info> is not meant to replace an external datfile, and as such it should not be used to store things like ingame languages, or game category, or game instructions, etc. anyway, it's up to the list creator to decide what to use this for or whether to use it at all

Examples:

<info name="developer" value="Treasure"/>
<info name="serial" value="NUS-NSMJ-JPN"/>

Minor Elements

If you look at the DTD declaration we use, you will notice that in addition to the nodes I have described above, there is also a <dipswitch> entry that can be used inside a <part>. Its sintax is the same as the MAME one, e.g.

<dipswitch name="Show Time" tag="DSW2" mask="1">
	<dipvalue name="No" value="0"/>
	<dipvalue name="Yes" value="1" default="yes"/>
</dipswitch>

and can be used for cartridge which have switches on it. some examples are in nes.xml, even if MESS cannot handle these yet during the emulation.

Naming Conventions

Differently from other projects, in MESS we don't currently enforce a precise naming standard. Anyway, we follow when possible MAME: the title should match the title screen when a title screen is available (but some flexibility is allowed: in some portable systems the game box might be more precise than the ingame screen, if e.g. programmers had to split the title in several screens due to hardware limitations) and the title should be kept short and simple whenever possible.

A bunch of examples:

  • if a system was only released in a specific country or region, there is no need to specify any country flag after the title (e.g. “Daiva” and not “Daiva (Jpn)” when dealing with Japanese home computers);
  • available languages flags should only be added if there is no other way to differentiate two entries: e.g. “ATV - Quad Power Racing (Euro, Rev. 1)” is enough to differentiate it from its first release “ATV - Quad Power Racing (Euro)”, without the need of specifying that more languages were available in the newer revision; on the other hand, “Creatures (Euro, English / Italian / Spanish)” and “Creatures (Euro, English / French / German)” are perfectly fine if there is no confirmation about some carts being only released in specific countries