Comment on page
Matchmaking.Client
Unity centric wrapper around the ISteamMatchmaking API
Support us as a GitHub Sponsor and get instant access to all our assets, exclusive tools and assets, escalated support and issue tracking and our gratitude.
These articles are made possible by our GitHub Sponsors ... become a sponsor today!
using API = HeathenEngineering.SteamworksIntegration.API;
public static class API.Matchmaking
The whole of the matchmaking system is only accessible from the Client API as a result you will always be using the form:
API.Matchmaking.Client
TIP
Save your self some typing. add this using statement to the top of any script that will need to use this API.
using Matchmaking = HeathenEngineering.SteamworksIntegration.API.Matchmaking.Client;
You can now access members in this API with a shorter call structure
var data = Matchmaking.GetLobbydata(lobby);
as opposed to the long form:
var data = API.Matchmaking.Client.GetLobbydata(lobby);
The matchmaking system is fundamentally a system for getting player's together in order to play games. The main feature of the system is the Steam Lobby. Steam Lobbies can be searched for based on the metadata of a lobby, they can be advertised via Party Beacons, on the friends list and direct invites can be sent to targeted players.
Steam Lobby can be used for more than a simple game lobby, depending on your games specific needs they can provide for teams, party/groups, session merging and more. Valve allows a user to be a member of 1 "normal" lobby and up to 2 additional "invisible" lobbies. Each lobby has its own set of metadata for the lobby its self and for each of its members and each lobby includes a simple chat system.
Take a look at the Lobby Manager for a tool that can help you manage a specific uses for a Steam Lobby and which can simplify lobby interactions and facilitate lobby UIs.
Lobby Manager
Heathen KB
Simplify Steam Lobbies
Lobby Chat Director
Heathen KB
Connect your UI to lobby chat quickly and easily
Lobby Chat Msg
Heathen KB
Lobby chat messages made easy
Lobby Game Server
Heathen KB
How you know where to go
Lobby Member
Heathen KB
Represents a lobby member and simples accessing its data
Occurs when a lobby enter callback is received and the response code is a success
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(LobbyEnter_t result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventLobbyEnterSuccess.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventLobbyEnterSuccess.RemoveListener(HandleEvent);
}
Occurs when a lobby enter callback is received and the response code is not a success.
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(LobbyEnter_t result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventLobbyEnterFailed.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventLobbyEnterFailed.RemoveListener(HandleEvent);
}
Occurs when the lobby metadata has changed.
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(LobbyDataUpdateEventData result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventLobbyDataUpdate.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventLobbyDataUpdate.RemoveListener(HandleEvent);
}
Occurs when a chat (text or binary) message for this lobby has been received. After getting this you must use GetLobbyChatEntry to retrieve the contents of this message.
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(LobbyChatMsg result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.LobbyChatMsgEvent.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.LobbyChatMsgEvent.RemoveListener(HandleEvent);
}
A server was added/removed from the favorites list, you should refresh now.
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(FavoritesListChanged_t result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventFavoritesListChanged.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behviour using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventFavoritesListChanged.RemoveListener(HandleEvent);
}
A lobby chat room state has changed, this is usually sent when a user has joined or left the lobby.
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(LobbyChatUpdate_t result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventLobbyChatUpdate.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventLobbyChatUpdate.RemoveListener(HandleEvent);
}
A game server has been set via Set Lobby Game Server for all of the members of the lobby to join. It's up to the individual clients to take action on this; the typical game behavior is to leave the lobby and connect to the specified game server; but the lobby may stay open throughout the session if desired.
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(LobbyGameCreated_t result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventLobbyGameCreated.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventLobbyGameCreated.RemoveListener(HandleEvent);
}
Someone has invited you to join a Lobby. Normally you don't need to do anything with this, as the Steam UI will also display a '<user> has invited you to the lobby, join?' notification and message.
If the user outside a game chooses to join, your game will be launched with the parameter
+connect_lobby <64-bit lobby id>You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(LobbyInvite_t result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventLobbyInvite.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventLobbyInvite.RemoveListener(HandleEvent);
}
Invoked when API.Matchmaking.Client.LeaveLobby is called
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(Lobby result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventLobbyLeave.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventLobbyLeave.RemoveListener(HandleEvent);
}
The local user has been asked to leave a lobby. In general you should handle this event and leave when asked assuming your game has implemented kick lobby.
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(Lobby result)
{
}
Then you would register the event such as:
API.Matchmaking.Client.EventLobbyAskedToLeave.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Matchmaking.Client.EventLobbyAskedToLeave.RemoveListener(HandleEvent);
}
This list is populated by the system as the user creates, joins and leaves lobbies. It is a list of lobbies the user is currently a member of.
public static List<Lobby> memberOfLobbies => get;
You can call this field via
foreach(var lobby in API.Matchmaking.Client.memberOfLobbies)
{
Debug.Log("Member of lobby: " + lobby.Name);
}
public static void AddHistoryGame(AppId_t appID,
uint ipAddress,
ushort port,
ushort queryPort,
DateTime lastPlayedOnServer)
Adds the game server to the local favorites list or updates the time played of the server if it already exists in the list.
public static void AddFavoriteGame(AppId_t appID,
uint ipAddress,
ushort port,
ushort queryPort,
DateTime lastPlayedOnServer)
Adds the game server to the local favorites list or updates the time played of the server if it already exists in the list.
public static void AddHistoryGame(AppId_t appID,
string ipAddress,
ushort port,
ushort queryPort,
DateTime lastPlayedOnServer)
Adds the game server to the local favorites list or updates the time played of the server if it already exists in the list.
public static void AddFavoriteGame(AppId_t appID,
string ipAddress,
ushort port,
ushort queryPort,
DateTime lastPlayedOnServer)
Adds the game server to the local favorites list or updates the time played of the server if it already exists in the list.
public static void AddRequestLobbyListDistanceFilter(ELobbyDistanceFilter distanceFilter)
Sets the physical distance for which we should search for lobbies, this is based on the users IP address and a IP location map on the Steam backed.
public static void AddRequestLobbyListFilterSlotsAvailable(int slotsAvailable)
Filters to only return lobbies with the specified number of open slots available.
public static void AddRequestLobbyListNearValueFilter(string key, int value)
Sorts the results closest to the specified value.
Near filters don't actually filter out values, they just influence how the results are sorted. You can specify multiple near filters, with the first near filter influencing the most, and the last near filter influencing the least.
public static void AddRequestLobbyListNumericalFilter(string key,
int value,
ELobbyComparison comparison)
Adds a numerical comparison filter to the next RequestLobbyList call.
public static void AddRequestLobbyListResultCountFilter(int max)
Sets the maximum number of lobbies to return. The lower the count the faster it is to download the lobby results & details to the client.
public static void AddRequestLobbyListStringFilter(string key,
string value,
ELobbyComparison comparison)
Adds a string comparison filter to the next RequestLobbyList call.
public static void CreateLobby(ELobbyType type,
int maxMembers,
Action<EResult, Lobby, bool> callback)
The callback delegate should be in the form of
void CallbackHandler(EResult result, Lobby lobby, bool IOError);
Create a new lobby and set the max members allowed. The callback will report success or failure and the reason why via the EResult value.
public static bool DeleteLobbyData(Lobby lobby, string key)
Removes a metadata key from the lobby.
public static FavoriteGame? GetFavoriteGame(int index)
Gets the details of the favorite game server by index.
public static FavoriteGame[] GetFavoriteGames()
Returns the collection of favorite game entries
public static int GetFavoriteGameCount()
Gets the number of favorite and recent game servers the user has stored locally.
public static string GetLobbyData(Lobby lobby, string key)
public static Dictionary<string, string> GetLobbyData(Lobby lobby)
Gets the metadata associated with the specified key from the specified lobby.
public static LobbyGameServer GetLobbyGameServer(Lobby lobby)
Gets the details of a game server set in a lobby.
public static LobbyMember[] GetLobbyMembers(Lobby lobby)
The current user must be in the lobby to retrieve the Steam IDs of other users in that lobby.
Returns a list of user IDs for the members of the indicated lobby
public static int GetLobbyMemberLimit(Lobby lobby)
The current limit on the # of users who can join the lobby.
public static CSteamID GetLobbyOwner(Lobby lobby)
Returns the current lobby owner.
public static bool InviteUserToLobby(Lobby lobby, UserData user)
Invite another user to the lobby.
public static void JoinLobby(Lobby lobby, Action<LobbyEnter_t, bool> callback)
Joins an existing lobby.
public static void LeaveLobby(Lobby lobby)
Leave a lobby that the user is currently in; this will take effect immediately on the client side, other users in the lobby will be notified by a LobbyChatUpdate_t callback.
public static bool RemoveFavoriteGame(AppId_t appId,
uint ip,
ushort connectionPort,
ushort queryPort)
Removes the game server from the local favorites list.
public static bool RemoveHistoryGame(AppId_t appId,
uint ip,
ushort connectionPort,
ushort queryPort)
Removes the game server from the local history list.
public static bool RequestLobbyData(LobbyData lobby)
If your in the lobby then its data is always up to date
Refreshes all of the metadata for a lobby that you're not in right now.
public static void RequestLobbyList(Action<LobbyData[], bool> callback)
Get a filtered list of relevant lobbies.
There can only be one active lobby search at a time. The old request will be canceled if a new one is started. Depending on the users connection to the Steam back-end, this call can take from 300ms to 5 seconds to complete, and has a timeout of 20 seconds.
To filter the results you MUST call the AddRequestLobbyList* functions before calling this. The filters are cleared on each call to this function.
If AddRequestLobbyListDistanceFilter is not called, k_ELobbyDistanceFilterDefault will be used, which will only find matches in the same or nearby regions.
This will only return lobbies that are not full, and only lobbies that are k_ELobbyTypePublic or k_ELobbyTypeInvisible, and are set to joinable with SetLobbyJoinable.
public static bool SendLobbyChatMsg(LobbyData lobby, byte[] messageBody)
Broadcasts a chat (text or binary data) message to the all of the users in the lobby.
public static bool SetLobbyData(LobbyData lobby, string key, string value)
This can only be set by the owner of the lobby. Lobby members should use SetLobbyMemberData instead.
Sets a key/value pair in the lobby metadata. This can be used to set the the lobby name, current map, game mode, etc.
public static void SetLobbyGameServer(LobbyData lobby,
uint ip,
ushort port,
CSteamID gameServerId)
Sets the game server associated with the lobby.
This can only be set by the owner of the lobby.
Either the IP/Port or the Steam ID of the game server must be valid, depending on how you want the clients to be able to connect.
A LobbyGameCreated_t callback will be sent to all players in the lobby, usually at this point, the users will join the specified game server.
public static bool SetLobbyJoinable(Lobby lobby, bool joinable)
Sets whether or not a lobby is joinable by other players. This always defaults to enabled for a new lobby.
If joining is disabled, then no players can join, even if they are a friend or have been invited.
public static string GetLobbyMemberData(Lobby lobby, CSteamID member, string key)
Gets per-user metadata from another player in the specified lobby.
public static bool GetMember(Lobby lobby, CSteamID id, out LobbyMember member)
Get the LobbyMember object for a given user
public static bool IsAMember(Lobby lobby, CSteamID id)
Checks if a user is a member of this lobby
public static void SetLobbyMemberData(Lobby lobby, string key, string value)
Sets per-user metadata for the local user.
Each user in the lobby will be receive notification of the lobby data change via a LobbyDataUpdate_t callback, and any new users joining will receive any existing data.
public static bool SetLobbyMemberLimit(Lobby lobby, int maxMembers)
Set the maximum number of players that can join the lobby.
public static bool SetLobbyOwner(Lobby lobby, CSteamID newOwner)
Changes who the lobby owner is.
This can only be set by the owner of the lobby. This will trigger a LobbyDataUpdate_t for all of the users in the lobby, each user should update their local state to reflect the new owner. This is typically accomplished by displaying a crown icon next to the owners name.
public static bool SetLobbyType(Lobby lobby, ELobbyType type)
Updates what type of lobby this is.
public static void CancelQuery(HServerListRequest request)
Cancel an outstanding server list request.
public static void CancelServerQuery(HServerQuery query)
Cancel an outstanding individual server query.
public static int GetServerCount(HServerListRequest request)
Gets the number of servers in the given list.
Get the details of a given server in the list. or get all servers as an array
public static gameserveritem_t GetServerDetails(
HServerListRequest request,
int index)
public static gameserveritem_t[] GetServerDetails(
HServerListRequest request)
public static bool IsRefreshing(HServerListRequest request)
Checks if the server list request is currently refreshing.
public static HServerQuery PingServer(uint ip,
ushort port,
ISteamMatchmakingPingResponse responce)
Queries an individual game servers directly via IP/Port to request an updated ping time and other details from the server.
public static HServerQuery PlayerDetails(uint ip,
ushort port,
ISteamMatchmakingPlayersResponse responce)
Queries an individual game servers directly via IP/Port to request the list of players currently playing on the server.
public static void RefreshQuery(HServerListRequest request)
Ping every server in your list again but don't update the list of servers.
public static void RefreshServer(HServerListRequest request, int index)
Refreshes a single server inside of a query.
public static void ReleaseRequest(HServerListRequest request)
Releases the asynchronous server list request object and cancels any pending query on it if there's a pending query in progress.
public static HServerListRequest RequestFavoritesServerList(AppId_t appId,
MatchMakingKeyValuePair_t[] filters,
ISteamMatchmakingServerListResponse pRequestServersResponse)
Request a new list of game servers from the 'favorites' server list.
public static HServerListRequest RequestFriendsServerList(AppId_t appId,
MatchMakingKeyValuePair_t[] filters,
ISteamMatchmakingServerListResponse pRequestServersResponse)
Request a new list of game servers from the 'friends' server list.
public static HServerListRequest RequestHistoryServerList(AppId_t appId,
MatchMakingKeyValuePair_t[] filters,
ISteamMatchmakingServerListResponse pRequestServersResponse)
Request a new list of game servers from the 'history' server list.
public static HServerListRequest RequestInternetServerList(AppId_t appId,
MatchMakingKeyValuePair_t[] filters,
ISteamMatchmakingServerListResponse pRequestServersResponse)
Request a new list of game servers from the 'internet' server list.
public static HServerListRequest RequestLANServerList(AppId_t appId,