mcstatus

README

mcstatus

A Go library for retrieving the status of a Minecraft server.

Installation

go get github.com/PassTheMayo/mcstatus/v4

Documentation

https://pkg.go.dev/github.com/PassTheMayo/mcstatus/v4

Usage

Status (1.7+)

import "github.com/PassTheMayo/mcstatus/v4"

func main() {
    response, err := mcstatus.Status("play.hypixel.net", 25565)

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Legacy Status (< 1.7)

import "github.com/PassTheMayo/mcstatus/v4"

func main() {
    response, err := mcstatus.StatusLegacy("play.hypixel.net", 25565)

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Bedrock Status

import "github.com/PassTheMayo/mcstatus/v4"

func main() {
    response, err := mcstatus.StatusBedrock("127.0.0.1", 19132)

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Basic Query

import "github.com/PassTheMayo/mcstatus/v4"

func main() {
    response, err := mcstatus.BasicQuery("play.hypixel.net", 25565)

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Full Query

import "github.com/PassTheMayo/mcstatus/v4"

func main() {
    response, err := mcstatus.FullQuery("play.hypixel.net", 25565)

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

RCON

import "github.com/PassTheMayo/mcstatus/v4"

func main() {
    client := mcstatus.NewRCON()

    if err := client.Dial("127.0.0.1", 25575); err != nil {
        panic(err)
    }

    if err := client.Login("mypassword"); err != nil {
        panic(err)
    }

    if err := client.Run("say Hello, world!"); err != nil {
        panic(err)
    }

    fmt.Println(<- client.Messages)

    if err := client.Close(); err != nil {
        panic(err)
    }
}

Send Vote

import "github.com/PassTheMayo/mcstatus/v4"

func main() {
    err := mcstatus.SendVote("127.0.0.1", 8192, mcstatus.VoteOptions{
		ServiceName: "my-service",
		Username:    "PassTheMayo",
		Token:       "abc123", // server's Votifier token
		UUID:        "",       // recommended but not required, UUID with dashes
		Timestamp:   time.Now(),
		Timeout:     time.Second * 5,
	})

    if err != nil {
        panic(err)
    }
}

Documentation

Index

• Variables
• func BasicQuery(host string, port uint16, options ...QueryOptions) (*basicQueryResponse, error)
• func FullQuery(host string, port uint16, options ...QueryOptions) (*fullQueryResponse, error)
• func NewRCON() *rcon
• func ParseAddress(address string, defaultPort uint16) (string, uint16, error)
• func SendVote(host string, port uint16, options VoteOptions) error
• func Status(host string, port uint16, options ...JavaStatusOptions) (*javaStatusResponse, error)
• func StatusBedrock(host string, port uint16, options ...BedrockStatusOptions) (*bedrockStatusResponse, error)
• func StatusLegacy(host string, port uint16, options ...JavaStatusLegacyOptions) (*javaStatusLegacyResponse, error)
• type BedrockStatusOptions
• type JavaStatusLegacyOptions
• type JavaStatusOptions
• type QueryOptions
• type RCONOptions
• type VoteOptions

Variables

var (
	// ErrUnexpectedResponse means the server sent an unexpected response to the client
	ErrUnexpectedResponse = errors.New("received an unexpected response from the server")
	// ErrVarIntTooBig means the server sent a varint which was beyond the protocol size of a varint
	ErrVarIntTooBig = errors.New("size of VarInt exceeds maximum data size")
	// ErrNotConnected means the client attempted to send data but there was no connection to the server
	ErrNotConnected = errors.New("client attempted to send data but connection is non-existent")
	// ErrAlreadyLoggedIn means the RCON client was already logged in after a second login attempt was made
	ErrAlreadyLoggedIn = errors.New("RCON client is already logged in after a second login attempt was made")
	// ErrInvalidPassword means the password used in the RCON loggin was incorrect
	ErrInvalidPassword = errors.New("incorrect RCON password")
	// ErrNotLoggedIn means the client attempted to execute a command before a login was successful
	ErrNotLoggedIn = errors.New("RCON client attempted to send message before successful login")
	// ErrDecodeUTF16OddLength means a UTF-16 was attempted to be decoded from a byte array that was an odd length
	ErrDecodeUTF16OddLength = errors.New("attempted to decode UTF-16 byte array with an odd length")
)

Functions

func BasicQuery

func BasicQuery(host string, port uint16, options ...QueryOptions) (*basicQueryResponse, error)

BasicQuery runs a query on the server and returns basic information

func FullQuery

func FullQuery(host string, port uint16, options ...QueryOptions) (*fullQueryResponse, error)

FullQuery runs a query on the server and returns the full information

func NewRCON

func NewRCON() *rcon

NewRCON creates a new RCON client from the options parameter

func ParseAddress

func ParseAddress(address string, defaultPort uint16) (string, uint16, error)

ParseAddress parses the host and port out of an address string

func SendVote

func SendVote(host string, port uint16, options VoteOptions) error

SendVote sends a Votifier vote to the specified Minecraft server

func Status

func Status(host string, port uint16, options ...JavaStatusOptions) (*javaStatusResponse, error)

Status retrieves the status of any Minecraft server

func StatusBedrock

func StatusBedrock(host string, port uint16, options ...BedrockStatusOptions) (*bedrockStatusResponse, error)

StatusBedrock retrieves the status of a Bedrock Minecraft server

func StatusLegacy

func StatusLegacy(host string, port uint16, options ...JavaStatusLegacyOptions) (*javaStatusLegacyResponse, error)

Types

type BedrockStatusOptions

type BedrockStatusOptions struct {
	EnableSRV  bool
	Timeout    time.Duration
	ClientGUID int64
}

type JavaStatusLegacyOptions

type JavaStatusLegacyOptions struct {
	EnableSRV       bool
	Timeout         time.Duration
	ProtocolVersion int
}

type JavaStatusOptions

type JavaStatusOptions struct {
	EnableSRV       bool
	Timeout         time.Duration
	ProtocolVersion int
}

type QueryOptions

type QueryOptions struct {
	Timeout   time.Duration
	SessionID int32
}

type RCONOptions

type RCONOptions struct {
	Timeout time.Duration
}

type VoteOptions

type VoteOptions struct {
	ServiceName string
	Username    string
	Token       string
	UUID        string
	Timestamp   time.Time
	Timeout     time.Duration
}