A2S Service

Contents

This feature is available on the Photon Bolt Pro version.

Monitoring your game servers is one of the main tasks after your game is launched, in order to get analytics data, downtime, number of players and so on. For this reason, Photon Bolt has a built-in implementation of the Server Query Protocol, also known as the A2S Protocol, created by Valve, that was first introduced on Half-Life servers.

The protocol is a simple serialization protocol created to retrieve information from the game server while it's running, such as:

  1. Current player count;
  2. Current map or loaded scene;
  3. Set of rules applied to the game, like game mode;
  4. Information about the game session, among others.

The A2S Protocol is fully described on the developers' site from Valve, with a description of all data types, the query procedure, and capabilities of the protocol. Here is the link for the main documentation: https://developer.valvesoftware.com/wiki/Server_queries. You can also find more information about the protocol here.

Using The Photon Bolt A2S Service

Before start using the protocol, you must be sure that it's enabled and running on your game server. On the Bolt Settings window, on the Miscellaneous section, you will find the options to configure the service. It's possible to enable/disable the background service and also configure the port where the data will be served.

A2S Service Enable
A2S Service Enable.

Enabling the service is all you need to set up the basic its usage. Internally, Photon Bolt will fill part of the information about your game server:

  1. Max players;
  2. Current player count;
  3. Game Host Operating System;
  4. Initial Game Scene;
  5. Company Name;
  6. Product Name;
  7. Game Server version;

In order to modify or complete this information, it's provided an API that can be used to fill the remaining pieces of data. You can access this API through the class Bolt.a2s.A2SManager, with the following methods:

  1. SetServerRules: Add or update server rules. This is a key/value pair of arbitrary data that can be associated with the server and is public to any requesting client;
  2. RemoveServerRule: Remove a server rules;
  3. UpdateServerInfo: Used to update all server information, like Game Name or server version;
  4. SetPlayerInfo: Using this method, you can update data related to the players connected to this game server, like it's ID or Score.

Here it's presented a sample code using this API:

using Bolt.a2s;

[BoltGlobalBehaviour(BoltNetworkModes.Server)]
public class ServerQueryManager : Bolt.GlobalEventListener
{
    void Awake()
    {
        DontDestroyOnLoad(gameObject);
    }

    public override void BoltStartDone()
    {
        // Configure new rules of the server after Bolt starts
        A2SManager.SetServerRules("rule1", "value1");
        A2SManager.SetServerRules("rule2", "value2");
    }

    public override void SceneLoadLocalDone(string map)
    {
        // For the Server Player, you can pass null as BoltConnection
        A2SManager.SetPlayerInfo(null, "Photon Server");

        // Update the Game Server metadata
        A2SManager.UpdateServerInfo(
            gameName: "Bolt Simple Tutorial",
            serverName: "Photon Bolt Server",
            map : map,
            version: "1.0",
            serverType : ServerType.Listen,
            visibility : Visibility.PUBLIC
        );
    }

    public override void SceneLoadRemoteDone(BoltConnection connection)
    {
        // When remote clients finish loading scene
        // you can configure it's metadata
        A2SManager.SetPlayerInfo(connection, "Conn: " + connection.ConnectionId.ToString(), 0);
    }
}

Back To Top

Tools To Retrieve Server Information

All data that is set using the API is stored in memory and can be retrieved by any tool capable of creating A2S Queries. One of the well-known tools for this purpose is called qstat and is the most simple way to retrieve the server info.

The qstat is a command-line tool that can be installed on most of the operating systems. You can find information about how to download and install it on the official Github repository. In the following, it's shown the basic usage of the program to get metadata associated with the game server:

$ qstat -R -P -xml -a2s localhost:21777
  • -R: fetch and display server rules;
  • -P: fetch and display player info;
  • -xml: output status data as an XML document;
  • -a2s: query server using the A2S protocol.

After the call, you will receive on the console an output similar to the one shown below:

<?xml version="1.0" encoding="iso-8859-1"?>
<qstat>
    <server type="A2S" address="localhost:21777" status="UP">
        <hostname>localhost:21777</hostname>
        <name>Photon Bolt Server</name>
        <gametype></gametype>
        <map>Tutorial1</map>
        <numplayers>1</numplayers>
        <maxplayers>32</maxplayers>
        <ping>11</ping>
        <retries>0</retries>
        <rules>
            <rule name="protocol">1</rule>
            <rule name="gamedir"></rule>
            <rule name="gamename">Bolt Simple Tutorial</rule>
            <rule name="dedicated">1</rule>
            <rule name="sv_os">m</rule>
            <rule name="version">1.0</rule>
            <rule name="rule1">value1</rule>
            <rule name="rule2">value2</rule>
        </rules>
        <players>
        </players>
    </server>
</qstat>

As you can see, the information is well structured and can easily be used to maintain analytical data of the servers of your game. This is just the most simple usage of the tool, there are several other options included, like scanning for many different servers or show the info on a formatted table, for example.

Other examples of tools to use the Server Queries service:

  1. Python-valve: is a Python library which intends to provide an all-in-one interface to various Valve products and services, including A2S server queries. Link.
  2. source-query-net: .NET library to query information from game servers using the source query protocol. Link.

To Document Top