
  ***** The GGZ Game Development Guide *****
  *** Development of games for the GGZ Gaming Zone 0.0.6 ***

  Author: GGZ Development Team

  Copyright (C) 2002 Josef Spillner
  Published under the GNU Free Documentation License.

  This file is the info format of the GGZ Gaming Zone Game Development Guide, which is
  also available in postscript and HTML format.
  It describes how to develop game clients and servers which run over GGZ.
  See http://ggz.sourceforge.net/docs/ for the latest edition.

Menu:
  * Foreword:: General notes about this document
  * The GGZ System:: How games can use the GGZ Gaming Zone
  * Game Clients:: Get into the player's eye
  * Game Servers:: Where the real magic takes place
  * Programming Details:: Network, configuration etc.

Chapter: Foreword

  The central element of the GGZ Gaming Zone is, obviously, everything related to
  games, especially the games themselves. From the very beginning, games of any
  kind have been a part of GGZ. After a long time of premature development, a lot
  of experience is present to be shared with the humble reader.

  As games are very different from applications, it is not easy to recommend for
  this or against that. Instead, a general collection of hints is presented,
  divided into the major differences on the client side (frontends) and the
  server side (programming languages).

Chapter: The GGZ System

 Section: Native GGZ Games ("internal")

  With more than a dozen games available, which can be played using nearly two
  dozen game clients, GGZ offers a solid bunch of different
  games by itself. They're all developed based on a client/server model.
  So how does that work?

  The player, using a GGZ core client to chat with others in a room, launches a
  game which he wants to play with some others. Technically, a table is created
  to hold that game, and the player is put onto that table, occupying one seat.
  The other available seats can be left empty, filled up with bots or used by
  other players. The quantity of each type is determined by the game server, for
  example, some games might not support bots (AI players) at all, or it might
  support an unlimited number of players.

 Section: Games which want to use GGZ ("external")

  External game work no different to internal ones. However, a few assumptions
  can be made, for example, most external game have been present before they got
  a GGZ mode, and are thus more complex in design.
  In the future, some GGZ game servers and clients will most likely also provide
  a standalone mode, just like some clients already do for local games,
  namely Muehle and KTicTacTux.

Chapter: Game Clients

 Section: Introduction

  Game clients in a client/server relation should be regarded as the
  visualization of the game itself. This is not the traditional view where the
  game client was the game itself, but in times of connected entertainment not
  every player can be trusted, so it is a general agreement that the server is
  the trusted element and the clients are just there to convert the game data to
  a more human-friendly format.
  However, this shouldn't stop anybody of developing great game clients.
  Furthermore, there are some GGZ games which run without a server, or with a
  minimal server which leaves all checks to the game clients.

  From version 0.0.6 on, game clients request a separate communication channel
  from the main client, which is connected to the game server directly. This
  leads to a slightly more difficult setup, but allows for higher speed.
  The next section has been added to document this.

 Section: The client base library: libggzmod

  This is a short description of ggzmod. Please see the API documentation for
  details.

  A launched game client gets a control channel on its way, which it connects to
  a callback to receive control messages.
  Then it requests a direct game connection, which results in the creation of a
  game channel, which gets connected to a callback too.
  This game channel is then used to communicate with the game server.

  A basic ggzmod usage may look like this:

  static void handle_ggz(gpointer data, gint source, GdkInputCondition cond)
  {
  	ggzmod_dispatch(ggzmod);
  }

  static void handle_ggzmod_server(GGZMod * ggzmod, GGZModEvent e, void *data)
  {
  	int fd = (int)data;
  	ggzmod_set_state(ggzmod, GGZMOD_STATE_PLAYING);
  	gdk_input_add(fd, GDK_INPUT_READ, game_handle_io, NULL);
  }

  int main()
  {
  ...
  	GGZMod *ggzmod;

  	ggzmod = ggzmod_new(GGZMOD_GAME);
  	ggzmod_set_handler(ggzmod, GGZMOD_EVENT_SERVER, &handle_ggzmod_server);
  ...
  	ggzmod_connect(ggzmod);
  	gdk_input_add(ggzmod_get_fd(ggzmod), GDK_INPUT_READ, handle_ggz, NULL);
  ...
  	ggzmod_disconnect(ggzmod)
  	ggzmod_free(game.ggzmod);
  ...
  }

  (Note that this is for a Gtk+ game client written in C. Things will differ for
  other toolkits like Qt, and other programming languages like C++. Also, return
  values should be checked and such.)

 Section: Game Registry

  Every game client must be registered in order to be found by the GGZ core
  clients like KGGZ or GGZ-Gtk. This is done via the ggz-config utily during the
  installation step. Basically, every game client has a file called module.dsc,
  which is used for this purpose:
  [ggz-config --install --force --modfile=module.dsc]

  The format of this configuration file is defined as follows:

  [ModuleInfo]
  Author = <author>
  CommandLine = <commandline>
  Frontend = <frontend>
  Homepage = <url>
  Name = <name of the game>
  ProtocolEngine = <engine name>
  ProtocolVersion = <protoversion>
  Version = <version>

  The entries don't have to have any special values, except that the combination
  of protocol engine and protocol version is used to ensure the compatibility
  with any game server of this name. The frontend should be a common abbreviation
  like kde, gtk, qt or sdl.

 Section: Client Toolkits
  Section: KDE or Qt (C++)

  See <<http://games.kde.org>> for information about KDE game development.
  There is also a mailing list for this topic with information available at
  <<http://mail.kde.org/mailman/listinfo/kde-games-devel>>.

  The language bindings for KDE are also maturing, so there shouldn't be major
  obstacles coding a KDE game client in Ruby, Python, Perl or Java.

  You will most likely be interested in using Qt classes for OpenGL or sprite
  animations, so get yourself a copy of the Qt documentation.

  The GGZ games KReversi, KDots, KTicTacTux, Krosswater, Muehle, Keepalive,
  Koenig, Kamikaze and Copenhagen have been written using KDE/Qt as development
  framework.

  Section: Gtk+, Gnome (C), Gtk-- (C++)

  There are several useful libraries for Gtk+, including GtkGLArea.
  Examples of Gtk+ GGZ games are TicTacToe, NetSpades, LaPocha, Connect the Dots,
  Hastings, Reversi, Combat, Chinese Checkers, Chess and GGZCards.
  T.E.G. is an example for a Gnome game.

  Section: SDL (C, C++, Python)

  SDL is a proven toolkit for game development, with tons of games already
  available. See <<http://www.libsdl.org>> for a list of them.
  The GGZ game Stalker has been written using SDL.

  Section: Others

  It does really not matter which toolkit one chooses. Therefore, Mesa3D (an
  OpenGL implementation), PLib, GLUT, Pygame and others are worth to have a look
  at.

Chapter: Game Servers

 Section: Introduction

  Game servers are launched by the main GGZ server and receive events on one
  dedicated file descriptor. There are different event types:

   * STATE: indicates that the state has changed (see below)
   * JOIN: a player has joined the game
   * LEAVE: player has left the game
   * SPECTATOR_JOIN: a spectator came to watch the game
   * SPECTATOR_LEAVE: spectator went away
   * PLAYER_DATA: one of the players (clients) sent some data
   * SPECTATOR_DATA: data sent from random spectators

  The states in which a game server can be are:

   * STATE_CREATED
   * STATE_WAITING
   * STATE_PLAYING
   * STATE_DONE

  In order to ease game development, the ggzdmod library has been written, which
  comes with extensive documentation.
  See <<http://ggz.sourceforge.net/api/ggzdmod/html/ggzdmod_8h.html>> for the
  online documentation, which is also available as man page (man 3 ggzdmod.h).

 Section: The server base library: libggzdmod

  In order to be informed about player joins and leaves, and the status of the
  game (running, done, ...), the ggzdmod library is essential to use.

  This is how a simple C game server embeds the necessary function calls:

  static void callback_state(GGZdMod *ggz, GGZdModEvent event, void *data)
  {
  	/* Evaluate state */
  }

  int main()
  {
  ...
  	ggzdmod_set_handler(ggzdmod, GGZDMOD_EVENT_STATE, callback_state);
  ...
  }

 Section: Game statistics: libggzstats

  GGZ game servers can use the ggzstats library which offers various statistic
  types. For example, the ELO ranking and win/loss ratios are supported.

  A typical scenario is the following one:

  GGZStats *stats;

  stats = ggzstats_new(ggzmod);
  ggzstats_set_game_winner(stats, winner, 1.0);
  ggzstats_set_game_winner(stats, (winner + 1) % 2, 0.0);
  ggzstats_recalculate_ratings(stats);
  ggzstats_free(stats);

 Section: Configuration Files

  Each game server must supply at least one file for each of main server's lists.
  Currently there is a room list and a game list, so a game can be present in
  multiple rooms, with either the same or another configuration.

  The game file (<name>.dsc) has the following format:

  [GameInfo]
  Author = <author>
  Description = <description>
  Homepage = <url>
  Name = <name of the game>
  Version = <version>

  [LaunchInfo]
  ExecutablePath = <server executable>

  [Protocol]
  Engine = <protocol name>
  Version = <protocol version>

  [TableOptions]
  AllowLeave = <0/1>
  BotsAllowed = <0 [1 [2 ...]]>
  PlayersAllowed = <1 [2 [3 ...]]>
  KillWhenEmpty = <0/1>
  AllowSpectators = <0/1>

  The room file (<name>.room) has the following format:

  [RoomInfo]
  Name = <roomname>
  Description = <description>
  GameType = <name of the game>
  MaxPlayers = <maximum of players>
  MaxTables = <maximum of tables>

  Have a look at the current game server description files if there are open
  questions.

 Section: Programming Language
  Section: C Development

  C programmers can use ggzdmod natively.

  Section: C++ Development

  For C++ developers there exist some choices in wrapping the ggzdmod library.
  For example, Krosswater uses the Zone library, and Muehle uses the
  GGZGameServer class, which are both wrappers for ggzdmod.
  In the latter case, you only need to inherit your main server class from
  GGZGameServer, and reimplement all of its protected event methods.

  Section: Python Development

  There is a python wrapper for ggzdmod: pyggzdmod.

  Section: Ruby Development

  There is a ruby wrapper for ggzdmod: ruggzdmod.
  In the future, the GGZ server will also be available as a complete ruby
  implementation, which will come with a native game server interface.

Chapter: Programming Details

 Section: General purpose wrappers

  GGZ as of version 0.0.6 provides two wrappers which make life easier for game
  developers. Either of these wrappers replaces a game of choice, while the game
  itself is kept to be launched by the wrapper then.

  Section: ggzwrap

  This one should be used in production code, and it's very suitable for the
  server, because it is small, has no GUI and supports command line options. Its
  arguments are the program to be executed (--exec), the inbound and outbound
  file descriptors to be redirected (--fdin, --fdout), and an option whether the
  received strings should be converted between 'traditional GGZ' easysock order
  and normal C string order (--convert).
  So a sample call may look like this:
  @command{ExecutablePath=/usr/local/ggz/lib/ggzwrap
  --exec=/usr/local/ggz/lib/tictactoe --fdin=3 --fdout=3}

  The GGZ Muehle game uses this one.

  Section: ShadowBridge

  The KDE equivalent of ggzwrap can be used to debug network connections
  visually. It displays incoming and outgoing traffic between the game and the
  game server, which is (technically) between the game client and ggzcore for
  most of our games (those without direct connections, anyway).

 Section: Network connections

  Section: Easysock (C)

  A very easy and convenious library for those who don't need any fancy features
  for TCP connections. This library is part of GGZ and therefore always
  available. It has been merged into libggz, so all functions are prefixed with
  ggz_ now.
  See the documentation for libggz for more details.

  Section: Qt (C++)

  Those game clients which use the Qt toolkit will most likely use the Qt network
  code as well. This has mostly to do with QSocket, QSocketNotifier and
  QDataStream, which are all very easy and intuitive to use.

  Section: KDE (C++)

  KDE does provide very powerful networking mechanisms. There are not only
  classes like KSocket/KExtSocket, but also the DCOP library, and the KDE games
  library named libkdegames.

 Section: Configuration

  Section: GGZConfIO (ini-Style)

  Many GGZ configurations are read and written using GGZConfIO. Formerly located
  in the ggzcore library, it is now part of libggz and consists of many
  ggz_conf_* functions.
  The details are again explained in the libggz documentation.

  Section: Minidom (XML-Style)

  If you want to read or write XML data, while avoiding the overhead of a complex
  XML library, the GGZ project offers the minidom library, which you can find in
  utils/metaserv/minidom.
  Currently, both the GGZ meta server and the Copenhagen game server make use of
  this library.


