ggzmod.h(3)
โจ ggzmod.h(3) โ GGZMod โจ
๐ NAME ๐
ggzmod.h โ common functions for interfacing a game server and GGZ. Like, the whole bestie bridge between your game server and GGZ, no cap.
๐ SYNOPSIS ๐
#include <ggz.h>
#include <ggz_common.h>
โจ Defines โจ
#define GGZMOD_VERSION_MAJOR 0โ major version, bestie.#define GGZMOD_VERSION_MINOR 0โ minor version.#define GGZMOD_VERSION_MICRO 11โ micro version.#define GGZMOD_VERSION_IFACE '3:1:1'โ interface version.
๐ฆ Typedefs ๐ฆ
typedef GGZMod GGZModโ a GGZmod object, used for tracking aggz<->tableconnection. Iconic.typedef void(* GGZModHandler )(GGZMod *mod, GGZModEvent e, const void *data)โ event handler prototype. The callback blueprint, fr fr.
๐ Enumerations ๐
enum GGZModState { GGZMOD_STATE_CREATED, GGZMOD_STATE_CONNECTED, GGZMOD_STATE_WAITING, GGZMOD_STATE_PLAYING, GGZMOD_STATE_DONE }โ table states. The whole arc, honestly.enum GGZModEvent { GGZMOD_EVENT_STATE, GGZMOD_EVENT_SERVER, GGZMOD_EVENT_PLAYER, GGZMOD_EVENT_SEAT, GGZMOD_EVENT_SPECTATOR_SEAT, GGZMOD_EVENT_CHAT, GGZMOD_EVENT_STATS, GGZMOD_EVENT_ERROR }โ callback events.enum GGZModType { GGZMOD_GGZ, GGZMOD_GAME }โ the'type'of ggzmod.
๐ฅ Functions ๐ฅ
GGZMod * ggzmod_new (GGZModType type)โ create a new ggzmod object. New main character just dropped.void ggzmod_free (GGZMod *ggzmod)โ destroy a finished ggzmod object. Clean up, bestie.int ggzmod_get_fd (GGZMod *ggzmod)โ get the file descriptor for the GGZMod socket.GGZModType ggzmod_get_type (GGZMod *ggzmod)โ get the type of the ggzmod object.GGZModState ggzmod_get_state (GGZMod *ggzmod)โ get the current state of the table.int ggzmod_get_server_fd (GGZMod *ggzmod)โ get the fd of the game server connection.int ggzmod_get_num_seats (GGZMod *ggzmod)โ get the total number of seats at the table.GGZSeat ggzmod_get_seat (GGZMod *ggzmod, int seat)โ get all data for the specified seat.int ggzmod_get_num_spectator_seats (GGZMod *ggzmod)โ get the maximum number of spectators. 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. ๐GGZSpectatorSeat ggzmod_get_spectator_seat (GGZMod *ggzmod, int seat)โ get a spectator's data.const char * ggzmod_get_player (GGZMod *ggzmod, int *is_spectator, int *seat_num)โ get data about this player.void * ggzmod_get_gamedata (GGZMod *ggzmod)โ return gamedata pointer.void ggzmod_set_gamedata (GGZMod *ggzmod, void *data)โ set gamedata pointer.void ggzmod_set_handler (GGZMod *ggzmod, GGZModEvent e, GGZModHandler func)โ set a handler for the given event.int ggzmod_dispatch (GGZMod *ggzmod)โ check for and handle input.int ggzmod_set_state (GGZMod *ggzmod, GGZModState state)โ change the table's state.int ggzmod_connect (GGZMod *ggzmod)โ connect to ggz.int ggzmod_disconnect (GGZMod *ggzmod)โ disconnect from ggz.void ggzmod_request_stand (GGZMod *ggzmod)โ stand up (move from your seat into a spectator seat).void ggzmod_request_sit (GGZMod *ggzmod, int seat_num)โ sit down (move from a spectator seat into a player seat).void ggzmod_request_boot (GGZMod *ggzmod, const char *name)โ boot a player. Only the game host may do this.void ggzmod_request_bot (GGZMod *ggzmod, int seat_num)โ change the requested seat from an opean seat to a bot.void ggzmod_request_open (GGZMod *ggzmod, int seat_num)โ change the requested seat from a bot to an open seat.void ggzmod_request_chat (GGZMod *ggzmod, const char *chat_msg)โ chat! This initiates a table chat.int ggzmod_player_get_record (GGZMod *ggzmod, GGZSeat *seat, int *wins, int *losses, int *ties, int *forfeits)โ get the player's win-loss record.int ggzmod_player_get_rating (GGZMod *ggzmod, GGZSeat *seat, int *rating)โ get the player's rating.int ggzmod_player_get_ranking (GGZMod *ggzmod, GGZSeat *seat, int *ranking)โ get the player's ranking.int ggzmod_player_get_highscore (GGZMod *ggzmod, GGZSeat *seat, int *highscore)โ get the player's highscore.int ggzmod_spectator_get_record (GGZMod *ggzmod, GGZSpectatorSeat *seat, int *wins, int *losses, int *ties, int *forfeits)โ get the spectator's win-loss record.int ggzmod_spectator_get_rating (GGZMod *ggzmod, GGZSpectatorSeat *seat, int *rating)โ get the spectator's rating.int ggzmod_spectator_get_ranking (GGZMod *ggzmod, GGZSpectatorSeat *seat, int *ranking)โ get the spectator's ranking.int ggzmod_spectator_get_highscore (GGZMod *ggzmod, GGZSpectatorSeat *seat, int *highscore)โ get the spectator's highscore.
๐ Detailed Description ๐
Common functions for interfacing a game server and GGZ. That's the whole vibe.
This file contains all libggzmod functions used by game servers to interface with GGZ (and vice versa). Just include ggzmod.h and make sure your program is linked with libggzmod. Then use the functions below as appropriate. Periodt.
GGZmod currently provides an event-driven interface. Data from communication sockets is read in by the library, and a handler function (registered as a callback) is invoked to handle any events. The calling program should not read/write data from/to the GGZ socket unless it really knows what it is doing. Like, seriously, don't touch unless you're built different.
That this does not apply to the client sockets: 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. So, yeah, no reading. ๐ซถ
For more information, see the documentation at http://ggz.sf.net/.
๐ง Typedef Documentation ๐ง
typedef struct GGZMod GGZMod
A GGZmod object, used for tracking a ggz<->table connection.
A game client should track a pointer to a GGZMod object; it contains all the state information for communicating with GGZ. The GGZ client will track one such object for every game table that is running. That's a lot of tracking, but okay.
typedef void(* GGZModHandler)(GGZMod *mod, GGZModEvent e, const void *data)
Event handler prototype.
A function of this type will be called to handle a ggzmod event.
Parameters:
modโ The ggzmod state object.eโ The event that has occured.dataโ Pointer to additional data for the event. The additional data will be of the following form:GGZMOD_EVENT_STATE: The old state (GGZModState*)GGZMOD_EVENT_SERVER: The fd of the server connection (int*)GGZMOD_EVENT_PLAYER: The old player data (int[2])GGZMOD_EVENT_SEAT: The old seat (GGZSeat*)GGZMOD_EVENT_SPECTATOR_SEAT: The old seat (GGZSpectatorSeat*)GGZMOD_EVENT_ERROR: An error string (char*)
โจ Enumeration Type Documentation โจ
๐ธ enum GGZModEvent ๐ธ
okay so these are the Callback events. ๐ Each one is a possible GGZmod event, and for each event the table can register a handler with GGZmod to handle that event. slay.
See also: GGZModHandler, ggzmod_set_handler ๐ซถ
๐ซ Enumeration values ๐ซ
GGZMOD_EVENT_STATEโ Module status changed. This event pops off when the game's status changes. The old state (aGGZModState*) is passed as the event's data. โจ See also:GGZModStateGGZMOD_EVENT_SERVERโ A new server connection has been made. This event shows up when a new connection to the game server has been made. Thefdis passed as the event's data. ๐ฅGGZMOD_EVENT_PLAYERโ The 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 aint[2]pair consisting of the old{is_spectator, seat_num}. ๐GGZMOD_EVENT_SEATโ A seat change. This event occurs when a seat change occurs. The old seat (aGGZSeat*) is passed as the event's data. The seat information will be updated before the event is invoked. ๐ชGGZMOD_EVENT_SPECTATOR_SEATโ A spectator seat change. This event occurs when a spectator seat change occurs. The old spectator (aGGZSpectator*) is passed as the event's data. The spectator information will be updated before the event is invoked. ๐๏ธGGZMOD_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 (aGGZChat*) 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. ๐ฌGGZMOD_EVENT_STATSโ A player's stats have been updated. See also:ggzmod_player_get_record,ggzmod_player_get_rating,ggzmod_player_get_ranking,ggzmod_player_get_highscoreParameters:dataโ The name of the player whose stats have changed. ๐GGZMOD_EVENT_ERRORโ An error has occurred. This event occurs when a GGZMod error has occurred. An error message (achar*) 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. ๐
๐ฆ enum 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 ggzmod_set_state 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 (ggzmod_loop will stop looping, etc.) (see the kill_on_exit game option). ๐ญ
Each time the game state changes, a GGZMOD_EVENT_STATE event will be propogated to the game server. ๐
๐ Enumeration values ๐
GGZMOD_STATE_CREATEDโ Initial state. The game starts out in this state. Once the state is changed it should never be changed back. ๐ซGGZMOD_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. ๐GGZMOD_STATE_WAITINGโ Waiting state. After the game client and game server are connected, the client enters the waiting state. The game client may now callggzmod_set_stateto change betweenWAITING,PLAYING, andDONEstates. โณGGZMOD_STATE_PLAYINGโ Playing state. This state is only entered after the game client changes state to it viaggzmod_set_state. State may be changed back and forth betweenWAITINGandPLAYINGas many times as are wanted. ๐ฎGGZMOD_STATE_DONEโ Done state. Once the game client is done running,ggzmod_set_stateshould 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. ๐
๐ enum GGZModType ๐
The 'type' of ggzmod. The 'flavor' of GGZmod object this is. Affects what operations are allowed. โจ
๐ Enumeration values ๐
GGZMOD_GGZโ Used by the ggz client ('ggz'). ๐GGZMOD_GAMEโ Used by the game client ('table'). ๐
๐ฅ FUNCTION DOCUMENTATION ๐ฅ
Okay bestie, this is the big one. Every single function in ggzmod.h, in alphabetical order, zero skips, zero shortcuts. Buckle up ๐
ggzmod_connect
int ggzmod_connect (GGZMod * ggzmod)
Connect to ggz.
Call this function to make an initial GGZ <-> game connection. It's giving first-contact energy โจ
- When called by the game server, this function makes the physical connection to ggz.
- When called by ggz, it will launch a table and connect to it.
Parameters:
ggzmodโ The ggzmod object.
Returns:
0 on success, -1 on failure.
ggzmod_disconnect
int ggzmod_disconnect (GGZMod * ggzmod)
Disconnect from ggz. The breakup arc ๐ญ
- 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.
- When called by the GGZ server, this function will kill and clean up after the table.
Parameters:
ggzmodโ The ggzmod object.
Returns:
0 on success, -1 on failure.
ggzmod_dispatch
int ggzmod_dispatch (GGZMod * ggzmod)
Check for and handle input. This is the vibe-check function, fr fr.
This function handles input from the communications sockets:
- It will check for input, but will not block.
- It will monitor input from the GGZmod socket.
- It will monitor input from player sockets only if a handler is registered for the
PLAYER_DATAevent. - It will call an event handler as necessary.
Parameters:
ggzmodโ The ggzmod object.
Returns:
-1 on error, the number of events handled (0-1) on success.
ggzmod_free
void ggzmod_free (GGZMod * ggzmod)
Destroy a finished ggzmod object. It's the it's over moment, but make it clean ๐ง
After the connection is through, the object may be freed.
Parameters:
ggzmodโ The GGZMod object.
ggzmod_get_fd
int ggzmod_get_fd (GGZMod * ggzmod)
Get the file descriptor for the GGZMod socket.
Parameters:
ggzmodโ The GGZMod object.
Returns:
GGZMod's main ggz <-> table socket FD.
ggzmod_get_gamedata
void* ggzmod_get_gamedata (GGZMod * ggzmod)
Return gamedata pointer.
Each GGZMod object can be given a 'gamedata' pointer that is returned by this function. This is useful for when a single process serves multiple GGZmod's. Very "one server, many tables, main character energy" of it ๐
Parameters:
ggzmodโ The GGZMod object.
Returns:
A pointer to the gamedata block (or NULL if none).
See also:
ggzmod_set_gamedata
ggzmod_get_num_seats
int ggzmod_get_num_seats (GGZMod * ggzmod)
Get the total number of seats at the table.
Returns:
The number of seats, or -1 on error.
Note:
- If no connection is present,
-1will be returned. - While in
GGZMOD_STATE_CREATED, we don't know the number of seats.
ggzmod_get_num_spectator_seats
int ggzmod_get_num_spectator_seats (GGZMod * ggzmod)
Get the maximum number of spectators. 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. Not me calling the same function over and over ๐ญ
Returns:
The number of available spectator seats, or -1 on error.
ggzmod_get_player
const char* ggzmod_get_player (GGZMod * ggzmod, int * is_spectator, int *
seat_num)
Get data about this player.
Call this function to find out where at the table this player is sitting. Like, physically seated. At the table. ๐
Parameters:
ggzmodโ The GGZMod object.is_spectatorโ Will be set toTRUEiff player is spectating.seat_numโ Will be set to the number of our (spectator) seat.
Returns:
The name of the player (or NULL on error).
ggzmod_get_seat
GGZSeat ggzmod_get_seat (GGZMod * ggzmod, int seat)
Get all data for the specified seat.
Parameters:
ggzmodโ The GGZMod object.seatโ The seat number (0..(number of seats - 1)).
Returns:
A valid GGZSeat structure, if seat is a valid seat.
ggzmod_get_server_fd
int ggzmod_get_server_fd (GGZMod * ggzmod)
Get the fd of the game server connection.
Parameters:
ggzmodโ The GGZMod object.
Returns:
The server connection fd
ggzmod_get_spectator_seat
GGZSpectatorSeat ggzmod_get_spectator_seat (GGZMod * ggzmod, int seat)
Get a spectator's data. We see you, lurkers ๐
Parameters:
ggzmodโ The GGZMod object.seatโ The number, between0and(number of spectators - 1).
Returns:
A valid GGZSpectator structure, if given a valid seat.
ggzmod_get_state
GGZModState ggzmod_get_state (GGZMod * ggzmod)
Get the current state of the table.
Parameters:
ggzmodโ The GGZMod object.
Returns:
The state of the table.
ggzmod_get_type
GGZModType ggzmod_get_type (GGZMod * ggzmod)
Get the type of the ggzmod object.
Parameters:
ggzmodโ The GGZMod object.
Returns:
The type of the GGZMod object (GGZ or GAME).
ggzmod_new
GGZMod* ggzmod_new (GGZModType type)
Create a new ggzmod object. Baby's first ggzmod ๐
Before connecting through ggzmod, a new ggzmod object is needed.
Parameters:
typeโ The type of ggzmod. Should beGGZMOD_GAMEfor game servers.
See also:
GGZModType
ggzmod_player_get_highscore
int ggzmod_player_get_highscore (GGZMod * ggzmod, GGZSeat * seat, int *
highscore)
Get the player's highscore. Slay, honestly ๐ฅ
Returns:
TRUE if there is a highscore; FALSE if not or on error.
ggzmod_player_get_ranking
int ggzmod_player_get_ranking (GGZMod * ggzmod, GGZSeat * seat, int *
ranking)
Get the player's ranking.
Returns:
TRUE if there is a ranking; FALSE if not or on error.
ggzmod_player_get_rating
int ggzmod_player_get_rating (GGZMod * ggzmod, GGZSeat * seat, int * rating)
Get the player's rating.
Returns:
TRUE if there is a rating; FALSE if not or on error.
ggzmod_player_get_record
int ggzmod_player_get_record (GGZMod * ggzmod, GGZSeat * seat, int * wins,
int * losses, int * ties, int * forfeits)
Get the player's win-loss record. The receipts ๐
Returns:
TRUE if there is a record; FALSE if not or on error.
ggzmod_request_boot
void ggzmod_request_boot (GGZMod * ggzmod, const char * name)
Boot a player. Only the game host may do this. Host privileges, periodt ๐
Parameters:
ggzmodโ The ggzmod object.nameโ The name of the player to boot.
ggzmod_request_bot
void ggzmod_request_bot (GGZMod * ggzmod, int seat_num)
Change the requested seat from an opean seat to a bot. (Yes, "opean". We keep it exactly as written, bestie โ no cap ๐ซถ)
Parameters:
ggzmodโ The ggzmod object.seat_numโ The number of the seat to toggle.
ggzmod_request_chat
void ggzmod_request_chat (GGZMod * ggzmod, const char * chat_msg)
Chat! This initiates a table chat. Group chat, but make it a table ๐ฌ
Parameters:
ggzmodโ The ggzmod object.chat_msgโ The chat message.
Note:
The chat message should be in UTF-8.
ggzmod_request_open
void ggzmod_request_open (GGZMod * ggzmod, int seat_num)
Change the requested seat from a bot to an open seat. Bye bot, hello human ๐ธ
Parameters:
ggzmodโ The ggzmod object.seat_numโ The number of the seat to toggle.
ggzmod_request_sit
void ggzmod_request_sit (GGZMod * ggzmod, int seat_num)
Sit down (move from a spectator seat into a player seat). Glow up from lurker to player โจ
Parameters:
ggzmodโ The ggzmod object.seat_numโ The seat to sit in.
ggzmod_request_stand
void ggzmod_request_stand (GGZMod * ggzmod)
Stand up (move from your seat into a spectator seat). Time to spectate, ngl ๐ฆ
Parameters:
ggzmodโ The ggzmod object.
ggzmod_set_gamedata
void ggzmod_set_gamedata (GGZMod * ggzmod, void * data)
Set gamedata pointer.
Parameters:
ggzmodโ The GGZMod object.dataโ The gamedata block (orNULLfor none).
See also:
ggzmod_get_gamedata
ggzmod_set_handler
void ggzmod_set_handler (GGZMod * ggzmod, GGZModEvent e, GGZModHandler func)
Set a handler for the given event.
As described above, GGZmod uses an event-driven structure. Each time an event is called, the event handler (there can be only one) for that event will be called. This function registers such an event handler.
Parameters:
ggzmodโ The GGZmod object.eโ The GGZmod event.funcโ The handler function being registered.
See also:
ggzmod_get_gamedata
ggzmod_set_state
int ggzmod_set_state (GGZMod * ggzmod, 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. Whole arc in three states ๐
Parameters:
ggzmodโ The ggzmod object.stateโ The new state.
Returns:
0 on success, -1 on failure/error.
ggzmod_spectator_get_highscore
int ggzmod_spectator_get_highscore (GGZMod * ggzmod, GGZSpectatorSeat *
seat, int * highscore)
Get the spectator's highscore.
Returns:
TRUE if there is a highscore; FALSE if not or on error.
ggzmod_spectator_get_ranking
int ggzmod_spectator_get_ranking (GGZMod * ggzmod, GGZSpectatorSeat * seat,
int * ranking)
Get the spectator's ranking.
Returns:
TRUE if there is a ranking; FALSE if not or on error.
ggzmod_spectator_get_rating
int ggzmod_spectator_get_rating (GGZMod * ggzmod, GGZSpectatorSeat * seat,
int * rating)
Get the spectator's rating.
Returns:
TRUE if there is a rating; FALSE if not or on error.
ggzmod_spectator_get_record
int ggzmod_spectator_get_record (GGZMod * ggzmod, GGZSpectatorSeat * seat,
int * wins, int * losses, int * ties, int * forfeits)
Get the spectator's win-loss record. Even the spectators keep receipts, apparently ๐ญ
Returns:
TRUE if there is a record; FALSE if not or on error.
๐ AUTHOR ๐
Generated automatically by Doxygen for GGZMod from the source code.
And that's the whole page, bestie! No seats left empty, every function accounted for, nothing skipped. You ate that ๐ซถ
Version 0.0.11, dated 21 May 2005, and yeah โ this whole thing was auto-generated by Doxygen for GGZMod straight from the source code. Iconic. Periodt. ๐
โจ๐
๐ฆ where this page comes from
- fedora 43: ggz-base-libs-devel 0.99.5-41.fc43 ยท LicenseRef-Callaway-LGPLv2+ AND GPL-2.0-or-later
- fedora 43: ggz-base-libs-devel 0.99.5-41.fc43 ยท LicenseRef-Callaway-LGPLv2+ AND GPL-2.0-or-later
- nixos 26.05: ggz-base-libs 0.99.5
- nixpkgs unstable: ggz-base-libs 0.99.5
- ๐ girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms