<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "0.5.6">
  <!ENTITY manrevision "1.1">
  <!ENTITY date "February 2008">
  <!ENTITY app "GNOME Video Arcade">
]>

<article id="index" lang="en">

  <articleinfo>

    <title><application>&app;</application> Manual</title>

    <abstract role="description">
      <para>&app; is a front-end for the <application>Multiple Arcade
      Machine Emulator (MAME)</application>.</para>
    </abstract>

    <copyright>
      <year>2007</year>
      <year>2008</year>
      <holder>Matthew Barnes</holder>
    </copyright>

    &legal;

    <authorgroup>
      <author role="maintainer">
        <firstname>Matthew</firstname>
        <surname>Barnes</surname>
      </author>
    </authorgroup>

    <revhistory>
      <revision>
        <revnumber>&app; Manual &manrevision;</revnumber>
        <date>2008-02-24</date>
      </revision>
    </revhistory>

    <releaseinfo>This manual describes version &appversion; of &app;</releaseinfo>

  </articleinfo>

  <section>
    <title>Introduction</title>
    <para>
      The <application>&app;</application> application allows you to play
      classic coin-operated arcade games on your GNOME desktop using the
      <application>Multiple Arcade Machine Emulator (MAME)</application>.
    </para>
    <para>
      <application>&app;</application> provides the following features:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Play classic arcade games on your desktop.
        </para>
      </listitem>
      <listitem>
        <para>
          Tag favorite games to easily find them again later.
        </para>
      </listitem>
      <listitem>
        <para>
          Read historical information and tips about your favorite games.
        </para>
      </listitem>
      <listitem>
        <para>
          Game recording and play back.
        </para>
      </listitem>
      <listitem>
        <para>
          Search.
        </para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Getting Started</title>
    <section>
      <title>Starting &app;</title>
      <para>
        You can start <application>&app;</application> in the following ways:
      </para>
      <variablelist>
        <varlistentry>
          <term><guimenu>Applications</guimenu> menu</term>
          <listitem>
            <para>
              Choose
              <menuchoice>
                <guisubmenu>Games</guisubmenu>
                <guimenuitem>Video Arcade</guimenuitem>
              </menuchoice>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Command line</term>
          <listitem>
            <para>
              To start <application>&app;</application> from a command line,
              type the following command, then press <keycap>Return</keycap>:
            </para>
            <para>
              <command>gnome-video-arcade</command>
            </para>
            <tip>
              <para>
                To view other command line options that are available, type
                <command>gnome-video-arcade --help</command>, then press
                <keycap>Return</keycap>.
              </para>
            </tip>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>When You Start &app;</title>
      <para>
        The first time <application>&app;</application> starts, it will
        build a database of game information and analyze available ROM
        files to determine which games are playable.  This process may
        take several minutes to complete, during which time the following
        window is displayed:
      </para>
      <figure>
        <title>&app; Building the Game Database</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/gva_building_database.png" format="PNG"/>
            </imageobject>
            <textobject>
              <para>
                Shows &app; main window while the database is being built.
                Most of the elements are grayed out, and a progress bar is
                shown at the bottom.
              </para>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        The window will then change to look like this:
      </para>
      <figure>
        <title>&app; Start Up Window</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/gva_main_window.png" format="PNG"/>
            </imageobject>
            <textobject>
              <para>
                Shows &app; main window with a sample list of games.
                Contains menubar, game list, view buttons, start game button,
                properties button and statusbar.
              </para>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        You may see a different list of games, depending on which ROM images
        are installed on your system.
      </para>
      <tip>
        <para>
          If you know that ROM images are installed on your system but
          <application>&app;</application> does not list any games, it may be
          that <application>MAME</application> is misconfigured or none of the
          installed ROM images are playable.  See the Troubleshooting section
          for more information.
        </para>
      </tip>
      <note>
        <para>
          Occasionally, the database may be rebuilt when
          <application>&app;</application> starts.  Most of the time it will
          skip this process and go straight to the window in Figure 2.
        </para>
      </note>
      <para>
        The <application>&app;</application> window contains the following
        elements:
      </para>
      <variablelist>
        <varlistentry>
          <term>Menubar</term>
          <listitem>
            <para>
              The menus on the menubar contain all the commands needed to
              use <application>&app;</application>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Game List</term>
          <listitem>
            <para>
              The game list displays a list of games to choose from.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>View Buttons</term>
          <listitem>
            <para>
              The view buttons control which games are displayed in the game
              list.  Choose between displaying all available games, a list of
              favorite games, or previous search results.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guibutton>Start Game</guibutton> Button</term>
          <listitem>
            <para>
              The <guibutton>Start Game</guibutton> button starts the
              highlighted game in the game list.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guibutton>Properties</guibutton> Button</term>
          <listitem>
            <para>
              The <guibutton>Properties</guibutton> button displays additional
              information about the highlighted game in the game list.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Statusbar</term>
          <listitem>
            <para>
              The statusbar displays the <application>MAME</application>
              version used to play games and contextual information about the
              menu items.  It also displays a progress bar while building the
              game database.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
  </section>

  <section>
    <title>Usage</title>
    <section>
      <title>To Start a Game</title>
      <para>
        Choose a game from the game list and click on it to highlight it.
        Then click the <guibutton>Start Game</guibutton> button or choose
        <menuchoice>
          <shortcut>
            <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>S</keycap>
            </keycombo>
          </shortcut>
          <guimenu>Game</guimenu>
          <guimenuitem>Start</guimenuitem>
        </menuchoice>.
      </para>
      <tip>
        <para>
          You can also start a game by double-clicking on it in the game list.
        </para>
      </tip>
    </section>
    <section>
      <title>To View Properties of a Game</title>
      <para>
        Choose a game from the game list and click on it to highlight it.
        Then click the <guibutton>Properties</guibutton> button or choose
        <menuchoice>
          <shortcut>
            <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>P</keycap>
            </keycombo>
          </shortcut>
          <guimenu>View</guimenu>
          <guimenuitem>Properties</guimenuitem>
        </menuchoice>.
      </para>
      <para>
        The <guilabel>Properties</guilabel> dialog displays information about
        the highlighted game, including some history about the game, tips and
        tricks to help improve your scores, pictures of the arcade cabinet,
        screen shots of the game in progress and some technical information
        about <application>MAME</application>'s emulation of the game.
      </para>
      <para>
        To close the <guilabel>Properties</guilabel> dialog, click the
        <guibutton>Close</guibutton> button.
      </para>
      <note>
        <para>
          Some of these features are not yet completed and will be available
          in a future version of <application>&app;</application>.
        </para>
      </note>
    </section>
    <section>
      <title>To Tag a Game as a Favorite</title>
      <para>
        To tag a game as a favorite, choose a game from the game list and
        click on it to highlight it.  Then choose
        <menuchoice>
          <shortcut>
            <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>+</keycap>
            </keycombo>
          </shortcut>
          <guimenu>Game</guimenu>
          <guimenuitem>Add to Favorites</guimenuitem>
        </menuchoice>.
        The heart icon for the highlighted game will light up to indicate
        that the game has been added to your list of favorites.
      </para>
      <para>
        If a game is no longer your favorite, click on its name in the game
        list to highlight it.  Then choose
        <menuchoice>
          <shortcut>
            <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>-</keycap>
            </keycombo>
          </shortcut>
          <guimenu>Game</guimenu>
          <guimenuitem>Remove from Favorites</guimenuitem>
        </menuchoice>.
        The heart icon for the highlighted game will turn gray to indicate
        that the game has been removed from your list of favorites.
      </para>
      <tip>
        <para>
          You can also click directly on a heart icon in the game list to tag
          the game as a favorite or not a favorite.
        </para>
      </tip>
    </section>
    <section>
      <title>To Change Which Games Are Displayed</title>
      <para>
        To show all available games in the game list, click the
        <guibutton>Available Games</guibutton> view button or choose
        <menuchoice>
          <guimenu>View</guimenu>
          <guimenuitem>Available Games</guimenuitem>
        </menuchoice>.
      </para>
      <para>
        To show only your favorite games in the game list, click the
        <guibutton>Favorite Games</guibutton> view button or choose
        <menuchoice>
          <guimenu>View</guimenu>
          <guimenuitem>Favorite Games</guimenuitem>
        </menuchoice>.
      </para>
      <para>
        To show your previous search results in the game list, click the
        <guibutton>Search Results</guibutton> view button or choose
        <menuchoice>
          <guimenu>View</guimenu>
          <guimenuitem>Search Results</guimenuitem>
        </menuchoice>.
      </para>
    </section>
    <section>
      <title>To Search for Games</title>
      <para>
        Choose
        <menuchoice>
          <shortcut>
            <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>F</keycap>
            </keycombo>
          </shortcut>
          <guimenu>Edit</guimenu>
          <guimenuitem>Search...</guimenuitem>
        </menuchoice>
        to display the following dialog:
      </para>
      <figure>
        <title>&app; Search Dialog</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/gva_search_window.png" format="PNG"/>
            </imageobject>
            <textobject>
              <para>
                Shows &app; search dialog.  Contains text entry box, find
                button and close button.
              </para>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        Type your search criteria in the entry box.  Search by the title of
        the game, the company that manufactured the game, the year the game
        was released, or the name of the game's ROM set or
        <application>MAME</application> driver.
      </para>
      <para>
        Click the <guibutton>Find</guibutton> button to start your search.
        The <guilabel>Search</guilabel> dialog will close and the results of
        your search will be displayed in the game list.
      </para>
      <para>
        Click the <guibutton>Close</guibutton> button to close the
        <guilabel>Search</guilabel> dialog without searching.
      </para>
    </section>
    <section>
      <title>To Record a Game</title>
      <para>
        Choose a game from the game list and click on it to highlight it.
        Then choose
        <menuchoice>
          <shortcut>
            <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>R</keycap>
            </keycombo>
          </shortcut>
          <guimenu>Game</guimenu>
          <guimenuitem>Record</guimenuitem>
        </menuchoice>.
      </para>
      <para>
        After you exit from <application>MAME</application>, your new
        recording will be highlighted in the following window:
      </para>
      <figure>
        <title>&app; Recorded Games Window</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/gva_recorded_games.png" format="PNG"/>
            </imageobject>
            <textobject>
              <para>
                Shows &app; recorded games window.  Contains list of game
                recordings, play back button, delete button and close button.
              </para>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        Each entry shows the title of the game that was recorded, and the
        date and time when recording began.  Click on the game's title
        to customize the comment.  You can add more information to the
        comment such as the final score or level reached.
      </para>
    </section>
    <section>
      <title>To Play Back a Recorded Game</title>
      <para>
        Choose
        <menuchoice>
          <guimenu>Game</guimenu>
          <guimenuitem>Play Back...</guimenuitem>
        </menuchoice>
        to display the <guilabel>Recorded Games</guilabel> window.
        Choose a game recording to play back and click on it to highlight it.
        Then click the <guibutton>Play Back</guibutton> button.
      </para>
    </section>
  </section>

  <section>
    <title>Preferences</title>
    <para>
      To modify the preferences of <application>&app;</application>, choose
      <menuchoice>
        <guimenu>Edit</guimenu>
        <guimenuitem>Preferences</guimenuitem>
      </menuchoice>.
    </para>
    <para>
      The <guilabel>Preferences</guilabel> dialog contains the following
      sections:
    </para>
    <section>
      <title>General</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/gva_general_preferences.png" format="PNG"/>
          </imageobject>
          <textobject>
            <para>
              Shows the General tab of the Preferences window.
            </para>
          </textobject>
        </mediaobject>
      </screenshot>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>
              Start games in fullscreen mode
            </guilabel>
          </term>
          <listitem>
            <para>
              Select this option to start games in fullscreen mode.
              Otherwise, games will be started in a window.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>
              Restore previous state when starting a game
            </guilabel>
          </term>
          <listitem>
            <para>
              Select this option to continue where you left off when you last
              exited <application>MAME</application>.  If this option is not
              selected, the emulator will boot the arcade machine each time a
              game is started.
            </para>
            <note>
              <para>
                State restoration does not take effect until the second time
                the game is started with the option enabled.  It does not
                apply to recording or playing back games.
              </para>
            </note>
            <warning>
              <para>
                Not all games support this feature.
              </para>
            </warning>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>
              Show alternate versions of original games
            </guilabel>
          </term>
          <listitem>
            <para>
              Select this option to show alternate versions of original games
              in the game list in the main window.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <note>
        <title>What are alternate versions?</title>
          <para>
            From the
            <ulink url="http://mamedev.org/devwiki/index.php/FAQ:General_Games"><application>MAME</application> FAQ</ulink>:
          </para>
          <blockquote>
            <para>
              Games were often licensed to other companies for a variety of
              reasons: the most common was that the makers wished to sell the
              game in a country or region in which they had no distribution
              of their own.  In the early 80s, Namco had no US distribution
              network so their games were licensed to Atari, Bally-Midway,
              and others.  Conversely, Atari licensed their games to Japanese
              companies (usually Namco) for sale there.
            </para>
            <para>
              Sometimes a set of ROMs with a different copyright date is
              found, or a bootleg set, or another alternate version.  When
              the <quote>parent</quote> game has already been emulated in
              <application>MAME</application>, these alternates are usually
              easy to add.  In some cases, alternate versions are slightly
              different: Game levels are in a different order, the game is
              harder or faster, etc.
            </para>
            <para>
              In some cases, ROMs were hacked to run on hardware they were
              not intended for.  For example, when
              <productname>Pac-Man</productname> was <quote>hot,</quote>
              some arcade operators found a way to dump
              <productname>Pac-Man</productname> ROMs and hack them to work
              on <productname>Scramble</productname> machines so they wouldn't
              have to purchase extra <productname>Pac-Man</productname>
              boards.  Since these hacked versions are masterpieces in their
              own right, the <application>MAME</application> developers have
              included them.
            </para>
          </blockquote>
      </note>
    </section>
    <section>
      <title>Columns</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/gva_column_preferences.png" format="PNG"/>
          </imageobject>
          <textobject>
            <para>
              Shows the Columns tab of the Preferences window.
            </para>
          </textobject>
        </mediaobject>
      </screenshot>
      <para>
        The <guilabel>Columns</guilabel> tab allows you to configure the
        game list in the main window to show additional information about
        the available games.  The column names are listed in the order that
        they appear in the game list.  Reorder columns and show additional
        columns using the <guibutton>Move Up</guibutton>,
        <guibutton>Move Down</guibutton>, <guibutton>Show</guibutton> and
        <guibutton>Hide</guibutton> buttons to the right of the column list.
      </para>
    </section>
  </section>

  <section>
    <title>Troubleshooting</title>
    <anchor id="troubleshooting"/>
    <section>
      <title>No games listed in the main window</title>
        <section>
          <title>
            Are any ROM images installed?
          </title>
          <para>
            For legal reasons, games are not bundled with
            <application>&app;</application> or
            <application>MAME</application>.  The
            <ulink url="http://mamedev.org/devwiki/index.php/FAQ:Setting_Up"><application>MAME</application> FAQ</ulink>
            has some suggestions for obtaining ROM images:
          </para>
          <blockquote>
            <para>
              There are several means of obtaining ROM images for use in
              <application>MAME</application>:
            </para>
            <itemizedlist>
              <listitem>
                <para>
                  A small number of ROM images are now available with the
                  copyright holders' permission at the
                  <ulink url="http://mamedev.org/roms/">mamedev.org ROMs page</ulink>.
                </para>
              </listitem>
              <listitem>
                <para>
                  The
                  <ulink url="http://www.hanaho.com/Products/HotRodJoystick.php"><productname>HotRod Joystick</productname> control panel</ulink>
                  from
                  <ulink url="http://www.hanaho.com/">Hanaho Games, Inc.</ulink>
                  comes bundled with a CD that includes
                  <application>MAME</application> and a selection of Capcom
                  ROMs.  Hanaho also sells the
                  <ulink url="http://www.hanaho.com/Products/ArcadePC.php"><productname>ArcadePC</productname> cabinet</ulink>
                  with a different selection of Capcom ROMs.
                </para>
              </listitem>
              <listitem>
                <para>
                  You can purchase your own arcade PCBs (on
                  <ulink url="http://www.ebay.com/">eBay</ulink>, for
                  example), buy a ROM reader, and use it to copy the ROM
                  chips' contents into files for your personal use.
                </para>
              </listitem>
            </itemizedlist>
            <para>
              Always check if the particular arcade games' copyright owner
              is selling the ROMs legally (as with Capcom).  That way you
              will support the companies that support emulation.
            </para>
          </blockquote>
        </section>
        <section>
          <title>
            Can <application>MAME</application> find the installed ROM images?
          </title>
          <para>
            <application>&app;</application> relies on
            <application>MAME</application> to find installed ROM images.
            To test where <application>MAME</application> is configured to
            look for ROM images, type the following command on a command
            line, then press <keycap>Return</keycap>:
          </para>
          <para>
            <command>gnome-video-arcade --inspect rompath</command>
          </para>
          <para>
            The command should print a directory name such as
            <computeroutput>/usr/share/mame/roms</computeroutput>.
            Move ROM images to this directory and restart
            <application>&app;</application>.
          </para>
          <para>
            If the command does not print a directory name, it may mean
            that <application>MAME</application> is not properly configured
            on your system.  If you obtained <application>MAME</application>
            from a <productname>GNU/Linux</productname> distribution, please
            contact the maintainers of that distribution for further
            instructions.
          </para>
        </section>
        <section>
          <title>
            Is the Available Games view selected?
          </title>
          <para>
            If no games have been tagged as favorites, the
            <guilabel>Favorite Games</guilabel> view will be empty.
            Similarly, if no searches have been run, the
            <guilabel>Search Results</guilabel> view will be empty.
            Switch to the <guilabel>Available Games</guilabel> view
            to ensure all available games are listed.
          </para>
        </section>
    </section>
  </section>

</article>
