Querying the Source Master Server¶
When a Source server starts it can optionally add it self to an index of live servers to enable players to find the server via matchmaking and the in-game server browsers. It does this by registering it self with the “master server”. The master server is hosted by Valve but the protocol used to communicate with it is reasonably well documented.
Clients can request a list of server addresses from the master server for
a particular region. Optionally, they can also specify a filtration criteria
to restrict what servers are returned. valve.source.master_server
provides an interface for interacting with the master server.
Note
Although “master server” is used in a singular context there are in fact
multiple servers. By default
valve.source.master_server.MasterServerQuerier
will lookup
hl2master.steampowered.com
which, at the time of writing, has three
A
entries.
valve.source.master_server¶
-
class
valve.source.master_server.
MasterServerQuerier
(address=(u'hl2master.steampowered.com', 27011), timeout=10.0)¶ Implements the Source master server query protocol
https://developer.valvesoftware.com/wiki/Master_Server_Query_Protocol
-
__iter__
()¶ An unfitlered iterator of all Source servers
This will issue a request for an unfiltered set of server addresses for each region. Addresses are received in batches but returning a completely unfiltered set will still take a long time and be prone to timeouts.
See
find()
for making filtered requests.
-
find
(region=u'all', **filters)¶ Find servers for a particular region and set of filtering rules
This returns an iterator which yields
(host, port)
server addresses from the master server.region
spcifies what regions to restrict the search to. It can either be aREGION_
constant or a string identifying the region. Alternately a list of the strings orREGION_
constants can be used for specifying multiple regions.The following region identification strings are supported:
String Region(s) na-east East North America na-west West North America na East North American, West North America sa South America eu Europe as Asia, the Middle East oc Oceania/Australia af Africa rest Unclassified servers all All of the above Note
“
rest
” corresponds to all servers that don’t fit with any other region. What causes a server to be placed in this region by the master server isn’t entirely clear.The region strings are not case sensitive. Specifying an invalid region identifier will raise a ValueError.
As well as region-based filtering, alternative filters are supported which are documented on the Valve developer wiki.
https://developer.valvesoftware.com/wiki/Master_Server_Query_Protocol#Filter
This method accepts keyword arguments which are used for building the filter string that is sent along with the request to the master server. Below is a list of all the valid keyword arguments:
Filter Description type Server type, e.g. “dedicated”. This can be a ServerType
instance or any value that can be converted to aServerType
.secure Servers using Valve anti-cheat (VAC). This should be a boolean. gamedir A string specifying the mod being ran by the server. For example: tf
,cstrike
,csgo
, etc..map Which map the server is running. linux Servers running on Linux. Boolean. empty Servers which are not empty. Boolean. full Servers which are full. Boolean. proxy SourceTV relays only. Boolean. napp Servers not running the game specified by the given application ID. E.g. 440
would exclude all TF2 servers.noplayers Servers that are empty. Boolean white Whitelisted servers only. Boolean. gametype Server which match all the tags given. This should be set to a list of strings. gamedata Servers which match all the given hidden tags. Only applicable for L4D2 servers. gamedataor Servers which match any of the given hidden tags. Only applicable to L4D2 servers. Note
Your mileage may vary with some of these filters. There’s no real guarantee that the servers returned by the master server will actually satisfy the filter. Because of this it’s advisable to explicitly check for compliance by querying each server individually. See
valve.source.a2s
.
-
Example¶
In this example we will list all European and Asian Team Fortress 2 servers running the map ctf_2fort and print out their addresses.
import valve.source.server
import valve.source.master_server
msq = valve.source.master_server.MasterServerQuerier()
try:
for address in msq.find(region=["eu", "as"],
gamedir="tf",
map="ctf_2fort"):
print "{0}:{1}".format(*address)
except valve.source.server.NoResponseError:
print "Master server request timed out!"