# README
mcstatusgo
mcstatusgo
is a pure Go Minecraft service status checker for Java Edition Minecraft servers.
mcstatusgo
supports requesting information through six protocols: status
, legacy status
, beta status
, ping
, basic query
, and full query
.
status
, ping
, basic query
, and full query
are the most up-to-date protocols.
legacy status
and beta status
are older implementations of status
used in older versions of Minecraft.
Usage
Current Protocols
package main
import (
"fmt"
"time"
"github.com/millkhan/mcstatusgo/v2"
)
func main() {
// Experiment with both the initialTimeout and ioTimeout values to see what works best.
initialTimeout := time.Second * 10
ioTimeout := time.Second * 5
// https://wiki.vg/Server_List_Ping
status, err := mcstatusgo.Status("mc.piglin.org", 25565, initialTimeout, ioTimeout)
if err != nil {
panic(err)
}
fmt.Printf("Max player count: %d\n", status.Players.Max)
// https://wiki.vg/Server_List_Ping#Ping
ping, err := mcstatusgo.Ping("mc.piglin.org", 25565, initialTimeout, ioTimeout)
if err != nil {
panic(err)
}
fmt.Printf("Server latency: %s\n", ping)
// https://wiki.vg/Query#Basic_stat
basicQuery, err := mcstatusgo.BasicQuery("mc.piglin.org", 25565, initialTimeout, ioTimeout)
if err != nil {
panic(err)
}
fmt.Printf("Map name: %s\n", basicQuery.MapName)
// https://wiki.vg/Query#Full_stat
fullQuery, err := mcstatusgo.FullQuery("mc.piglin.org", 25565, initialTimeout, ioTimeout)
if err != nil {
panic(err)
}
fmt.Printf("Server version: %s\n", fullQuery.Version.Name)
}
Older Protocols
package main
import (
"fmt"
"time"
"github.com/millkhan/mcstatusgo/v2"
)
func main() {
// Experiment with both the initialTimeout and ioTimeout values to see what works best.
initialTimeout := time.Second * 10
ioTimeout := time.Second * 5
// https://wiki.vg/Server_List_Ping#1.6
statusLegacy, err := mcstatusgo.StatusLegacy("us.mineplex.com", 25565, initialTimeout, ioTimeout)
if err != nil {
panic(err)
}
fmt.Printf("Max player count: %d\n", statusLegacy.Players.Max)
// https://wiki.vg/Server_List_Ping#Beta_1.8_to_1.3
statusBeta, err := mcstatusgo.StatusBeta("us.mineplex.com", 25565, initialTimeout, ioTimeout)
if err != nil {
panic(err)
}
fmt.Printf("Online player count: %d\n", statusBeta.Players.Online)
}
Documentation
https://pkg.go.dev/github.com/millkhan/mcstatusgo/v2
Installation
mcstatusgo can be installed easily using the following command:
go get github.com/millkhan/mcstatusgo/v2
License
mcstatusgo
is licensed under the MIT License.
Check LICENSE for more information.
# Functions
BasicQuery requests basic server information from a Minecraft server.
FullQuery requests detailed server information from a Minecraft server.
Ping serves as a convenience wrapper over Status to retrieve the server latency.
Status requests basic server information from a Minecraft server.
StatusBeta requests basic server information from a Minecraft server using the beta (oldest version) implementation of Status.
StatusLegacy requests basic server information from a Minecraft server using the older legacy implementation of Status.
# Variables
ErrAbsentChallengeTokenNullTerminator is returned when the challenge token doesn't contain a null-terminator at the end.
ErrAbsentPlayerToken is returned when the player token used to split the full query response into two parts for parsing isn't present.
ErrInvalidPong is returned when the pong response received from the server does not match the ping packet sent to it.
ErrInvalidSizeInfo is returned when the information containing the JSON length does not match the actual JSON length.
ErrLargeVarInt is returned when a varint sent by the server is above the 5 bytes size limit.
ErrShortChallengeToken is returned when the received challenge token is too small to be valid.
ErrShortQueryResponse is returned when the received response is too small to contain valid data.
ErrShortStatusLegacyResponse is returned when the received response is too small to contain valid data.
ErrShortStatusResponse is returned when the received response is too small to contain valid data.
ErrStatusBetaMissingInformation is returned when the received response doesn't contain all 3 expected values.
ErrStatusLegacyMissingInformation is returned when the received response doesn't contain all 5 expected values.
# Structs
BasicQueryResponse contains the information from the basic query request.
ErrMissingInformation is returned when expected values are not receieved.
FullQueryResponse contains the information from the full query request.
StatusBetaResponse contains the information from the beta status request.
StatusLegacyResponse contains the information from the legacy status request.
StatusResponse contains the information from the status request.