The Server Query Protocol (SQP) allows clients to retrieve information about a running game server using UDP/IP packets.A client initiates queries by sending a
ChallengeRequest
to the server. In response, the server sends a
ChallengeResponse
that includes a
ChallengeId
. After the client receives the
ChallengeResponse
, it can continue to query the server for information.The following sections describe the technical specifications of SQP, including data types, request types, and packet formats.Game server state information that SQP supports includes:
Server name: The name of the game server.
Build ID: The identifier of the game image the game server is running.
Current players: The current number of connected players.
Max players: The maximum number of players that can join the game server.
IP address: The IP address of the machine the game server is hosted on.
Port: The port of the game server by which clients can connect to the specific game server on the host machine.
Game type: The game that the game server is running.
Map: The game map that's currently loaded on the game server.
Note: SQP works with the Clanforge game server monitoring process to make sure reports by the game server match the information in Clanforge’s database.
Requirements
Before implementing SQP as the game server query protocol, you must populate the
ServerInfoData
object with all the game server information on the game client end. This ensures the game server reports the correct information.
Reference implementation
Refer to go-svrquery for an example implementation of SQP. go-svrquery is a Golang client or talking to game servers using various query protocols, including SQP.
Data types
All server queries consist of five basic types of data packed together into a data stream. The following table describes each of these types. All types are big-endian.
Name
Description
byte
An 8-bit character or an unsigned integer.
ushort
A 16-bit unsigned integer.
uint
A 32-bit unsigned integer.
ulong
A 64-bit unsigned integer.
string
A variable-length byte field, encoded in UTF-8, and prefixed with a byte containing the length of the string. Strings are limited to 255 bytes.
Request types
A client can make five types of requests to a server. The following table specifies the response a client should expect from the server for each request type.
Request
Response
ChallengeRequest
The server returns a challenge number for the client to use in query request responses.
QueryRequest
with
ServerInfo
chunk
The server returns basic information about the server, for example, the current number of players, the max players, the game type, and the build ID.
Packet types
The following table has the distinct types of SQP packets.
Packet type
Byte value
ChallengeRequest
0
ChallengeResponse
0
QueryRequest
1
QueryResponse
1
Headers
All SQP packets, whether they're a request or a response, contain a header with the following data.
Data
Type
Comment
Type
byte
Has the packet type. Refer to Packet types.
ChallengeToken
uint
The
ChallengeToken
has the challenge number. The challenge number is required for
QueryRequest
and
QueryResponse
packet types. Refer to Challenge numbers.
Payload
N/A
Has the body of the packet (if the packet has a body).
Challenge numbers
SQP uses a challenge number, which is a random 32-bit integer, to ensure the client making query requests is the same client that received the challenge number.When a client first sends a request to a server, the server randomly selects the challenge number and includes it in the packet header. The client must then include the same challenge number in the header of all following requests.
Challenge packets
Clients can use challenge packets to retrieve a usable challenge number for a following request.
Note: Challenge packets only have a header. There is no payload.
Clients can send query packets to retrieve information about a server. Clanforge only requires game servers to respond to queries with
ServerInfo
chunks. You can use the other request types but they're not necessary for Clanforge.
Chunk types
There are four different types of chunks that clients can request with a query packet. However, this documentation only includes the
ServerInfo
chunk type since it's the only one Clanforge supports.The byte value of each chunk type indicates the response chunk that the requesting client expects. When a server receives a query packet, it inspects the
RequestedChunks
field in the request and performs a bitwise
AND
operation using the byte value of the chunk type. The server knows a chunk type has been requested if the result of this operation is greater than zero.For example, the server responds with a
ServerInfo
chunk if
RequestedChunks&1 > 0
. Refer to note below.
Note: Although there are four types of chunk types available in the SQP protocol, Clanforge only supports the
ServerInfo
chunk type.
Example RequestedChunk
Meaning
Checks
00000001
ServerInfo
RequestedChunks & 0x01 > 0
00000010
Reserved
RequestedChunks & 0x02 > 0
00000100
Reserved
RequestedChunks & 0x04 > 0
00000010
Reserved
RequestedChunks & 0x08 > 0
Note:
RequestedChunks
can request more than one chunk at the same time, so your implementation must be able to perform the correct bitwise checks on the
RequestedChunks
value.
Request format
The request format is the same for all query requests.
Note: Clanforge only requires a server to respond to
ServerInfo
requests. Therefore, all other request types are omitted.