Structure of the whdload_db.xml file

About

The whdload_db.xml file is used by the WHDLoad auto-booter to confirm the contents of a supported pre-installed WHDLoad game, and to improve compatibility in the booter by specifying specific emulator settings which may be required to ensure a game loads with minimum effort.

The XML is also used by the Lars Muldjord's SkyScraper to match the LHA packages with the OpenRetro database.

The XML is generated through regular scanning of the popular RetroPlay LHA Installed packages. The scanned packages are then validated against external information to determine whether additional settings should be included. This scanning occurs at-minimum weekly, with the updated XML uploaded via the scanner's own GitHub page.

<whdbooter> Root Element

The highest level element for the XML is <whdbooter> which is used to identify the data set as beinf for this booter.

This element contains the attribute timestamp" which is used to date the dataset. This has the format yyyy=mm=dd at hh:mm:ss'

Example:<whdbooter timestamp="2019-03-29 at 03:00:09"> ... </whdbooter>.

<game> Element

The main child element for the XML is <game> which is used for all entries within the dataset. A single entry is created for each file that has been scanned.

The <game> element does not contain any data, but is used for collecting the sub-elements detailed below.

This element contains two attributes for the purpose of identification.

The attribute filename contains the filename (case senstitive) that has been scanned to produce the <game> element. However, this does not include any file extension.

The attribute sha1 contains the sha1 identification of the file that has been scanned to produce the <game> element.

Example: <game filename="1001StolenIdeas_v1.0_Airwalk" sha1="a24c60e66c9cdb5ca96075d9f4f4ad7eaa900d76"> .... </game>

<name> Element (child of <game>)

This element contains the 'clean' name of the file which has been scanned. This may be used as a fall-back to identify the game within SkyScraper.

Example: <name>BloodNet - A Cyberpunk Gothic</name>

<subpath> Element (child of <game>)

This element contains the Amiga directory, within the LHA file, which contains the game itself. This is required in order to ensure the WHDload auto-booter is able to automatically navigate to the correct sub-folder.

Example: <subpath>AlienBreed3DNoMusicCD32</subpath>

<variant_uuid> Element (child of <game>)

This element contains the OpenRetro "variant_uuid" - a unique indentifier to navigate to the correct database entry, and is used by SkyScraper.

Example: <variant_uuid>6ef71e21-2119-5f8d-a239-e9e6efbcec69</variant_uuid>

<slave_count> Element (child of <game>)

This element contains the number of available WHDLoad .slave files within the archive. This will be used to allow Amiberry to select which slave file should be used by user preference from the GUI.

Example: <slave_count>2</slave_count>

<slave_default> Element (child of <game>)

This element contains the filename of the WHDLoad .slave files which will be used by default by the auto-booter.

Example: <slave_default>BrianLarasCricket96.Slave</slave_default>

<slave_libraries> Element (child of <game>)

This element contains a boolean true/false value to inform the auto-booter whether additional library files (eg. XPK cruncher libraries) should be made available for the purpose of compatibility. If unpsecified, this is assumed to be 'false'.

Example: <slave_libraries>False</slave_libraries>

<slave> Element (child of <game>)

All of the available slave files from within the scanned archive will be collected and detailed within the sub-elements of the <slave> node.

The <slave> element does not contain any data, but is used for collecting the sub-elements detailed below.

The attribute number contains an incremenatal reference number for each entry in the <slave> element.

Example: <slave number="3"> .... </slave>

<filename> Element (child of <slave>)

This element contains the slave file's filename (case senstitive) from the archive has been scanned to produce the <slave> element.

Example: <filename>BrianTheLionAGA.Slave</filename>

<datapath> Element (child of <slave>)

This element contains the data path which has been read from the slave file's header and is used to specify any sub-folder which contains the necessary game data

Example: <datapath>Fed1</datapath>

<custom> Element (child of <slave>)

This element contains the WHDLoad slave CUSTOM options which have been read from the slave file's header. These may be used to select preferential patches such as alternative level sets, trainers, or specific fixes which differ from the original game.

These parameters will be used to allow Amiberry to select which CUSTOM options should be used by user preference from the GUI.

For details of the syntax of this information please refer to the WHDLoad technical documentation

Example:

			<custom>
			C1:X:Unlimited Lives:0
			C1:X:Invincibility:1
			C1:X:Start with Full Extra Equipmemt:2
			C1:X:In-Game Keys (Press HELP during game):3
			C2:L:Start at Level:1,2,3,4,5,6
			</custom>

<hardware> Element (child of <game>)

This element contains the options which will be automatically applied by the WHDLoad booter for this auto-loading of the game for the purpose of compatibility. This includes whether a game's default control method should be the Joystick or a Mouse, CPU settings to be applied, RAM etc.

The following settings are available, with the options for each seperated by a slash / in the below.

PRIMARY_CONTROL=MOUSE/JOYSTICK
SECONDARY_CONTROL=MOUSE/JOYSTICK
PORT0=MOUSE/JOY/CD32
PORT1=MOUSE/JOY/CD32
FAST_COPPER=TRUE/FALSE
CPU=68000/68010/68020/68040
BLITTER=NORMAL/WAIT/IMMEDIATE
CLOCK=7/14/25/28/MAX (25 and 28 are the same)
CHIPSET=OCS/ECS/AGA
JIT=TRUE/FALSE
CPU_24BITADDRESSING=TRUE/FALSE
CPU_COMPATIBLE=TRUE/FALSE
SPRITES=NONE/PLAYFIELD/SPRITES/FULL
SCREEN_WIDTH=640/704/768 (or any number)
SCREEN_HEIGHT=400/512/576 (or any number)
SCREEN_AUTOHEIGHT=TRUE/FALSE
SCREEN_CENTERH=SMART
SCREEN_CENTERV=SMART
SCREEN_OFFSETH=
SCREEN_OFFSETV=
NTSC=TRUE/FALSE
NTSC=TRUE/FALSE
FAST_RAM=1/2/4/8
Z3_RAM=16/32/64/128
CPU_EXACT=TRUE/FALSE (only supported on 68000)

Note: The hardware parameters are set at a 'game' level and not for each slave file. As a result these settings should be able to accomodate the running of any slave contained within a single archive.

Example:

		<hardware>
		PRIMARY_CONTROL=JOYSTICK
		PORT0=JOY
		PORT1=JOY
		JIT=FALSE
		SCREEN_HEIGHT=512
		
		</hardware>

<custom_controls> Element (child of <game>)

This element contains custom control options which will be automatically applied by the WHDLoad booter for this auto-loading of the game for the purpose of RetroArch style controller compatibility. This is intended to remove (where possible) keyboard dependencies within games, including remapping of (for example) third player keyboard controls onto an additional controller input.

Example:

joyport2_amiberry_custom_none_dpad_up=Cursor Up
joyport2_amiberry_custom_none_dpad_down=Cursor Down
joyport2_amiberry_custom_none_dpad_left=Cursor Left
joyport2_amiberry_custom_none_dpad_right=Cursor Right
joyport2_amiberry_custom_none_south=Right Shift

whdload_db.xml Example Entry

<?xml version="1.0" encoding="UTF-8"?>
<whdbooter timestamp="2019-03-29 at 03:00:09">
	<game filename="Bloodwych&amp;ExtendedLevels_v2.51_0439&amp;0043"  sha1="f0bb11fdbb8526d7430bc3b0c4ddbfa574594602">
		<name>Bloodwych (&amp; Extended Levels)</name>
		<subpath>Bloodwych&amp;ExtendedLevels</subpath>
		<variant_uuid>5c20d783-8515-54ef-946f-519cf71a7bd6</variant_uuid>
		<slave_count>2</slave_count>
		<slave_default>Bloodwych.Slave</slave_default>
		<slave_libraries>False</slave_libraries>
		<slave number="1">
			<filename>Bloodwych.Slave</filename>
			<datapath>data</datapath>
			<custom>
			C1:B:Skip Intro
			C2:X:Swap Keyboard Controls:0
			C2:X:Alternative Keyboard Controls:1
			C3:X:Enable CD32 Mode:0
			C3:X:Hold-to-walk CD32 Controls (Player 1):1
			C3:X:Hold-to-walk CD32 Controls (Player 2):2
			
			</custom>
		</slave>
		<slave number="2">
			<filename>ExtendedLevels.Slave</filename>
			<datapath>data</datapath>
			<custom>
			C1:B:Skip Intro
			C2:X:Swap Keyboard Controls:0
			C2:X:Alternative Keyboard Controls:1
			C3:X:Enable CD32 Mode:0
			C3:X:Hold-to-walk CD32 Controls (Player 1):1
			C3:X:Hold-to-walk CD32 Controls (Player 2):2
			
			</custom>
		</slave>
		<hardware>
		PRIMARY_CONTROL=MOUSE
		PORT0=MOUSE
		PORT1=JOY
		SCREEN_HEIGHT=400
		
		</hardware>
	</game>
</whdbooter>