Configuration

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.

Contents

Locations & Naming

Data Types

Basic Structure

Interface Section

Elements of <interface>

Defining Controls

Lookups

Emulators Section

Locations Section

Game List Section

Game Images

General/Reused Elements

Parameters

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.

Data Types

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.

Basic Structure

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!

Interface Section

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.

Top-level

<screen>

<graphics>

Defining Controls

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.

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

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".

Emulators Section

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.

Locations Section

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:

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:

Game Images

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.

General/Reused Elements

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

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

Copyright ©2012 Steve Maddison