.. -*- 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!