Minecraft Server Status

This is a script I wrote to get the informations from a running minecraft server.

How to use

The module is available using npm.

import { getStatus } from "@neryss/mc_server_status";

getStatus("neryss.pw", 25565).then(res => {
  console.log(res);
}).catch((error) => {
  console.error(error);
});

Response will be formated as follows:

{
  favicon: 'data:image/png;base64,{data}`,
  isModded: true/false,
  description: 'server description',
  players: {max: 20, online: 0},
  version: {name: '1.21.1', protocol: 767},
  preventChatReports: true/false
}

Dev info

You'll fine documentation about how the package was developped further below!

Sources

• Minecraft server list protocol
• VarInt pseudo code
• Handshake format
• Protocol ids

Packets

When sending a TCP request to the server, it expects a specific packet to arrive:

|     name    |  type  |            notes                 |
|-------------|--------|----------------------------------|
| Length      | VarInt | Leng of packet ID + data         |
| Packet ID   | VarInt | Protocol id (protocol packet id) |
| Data        | Byte[] | Depends on the case, check below |

Handshake protocol

In our case, the handshake protocol comes first, it uses the protocol 0x00 and its data is formed as follows:

|     name         |  type       |            notes                                               |
|------------------|-------------|----------------------------------------------------------------|
| Protocol version | VarInt      | The protocol version (minecraft version, check "protocol ids") |
| Server addr      | String      | hostname/ip of the server                                      |
| Server port      | u_short     | Defaults to 25565                                              |
| Intent           | VarInt Enum | 1 for status, 2 for login, 3 for transfer                 |

Status Request

The status packet is only composed of the packet ID and its length. It must be sent right after the handshake and before anythhing else (ping etc.), it won't work otherwise.

Response

The server response format can be found here. It is composed of a single String field, as with every other String response, it is prefixed by its length as a VarInt, which can be used to wait and read for several chunks as done in the script.