Query Tutorial

Introduction

Welcome to the tutorial for QUERYClient! This section aims to give you a basic understanding on QUERYClient usage.

Basic Query Usage

mctools gives you the ability to retrieve server statistics via the Minecraft Query protocol. The Minecraft Query protocol is an implementation of the Gamespy Query protocol.

Note

While the Minecraft Query protocol was made to be compatible with the Gamespy Query protocol, we don’t recommend using QUERYClient for anything other than Minecraft. No testing has been done on other Query implementations.

Creating the Instance

First, you must create a QUERYClient instance:

from mctools import QUERYClient

query = QUERYClient('mc.server.net')

This will create a QUERYClient instance with the default configuration. All of the options can be set as you see fit, but the default configuration is recommended for most users. Query can only be used if the server has Query functionality enabled.

Note

For more information on general client configuration and instantiation, see the client tutorial.

Retrieving Statistics

Their are two types of information you can retrieve from a server: basic stats and full stats. Basic stats show host IP, port number, message of the day, ect. This is fine for most uses. Full stats shows more information about the server, such as players connected, plugins installed, ect. We will walk through the process of retrieving both.

Basic statistics

You can retrieve basic stats like so:

stats = query.get_basic_stats()

This will fetch basic server statistics and put it into a dictionary. The dictionary has the following format:

{'gametype': 'SMP',
'hostip': '127.0.0.1',
'hostport': '25565',
'map': 'world',
'maxplayers': '20',
'motd': 'Now we got business!',
'numplayers': '1'}

The gametype field is is hardcoded to ‘SMP’.

The hostip field is the host IP of the server.

The hostport field is the hostip of the server.

The map field is the name of the current map.

The maxplayers field is the maximum number of players.

The motd field is the message of the day.

The numplayers are the players connected to the server.

Full statistics

If you want to retrieve the full stats, you may do the following:

stats = query.get_full_stats()

This will fetch full server statistics and put it into a dictionary. The dictionary should have the following format:

{'game_id': 'MINECRAFT',
'gametype': 'SMP',
'hostip': '127.0.0.1',
'hostport': '25565',
'map': 'world',
'maxplayers': '20',
'motd': 'Now we got business!',
'numplayers': '1',
'players': ['MinecraftPlayer'],
'plugins': '',
'version': '1.15.2'}

The game_id field is hardcoded to ‘MINECRAFT’.

The gametype field is hardcoded to ‘SMP’.

The hostip field is the host IP of the server.

The hostport field is the port number of the server.

The map field is the name of current map.

The maxplayers field is the maximum amount of players allowed on the server.

The motd is the message of the day.

The numplayers are the number of players currently connected.

The players is a list containing the user names of all connected players.

The plugins filed contains a list of plugins used. This is not used by the vanilla server, however community servers such as Bukkit and Spigot use this value. Most servers follow this format:

[SERVER_MOD_NAME[: PLUGIN_NAME(; PLUGIN_NAME...)]]

The version field is the version of the server.

Stopping the instance

Due to the UDP protocol’s design(The protocol Query uses), the client instance does not need to be stopped. However, we still recommend stopping your client for readability, and so you can be explicit as to when your program will stop communicating over the network.

Conclusion

That concludes the tutorial on QUERYClient usage!