Difference between revisions of "Server queries"

From Valve Developer Community
Jump to: navigation, search
m (translation link)
m (oups :p)
Line 26: Line 26:
 
|-
 
|-
 
| Packet Number || [[byte]] / [[short]] || (Half-Life 1)The lower four bits represent the number of packets (2 to 15) and the upper four bits represent the current packet starting with 0.   
 
| Packet Number || [[byte]] / [[short]] || (Half-Life 1)The lower four bits represent the number of packets (2 to 15) and the upper four bits represent the current packet starting with 0.   
(Source Engine)The upper byte is the number of packets, the lower byte this current packet starting with 0.
+
(Source Engine)The lower byte is the number of packets, the upper byte this current packet starting with 0.
 
|-
 
|-
 
| Size of the Splits || [[short]] || (Source Engine)For the new version of the source engine we changed the SPLITPACKET header slightly to include at the end a short which is the size of the splits (it used to be hard coded).  In our games  a user can request a smaller packet size before a split occurs, the default is 0x04e0 which is 1248 bytes.  The query protocols, however, don't allow requesting a different split size, so the new default (1248) is what you should always see there.  So if you are querying a TF2 server you need to account for that.  A TF2 server op can also lower the max routable payload, so you can't guarantee that it'll always be 0x04e0.
 
| Size of the Splits || [[short]] || (Source Engine)For the new version of the source engine we changed the SPLITPACKET header slightly to include at the end a short which is the size of the splits (it used to be hard coded).  In our games  a user can request a smaller packet size before a split occurs, the default is 0x04e0 which is 1248 bytes.  The query protocols, however, don't allow requesting a different split size, so the new default (1248) is what you should always see there.  So if you are querying a TF2 server you need to account for that.  A TF2 server op can also lower the max routable payload, so you can't guarantee that it'll always be 0x04e0.

Revision as of 15:33, 18 January 2008

You can query information from a running game server using UDP/IP packets. This document describes the packet formats and protocol to access this data.

Basic Data Types

All server queries consist of 5 basic types of data packed together into a data stream. All types are little endian, so no conversion is needed on x86 CPUs.

Name Description
byte 8 bit character
short 16 bit signed integer
long 32 bit signed integer
float 32 bit float value
string variable length byte field, terminated by 0x00

Protocol

Steam uses a packet size of 1400 bytes + IP/UDP headers. If a request or response needs more packets for the data it starts the packets with an additional header in the following format:

Data Type Comment
Type long -2 (0xFFFFFFFE) to indicate that data is split over several packets
Request ID long The server assigns a unique number to each split packet. (Source Engine only) If the top bit of the request ID is set then this packet has been compressed with the BZip2 algorithm before being split, after you get all the pieces you need to uncompress it with BZ2_bzBuffToBuffDecompress() before reading the raw data.
Packet Number byte / short (Half-Life 1)The lower four bits represent the number of packets (2 to 15) and the upper four bits represent the current packet starting with 0.

(Source Engine)The lower byte is the number of packets, the upper byte this current packet starting with 0.

Size of the Splits short (Source Engine)For the new version of the source engine we changed the SPLITPACKET header slightly to include at the end a short which is the size of the splits (it used to be hard coded). In our games a user can request a smaller packet size before a split occurs, the default is 0x04e0 which is 1248 bytes. The query protocols, however, don't allow requesting a different split size, so the new default (1248) is what you should always see there. So if you are querying a TF2 server you need to account for that. A TF2 server op can also lower the max routable payload, so you can't guarantee that it'll always be 0x04e0.


If the packet is compressed, there are two extra fields in the first packet.

Data Type Comment
Type integer Number of bytes the data uses after decompression;
Type integer CRC32 checksum of the uncompressed data for validation.

Because UDP packets can arrive in different order or delayed, every packet should be verified by its Request ID and the Packet Number! Every request or response with or without this header is continued with an integer -1 (0xFFFFFFFF) and the user data.
So by reading the first 4 bytes you can decide whether the data is split (-2) or in one packet (-1).

Query Types

The server responds to 4 queries:

  • A2S_SERVERQUERY_GETCHALLENGE - Returns a challenge number for use in the player and rules query.
  • A2S_INFO - Basic information about the server.
  • A2S_PLAYER - Details about each player on the server.
  • A2S_RULES - The rules the server is using.

Queries should be sent in UDP packets to the listen port of the server, which is typically port 27015.

A2S_SERVERQUERY_GETCHALLENGE

Request format

Challenge values are required for A2S_PLAYER and A2S_RULES requests, you can use this request to get one.

Note:You can also send A2S_PLAYER and A2S_RULES queries with a challenge value of -1 (0xFF FF FF FF) and they will respond with a challenge value to use (using the reply format below).
FF FF FF FF 57

Reply format

Data Type Comment
Type byte Should be equal to 'A' (0x41)
Challenge long The challenge number to use

Example reply:

FF FF FF FF 41 32 42 59 45

A2S_INFO

Request format

Server info can be requested by sending the following byte values in a UDP packet to the server.

FF FF FF FF 54 53 6F 75 72 63 65 20 45 6E 67 69   ÿÿÿÿTSource Engi
6E 65 20 51 75 65 72 79 00                        ne Query

i.e. -1 (int), 'T' (byte), "Source Engine Query" (string)

Reply format

Source servers

Data Type Comment
Type byte Should be equal to 'I' (0x49)
Version byte Network version. 0x07 is the current Steam version.
Server Name string The Source server's name, eg: "Recoil NZ CS Server #1"
Map string The current map being played, eg: "de_dust"
Game Directory string The name of the folder containing the game files, eg: "cstrike"
Game Description string A friendly string name for the game type, eg: "Counter Strike: Source"
AppID short Steam Application ID
Number of players byte The number of players currently on the server
Maximum players byte Maximum allowed players for the server
Number of bots byte Number of bot players currently on the server
Dedicated byte 'l' for listen, 'd' for dedicated, 'p' for SourceTV
OS byte Host operating system. 'l' for Linux, 'w' for Windows
Password byte If set to 0x01, a password is required to join this server
Secure byte if set to 0x01, this server is VAC secured
Game Version string The version of the game, eg: "1.0.0.22"

Example reply:

FF FF FF FF 49 02 67 61 6D 65 32 78 73 2E 63 6F    ÿÿÿÿI.game2xs.co
6D 20 43 6F 75 6E 74 65 72 2D 53 74 72 69 6B 65    m Counter-Strike
20 53 6F 75 72 63 65 20 23 31 00 64 65 5F 64 75     Source #1.de_du
73 74 00 63 73 74 72 69 6B 65 00 43 6F 75 6E 74    st.cstrike.Count
65 72 2D 53 74 72 69 6B 65 3A 20 53 6F 75 72 63    er-Strike: Sourc
65 00 F0 00 05 10 04 64 6C 00 00 31 2E 30 2E 30    e......dl..1.0.0
2E 32 32 00                                        .22.

The Ship servers

Data Type Comment
Type byte Should be equal to 'I' (0x49)
Version byte Network version. 0x07 is the current Steam version.
Server Name string The Source server's name, eg: "Xtra The Ship #1 [Hunt]"
Map string The current map being played, eg: "batavier"
Game Directory string The name of the folder containing the game files, eg: "ship"
Game Description string A friendly string name for the game type, eg: "The Ship"
AppID short Steam Application ID
Number of players byte The number of players currently on the server
Maximum players byte Maximum allowed players for the server
Number of bots byte Number of bot players currently on the server
Dedicated byte 'l' for listen, 'd' for dedicated, 'p' for SourceTV
OS byte Host operating system. 'l' for Linux, 'w' for Windows
Password byte If set to 0x01, a password is required to join this server
Secure byte if set to 0x01, this server is VAC secured
Game Mode byte 0x00 for Hunt, 0x01 for Elimination, 0x02 for Duel, 0x03 for Deathmatch, 0x04 for Team VIP, 0x05 for Team Elimination
Witness Count byte The minimum number of witnesses for a player to be arrested.
Witness Time byte Time in seconds before player is arrested while being witnessed.
Game Version string The version of the game, eg: "1.0.0.14"

Example reply:

FF FF FF FF 49 07 53 68 69 70 20 53 65 72 76 65    ÿÿÿÿI.Ship Serve
72 00 62 61 74 61 76 69 65 72 00 73 68 69 70 00    r.batavier.ship.
54 68 65 20 53 68 69 70 00 60 09 01 05 00 6C 77    The Ship.`....lw
00 00 01 03 03 31 2E 30 2E 30 2E 34 00             .....1.0.0.4.

Goldsource servers

Data Type Comment
Type byte Should be equal to 'm' (0x6D)
Game IP string Game Server IP address and port
Server Name string The server's name, eg: "Recoil NZ CS Server #1"
Map string The current map being played, eg: "de_dust"
Game Directory string The name of the folder containing the game files, eg: "cstrike"
Game Description string A friendly string name for the game type, eg: "Counter-Strike"
Number of players byte The number of players currently on the server
Maximum players byte Maximum allowed players for the server
Version byte Network version. 0x07 is the current Steam version.
Dedicated byte 'l' for listen, 'd' for dedicated, 'p' for HLTV
OS byte Host operating system. 'l' for Linux, 'w' for Windows
Password byte If set to 0x01, a password is required to join this server
IsMod byte If set to 0x01, this byte is followed by ModInfo
Secure byte if set to 0x01, this server is VAC secured
Number of bots byte Number of bot players currently on the server
ModInfo
Data Type Comment
URLInfo string URL containing information about this mod
URLDL string URL to download this mod
Nul byte 0x00
ModVersion long Version of the installed mod
ModSize long The download size of this mod
SvOnly byte If 1 this is a server side only mod
ClDLL byte If 1 this mod has a custom client dll

SiN 1 Multiplayer servers

SiN 1 Multiplayer servers respond to the "Source Engine Query" request. Their reply is in the same format as Source's.

Example reply:

FF FF FF FF 49 2F 53 65 6E 73 65 6D 61 6E 6E 20    ÿÿÿÿI/Sensemann 
53 69 4E 20 44 4D 00 70 61 72 61 64 6F 78 00 53    SiN DM.paradox.S
69 4E 20 31 00 53 69 4E 20 31 00 1D 05 00 10 00    iN 1.SiN 1......
6C 77 00 00 31 2E 30 2E 30 2E 30 00                lw..1.0.0.0.

Rag Doll Kung Fu servers

Rag Doll Kung Fu servers respond to the "Source Engine Query" request. Their reply is in the same format as Source's. Example reply:

FF FF FF FF 49 FC 54 68 65 20 44 75 64 65 27 73     ÿÿÿÿIüThe Dude's
20 64 6F 6A 6F 00 53 6F 63 63 65 72 00 52 44 4B      dojo.Soccer.RDK
46 53 6F 63 63 65 72 00 52 61 67 44 6F 6C 6C 4B     FSoccer.RagDollK
75 6E 67 46 75 3A 20 53 6F 63 63 65 72 00 EA 03     ungFu: Soccer.ê.
01 04 00 00 77 00 00 32 2E 33 2E 30 2E 30 00        ....w..2.3.0.0.

A2S_PLAYER

Request format

FF FF FF FF 55 <4 byte challenge number>

The challenge number can either be set to -1 (0xFF FF FF FF) to have the server reply with S2C_CHALLENGE, or use the value from a previous A2S_SERVERQUERY_GETCHALLENGE request.

Reply format

The players response has two sections, the initial header:

Data Type Comment
Type byte Should be equal to 'D' (0x44)
Num Players byte The number of players reported in this response

Then for each player the following fields are sent:

Data Type Comment
Index byte The index into [0.. Num Players] for this entry
Player Name string Player's name
Kills long Number of kills this player has
Time connected float The time in seconds this player has been connected


Note: Java users can read the player score as an int and reverse the bytes with Integer.reverseBytes(int i).

A2S_RULES

Request format

FF FF FF FF 56 <4 byte challenge number>

The challenge number can either be set to -1 (0xFF FF FF FF) to have the server reply with S2C_CHALLENGE, or use the value from a previous A2S_SERVERQUERY_GETCHALLENGE request.

Reply format

The rules response has two sections, the initial header:

Data Type Comment
Type byte Should be equal to 'E' (0x45)
Num Rules short The number of rules reported in this response

Then for each rule the following fields are sent:

Data Type Comment
Rule Name string The name of the rule
Rule Value string The rule's value

See Also

Template:Otherlang:en Template:Otherlang:en:fr