Using ggz-config to manage client game modules
==============================================
The ggz-config utility, installed as part of ggz-client-libs, allows
you to manage the client game module installed on your system.  It
takes information from a module description file (distributed with
each game module) and stores it in a global configuration file.  All
GGZ client frontends share this file to determine what game modules
are available.

ggz-config also allows client and game developers to automatically
configure pathnames for executable files, data files and so forth
without requiring direct access to the ggz-client-libs sources.


ggz-config Game Module Install
------------------------------
Most game modules will call ggz-config automatically from their
install scripts.  The syntax for calling ggz-config to install a game
module manually is:

    ggz-config --install --modfile=<module desc file>

Some additional options may also be specified:

    --force         Allows the installation information to overwrite
                    existing information of the same game version.

    --destdir       Typically used during package builds, this causes
                    the installation information to go to a
                    ggz.modules file in a temporary build
                    directory, as specified by the DESTDIR environment
                    variable.

    --noregistry    Copies the whole module description file to the
	                GGZ registration directory to facilitate registration
                    after installation from binary packages.

ggz-config Game Module Uninstall 
--------------------------------
When a game module is removed, ggz-config should be run to remove the
game's information from the ggz.modules file.  The preferred method of
removing the module is to use the original module description file
like this:


     ggz-config --remove --modfile=<module desc file>

In the event that the original module description file no longer
exists, the game module information can be removed manually using the
following options:

    --modname=NAME      Specify the Name entry for the module
    --modauthor=AUTHOR  Specify the Author entry for the module
    --modui=<fe code>   Specify the frontend code for the module



Basic ggz-config Queries
------------------------
The pathname query features can be used to query the pathnames that
are compiled into the ggz-client-libs on a particular system.  These
include the following locations:

    --configdir     Query location of configuration directory
    --gamedir       Query location of game modules directory
    --datadir       Query location of game data storage directory

Finally, the --version option of ggz-config can be used to check that the
currently installed version of ggz-client-libs is sufficient for correct
compilation/installation of the client or game.

ggz-config will print the requested pathname(s) or version to standard
output where it can easily be parsed by a shell script.

Game Module Description File Format
-----------------------------------
The preferred method of installing a game module's launch information
into the ggz.modules file is by using a module description file
(commonly named module.dsc).  The command line method of installing
information is not yet documented (and may eventually be removed).

A module.dsc file should be formatted as follows:

    # Comment lines are ignored
    [ModuleInfo]
    Author = Author Name
    CommandLine = /pathname/to/executable/ggz.game
    Frontend = <fe code>
    Homepage = http://host.domain/location/
    Name = <game name>
    ProtocolEngine = <protocol engine>
    ProrocolVersion = <protocol version>
    Version = <game module version>
	Environment = <environment code>
	IconPath = /pathname/to/game.icon
	HelpPath = /pathname/to/game/help.html

The current <fe code>s which are understood are 'gtk', 'kde', 'sdl',
'x11' and 'console' and should describe the native toolkit used for this
game.  This field is simply to give the various GGZ clients an idea of
what toolkit a game was compiled with.  All game clients should always
work with any client frontend (assuming the user has the required GUI
environment installed).
These names are not fixed. More toolkit choices include 'gnome',
'java' and 'guru' to describe chatbot plugin games.

A related field is Environment. The <environment code>s are
'xwindow', 'xfullscreen', 'framebuffer', 'console' and 'passive', where
passive means a game without any user interface. The environment defaults
to 'xwindow'.

The <game name> should match the game name as used by the ggzd server.
The actual displayed name for the game will be set by the server.

The prorocol engine and version must match those of the game module
server.  This insures that game clients, which may be of different
versions will properly work with the game server.

The <game module version> is used internally to identify which game
version to be used.  This allows multiple clients to be installed as
long as their game version is different - obviously (or perhaps not)
these would need to have different CommandLine entries.

When the IconPath field shall be used, an icon can be specified by adding
--iconpath which is then automatically copied to the GGZ registration data
directory upon installation, so that it can be displayed by all GGZ tools,
including the core clients.
Otherwise, there are some generic gametype icons shipped with GGZ, but it
is recommended to use the IconPath feature.
Likewise, the HelpPath field should refer to a viewable text or HTML document
which documents the game.
Both IconPath and HelpPath are not modified, if they are absolute paths,
making it possible to configure the location as part of the auto-configuration
process.

