Quick-Start Quide

This guide assumes you are either using the Windows package or have compiled and installed Cabrio from source. If you are installing from source, please see the compilation documentation first.

Initial Configuration

Cabrio is configured by means of an XML file named "config.xml". On Unix systems, this is found in the ".cabrio" subdirectory of the users home directory, in other words: "~/.cabrio/config.xml". The Windows version assumes the file is in the current directory (i.e. the same directory as the "cabrio.exe" program itself). If this file doesn't exist when Cabrio is started, a short setup utility runs to allow you to set up the basic controls. Assuming the directory Cabrio was installed to is in your path, simply type "cabrio" to start the front end (Unix) or double-click the executable (Windows). Then press a key, move a joystick, or whatever to register each of the controls when prompted. The result will be written to a new configuration file (if you mess it up, just delete the file and try again). Press the control you chose for "quit" to exit the program.

The generated configuration file contains default values for the screen settings, which you may like to edit, for example:

  <full-screen>true</full-screen>
  <frame-rate>60</frame-rate>
  <screen>
    <width>640</width>
    <height>480</height>
    <rotation>0</rotation>
  </screen>

A default emulator will be automatically configured too, which is worth checking over. An example of what this may look like for a Windows system is:

  <emulators>
    <emulator>
      <name>MAME</name>
      <executable>mamepp.exe</executable>
      <directory>C:\Program Files\MAME</directory>
      <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>

For further information on how to use the configuration file, see the detailed documentation.

Game List

Now that the basic stuff is configured, we need to add our games. Cabrio does not yet generate its own game lists, but the popular ROMLister utility can help you produce lists for use with Cabrio. Simply place the resulting XML file in the same directory as the main "config.xml" file and it will be detected by Cabrio the next time it starts up.

Games can also be added manually by creating or adding to a <game-list> section in the configuration file, for example:

<cabrio-config>
  ...
  <game-list>
    <games>
      <game>
        <name>Pac Man</name>
        <rom-image>pacman.zip</rom-image>
        <platform>Arcade</platform>
      </game>
    </games>
  </game-list>
  ...
</cabrio-config>

Where <rom-image> is the name of the ROM file the emulator should run (whether this has to to an absolute path or just a file name depends on your emulator and how it's set up). The <platform> tag can be anything you like, and will appear in the relevant filter when Cabrio runs. Other filters can be easily added using categories. Again, further details on the available options are described in the detailed documentation.

Using The Front End

Start the front end as before. The effects of the controls are as follows (use the controls you chose in the setup utility).

Up/Down & Left/Right: Navigate through the main menu, filters and game selector; the meaning of the controls depends on the orientation. When the game selector is visible, one pair of controls skips one game at a time, the other is used to skip to the next/previous game beginning with a different initial letter (games beginning with numbers count as the same initial).
Select: Choose the selected menu item of filter value. When the game selector is visible, start the selected game.
Back: Return to the previous menu.
Quit: Exit the front end.