Categorygithub.com/millkhan/mcstatusgo/v2
modulepackage
2.2.0
Repository: https://github.com/millkhan/mcstatusgo.git
Documentation: pkg.go.dev

# 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.