libggzmod(3)							C Library Functions						      libggzmod(3)

NAME

       libggzmod - The GGZ Gaming Zone game frontend library.

DESCRIPTION

       This  library  allows games to communicate with the GGZ Gaming Zone core client, which allows establishing the connection to the GGZ Gaming
       Zone server and its associated game server.

       The libggzmod allows game authors to use GGZ Gaming Zone in their game clients. This library provides a state  engine  and  an  event  dis-
       patcher.  The  states  are  associated  with  the  game	tables.  Each  table  has  a current state which is tracked by GGZMod and the GGZ-
       MOD_EVENT_STATE is propagated to the game server, each time game state changes.

   STATES
       GGZMOD_STATE_CREATED    The game is in this state when it is executed for the first time. This state should never be changed back once  the
			       state is set.

       GGZMOD_STATE_CONNECTED  Once  the  GGZ  client  and the game are connected, the game changes state to this automatically. This state should
			       never be changed back once the game leaves this state.

       GGZMOD_STATE_WAITING    After the game client and game server are connected, the client enters this state. The game  client  may  now  call
			       ggzmod_set_state to change states between GGZMOD_STATE_WAITING, GGZMOD_STATE_PLAYING, and GGZMOD_STATE_DONE.

       GGZMOD_STATE_PLAYING    This  state  tells that the game is actively being played, while the GGZMOD_STATE_WAITING state in the game is con-
			       sidered waiting for players.

       GGZMOD_STATE_DONE       This state indicates the table is considered dead and will exit shortly thereafter.

   EVENTS
       For each of the events available in GGZModEvent, the table may register a handler to handle that event.	Events include:

       GGZMOD_EVENT_STATE

	   Inform about a new game status. The old state (a GGZModState*) is passed as the event's data.

       GGZMOD_EVENT_SERVER

	   This event occurs when a new connection to the game server has been made, either by the core client or by the game  client  itself.	In
	   this case the fd is passed as the event's data.

       GGZMOD_EVENT_PLAYER

	   This  event occurs when the player's seat status changes.  For example, if a player or bot joins, leaves seat, or starts/stops spectat-
	   ing. The passed event data is a int[2] pair consisting of the old {is_spectator, seat_num}.

       GGZMOD_EVENT_SEAT

	   Informs about seat changes.	The old seat (a GGZSeat*) is passed as the event data. The seat information will be  updated  before  this
	   event is invoked.

       GGZMOD_EVENT_SPECTATOR_SEAT

	   This  event occurs when a spectator seat change happens.   The old spectator (a GGZSpectator*) is passed as the event data. The specta-
	   tor information will be updated before this event is invoked.

       GGZMOD_EVENT_CHAT

	   This is an event for receiving a chat. The chat may have originated in another game client or from the GGZ client. The chat information
	   (a GGZChat*) is passed as the event's data.

       GGZMOD_EVENT_STATS

	   This is an event informing that player's statistics have been updated.

       GGZMOD_EVENT_INFO

	   This  event	fires  when information about one or more other players has been requested and has been received. The event's data is in a
	   GGZPlayerInfo* structure or NULL if information about all players was requested.

       GGZMOD_EVENT_ERROR

	   This event informs about GGZMod errors. An error message (a char*) is passed as the event's data. The GGZMod  may  attempt  to  recover
	   from the error, but it is not guaranteed that the GGZ connection will continue to work after an error has happened.

FILES

       The following files are used by this library:

       /usr/lib/libggzmod.so	       The GGZ Gaming Zone game frontend shared library

       /etc/ggz.modules 	       Game module registry for game clients

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWgnome-games		   |
       +-----------------------------+-----------------------------+
       |Interface stability	     |Volatile			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       ggz_h(3),  ggzcore_h(3),  ggzmod_h(3), libggz(3), libggzcore(3), attributes(5), ggz.modules(5), gnome-interfaces(5), ggz(6), ggz-config(6),
       ggz(7)

       GGZ Gaming Zone:

	   http://www.ggzgamingzone.org/
	   http://www.ggzgamingzone.org/docs/api/libggz/
	   http://www.ggzgamingzone.org/docs/api/ggzcore/
	   http://www.ggzgamingzone.org/docs/api/ggzmod/

NOTES

       Written by Michal Pryc, Sun Microsystems Inc., 2008.

SunOS 5.11							    29 May 2008 						      libggzmod(3)