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

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