This document describes the basic XML configuration file structure in detail. Theme configuration is covered in a separate document. The reader is assumed to have at least basic knowledge of XML.
- Locations & Naming
- Data Types
- Basic Structure
- Interface Section
- Emulators Section
- Locations Section
- Game List Section
- General/Reused Elements
Locations & Naming
The main configuration file is named "config.xml". On Unix-like systems, it is located in a the ".cabrio" subdirectory of the user's home directory, i.e. "~/.cabrio/config.xml". On Windows systems, the file is located in the current directory, which is generally the directory in which the executable "cabrio.exe" resides.
As well as "config.xml", Cabrio will attempt to read any other files with the ".xml" extension it finds in the same directory. This allows, for example, game lists to be generated separately and automatically included in the configuration at runtime.
Theme configuration can also be loaded via a different mechanism, as described in a separate document.
All configuration parameters have a particular data type associated with them. The basic types are listed below. Some parameters may also limit these types further, e.g. by accepting only predefined strings of characters, strings up to a certain length, or only positive numbers.
|Data Type||Valid values|
|String||Any combination of characters|
|Integer||Positive or negative whole numbers consisting of only an optional minus sign ("-") and the numbers "0" thru "9".|
|Floating Point||Positive or negative floating point ("decimal") numbers consisting of only an optional minus sign ("-"), the numbers "0" thru "9" and an optional decimal point (".").|
|Percentage||A whole number percentage from 0 thru 100, optionally followed by a "%" sign.|
|Boolean||true, false, yes, no|
|RGB||A colour described in hexadecimal format, two characters (0-f) for each component red, green and blue, in that order.|
The root element of all files is <cabrio-config>. The major sections are:
- The <interface> element, which contains the configuration for visual properties and controls
- The <emulators> element, containing the names and parameters of emulator programs
- The <locations> element, containing the directories of media files, such as images
- The <game-list> element, which contains the game list.
- The <themes> element, which contains specific details of the application's "look and feel".
All element names ("tags") are case sensitive, i.e. they must be written in lower case to be recognised. Element values are generally not case sensitive, i.e. the strings "Up", "up", "UP" and even "uP" are considered to mean the same thing.
The current configuration file format makes no use of XML attributes, only regular elements. This may result in a more verbose configuration file, but at least one needn't think whether particular parameters must be specified as attributes or not!
The interface section is used to configure the screen, controls and other properties related to the interface of the application. For example:
<cabrio-config> <interface> <full-screen>true</full-screen> <frame-rate>60</frame-rate> <theme>MyTheme</theme> <screen> <width>640</width> <height>480</height> <rotation>90</rotation> </screen> <graphics> <quality>high</quality> <max-image-width>512</max-image-width> <max-image-height>256</max-image-height> </graphics> <controls> <event> ... </event> ... </controls> <lookups> ... </lookups> ... </interface> ... </cabrio-config>
Elements of <interface>
In addition to the specific elements listed below, most elements used for theme configuration can also be used in the <interface> section, in order to override a theme's parameters. More details of how this works can be found in the theme configuration document.
|full-screen||Boolean||Whether the application should start in full-screen mode. If set to "false", the application runs in a window.|
|frame-rate||Numeric||Specify the desired frame rate, the default being 60. On slower machines, lower frame rates may be required. Fast machines may use higher frame rates for even smoother animation. A zero value means "unlimited", i.e. draw frames as fast as possible.|
|theme||String||The name of the predefined theme to use (see this document for details).|
|controls||-||Defines the controls which are used to operate the application (see below)|
|lookups||-||Defines strings used to translate or group category values (see below)|
|width||Numeric||The width of the screen/window in pixels.|
|height||Numeric||The height of the screen/window in pixels.|
|rotation||Numeric||Number of degrees to rotate the screen, in steps of 90. Positive values rotate clockwise, negative values rotate anticlockwise.|
|quality||String||Determines the quality with which graphics are rendered. Specify "low", "medium" or "high". The default is "high", but slower machines may benefit from a lower quality setting.|
|max-image-width||Numeric||The maximum width of images to be used by the front end, defined in pixels. Images larger than this will be scaled down internally.|
|max-image-height||Numeric||The maximum height of images to be used by the front end, defined in pixels. Images larger than this will be scaled down internally.|
The user can define custom controls via this element (although it is much simpler to do so automatically via the setup utility). Controls are defined per "event", i.e. something that happens in the application to trigger an action. Events that are left undefined are assigned default values. The recognised events and their default values are listed in the following table.
|Event name||Default control|
|Up||Up cursor/arrow key|
|Down||Down cursor/arrow key|
|Left||Left cursor/arrow key|
|Right||Right cursor/arrow key|
The <event> element itself looks like this example:
<cabrio-config> <interface> ... <controls> <event> <name>up</name> <device> <type>joystick</type> <id>1</id> </device> <control> <type>axis</type> <id>0</id> </control> <value>up</value> </event> ... </controls> </interface> ... </cabrio-config>
The <name> element specifies which event this control will trigger. It may be any of the valid event names listed above. The value is not case sensitive. If the same event is defined more than once, the results are undefined.
The <device> element defines which peripheral device is to be used; the <type> sub-element indicating the type of device (e.g. keyboard, joystick, mouse) and the <id> element indicating the particular device of the given type. The example above (joystick, 1) means the second joystick detected when the application initialises. If no <id> is given, a default value of zero is assumed (i.e. the first device).
The <control> element defines which specific control on the specified device is to be used; the <type> sub-element indicating the type of control (e.g. a button press, axis movement, etc.) and the <id> element indicating the particular control, in case more than one is present. The example above (axis, 0) means the first analogue axis on the joystick. As with the device <id>, a default value of zero is assumed is this is omitted.
The <value> element defines, at the lowest level, which action will trigger the event. Acceptable values depend on the device/control type:
- Keyboard device: A valid key name, which is any one of the SDLKey names, minus the SDLK_ prefix.
- Joystick axis: The words "plus" to indicate a positive value, or "minus" to indicate a negative value. In addition, the words "right" or "down" may be used as synonyms for "plus" and the words "up" or "left" may be used as synonyms for "minus".
- Joystick ball/hat or mouse axis: The words "up", "down", "left" and "right" are used to indicate the direction.
- Joystick or mouse button: The numerical index of the button (0 for the first, 1 for the second, and so on).
Whilst the <device>, its <type> and the <value> are always required, other elements may support different values or be omitted completely, depending on the device and control types. The table below shows the control types supported by each device type. If none (or only the default) are listed, the <control> element may be omitted for that device type (if specified, it will be ignored anyway).
Lookups are used to tanslate category values into more readable names, or group values together under a single name. They are most useful when using auto-generated game lists, which may contain values which you'd like to display in a more "friendly" way. For example:
<cabrio-config> ... <lookups> <category-lookup> <category>Controls</category> <lookup> <match>dial</match> <value>Spinner</value> </lookup> <lookup> <match>joy*</match> <value>Joystick</value> </lookup> </category-lookup> </lookups> ... </cabrio-config>
Inside the <lookups> element, a <category-lookup> is defined. This is the only type of lookup at present, but others may be added in the future. The <category-lookup> has a <category> which specifies to which category the lookup applies. The individual <lookup> elements have a <match> element which holds the pattern to match. Any values matching this pattern will be replaced by the string in <value>.
The first example is a simple translation of the word "dial" to "Spinner". The second illustrates the use of a wildcard pattern which will group all values which begin with the string "joy" into a single value "Joystick". The asterisks ('*') may appear anywhere in the string to signify "match anything".
This section allows the configuration of individual emulators which will ultimately be used to run the configured games. The section consists of the <emulators> element containing zero or more <emulator> elements. It is of course preferable to configure at least one emulator! For example, the default emulator is configured thus:
<cabrio-config> ... <emulators> <emulator> <name>MAME</name> <executable>mame</executable> <Platform>Arcade</platform> <params> <param> <name>-nowindow</name> </param> <param> <name>-skip_gameinfo</name> </param> <param> <name>-switchres</name> </param> <param> <name>-joystick</name> </param> </params> </emulator> </emulators> ... </cabrio-config>
The sub-elements of an <emulator> are as follows.
|name||String||A natural language name for the emulator which can be used for display purposes.|
|executable||String||The name of the file to run in order to launch the emulator. If the emulator is not in the execution path, a full path must be provided.|
|directory||String||Change to this directory when executing the emulator. If no directory is supplied, the current directory is retained.|
|default||Boolean||Use this emulator as the default, in case a game cannot be matched to an emulator automatically.|
|params||-||Element containing extra parameters which will be passed to the emulator when it is run. See below for more details on the <params> element.|
In the locations section, you can specify which directories should be searched for different kinds of resources. At the moment, this is used only for image types, but this can later be expanded to include other types of resources (e.g. music or videos). For example:
<cabrio-config> ... <locations> <location> <type>screenshot</type> <directory>/path/to/my/screenshots</directory> </location> ... </locations> ... </game> <cabrio-config>
Specifies a directory which contains screenshot images. For games it is therefore possible to specify a simple filename in their <image> parameters - the front end will automatically search for it in the specified directory. In many cases, it may not even be necessary to specify any game images at all: If no image is specifically given, the front end will search the <location>s for files which match the <rom-image> parameter of the game, but may have a different extension. The <type> may be anything, but the following values have special meanings:
|background||Directory is automatically searched for game background images.|
|logo||Directory is automatically searched for logos, which are displayed in the game selector by default.|
|video||Directory is automatically searched for video file, which are displayed on screen in the "snap" by default.|
|screenshot||Directory is automatically searched for screen shots, which are displayed on screen in the "snap" unless a video is available.|
Game List Section
The game list section is used to populate the list of available games. The section consists of a <game-list> element containing an optional <name> and zero or more <game>elements, contained in a <games> element e.g.:
<cabrio-config> ... <game-list> <name>My List</name> <games> <game> <name>Pac Man</name> <platform>Arcade</platform> <rom-image>pacman.zip</rom-image> <images> <image> <type>logo</type> <image-file>/path/to/logos/pacman.png</image-file> </image> <image> <type>screenshot</type> <image-file>/path/to/screenshots/pacman.png</image-file> </image> </images> <categories> <category> <name>Genre</name> <value>Maze</value> </category> </categories> </game> ... </games> </game-list> </cabrio-config>
The valid elements within a <game> entry are:
|name||String||A natural language name for the game which can be used for display purposes.|
|rom-image||String||The file containing the game's ROM. This value is passed as-is to the emulator so, depending on how the particular emulator is set up, it may be simply a name or could have to be a full path.|
|platform||String||A natural language name for the platform of the game (i.e. which system the game runs on). Unique values over all games are collected to build the list of available genres, which may then be used as a filter. The platform is used used to determine which emulator should be used to run the game, unless overridden.|
|emulator||String||Use the emulator defined with the <name> equal to this value, instead of selecting one automatically based on <platform>.|
|video||String||Video/movie file to be shown as a preview for this game.|
|images||-||Contains an <image> element for each image associated with this game (e.g. a logo, screen shot or background) - see below.|
|categories||-||Categories are speficied as name/value pairs. Both the name and the value can be any arbitrary string. Unique category names are used to create filters, which appear in the menu. The unique values for each category are listed as criteria for the filter. A game may have several entries with the same name and different values (e.g. to allow the game to appear in more than one genre).|
|params||-||Element containing extra parameters which will be passed to the emulator when this particular game is run. Parameters are appended to any defined for the emulator itself. See below for more details on the <params> element.|
As mentioned above, the <images> element contains individual <image> subelements for each image associated with the game. Images have a <type>, which may be an arbitrary string value identifying the type of image. Some values have special meanings by default:
- logo: Images of this type are used for the game selector by default.
- background: Images of this type are used to set the background when the game is selected.
- screenshot: Images of this type are displayed as the snap when the game is selected.
The <image-file> element is used to specify the location of the image. If a <location> with a <type> equal to the of the game exists, a relative path may be specified; the location's directory will be searched for the file. If an absolute path is specified, no automatic searching is performed.
Some elements are used in more than one place, but follow the same rules regarding sub-elements and values. These "general" elements are described here.
Parameters are defined as having a <name> and an optional <value>. When passed to the emulator, the value (if present) is appended to the argument list after the name. For example:
... <params> <param> <name>-x</name> </param> <param> <name>-rotate</name> <value>90</value> </param> </params> ...
The above example would result in an emulator "myemu" being run thus:
myemu -x -rotate 90
While <value> always appears after the <name>, it is not guaranteed that parameters will be passed in the same order as they appear in the <params> element. The above example may also turn out as:
myemu -rotate 90 -x