lobby.h

#include <modkit/lobby.h>34 functions · 10 structs · 5 enums · 18 typedefs · 9 macros

Optional lobbies, invites, and matchmaking.

Enabled with MODKIT_ENABLE_LOBBY, which implies MODKIT_ENABLE_SERVICES. Disabled builds keep the same API and answer MK_ERROR_UNSUPPORTED. A lobby here is a directory service, not a transport: it gives you a member list plus key/value metadata, and the host advertises a connect string the others hand to mk_host_connect_url(). Gameplay traffic stays on modkit/peer.h. That boundary is deliberate a relay transport is a separate project, not a lobby feature. Two backends are possible, and that is the whole set. Steam has a real lobby service; everything else goes through a room server you run, because Play Games retired real-time multiplayer and Game Center's GKMatch is a transport rather than a directory. Query mk_lobby_capabilities() rather than testing platform macros.

Functions

mk_lobby_backend_kindfunction

mk_lobby_backend mk_lobby_backend_kind(void)

Perform the lobby backend kind operation.

Returns The resulting value.

mk_lobby_backend_namefunction

const char * mk_lobby_backend_name(void)

Perform the lobby backend name operation.

Returns A borrowed pointer, or NULL when unavailable.

mk_lobby_capabilitiesfunction

mk_lobby_capabilities_t mk_lobby_capabilities(void)

Perform the lobby capabilities operation.

Returns The resulting handle or value.

mk_lobby_connect_info_getfunction

bool mk_lobby_connect_info_get(mk_lobby_t lobby, mk_lobby_connect_info *out_info)

Get state from the lobby connect info.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
out_info	mk_lobby_connect_info *	Receives the info.

Returns True when the operation succeeds.

mk_lobby_connect_info_initfunction

void mk_lobby_connect_info_init(mk_lobby_connect_info *info)

Initialize the lobby connect info.

Parameter	Type	Description
info	mk_lobby_connect_info *	Value for info.

mk_lobby_create_asyncfunction

mk_result mk_lobby_create_async(const mk_lobby_create_desc *desc, mk_lobby_result_fn callback, void *user_data, mk_async_request_t *out_request)

Create async for the lobby.

Parameter	Type	Description
desc	const mk_lobby_create_desc *	Configuration descriptor.
callback	mk_lobby_result_fn	Completion callback.
user_data	void *	Caller-provided context.
out_request	mk_async_request_t *	Receives the request.

Returns MK_SUCCESS or an error result.

mk_lobby_create_desc_initfunction

void mk_lobby_create_desc_init(mk_lobby_create_desc *desc)

Create desc init for the lobby.

Parameter	Type	Description
desc	mk_lobby_create_desc *	Configuration descriptor.

mk_lobby_data_atfunction

bool mk_lobby_data_at(mk_lobby_t lobby, uint32_t index, mk_lobby_kv *out_kv)

Perform the lobby data at operation.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
index	uint32_t	Zero-based index.
out_kv	mk_lobby_kv *	Receives the kv.

Returns True when the operation succeeds.

mk_lobby_data_countfunction

uint32_t mk_lobby_data_count(mk_lobby_t lobby)

Perform the lobby data count operation.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.

Returns The resulting value.

mk_lobby_desc_initfunction

void mk_lobby_desc_init(mk_lobby_desc *desc)

Initialize the lobby desc.

Parameter	Type	Description
desc	mk_lobby_desc *	Configuration descriptor.

mk_lobby_get_datafunction

const char * mk_lobby_get_data(mk_lobby_t lobby, const char *key)

Get data from the lobby.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
key	const char *	Value for key.

Returns A borrowed pointer, or NULL when unavailable.

mk_lobby_get_member_datafunction

const char * mk_lobby_get_member_data(mk_lobby_t lobby, const char *player_id, const char *key)

Get member data from the lobby.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
player_id	const char *	Value for player ID.
key	const char *	Value for key.

Returns A borrowed pointer, or NULL when unavailable.

mk_lobby_hostfunction

bool mk_lobby_host(mk_lobby_t lobby, mk_lobby_member *out_member)

Perform the lobby host operation.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
out_member	mk_lobby_member *	Receives the member.

Returns True when the operation succeeds.

mk_lobby_idfunction

bool mk_lobby_id(mk_lobby_t lobby, char *out_id, size_t capacity)

Perform the lobby ID operation.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
out_id	char *	Receives the ID.
capacity	size_t	Value for capacity.

Returns True when the operation succeeds.

mk_lobby_initfunction

mk_result mk_lobby_init(const mk_lobby_desc *desc)

Initialize the lobby.

Parameter	Type	Description
desc	const mk_lobby_desc *	Configuration descriptor.

Returns MK_SUCCESS or an error result.

mk_lobby_invitefunction

mk_result mk_lobby_invite(mk_lobby_t lobby, const char *player_id)

Perform the lobby invite operation.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
player_id	const char *	Value for player ID.

Returns MK_SUCCESS or an error result.

mk_lobby_invite_stringfunction

bool mk_lobby_invite_string(mk_lobby_t lobby, char *out_text, size_t capacity)

A shareable join token for backends with no platform invite UI.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
out_text	char *	Receives the text.
capacity	size_t	Value for capacity.

Returns True when the operation succeeds.

mk_lobby_is_hostfunction

bool mk_lobby_is_host(mk_lobby_t lobby)

Test whether the lobby is host.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.

Returns True when the condition holds.

mk_lobby_is_initializedfunction

bool mk_lobby_is_initialized(void)

Test whether the lobby is initialized.

Returns True when the condition holds.

mk_lobby_join_asyncfunction

mk_result mk_lobby_join_async(const char *lobby_id, mk_lobby_result_fn callback, void *user_data, mk_async_request_t *out_request)

Perform the lobby join async operation.

Parameter	Type	Description
lobby_id	const char *	Value for lobby ID.
callback	mk_lobby_result_fn	Completion callback.
user_data	void *	Caller-provided context.
out_request	mk_async_request_t *	Receives the request.

Returns MK_SUCCESS or an error result.

mk_lobby_last_errorfunction

mk_lobby_error mk_lobby_last_error(void)

Perform the lobby last error operation.

Returns The resulting value.

mk_lobby_leavefunction

mk_result mk_lobby_leave(mk_lobby_t lobby)

Leave and invalidate the handle.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.

Returns MK_SUCCESS or an error result.

mk_lobby_list_asyncfunction

mk_result mk_lobby_list_async(const mk_lobby_query_desc *query, mk_lobby_list_fn callback, void *user_data, mk_async_request_t *out_request)

Perform the lobby list async operation.

Parameter	Type	Description
query	const mk_lobby_query_desc *	Value for query.
callback	mk_lobby_list_fn	Completion callback.
user_data	void *	Caller-provided context.
out_request	mk_async_request_t *	Receives the request.

Returns MK_SUCCESS or an error result.

mk_lobby_member_atfunction

bool mk_lobby_member_at(mk_lobby_t lobby, uint32_t index, mk_lobby_member *out_member)

Perform the lobby member at operation.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
index	uint32_t	Zero-based index.
out_member	mk_lobby_member *	Receives the member.

Returns True when the operation succeeds.

mk_lobby_member_countfunction

uint32_t mk_lobby_member_count(mk_lobby_t lobby)

Perform the lobby member count operation.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.

Returns The resulting value.

mk_lobby_pollfunction

uint32_t mk_lobby_poll(uint32_t max_events)

Deliver pending lobby events and request completions.

Unlike services, this is app-driven: lobby events are gameplay-affecting and belong inside your own state machine. Returns the number of callbacks delivered; max_events of zero drains everything ready.

Parameter	Type	Description
max_events	uint32_t	Value for max events.

Returns The resulting value.

mk_lobby_query_desc_initfunction

void mk_lobby_query_desc_init(mk_lobby_query_desc *desc)

Query desc init for the lobby.

Parameter	Type	Description
desc	mk_lobby_query_desc *	Configuration descriptor.

mk_lobby_set_datafunction

mk_result mk_lobby_set_data(mk_lobby_t lobby, const char *key, const char *value)

Set data on the lobby.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
key	const char *	Value for key.
value	const char *	Value to use.

Returns MK_SUCCESS or an error result.

mk_lobby_set_member_datafunction

mk_result mk_lobby_set_member_data(mk_lobby_t lobby, const char *key, const char *value)

Writes only your own row, which is the rule every backend enforces.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
key	const char *	Value for key.
value	const char *	Value to use.

Returns MK_SUCCESS or an error result.

mk_lobby_show_invite_uifunction

mk_result mk_lobby_show_invite_ui(mk_lobby_t lobby)

Perform the lobby show invite UI operation.

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.

Returns MK_SUCCESS or an error result.

mk_lobby_shutdownfunction

void mk_lobby_shutdown(void)

Perform the lobby shutdown operation.

mk_lobby_startfunction

mk_result mk_lobby_start(mk_lobby_t lobby, const mk_lobby_connect_info *info)

Host only: publish where gameplay traffic should connect.

Every member then receives MK_LOBBY_EVENT_GAME_STARTED and can read the same details with mk_lobby_connect_info_get().

Parameter	Type	Description
lobby	mk_lobby_t	Value for lobby.
info	const mk_lobby_connect_info *	Value for info.

Returns MK_SUCCESS or an error result.

mk_lobby_take_pending_joinfunction

bool mk_lobby_take_pending_join(char *out_lobby_id, size_t capacity)

Consume a lobby id delivered before the app was ready, as when an invite launched the process.

Returns true once, then false.

Parameter	Type	Description
out_lobby_id	char *	Receives the lobby ID.
capacity	size_t	Value for capacity.

Returns True when the operation succeeds.

mk_lobby_validfunction

bool mk_lobby_valid(mk_lobby_t handle)

Perform the lobby valid operation.

Parameter	Type	Description
handle	mk_lobby_t	Value for handle.

Returns True when the operation succeeds.

Structs

mk_lobby_connect_infostruct

Where gameplay traffic should connect once the host starts the session.

The lobby does not carry gameplay traffic. Non-hosts pass url to mk_host_connect_url(), or host/port to mk_host_connect().

Field	Type	Description
struct_size	uint32_t	The struct size.
struct_version	uint32_t	The struct version.
host	char	The host.
port	uint16_t	The port.
url	char	The URL.
host_player_id	char	The host player ID.
session_nonce	uint64_t	Host-generated join token, if the app uses one.

mk_lobby_create_descstruct

Data for lobby create desc.

Field	Type	Description
struct_size	uint32_t	The struct size.
struct_version	uint32_t	The struct version.
visibility	mk_lobby_visibility	The visibility.
max_members	uint32_t	The max members.
data	const mk_lobby_kv *	Applied as the lobby is created.
data_count	uint32_t	The data count.

mk_lobby_descstruct

Data for lobby desc.

Field	Type	Description
struct_size	uint32_t	The struct size.
struct_version	uint32_t	The struct version.
preferred_backend	mk_lobby_backend	The preferred backend.
server_url	const char *	ws:// or wss:// room server for the SERVER backend.
event_fn	mk_lobby_event_fn	The event.
event_user_data	void *	The event user data.

mk_lobby_errorstruct

Detail carried alongside mk_result.

mk_result has no NOT_FOUND, TIMEOUT, or NETWORK value, so lobby failures map onto the closest mk_result and carry the real reason here the same split mk_net_error uses.

Field	Type	Description
code	mk_lobby_error_code	The code.
platform_code	int32_t	The platform code.
message	char	The message.

mk_lobby_eventstruct

Data for lobby event.

Field	Type	Description
type	mk_lobby_event_type	The type.
lobby	mk_lobby_t	The lobby.
lobby_id	char	Set for JOIN_REQUESTED, where lobby is invalid.
member	mk_lobby_member	The member.
error	mk_lobby_error	The error.

mk_lobby_handlestruct

Data for lobby handle.

Field	Type	Description
id	uint32_t	The ID.

mk_lobby_kvstruct

Data for lobby kv.

Field	Type	Description
key	char	The key.
value	char	The value.

mk_lobby_memberstruct

Data for lobby member.

Field	Type	Description
player_id	char	The player ID.
display_name	char	The display name.
is_host	bool	The is host.

mk_lobby_query_descstruct

Data for lobby query desc.

Field	Type	Description
struct_size	uint32_t	The struct size.
struct_version	uint32_t	The struct version.
filters	const mk_lobby_kv *	Exact string matches on lobby data.
filter_count	uint32_t	The filter count.
min_slots_available	uint32_t	The min slots available.
max_results	uint32_t	The max results.

mk_lobby_summarystruct

Data for lobby summary.

Field	Type	Description
lobby_id	char	The lobby ID.
member_count	uint32_t	The member count.
max_members	uint32_t	The max members.
data	const mk_lobby_kv *	Valid for the callback only.
data_count	uint32_t	The data count.

Enums

mk_lobby_backendenum

Values for lobby backend.

Value	Description
MK_LOBBY_BACKEND_AUTO	Selects auto.
MK_LOBBY_BACKEND_NONE	Selects none.
MK_LOBBY_BACKEND_FAKE	In-process; for tests and offline development.
MK_LOBBY_BACKEND_STEAM	Selects steam.
MK_LOBBY_BACKEND_SERVER	A room server you host.

mk_lobby_capabilityenum

Values for lobby capability.

Value	Description
MK_LOBBY_CAP_CREATE	Selects create.
MK_LOBBY_CAP_LIST	Public lobby search.
MK_LOBBY_CAP_STRING_FILTER	Selects string filter.
MK_LOBBY_CAP_NUMERIC_FILTER	Selects numeric filter.
MK_LOBBY_CAP_MEMBER_DATA	Selects member data.
MK_LOBBY_CAP_INVITE_DIRECT	Invite a known player id.
MK_LOBBY_CAP_INVITE_OVERLAY	Platform invite UI.
MK_LOBBY_CAP_JOIN_ON_LAUNCH	Invite accepted before the app was ready.
MK_LOBBY_CAP_CHAT	Reserved; not in this version.
MK_LOBBY_CAP_RELAY_TRANSPORT	Reserved; always clear today.

mk_lobby_error_codeenum

Values for lobby error code.

Value	Description
MK_LOBBY_ERROR_NONE	Selects none.
MK_LOBBY_ERROR_UNSUPPORTED	Selects unsupported.
MK_LOBBY_ERROR_NOT_SIGNED_IN	Selects not signed in.
MK_LOBBY_ERROR_FULL	Selects full.
MK_LOBBY_ERROR_NOT_FOUND	Selects not found.
MK_LOBBY_ERROR_BANNED	Selects banned.
MK_LOBBY_ERROR_NETWORK	Selects network.
MK_LOBBY_ERROR_TIMEOUT	Selects timeout.
MK_LOBBY_ERROR_PLATFORM	Selects platform.

mk_lobby_event_typeenum

Values for lobby event type.

Value	Description
MK_LOBBY_EVENT_MEMBER_JOINED	Selects member joined.
MK_LOBBY_EVENT_MEMBER_LEFT	Selects member left.
MK_LOBBY_EVENT_DATA_CHANGED	Selects data changed.
MK_LOBBY_EVENT_MEMBER_DATA_CHANGED	Selects member data changed.
MK_LOBBY_EVENT_HOST_CHANGED	Selects host changed.
MK_LOBBY_EVENT_GAME_STARTED	Connect info is now readable.
MK_LOBBY_EVENT_KICKED	The handle is terminal after this.
MK_LOBBY_EVENT_JOIN_REQUESTED	An invite was accepted; you have NOT joined.
MK_LOBBY_EVENT_DISCONNECTED	Selects disconnected.

mk_lobby_visibilityenum

Values for lobby visibility.

Value	Description
MK_LOBBY_PRIVATE	Invite only.
MK_LOBBY_FRIENDS	Selects friends.
MK_LOBBY_PUBLIC	Selects public.
MK_LOBBY_INVISIBLE	Joinable by id but not listed.

Typedefs

mk_lobby_backendtypedef

typedef enum mk_lobby_backend mk_lobby_backend

Values for lobby backend.

mk_lobby_capabilities_ttypedef

typedef uint64_t mk_lobby_capabilities_t

Type used for lobby capabilities.

mk_lobby_connect_infotypedef

typedef struct mk_lobby_connect_info mk_lobby_connect_info

Where gameplay traffic should connect once the host starts the session.

The lobby does not carry gameplay traffic. Non-hosts pass url to mk_host_connect_url(), or host/port to mk_host_connect().

mk_lobby_create_desctypedef

typedef struct mk_lobby_create_desc mk_lobby_create_desc

Data for lobby create desc.

mk_lobby_desctypedef

typedef struct mk_lobby_desc mk_lobby_desc

Data for lobby desc.

mk_lobby_errortypedef

typedef struct mk_lobby_error mk_lobby_error

Detail carried alongside mk_result.

mk_result has no NOT_FOUND, TIMEOUT, or NETWORK value, so lobby failures map onto the closest mk_result and carry the real reason here the same split mk_net_error uses.

mk_lobby_error_codetypedef

typedef enum mk_lobby_error_code mk_lobby_error_code

Values for lobby error code.

mk_lobby_eventtypedef

typedef struct mk_lobby_event mk_lobby_event

Data for lobby event.

mk_lobby_event_fntypedef

typedef void(*) mk_lobby_event_fn(const mk_lobby_event *event, void *user_data)

Lobby state change.

Delivered from mk_lobby_poll(); valid for the call only.

mk_lobby_event_typetypedef

typedef enum mk_lobby_event_type mk_lobby_event_type

Values for lobby event type.

mk_lobby_kvtypedef

typedef struct mk_lobby_kv mk_lobby_kv

Data for lobby kv.

mk_lobby_list_fntypedef

typedef void(*) mk_lobby_list_fn(mk_async_request_t request, mk_result result, const mk_lobby_error *error, const mk_lobby_summary *lobbies, uint32_t count, void *user_data)

Callback used for lobby list.

mk_lobby_membertypedef

typedef struct mk_lobby_member mk_lobby_member

Data for lobby member.

mk_lobby_query_desctypedef

typedef struct mk_lobby_query_desc mk_lobby_query_desc

Data for lobby query desc.

mk_lobby_result_fntypedef

typedef void(*) mk_lobby_result_fn(mk_async_request_t request, mk_result result, const mk_lobby_error *error, mk_lobby_t lobby, void *user_data)

Callback used for lobby result.

mk_lobby_summarytypedef

typedef struct mk_lobby_summary mk_lobby_summary

Data for lobby summary.

mk_lobby_ttypedef

typedef struct mk_lobby_handle mk_lobby_t

Data for lobby handle.

mk_lobby_visibilitytypedef

typedef enum mk_lobby_visibility mk_lobby_visibility

Values for lobby visibility.

Macros

MK_LOBBY_CONNECT_INFO_VERSIONdefine

MK_LOBBY_CONNECT_INFO_VERSION

ABI or format version for lobby connect info.

MK_LOBBY_CREATE_DESC_VERSIONdefine

MK_LOBBY_CREATE_DESC_VERSION

ABI or format version for lobby create desc.

MK_LOBBY_DESC_VERSIONdefine

MK_LOBBY_DESC_VERSION

ABI or format version for lobby desc.

MK_LOBBY_INVALIDdefine

MK_LOBBY_INVALID

Invalid sentinel for lobby.

MK_LOBBY_MAX_IDdefine

MK_LOBBY_MAX_ID

Maximum supported lobby ID.

MK_LOBBY_MAX_KEYdefine

MK_LOBBY_MAX_KEY

Maximum supported lobby key.

MK_LOBBY_MAX_NAMEdefine

MK_LOBBY_MAX_NAME

Maximum supported lobby name.

MK_LOBBY_MAX_VALUEdefine

MK_LOBBY_MAX_VALUE

Maximum supported lobby value.

MK_LOBBY_QUERY_DESC_VERSIONdefine

MK_LOBBY_QUERY_DESC_VERSION

ABI or format version for lobby query desc.