Sends a server list ping packet to Minecraft servers
Usage:
require('minecraft-ping').ping_fe01fa({host:'localhost', port:25565}, function(err, response) {
console.log(err, response);
});
Several pings are supported. Version compatibility:
| Minecraft Version | ping_fe01fa | ping_fe01 | ping_fe | Netty status ping(*) |
|---|---|---|---|---|
| 1.9 | YES | YES | Limited | YES |
| 1.8.9 | YES | YES | Limited | YES |
| 1.7.10 | YES | YES | Limited | YES |
| 1.6.4 | YES | Slow | Limited, Slow | NO |
| 1.5.2 | YES | YES | Limited, Slow | NO |
| 1.4.4 | YES | YES | Limited, Slow | NO |
| 1.3.2 | NO | Limited | Limited | NO |
| 1.2.5 | NO | Limited | Limited | NO |
| earlier | NO | maybe | probably | NO |
(*) As implemented in node-minecraft-protocol src/ping.js
(**) Limited = responds but does not return the game/protocol version
Example:
node demo.js localhost 25565
ping_fe01fa is the best general-purpose ping for most use cases, where a fast response and
reasonable version compatibility is required. It includes MC|PingHost,
for efficient 1.6.4 compatibility (but ≤1.3.2 incompatibility). You can use it on old servers
starting with 1.4.4 at the earliest, then 1.5.2 and 1.6.4, and it even works on Netty-based
1.7.10, 1.8.9, and 1.9 servers. The protocol and game version is included in the ping so you
can tell what protocol to speak to it. Example responses from ping_fe01fa:
{
pingVersion: 1,
protocolVersion: 78,
gameVersion: '1.6.4',
motd: 'A Minecraft Server',
playersOnline: 0,
maxPlayers: 2
}
{
pingVersion: 1,
protocolVersion: 61,
gameVersion: '1.5.2',
motd: 'A Minecraft Server',
playersOnline: 0,
maxPlayers: 2
}
{
pingVersion: 1,
protocolVersion: 49,
gameVersion: '1.4.4',
motd: 'A Minecraft Server',
playersOnline: 0,
maxPlayers: 2
}ping_fe01fa does not support 1.3.2 and 1.2.5. If you need to be compatible with older versions,
see ping_fe01, ping_fe, and/or ping_fefd_udp.
ping_fe01fa is also exported as ping, since it is expected to be the most commonly used ping type.
ping_fe01 is similar to ping_fe01fa, but without the MC|PingHost channel. The missing
MC|PingHost means it will respond slowly on 1.6.4 servers, but this has the advantage of
not confusing 1.3.2 and 1.2.5 servers with the extra data.
However, 1.3.2 and 1.2.5 servers respond only with limited information (no protocol payload, only server message of the day description, number of online players, and maximum player count). 1.7.10 and above will respond quickly and include the full response, including protocol version.
If you need to support arbitrarily old versions, but do not mind the slow 1.6.4 response (for example,
if you're sending a batch of ping requests over a long period of time), ping_fe01 may be a good choice.
ping_fe sends nothing more than a single 0xfe byte, and only returns motd, playersOnline, and
maxPlayers. No protocol or game version. However it works even on 1.2.5 and 1.3.2. It will also
work on 1.4.4, 1.5.2, and 1.6.4, but is noticeably slower than ping_fe01. On 1.7.10, 1.8.9, and 1.9
it responds quicker, but still lacks the protocol information also returned in ping_fe01.
If all you need is the server description, and do not mind the slowness of 1.6.4/1.5.2/1.4.4, consider
ping_fe. It is not very useful in most situations, better served by ping_fe01fa or ping_fe01.
ping_fefd_udp is a multi-step UDP-based query protocol described in 2011 at
https://dinnerbone.com/blog/2011/10/14/minecraft-19-has-rcon-and-query (for Minecraft 1.9 beta).
require('minecraft-ping').ping_fefd_udp({host:'localhost', port:25565}, function(err, response) {
console.log(err, response);
});
Example response from ping_fefd_udp:
{ worldHeight: 128,
motd: 'A Minecraft Server',
gameType: 'SMP',
gameName: 'MINECRAFT',
gameVersion: '1.5.2',
plugins: 'CraftBukkit on Bukkit 1.5.2-R1.1-SNAPSHOT: MultiWorld 4.5.4; SilkSpawners 3.2.2; OpenInv 2.0.2; EnchantMore 2.0; WorldEdit 5.5.6',
defaultWorld: 'world',
numPlayers: 0,
maxPlayers: 20,
port: 25565,
host: '0.0.0.0'
}It can be used to query modified servers, such as CraftBukkit, in order to get their installed plugins. Unlike the fe pings, it does not include the protocol version, though it does include the game version.
On vanilla servers, support can be enabled by setting enable-query=true in server.properties
(and optionally query.port, which defaults to the same as server-port). If enabled, the server will log:
2016-01-30 11:28:10 [INFO] Starting GS4 status listener
2016-01-30 11:28:11 [INFO] Setting default query port to 25565
2016-01-30 11:28:11 [INFO] Query running on 0.0.0.0:25565
where GS4 is apparently the "GameSpy4" protocol. Since it is off by default, you'll probably
not need to use ping_fefd_udp except in very specialized situations.
ping_all sends all of the types of pings, and calls the callback multiple times.
You can get the ping type with the third argument in the callback function.
Note: synchronizing and waiting for each of the pings is currently out of the scope
of this module (see #4),
in general it is preferrable to use only one ping type (suggestion: ping_fe01fa).
MIT