mcstatus

README

MCStatus

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

Installation

go get -u github.com/PassTheMayo/mcstatus

Documentation

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

Usage

Status

import "github.com/PassTheMayo/mcstatus"

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

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

Bedrock Status

import "github.com/PassTheMayo/mcstatus"

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"

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"

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

    if err != nil {
        panic(err)
    }

    fmt.Println(response)
}

RCON

import "github.com/PassTheMayo/mcstatus"

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"

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 SendVote(host string, port uint16, options VoteOptions) error
• type BasicQueryResponse
  • func BasicQuery(host string, port uint16, options ...QueryOptions) (*BasicQueryResponse, error)
• type BedrockStatusOptions
• type BedrockStatusResponse
  • func StatusBedrock(host string, port uint16, options ...BedrockStatusOptions) (*BedrockStatusResponse, error)
• type Favicon
  • func (f Favicon) Exists() bool
  • func (f Favicon) Image() (image.Image, error)
  • func (f Favicon) SaveToFile(path string) error
  • func (f Favicon) String() string
• type FormatItem
• type FullQueryResponse
  • func FullQuery(host string, port uint16, options ...QueryOptions) (*FullQueryResponse, error)
• type JavaStatusLegacyOptions
• type JavaStatusLegacyPlayers
• type JavaStatusLegacyResponse
  • func StatusLegacy(host string, port uint16, options ...JavaStatusLegacyOptions) (*JavaStatusLegacyResponse, error)
• type JavaStatusLegacyVersion
• type JavaStatusOptions
• type JavaStatusResponse
  • func Status(host string, port uint16, options ...JavaStatusOptions) (*JavaStatusResponse, error)
• type MOTD
  • func (m MOTD) Clean() string
  • func (m MOTD) HTML() string
  • func (m MOTD) Raw() string
  • func (m MOTD) String() string
• type QueryOptions
• type RCON
  • func NewRCON() *RCON
  • func (r *RCON) Close() error
  • func (r *RCON) Dial(host string, port uint16, options ...RCONOptions) error
  • func (r *RCON) Login(password string) error
  • func (r *RCON) Run(command string) error
• type RCONOptions
• type SRVRecord
• 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 SendVote

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

SendVote sends a Votifier vote to the specified Minecraft server

Types

type BasicQueryResponse

type BasicQueryResponse struct {
	MOTD          MOTD
	GameType      string
	Map           string
	OnlinePlayers uint64
	MaxPlayers    uint64
	HostPort      uint16
	HostIP        string
}

func BasicQuery

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

BasicQuery runs a query on the server and returns basic information

type BedrockStatusOptions

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

type BedrockStatusResponse

type BedrockStatusResponse struct {
	ServerGUID      int64      `json:"server_guid"`
	Edition         string     `json:"edition"`
	MOTD            MOTD       `json:"motd"`
	ProtocolVersion int64      `json:"protocol_version"`
	Version         string     `json:"version"`
	OnlinePlayers   int64      `json:"online_players"`
	MaxPlayers      int64      `json:"max_players"`
	ServerID        uint64     `json:"server_id"`
	Gamemode        string     `json:"gamemode"`
	GamemodeID      int64      `json:"gamemode_id"`
	PortIPv4        uint16     `json:"port_ipv4"`
	PortIPv6        uint16     `json:"port_ipv6"`
	SRVResult       *SRVRecord `json:"srv_result"`
}

func StatusBedrock

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

StatusBedrock retrieves the status of a Bedrock Minecraft server

type Favicon

type Favicon struct {
	// contains filtered or unexported fields
}

Favicon contains helper functions for reading and writing the favicon

func (Favicon) Exists

func (f Favicon) Exists() bool

func (Favicon) Image

func (f Favicon) Image() (image.Image, error)

func (Favicon) SaveToFile

func (f Favicon) SaveToFile(path string) error

func (Favicon) String

func (f Favicon) String() string

type FormatItem

type FormatItem struct {
	Text          string `json:"text"`
	Color         string `json:"color"`
	Obfuscated    bool   `json:"obfuscated"`
	Bold          bool   `json:"bold"`
	Strikethrough bool   `json:"strikethrough"`
	Underline     bool   `json:"underline"`
	Italic        bool   `json:"italic"`
}

FormatItem is a formatting item parsed from the MOTD for easy use

type FullQueryResponse

type FullQueryResponse struct {
	Data    map[string]string
	Players []string
}

func FullQuery

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

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

type JavaStatusLegacyOptions

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

type JavaStatusLegacyPlayers

type JavaStatusLegacyPlayers struct {
	Online int `json:"online"`
	Max    int `json:"max"`
}

type JavaStatusLegacyResponse

type JavaStatusLegacyResponse struct {
	Version   *JavaStatusLegacyVersion `json:"version"`
	Players   JavaStatusLegacyPlayers  `json:"players"`
	MOTD      MOTD                     `json:"motd"`
	SRVResult *SRVRecord               `json:"srv_result"`
}

func StatusLegacy

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

type JavaStatusLegacyVersion

type JavaStatusLegacyVersion struct {
	Name     string `json:"name"`
	Protocol int    `json:"protocol"`
}

type JavaStatusOptions

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

type JavaStatusResponse

type JavaStatusResponse struct {
	Version struct {
		Name     string `json:"name"`
		Protocol int    `json:"protocol"`
	} `json:"version"`
	Players struct {
		Max    int `json:"max"`
		Online int `json:"online"`
		Sample []struct {
			Name string `json:"name"`
			ID   string `json:"id"`
		} `json:"sample"`
	} `json:"players"`
	MOTD      MOTD       `json:"motd"`
	Favicon   Favicon    `json:"favicon"`
	SRVResult *SRVRecord `json:"srv_result"`
}

func Status

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

Status retrieves the status of any Minecraft server

type MOTD

type MOTD struct {
	Tree []FormatItem `json:"-"`
}

MOTD contains helper functions for reading and writing the MOTD from a server

func (MOTD) Clean

func (m MOTD) Clean() string

Clean returns the description with no formatting

func (MOTD) HTML

func (m MOTD) HTML() string

HTML returns the description with HTML formatting

func (MOTD) Raw

func (m MOTD) Raw() string

Raw returns the raw description with formatting

func (MOTD) String

func (m MOTD) String() string

String returns the description with formatting

type QueryOptions

type QueryOptions struct {
	Timeout   time.Duration
	SessionID int32
}

type RCON

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

func NewRCON

func NewRCON() *RCON

NewRCON creates a new RCON client from the options parameter

func (*RCON) Close

func (r *RCON) Close() error

func (*RCON) Dial

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

func (*RCON) Login

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

func (*RCON) Run

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

type RCONOptions

type RCONOptions struct {
	Timeout time.Duration
}

type SRVRecord

type SRVRecord struct {
	Host string `json:"host"`
	Port uint16 `json:"port"`
}

type VoteOptions

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