minecraft

README

minecraft-client

A client for the Minecraft RCON protocol.

Library Usage

// Create a new client and connect to the server.
client, err := minecraft.NewClient("127.0.0.1:25575")
if err != nil {
	log.Fatal(err)
}
defer client.Close()

// Send some commands.
if err := client.Authenticate("password"); err != nil {
	log.Fatal(err)
}
resp, err := client.SendCommand("seed")
if err != nil {
	log.Fatal(err)
}
log.Println(resp.Body) // "Seed: [1871644822592853811]"

Shell Utility

If you are looking for a tool rather than a library, try the shell command:

$ cd cmd/shell
$ go run main.go --hostport 127.0.0.1:25575 --password minecraft
Starting RCON shell. Use 'exit', 'quit', or Ctrl-C to exit.
> list
There are 0 of a max of 20 players online:
> seed
Seed: [5853448882787620410]

Limitations

Response bodies over 4KB will be truncated.

Starting a server for testing

$ docker pull itzg/minecraft-server
$ docker run --name=minecraft-server -p 25575:25575 -d -e EULA=TRUE itzg/minecraft-server

Running Tests

After starting the test server in Docker:

$ go test -v

Reference

• https://wiki.vg/Rcon

Documentation

Index

• func EncodeMessage(msg Message) ([]byte, error)
• type Client
  • func NewClient(hostport string) (*Client, error)
  • func (c *Client) Authenticate(password string) error
  • func (c *Client) Close() error
  • func (c *Client) SendCommand(command string) (Message, error)
• type Message
  • func DecodeMessage(msg []byte) (Message, error)
• type MessageType

Functions

func EncodeMessage

func EncodeMessage(msg Message) ([]byte, error)

EncodeMessage serializes an RCON command. Format: [4-byte message size | 4-byte message ID | 4-byte message type | variable length message | 2-byte terminator].

Types

type Client

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

Client manages a connection to a Minecraft server.

func NewClient

func NewClient(hostport string) (*Client, error)

NewClient creates a TCP connection to a Minecraft server.

func (*Client) Authenticate

func (c *Client) Authenticate(password string) error

Authenticate starts a logged-in RCON session.

func (*Client) Close

func (c *Client) Close() error

Close disconnects from the server.

func (*Client) SendCommand

func (c *Client) SendCommand(command string) (Message, error)

SendCommand sends an RCON command to the server.

type Message

type Message struct {
	Length int32
	ID     int32
	Type   MessageType
	Body   string
}

Message contains fields for RCON messages.

func DecodeMessage

func DecodeMessage(msg []byte) (Message, error)

DecodeMessage deserialize an RCON response. Format: [4-byte message size | 4-byte message ID | 4-byte message type | variable length message].

type MessageType

type MessageType int32

MessageType is an int32 representing the type of message being sent or received.

const (
	// MsgResponse is returned by the server.
	MsgResponse MessageType = iota

	// MsgCommand is used when sending commands to the server.
	MsgCommand
	// MsgAuthenticate is used when logging into the server.
	MsgAuthenticate
)