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+)

Retrieves the status of the Java Edition Minecraft server. This method only works on netty servers, which is version 1.7 and above. An attempt to use on pre-netty servers will result in an error.

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)

Retrieves the status of the Java Edition Minecraft server. This is a legacy method that is supported by all servers, but only retrieves basic information. If you know the server is running version 1.7 or above, please use Status() instead.

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

Retrieves the status of the Bedrock Edition Minecraft server.

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

Performs a basic query lookup on the server, retrieving most information about the server. Note that the server must explicitly enable query for this functionality to work.

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

Performs a full query lookup on the server, retrieving all available information. Note that the server must explicitly enable query for this functionality to work.

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

Executes remote console commands on the server. You must know the connection details of the RCON server, as well as the password.

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

Sends a Votifier vote to the specified server, typically used by server listing websites. The host and port must be known of the Votifier server, as well as the token generated by the server. This is for use on servers running Votifier 2 and above, such as NuVotifier.

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)
    }
}

Send Legacy Vote

Sends a legacy Votifier vote to the specified server, typically used by server listing websites. The host and port must be known of the Votifier server, as well as the public key generated by the server. This is for use on servers running Votifier 1, such as the original Votifier plugin. It is impossible to tell whether the vote was successfully processed by the server because Votifier v1 protocol does not return any data.

import (
    "github.com/mcstatus-io/mcutil"
    "github.com/mcstatus-io/mcutil/options"
)

func main() {
    err := mcutil.SendLegacyVote("127.0.0.1", 8192, options.LegacyVote{
        PublicKey:   "...", // the contents of the 'plugins/<Votifier>/rsa/public.key' file on the server
        ServiceName: "my-service",
        Username:    "PassTheMayo",
        IPAddress:   "127.0.0.1",
        Timestamp:   time.Now(),
        Timeout:     time.Second * 5,
    })

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

License

MIT License

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(protocol, host string, port uint16) (*net.SRV, error)
• func ParseAddress(address string, defaultPort uint16) (string, uint16, error)
• func SendLegacyVote(host string, port uint16, opts options.LegacyVote) 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)

Variables

var (
	// ErrVarIntTooBig means the varint received from the server is too big
	ErrVarIntTooBig = errors.New("varint: too big, overflows")
)

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(protocol, 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 SendLegacyVote

func SendLegacyVote(host string, port uint16, opts options.LegacyVote) error

SendVote sends a legacy Votifier vote to the specified Minecraft server

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