Steamworks Documentation
ISteamMatchmaking Interface
Functions for clients to access matchmaking services, favorites, and to operate on game lobbies.

See Steam Matchmaking & Lobbies for more information.

Member Functions

Member functions for ISteamMatchmaking are called through the global accessor function SteamMatchmaking().

AddFavoriteGame

int AddFavoriteGame( AppId_t nAppID, uint32 nIP, uint16 nConnPort, uint16 nQueryPort, uint32 unFlags, uint32 rTime32LastPlayedOnServer );
NameTypeDescription
nAppIDAppId_tThe App ID of the game.
nIPuint32The IP address of the server in host order, i.e 127.0.0.1 == 0x7f000001.
nConnPortuint16The port used to connect to the server, in host order.
nQueryPortuint16The port used to query the server, in host order.
unFlagsuint32Sets the whether the server should be added to the favorites list or history list. See k_unFavoriteFlagNone for more information.
rTime32LastPlayedOnServeruint32This should be the current time in Unix epoch format (seconds since Jan 1st, 1970).

Adds the game server to the local favorites list or updates the time played of the server if it already exists in the list.

Returns: int

AddRequestLobbyListCompatibleMembersFilter

void AddRequestLobbyListCompatibleMembersFilter( CSteamID steamIDLobby );
NameTypeDescription
steamIDLobbyCSteamID

Unused - Checks the player compatibility based on the frenemy system.

AddRequestLobbyListDistanceFilter

void AddRequestLobbyListDistanceFilter( ELobbyDistanceFilter eLobbyDistanceFilter );
NameTypeDescription
eLobbyDistanceFilterELobbyDistanceFilterSpecifies the maximum distance.

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.

AddRequestLobbyListFilterSlotsAvailable

void AddRequestLobbyListFilterSlotsAvailable( int nSlotsAvailable );
NameTypeDescription
nSlotsAvailableintThe number of open slots that must be open.

Filters to only return lobbies with the specified number of open slots available.

AddRequestLobbyListNearValueFilter

void AddRequestLobbyListNearValueFilter( const char *pchKeyToMatch, int nValueToBeCloseTo );
NameTypeDescription
pchKeyToMatchconst char *The filter key name to match. This can not be longer than k_nMaxLobbyKeyLength.
nValueToBeCloseTointThe value that lobbies will be sorted on.

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.

AddRequestLobbyListNumericalFilter

void AddRequestLobbyListNumericalFilter( const char *pchKeyToMatch, int nValueToMatch, ELobbyComparison eComparisonType );
NameTypeDescription
pchKeyToMatchconst char *The filter key name to match. This can not be longer than k_nMaxLobbyKeyLength.
nValueToMatchintThe number to match.
eComparisonTypeELobbyComparisonThe type of comparison to make.

Adds a numerical comparison filter to the next RequestLobbyList call.

AddRequestLobbyListResultCountFilter

void AddRequestLobbyListResultCountFilter( int cMaxResults );
NameTypeDescription
cMaxResultsintThe maximum number of lobbies to return.

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.

AddRequestLobbyListStringFilter

void AddRequestLobbyListStringFilter( const char *pchKeyToMatch, const char *pchValueToMatch, ELobbyComparison eComparisonType );
NameTypeDescription
pchKeyToMatchconst char *The filter key name to match. This can not be longer than k_nMaxLobbyKeyLength.
pchValueToMatchconst char *The string to match.
eComparisonTypeELobbyComparisonThe type of comparison to make.

Adds a string comparison filter to the next RequestLobbyList call.

CheckForPSNGameBootInvite

void CheckForPSNGameBootInvite( unsigned int iGameBootAttributes );
NameTypeDescription
iGameBootAttributesunsigned int

Deprecated - PS3 only.

CreateLobby

SteamAPICall_t CreateLobby( ELobbyType eLobbyType, int cMaxMembers );
NameTypeDescription
eLobbyTypeELobbyTypeThe type and visibility of this lobby. This can be changed later via SetLobbyType.
cMaxMembersintThe maximum number of players that can join this lobby. This can not be above 250.

Create a new matchmaking lobby.

Returns: SteamAPICall_t to be used with a LobbyCreated_t call result.
Triggers a LobbyEnter_t callback.
Triggers a LobbyDataUpdate_t callback.
If the results returned via the LobbyCreated_t call result indicate success then the lobby is joined & ready to use at this point.

The LobbyEnter_t callback is also received since the local user has joined their own lobby.

DeleteLobbyData

bool DeleteLobbyData( CSteamID steamIDLobby, const char *pchKey );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to delete the metadata for.
pchKeyconst char *The key to delete the data for.

Removes a metadata key from the lobby.

This can only be done by the owner of the lobby.

This will only send the data if the key existed. There is a slight delay before sending the data so you can call this repeatedly to set all the data you need to and it will automatically be batched up and sent after the last sequential call.

Returns: bool
true if the key/value was successfully deleted; otherwise, false if steamIDLobby or pchKey are invalid.

GetFavoriteGame

bool GetFavoriteGame( int iGame, AppId_t *pnAppID, uint32 *pnIP, uint16 *pnConnPort, uint16 *pnQueryPort, uint32 *punFlags, uint32 *pRTime32LastPlayedOnServer );
NameTypeDescription
iGameintThe index of the favorite game server to get the details of. This must be between 0 and GetFavoriteGameCount
pnAppIDAppId_t *Returns the App ID this server is for.
pnIPuint32 *Returns the IP address of the server in host order, i.e 127.0.0.1 == 0x7f000001.
pnConnPortuint16 *Returns the port used to connect to the server, in host order.
pnQueryPortuint16 *Returns the port used to query the server, in host order.
punFlagsuint32 *Returns whether the server is on the favorites list or the history list. See k_unFavoriteFlagNone for more information.
pRTime32LastPlayedOnServeruint32 *Returns the time the server was last added to the favorites list in Unix epoch format (seconds since Jan 1st, 1970).

Gets the details of the favorite game server by index.

NOTE: You must call GetFavoriteGameCount before calling this.

Returns: bool
true if the details were successfully retrieved. false if iGame was an invalid index.

See Also: AddFavoriteGame, RemoveFavoriteGame

GetFavoriteGameCount

int GetFavoriteGameCount();
Gets the number of favorite and recent game servers the user has stored locally.

Returns: int


See Also: AddFavoriteGame, RemoveFavoriteGame

GetLobbyByIndex

CSteamID GetLobbyByIndex( int iLobby );
NameTypeDescription
iLobbyintThe index of the lobby to get the Steam ID of, from 0 to LobbyMatchList_t.m_nLobbiesMatching.

Gets the Steam ID of the lobby at the specified index after receiving the RequestLobbyList results.

NOTE: This should only be called after a LobbyMatchList_t call result is received.

Returns: CSteamID
Returns k_steamIDNil if the provided index is invalid or there are no lobbies found.

GetLobbyChatEntry

int GetLobbyChatEntry( CSteamID steamIDLobby, int iChatID, CSteamID *pSteamIDUser, void *pvData, int cubData, EChatEntryType *peChatEntryType );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to get the chat entry from. This should almost always be LobbyChatMsg_t::m_ulSteamIDUser.
iChatIDintThe index of the chat entry in the lobby. This should almost always be LobbyChatMsg_t::m_iChatID.
pSteamIDUserCSteamID *If set then this returns the Steam ID of the user who sent this message. Usually unneeded since it will be the same as LobbyChatMsg_t::m_ulSteamIDUser.
pvDatavoid *Returns the message data by copying it into this buffer. This buffer should be up to 4 Kilobytes.
cubDataintThe size of the buffer allocated for pvData.
peChatEntryTypeEChatEntryType *If set then this will just always return k_EChatEntryTypeChatMsg. This can usually just be set to NULL.

Gets the data from a lobby chat message after receiving a LobbyChatMsg_t callback.

Returns: int
The number of bytes copied into pvData.

See Also: SendLobbyChatMsg

GetLobbyData

const char * GetLobbyData( CSteamID steamIDLobby, const char *pchKey );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to get the metadata from.
pchKeyconst char *The key to get the value of.

Gets the metadata associated with the specified key from the specified lobby.

NOTE: This can only get metadata from lobbies that the client knows about, either after receiving a list of lobbies from LobbyMatchList_t, retrieving the data with RequestLobbyData or after joining a lobby.

Returns: const char *
Returns an empty string ("") if no value is set for this key, or if steamIDLobby is invalid.

GetLobbyDataByIndex

bool GetLobbyDataByIndex( CSteamID steamIDLobby, int iLobbyData, char *pchKey, int cchKeyBufferSize, char *pchValue, int cchValueBufferSize );
NameTypeDescription
steamIDLobbyCSteamIDThis MUST be the same lobby used in the previous call to GetLobbyDataCount!
iLobbyDataintAn index between 0 and GetLobbyDataCount.
pchKeychar *Returns the name of the key at the specified index by copying it into this buffer.
cchKeyBufferSizeintThe size of the buffer allocated for pchKey. This typically should be k_nMaxLobbyKeyLength.
pchValuechar *Returns the value associated with the key at the specified index by copying it into this buffer.
cchValueBufferSizeintThe size of the buffer allocated for pchValue. This typically should be k_cubChatMetadataMax.

Gets a lobby metadata key/value pair by index.

NOTE: You must call GetLobbyDataCount before calling this.

Returns: bool
true upon success; otherwise, false if the steamIDLobby or iLobbyData are invalid.

GetLobbyDataCount

int GetLobbyDataCount( CSteamID steamIDLobby );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to get the data count from.

Gets the number of metadata keys set on the specified lobby.

NOTE: This can only get metadata from lobbies that the client knows about, either after receiving a list of lobbies from LobbyMatchList_t, retrieving the data with RequestLobbyData or after joining a lobby.

This is used for iteration, after calling this then GetLobbyDataByIndex can be used to get the key/value pair of each piece of metadata.

NOTE: This should typically only ever be used for debugging purposes.

Returns: int
Returns 0 if steamIDLobby is invalid.

Example:
void ListLobbyData( CSteamID lobbyID ) { int nData = SteamMatchmaking()->GetLobbyDataCount( lobbyID ); char key[k_nMaxLobbyKeyLength]; char value[k_cubChatMetadataMax]; for( int i = 0; i < nData; ++i ) { bool bSuccess = SteamMatchmaking()->GetLobbyDataByIndex( lobbyID, i, key, k_nMaxLobbyKeyLength, value, k_cubChatMetadataMax ); if ( bSuccess ) { printf( "Lobby Data %d, Key: \"%s\" - Value: \"%s\"\n", i, key, value ); } } }

GetLobbyGameServer

bool GetLobbyGameServer( CSteamID steamIDLobby, uint32 *punGameServerIP, uint16 *punGameServerPort, CSteamID *psteamIDGameServer );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to get the game server information from.
punGameServerIPuint32 *Returns the IP address of the game server, in host order, i.e 127.0.0.1 == 0x7f000001, if it's set.
punGameServerPortuint16 *Returns the connection port of the game server, in host order, if it's set.
psteamIDGameServerCSteamID *Returns the Steam ID of the game server, if it's set.

Gets the details of a game server set in a lobby.

Either the IP/Port or the Steam ID of the game server has to be valid, depending on how you want the clients to be able to connect.

Returns: bool
true if the lobby is valid and has a valid game server set; otherwise, false.

See Also: SetLobbyGameServer

GetLobbyMemberByIndex

CSteamID GetLobbyMemberByIndex( CSteamID steamIDLobby, int iMember );
NameTypeDescription
steamIDLobbyCSteamIDThis MUST be the same lobby used in the previous call to GetNumLobbyMembers!
iMemberintAn index between 0 and GetNumLobbyMembers.

Gets the Steam ID of the lobby member at the given index.

NOTE: You must call GetNumLobbyMembers before calling this.

NOTE: The current user must be in the lobby to retrieve the Steam IDs of other users in that lobby.

Returns: CSteamID
Invalid indices return k_steamIDNil.

GetLobbyMemberData

const char * GetLobbyMemberData( CSteamID steamIDLobby, CSteamID steamIDUser, const char *pchKey );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby that the other player is in.
steamIDUserCSteamIDThe Steam ID of the player to get the metadata from.
pchKeyconst char *The key to get the value of.

Gets per-user metadata from another player in the specified lobby.

This can only be queried from members in lobbies that you are currently in.

Returns: const char *
Returns NULL if steamIDLobby is invalid, or steamIDUser is not in the lobby.

Returns an empty string ("") if pchKey is not set for the player.

See Also: SetLobbyMemberData

GetLobbyMemberLimit

int GetLobbyMemberLimit( CSteamID steamIDLobby );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to get the member limit of.

The current limit on the # of users who can join the lobby.
Returns 0 if no limit is defined.

Returns: int
Returns 0 if no metadata is available for the specified lobby.

GetLobbyOwner

CSteamID GetLobbyOwner( CSteamID steamIDLobby );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to get the owner of.

Returns the current lobby owner.

NOTE: You must be a member of the lobby to access this.

There always one lobby owner - if the current owner leaves, another user in the lobby will become the owner automatically. It is possible (but rare) to join a lobby just as the owner is leaving, thus entering a lobby with self as the owner.

Returns: CSteamID
Returns k_steamIDNil if you're not in the lobby.

See Also: SetLobbyOwner

GetNumLobbyMembers

int GetNumLobbyMembers( CSteamID steamIDLobby );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to get the number of members of.

Gets the number of users in a lobby.

NOTE: The current user must be in the lobby to retrieve the Steam IDs of other users in that lobby.

This is used for iteration, after calling this then GetLobbyMemberByIndex can be used to get the Steam ID of each person in the lobby. Persona information for other lobby members (name, avatar, etc.) is automatically received and accessible via the ISteamFriends interface.

Returns: int
The number of members in the lobby, 0 if the current user has no data from the lobby.

InviteUserToLobby

bool InviteUserToLobby( CSteamID steamIDLobby, CSteamID steamIDInvitee );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to invite the user to.
steamIDInviteeCSteamIDThe Steam ID of the person who will be invited.

Invite another user to the lobby.

If the specified user clicks the join link, a GameLobbyJoinRequested_t callback will be posted if the user is in-game,
or if the game isn't running yet then the game will be automatically launched with the command line parameter +connect_lobby <64-bit lobby Steam ID> instead.

Returns: bool
true if the invite was successfully sent; otherwise, false if the local user isn't in a lobby, no connection to Steam could be made, or the specified user is invalid.

NOTE: This call doesn't check if the other user was successfully invited.

JoinLobby

SteamAPICall_t JoinLobby( CSteamID steamIDLobby );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to join.

Joins an existing lobby.

The lobby Steam ID can be obtained either from a search with RequestLobbyList, joining on a friend, or from an invite.

Returns: SteamAPICall_t to be used with a LobbyEnter_t call result.
Triggers a LobbyDataUpdate_t callback.

LeaveLobby

void LeaveLobby( CSteamID steamIDLobby );
NameTypeDescription
steamIDLobbyCSteamIDThe lobby to leave.

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.

RemoveFavoriteGame

bool RemoveFavoriteGame( AppId_t nAppID, uint32 nIP, uint16 nConnPort, uint16 nQueryPort, uint32 unFlags );
NameTypeDescription
nAppIDAppId_tThe App ID of the game.
nIPuint32The IP address of the server in host order, i.e 127.0.0.1 == 0x7f000001.
nConnPortuint16The port used to connect to the server, in host order.
nQueryPortuint16The port used to query the server, in host order.
unFlagsuint32Whether the server is on the favorites list or history list. See k_unFavoriteFlagNone for more information.

Removes the game server from the local favorites list.

Returns: bool
true if the server was removed; otherwise, false if the specified server was not on the users local favorites list.

RequestLobbyData

bool RequestLobbyData( CSteamID steamIDLobby );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to refresh the metadata of.

Refreshes all of the metadata for a lobby that you're not in right now.

You will never do this for lobbies you're a member of, that data will always be up to date. You can use this to refresh lobbies that you have obtained from RequestLobbyList or that are available via friends.

Returns: bool
Triggers a LobbyDataUpdate_t callback.
true if the request was successfully sent to the server. false if no connection to Steam could be made, or steamIDLobby is invalid.

If the specified lobby doesn't exist, LobbyDataUpdate_t::m_bSuccess will be set to false.

RequestLobbyList

SteamAPICall_t RequestLobbyList();
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.

NOTE: To filter the results you MUST call the AddRequestLobbyList* functions before calling this. The filters are cleared on each call to this function.

NOTE: If AddRequestLobbyListDistanceFilter is not called, k_ELobbyDistanceFilterDefault will be used, which will only find matches in the same or nearby regions.

NOTE: 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.

Returns: SteamAPICall_t to be used with a LobbyMatchList_t call result.
NOTE: This also returns as a callback for compatibility with older applications, but you should use the call result if possible.

See Also: AddRequestLobbyListStringFilter, AddRequestLobbyListNumericalFilter, AddRequestLobbyListNearValueFilter, AddRequestLobbyListFilterSlotsAvailable, AddRequestLobbyListDistanceFilter, AddRequestLobbyListResultCountFilter

Example:
class CLobbyListManager { CCallResult< CLobbyListManager, LobbyMatchList_t > m_CallResultLobbyMatchList; void FindLobbies() { // SteamMatchmaking()->AddRequestLobbyListFilter*() functions would be called here, before RequestLobbyList() SteamAPICall_t hSteamAPICall = SteamMatchmaking()->RequestLobbyList(); m_CallResultLobbyMatchList.Set( hSteamAPICall, this, &CLobbyListManager::OnLobbyMatchList ); } void OnLobbyMatchList( LobbyMatchList_t *pLobbyMatchList, bool bIOFailure ) { // lobby list has been retrieved from Steam back-end, use results } }

SendLobbyChatMsg

bool SendLobbyChatMsg( CSteamID steamIDLobby, const void *pvMsgBody, int cubMsgBody );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to send the chat message to.
pvMsgBodyconst void *This can be text or binary data, up to 4 Kilobytes in size.
cubMsgBodyintThe size in bytes of pvMsgBody, if it's a text message then this should be strlen( text ) + 1 to include the null terminator.

Broadcasts a chat (text or binary data) message to the all of the users in the lobby.

All users in the lobby (including the local user) will receive a LobbyChatMsg_t callback with the message.

If you're sending binary data, you should prefix a header to the message so that you know to treat it as your custom data rather than a plain old text message.

For communication that needs to be arbitrated (for example having a user pick from a set of characters, and making sure only one user has picked a character), you can use the lobby owner as the decision maker. GetLobbyOwner returns the current lobby owner. There is guaranteed to always be one and only one lobby member who is the owner. So for the choose-a-character scenario, the user who is picking a character would send the binary message 'I want to be Zoe', the lobby owner would see that message, see if it was OK, and broadcast the appropriate result (user X is Zoe).

These messages are sent via the Steam back-end, and so the bandwidth available is limited. For higher-volume traffic like voice or game data, you'll want to use the Steam Networking API.

Returns: bool
Triggers a LobbyChatMsg_t callback.
true if the message was successfully sent. false if the message is too small or too large, or no connection to Steam could be made.

SetLinkedLobby

bool SetLinkedLobby( CSteamID steamIDLobby, CSteamID steamIDLobbyDependent );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the primary lobby.
steamIDLobbyDependentCSteamIDThe Steam ID that will be linked to the primary lobby.

Unused - Link two lobbies for the purposes of checking player compatibility using the frenemy system.

You must be the lobby owner of both lobbies.

Returns: bool
true if the request was successfully sent to the Steam server.
false if the local user isn't the owner of both lobbies, or no connection to Steam could be made.

SetLobbyData

bool SetLobbyData( CSteamID steamIDLobby, const char *pchKey, const char *pchValue );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to set the metadata for.
pchKeyconst char *The key to set the data for. This can not be longer than k_nMaxLobbyKeyLength.
pchValueconst char *The value to set. This can not be longer than k_cubChatMetadataMax.

Sets a key/value pair in the lobby metadata. This can be used to set the the lobby name, current map, game mode, etc.

This can only be set by the owner of the lobby. Lobby members should use SetLobbyMemberData instead.

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.

This will only send the data if it has changed. There is a slight delay before sending the data so you can call this repeatedly to set all the data you need to and it will automatically be batched up and sent after the last sequential call.

Returns: bool
true if the data has been set successfully. false if steamIDLobby was invalid, or the key/value are too long.

SetLobbyGameServer

void SetLobbyGameServer( CSteamID steamIDLobby, uint32 unGameServerIP, uint16 unGameServerPort, CSteamID steamIDGameServer );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to set the game server information for.
unGameServerIPuint32Sets the IP address of the game server, in host order, i.e 127.0.0.1 == 0x7f000001.
unGameServerPortuint16Sets the connection port of the game server, in host order.
steamIDGameServerCSteamIDSets the Steam ID of the game server. Use k_steamIDNil if you're not setting this.

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.

Returns: void
Triggers a LobbyGameCreated_t callback.


See Also: GetLobbyGameServer

SetLobbyJoinable

bool SetLobbyJoinable( CSteamID steamIDLobby, bool bLobbyJoinable );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby
bLobbyJoinableboolEnable (true) or disable (false) allowing users to join this lobby?

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.

Lobbies with joining disabled will not be returned from a lobby search.

Returns: bool
true upon success; otherwise, false if you're not the owner of the lobby.

SetLobbyMemberData

void SetLobbyMemberData( CSteamID steamIDLobby, const char *pchKey, const char *pchValue );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to set our metadata in.
pchKeyconst char *The key to set the data for. This can not be longer than k_nMaxLobbyKeyLength.
pchValueconst char *The value to set. This can not be longer than k_cubChatMetadataMax.

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.

There is a slight delay before sending the data so you can call this repeatedly to set all the data you need to and it will automatically be batched up and sent after the last sequential call.

Returns: void
Triggers a LobbyDataUpdate_t callback.


See Also: GetLobbyMemberData

SetLobbyMemberLimit

bool SetLobbyMemberLimit( CSteamID steamIDLobby, int cMaxMembers );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to set the member limit for.
cMaxMembersintThe maximum number of players allowed in this lobby. This can not be above 250.

Set the maximum number of players that can join the lobby.

This is also set when you create the lobby with CreateLobby.
This can only be set by the owner of the lobby.

Returns: bool
true if the limit was successfully set.
false if you are not the owner of the specified lobby.

SetLobbyOwner

bool SetLobbyOwner( CSteamID steamIDLobby, CSteamID steamIDNewOwner );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby where the owner change will take place.
steamIDNewOwnerCSteamIDThe Steam ID of the user that will be the new owner of the lobby, they must be in the lobby.

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.

Returns: bool
Triggers a LobbyDataUpdate_t callback.
true if the owner was successfully changed.
false if you're not the current owner of the lobby, steamIDNewOwner is not a member in the lobby, or if no connection to Steam could be made.

See Also: GetLobbyOwner

SetLobbyType

bool SetLobbyType( CSteamID steamIDLobby, ELobbyType eLobbyType );
NameTypeDescription
steamIDLobbyCSteamIDThe Steam ID of the lobby to set the type of.
eLobbyTypeELobbyTypeThe new lobby type to that will be set.

Updates what type of lobby this is.

This is also set when you create the lobby with CreateLobby.
This can only be set by the owner of the lobby.

Returns: bool
true upon success; otherwise, false if you're not the owner of the lobby.

Callbacks

These are callbacks which can be fired by calling SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ISteamMatchmaking.

FavoritesListAccountsUpdated_t



NameTypeDescription
m_eResultEResult

FavoritesListChanged_t

A server was added/removed from the favorites list, you should refresh now.

NameTypeDescription
m_nIPuint32An IP of 0 means reload the whole list, any other value means just one server. This is host order, i.e 127.0.0.1 == 0x7f000001.
m_nQueryPortuint32If m_nIP is set then this is the new servers query port, in host order.
m_nConnPortuint32If m_nIP is set then this is the new servers connection port, in host order.
m_nAppIDuint32If m_nIP is set then this is the App ID the game server belongs to.
m_nFlagsuint32If m_nIP is set then this returns whether the the server is on the favorites list or the history list. See k_unFavoriteFlagNone for more information.
m_bAddboolIf m_nIP is set then this is whether the server was added to the list (true) or removed (false) from it.
m_unAccountIdAccountID_t

LobbyChatMsg_t

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.

NameTypeDescription
m_ulSteamIDLobbyuint64The Steam ID of the lobby this message was sent in.
m_ulSteamIDUseruint64Steam ID of the user who sent this message. Note that it could have been the local user.
m_eChatEntryTypeuint8Type of message received. This is actually a EChatEntryType.
m_iChatIDuint32The index of the chat entry to use with GetLobbyChatEntry, this is not valid outside of the scope of this callback and should never be stored.

Associated Functions: SendLobbyChatMsg

LobbyChatUpdate_t

A lobby chat room state has changed, this is usually sent when a user has joined or left the lobby.

NameTypeDescription
m_ulSteamIDLobbyuint64The Steam ID of the lobby.
m_ulSteamIDUserChangeduint64The user who's status in the lobby just changed - can be recipient.
m_ulSteamIDMakingChangeuint64Chat member who made the change. This can be different from m_ulSteamIDUserChanged if kicking, muting, etc. For example, if one user kicks another from the lobby, this will be set to the id of the user who initiated the kick.
m_rgfChatMemberStateChangeuint32Bitfield of EChatMemberStateChange values.

LobbyCreated_t

Result of our request to create a Lobby. At this point, the lobby has been joined and is ready for use, a LobbyEnter_t callback will also be received (since the local user is joining their own lobby).

NameTypeDescription
m_eResultEResultThe result of the operation.

Possible values:
m_ulSteamIDLobbyuint64The Steam ID of the lobby that was created, 0 if failed.

Associated Functions: CreateLobby

LobbyDataUpdate_t

The lobby metadata has changed.

If m_ulSteamIDMember is a user in the lobby, then use GetLobbyMemberData to access per-user details; otherwise, if m_ulSteamIDMember == m_ulSteamIDLobby, use GetLobbyData to access the lobby metadata.

NameTypeDescription
m_ulSteamIDLobbyuint64The Steam ID of the Lobby.
m_ulSteamIDMemberuint64Steam ID of either the member whose data changed, or the room itself.
m_bSuccessuint8true if the lobby data was successfully changed, otherwise false.

Associated Functions: CreateLobby, JoinLobby, SetLobbyMemberData, RequestLobbyData, SetLobbyOwner

LobbyEnter_t

Recieved upon attempting to enter a lobby. Lobby metadata is available to use immediately after receiving this.

NameTypeDescription
m_ulSteamIDLobbyuint64The steam ID of the Lobby you have entered.
m_rgfChatPermissionsuint32Unused - Always 0.
m_bLockedboolIf true, then only invited users may join.
m_EChatRoomEnterResponseuint32This is actually a EChatRoomEnterResponse value. This will be set to k_EChatRoomEnterResponseSuccess if the lobby was successfully joined, otherwise it will be k_EChatRoomEnterResponseError.

Associated Functions: CreateLobby, JoinLobby

LobbyGameCreated_t

A game server has been set via SetLobbyGameServer 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.

NameTypeDescription
m_ulSteamIDLobbyuint64The lobby that set the game server.
m_ulSteamIDGameServeruint64The Steam ID of the game server, if it's set.
m_unIPuint32The IP address of the game server in host order, i.e 127.0.0.1 == 0x7f000001, if it's set.
m_usPortuint16The connection port of the game server, in host order, if it's set.

Associated Functions: SetLobbyGameServer

LobbyInvite_t

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>, or with the callback GameLobbyJoinRequested_t if they're already in-game.

NameTypeDescription
m_ulSteamIDUseruint64Steam ID of the person that sent the invite.
m_ulSteamIDLobbyuint64Steam ID of the lobby we're invited to.
m_ulGameIDuint64Game ID of the lobby we're invited to.

LobbyKicked_t

Currently unused! If you want to implement kicking at this time then do it with a special packet sent with SendLobbyChatMsg, when the user gets the packet they should call LeaveLobby.

NameTypeDescription
m_ulSteamIDLobbyuint64
m_ulSteamIDAdminuint64
m_bKickedDueToDisconnectuint8

LobbyMatchList_t

Result when requesting the lobby list. You should iterate over the returned lobbies with GetLobbyByIndex, from 0 to m_nLobbiesMatching-1.

NameTypeDescription
m_nLobbiesMatchinguint32Number of lobbies that matched search criteria and we have Steam IDs for.

Associated Functions: RequestLobbyList

PSNGameBootInviteResult_t

Deprecated - PS3 only.

NameTypeDescription
m_bGameBootInviteExistsbool
m_steamIDLobbyCSteamID

Enums

These are enums which are defined for use with ISteamMatchmaking.

EChatMemberStateChange

Flags describing how a users lobby state has changed. This is provided from LobbyChatUpdate_t.

NameValueDescription
k_EChatMemberStateChangeEntered0x0001This user has joined or is joining the lobby.
k_EChatMemberStateChangeLeft0x0002This user has left or is leaving the lobby.
k_EChatMemberStateChangeDisconnected0x0004User disconnected without leaving the lobby first.
k_EChatMemberStateChangeKicked0x0008The user has been kicked.
k_EChatMemberStateChangeBanned0x0010The user has been kicked and banned.

ELobbyComparison

Lobby search filter options. These can be set with AddRequestLobbyListStringFilter and AddRequestLobbyListNearValueFilter.

NameValueDescription
k_ELobbyComparisonEqualToOrLessThan-2The lobbies value must be equal to or less than this one.
k_ELobbyComparisonLessThan-1The lobbies value must be less than this one.
k_ELobbyComparisonEqual0The lobbies value must match this this one exactly.
k_ELobbyComparisonGreaterThan1The lobbies value must be greater than this one.
k_ELobbyComparisonEqualToOrGreaterThan2The lobbies value must be equal to or greater than this one.
k_ELobbyComparisonNotEqual3The lobbies value must not match this this.

ELobbyDistanceFilter

Lobby search distance filters when requesting the lobby list. Lobby results are sorted from closest to farthest. This can be set with AddRequestLobbyListDistanceFilter.

NameValueDescription
k_ELobbyDistanceFilterClose0Only lobbies in the same immediate region will be returned.
k_ELobbyDistanceFilterDefault1Only lobbies in the same region or nearby regions will be returned.
k_ELobbyDistanceFilterFar2For games that don't have many latency requirements, will return lobbies about half-way around the globe.
k_ELobbyDistanceFilterWorldwide3No filtering, will match lobbies as far as India to NY (not recommended, expect multiple seconds of latency between the clients).

ELobbyType

Specifies the lobby type, this is set from CreateLobby and SetLobbyType.

NameValueDescription
k_ELobbyTypePrivate0The only way to join the lobby is from an invite.
k_ELobbyTypeFriendsOnly1Joinable by friends and invitees, but does not show up in the lobby list.
k_ELobbyTypePublic2Returned by search and visible to friends.
k_ELobbyTypeInvisible3Returned by search, but not visible to other friends.
This is useful if you want a user in two lobbies, for example matching groups together. A user can be in only one regular lobby, and up to two invisible lobbies.

Typedefs

These are typedefs which are defined for use with ISteamMatchmaking.

NameBase typeDescription
HServerListRequestvoid*Handle that you will receive when requesting server list.
HServerQueryintHandle that you will receive when querying details on an individual server.

Constants

These are constants which are defined for use with ISteamMatchmaking.

NameTypeValueDescription
HSERVERQUERY_INVALIDint0xffffffff
k_nMaxLobbyKeyLengthint255Maximum number of characters a lobby metadata key can be.
k_unFavoriteFlagFavoriteuint320x01This favorite game server entry is for the favorites list.
k_unFavoriteFlagHistoryuint320x02This favorite game server entry is for the history list.
k_unFavoriteFlagNoneuint320x00This favorite game server has no flags set.
STEAMMATCHMAKINGSERVERS_INTERFACE_VERSIONconst char *"SteamMatchMakingServers002"
STEAMMATCHMAKING_INTERFACE_VERSIONconst char *"SteamMatchMaking009"