mcutil

README

mcutil

A zero-dependency library for interacting with the Minecraft protocol in Go. Supports retrieving the status of any Minecraft server (Java or Bedrock Edition), querying a server for information, sending remote commands with RCON, and sending Votifier votes. Look at the examples in this readme or search through the documentation instead.

Installation

go get github.com/mcstatus-io/mcutil

Documentation

https://pkg.go.dev/github.com/mcstatus-io/mcutil

Usage

Status (1.7+)

import "github.com/mcstatus-io/mcutil"

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

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Legacy Status (‹ 1.7)

import "github.com/mcstatus-io/mcutil"

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

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Bedrock Status

import "github.com/mcstatus-io/mcutil"

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

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Basic Query

import "github.com/mcstatus-io/mcutil"

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

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Full Query

import "github.com/mcstatus-io/mcutil"

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

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

RCON

import "github.com/mcstatus-io/mcutil"

func main() {
    client := mcutil.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/mcstatus-io/mcutil"
    "github.com/mcstatus-io/mcutil/options"
)

func main() {
    err := mcutil.SendVote("127.0.0.1", 8192, options.Vote{
        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 ...options.Query) (*response.BasicQuery, error)
• func FullQuery(host string, port uint16, options ...options.Query) (*response.FullQuery, error)
• func LookupSRV(host string, port uint16) (*net.SRV, error)
• func ParseAddress(address string, defaultPort uint16) (string, uint16, error)
• func SendVote(host string, port uint16, opts options.Vote) error
• func Status(host string, port uint16, options ...options.JavaStatus) (*response.JavaStatus, error)
• func StatusBedrock(host string, port uint16, options ...options.BedrockStatus) (*response.BedrockStatus, error)
• func StatusLegacy(host string, port uint16, options ...options.JavaStatusLegacy) (*response.JavaStatusLegacy, error)
• func StatusRaw(host string, port uint16, options ...options.JavaStatus) (map[string]interface{}, error)
• type RCONClient
  • func NewRCON() *RCONClient
  • func (r *RCONClient) Close() error
  • func (r *RCONClient) Dial(host string, port uint16, options ...options.RCON) error
  • func (r *RCONClient) Login(password string) error
  • func (r *RCONClient) Run(command string) error

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 ...options.Query) (*response.BasicQuery, error)

BasicQuery runs a query on the server and returns basic information

func FullQuery

func FullQuery(host string, port uint16, options ...options.Query) (*response.FullQuery, error)

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

func LookupSRV

func LookupSRV(host string, port uint16) (*net.SRV, error)

LookupSRV resolves any Minecraft SRV record from the DNS of the domain

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, opts options.Vote) error

SendVote sends a Votifier vote to the specified Minecraft server

func Status

func Status(host string, port uint16, options ...options.JavaStatus) (*response.JavaStatus, error)

Status retrieves the status of any 1.7+ Minecraft server

func StatusBedrock

func StatusBedrock(host string, port uint16, options ...options.BedrockStatus) (*response.BedrockStatus, error)

StatusBedrock retrieves the status of a Bedrock Minecraft server

func StatusLegacy

func StatusLegacy(host string, port uint16, options ...options.JavaStatusLegacy) (*response.JavaStatusLegacy, error)

StatusLegacy retrieves the status of any Java Edition Minecraft server, but with reduced properties compared to Status()

func StatusRaw

func StatusRaw(host string, port uint16, options ...options.JavaStatus) (map[string]interface{}, error)

StatusRaw returns the raw status data of any 1.7+ Minecraft server

Types

type RCONClient

type RCONClient struct {
	Messages chan string
	// contains filtered or unexported fields
}

RCONClient is a client for interacting with RCON and contains multiple methods

func NewRCON

func NewRCON() *RCONClient

NewRCON creates a new RCON client from the options parameter

func (*RCONClient) Close

func (r *RCONClient) Close() error

Close closes the connection to the server

func (*RCONClient) Dial

func (r *RCONClient) Dial(host string, port uint16, options ...options.RCON) error

Dial creates a new connection to the server

func (*RCONClient) Login

func (r *RCONClient) Login(password string) error

Login communicates authentication with the server using the plaintext password

func (*RCONClient) Run

func (r *RCONClient) Run(command string) error

Run executes the command on the server but does not wait for a response