ggzcore.h(3)

📦 version 0.99.5, in fedora 43, nixos 26.05, nixpkgs unstable

okay bestie, welcome to ggzcore.h(3) — the GGZCore manual page 💅 this is the interface for the ggzcore library used by GGZ clients, and we're about to go through it together. no cap.

💖 NAME 💖

ggzcore.h — the interface for the ggzcore library used by GGZ clients. periodt.

✨ SYNOPSIS ✨

first things first, you gotta include these:

#include <stdarg.h>
#include <sys/types.h>
#include <ggz_common.h>

🎀 Defines 🎀

okay so here's the define section, and it's giving version numbers plus a whole squad of debug tags. let's go one by one, bestie ✨

#define GGZCORE_VERSION_MAJOR 0 — the major version, and it's literally 0. humble beginnings.
#define GGZCORE_VERSION_MINOR 0 — minor version, also 0.
#define GGZCORE_VERSION_MICRO 11 — micro version, sitting at 11.
#define GGZCORE_VERSION_IFACE '7:0:0' — the interface version string, exactly '7:0:0'.
#define GGZCORE_DBG_CONF 'GGZCORE:CONF' — this is a ggz_debug debugging type for the configuration system. so if you're debugging config stuff, this is the tag.
#define GGZCORE_DBG_GAME 'GGZCORE:GAME' — ggz_debug debugging type for game communication.
#define GGZCORE_DBG_HOOK 'GGZCORE:HOOK' — ggz_debug debugging type for the hook system.
#define GGZCORE_DBG_MODULE 'GGZCORE:MODULE' — ggz_debug debugging type for accessing modules.
#define GGZCORE_DBG_NET 'GGZCORE:NET' — ggz_debug debugging type for network interaction.
#define GGZCORE_DBG_POLL 'GGZCORE:POLL' — ggz_debug debugging type for debugging while polling.
#define GGZCORE_DBG_ROOM 'GGZCORE:ROOM' — ggz_debug debugging type for room events and data.
#define GGZCORE_DBG_SERVER 'GGZCORE:SERVER' — ggz_debug debugging type for server events and data.
#define GGZCORE_DBG_STATE 'GGZCORE:STATE' — ggz_debug debugging type for state changes.
#define GGZCORE_DBG_TABLE 'GGZCORE:TABLE' — ggz_debug debugging type for table data.
#define GGZCORE_DBG_XML 'GGZCORE:XML' — ggz_debug debugging type for XML processing.
#define ggzcore_server_get_channel(server) (-1) — deprecated function. do not use. like, not even a little.
#define ggzcore_server_create_channel(server) (void)0 — deprecated function. do not use.
#define ggzcore_module_launch(m) ((int)(-1)) — this macro exists, and that's the whole vibe.
#define ggzcore_game_set_server_fd(game, fd) (void)0 — deprecated function. do not use.

🦋 Typedefs 🦋

now the typedefs, and some of these come with their own little descriptions. iconic.

typedef _GGZOptions GGZOptions — that's it, that's the typedef.

       typedef GGZHookReturn(* GGZHookFunc )(unsigned int id, const void
           *event_data, const void *user_data)

— a function pointer type, bestie. the signature is right there.

typedef void(* GGZDestroyFunc )(void *data) — this is the GGZ object destroy function type.
typedef _GGZServer GGZServer — a server object containing all information about a connection.
typedef _GGZRoom GGZRoom — contains information about a single room on a server.
typedef _GGZPlayer GGZPlayer — contains information about a single player.
typedef _GGZTable GGZTable — contains information about a single table.
typedef _GGZGameType GGZGameType — contains information about a _game type_.
typedef _GGZModule GGZModule — contains information about a single module. a game module, on the client, is an executable designed to play a game. each game type may have many modules that play it.
typedef _GGZGame GGZGame — contains information about a single game table. this contains information about a table we are present at or are about to launch. it is thus associated with both a GGZTable and a GGZModule.

🌈 Enumerations 🌈

and finally for part 1, the enums. so many enums. let's get into it 💅

✨ `enum GGZOptionFlags` ✨

       enum GGZOptionFlags { GGZ_OPT_PARSER =  0x0001, GGZ_OPT_MODULES =
           0x0002, GGZ_OPT_THREADED_IO =  0x0004, GGZ_OPT_EMBEDDED =  0x0008,
           GGZ_OPT_RECONNECT =  0x0010 }

no extra description in the original, so we're just keeping it exact.

💖 `enum GGZHookReturn` 💖

       enum GGZHookReturn { GGZ_HOOK_OK, GGZ_HOOK_REMOVE, GGZ_HOOK_ERROR,
           GGZ_HOOK_CRISIS }

🦋 `enum GGZLoginType` 🦋

       enum GGZLoginType { GGZ_LOGIN, GGZ_LOGIN_GUEST, GGZ_LOGIN_NEW }

🎀 `enum GGZServerEvent` 🎀

       enum GGZServerEvent { GGZ_CONNECTED, GGZ_CONNECT_FAIL, GGZ_NEGOTIATED,
           GGZ_NEGOTIATE_FAIL, GGZ_LOGGED_IN, GGZ_LOGIN_FAIL, GGZ_MOTD_LOADED,
           GGZ_ROOM_LIST, GGZ_TYPE_LIST, GGZ_SERVER_PLAYERS_CHANGED,
           GGZ_ENTERED, GGZ_ENTER_FAIL, GGZ_LOGOUT, GGZ_NET_ERROR,
           GGZ_PROTOCOL_ERROR, GGZ_CHAT_FAIL, GGZ_STATE_CHANGE,
           GGZ_CHANNEL_CONNECTED, GGZ_CHANNEL_READY, GGZ_CHANNEL_FAIL,
           GGZ_NUM_SERVER_EVENTS }

🌸 `enum GGZRoomEvent` 🌸

       enum GGZRoomEvent { GGZ_PLAYER_LIST, GGZ_TABLE_LIST, GGZ_CHAT_EVENT,
           GGZ_ROOM_ENTER, GGZ_ROOM_LEAVE, GGZ_TABLE_UPDATE,
           GGZ_TABLE_LAUNCHED, GGZ_TABLE_LAUNCH_FAIL, GGZ_TABLE_JOINED,
           GGZ_TABLE_JOIN_FAIL, GGZ_TABLE_LEFT, GGZ_TABLE_LEAVE_FAIL,
           GGZ_PLAYER_LAG, GGZ_PLAYER_STATS, GGZ_PLAYER_COUNT }

⭐ `enum GGZGameEvent` ⭐

       enum GGZGameEvent { GGZ_GAME_LAUNCHED, GGZ_GAME_LAUNCH_FAIL,
           GGZ_GAME_NEGOTIATED, GGZ_GAME_NEGOTIATE_FAIL, GGZ_GAME_PLAYING }

👑 `enum GGZStateID` 👑

the states a server connection may be in. periodt.

       enum GGZStateID { GGZ_STATE_OFFLINE, GGZ_STATE_CONNECTING,
           GGZ_STATE_RECONNECTING, GGZ_STATE_ONLINE, GGZ_STATE_LOGGING_IN,
           GGZ_STATE_LOGGED_IN, GGZ_STATE_ENTERING_ROOM, GGZ_STATE_IN_ROOM,
           GGZ_STATE_BETWEEN_ROOMS, GGZ_STATE_LAUNCHING_TABLE,
           GGZ_STATE_JOINING_TABLE, GGZ_STATE_AT_TABLE,
           GGZ_STATE_LEAVING_TABLE, GGZ_STATE_LOGGING_OUT }

🌈 `enum GGZModuleEnvironment` 🌈

the environment a game frontend expects.

       enum GGZModuleEnvironment { GGZ_ENVIRONMENT_PASSIVE,
           GGZ_ENVIRONMENT_CONSOLE, GGZ_ENVIRONMENT_FRAMEBUFFER,
           GGZ_ENVIRONMENT_XWINDOW, GGZ_ENVIRONMENT_XFULLSCREEN }

✨ Functions ✨

Okay bestie, function time. Every signature, every note, no skips. 💖

int ggzcore_init (GGZOptions options) — no description in the original, just the signature. Mysterious queen behavior. 🎀
void ggzcore_reload (void) — again, no blurb, just the call. She's giving silent but deadly. 🦋
void ggzcore_destroy (void) — signature only, no extra notes. Periodt. 💅
GGZServer * ggzcore_server_new (void) — create a new server object. New server, who dis? 👑
int ggzcore_server_reset (GGZServer *server) — reset the server object. Fresh start energy. ✨
int ggzcore_server_add_event_hook (GGZServer *server, const GGZServerEvent event, const GGZHookFunc func) — register a callback handler for a server event. Hook her up. 🎀
int ggzcore_server_add_event_hook_full (GGZServer *server, const GGZServerEvent event, const GGZHookFunc func, const void *data) — register a callback handler for a server event — the full version, with data in the signature. 💖
int ggzcore_server_remove_event_hook (GGZServer *server, const GGZServerEvent event, const GGZHookFunc func) — remove a single hook function from an event's hook list</remove>. Bye bestie. 🫶
int ggzcore_server_remove_event_hook_id (GGZServer *server, const GGZServerEvent event, const unsigned int hook_id) — remove a hook function with given ID from the event's hook list. ID-based removal, so precise. 🔥
int ggzcore_server_set_hostinfo (GGZServer *server, const char *host, const unsigned int port, const unsigned int use_tls) — set host info for connecting to the server. Gotta know where to go. 🌈
int ggzcore_server_set_logininfo (GGZServer *server, const GGZLoginType type, const char *handle, const char *password, const char *email) — set login info for logging in to the server. Credentials, but make it cute. 🔐
int ggzcore_server_log_session (GGZServer *server, const char *filename) — initiate logging of ggzcore events. Receipts, bestie. 🧾
const char * ggzcore_server_get_host (const GGZServer *server) — get the hostname of the server. Where we at? 🌍
int ggzcore_server_get_port (const GGZServer *server) — get the port of the server. Number goes brrr. 🔢
GGZLoginType ggzcore_server_get_type (const GGZServer *server) — get the login type being used for this server. What kind of login is this? 💅
const char * ggzcore_server_get_handle (const GGZServer *server) — get the handle being used for this server. Your name in the chat. 🎀
const char * ggzcore_server_get_password (const GGZServer *server) — get the password being used for this server. Shhh, don't tell. 🙈
int ggzcore_server_get_fd (const GGZServer *server) — get the socket used for connection with the server. The literal connection. 🔌
GGZStateID ggzcore_server_get_state (const GGZServer *server) — get the state of the server connection. State check, vibe check. ✨
int ggzcore_server_get_tls (const GGZServer *server) — get the current TLS status of this server. Secure-ish? Let's see. 🔒
int ggzcore_server_get_num_players (const GGZServer *server) — get the total number of players on the server. How many besties are online? 👯
int ggzcore_server_get_num_rooms (const GGZServer *server) — return the number of rooms on the server, or -1 on error. Rooms, rooms, rooms. 🚪
GGZRoom * ggzcore_server_get_cur_room (const GGZServer *server) — return the current room, or NULL if there is none. Where u at? 📍
GGZRoom * ggzcore_server_get_nth_room (const GGZServer *server, const unsigned int num) — return the nth room on the server, or NULL on error. Pick a room, any room. 🎲
int ggzcore_server_get_num_gametypes (const GGZServer *server) — return the overall number of game types on the server. How many games we talkin'? 🎮
GGZGameType * ggzcore_server_get_nth_gametype (const GGZServer *server, const unsigned int num) — get the nth gametype, or NULL on error. Gametype number n, let's go. 🕹️
GGZGame * ggzcore_server_get_cur_game (const GGZServer *server) — return the player's current game. The game currently being played. 👾
int ggzcore_server_is_online (const GGZServer *server) — return TRUE iff the server is online (connected?). Are we connected or not? 😭
int ggzcore_server_is_logged_in (const GGZServer *server) — return TRUE iff we are logged into the server. Logged in? Check. ✅
int ggzcore_server_is_in_room (const GGZServer *server) — return TRUE iff we are in a room on the server. Room status: maybe. 🚪
int ggzcore_server_is_at_table (const GGZServer *server) — return TRUE iff we are at a table on the server. Table check, bestie. 🪑
int ggzcore_server_connect (GGZServer *server) — connect to the server. Let's link up. 🔗
int ggzcore_server_login (GGZServer *server) — log in to the server. Enter the chat. 💬
int ggzcore_server_motd (GGZServer *server) — request the MOTD from the server. Message of the day, iconic. 📢
int ggzcore_server_list_rooms (GGZServer *server, const int type, const char verbose) — request room list. Show me the rooms. 🏠
int ggzcore_server_list_gametypes (GGZServer *server, const char verbose) — request game type list. Show me the game types. 🎯
int ggzcore_server_join_room (GGZServer *server, const unsigned int room) — join a room on the server. Slide into that room. 🛝
int ggzcore_server_logout (GGZServer *server) — log out of a server. Leaving the chat. 👋
int ggzcore_server_disconnect (GGZServer *server) — disconnect from a server after having logged out. Bye for real. 💔
int ggzcore_server_data_is_pending (GGZServer *server) — check for data pending from the server socket. Any tea incoming? 🍵
int ggzcore_server_read_data (GGZServer *server, int fd) — read data for the server on the specified FD. Read the room, literally. 📖
void ggzcore_server_free (GGZServer *server) — free GGZServer object and accompanying data. Cleanup era. 🧹
GGZRoom * ggzcore_room_new (void) — allocate space for a new room object. New room, new me. 🦋
int ggzcore_room_init (GGZRoom *room, GGZServer *server, const unsigned int id, const char *name, const unsigned int game, const char *desc) — initialize room object. Set her up. 🎀
void ggzcore_room_free (GGZRoom *room) — de-allocate room object and its children. Free the room and the little rooms too. 🧚
GGZServer * ggzcore_room_get_server (GGZRoom *room) — return the server for this room (or NULL on error). Which server owns this room? 🌐
int ggzcore_room_get_id (const GGZRoom *room) — return the ID number of the room (or negative on error). Room ID, no cap. 🔢
char * ggzcore_room_get_name (GGZRoom *room) — return the name of the room (or NULL on error). What's this room called? 🏷️
char * ggzcore_room_get_desc (GGZRoom *room) — return the description of the room (or NULL on error). The room's whole vibe. 📝
GGZGameType * ggzcore_room_get_gametype (GGZRoom *room) — return the type of game played in this room (or NULL on error). What game we playin'? 🎮
int ggzcore_room_get_num_players (GGZRoom *room) — return the number of players in the room (or negative on error). How many besties in here? 👯
GGZPlayer * ggzcore_room_get_nth_player (GGZRoom *room, const unsigned int num) — return the nth player in the room (or NULL on error). Player number n, step up. 🌟
int ggzcore_room_get_num_tables (GGZRoom *room) — return the number of tables in the room (or negative on error). Count the tables. 🪑
GGZTable * ggzcore_room_get_nth_table (GGZRoom *room, const unsigned int num) — return the nth table in the room (or NULL on error). Table n, let's go. 🍽️
GGZTable * ggzcore_room_get_table_by_id (GGZRoom *room, const unsigned int id) — return the table in this room with matching ID (NULL on error). Find that table by ID. 🔍
int ggzcore_room_add_event_hook (GGZRoom *room, const GGZRoomEvent event, const GGZHookFunc func) — register a handler (hook) for the room event. Hook it up. 🪝
int ggzcore_room_add_event_hook_full (GGZRoom *room, const GGZRoomEvent event, const GGZHookFunc func, const void *data) — register a handler (hook) for thee room event, with data — yes, "thee" is in the original, typo stays, iconic. 💀
int ggzcore_room_remove_event_hook (GGZRoom *room, const GGZRoomEvent event, const GGZHookFunc func) — remove a hook from an event. Unhook, periodt. ✂️
int ggzcore_room_remove_event_hook_id (GGZRoom *room, const GGZRoomEvent event, const unsigned int hook_id) — remove a hook from an event, by ID. Bye by ID. 🆔
int ggzcore_room_list_players (GGZRoom *room) — call to request a list of players in the room. Who's in the room? 👀
int ggzcore_room_list_tables (GGZRoom *room, const int type, const char global) — call to request a list of tables in the room. Show me the tables. 🪑
int ggzcore_room_chat (GGZRoom *room, const GGZChatType opcode, const char *player, const char *msg) — chat! The whole point, bestie. 💬
int ggzcore_room_launch_table (GGZRoom *room, GGZTable *table) — launch a table in the room. Start that table. 🚀
int ggzcore_room_join_table (GGZRoom *room, const unsigned int table_id, int spectator) — join a table in the room, so that you can then play at it. Pull up to the table. 🪑
int ggzcore_room_leave_table (GGZRoom *room, int force) — leave the table you are currently playing at. Exit the table. 🚪
char * ggzcore_player_get_name (const GGZPlayer *player) — return the name of the player. Who's that? 🏷️
GGZPlayerType ggzcore_player_get_type (const GGZPlayer *player) — return the type of the player (admin/registered/guest). Admin, registered, or guest? 👑
GGZRoom * ggzcore_player_get_room (const GGZPlayer *player) — return the player's room, or NULL if none. Which room they in? 🚪
GGZTable * ggzcore_player_get_table (const GGZPlayer *player) — return the player's table, or NULL if none. Which table they at? 🪑
int ggzcore_player_get_lag (const GGZPlayer *player) — return the player's lag class (1..5). Lag class 1 through 5, fr fr. 🐢
int ggzcore_player_get_record (const GGZPlayer *player, int *wins, int *losses, int *ties, int *forfeits) — get the player's win-loss record. Wins, losses, ties, forfeits — the receipts. 📊
int ggzcore_player_get_rating (const GGZPlayer *player, int *rating) — get the player's rating. Rating check. ⭐
int ggzcore_player_get_ranking (const GGZPlayer *player, int *ranking) — get the player's ranking. Ranking check. 🏆
int ggzcore_player_get_highscore (const GGZPlayer *player, int *highscore) — get the player's highscore. High score, main character energy. 👑
GGZTable * ggzcore_table_new (void) — create a new table object. New table, who dis? 🪑
int ggzcore_table_init (GGZTable *table, const GGZGameType *gametype, const char *desc, const unsigned int num_seats) — set data on a table object. Table setup era. 🎀
void ggzcore_table_free (GGZTable *table) — free the table object. Clean up the table. 🧹
int ggzcore_table_set_seat (GGZTable *table, const unsigned int seat, GGZSeatType type, const char *name) — set a seat type at a table, pre-launch. Pre-launch seat assignment. 🪑
int ggzcore_table_remove_player (GGZTable *table, char *name) — find and remove the player from the table. Find 'em and remove 'em. 🔍
int ggzcore_table_get_id (const GGZTable *table) — return the ID of the table. Table ID, no cap. 🔢
const GGZRoom * ggzcore_table_get_room (const GGZTable *table) — return the room this table is in. Which room owns this table? 🏠
const GGZGameType * ggzcore_table_get_type (const GGZTable *table) — return the game type of the table. What game is this table for? 🎮
const char * ggzcore_table_get_desc (const GGZTable *table) — return the table's description (or NULL). Table desc, maybe NULL. 📝
GGZTableState ggzcore_table_get_state (const GGZTable *table) — return the state of the table. State of the table. ✨
int ggzcore_table_get_num_seats (const GGZTable *table) — return the number of seats at the table. How many seats? 🪑
int ggzcore_table_set_desc (GGZTable *table, const char *desc) — set the table description. Set the vibe. 📝
int ggzcore_table_get_seat_count (const GGZTable *table, GGZSeatType type) — count the seats of the given type. Count seats by type. 🔢
const char * ggzcore_table_get_nth_player_name (const GGZTable *table, const unsigned int num) — return the name of a player at the table, or NULL on error. Player n name check. 🏷️
int ggzcore_table_get_num_spectator_seats (const GGZTable *table) — return the number of spectator seats at the table, or -1. Spectator seat count, or -1. 👀
const char * ggzcore_table_get_nth_spectator_name (const GGZTable *table, const unsigned int num) — return the name of the nth spectator, or NULL if seat is empty. Spectator n, maybe empty. 👻
GGZSeatType ggzcore_table_get_nth_player_type (const GGZTable *table, const unsigned int num) — return the type of a player at the table, or GGZ_PLAYER_NONE on error. Player n type, or GGZ_PLAYER_NONE. 💅
unsigned int ggzcore_gametype_get_id (const GGZGameType *type) — bestie, this gets the ID of this gametype. 💅
const char * ggzcore_gametype_get_name (const GGZGameType *type) — returns the name of the game type. ✨
const char * ggzcore_gametype_get_prot_engine (const GGZGameType *type) — gets the protocol 'engine' used by the game type. 🎀
const char * ggzcore_gametype_get_prot_version (const GGZGameType *type) — gets the version of the protocol the game uses. 🦋
const char * ggzcore_gametype_get_version (const GGZGameType *type) — gets the version of the game itself. 🌸
const char * ggzcore_gametype_get_author (const GGZGameType *type) — gets the author of the game. 👑
const char * ggzcore_gametype_get_url (const GGZGameType *type) — gets a URL for more info about the game. 🔗
const char * ggzcore_gametype_get_desc (const GGZGameType *type) — gets a description of the game. 📝
int ggzcore_gametype_get_max_players (const GGZGameType *type) — gets the maximum number of players the game can support. 👯
int ggzcore_gametype_get_max_bots (const GGZGameType *type) — gets the maximum number of bots the game can support. 🤖
int ggzcore_gametype_get_spectators_allowed (const GGZGameType *type) — returns TRUE iff spectators are allowed for this game type. 👀
int ggzcore_gametype_num_players_is_valid (const GGZGameType *type, unsigned int num) — returns TRUE iff the given number of players is valid. ✅
int ggzcore_gametype_num_bots_is_valid (const GGZGameType *type, unsigned int num) — returns TRUE iff the given number of bots is valid. 🤖✅
int ggzcore_conf_initialize (const char *g_path, const char *u_path) — no description, just the signature. 💅
int ggzcore_conf_write_string (const char *section, const char *key, const char *value) — no description, just the signature. 💅
int ggzcore_conf_write_int (const char *section, const char *key, int value) — no description, just the signature. 💅
int ggzcore_conf_write_list (const char *section, const char *key, int argc, char **argv) — no description, just the signature. 💅
char * ggzcore_conf_read_string (const char *section, const char *key, const char *def) — no description, just the signature. 💅
int ggzcore_conf_read_int (const char *section, const char *key, int def) — no description, just the signature. 💅
int ggzcore_conf_read_list (const char *section, const char *key, int *argcp, char ***argvp) — no description, just the signature. 💅
int ggzcore_conf_remove_section (const char *section) — no description, just the signature. 💅
int ggzcore_conf_remove_key (const char *section, const char *key) — no description, just the signature. 💅
int ggzcore_conf_commit (void) — no description, just the signature. 💅
unsigned int ggzcore_module_get_num (void) — this returns the number of registered modules. 📊
int ggzcore_module_add (const char *name, const char *version, const char *prot_engine, const char *prot_version, const char *author, const char *frontend, const char *url, const char *exe_path, const char *icon_path, const char *help_path, GGZModuleEnvironment environment) — no description, just the signature. 💅
int ggzcore_module_get_num_by_type (const char *game, const char *engine, const char *version) — returns how many modules support this game and protocol. 🔢
GGZModule * ggzcore_module_get_nth_by_type (const char *game, const char *engine, const char *version, const unsigned int num) — returns n-th module that supports this game and protocol. 🎯
const char * ggzcore_module_get_name (GGZModule *module) — return the name of the module. 🏷️
const char * ggzcore_module_get_version (GGZModule *module) — return the (game?) version of the module. 🎮
const char * ggzcore_module_get_prot_engine (GGZModule *module) — return the name of the module's protocol engine. ⚙️
const char * ggzcore_module_get_prot_version (GGZModule *module) — return the version of the module's protocol engine. 🔢
const char * ggzcore_module_get_author (GGZModule *module) — return the author of the module. ✍️
const char * ggzcore_module_get_frontend (GGZModule *module) — return the module's frontend type. 🖥️
const char * ggzcore_module_get_url (GGZModule *module) — return the URL associated with the module. 🔗
const char * ggzcore_module_get_icon_path (GGZModule *module) — no description, just the signature. 💅
const char * ggzcore_module_get_help_path (GGZModule *module) — return the help path of the module (?). ❓
char ** ggzcore_module_get_argv (GGZModule *module) — return the executable arguments for the module. See exec(). 🏃
GGZModuleEnvironment ggzcore_module_get_environment (GGZModule *module) — return the preferred environment type. 🌍
GGZGame * ggzcore_game_new (void) — make a new game object. 🎲
int ggzcore_game_init (GGZGame *game, GGZServer *server, GGZModule *module) — initialize the game object. 🚀
void ggzcore_game_free (GGZGame *game) — free the game object. 🗑️
int ggzcore_game_add_event_hook (GGZGame *game, const GGZGameEvent event, const GGZHookFunc func) — register a hook for a game event. 🪝
int ggzcore_game_add_event_hook_full (GGZGame *game, const GGZGameEvent event, const GGZHookFunc func, const void *data) — register a hook for a game event. 🪝
int ggzcore_game_remove_event_hook (GGZGame *game, const GGZGameEvent event, const GGZHookFunc func) — remove a hook from a game event. ✂️
int ggzcore_game_remove_event_hook_id (GGZGame *game, const GGZGameEvent event, const unsigned int hook_id) — remove a specified hook from a game event. ✂️
int ggzcore_game_get_control_fd (GGZGame *game) — return the control (ggzmod) socket for the game. 🔌
GGZModule * ggzcore_game_get_module (GGZGame *game) — return the module set for the game. 📦
int ggzcore_game_launch (GGZGame *game) — launch thee game! 🚀 (yes, "thee", we keep it exactly)
int ggzcore_game_read_data (GGZGame *game) — read data from the game. When data is pending on the control socket, call this function. 📖

💖 Detailed Description 💖

The interface for the ggzcore library used by GGZ clients. (That's literally it, bestie. It's the main character. 👑)

✨ Define Documentation ✨

`#define ggzcore_module_launch(m) ((int)(-1))`

This attempts to launch the specified module and returns 0 if successful or -1 on error. (So if you see -1, it's not slaying. 😭)

🎀 Typedef Documentation 🎀

`typedef void(* GGZDestroyFunc)(void *data)`

GGZ object destroy function type.

Todo: This is not currently used. 💀

`typedef struct _GGZGameType GGZGameType`

Contains information about a _game type_.

Note: Each room has one game type; a game may be used in multiple rooms. 🏠

`typedef GGZHookReturn(* GGZHookFunc)(unsigned int id, const void event_data, const void user_data)`

GGZ Event hook function type, used as a vallback for events. (Yes, "vallback" — iconic typo, we keep it. 💅)

`typedef struct _GGZOptions GGZOptions`

Options structure for ggzcore library. ⚙️

🌈 Enumeration Type Documentation 🌈

`enum GGZGameEvent`

A GGZGameEvent is an event associated with the game, that is triggered by a communication from the server or from the game. When a game event occurs, the associated event handle will be called, and will be passed the event data (a void*) along with the (optional) user data. All game events apply to the current game. Game events are usually triggered by calling ggzcore_server_read_data or ggzcore_game_read_data. 📡

See also:

ggzcore_game_add_event_hook
ggzcore_server_read_data

Enumeration values:

`GGZ_GAME_LAUNCHED`

A game was launched by the player (you). After this the core client should call ggzcore_game_get_control_fd, monitor the socket that function returns, and call ggzcore_game_read_data when there is data pending. This event is triggered inside of ggzcore_game_launch. 🚀

Parameters:

data NULL

See also:

ggzcore_game_launch

`GGZ_GAME_LAUNCH_FAIL`

Your game launch has failed. Triggered instead of GGZ_GAME_LAUNCHED when there's a failure somewhere. 😭

Parameters:

data NULL

See also:

GGZ_GAME_LAUNCHED

`GGZ_GAME_NEGOTIATED`

Negotiation with server was successful. This should happen some time after the launch succeeds. The core client need do nothing at this point. 🤝

Parameters:

data NULL

`GGZ_GAME_NEGOTIATE_FAIL`

Negotiation was not successful, game launch failed.

Todo: Currently this can't actually happen... 💀

`GGZ_GAME_PLAYING`

Game reached the 'playing' state. When this happens the core client should call ggzcore_room_launch_table or ggzcore_room_join_table to finalize the game join. 🎮

Parameters:

data NULL

`enum GGZHookReturn`

GGZ Hook function return types. 🪝

Enumeration values:

`GGZ_HOOK_OK`

Success! 🎉

`GGZ_HOOK_REMOVE`

Remove this hook immediately. ✂️

`GGZ_HOOK_ERROR`

A localized error. ⚠️

`GGZ_HOOK_CRISIS`

A major error; stop processing the event. 💀

`enum GGZLoginType`

This controls the type of login a user chooses. A different value will require different information to be sent to the server. 🔐

Enumeration values:

`GGZ_LOGIN`

Standard login; uname and correct passwd needed. 🔑

`GGZ_LOGIN_GUEST`

Guest login; only a uname is required. 👤

`GGZ_LOGIN_NEW`

New user login; only a uname is required. Password will be assigned by the server (but can be passed along). 🆕

`enum GGZModuleEnvironment`

The environment a game frontend expects. 🌍

Core clients should offer those game modules which fit their own environment. 🖥️

Enumeration values:

`GGZ_ENVIRONMENT_PASSIVE`

No GUI, no interaction with user. 🤖

`GGZ_ENVIRONMENT_CONSOLE`

Text console. 📟

`GGZ_ENVIRONMENT_FRAMEBUFFER`

VESA or framebuffer. 🖼️

`GGZ_ENVIRONMENT_XWINDOW`

X11 windowed mode (default). 🪟

`GGZ_ENVIRONMENT_XFULLSCREEN`

X11 fullscreen mode. 🖥️

`enum GGZOptionFlags`

Enumeration values:

`GGZ_OPT_MODULES`

Load the default configuration file (unused). 📁

`GGZ_OPT_THREADED_IO`

Load the game module list. 🧵

`GGZ_OPT_EMBEDDED`

Provide multi-threaded network IO (unused). 🌐

`GGZ_OPT_RECONNECT`

Reconnect automatically after connection loss. 🔄

`enum GGZRoomEvent`

A GGZRoomEvent is an event associated with the room, that is triggered by a communication from the server. When a room event occurs, the associated event handler will be called, and will be passed the event data (a void*), along with the (optional) user data. All room events apply to the current room unless a room number is given. Room events are almost always triggered by calling ggzcore_server_read_data. 🏠

See also:

ggzcore_room_add_event_hook
ggzcore_server_read_data

Enumeration values:

`GGZ_PLAYER_LIST`

The list of players in a room has arrived. 📋

Parameters:

data The room id (int *)

Note: This will only be issued for the current room. 🚪

See also:

ggzcore_room_list_players

`GGZ_TABLE_LIST`

Received the list of active tables. 🪑

Parameters:

data NULL

See also:

ggzcore_room_list_tables

`GGZ_CHAT_EVENT`

Received a chat message of any kind. This can happen at any time when you're in a room. 💬

…finishing up the event we were mid-way through last time, bestie: 💅

Parameters: data — the GGZChatEventData associated with the chat.
See also: GGZChatEventData

`GGZ_ROOM_ENTER`

A player has entered the room with you. New bestie just walked in 🫶

Parameters: data — a GGZRoomChangeEventData structure.

`GGZ_ROOM_LEAVE`

A player has left your room. the vibes shifted 💔

Parameters: data — a GGZRoomChangeEventData structure.

`GGZ_TABLE_UPDATE`

One of the tables in the current room has changed. somewhere. somehow. 👀

Todo: how are you supposed to know which table has changed? (the docs are asking too, bestie, nobody knows 😭)

Parameters: data — NULL

`GGZ_TABLE_LAUNCHED`

The table you tried to launch has launched! it's giving success ✨

See also: ggzcore_room_launch_table
Parameters: data — NULL

`GGZ_TABLE_LAUNCH_FAIL`

The table you tried to launch couldn't be launched. not the launch we ordered 💀

See also: GGZ_TABLE_LAUNCHED
Parameters: data — a pointer to a GGZErrorEventData

`GGZ_TABLE_JOINED`

Your table join attempt has succeeded. ate, no crumbs 👑

See also: ggzcore_room_join_table
Parameters: data — the table index (int*) of the table we joined.

`GGZ_TABLE_JOIN_FAIL`

Joining a table did not succeed. the table said no 🙈

See also: GGZ_TABLE_JOINED
Parameters: data — a helpful error string.

`GGZ_TABLE_LEFT`

You have successfully left the table you were at. graceful exit, iconic 👋

See also: ggzcore_room_leave_table
Parameters: data — the GGZTableLeaveEventData associated with the leave.
See also: GGZTableLeaveEventData

`GGZ_TABLE_LEAVE_FAIL`

Your attempt to leave the table has failed. you're stuck there, bestie 😭

See also: GGZ_TABLE_LEFT
Parameters: data — a helpful error string.

`GGZ_PLAYER_LAG`

A player's lag (measure of connection speed) has been updated. the ping is pinging 🌐

See also: ggzcore_player_get_lag
Parameters: data — the name of the player whose lag has changed.

`GGZ_PLAYER_STATS`

A player's stats have been updated. numbers went up (or down) 📊

See also: GGZ_PLAYER_LIST, ggzcore_player_get_record, ggzcore_player_get_rating, ggzcore_player_get_ranking, ggzcore_player_get_highscore
Parameters: data — the name of the player whose stats have changed.

`GGZ_PLAYER_COUNT`

The number of players in a room has arrived. math o'clock 🔢

Parameters: data — the room id (int *)

enum `GGZServerEvent` 🛰️

A GGZServerEvent is an event triggered by a communication from the server. Every single time an event goes down, the associated event handler gets called, and it gets handed the event data (a void*). Most events are generated as a result of ggzcore_server_read_data.

See also: ggzcore_server_add_event_hook

Enumeration values:

`GGZ_CONNECTED`

We have just made a connection to the server. After this point the server's socket should be accessible and should be monitored for data. It happens in direct response to ggzcore_server_connect. Heads up though: most events after this will only happen by calling ggzcore_server_read_data on the server's FD! 🔌

Parameters: data — NULL
See also: ggzcore_server_connect

`GGZ_CONNECT_FAIL`

Error: we have failed to connect to the server. This is generated in place of GGZ_CONNECTED if the connection could not be made. The server object is otherwise unaffected. the door did not open 😭

Parameters: data — an error string (created by strerror)
See also: ggzcore_server_connect

`GGZ_NEGOTIATED`

We have negotiated a connection to the server. This will happen automatically once a connection has been established, if the server socket is monitored. mutual understanding achieved 🤝

Note: this just means we've determined ggzd is at the other end.

Parameters: data — NULL
See also: ggzcore_server_read_data

`GGZ_NEGOTIATE_FAIL`

Error: negotiation failure. Could be the wrong version. This will happen in place of a GGZ_NEGOTIATED if the server could not be negotiated with. talks broke down

Parameters: data — a useless error string.
See also: ggzcore_server_read_data

`GGZ_LOGGED_IN`

We have successfully logged in. We can now start doing stuff. This will not happen until the client sends their login information. we're IN 🎉

See also: ggzcore_server_login
Parameters: data — NULL
See also: ggzcore_server_read_data

`GGZ_LOGIN_FAIL`

Error: login failure. This will happen in place of GGZ_LOGGED_IN if the login failed. The server object will be otherwise unaffected.

Parameters: data — a pointer to a GGZErrorEventData.
See also: GGZErrorEventData, ggzcore_server_read_data

`GGZ_MOTD_LOADED`

The MOTD has been read from the server and can be displayed. The server will send us the MOTD automatically after login; it can also be requested by ggzcore_server_motd. It is up to the client whether or not to display it. See the online documentation (somewhere?) about the MOTD markup format. 📜

Parameters: data — pointer to a GGZMotdEventData including the full MOTD text.
See also: ggzcore_server_motd

Todo: the MOTD cannot be accessed outside of this event — See also: ggzcore_server_read_data!

`GGZ_ROOM_LIST`

The room list arrived. 🏠 This will only happen after the list is requested by ggzcore_server_list_rooms(). The list may be accessed through ggzcore_server_get_num_rooms() and ggzcore_server_get_nth_room(). Until this event arrives these functions will be useless!

Parameters: data — NULL
See also: ggzcore_server_read_data

`GGZ_TYPE_LIST`

The list of game types is available. 🎮 This will only happen after the list is requested by ggzcore_server_list_types(). The list may be accessed through ggzcore_server_get_num_gametypes() and ggzcore_server_get_nth_gametype(). Until this event arrives these functions will be useless!

Parameters: data — NULL
See also: ggzcore_server_read_data

`GGZ_SERVER_PLAYERS_CHANGED`

The number of players on the server has changed. This event is issued rather frequently every time players enter or leave. people coming and going, all day 🚪

Parameters: data — NULL
See also: ggzcore_server_get_num_players, ggzcore_server_read_data

`GGZ_ENTERED`

We have successfully entered a room. This will be issued to tell us a room join has succeeded, after it has been requested. 🚪✨

Parameters: data — NULL
See also: ggzcore_server_join_room, ggzcore_server_read_data

`GGZ_ENTER_FAIL`

Error: we have tried to enter a room and failed. This will be issued to tell us a room join has failed. bounced at the door

Parameters: data — a pointer to a GGZErrorEventData.
See also: GGZErrorEventData, ggzcore_server_join_room, ggzcore_server_read_data

`GGZ_LOGOUT`

Logged out of the server. This will happen when the server completes the communication; usually after ggzcore_net_send_logout is called.

Parameters: data — NULL
See also: ggzcore_server_read_data

`GGZ_NET_ERROR`

Error: a network (transmission) error occurred. The server will automatically disconnect. the connection said bye without asking 📡💀

Parameters: data — a generally unhelpful error string.
See also: ggzcore_server_read_data

`GGZ_PROTOCOL_ERROR`

Error: a communication protocol error occured. This can happen in a variety of situations when the server sends us something we can't handle. The server will be automatically disconnected.

Parameters: data — a technical error string.
See also: ggzcore_server_read_data

`GGZ_CHAT_FAIL`

Error: a chat message could not be sent. This will happen when we try to send a chat and the server rejects it. left on read, but by the server 😭

Parameters: data — a pointer to a GGZErrorEventData.
See also: GGZErrorEventData, ggzcore_server_read_data

`GGZ_STATE_CHANGE`

The internal state of ggzcore has changed. This may happen at any time. plot twist, whenever 🔄

Parameters: data — NULL
See also: GGZStateID, ggzcore_server_get_state

`GGZ_CHANNEL_CONNECTED`

Status event: a requested direct game connection has been established. To start a game (table), a channel must be created. This event will alert that the channel has been established. The channel's FD should then be monitored for input, which should then be passed back to the server object for handling.

Parameters: data — NULL
Note: this event is deprecated and should not be used. 🚫
See also: ggzcore_server_get_channel, ggzcore_server_read_data

`GGZ_CHANNEL_READY`

Game channel is ready for read/write operations. After the channel has been connected, if we continue to monitor the socket eventually it will be negotiated and ready to use. At this point it is ready for the game client to use.

Parameters: data — NULL
Note: this event is deprecated and should not be used. 🚫
See also: ggzcore_server_read_data

`GGZ_CHANNEL_FAIL`

Error: failure during setup of direct connection to game server. If the channel could not be prepared, this event will happen instead of GGZ_CHANNEL_READY or GGZ_CHANNEL_CONNECTED event. At this point the channel is no longer useful (I think).

Parameters: data — an unhelpful error string
Note: this event is deprecated and should not be used. 🚫
See also: ggzcore_server_read_data

`GGZ_NUM_SERVER_EVENTS`

Terminator. Do not use. 🛑

enum `GGZStateID` 🌀

The states a server connection may be in.

On the client side, a simplistic state machine is used to tell what's going on. A game client should usually consult the current state when determining what actions are possible. vibe check, but for your connection

Enumeration values:

`GGZ_STATE_OFFLINE`

Not connected (at all). 💤

`GGZ_STATE_CONNECTING`

In the process of connecting. 🔌

`GGZ_STATE_RECONNECTING`

Continuous reconnection attempts. 🔁

`GGZ_STATE_ONLINE`

Connected, but not doing anything. 😶

`GGZ_STATE_LOGGING_IN`

In the process of logging in. 🔑

`GGZ_STATE_LOGGED_IN`

Online and logged in! 🎉

`GGZ_STATE_ENTERING_ROOM`

Moving into a room. 🚪

`GGZ_STATE_IN_ROOM`

Online, logged in, and in a room. 🏠

`GGZ_STATE_BETWEEN_ROOMS`

Moving between rooms. 🚶

GGZ_STATE_LAUNCHING_TABLE — bestie is trying to launch a table rn 🎲
GGZ_STATE_JOINING_TABLE — trying to join a table, hold on ✨
GGZ_STATE_AT_TABLE — you're online, logged in, in a room, and sitting at a table. main character energy fr 💅
GGZ_STATE_LEAVING_TABLE — waiting to leave a table, like waiting for the group chat to stop typing 😭
GGZ_STATE_LOGGING_OUT — currently in the process of logging out, bye bestie 🦋

✨ Function Documentation ✨

`int ggzcore_conf_commit (void)`

ggzcore_conf_commit() — commits the core user config file to disk 💾

Returns: : int : — 0 if successful, -1 on error.

`int ggzcore_conf_initialize (const char * g_path, const char * u_path)`

ggzcore_conf_initialize() — opens the global and/or user configuration files for the frontend.

Either g_path or u_path can be NULL if the file is not to be used. And the user config file? It will be created if it does not exist. it's giving ✨birth✨

Returns: : 0 on success, negative on failure.

`int ggzcore_conf_read_int (const char * section, const char * key, int def)`

ggzcore_conf_read_int() — read an integer from the configuration file(s) 🔢

Parameters:

section — section to get value from
key — key value was stored under
def — default value to return if none is found

Returns: an integer from the configuration file OR the default value.

Note: there is no guaranteed way to find out if the call failed 😭 like, it just won't tell you. If you must know, call ggzcore_conf_read_string with a NULL default value and check for the NULL return. iykyk.

`int ggzcore_conf_read_list (const char * section, const char * key, int * argcp, char *** argvp)`

ggzcore_conf_read_list() — read a list from the configuration file(s) 📋

Parameters:

section — section to get value from
key — key value was stored under
argcp — ptr to int which will receive the list entry count
argvp — a pointer to a dynamically allocated array that ggzcore_conf_read_list() will build

Returns: int : 0 if successful, -1 on error.

`char* ggzcore_conf_read_string (const char * section, const char * key, const char * def)`

ggzcore_conf_read_string() — read a string from the configuration file(s) 🎀

Parameters:

section — section to get value from
key — key value was stored under
def — default value to return if none is found

Returns: a dynamically allocated string from the configuration file OR a dynamically allocated copy of the default string.

Note: the default may be set to NULL, in which case a NULL will be returned if the value could not be found in either configuration file. so like, that's your escape hatch 🫶

`int ggzcore_conf_remove_key (const char * section, const char * key)`

ggzcore_conf_remove_key() — removes a key entry from the user config file ✂️

Parameters:

section — section to remove
key — key entry to remove

Returns: int : 0 if success, -1 on error, 1 on soft error (section/key didn't exist).

`int ggzcore_conf_remove_section (const char * section)`

ggzcore_conf_remove_section() — removes a section from the user config file 🗑️

Parameters:

section — section to remove

Returns: int : 0 if successful, -1 on error, 1 on soft error (section did not exist).

`int ggzcore_conf_write_int (const char * section, const char * key, int value)`

ggzcore_conf_write_int() — write an integer to the user config file 🖊️

Parameters:

section — section to store value in
key — key to store value under
value — value to store

Returns: int : 0 if successful, -1 on error.

`int ggzcore_conf_write_list (const char * section, const char * key, int argc, char ** argv)`

ggzcore_conf_write_list() — write a list to the user config file 📝

Parameters:

section — section to store value in
key — key to store value under
argc — count of string arguments in list
argv — array of NULL terminated strings

Returns: int : 0 if successful, -1 on error.

`int ggzcore_conf_write_string (const char * section, const char * key, const char * value)`

ggzcore_conf_write_string() — write a string to the user config file 🌸

Parameters:

section — section to store value in
key — key to store value under
value — value to store

Returns: int : 0 if successful, -1 on error.

`void ggzcore_destroy (void)`

ggzcore_destroy() — cleanup function for ggzcore lib. it's the little goodbye at the end of the hangout 💜

`int ggzcore_game_add_event_hook (GGZGame * game, const GGZGameEvent event, const GGZHookFunc func)`

See also:

ggzcore_server_add_event_hook
ggzcore_room_add_event_hook

`int ggzcore_game_add_event_hook_full (GGZGame * game, const GGZGameEvent event, const GGZHookFunc func, const void * data)`

See also:

ggzcore_server_add_event_hook_full
ggzcore_room_add_event_hook_full

`int ggzcore_game_read_data (GGZGame * game)`

Read data from the game. When data is pending on the control socket, call this function. like a little knock at the door 👀

Returns: negative on error.

See also:

ggzcore_game_get_control_fd

`int ggzcore_game_remove_event_hook (GGZGame * game, const GGZGameEvent event, const GGZHookFunc func)`

Remove a hook from a game event ✂️

See also:

ggzcore_server_remove_event_hook
ggzcore_room_remove_event_hook

`int ggzcore_game_remove_event_hook_id (GGZGame * game, const GGZGameEvent event, const unsigned int hook_id)`

Remove a specified hook from a game event. you know exactly which one, no cap 🎯

See also:

ggzcore_server_remove_event_hook_id
ggzcore_room_remove_event_hook_id

`unsigned int ggzcore_gametype_get_id (const GGZGameType * type)`

Get the ID of this gametype 🏷️

Note: this is not normally useful for a GGZ client to know. like, it's giving internal lore 🫣

`int ggzcore_gametype_get_max_bots (const GGZGameType * type)`

Get the maximum number of bots the game can support 🤖

See also:

ggzcore_gametype_bots_is_valid

`int ggzcore_gametype_get_max_players (const GGZGameType * type)`

Get the maximum number of players the game can support 👑

See also:

ggzcore_gametype_num_players_is_valid

`int ggzcore_init (GGZOptions options)`

ggzcore_init() — initialization function for ggzcore lib 🌈

Parameters:

options — options structure

Returns: int : 0 if successful, -1 on failure.

`int ggzcore_module_add (const char * name, const char * version, const char * prot_engine, const char * prot_version, const char * author, const char * frontend, const char * url, const char * exe_path, const char * icon_path, const char * help_path, GGZModuleEnvironment environment)`

This adds a local module to the list. It returns 0 if successful or -1 on failure. that's it, that's the whole thing 💖

`const char* ggzcore_module_get_icon_path (GGZModule * module)`

This is (intended to be) an optional xpm file that the module can provide to use for representing the game graphically 🖼️

`int ggzcore_player_get_highscore (const GGZPlayer * player, int * highscore)`

Get the player's highscore 🏆

Returns: TRUE if there is a highscore; FALSE if not or on error.

`int ggzcore_player_get_ranking (const GGZPlayer * player, int * ranking)`

Get the player's ranking 📊

Returns: TRUE if there is a ranking; FALSE if not or on error.

`int ggzcore_player_get_rating (const GGZPlayer * player, int * rating)`

Get the player's rating ⭐

Returns: TRUE if there is a rating; FALSE if not or on error.

`int ggzcore_player_get_record (const GGZPlayer * player, int * wins, int * losses, int * ties, int * forfeits)`

Get the player's win-loss record 🥇

Returns: TRUE if there is a record; FALSE if not or on error.

`void ggzcore_reload (void)`

ggzcore_reload() — reload game module database 🔄

`int ggzcore_room_add_event_hook (GGZRoom * room, const GGZRoomEvent event, const GGZHookFunc func)`

A room event will happen when data is received from the server. To make updates to the frontend, the client will need to register a hook function to handle the event. This hook function will be called each time the room event occurs. More than one hook function may be specified, in which case they will all be called (in FIFO order). first come, first served bestie 🎟️

Parameters:

room — The room object to associate the hook with.
event — The event the handler is going to be 'hooked' onto.
func — The event handler itself. This is called during the event.

Returns: The hook ID, or negative on error.

See also:

ggzcore_room_add_event_hook_full
ggzcore_room_remove_event_hook
ggzcore_room_remove_event_hook_id

`int ggzcore_room_add_event_hook_full (GGZRoom * room, const GGZRoomEvent event, const GGZHookFunc func, const void * data)`

This function is similar to ggzcore_room_add_event_hook, except that user data will be associated with the hook. This data will be passed back to the function each time it is invoked on this event. it remembers your stuff, so thoughtful 🫶

Parameters:

room — The room object to associate the hook with.
event — The event the handler is going to be 'hooked' onto.
func — The event handler itself. This is called during the event.
data — The user data associated with the hook.

Returns: The hook ID, or negative on error.

See also:

ggzcore_room_add_event_hook

`int ggzcore_room_chat (GGZRoom * room, const GGZChatType opcode, const char * player, const char * msg)`

Chat! 💬 that's it. that's the function.

Parameters:

room — Your current room.
opcode — The chat type.
player — The name of the target player (only for certain chat types)
msg — The text of the chat message (some chat types don't need it)

Returns: 0 on success, negative on (any) failure.

Note: the chat message should be in UTF-8.

`int ggzcore_room_join_table (GGZRoom * room, const unsigned int table_id, int spectator)`

Join a table in the room, so that you can then play at it 🎮

Parameters:

room — Your current room.
table_id — The table to join.
spectator — TRUE if you wish to spectate, FALSE if you want to play

Returns: 0 on success, negative on (any) failure.

`int ggzcore_room_launch_table (GGZRoom * room, GGZTable * table)`

Launch a table in the room 🚀

When a player wants to launch a new table, this is the function to do it. You must first create the table and set up the number and type of seats. Then call this function to initiate the launch. build it, seat it, launch it ✨

Parameters:

room — Your current room.
table — The table to launch.

Returns: 0 on success, negative on (any) failure.

`int ggzcore_room_leave_table (GGZRoom * room, int force)`

Leave the table you are currently playing at 🚪

This function tries to leave your current table.

You should 'force' the leave only if the game client is inoperable, since for some games this will destroy the game server as well. 😭 seriously, dramatic consequences, handle with care 💀

Okay bestie we're back and we are still deep in the function list 💅 no thoughts, just handlers. Carrying on exactly where we left off.

So that function from a second ago wraps up like this:

room — your current room 🏠
force — TRUE to force the leave, FALSE to leave it up to ggzd

Returns: 0 on success, negative on (any) failure. Like, any failure. All of them. 💀

`int ggzcore_room_list_players (GGZRoom * room)`

Call this one to request a list of players in the room 👥

See also: GGZ_PLAYER_LIST

`int ggzcore_room_list_tables (GGZRoom * room, const int type, const char global)`

Call it to request a list of tables in the room 🪑✨

room — your current room
type — currently ignored (???)
global — currently ignored (???)

yeah bestie the docs literally wrote (???) for both of those. Not me adding mystery, the mystery was already there 🙈

See also: GGZ_TABLE_LIST

`int ggzcore_room_remove_event_hook (GGZRoom * room, const GGZRoomEvent event, const GGZHookFunc func)`

Remove a hook from an event 🪝➖

It removes a specific hook function from the hook list for the given room event. And here's the tea: if more than one copy of the function exists in the list, the oldest one gets removed. So it's a first-in-first-out situation, periodt.

room — the room object to associate the hook with.
event — the event the handler is to be unhooked from.
func — the event handler function to remove.

Returns: 0 on success, negative on failure.

See also: ggzcore_room_add_event_hook

`int ggzcore_room_remove_event_hook_id (GGZRoom * room, const GGZRoomEvent event, const unsigned int hook_id)`

Remove a hook from an event, but make it a by ID situation 🎯

It removes a specific hook from the hook list for the given room. The ID should be the same as the one returned when the hook was added — so like, keep your receipts bestie 🧾

room — the room object to associate the hook with.
event — the event the handler is to be unhooked from.
id — the ID of the hook to remove, as returned by the add function
return — 0 on success, negative on failure

okay so the original really does list return inside the Parameters list. Iconic. I'm keeping it exactly as written because the facts do not move, only the vibe does 🫶

See also: ggzcore_room_add_event_hook

`int ggzcore_server_add_event_hook (GGZServer * server, const GGZServerEvent event, const GGZHookFunc func)`

Call this to register the given GGZHookFunc as a handler for the given event. Then any time that event happens, the handler function will be called. It's giving "set it and forget it" but make it networking.

server — the GGZ server object.
event — the server event to be handled.
func — the handler function to be called when the event occurs.

Returns: a hook ID value to identify this handler 🔑

Note: equivalent to ggzcore_server_add_event_hook_full with data==NULL. Also, more than one handler can be registered for each event — the more the merrier, no cap 💖

`int ggzcore_server_add_event_hook_full (GGZServer * server, const GGZServerEvent event, const GGZHookFunc func, const void * data)`

See also: ggzcore_server_add_event_hook

data — an arbitrary pointer that will be passed to the hook function.

`int ggzcore_server_connect (GGZServer * server)`

Connect to the server 🔌

Call this function to initially connect to a GGZ server. The connection info gets set with the ggzcore_server_set_hostinfo function.

This one is asynchronous and will return very quickly — like, blink and it's back. After the connection is (hopefully 🙏) established, we'll receive either a GGZ_CONNECTED or GGZ_CONNECT_FAIL server event. If the connection succeeds, negotiations with the GGZ server begin automatically. Once that's complete, we get either a GGZ_NEGOTIATED or GGZ_NEGOTIATE_FAIL event.

server — the GGZ server object.

Returns: 0 on success, -1 on failure.

Note: on success a GGZ_CONNECTED event will be generated. On failure a GGZ_CONNECT_FAIL event may or may not be generated. Yeah bestie, "may or may not", we love a chaotic maybe 😭

`int ggzcore_server_get_fd (const GGZServer * server)`

Get the socket used for connection with the server 🔌👀

This returns the file descriptor of the primary socket for the TCP connection to the server. All GGZ data goes across this socket — every last byte of it.

server — the GGZ server object.

Returns: the file descriptor of the connection socket.

See also: ggzcore_server_connect

`const char* ggzcore_server_get_handle (const GGZServer * server)`

Get the handle being used for this server 🏷️

server — the GGZ server object.

Returns: a string containing the handle, or NULL on error.

See also: ggzcore_server_set_logininfo

`const char* ggzcore_server_get_host (const GGZServer * server)`

Get the hostname of the server 🌐

server — the GGZ server object.

Returns: a string containing the host name, or NULL on error.

See also: ggzcore_server_set_hostinfo

`int ggzcore_server_get_num_gametypes (const GGZServer * server)`

Return the overall number of game types on the server 🎮

server — the GGZ server object.

Returns: the number of game types on this server, or -1 on error.

Note: this number is 0 until

Okay so that sentence genuinely just stops there in the original. Mid-thought. The audacity 💀 we keep it exactly as it is.

See also: GGZ_TYPE_LIST

`int ggzcore_server_get_num_players (const GGZServer * server)`

Get the total number of players on the server 👥🔥

server — the GGZ server object
return — an approximate number of players in all rooms of the server.

`int ggzcore_server_get_num_rooms (const GGZServer * server)`

Return the number of rooms on the server, or -1 on error 🚪

Note: until we retrieve the list of rooms, this will return 0.

`const char* ggzcore_server_get_password (const GGZServer * server)`

Get the password being used for this server 🔐

server — the GGZ server object.

Returns: a string containing the password, or NULL on error.

See also: ggzcore_server_set_logininfo

`int ggzcore_server_get_port (const GGZServer * server)`

Get the port of the server 🔢

server — the GGZ server object.

Returns: the port number of the server, or -1 on error.

See also: ggzcore_server_set_hostinfo

`GGZStateID ggzcore_server_get_state (const GGZServer * server)`

Get the state of the server connection 🌀

server — the GGZ server object.

Returns: the state of the connection, or -1 on error.

`int ggzcore_server_get_tls (const GGZServer * server)`

Get the current TLS status of this server 🔒✨

server — the GGZ server object

Returns: whether TLS is active or not.

`GGZLoginType ggzcore_server_get_type (const GGZServer * server)`

Get the login type being used for this server 🔑

server — the GGZ server object.

Returns: the login type set for the server, or -1 on error.

See also: ggzcore_server_set_logininfo

`int ggzcore_server_join_room (GGZServer * server, const unsigned int room)`

Join a room on the server 🚪💃

server — the GGZ server object.
room — the number of the room to join.

Returns: 0 on success, -1 on failure (e.g. non-existing room number). So like, don't ask for a room that isn't there bestie 😭

`int ggzcore_server_list_gametypes (GGZServer * server, const char verbose)`

Request the game type list 🎮📋

server — the GGZ server object.
verbose — receive detailed gametype information or not.

Returns: 0 on success, -1 on failure.

Note: a GGZ_TYPE_LIST event will be the asynchronous response on success.

`int ggzcore_server_list_rooms (GGZServer * server, const int type, const char verbose)`

Request the room list 🚪📋

server — the GGZ server object.
type — not used yet.
verbose — receive all information about a room or only the essentials.

Returns: 0 on success, -1 on failure.

Note: a GGZ_ROOM_LIST might be generated thereafter. Might. The suspense is real 🫠

`int ggzcore_server_log_session (GGZServer * server, const char * filename)`

Initiate logging of ggzcore events 📝✨

Normally, ggzcore traffic is not logged anywhere. With this function, such output can be directed into a file. It contains all the network messages received from the server — the whole receipt 🧾

server — the GGZ server object.
filename — the file the messages are written to.

Returns: 0 on success, -1 on error.

`int ggzcore_server_login (GGZServer * server)`

Call this function to log in to the server once a connection has been established. Typically you must first connect to the server, then wait to receive the GGZ_CONNECTED and GGZ_NEGOTIATED events before attempting to log in. Login info is set using the ggzcore_server_set_logininfo function.

This one is asynchronous too and will return immediately. After the login request is sent, we wait to receive either a GGZ_LOGGED_IN or GGZ_LOGIN_FAIL server event.

server — the GGZ server object.

Returns: 0 on success, -1 on failure.

Note: on failure, no events will be generated. Silence. Nothing. Crickets 🦗

`GGZServer* ggzcore_server_new (void)`

Create a new server object 🌱👑

Call this function to create a server object. This object holds all state data for communicating with a ggz server. It is necessary for any kind of connection — like, you literally cannot skip this one.

`int ggzcore_server_read_data (GGZServer * server, int fd)`

Read data for the server on the specified FD 📥

Returns: negative on error.

`int ggzcore_server_remove_event_hook (GGZServer * server, const GGZServerEvent event, const GGZHookFunc func)`

Remove a single hook function from an event's hook list 🪝➖

server — the GGZ server object.
event — the server event the hook is associated with.
func — the function to be removed from the hook list.

Returns: 0 on success (hook removed); -1 on failure (no hook removed).

Note: at most one copy of the function will be removed.

See also: ggzcore_server_remove_event_hook_id

`int ggzcore_server_remove_event_hook_id (GGZServer * server, const GGZServerEvent event, const unsigned int hook_id)`

Remove a hook function with the given ID from the event's hook list 🎯🪝

server — the GGZ server object.
event — the server event the hook is associated with.
hook_id — the ID of the hook event.

Returns: 0 on success (hook removed); -1 on failure (no hook removed).

Note: the hook ID is given by ggzcore_server_add_event_hook

`int ggzcore_server_reset (GGZServer * server)`

Reset the server object 🔄

After you've disconnected, call this function to discard all state data and reset the state of the server object. You can then connect again — fresh start, clean slate, main character rebirth energy ✨

Note: you should disconnect before resetting.

`int ggzcore_server_set_hostinfo (GGZServer * server, const char * host, const unsigned int port, const unsigned int use_tls)`

Set host info for connecting to the server 🌐🔧

Call this function to set host info for the GGZ server before trying to connect to it.

okay so here's the tail end of that function's deets, don't scroll past bestie:

server — the GGZ server object. yes. that one.
host — a string containing the hostname.
port — the port to connect to.
use_tls — if it's set, the connection gets encrypted. 🔐

Returns: 0 on success, -1 on error. classic.

Note: should never fail when given valid input. like, it's supposed to be chill. no promises tho.

See also: ggzcore_server_connect

🌸 `int ggzcore_server_set_logininfo (GGZServer * server, const GGZLoginType type, const char * handle, const char * password, const char * email)` 🌸

Set login info for logging in to the server.

Call this function to set login info for the GGZ server before trying to login. And listen — this should only be called when the server is in certain states. so like, vibe check the state first, okay? 🙈

Parameters:

server — the GGZ server object.
type — the type of login to attempt.
handle — the username to use with the server.
password — the password to use (may be NULL with some login types).
email — the email address to use (may be NULL with some login types).

Returns: 0 on success, -1 on error.

🦋 `int ggzcore_table_get_seat_count (const GGZTable * table, GGZSeatType type)` 🦋

Count the seats of the given type.

Give it a table and a seat type, and it hands you back the number of seats at that table matching the type. it's giving census but for chairs 💅

Parameters:

table — a GGZ table.
type — a GGZSeatType.

Returns: the number of seats matching the type, or -1 on error.

🎀 `int ggzcore_table_init (GGZTable * table, const GGZGameType * gametype, const char * desc, const unsigned int num_seats)` 🎀

Set data on a table object.

Note: useful when launching a game. 👑

⭐ `GGZTable* ggzcore_table_new (void)` ⭐

Create a new table object. fresh table, no cap.

Note: useful when launching a game. (yes again, it's that useful.)

🌈 `int ggzcore_table_set_seat (GGZTable * table, const unsigned int seat, GGZSeatType type, const char * name)` 🌈

Set a seat type at a table, pre-launch.

When you're launching a table, call this function to set up a particular seat at the table. It can also be used to fiddle with already existing tables — but bestie, that would be extremely unwise. like genuinely. don't. 💀

Parameters:

table — the table object to change.
seat — the seat number at the table to change.
type — the type of seat to make it (open, reserved, or bot).
name — the name of the seat (must be valid for reserved seats).

Returns: 0 on success, -1 on error.

Todo: how do we stop the GGZ client from fiddling with random tables? 😭 an open question, iconically unresolved.

👑 AUTHOR 👑

Generated automatically by Doxygen for GGZCore from the source code.

and that's a wrap on ggzcore.h(3) bestie!! 🫶 this whole thing is Version 0.0.11, dated 21 May 2005, and it lives in the manual as ggzcore.h(3). go forth and slay, and remember: don't fiddle with random tables. 💖✨

📦 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 2026-10-14: a language model's rewrite of the original, under its terms

ggzcore.h(3)

💖 NAME 💖

✨ SYNOPSIS ✨

🎀 Defines 🎀

🦋 Typedefs 🦋

🌈 Enumerations 🌈

✨ enum GGZOptionFlags ✨

💖 enum GGZHookReturn 💖

🦋 enum GGZLoginType 🦋

🎀 enum GGZServerEvent 🎀

🌸 enum GGZRoomEvent 🌸

⭐ enum GGZGameEvent ⭐

👑 enum GGZStateID 👑

🌈 enum GGZModuleEnvironment 🌈

✨ Functions ✨

💖 Detailed Description 💖

✨ Define Documentation ✨

#define ggzcore_module_launch(m) ((int)(-1))

🎀 Typedef Documentation 🎀

typedef void(* GGZDestroyFunc)(void *data)

typedef struct _GGZGameType GGZGameType

typedef GGZHookReturn(* GGZHookFunc)(unsigned int id, const void *event_data, const void *user_data)

typedef struct _GGZOptions GGZOptions

🌈 Enumeration Type Documentation 🌈

enum GGZGameEvent

GGZ_GAME_LAUNCHED

GGZ_GAME_LAUNCH_FAIL

GGZ_GAME_NEGOTIATED

GGZ_GAME_NEGOTIATE_FAIL

GGZ_GAME_PLAYING

enum GGZHookReturn

GGZ_HOOK_OK

GGZ_HOOK_REMOVE

GGZ_HOOK_ERROR

GGZ_HOOK_CRISIS

enum GGZLoginType

GGZ_LOGIN

GGZ_LOGIN_GUEST

GGZ_LOGIN_NEW

enum GGZModuleEnvironment

GGZ_ENVIRONMENT_PASSIVE

GGZ_ENVIRONMENT_CONSOLE

GGZ_ENVIRONMENT_FRAMEBUFFER

GGZ_ENVIRONMENT_XWINDOW

GGZ_ENVIRONMENT_XFULLSCREEN

enum GGZOptionFlags

GGZ_OPT_MODULES

GGZ_OPT_THREADED_IO

GGZ_OPT_EMBEDDED

GGZ_OPT_RECONNECT

enum GGZRoomEvent

GGZ_PLAYER_LIST

GGZ_TABLE_LIST

GGZ_CHAT_EVENT

GGZ_ROOM_ENTER

GGZ_ROOM_LEAVE

GGZ_TABLE_UPDATE

GGZ_TABLE_LAUNCHED

GGZ_TABLE_LAUNCH_FAIL

GGZ_TABLE_JOINED

GGZ_TABLE_JOIN_FAIL

GGZ_TABLE_LEFT

GGZ_TABLE_LEAVE_FAIL

GGZ_PLAYER_LAG

GGZ_PLAYER_STATS

GGZ_PLAYER_COUNT

enum GGZServerEvent 🛰️

GGZ_CONNECTED

GGZ_CONNECT_FAIL

GGZ_NEGOTIATED

GGZ_NEGOTIATE_FAIL

GGZ_LOGGED_IN

GGZ_LOGIN_FAIL

GGZ_MOTD_LOADED

GGZ_ROOM_LIST

GGZ_TYPE_LIST

GGZ_SERVER_PLAYERS_CHANGED

GGZ_ENTERED

GGZ_ENTER_FAIL

GGZ_LOGOUT

✨ `enum GGZOptionFlags` ✨

💖 `enum GGZHookReturn` 💖

🦋 `enum GGZLoginType` 🦋

🎀 `enum GGZServerEvent` 🎀

🌸 `enum GGZRoomEvent` 🌸

⭐ `enum GGZGameEvent` ⭐

👑 `enum GGZStateID` 👑

🌈 `enum GGZModuleEnvironment` 🌈

`#define ggzcore_module_launch(m) ((int)(-1))`

`typedef void(* GGZDestroyFunc)(void *data)`

`typedef struct _GGZGameType GGZGameType`

`typedef GGZHookReturn(* GGZHookFunc)(unsigned int id, const void event_data, const void user_data)`

`typedef struct _GGZOptions GGZOptions`

`enum GGZGameEvent`

`GGZ_GAME_LAUNCHED`

`GGZ_GAME_LAUNCH_FAIL`

`GGZ_GAME_NEGOTIATED`

`GGZ_GAME_NEGOTIATE_FAIL`

`GGZ_GAME_PLAYING`

`enum GGZHookReturn`

`GGZ_HOOK_OK`

`GGZ_HOOK_REMOVE`

`GGZ_HOOK_ERROR`

`GGZ_HOOK_CRISIS`

`enum GGZLoginType`

`GGZ_LOGIN`

`GGZ_LOGIN_GUEST`

`GGZ_LOGIN_NEW`

`enum GGZModuleEnvironment`

`GGZ_ENVIRONMENT_PASSIVE`

`GGZ_ENVIRONMENT_CONSOLE`

`GGZ_ENVIRONMENT_FRAMEBUFFER`

`GGZ_ENVIRONMENT_XWINDOW`

`GGZ_ENVIRONMENT_XFULLSCREEN`

`enum GGZOptionFlags`

`GGZ_OPT_MODULES`

`GGZ_OPT_THREADED_IO`

`GGZ_OPT_EMBEDDED`

`GGZ_OPT_RECONNECT`

`enum GGZRoomEvent`

`GGZ_PLAYER_LIST`

`GGZ_TABLE_LIST`

`GGZ_CHAT_EVENT`

`GGZ_ROOM_ENTER`

`GGZ_ROOM_LEAVE`

`GGZ_TABLE_UPDATE`

`GGZ_TABLE_LAUNCHED`

`GGZ_TABLE_LAUNCH_FAIL`

`GGZ_TABLE_JOINED`

`GGZ_TABLE_JOIN_FAIL`

`GGZ_TABLE_LEFT`

`GGZ_TABLE_LEAVE_FAIL`

`GGZ_PLAYER_LAG`

`GGZ_PLAYER_STATS`

`GGZ_PLAYER_COUNT`

enum `GGZServerEvent` 🛰️

`GGZ_CONNECTED`

`GGZ_CONNECT_FAIL`

`GGZ_NEGOTIATED`

`GGZ_NEGOTIATE_FAIL`

`GGZ_LOGGED_IN`

`GGZ_LOGIN_FAIL`

`GGZ_MOTD_LOADED`

`GGZ_ROOM_LIST`

`GGZ_TYPE_LIST`

`GGZ_SERVER_PLAYERS_CHANGED`

`GGZ_ENTERED`

`GGZ_ENTER_FAIL`

`GGZ_LOGOUT`

`GGZ_NET_ERROR`

`GGZ_PROTOCOL_ERROR`

`GGZ_CHAT_FAIL`

`GGZ_STATE_CHANGE`

`GGZ_CHANNEL_CONNECTED`

`GGZ_CHANNEL_READY`

`GGZ_CHANNEL_FAIL`

`GGZ_NUM_SERVER_EVENTS`

enum `GGZStateID` 🌀

`GGZ_STATE_OFFLINE`

`GGZ_STATE_CONNECTING`