Game definition standard (GDS) is a standard for creating key and button definitions for emulators. When you use an emulator on a console or a cell phone, there is always a problem about controls. Even on a PC with a hundred keys on the keyboard, setting up controls remains as a problem. You have to configure host machine’s control buttons, keys or joysticks to emulated machine’s accessories. Even this might not be enough, because not every game uses same way to control a character, navigate into menus or start the game.

GDS provides convenient method for generalize controls over different host platforms and on different emulated software by using XML engine.

Goals

The main goal of this project is to bring a standard to the emulation scene, when playing games on different hosts and on emulated platforms with varying control methods. With GDS, all games on all platforms will play on host machine’s native controls without needing any prior configuration. You just load the game and start playing immediately regardless that you are using a pc, a handheld, a console or a cell phone.

Why XML?

While harder to parse and integrate into emulators, XML is a widely used format. To cope with parsing problem, there are numerous open source xml parsers out there.

We use XML because while it maintains human readability, it also provides multiple configurations in one gds file.

Terminology

*to do*

Structure

A GDS file is an XML file, and conforms to XML standards which can be found at http://www.w3.org/TR/REC-xml/. Following elements, attributes and values are defined to use in a game definitions standard file:

GDS data, GDS File type and usage

GDS, “Game Definition Standard” is not only a key assignment library, but it’s also stores comprehensive information about a game.

GDS files must conform to XML 1.0 standard.

A GDS file may contain one or more games in it. Common usage of the GDS files like this:

It_came_from_desert.tzx

It_came_from_desert.gds

You provide a GDS file for every game image in the folder. We call this usage as “GDS pairs”.

When talking about handheld devices, storage is another problem. So GDS provides another solution to storing GDS data: it’s possible to merge all those files to form a single big “GDS archive”. A gds data is formed to create an information hierarchy to make it easy to separate one game’s information from another in an archive. When merged into one file, the gds archive must be named as “gds_archive.gds”.

When emulator checks if there is a GDS file associated to a game, “GDS pairs” always supersedes a “GDS archive”. That means, if there is a “pair” for a game, an emulator never searches for a “GDS archive” unless the pair is broken or invalid. If there is no pair for a game, emulator first checks if there is a “gds_archive.gds” file in the game directory, if it’s there, it will search for the game entry by checking either game name (if that information is available to emulator) or game file names. Those fields are only mandatory fields in a GDS file.

Types

Following data types are used in the GDS specification:

Type	Description
TwoPartNumber	A simple type contains version information eg. “1.2” (0-65535.0-65535)
path	Windows based path string. In a path string /\*?:”<>\| characters not allowed.
BoundedString	A string which preserves white space and max. 512 chars long.
Number	A simple type contains an integer number.
String	A string which preserves white space and max. Up to 65535 chars long.
Bool	A Boolean value, either “False” or “True”.

GameDefinitionStandard (Root element)

GameDefinitionStandard, is the root element and it contains one or more game definitions.

This element has one sub-element: GameDefinition

< GameDefinitionStandard>

…One or more game definitions…

</ GameDefinitionStandard>

GameDefinition (GameDefinitionStandard >)

This is the main element that holds all the data about a game and key bindings. This element has five attributes:

GameName, Version, Creator, Generator,Set

Name	Type	Mandatory	Description
GameName	Bounded String	Yes	GameName is uniquely identifies your game to the emulator. It may be taken from a big database, or may be pre-set by the creator of the game. Stay true to the game in question’s name. Sometimes games have different names across platforms. In this case, try to find oldest/original version’s name, and put other names to <gameinformation> block.
Version	TwoPart Number	Yes	GDS definition version for this entry. It starts from 0.1 as of this document.
Creator	Bounded String	No	Creator of GDS file
Generator	Bounded String	No	The Tool used when creating GDS file
Set	Number	No	This is autogenerated by OGDS system to identify multiple keymappings for the same game. Usually set 0 is assigned for Default keymap for a game. If you want to autoload a keymap from a GDS file, check if there is a set “0”. Note that this value is not mandatory, “Set” is just a helper for OGDS system to handle server requests, it may not be there if a GDS file prepared by hand on a text editor.

This element has one sub-element: Platform

Example

Platform (GameDefinitionStandard > GameDefinition >)

This element specifies the definition file is specially to be played on a specific emulated machine. It must be declared before any MAP binding.

It has a set of optional sub items with additional attributes: “Hardware”, “Model”,”Version”. Declaring one of those attributes makes that definition only used by that specified hardware or model. If PLATFORM attributes are empty, the definition is shared by different platforms and models.

Name	Type	Mandatory	Description
Hardware	Bounded String	No	Defines the hardware brand, e.g. Commodore, Sinclair, Amstrad, Nintendo, Gamepark,.
Model	Bounded String	No	Defines the hardware model. E.g. Amiga, ZX Spectrum +, CPC464, GP32, ZX Spectrum Vega etc.
Mode	Bounded String	No	Defines the hardware mode: 48K, 64K, 128K, 50hz, 60hz etc.
Version	Bounded String	No	Hardware or OS version. E.g. 3.5, 3.9, 1.0B. Note that this attribute is a string.

This element has following optional sub-elements: GameFilename, ControlAssignment and GameInformation

Examples

… definition is declared for any computer produced under Sinclair brand…

</Platform>

…definition is declared only for commodore 64 model…

</platform>

…definitions will be shared on all platforms…

</platform>

GameFileName ( Platform >)

This attribute may be required to identify game to the emulator, yet may be ignored by it. This attribute is highly recommended. A Platform element may include more than one GameFileName element under it. If you don’t provide this element, and no hash element is present, your definition cannot be accessible.

Example

<GameFileName>somegame.tzx</Gamefilename>

<GameFileName>somegame.z80</Gamefilename>

<GameFileName>somegame.sna</Gamefilename>

<GameFileName>somegame.szx</Gamefilename>

… Definitions go here

</Platform>

Hash ( Platform >)

While filenames are not very consistent as users may change filenames, a hash can be used instead or in conjunction with GameFileName element. A hash type is a CRC32, MD5, SHA1 or SHA2 hash. Element data holds the hash value.

Name	Type	Mandatory	Description
Type	Bounded string	Yes	The hash type. Valid strings are: CRC32, MD5, SHA1 or SHA2 Note that as hashing algorithm advances, more CPU and storage required. Low power emulators may not support SHA2 or even MD5. CRC32 Checksum is very cheap way to check a file’s redundancy, so it’s recommended you provide a CRC32 checksum if possible.

Example

        <Hash type=”MD5”>e4d909c290d0fb1ca068ffaddf22cbd0</Hash>

Sign (Platform>)

SIGN is the signature of a game used for identifying the game without using filename or a hash. It is a BASE64 string that converts into a imprint of emulated ram. Address is a starting address of an imprint, and data part is the imprint itself. An emulator may match this imprint in it’s memory to identify a game. Note that this element is autogenerated by GDS system and the imprint is the result of extensive ram image research.

Name	Type	Mandatory	Description
Address	Number	Yes	Start Address of a signature

Example

TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5I

</Sign>

ControlAssignment ( Platform >)

This attribute encapsules all key bindings and macros. It consists of one or more ALT entries.

Example

<ControlAssignment>

… Definitions go here

</ ControlAssignment >

</Platform>

ControlAssignment element has one sub-element: ALT

ALT (Platform > ControlAssignment >)

GDS supports different setups and ways to cycle between them. ALT tag sets a new set of controls to each host button. Every mapping set starts with an “ALT” tag. Attributes follows. While there is no limit on creating alternate key configurations, we should keep in mind that mobile devices usually are low on resources, and possibly there may be not enough memory to store alternate setups. To stay on the safe side, try to limit your alternate setup count to four.

Name	Type	Mandatory	Description
ID	BoundedString	Yes	A unique id for the button set.
Description	BoundedString	No	A description of the set of keys.
Default	Boolean	No	This attribute makes the alternative set as default controls. It will be the active control set when launching a game. You should specify at least one default attribute. If you don’t specify the default attribute in the any of the alternate setup it will be up to the emulator to choose one of them, you cannot guarantee which control set will be used.

Examples

<ALT id=”main” description=”Movement” Default=”True”>

</MAP>

</ALT>

<ALT id=”inv” description=”inventory keys”>

</MAP>

</ALT>

MAP (ControlAssignment > ALT >)

Map tag, assigns one or more virtual key to one or more host button. Note that this is a macro container element. A GDS macro is a sequence of commands to perform by the emulator.

When creating a macro, it’s recommended it may took less than 60 seconds. A macro timeout default is 60 seconds, but an emulator designer may put facilities to adjust this limitation, or ignore it.

An emulator should process all the MAP sub elements and plays them from top to bottom, in a same cycle. Only WAIT element stops a macro temporarily. Please see examples at the end of this document for macros.

Name

Type

Mandatory

Description

Button

Button

Yes

Host button to assign. You can find all available button constants at the next part of this document.

Description

BoundedString

Assigns a description to assigned key. If you don’t provide a description, default one will be used. Default descriptions are the same as the element name but without the “B_” prefix.

Eg.” B_START”’s default description is “START”, “B_UP”’s is “UP”…

Examples

…mapped virtual key assignments and/or macros…

</MAP>

….assignments…

</MAP>

ASSIGN ( ControlAssignment > ALT > MAP >)

Copies the host button behavior to virtual key. If user presses the button for 1 sec, Virtual key will be pressed for exactly 1 second. This is the most basic assignment command. “Assign” generally is not used in the macros as it creates an interactive assignment and may produce unexpected results. You may use multiple assign elements under a MAP element. They will be pressed together. ASSIGN element has priority over any other element in a MAP element.

Name	Type	Mandatory	Description
Key	Vkey	Yes	Virtual key to be assigned

Example

<ASSIGN key=”VK_Q”/>

</MAP>

SWITCH ( ControlAssignment > ALT > MAP >)

This tag switches settings between alternate setups. Switch is a way to assign a button to jump to a different “ALT”.

Name	Type	Mandatory	Description
Alt	String	Yes	Alternate Location ID
Clear	Bool	No	Clear attribute clears all assignments to GDS_DUMMY before making a switch. Default setting for this attribute is “False”. So assignments will be carried to alternate setups if they are not set in the alternatives.

Examples

</MAP>

</ALT>

</MAP>

</ALT>

HOLD ( ControlAssignment > ALT > MAP >)

This is a MACRO command. It causes the virtual key to press and hold until the end of macro sequence, until a RELEASE command encountered.

Name	Type	Mandatory	Description
Key	Vkey	Yes	Virtual key to be assigned

Example

<HOLD key=”VK_Q”/>

</MAP>

RELEASE ( ControlAssignment > ALT > MAP >)

This element causes all HOLD keys to release.

Example

<RELEASE/>

</MAP>

LOCK ( ControlAssignment > ALT > MAP >)

This is a MACRO command. It causes the the actual controller button dumb until the end of macro.

Normally a macro should reset if a user represses the button before finishing a macro, LOCK element prevents this behavior. If a macro is played while LOCKed, user cannot press the button again to restart the macro. At the end of MAP command the button will return to previous state.

Note that there is no UNLOCK element. When you LOCK a button, it will not be released until the macro ends or a timeout (60 sec) occurs.

Example

<LOCK/>

…other macro commands

</MAP>

WAIT ( ControlAssignment > ALT > MAP >)

This is a MACRO command. It causes a macro to stop and wait for desired miliseconds or an exact value in emulated RAM. If there is no attribute is assigned for WAIT command, it waits for 100 milliseconds (5 video frames for a PAL system).

Name	Type	Mandatory	Description
Duration	Number	No	Milliseconds to wait
Address	Number	No	A ram location to check for a value

Example

<WAIT/>

…waits for 100 milliseconds

<WAIT Duration=”1000”>

…waits for 1 second

<WAIT Address=”22552”>56</WAIT>

…waits until RAM location 22552 equals 56.

</MAP>

FIX ( ControlAssignment > ALT > MAP >)

This is a MACRO command. Fix command modifies a byte in the emulated RAM.

Name	Type	Mandatory	Description
Key	Vkey	Yes	Virtual key to be assigned

Example

<HOLD key=”VK_Q”/>

</MAP>

ECHO ( ControlAssignment > ALT > MAP >)

This is a MACRO command. It sends a message to the emulator. Emulator may (or may not) print this message to it’s console or directly on screen. If it displays this message to the user, gds creator may include a duration to keep the message on screen for a period of a time, up to macro timeout limit (default is 60seconds). This Duration will NOT stop the macro. ECHO commands generally ignored or turned off default by emulators. Use descriptions to pass messages to the user.

Name	Type	Mandatory	Description
Duration	Number	No	Message visibility duration in milliseconds. Not every emulator support this attribute.

Example

<ECHO>Hello World!</ECHO>

</MAP>

KEY Constants

Basic Controls

The basic controls include a directional pad, two action buttons, a select and a start button.

Name	Recommended Usage
B_SELECT	Switching between alternate configurations, options, menus or pause.
B_START	To start a game. Provide a macro if needed.
B_ UP	Cursor/Character Movement
B_ DOWN	Cursor/Character Movement
B_ LEFT	Cursor/Character Movement
B_ RIGHT	Cursor/Character Movement
B_FIRE1	Main Action Button
B_FIRE2	Secondary action button
B_TOOL1	A tool button for assign utility keys (eg. QuickSave)
B_TOOL2	Another tool button (eg.QuickLoad)

The best binding is made by assigning all buttons (including additional buttons) to some function/virtual key. But in many cases this is not possible. But a binding never complete without all of the above buttons have an assignment, never leave above buttons unassigned.

Additional Buttons

Use additional buttons if the game only and ultimately requires more buttons, even in this case, try to fit most basic functions to above keys. Keep in mind handheld devices usually does not have those extra keys. And using those keys usually renders your GDS definition unusable by those devices.

B_FIRE3…31

B_LTHUMB1

B_LTHUMB2

B_LTHUMB3

B_RTHUMB1

B_RTHUMB2

B_RTHUMB3

B_SHOULDER1

B_SHOULDER2

B_SHOULDER3

B_SHOULDER1

B_SHOULDER2

B_SHOULDER3

B_TOOL3…31

CELL PHONE SPECIFIC CONTROLS

B_YES

B_NO

B_CPAD_UP

B_CPAD_DOWN

B_CPAD_LEFT

B_CPAD_RIGHT

B_MENU

THE DEVICES WITH KEYBOARD

B_KEY_A…Z

B_KEY_0…9

ZX Spectrum Vega Buttons

Zx Spectrum Vega is the main driving force beyond OGDS v0.2. Unfortunately zx vega controller is not a common one. Due to public demand designers added four extra buttons on Vega. With these, configurable button count reached to 11. Base controls for GDS system is for 10 buttons. Following table is for Vega GDS Standardization for generic Platform element.

It’s also OK to use B_KEY_ for buttons FS12ABC as long as you fill out the PLATFORM attribute Model=” ZX Spectrum Vega”. Note that this makes your GDS specific to vega platform, other emulators may ignore your definitions.

Name	Vega Button
B_SELECT	1
B_START	S
B_ UP	Up
B_ DOWN	Down
B_ LEFT	Left
B_ RIGHT	Right
B_FIRE1	F
B_FIRE2	2
B_TOOL1	A
B_TOOL2	B
B_KEY_C	C
B_MENU	M (this button is not reconfigurable on Vega)
B_KEY_R	R (this button is not reconfigurable on Vega)

Virtual Keys

These keys represent the emulated key, for example, a key press event on a emulated machine. There may be different keys in different machines, e.g. Apple key on an old Macintosh computer. Or set of control keys on an atari800XL or c64 Platform. Those keys will be added in later revisions of this document.

As first version intended to be used in Zx Spectrum Platform Emulators, only special spectrum keys are listed here:

Name	Description
VK_0..9	Numbers on keyboard above the letters, not the numeric part of the keyboard.
VK_A..Z	Keys of the keyboard, A to Z (ANSI Characters only)
VK_CAPSSHIFT	Caps Shift key on ZX Spectrum
VK_SYMBOLSHIFT	Symbol Shift key on ZX Spectrum
VK_ENTER	Enter Key on Zx Spectrum
VK_KEYCODE_0…255	Keyboard input codes on emulated machine. Those constants are for special keys, not listed on this listing.
VK_JOY1_UP	Joystick PORT 1 on emulated machine (Sinclair in this case)
VK_JOY1_DOWN	“
VK_JOY1_LEFT	“
VK_JOY1_RIGHT	“
VK_JOY1_FIRE1	“
VK_JOY1_FIRE2	“
VK_JOY2_UP	Joystick PORT 2 on emulated machine (Sinclair in this case)
VK_JOY2_DOWN	“
VK_JOY2_LEFT	“
VK_JOY2_RIGHT	“
VK_JOY2_FIRE1	“
VK_JOY2_FIRE2	“
VK_KEMPSTON_UP	Kempston Joystick on a ZX Spectrum
VK_ KEMPSTON_DOWN	“
VK_ KEMPSTON_LEFT	“
VK_ KEMPSTON_RIGHT	“
VK_ KEMPSTON_FIRE1	“
VK_ KEMPSTON_FIRE2	“
VK_ KEMPSTON_FIRE3	“
VK_MOUSE_X	Generic Mouse on a emulated machine X axis
VK_MOUSE_Y	“, Y axis
VK_MOUSE_L	Left mouse button
VK_MOUSE_R	Right mouse button
VK_MOUSE_M	Middle mouse button

Planned Virtual Keys

Following keys are not need to be supported right now, but it will be added to the later revisions of GDS format. You can use them if you need any.

VK_SHIFT	Generic Shift key
VK_F1..F12	Generic F-keys
VK_START	Start button on emulated machine
VK_SELECT	Select button on a emulated machine
VK_RESET	Reset button on emulated machine
VK_OPTION	Option button on emulated machine
VK_HELP	Help button on emulated machine
VK_ESC	Esc button on emulated machine
VK_CAPSLOCK	Caps Lock button on emulated machine
VK_IN(0..65535)_(0..255)	PORT Commands. (eg. VK_IN_31_255 )

Emulator functions

These functions may not be supported by all emulators!

Name	Description	Recommended Button
GDS_QUICKSAVE	Makes emulator to make a quick save operation	B_TOOL1
GDS_QUICKLOAD	Makes emulator to make a quick load operation	B_TOOL2
GDS_SAVE	Makes emulator to execute a save operation
GDS_LOAD	Makes emulator to execute a save operation
GDS_OPTIONS	Makes emulator to show it’s options dialog
GDS_ESC	Makes emulator to performs an ESC action (eg. While in menu’s)
GDS_OK	Accept button for dialogues on emulator
GDS_CANCEL	Cancel button for dialogues on emulator
GDS_SELECT	Select button on emulator
GDS_BACK	Makes emulator to performs an BACK action (eg. While in menu’s)
GDS_QUIT	Makes emulator to quit.
GDS_RESET	Makes emulator to perform a reset.
GDS_VIEW_ DESCRIPTIONS	Makes emulator to show key descriptions on screen.
GDS_DUMMY	A dummy keyword. Does nothing.

*These functions are not yet defined.

Game Information Group

While not comprehensive, Open Game Definition Standard supports to include basic information about a game.

Game Information

This group’s root element is <GameInformation>.

Example

…informational elements…

</ GameInformation>

Name (BoundedString, optional) (Platform > Game Information >)

Declares game’s official name. While this element is also optional, declaring a name for a game is recommended.

Example

<Name>Chuckie Egg</Name>

Description (String, Optional) (Platform > Game Information >)

A description about game.

Example

<Description>Fast paced platformer</Description>

ReleaseDate (BoundedString, optional) (Platform > Game Information >)

Example

Version(TwoPartNumber, optional) (Platform > Game Information >)

Specifies the version of the defined game.

Example

< Version>1.0 <Version>

Developers, Publishers (BoundedString, optional)(Platform > Game Information >)

These two elements may/may not have URLs to respective sites.

Example

<Developer URL=”HTTP://www.somesite.com” >SomeSoftware House</Developer>

</Developers>

<Publisher>Imagine</Publisher>

</Publishers>

Genres (BoundedString, optional)(Platform > Game Information >)

This element holds many GENRE sub-elements to hold genre information for a game.

*todo* valid genre string list.

Example

<Genre>Action</Genre>

<Genre>Adventure</Genre>

</Genres>

Infoseek ID (Number, Optional) (Platform > Game Information >)

For zx spectrum platform, while not mandatory, infoseek ID is highly recommended.

Example

People (Bounded String, optional) (Platform > Game Information >)

The people who worked on the game.

The sub elements are:

Code, Additional Code, Graphics, Sound, Music, Concept, Design

<Code>Costa Yappari</Code>

<Design>Rosetta Rock</Design>

<Design>Sid Freier</Design>

<Music>Ron Lumbard</Music>

<Graphics>Mark A. Sponges</Graphics>

</People>

Example GDS Files

Minimalistic Example

<GameFileName>somegame.tzx</GameFileName>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</ALT>

</ControlAssignment>

</Platform>

</GameDefinition>

</GameDefinitionFile>

Detailed Example

<GameFileName>somegame2.tzx</GameFileName>

<GameFileName>somegamewithdifferentname.sna</GameFileName>

<Description>Sequel to Fast paced platformer</Description>

< Version>1.0 <Version>

<Developer URL=”HTTP://www.somesite.com” >SomeSoftware House</Developer>

</Developers>

< Publisher URL=”HTTP://www.somesite.com” >SomeSoftware House</ Publishers>

</Publishers>

<Code>James Cook</Code>

<Code>Matt Winston</Code>

<Design>Rosetta Rock</Design>

<Music>Eth Baltaci</Music>

<Graphics>Rim Kavcar</Graphics>

</People>

</GameInformation>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

<HOLD key=”VK_SS”/>

<HOLD key=”VK_Q”/>

<WAIT =”1000”/>

<RELEASE/>

<WAIT address =”16384”>0</WAIT>

<FIX address=”32768”>200</POKE>

<ECHO duration=”3500”>Cheat Enabled</ECHO>

</MAP>

</ALT>

</ControlAssignment>

</Platform>

</GameDefinition>

</GameDefinitionFile>

A GDS Example with Multiple Game Entries

(Note that Game Definitions from different versions of GDS/QGDS can be used together in a GDS container.)

<GameFileName>somegame.tzx</GameFileName>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</ALT>

</ControlAssignment>

</Platform>

</GameDefinition>

<GameFileName>anothergame.tzx</GameFileName>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</MAP>

</ALT>

</ControlAssignment>

</Platform>

</GameDefinition>

</GameDefinitionFile>

Creating Multiple Alternative Controls for Same game with Runtime Switching

<GameFileName>somegame.tzx</GameFileName>

</MAP>

</MAP>

</MAP>

</MAP>

</ALT>

</MAP>

</MAP>

</MAP>

</MAP>

</ALT>

</ControlAssignment>

</Platform>

</GameDefinition>

</GameDefinitionFile>