GGZ Gaming Zone Core Clients

Revision: 0.3
Date: 30.12.2006
Author: Josef Spillner <josef at ggzgamingzone dot org>

Core clients enable players to log into GGZ servers, chat, select a game for play or spectating, view the network lag and handle numerous smaller tasks. Hence, they are an essential part of GGZ and their internals should be well understood. A core client feature comparison matrix is aiding in finding out which clients provide which functionality.

The programmes themselves

Basically, each core client starts out as a chat client. It offers connection profiles for each server. The server list can be maintained by hand or updated via the GGZ metaserver. Connection options include the type of login (as a guest, registered player or for the first time), the encryption, and of course the nickname.

After having logged in, the core client will enter the first room, called the Entry Room or Lounge. It doesn't have any games associated with it so only chatting is possible. Within each room, players can view their peers and their properties (including privilege status, buddy list status and game statistics). They also can start a private conversation, check their connection lag, and talk with the chatbot, for which a visual dialog might exist.

Entering a regular room opens the possibility of launching a table, with a predefined number of open and reserved seats and AI players. Existing tables can also be joined, either as player or as spectator. Then, directly linked to the join is the launch of the local game module which will then communicate with the game server. Core clients still handle tasks like transmitting the player list, highscores and so on.

A core client lets some privileged users perform additional actions. GGZ differentiates into admins, hosts, regular registered users, registered bots and guest users. Hosts can make other players be quiet or kick them from the server if they behave badly. They can also chat in private at tables while they're playing, which is forbidden for non-privileged players. Administrators can do all that and in addition modify the permissions of registered players so that new hosts or administrators can be created. The first set of actions is called "admin actions", the second one "player permission management".

Existing core clients

Regular GGZ core clients present themselves online at the core client homepages. This includes KGGZ, GGZ-Gtk and GGZ-Gnome for typical Linux desktops running e.g. KDE, GNOME or XFCE, GGZ-Java for any desktop or usage as an applet on webpages and Víbora for full-screen environments. It also includes ggz-txt for text console users such as found alot among GGZ developers. Beside the regular GGZ core clients, some special clients exist. The first group of special core clients includes include all programs which behave a bit different from regular core clients but nevertheless use the same technical base. This group includes Grubby (the chatbot), TelGGZ, the Telnet wrapper for GGZ, and GGZap and ggz-wrapper which are tools for launching GGZ games quickly. GGZap is a graphical tool for KDE, whereas ggz-wrapper is a command-line tool used by the instant messenger plugins for Pidgin (formerly Gaim) and Kopete. The second group of special core clients are games which run in "embedded mode". Those are games which not only can be launched by other core clients, but they connect to GGZ servers themselves! Of course in most cases they won't have all the features that regular core clients have, but the advantage is that one can launch a network game right away from the application menu. It is considered good habit to support both launching from core clients and running in "embedded mode" at the same time at least for larger games. The GGZ Game Development Guide has more information on that topic.

In summary, the following core clients exist:

A building block: ggzcore

The ggzcore library has been written to support the development of core clients. It is currently used in the regular clients as well as in the special clients and games which run in "embedded mode". However, not all of those use ggzcore directly, which is written in C and therefore mainly used by C programmers. Wrappers exist for C++ (called GGZCore++) and Python (called PyGGZCoreSimple). GGZCore++ is used by KGGZ and GGZap, and PyGGZCoreSimple is used by Víbora, the Pygame/SDL core client. In addition, GGZ-Java provides its own reimplementation of ggzcore. It is not yet offered as a library but usable as a package under the name ggz.client.core. An overview about the ggzcore library and its counterparts for other programming languages is given on its developer homepage. The overview includes links to API documentation if available.

The following text is a guide on how to use ggzcore. It sort of represents a tutorial which at some later point will be moved to its own document.

Initialising ggzcore is always the first step and performed with ggzcore_init. There are a few options which can be combined to tune the library behaviour:

The way ggzcore works is that it maps the entities to object-orientated structures and functions. Thus, after initialising the library with ggzcore_init, the first action will always be to initialise a server "object" by calling ggzcore_server_new. Afterwards, some variables may be set, like the hostname, but before actually connecting, callbacks must be set up because ggzcore works callback-based all the way. This can be done with ggzcore_server_add_event_hook. Examples of such hooks are GGZ_CONNECTED, when the connection is first established, or GGZ_LOGIN_FAIL, if the subsequent login did not succeed.

Server and rooms relation

As can bee seen in the picture, the server hosts a lot of rooms. The room list can be fetched by calling ggzcore_server_list_rooms, for which the event GGZ_ROOM_LIST will asynchronously be generated later on. The client can then change the room, this is what ggzcore_server_join_room is for.

In order to prepare gaming, the gametype associated to each room must be known also. As for the room list, the list of gametypes will arrive upon calling ggzcore_server_list_gametypes. Usually, this is even performed before joining any room, but to speed up things it could also be done afterwards in the background.

Just like a GGZServer object represents the server, the room the player has joined is accessible via a GGZRoom object, which can always conveniently be retrieved as the result of the function ggzcore_server_get_cur_room.


After entering a room, the players will likely see a visual list of players, passed to the client by ggzcore_room_get_nth_player. A message can be sent to all of them by calling ggzcore_room_chat with a chat type of GGZ_CHAT_NORMAL. Likewise, using GGZ_CHAT_BEEP and GGZ_CHAT_PERSONAL send a beep or a message to a selected player, respectively. Administrative broadcasts are possible with GGZ_CHAT_ANNOUNCE. However, in order to receive all the chat messages, the room hooks must be set up just like the server hooks were, which is the task of ggzcore_room_add_event_hook.

It is also possible to chat with a subgroup of people who are playing on the same table. In order to get that far, a closer look at how games are launched must be done first.

Playing games

The gametype associated with each room must be supported by at least one game client, but there can also be multiple frontends for each game. The way a launch works, a GGZTable object is built first with ggzcore_table_new, and its seats are configured by the launching player, who is also known as game host, as opposed to the other players who will join later on.

Tables and players in a room

The core client will then move the players to the table, and out of the list of players who are not on any table. During the game, it keeps the connection to the game client using several functions of the ggzcore library, so when a game requests statistics, for instance, it will relay this request to the main server (ggzd), read the statistics, and forward them to the game client again. This helps to keep the game protocols small, since all the common data exchanges can be done via GGZ. The same goes for game and team chat.

The launch in detail

Launching table and game

The way from wanting to play a game to actually playing it is very complex. It consists of two parts, table launch and game launch, where the first part only applies to the first player, as all others can simply join the table.

It is important to know when to start reading data from the game module's control file descriptor and when to stop it again - at this time the game will already be set to the PLAYING state and the core client has mostly done its duty.