The GGZ Gaming Zone - Release 0.0.6
===================================
Welcome to the GGZ Gaming Zone, a multiuser networked gaming
environment. This project is still in the development phase, and as
such may have some bugs. It may not even compile or run on your
machine (although we do our best to make sure it does). If you are
interested in assisting with development or in writing a module for
your favorite game, please let us know at ggz-dev@lists.sourceforge.net
The server currently supports thirteen different game types, including
spades, tic-tac-toe, chess, reversi, and others. Players can create
accounts, login, and play games in any one of multiple game rooms.
Sometimes they can even watch other players.
More game servers are available in experimental state or as part of
other projects.
Downloading
===========
You can always download the latest released version of GGZ from our
homepage at http://ggz.sourceforge.net, or for the absolute bleeding
edge you can check out the sources via anonymous CVS (instructions are
at the aforementioned homepage). GGZ is comprised of several
components, each of which is packaged separately for maximum
flexibility. The components are:
- The libggz library
This is a library of common function calls for client/server
communication and utily functions. It is distributed in source form
as libggz-X.X.X.tar.gz, where X.X.X is the version number. The
easysock library has been merged into libggz.
- Common client libraries
This is the set of libraries common to all clients. The source is
available as ggz-client-libs-X.X.X.tar.gz where X.X.X is the
version number.
- GGZ client
This is the core client program that lets you log into a GGZ server,
chat with friends, move between rooms and launch tables (the actual
games are distributed separately). It is our goal to provide
frontends for all environments. We currently have a Gtk+ client, a
KDE client, and a simple text-only client. These are available as
ggz-YYY-client-X.X.X.tar.gz where YYY is one of kde, gtk, or txt,
and X.X.X is the version number.
- GGZ game client modules
To make it easy to add more games without having to recompile GGZ,
we distribute games as modules. Each frontend (kde, gtk, etc) has
separate modules, but you can mix and match as you like. Every GGZ
module should work with every GGZ client (within reason. You can't
expect X-based games to work on a text console, of course). The
games are distributed as ggz-YYY-games-X.X.X.tar.gz where YYY is kde
or gtk (no text-specific games yet), and X.X.X is the version number.
- The GGZ server
This is the software for setting up and managing a GGZ server
installation, including the server game modules. Note that if you
only want to play games on an existing server, you do not need to
download this. The GGZ server is distributed as
ggz-server-X.X.X.tar.gz where X.X.X is the version number.
- Additional software
If you want to experience everything of GGZ, try this out.
The current additional packages are grubby (our chat bot), available
as ggz-grubby-X.X.X.tar.gz, and various utilities, ggz-utils.X.X.X.
For the very bleeding edge, some more (not distributed) software
can be found in the playground CVS module.
- Documentation
A whole bunch of documentation, including the GGZ hosting guide and
the GGZ development guide, as well as information on the various games
and the project itself can be found in ggz-docs-X.X.X.
Compiling and Installing
========================
For more detailed instructions on configuring and installing each
of GGZ components, please read the INSTALL file in each of the
respective source directories. For an overview of the installation
process, please read the QuickStart.GGZ file.
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.
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>
The current <fe code>s which are understood are 'gtk' and 'kde' and
should describe the native environment 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).
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.
Running
=======
You must have access to a running server for the client to be of any
use to you. The server does not have to be running on your machine,
however, if you have no (or slow!) network access, you may want to run
both the client and the server locally. If you choose to install the
GGZ server, you may launch it simply by running the command 'ggzd'
This will start the server listening on port of 5688.
You can find a list of GGZ servers on our homepage.
The command to launch the client will vary, depending on the
particular flavor you have installed. For example, the Gtk+ client is
started by running 'ggz-gtk', whereas the KDE client is started by
running 'kggz'. Once the client is running you should be able to log
into a running GGZ server and begin playing! (Provided you have
installed some games as well).
Bugs
====
Bugs in our code? Never! :) But if you do happen to find one, you
can report it at http://sourceforge.net/bugs/?group_id=1325 or feel
free to contact us at the email address below.
Please let us know if you have any problems, comments, feedback. etc.
Enjoy!
--The GGZ Development Team
<ggz-dev@lists.sourceforge.net>
