GGZ Gaming Zone for KDE 4 - Tutorial 0
--------------------------------------

There will be 3 tutorials for GGZ in KDE, one for each library (kggzmod,
kggznet, kggzgames). We will start with kggzmod since this is probably
the most interesting one. However, before starting, this tutorial 0
should give some information about the build system and general
GGZ game module information.

At some point the tutorials, currently sent by e-mail, will be converted
to HTML and put onto developernew.kde.org or games.kde.org, depending
on where game development documentation should go to.

Note that in addition to the tutorials, the GGZ libraries all ship with
full API docs now, which can be consulted online at:
	http://www.ggzgamingzone.org/docs/api/kggzmod/
	http://www.ggzgamingzone.org/docs/api/kggznet/
	http://www.ggzgamingzone.org/docs/api/kggzgames/
Simply running 'doxygen' for each library will also work of course.
The API docs will end up somewhere at api.kde.org in the standard KDE
apidox format eventually.

Build system
------------

All build issues are handled by GGZ.cmake, which at the time of writing lives
under kdegames/cmake/modules. For some reason, calling
  include (../cmake/modules/GGZ.cmake)
or similar seems to be necessary for each CMakeLists.txt which wants to make
use of it. This will be improved in the future.

GGZ.cmake sets up some variables and helps with GGZ module registration.
Modules are game clients which can run on GGZ and which are registered in a
central system-wide file so every GGZ core client can find them.

All that is needed for KDE games making use of GGZ is to link against the
kggz* libraries in kdegames and to install a module.dsc file containing the
registration data. In terms of CMake, this looks like this:

  register_ggz_module(module.dsc)
  target_link_libraries(mygame ... ${KGGZGAMES_LIBS})

The include directories must include libkdegames, but usually this is already
the case. If not (e.g. for games not in KDE SVN), the following helps:

  include_directories(${KGGZGAMES_INCLUDE_DIR})

GGZ modules
-----------

At the moment, this tutorial assumes that game clients are written for game
servers which already exist, or that the developer knows how to write GGZ game
servers.
Either way, the client and server are identified on the basis of a protocol
engine and an associated version number, both of which must match exactly.
A module.dsc file contains this information and some more:

[ModuleInfo]
Name = ...
Author = ...
CommandLine = <executable-name>
Frontend = kde
Homepage = http://games.kde.org/...
ProtocolEngine = Reversi
ProtocolVersion = 4
Version = ...

In the example above, Reversi:4 is determined by the server, and the client
confirms this combination by stating that it will understand the Reversi
protocol as of version 4. Should the protocol change on the server, the user
will be notified accordingly.

GGZ game servers
----------------

Help out getting network code into as many games as possible! Several KDE
games look like they could match GGZ game servers, so development will be
easy.
Have a look at http://www.ggzgamingzone.org/gameservers/ for a full list
of GGZ and external game servers.
If you write a game server, make sure to have it added there (assuming it
runs on GGZ).