ggzmod Python Module Reference

Common functions for interfacing with the GGZ system from GGZ game clients. More...

import ggzmod

Enumerations
GGZModState	STATE_CREATED, STATE_CONNECTED, STATE_WAITING, STATE_PLAYING, STATE_DONE
	Table states. More...
GGZModEvent	EVENT_STATE, EVENT_SERVER, EVENT_PLAYER, EVENT_SEAT, EVENT_SPECTATOR, EVENT_CHAT, EVENT_STATS, EVENT_INFO, EVENT_ERROR
	Callback events from the GGZ core client. More...
GGZSeatType	SEAT_NONE, SEAT_OPEN, SEAT_BOT, SEAT_PLAYER, SEAT_RESERVED, SEAT_ABANDONED
	Possible types of each seat. More...
Functions
None	setHandler (GGZModEvent event, method)
	Sets up a Python method callback for the given event.
boolean	connect ()
	Connects to the GGZ core client.
boolean	disconnect ()
	Disconnects from the GGZ core client.
boolean	setState (GGZModState state)
	Changes the table's state.
GGZModState	getState ()
	Get the current state of the table.
boolean	autonetwork ()
	Checks for messages from the GGZ core client and the game server.
int/socket	getFd ()
	Get the file descriptor of the game server connection.
int	getNumSeats ()
	Get the total number of seats at the table.
int	getNumSpectators ()
	Get the current number of spectators, which may change constantly.
(int, GGZModSeatType, string)	getSeat (int number)
	Get all data for the specified seat.
(int, string)	getSpectator (int number)
	Get a spectator's data.
(string, boolean, int)	getPlayer ()
	Get data about this player.
None	requestStand ()
	Stand up (move from your seat into a spectator seat).
None	requestSit (int number)
	Sit down (move from a spectator seat into a player seat).
None	requestBoot (string name)
	Boot a player. Only the game host may do this.
None	requestBot (int number)
	Change the requested seat from an opean seat to a bot.
None	requestOpen (int number)
	Change the requested seat from a bot to an open seat.
None	requestChat (string message)
	Chat! This initiates a table chat.
boolean	requestInfo (int number)
	Request extended player information for one or more players.
(int, string, string, string)	getInfo (int number)
	Get the extended information for the specified seat.
(int, int, int, int)	getRecord (int number)
	Get the player's win-loss record.
(int)	getRating (int number)
	Get the player's rating.
(int)	getRanking (int number)
	Get the player's ranking.
(int)	getHighscore (int number)
	Get the player's highscore.

---

Detailed Description

Common functions for interfacing with the GGZ system from GGZ game clients.

This module contains wrappers for all libggzmod functions used by game clients to interface with GGZ server events as received by the GGZ core clients, and to get the connection to the game server. Just import the ggzmod module and use the module-level functions below as appropriate.

GGZmod currently provides an event-driven interface. Data from communication sockets is read in by the library, and a handler method (registered as a callback) is invoked to handle any events such as joining players, chat messages and statistics updates.

GGZMod provides one file desriptor for communicating (TCP) to each client. If data is ready to be read by one of these file descriptors ggzmod may invoke the appropriate handler (see below), but will never actually read any data.

In essence, a game client will check first whether it runs in GGZ mode at all. If this is the case, the environment variable GGZMODE=true is set, even though games might opt to use command line parameters to determine this. Then, the game will set up some event handlers using setHandler. None of these is required, but EVENT_SERVER is recommended to know when the connection to the game server has been established. At some point, the game will invoke connect to enter in contact with the GGZ core client, which in turn is connected to the GGZ server and will establish the game connection, as described above. The game client and server will then communicate over their protocol, and the game client needs to call autonetwork in order to know when new messages have arrived. Sending and receiving messages happens via a Python socket object on top of the game connection file descriptor, which is returned by getFd. A good game will also keep track of the game or table state, which can be set to STATE_WAITING for the (optional) pregame phase, to STATE_PLAYING for the game itself, and finally to STATE_DONE to indicate that the game is over and no player wants to start another game on the same table.

For more information, see the documentation at http://www.ggzgamingzone.org/.

---

Enumeration Type Documentation

GGZModEvent

Callback events. Each of these is a possible GGZmod event. For each event, the table may register a handler with GGZmod to handle that event. All callback handlers are Python methods which will receive one or more values, or none at all, depending on the event type. See also: setHandler Enumeration values: EVENT_STATE Module status changed. This event occurs when the game's status changes. The old state (a GGZModState) is passed as the event's data. EVENT_SERVER A new server connection has been made. This event occurs when a new connection to the game server has been made. The file descriptor is passed as the event's data. It should be used to construct a Python socket object, but can otherwise be discarded since it can always be gotten by calling getFd. EVENT_PLAYER The game client player's seat status has changed. This event occurs when the player's seat status changes; i.e. he changes seats or starts/stops spectating. The event data is given as two variables, the old spectator status (either True if he was a spectator, or False otherwise) and the old seat number. EVENT_SEAT A seat change. This event occurs when a seat change occurs. The old seat number is passed as the event's data. The seat information will be updated before the event is invoked. EVENT_SPECTATOR A spectator seat change. This event occurs when a spectator seat change occurs. The old spectator number is passed as the event's data. The spectator information will be updated before the event is invoked. EVENT_CHAT A chat message event. This event occurs when we receive a chat. The chat may have originated in another game client or from the GGZ client; in either case it will be routed to us. The chat information, two variables being the sender name and message text, is passed as the event's data. Note that the chat may originate with a player or a spectator, and they may have changed seats or left the table by the time it gets to us. EVENT_STATS The statistics of some or all players have been updated. No values are given as data for this event, instead the game should use the statistics-related functions to get to know more about it. See also: getPlayerRecord getPlayerRating getPlayerRanking getPlayerHighscore EVENT_INFO Information has been requested about one or more players and it has now arrived. No values are given as data for this event, instead the game should use the player information functions to get to know more about it. See also: getInfo EVENT_ERROR An error has occurred. This event occurs when a GGZMod error has occurred. An error message string will be passed as the event's data. 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.

GGZModState

Table states. Each table has a current "state" that is tracked by ggzmod. First the table is executed and begins running. Then it receives a launch event from GGZ and begins waiting for players. At some point a game will be started and played at the table, after which it may return to waiting. Eventually the table will probably halt and then the program will exit. More specifically, the game is in the CREATED state when it is first executed. It moves to the CONNECTED state after GGZ first communicates with it, and to WAITING after the connection is established with the game server. After this, the game server may use setState to change between WAITING, PLAYING, and DONE states. A WAITING game is considered waiting for players (or whatever), while a PLAYING game is actively being played (this information may be, but currently is not, propogated back to GGZ for display purposes). Once the state is changed to DONE, the table is considered dead and will exit shortly thereafter. Each time the game state changes, an EVENT_STATE event will be propogated to the game server. Enumeration values: STATE_CREATED Initial state. The game starts out in this state. Once the state is changed it should never be changed back. STATE_CONNECTED Connected state. After the GGZ client and game client get connected, the game changes into this state automatically. Once this happens messages may be sent between these two. Once the game leaves this state it should never be changed back. STATE_WAITING Waiting state. After the game client and game server are connected, the client enters the waiting state. The game client may now call setState to change between WAITING, PLAYING, and DONE states. STATE_PLAYING Playing state. This state is only entered after the game client changes state to it via setState. State may be changed back and forth between WAITING and PLAYING as many times as are wanted. STATE_DONE Done state. Once the game client is done running, setState should be called to set the state to done. At this point nothing "new" can happen. The state cannot be changed again after this. However the game client will not be terminated by the GGZ client; GGZ just waits for it to exit of its own volition.

GGZSeatType

Seat types. Each "seat" at a table of a GGZ game can have one of these values. They are used by the GGZ client, GGZ server, and game servers; their use in game clients is completely optional. Enumeration values: SEAT_NONE This seat does not exist. SEAT_OPEN The seat is open (unoccupied). SEAT_BOT The seat has a bot (AI) in it. SEAT_PLAYER The seat has a regular player in it. SEAT_RESERVED The seat is reserved for a player. SEAT_ABANDONED The seat is abandoned by a player.

---

Function Documentation

boolean connect ()

Connect to GGZ. Call this function to make an initial GGZ <-> game connection. Note that as opposed to the C version, which always succeeds on some platforms, the Python version will require the environment variable GGZMODE to be set to disambiguate the launch in GGZ from other means. Returns: True on success, False on failure.

boolean disconnect ()

Disconnect from ggz. When called by the game server, this function stops the connection to GGZ. It should only be called when the table is ready to exit. Returns: True on success, False on failure.

boolean setState  (  GGZModState  state )

Change the table's state. This function should be called to change the state of a table. A game can use this function to change state between WAITING and PLAYING, or to set it to DONE. Parameters: state  The new state. Returns: True on success, False on failure/error.

int getFd ()

Get the file descriptor of the game server connection. Returns: A valid file descriptor on success, -1 on failure.

GGZModState getState ()

Get the current state of the table. Returns: The state of the table.

boolean autonetwork ()

Checks for messages from the GGZ core client and the game server. Any GGZ events are processed first. If data from the game server is also available, it is left in place, and the functions returns True to indicate that the game client may read the data from the server using the file descriptor obtained by getFd. Returns: True if data has arrived, False otherwise.

setHandler (  GGZModEvent  event, python method   method )

Sets up a Python method callback for the given event. Whenever the event will occur, the callback will be invoked with parameters according to the documentation of GGZModEvent. Parameters: event  The GGZMod event. method  The handler method being registered.

int getNumSeats ()

Get the total number of seats at the table. As long as the table is in the state STATE_CREATED, the number of seats is not known, and hence -1 is returned, just like in the case of other errors. Returns: The number of seats, or -1 on error.

int getNumSpectators ()

Get the current number of spectators, which may change constantly. This function returns the maximum number of spectator seats available. A game can use this to iterate over the spectator seats to look for spectators occupying them. Since spectators may come and go at any point and there is no limit on the number of spectators, you should consider this value to be dynamic and call this function again each time you're looking for spectators. Returns: The current number of spectators, or -1 on error.

(int, GGZModSeatType, string) getSeat  (  int  number )

Get all data for the specified seat. The function returns information about a seat assignment, like the seat type (player, bot, empty...) and the name in the case of players, bots, reserved and abandoned seats. Parameters: number  The seat number. Returns: A 3-element tuple (int num, GGZSeatType type, string name) containing the seat number which was given to the function, the seat type and the name of the player or bot, if applicable. The name is None in cases like open seats, and the whole result can be None if an invalid seat number was given.

(int, string) getSpectator  (  int  number )

Get a spectator's data. This function can be used to look up the names of all spectating people. Parameters: number  The spectator seat number. Returns: A 2-element tuple (int num, string name) containing the seat number which was given to the function and the name of the spectator. The whole result can be None if an invalid spectator seat number was given.

(string, boolean, int) getPlayer ()

Get data about the player who is represented by this game client. Call this function to find out where at the table this player is sitting. Returns: A 3-element tuple (string name, boolean isspectator, int num) containing the player's name, whether he is currently spectating or not, and the seat or spectator seat number. In the case of errors, None is returned instead.

requestStand ()

Stand up (move from your seat into a spectator seat). The player of the game client itself will quit playing and becoming a spectator instead.

requestSit  (  int  number )

Sit down (move from a spectator seat into a player seat). The player of the game client itself will stop spectating and become a player again, in case a free seat is still available. Parameters: number  The seat number where to sit down.

requestBoot  (  string  name )

Boot a player. Only the game host may do this. Game host refers to the player who has initiated the game. The booted player will then be forced to leave the current table. Parameters: name  The name of the player to boot.

requestBot  (  int  number )

Change the requested seat from an opean seat to a bot. This is useful in case a game is stuck because one seat is not assigned to anybody yet. This methods creates an AI player who will then play in the given seat. Parameters: number  The seat number where to place a bot.

requestOpen  (  int  number )

Change the requested seat from a bot to an open seat. This is comparable to booting a player, instead it works on AI players in this method. Parameters: number  The seat number which should be opened.

requestChat  (  string  message )

Chat! This initiates a table chat. Table chat refers to messages which only the participants of the current game can send. Parameters: message  The chat message.

boolean requestInfo  (  int  number )

Request extended player information for one or more players. Depending on the seat parameter (-1 or valid number), this function asynchronously requests information about player(s), which will arrive with a EVENT_INFO event. Parameters: number  The seat number to request info for, or -1 to select all. Returns: True if seat is -1 or valid number, False for non-player seats.

(int, string, string, string) getInfo  (  int  number )

Get the extended information for the specified seat. Calling this method might reveal player properties beyond the login name. Parameters: number  The seat number. Returns: A tuple describing the player's properties, containing (seat number, realname, photo, host) if seat is valid and has info, None otherwise.

(int, int, int, int) getRecord  (  int  number )

Get the player's win-loss record. Tells about how the player performed so far for the current game type. The record consists of simple additions of the number of wins, losses, ties and forfeits achieved in the past. Parameters: number  The seat number to Returns: A statistics tuple containing (wins, losses, ties, forfeits) for valid seats, or None otherwise.

(int) getRating  (  int  number )

Get the player's rating. Tells about how the player performed so far for the current game type. Ratings are game-specific calculated values, which many times take into account the quality of play over many games. Parameters: number  The seat number. Returns: The player's rating in a 1-element tuple, or None if the player doesn't have a rating yet or the present game type doesn't support ratings.

(int) getRanking  (  int  number )

Get the player's ranking. Tells about how the player performed so far for the current game type. Rankings range from number 1 (the best) to higher numbers (worse) and are calculated automatically based on the player's record, rating and highscore, depending on the game type. The ranking is guaranteed to be unique per game type. Parameters: number  The seat number. Returns: The player's ranking in a 1-element tuple, or None if the player doesn't have a ranking yet or the present game type doesn't support rankings.

(int) getHighscore  (  int  number )

Get the player's highscore. Tells about how the player performed so far for the current game type. The highscore is a single number, the higher the better. Parameters: number  The seat number. Returns: The player's highscore in a 1-element tuple, or None if the player doesn't have a highscore yet or the present game type doesn't support highscores.

---