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/v3

Documentation

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

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 (
	"context"
	"fmt"
	"time"

	"github.com/mcstatus-io/mcutil/v3"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)

	defer cancel()

	response, err := mcutil.Status(ctx, "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 (
	"context"
	"fmt"
	"time"

	"github.com/mcstatus-io/mcutil/v3"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)

	defer cancel()

	response, err := mcutil.StatusLegacy(ctx, "play.hypixel.net", 25565)

	if err != nil {
		panic(err)
	}

	fmt.Println(response)
}

Bedrock Status

Retrieves the status of the Bedrock Edition Minecraft server.

import (
	"context"
	"fmt"
	"time"

	"github.com/mcstatus-io/mcutil/v3"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)

	defer cancel()

	response, err := mcutil.StatusBedrock(ctx, "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 (
	"context"
	"fmt"
	"time"

	"github.com/mcstatus-io/mcutil/v3"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)

	defer cancel()

	response, err := mcutil.BasicQuery(ctx, "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 (
	"context"
	"fmt"
	"time"

	"github.com/mcstatus-io/mcutil/v3"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)

	defer cancel()

	response, err := mcutil.FullQuery(ctx, "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/v3/rcon"

func main() {
    client, err := rcon.Connect("127.0.0.1", 25575)

	if 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 or RSA public key generated by the server. This is for use on servers running Votifier 1 or Votifier 2, such as NuVotifier.

import (
	"context"
	"time"

	"github.com/mcstatus-io/mcutil/v3"
	"github.com/mcstatus-io/mcutil/v3/options"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)

	defer cancel()

	err := mcutil.SendVote(ctx, "127.0.0.1", 8192, options.Vote{
		// General
		ServiceName: "my-service",    // Required
		Username:    "PassTheMayo",   // Required
		Timestamp:   time.Now(),      // Required
		Timeout:     time.Second * 5, // Required

		// Votifier 1
		PublicKey: "...", // Required

		// Votifier 2
		Token: "abc123", // Required
		UUID:  "",       // Optional
	})

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

License

MIT License

Documentation

Index

• Constants
• Variables
• func BasicQuery(ctx context.Context, host string, port uint16, options ...options.Query) (*response.BasicQuery, error)
• func FullQuery(ctx context.Context, host string, port uint16, options ...options.Query) (*response.FullQuery, error)
• func LookupSRV(protocol, host string) (*net.SRV, error)
• func ParseAddress(address string, defaultPort uint16) (string, uint16, error)
• func SendVote(ctx context.Context, host string, port uint16, opts options.Vote) error
• func Status(ctx context.Context, host string, port uint16, options ...options.JavaStatus) (*response.JavaStatus, error)
• func StatusBedrock(ctx context.Context, host string, port uint16, ...) (*response.BedrockStatus, error)
• func StatusLegacy(ctx context.Context, host string, port uint16, ...) (*response.JavaStatusLegacy, error)
• func StatusRaw(ctx context.Context, host string, port uint16, options ...options.JavaStatus) (map[string]interface{}, error)

Constants

const (
	DefaultJavaPort    = 25565
	DefaultBedrockPort = 19132
)

Variables

var (
	// ErrPublicKeyRequired means that the server is using Votifier 1 but the PublicKey option is missing
	ErrPublicKeyRequired = errors.New("vote: PublicKey is a required option but the value is empty")
	// ErrInvalidPublicKey means the public key provided cannot be parsed
	ErrInvalidPublicKey = errors.New("vote: invalid public key value")
	// ErrPublicKeyRequired means that the server is using Votifier 2 but the Token option is missing
	ErrTokenRequired = errors.New("vote: Token is a required option but the value is empty")
)

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

Functions

func BasicQuery

func BasicQuery(ctx context.Context, 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(ctx context.Context, 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) (*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(ctx context.Context, host string, port uint16, opts options.Vote) error

SendVote sends a Votifier vote to the specified Minecraft server

func Status

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

Status retrieves the status of any 1.7+ Minecraft server

func StatusBedrock

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

StatusBedrock retrieves the status of a Bedrock Minecraft server

func StatusLegacy

func StatusLegacy(ctx context.Context, 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(ctx context.Context, host string, port uint16, options ...options.JavaStatus) (map[string]interface{}, error)

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