QueryServer

QueryServer is a PocketMine-MP plugin that queries another server from the console or through a callback API for plugins.

The command and API use the external Minecraft server status API when no separate port is supplied. A host with a port can fall back to a UDP query if the HTTP lookup fails. Supplying the port as a separate API argument or command argument uses UDP directly. The bundled libpmquery implementation handles the basic UDP response, and a second UDP request attempts to obtain the optional full stat.

Requirements and compatibility

• plugin.yml declares PocketMine-MP API 5.0.0 and the code requires PHP 8.1 or newer.
• Static analysis targets Axolotl-PM 5 API. Runtime compatibility across the 5.x line has not yet been established. See the build workflow for the exact revision tested in CI.
• Plugins calling the API must depend on the QueryServer plugin so its instance is loaded first.

Install and use

Build a plugin PHAR with DevTools, then place the verified PHAR in the server's plugins directory. The console command requires the queryserver.cmd permission, which defaults to operators.

/query example.org
/query example.org:19132
/query example.org 19132

The first two forms try the HTTP status API, with UDP fallback available for the address containing a port. The third form uses UDP directly. Query results depend on the remote server's query settings and network access.

Another plugin can depend on QueryServer and call its API after both plugins load:

use NhanAZ\QueryServer\Main;

Main::getInstance()->getApi()->query("example.org", 19132, function (array $result): void {
    if (($result["ok"] ?? false) !== true) {
        // Inspect $result["error"].
        return;
    }

    // $result["source"] identifies "udp" or "api".
    // $result["data"] is a UDP array or HTTP status object.
});

The example consumer shows plugin dependency and command wiring. Its /qtest [host] [port] command accepts a separate host and UDP port for local testing; without arguments, it uses the public test server. A callback is delivered once after success or the final failure. Keep the callback lightweight because it runs when the asynchronous task completes on the server thread.

Build and verify

The build workflow runs PHPStan at maximum level, PHP lint, callback and loopback UDP fixtures, and DevTools PHAR builds for both the plugin and its example consumer. It verifies PHAR contents and SHA-256 digests before uploading the plugin artifact. The UDP fixture checks ping parsing and malformed replies against a local responder; it does not establish reachability of public servers. A CI artifact is a test result, not a stable release.

The repository also contains historical virion.yml and Poggit metadata. The public API currently depends on a loaded plugin instance, so the source should not be presented as a standalone virion. No current standalone virion release is offered.

License and upstream

The root LICENSE contains GPL-3.0 text. The bundled libpmquery files carry LGPL-3.0-or-later notices, with its license text also included in the PHAR. The composer.json and virion.yml license declarations currently differ from the root license. This discrepancy needs a provenance and rights review before a stable release or standalone virion distribution.

The repository history helps locate the discrepancy: commit 66d5565 added the root GPL text in 2021; commit 7bba7be brought in a contributor's query implementation in 2023; commit bf78f5f added the bundled libpmquery code and notice in 2026; and commit e117469 added the LGPL declaration to virion metadata without changing the root license. These commits identify the files and contributors to review; they do not by themselves resolve the rights question.

Report issues through GitHub Issues or NhanAZ Discord.