Overview

.. -*- mode: rst; fill-column: 80; auto-fill; -*-

================
 GemRB Launcher
================

:Author: Nick Daly <Nick.M.Daly@gmail.com>
:Copyright: 2008-2010, Nick Daly

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/>.

See the file "COPYING" for more details.

.. contents::

Intro
=====

This program is deisgned to make launching GemRB games and handling multiple
configurations for multiple GemRB games much easier than simply using the
standard GemRB executable.  It locates installed games and manages running games
through an easy to use interface, even handling mounting and unmounting disc
images as necessary.

This guide is divided into several parts:

`Everything in 30 Seconds`_
  Everything you need to know and do in 30 seconds.  A good intro to the rest of
  the sections.
`The Launcher`_ 
  Details on configuring the installer and its prerequisites.  Also an
  explanation of the launcher's config file.
`Installing Games`_
  Setting up the list of installations the launcher will peruse.
Hacking_
  Instructions for hacking on the launcher.

For the most up-to-date version of the launcher, see the `upstream homepage`_.
There are errors and omissions in this document, but I've been too close to it
for too long to be able to pick them out well.  If anything seems unclear,
omitted, or just leading you to further questions, please email me!

.. _upstream homepage: http://bitbucket.org/nickdaly/gemrb-launcher/

Everything in 30 Seconds
========================

You already have GemRB_ and `the launcher`_ unpacked.  Next, go into your
`gemrb_launcher.ini`_ `config file`_ and change the ``[GemRB] -> executable``
line point to your GemRB executable.

Using `NJW's GemRB Installer`_, install any supported Infinity Engine game.  The
installer will set up your ``~/.gemrb/installations.ini`` file that the launcher
needs to find the installed games.

Now, configure any additional settings in your `game's config`_ file (there
shouldn't be any if you used the installer), and run 
``python gemrb_launcher.py`` from the launcher's `src`_ directory.

.. _game's config: config_file
.. _src: src/

The launcher should find your installed games.  Just hit "Play" to enjoy them!

The Launcher
============

Getting It
**********

The launcher is available in several different places:

Included in GemRB_
  This is always the latest working and stable version of the launcher.  It
  might be a bit out of date, but it's the no-hassle option for folks who want
  something that just always works.
The `upstream homepage`_
  This is where the launcher is developed.  If I ever mark a tree as stable
  that'll be a more updated stable option but, for now, anything after 
  `revision 73`_ should be considered stable.  Always the latest and greatest,
  but it might be aggravating, too.

.. _GemRB: http://gemrb.sourceforge.net/
.. _revision 73: http://bitbucket.org/nickdaly/gemrb-launcher/changeset/f606cb107f0e

Prerequisites
*************

Now that you've acquired the launcher, you'll also need it's prerequisites,
including:

- Python_ (2.4 or later releases should work)
- PyGTK_ (2.12 or later, maybe 2.10?)

.. _Python: http://www.python.org
.. _PyGTK: http://www.pygtk.org

If you have GemRB, you probably already have Python.  If you can, use your
distribution's recommended method of acquiring these packages.

Config File
***********

Required Configuration
++++++++++++++++++++++

Configuring the launcher itself is fairly simple.  Just open up the
`gemrb_launcher.ini`_ file and edit the entries in the ``[GemRB]`` section.
You'll probably want to set:

.. _gemrb_launcher.ini: src/gemrb_launcher.ini

``executable``
  The full path to the GemRB executable.

Optional Configuration
++++++++++++++++++++++

If you want to use a different GUI or mounter, just edit the ``Metadata``
section and change the "gui" option to one of the available `GUI directories`_.
The launcher will then use that GUI the next time it's started or you hit the
"Refresh" button.

.. _GUI directories: src/guis/

The ``GenericMounter`` should be generic enough for most any mounting method,
though it's only been proven with fuseiso_ and fusermount_.

.. _fuseiso: http://sourceforge.net/projects/fuseiso/
.. _fusermount: http://fuse.sourceforge.net/

Installing Games
================

There are two common ways to install games.  The first, and recommended, is by
using `NJW's GemRB Installer`_, which should work on bash-supported platforms.
Otherwise, you can `manually install`_ it yourself.

.. _manually install: #manual-installation

NJW's GemRB Installer
*********************

Simply unpack the installer, insert your first disc, and run
``auto-installer.sh``.  Assuming your disc is recognized by the installer
(everything but Icewind Dale 2, as far as I know), it will then be installed
automatically.

.. _NJW's GemRB Installer: http://git.njw.me.uk/cgit/cgit.cgi/gemrb-gameinstallers/

Manual Installation
*******************

If you're looking to do a manual installation, you're mostly on your own.
`Several`_ `wiki`_ `pages`_ exist to help you with that.  Any work to unify
those pages would be apreciated.

.. _Several: http://gemrb.sourceforge.net/wiki/doku.php?id=getting_started
.. _wiki: http://gemrb.sourceforge.net/wiki/doku.php?id=installation
.. _pages: http://wiki.winehq.org/Infinity_Engine_Games#BaldursGate2ThroneOfBhaal

CD Image Setup
**************

After installing the games by whatever method you prefer, you have the option to
configure the launcher to automatically load CD images, so you don't need to use
your original, physical, scratcable discs to play the game.  Also, this can
conserve on hard drive space used to install the game.

First, open up whatever GemRB config file ("GemRB.cfg") you'd like to use CD
images for.  You can now add three different types of keys to the config file:

- CD#
- CD#image
- CD#mount

If you used NJW's installer, the "CD#" entries are probably already filled in.
If you did a full installation from the CDs, you're all done.

However, if you didn't do a full install, you'll have to tell GemRB how to
handle your CDs, as you're probably using CD ISOs, instead of real, physical
CDs.

CD# 
  These lines store the location of the CD's data.  For example, if you're
  mounting disks to ``/tmp/bg2/``, you'll want to mount CD3 to ``/tmp/bg2/3``
  and include the line ``CD3=/tmp/bg2/3`` in your config file.
CD#image
  These lines point to the CD's image file.  If you're not using actual CDs, but
  CD images instead, you'll set these values to the location of the CD image on
  your hard drive.  These lines should look like ``CD3image=~/bg2/cd3.iso``.
CD#mount
  These lines point to where the CD's image file should be mounted.  In this CD3
  example that we're using, you'd want to include the line
  ``CD3mount=/tmp/bg2``.  Notice how that line includes the location specified
  in the "CD#" variable, above.

Example
+++++++

Let's take the most complicated example possible, the third disc of BG:TOS (the
original Baldur's Gate with the Tales of the Sword Coast expansion included,
sold some time in the early 2000's).  This is a 3 CD set in total, containing
data that was originally stored across 6 physical discs.  If you can understand
this example, any working configuration can be derived from this one.

First, we'll need to start with a directory listing of CD3::

    BG_TOS_CD3/
        CD3/
        CD4/
        CD6/

As you can see, the third CD contains 3 subdirectories, each containing one of
the original six discs in and of itself, making things annoyingly complex for
the rest of us who tend to assume that 1 CD acutally is 1 CD.  The launcher,
however, can handle even this strange situation.  You'll need to add another
entry in your config file though::

    "CD#mount="

This tells the launcher where to mount a disc, great when using meta-discs like
this one.  The trick is to mount the meta-disc itself as a primary directory
and then have gemrb search for the CD data in the sub-directories.  In the case
of BG:TOS CD3, your config file would look like::

    # the disc image
    CD3image=/home/nick/bg_tos_cd3.iso

    # where to mount the disc image
    CD3mount=/tmp/bg_tos/disc3

    # where GemRB will read the CD data from
    CD3=/tmp/bg_tos/disc3/CD3
    CD4=/tmp/bg_tos/disc3/CD4
    CD6=/tmp/bg_tos/disc3/CD6

Just remember, each disc image contains the data from several CDs.  GemRB needs
to see each individual CD's data, not the list of CD folders.

Hacking
=======

You'll want to check out the launcher from it's `upstream homepage`_::

    $ hg clone http://bitbucket.org/nickdaly/gemrb-launcher

Engine Structure
****************

You'll want to pay the most attention to the `src`_ directory, which contains
``gemrb_launcher.py``.  A description of all the classes follows:

AbstractException
  The error any unimplemented functionality throws by default.
ConfigLocator
  This class locates and loads GemRB's config files.
Game
  This class launches a GemRB game, setting up and tearing down the environment
  as necessary.
GameTemplate
  This class contains settings from each GemRB config file found and is used to
  create *Game*\ s.
GuiBase
  The fundamental, abstract, base GUI class that all others should be built
  from.
Main
  This class keeps the Gui, Games, and GameTemplates organized and coordinated,
  essentially running the launcher.
SectionlessConfigParser
  This class converts GemRB's config files into config files that Python can
  understand, which can then be loaded by the ConfigLocator.

The *Main* loads the target Gui, as specified in ``gemrb_launcher.ini``.  It's
very possible to build and specify your own Guis, as explained in the next
section.

Adding GUIs
***********

You don't like GTK+ and want to include your own Gui library?  Qt?  wxWidgets?
PyGame strike your fancy?  Here's your chance:

*Main* loads the Gui library specified in ``gemrb_launcher.ini``'s
``Metadata.gui`` option, by loading the following path::

    guis/%(gui)s/gemrb_gui_%(gui)s.py

For example, the GTK Gui is located in::

    guis/gtk/gemrb_gui_gtk.py

For example, if you set ``Metadata.gui`` to "qt", you'll need to create the
following path structure::

    guis/qt/gemrb_gui_qt.py

GUI Structure
+++++++++++++

After creating the file, you'll want to implement each of the abstract methods
in the *GuiBase* class, as those are the methods *Main* will call to perform the
user's requested actions.  Currently, you'll have to define 9 functions to allow
a properly functioning Gui.

The function signatures are as follow::

    class Gui(GuiBase):
        __init__ (self,main)
        disable_new_game_button (self)
        display (self)
        enable_new_game_button (self)
        end_game (self,game_id)
        new_game (self,new_game)
        notify (self,message)
        update_game_templates (self,configurations)
        update_running_games (self)

Write some unit tests for each of those functions, and then feel free to
implement those functions inside your ``Gui`` class.  At that point, you should
be good to go!