Matchmaking Servers

Functions which provide access to the game server browser. See Game Servers for more information.

Only available in the main GodotSteam branches

Functions

cancelQuery

cancelQuery( uint64_t server_list_request = 0 )

Parameter	Type	Notes
server_list_request	uint64_t	The handle to the server list request. Defaults to 0.

Cancel an outstanding server list request.

You should call this to cancel any in-progress requests before destructing a callback object that may have been passed to one of the below request calls. Not doing so may result in a crash when a callback occurs on the destructed object. Canceling a query does not release the allocated request handle. The request handle must be released using releaseRequest.

You can pass a server_list_request handle or, if you do not, it will use the last internally stored one.

Returns: void

cancelServerQuery

cancelServerQuery( int server_query )

Parameter	Type	Notes
server_query	int	The server query to cancel.

Cancel an outstanding individual server query.

The calls that create this type of query are: pingServer, playerDetails, and serverRules. You should call this to cancel any in-progress requests before destructing a callback object that may have been passed to one of the above calls to avoid crashing when callbacks occur.

Returns: void

getServerCount

getServerCount( uint64_t server_list_request = 0 )

Parameter	Type	Notes
server_list_request	uint64_t	The handle to the server list request. Defaults to 0.

Gets the number of servers in the given list. This is used for iterating with getServerDetails.

You can pass a server_list_request handle or, if you do not, it will use the last internally stored one.

Returns: int

The number of servers in a server list request object. Returns 0 if server_list_request is invalid.

getServerDetails

getServerDetails( int server, uint64_t server_list_request = 0 )

Parameter	Type	Notes
server	int	The index of the server to get the details of, from 0 to getServerCount.
server_list_request	uint64_t	The handle to the server list request. Defaults to 0.

Get the details of a given server in the list.

You can get the valid range of index values by calling getServerCount. You will also receive index values in request_server_list_server_responded callbacks.

You can pass a server_list_request handle or, if you do not, it will use the last internally stored one.

Returns: dictionary

Contains the following keys:

Key	Type	Notes
ping	int	Current ping time in milliseconds.
success_response	bool	Server has responded successfully in the past.
no_refresh	bool	Server is marked as not responding and should no longer be refreshed.
game_dir	string	Current game directory.
map	string	Current map.
description	string	Game description.
app_id	uint32_t	Steam App ID of this server.
players	int	Total number of players currently on the server; includes bots.
max_players	int	Maximum players that can join this server.Number of bots (i.e simulated players) on this server.
bot_players	int	Number of bots; ie.simulated players) on this server.
password	bool	True if this server needs a password to join.
secure	bool	Is this server protected by VAC.
last_played	uint32_t	Time (in unix time) when this server was last played on (for favorite/history servers).
server_version	int	Server version as reported to Steam.

isRefreshing

isRefreshing( uint64_t server_list_request = 0 )

Parameter	Type	Notes
server_list_request	uint64_t	The handle to the server list request. Defaults to 0.

Checks if the server list request is currently refreshing.

You can pass a server_list_request handle or, if you do not, it will use the last internally stored one.

Returns: bool

Returns true if server_list_request is valid and is currently refreshing; otherwise, false.

pingServer

pingServer( string ip, uint16 port )

Parameter	Type	Notes
ip	string	The IP of the game server you are querying in host order.
port	uint16	The port of the game server you are querying, in host order.

Queries an individual game server directly via IP/Port to request an updated ping time and other details from the server.

Returns: int

Handle to the outstanding server query.

playerDetails

playerDetails( string ip, uint16 port )

Parameter	Type	Notes
ip	string	The IP of the game server you are querying in host order.
port	uint16	The port of the game server you are querying, in host order.

Queries an individual game server directly via IP/Port to request the list of players currently playing on the server.

Returns: int

Handle to the outstanding server query.

refreshQuery

refreshQuery( uint64_t server_list_request = 0 )

Parameter	Type	Notes
server_list_request	uint64_t	The handle to the server list request. Defaults to 0.

Ping every server in your list again but don't update the list of servers.

The query callback installed when the server list was requested will be used again to post notifications and request_server_list_refresh_complete will be called again, so the callback must remain valid until it completes or the request is released with releaseRequest.

You can pass a server_list_request handle or, if you do not, it will use the last internally stored one.

Returns: void

No notes.

refreshServer

refreshServer( int server, uint64_t server_list_request = 0 )

Parameter	Type	Notes
server	int	The index of the server to get the details of, from 0 to getServerCount.
server_list_request	uint64_t	The handle to the server list request. Defaults to 0.

Refreshes a single server inside of a query.

If you want to refresh all of the servers then you should use refreshQuery.

You can pass a server_list_request handle or, if you do not, it will use the last internally stored one.

Returns: void

No notes.

releaseRequest

releaseRequest( uint64_t server_list_request = 0 )

Parameter	Type	Notes
server_list_request	uint64_t	The asynchronous server list request object to release. Defaults to 0.

Releases the asynchronous server list request object and cancels any pending query on it if there's a pending query in progress.

You can pass a server_list_request handle or, if you do not, it will use the last internally stored one.

Returns: void

No notes.

requestFavoritesServerList

requestFavoritesServerList( uint32_t app_id, array filters )

Parameter	Type	Notes
app_id	uint32_t	The app to get the server list of.
filters	array	An array of filters to only retrieve servers the user cares about.

Request a new list of game servers from the 'favorites' server list. This request object must be released by calling releaseRequest when you are done using it.

See MatchMakingKeyValuePair_t for more information.

Returns: uint64_t

A new asynchronous server list request object.

requestFriendsServerList

requestFriendsServerList( uint32_t app_id, array filters )

Parameter	Type	Notes
app_id	uint32_t	The app to get the server list of.
filters	array	An array of filters to only retrieve servers the user cares about.

Request a new list of game servers from the 'friends' server list. This request object must be released by calling releaseRequest when you are done using it.

See MatchMakingKeyValuePair_t for more information.

Returns: uint64_t

A new asynchronous server list request object.

requestHistoryServerList

requestHistoryServerList( uint32_t app_id, array filters )

Parameter	Type	Notes
app_id	uint32_t	The app to get the server list of.
filters	array	An array of filters to only retrieve servers the user cares about.

Request a new list of game servers from the 'history' server list. This request object must be released by calling releaseRequest when you are done using it.

See MatchMakingKeyValuePair_t for more information.

Returns: uint64_t

A new asynchronous server list request object.

requestInternetServerList

requestInternetServerList( uint32_t app_id, array filters )

Parameter	Type	Notes
app_id	uint32_t	The app to get the server list of.
filters	array	An array of filters to only retrieve servers the user cares about.

Request a new list of game servers from the 'internet' server list. This request object must be released by calling releaseRequest when you are done using it.

See MatchMakingKeyValuePair_t for more information.

Returns: uint64_t

This returns a new asynchronous server list request object.

Triggers

lobby_chat_update callback

requestLANServerList

requestLANServerList( uint32_t app_id )

Parameter	Type	Notes
app_id	uint32_t	The app to get the server list of.

Request a new list of game servers from the 'LAN' server list. This request object must be released by calling releaseRequest when you are done using it.

See MatchMakingKeyValuePair_t for more information.

Returns: uint64_t

A new asynchronous server list request object.

requestSpectatorServerList

requestSpectatorServerList( uint32_t app_id, array filters )

Parameter	Type	Notes
app_id	uint32_t	The app to get the server list of.
filters	array	An array of filters to only retrieve servers the user cares about.

Request a new list of game servers from the 'spectator' server list. This request object must be released by calling releaseRequest when you are done using it.

See MatchMakingKeyValuePair_t for more information.

Returns: uint64_t

A new asynchronous server list request object.

serverRules

serverRules( string ip, uint16 port )

Parameter	Type	Notes
ip	string	The IP of the game server you are querying in host order.
port	uint16	The port of the game server you are querying, in host order.

Queries an individual game server directly via IP/Port to request the list of rules that the server is running. See setKeyValue to set the rules on the server side.

Returns: int

Handle to the outstanding server query.

Signals

These callbacks require you to setup one of the three callback methods to receive them.

ping_server_failed_to_respond

The server has failed to respond to a ping request.

Returns

Nothing.

ping_server_responded

The server has responded to a ping request.

Returns

Key	Type	Notes
server_details	dictionary	Data about the server.

server_details contains the following keys:

Key	Type	Notes
name	string	Game server name.
connection_address	string	IP / connection port for this server.
query_address	string	IP / query port for this server.
ping	int	Current ping time in milliseconds.
success_response	bool	Server has responded successfully in the past.
no_refresh	bool	Server is marked as not responding and should no longer be refreshed.
game_dir	string	Current game directory.
map	string	Current map.
description	string	Game description.
app_id	uint32_t	Steam App ID of this server.
players	int	Total number of players currently on the server; includes bots.
max_players	int	Maximum players that can join this server.Number of bots (i.e simulated players) on this server.
bot_players	int	Number of bots; ie.simulated players) on this server.
password	bool	True if this server needs a password to join.
secure	bool	Is this server protected by VAC.
last_played	uint32_t	Time (in unix time) when this server was last played on (for favorite/history servers).
server_version	int	Server version as reported to Steam.
game_tags	string	The tags this server exposes.
steam_id	uint64_t	The Steam ID of the game server; invalid if it doesn't have one. Old server or not connected to Steam.

player_details_failed_to_respond

The server failed to respond to a player details request.

Returns

Nothing.

player_details_player_added

The server has responded to a player details request.

Returns

Key	Type	Notes
name	string	The name of the player added.
score	int	The score this player had.
time_played	float	The amount of time played.

player_details_refresh_complete

The server has completed a player details request.

Returns

Nothing.

request_server_list_refresh_complete

A server list request has completed.

Returns

Key	Type	Notes
request_handle	uint64_t	The handle for the request.
response	MatchMakingServerResponse enum	The server response result.

request_server_list_server_failed_to_respond

A server failed to respond to a list request.

Returns

Key	Type	Notes
request_handle	uint64_t	The handle for the request.
server	int	The handle for the server.

request_server_list_server_responded

A server has responded to a list request.

Returns

Key	Type	Notes
request_handle	uint64_t	The handle for the request.
server	int	The handle for the server.

server_rules_failed_to_respond

The server failed to respond with a rules request.

Returns

Nothing.

server_rules_refresh_complete

The server has completed a rules refresh.

Returns

Nothing.

server_rules_responded

The server responded with a rules request.

Returns

Key	Type	Notes
rule	string	The name of the rule.
value	string	The value of that rule.

Constants

Name	SDK Name	Value	Details
MAX_GAME_SERVER_GAME_DATA	k_cbMaxGameServerGameData	2048	-
MAX_GAME_SERVER_GAME_DESCRIPTION	k_cbMaxGameServerGameDescription	64	-
MAX_GAME_SERVER_GAME_DIR	k_cbMaxGameServerGameDir	32	-
MAX_GAME_SERVER_MAP_NAME	k_cbMaxGameServerMapName	32	-
MAX_GAME_SERVER_NAME	k_cbMaxGameServerName	64	-
MAX_GAME_SERVER_TAGS	k_cbMaxGameServerTags	128	-

Enums

MatchMakingServerResponse

Enumerator	SDK Name	Value	Notes
SERVER_RESPONDED	eServerResponded	0	-
SERVER_FAILED_TO_RESPOND	eServerFailedToRespond	1	-
NO_SERVERS_LISTED_ON_MASTER_SERVER	eNoServersListedOnMasterServer	2	For the Internet query type; returned in response callback if no servers of this type match.