Functions | Matchmaking

Here is a list of all the functions available in the GodotSteam module. The descriptions are pulled from the official Steamworks SDK documentation with modifications made to fit GodotSteam's implementation of the functions. Naturally, any GodotSteam-specific functions will be noted as such.


addFavoriteGame( int app_id, int ip, int port, int queryPort, int flags, int lastPlayed ) addFavoriteGame( uint32 ip, uint16 port, uint16 queryPort, uint32 flags, uint32 lastPlayed )

  • 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 an int.

addRequestLobbyListDistanceFilter( int distance_filter )

  • 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.
  • Returns nothing; void.

addRequestLobbyListFilterSlotsAvailable( int slots_available )

  • Filters to only return lobbies with the specified number of open slots available.
  • Returns nothing; void.

addRequestLobbyListNearValueFilter( string keyToMatch, int valueToBeCloseTo )

  • 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.
  • Returns nothing; void.

addRequestLobbyListNumericalFilter( string key_to_match, int value_to_match, int comparison_type )

  • Adds a numerical comparison filter to the next requestLobbyList call.
  • Returns nothing; void.

addRequestLobbyListResultCountFilter( int max_results )

  • 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.
  • Returns nothing; void.

addRequestLobbyListStringFilter( string key_to_match, string value_to_match, int comparison_type )

  • Adds a string comparison filter to the next requestLobbyList call.
  • Returns nothing; void.

createLobby( int lobby_type, int max_members )

  • Create a new matchmaking lobby.
  • Triggers a lobby_created callback.
  • Triggers a lobby_joined callback.
  • Triggers a lobby_data_update callback.
  • Returns nothing; void. If the results returned via the lobby_created call result indicate success then the lobby is joined & ready to use at this point.

deleteLobbyData( int steam_lobby_id, string key ) deleteLobbyData( uint64_t steam_lobby_id, string key )

  • 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 a bool.

getAllLobbyData( int steam_lobby_id ) getAllLobbyData( uint64_t steam_lobby_id )

  • Get lobby data by the lobby's ID.
  • Note: This is a GodotSteam specific function.
  • Returns a dictionary:
    • index (int)
    • key (string)
    • value (string)

getFavoriteGames()

  • Gets the details of the favorite game server by index.
  • Note: You must call getFavoriteGameCount before calling this. This is already used in GodotSteam's implementation, however.
  • Returns an array of:
    • favorite (dictionary)
      • ret (bool)
      • app (int)
      • ip (string)
      • port (int)
      • query (int)
      • flags (int)
      • last_played (int)
      • ret (bool)
      • app (uint32)
      • ip (string)
      • game_port (uint16)
      • query_port (uint16)
      • flags (uint32)
      • last_played (uint32)

getLobbyData( int steam_lobby_id, string key ) getLobbyData( uint64_t steam_lobby_id, string key )

  • 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 lobby_match_list, retrieving the data with requestLobbyData or after joining a lobby.
  • Returns a string. Returns an empty string if no value is set for this key, or if steam_lobby_id is invalid.

getLobbyGameServer( int steam_lobby_id ) getLobbyGameServer( uint64_t steam_lobby_id )

  • 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 a dictionary:
    • ret (bool) - true if the lobby is valid and has a valid game server set; otherwise, false.
    • ip (string)
    • port (int)
    • id (int)
    • ret (bool) - true if the lobby is valid and has a valid game server set; otherwise, false.
    • ip (string)
    • port (uint32)
    • id (uint64_t)

getLobbyMemberByIndex( int steam_lobby_id, int member ) getLobbyMemberByIndex( uint64_t steam_lobby_id, int member )

  • 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 an int.

getLobbyMemberData( int steam_lobby_id, int steam_user_id, string key ) getLobbyMemberData( uint64_t steam_lobby_id, uint64_t steam_user_id, string key )

  • 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 a string. Returns NULL if steam_lobby_id is invalid, or steam_user_id is not in the lobby. Returns an empty string if key is not set for the player.

getLobbyMemberLimit( int steam_lobby_id ) getLobbyMemberLimit( uint64_t steam_lobby_id )

  • The current limit on the number of users who can join the lobby.
  • Returns an int.

getLobbyOwner( int steam_lobby_id ) getLobbyOwner( uint64_t steam_lobby_id )

  • 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 an int. Returns an uint64_t.

getNumLobbyMembers( int steam_lobby_id ) getNumLobbyMembers( uint64_t steam_lobby_id )

  • 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 SteamFriends interface.
  • Returns an int.

inviteUserToLobby( int steam_lobby_id, int steam_id_invitee ) inviteUserToLobby( uint64_t steam_lobby_id, uint64_t steam_id_invitee )

  • Invite another user to the lobby.
  • If the specified user clicks the join link, a join_requested 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 a bool.

joinLobby( int steam_lobby_id )

  • 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.
  • Triggers a lobby_joined callback for other users.
  • Returns nothing; void.

leaveLobby( int steam_lobby_id ) leaveLobby( uint64_t steam_lobby_id )

  • 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 lobby_chat_update callback.
  • Returns nothing; void.

removeFavoriteGame( int app_id, int ip, int port, int query_port, int flags ) removeFavoriteGame( uint32 app_id, uint32 ip, uint16 port, uint16 query_port, uint32 flags )

  • Removes the game server from the local favorites list.
  • Returns a bool.

requestLobbyData( int steam_lobby_id ) requestLobbyData( uint64_t steam_lobby_id )

  • 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.
  • Triggers a lobby_data_update callback.
  • Returns a bool. True if the request was successfully sent to the server. False if no connection to Steam could be made, or steam_lobby_id is invalid.

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 public (2) or invisible (3), and are set to joinable with setLobbyJoinable.
  • Triggers a lobby_match_list callback.
  • Returns nothing; void.

sendLobbyChatMsg( int steam_lobby_id, string messageBody ) sendLobbyChatMsg( uint64_t steam_lobby_id, string message_body )

  • 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 lobby_message callback with the 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.
  • Triggers a lobby_message.
  • Returns a bool.

setLobbyData( int steam_lobby_id, string key, string value ) setLobbyData( uint64_t steam_lobby_id, string key, string value )

  • 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 lobby_data_update 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 a bool. True if the data has been set successfully. False if steam_lobby_id was invalid, or the key/value are too long.

setLobbyGameServer( int steam_lobby_id, string server_ip, int server_port, int steam_id_game_server ) setLobbyGameServer( uint64_t steam_lobby_id, string server_ip, uint16 server_port, uint64_t steam_id_game_server )

  • 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 lobby_game_created callback will be sent to all players in the lobby, usually at this point, the users will join the specified game server.
  • Triggers a lobby_game_created callback.
  • Returns nothing; void.

setLobbyJoinable( int steam_lobby_id, bool joinable ) setLobbyJoinable( uint64_t steam_lobby_id, 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.
  • Lobbies with joining disabled will not be returned from a lobby search.
  • Returns a bool. True upon success; otherwise, false if you're not the owner of the lobby.

setLobbyMemberData( int steam_lobby_id, string key, string value ) setLobbyMemberData( uint64_t steam_lobby_id, 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 lobby_data_update 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.
  • Triggers a lobby_data_update callback.
  • Returns nothing; void.

setLobbyMemberLimit( int steam_lobby_id, int max_members ) setLobbyMemberLimit( uint64_t steam_lobby_id, int max_members )

  • 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 a bool.

setLobbyOwner( int steam_lobby_id, int steam_id_new_owner ) setLobbyOwner( uint64_t steam_lobby_id, uint64_t steam_id_new_owner )

  • Changes who the lobby owner is.
  • This can only be set by the owner of the lobby. This will trigger a lobby_data_update 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.
  • Triggers a lobby_data_update callback.
  • Return a bool.

setLobbyType( int steam_lobby_id, int eLobbyType )

  • 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 a bool.