minecraft-status
Version:
Node.js module for gathering information about Minecraft Java Edition servers and Minecraft Bedrock Edition servers.
219 lines (178 loc) • 5.89 kB
Markdown
# minecraft-status
Node.js module for gathering information about Minecraft Java Edition servers and Minecraft Bedrock Edition servers.
**minecraft-status** was based off of [mc-ping-updated](https://github.com/Cryptkeeper/mc-ping-updated), [mc-stat](https://github.com/winny-/mcstat), and [mcpe-ping](https://github.com/falkirks/mcpe-ping).
**minecraft-status** supports the [Server List Ping](https://wiki.vg/Server_List_Ping) protocol for Minecraft Java Edition servers on Minecraft versions 1.7 and above (current), [1.6](https://wiki.vg/Server_List_Ping#1.6), and [1.4 through 1.5](https://wiki.vg/Server_List_Ping#1.4_to_1.5), and [Beta 1.8 through 1.3](https://wiki.vg/Server_List_Ping#Beta_1.8_to_1.3) and the [Query](https://wiki.vg/Server_List_Ping) protocol for Minecraft Java Edition servers on Minecraft versions 1.9pre4 and above.
Support for Minecraft Bedrock Edition servers should be implemented soon™️.
## Documentation
Include **minecraft-status** in your project like so.
```js
// MinecraftServerListPing (either)
const { MinecraftServerListPing } = require("minecraft-status");
const MinecraftServerListPing = require("minecraft-status").MinecraftServerListPing;
// MinecraftQuery (either)
const { MinecraftQuery } = require("minecraft-status");
const MinecraftQuery = require("minecraft-status").MinecraftQuery;
// Both
const { MinecraftServerListPing, MinecraftQuery } = require("minecraft-status");
```
For more information on the [Server List Ping](https://wiki.vg/Server_List_Ping) or [Query](https://wiki.vg/Server_List_Ping) protocols, consult [wiki.vg](https://wiki.vg/).
Unlike previous versions of **minecraft-status**, functions use promises rather than callback functions.
```js
MinecraftServerListPing.ping(4, "mc.hypixel.net", 25565, 3000)
.then(response => {
// Success
})
.catch(error => {
// Error
});
```
## [Server List Ping](https://wiki.vg/Server_List_Ping)
### 1.7 and above (current)
```js
MinecraftServerListPing.ping(protocol, host, port, timeout)
```
`protocol` Default **4**. See [protocol version numbers](https://wiki.vg/Protocol_version_numbers). The version the client uses to connect to the server.
`host` The host, or the domain name, IPv4, or IPv6 address, of the server.
`port` Default **25565**. The port of the server.
`callback(error, response)`
`timeout` Default **3000**. Milliseconds.
```json
{
"version": {
"name": "1.8.7",
"protocol": 47
},
"players": {
"max": 100,
"online": 5,
"sample": [
{
"name": "thinkofdeath",
"id": "4566e69f-c907-48ee-8d71-d7ba5aa00d20"
}
]
},
"description": {
"text": "Hello world"
},
"favicon": "data:image/png;base64,<data>"
}
```
### 1.6
```js
MinecraftServerListPing.ping16(protocol, host, port, timeout)
```
`protocol` Default **73**. See [protocol version numbers](https://wiki.vg/Protocol_version_numbers). The version the client uses to connect to the server.
`host` The host, or the domain name, IPv4, or IPv6 address, of the server.
`port` Default **25565**. The port of the server.
`callback(error, response)`
`timeout` Default **3000**. Milliseconds.
```json
{
"version": {
"name": "1.6.4",
"protocol": 78
},
"players": {
"max": 100,
"online": 5
},
"description": "A Minecraft Server"
}
```
### 1.4 through 1.5
```js
MinecraftServerListPing.ping15(host, port, timeout)
```
`host` The host, or the domain name, IPv4, or IPv6 address, of the server.
`port` Default **25565**. The port of the server.
`callback(error, response)`
`timeout` Default **3000**. Milliseconds.
```json
{
"version": {
"name": "1.4.7",
"protocol": 51
},
"players": {
"max": 100,
"online": 5
},
"description": "A Minecraft Server"
}
```
### Beta 1.8 through 1.3
```js
MinecraftServerListPing.ping13(host, port, timeout)
```
`host` The host, or the domain name, IPv4, or IPv6 address, of the server.
`port` Default **25565**. The port of the server.
`callback(error, response)`
`timeout` Default **3000**. Milliseconds.
```json
{
"players": {
"max": 100,
"online": 5
},
"description": "A Minecraft Server"
}
```
## [Query](https://wiki.vg/Query)
The following must be configured in the `server.properties` file.
```
enable-query=true
query.port=<1-65535>
```
The default query port matches the port established in `server-port`.
### Basic stat
```js
MinecraftQuery.query(host, port, timeout)
```
`host` The host, or the domain name, IPv4, or IPv6 address, of the server.
`port` Default **25565**. The port of the server.
`callback(error, response)`
`timeout` Default **3000**. Milliseconds.
```json
{
"players": {
"online": 5,
"max": 100
},
"description": "\u0001A Minecraft Server",
"map": "world",
"game_type": "SMP"
}
```
### Full stat
```js
MinecraftQuery.fullQuery(host, port, timeout)
```
`host` The host, or the domain name, IPv4, or IPv6 address, of the server.
`port` Default **25565**. The port of the server.
`callback(error, response)`
`timeout` Default **3000**. Milliseconds.
```json
{
"version": {
"name": "1.15.2"
},
"players": {
"online": 1,
"max": 20,
"sample": [
"mathhulk"
]
},
"description": "A Minecraft Server",
"map": "world",
"game_type": "SMP",
"game_id": "MINECRAFT",
"server_modification": {
"name": "Paper on 1.15.2-R0.1-SNAPSHOT",
"plugins": [
"SimpleTpa 3.0"
]
}
}
```