mclib

README

mclib

---

The mclib package provides utilities for interacting with Minecraft servers using the Minecraft protocol. It includes functionality to query Minecraft servers for status and latency information. mclib is also capable of determining the software a server is running on by using fingerprinting techniques.

---

Installation

To use this package in your Go project, simply install it:

go get github.com/sch8ill/mclib

Usage

StatusPing

package main

import (
	"fmt"

	"github.com/sch8ill/mclib"
)

func main() {
	client, _ := mclib.NewClient("2b2t.org")
	res, _ := client.StatusPing()

	fmt.Printf("version: %s\n", res.Version.Name)
	fmt.Printf("protocol: %d\n", res.Version.Protocol)
	fmt.Printf("online players: %d\n", res.Players.Online)
	fmt.Printf("max players: %d\n", res.Players.Max)
	fmt.Printf("sample players: %+q\n", res.Players.Sample)
	fmt.Printf("description: %s\n", res.Description.String())
	fmt.Printf("latency: %dms\n", res.Latency)
}

output

version: Velocity 1.7.2-1.20.4
protocol: 47
online players: 571
max players: 1
sample players: [{"Fit" "fdee323e-7f0c-4c15-8d1c-0f277442342a"}]
description: 2B Updated to 1.19! 2T
latency: 8ms

Fingerprint

package main

import (
	"fmt"

	"github.com/sch8ill/mclib/fingerprint"
)

func main() {
	software, _ := fingerprint.Fingerprint("localhost")
	fmt.Printf("software fingerprint: %s\n", software)
}

output

software fingerprint: craftbukkit

Further documentation can be found on pkg.go.dev.

---

Cli

Build

requires:

make
go >= 1.22

make build

Usage

mclib also provides a simple command line interface:

  -addr string
        the server address (default "localhost")
  -fingerprint
        whether a software fingerprint should be performed on the server (default true)
  -protocol int
        the protocol version number the client should use (default 760)
  -srv
        whether a srv lookup should be made (default true)
  -timeout duration
        the connection timeout (default 5s)

For example:

mcli --addr hypixel.net --timeout 10s

---

License

This package is licensed under the MIT License.

---

Documentation

Index

• Constants
• type Client
  • func NewClient(addr string, opts ...ClientOption) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) LoginError() (string, int32, error)
  • func (c *Client) Ping() (int, error)
  • func (c *Client) Status() (*slp.Response, error)
  • func (c *Client) StatusPing() (*slp.Response, error)
• type ClientOption
  • func WithAddress(addr *address.Address) ClientOption
  • func WithConnection(conn net.Conn) ClientOption
  • func WithProtocolVersion(protocol int32) ClientOption
  • func WithTimeout(timeout time.Duration) ClientOption
  • func WithoutSRV() ClientOption
• type ConnState

Constants

const (
	DefaultTimeout        = 5 * time.Second
	DefaultProtocol int32 = 47

	StatusState int32 = 1
	LoginState  int32 = 2
)

Types

type Client

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

Client represents a client for interacting with Minecraft servers through the Minecraft protocol.

func NewClient

func NewClient(addr string, opts ...ClientOption) (*Client, error)

NewClient creates a new Client for pinging a Minecraft server at the specified address.

func (*Client) Close

func (c *Client) Close() error

Close safely closes the TCP connection to the Minecraft server.

func (*Client) LoginError

func (c *Client) LoginError() (string, int32, error)

LoginError tries to trigger an exception in the servers packet parser. The error response can be used to fingerprint the server software.

func (*Client) Ping

func (c *Client) Ping() (int, error)

Ping performs a ping operation to the Minecraft server and returns the latency in milliseconds.

func (*Client) Status

func (c *Client) Status() (*slp.Response, error)

Status performs a status query to the Minecraft server and retrieves server information.

func (*Client) StatusPing

func (c *Client) StatusPing() (*slp.Response, error)

StatusPing performs both a status query and a ping to the Minecraft server and returns the combined result.

type ClientOption

type ClientOption func(*Client)

ClientOption represents a functional option for configuring a Client instance.

func WithAddress

func WithAddress(addr *address.Address) ClientOption

WithAddress sets a custom address.

func WithConnection

func WithConnection(conn net.Conn) ClientOption

WithConnection set a custom already connected connection.

func WithProtocolVersion

func WithProtocolVersion(protocol int32) ClientOption

WithProtocolVersion sets a custom Minecraft protocol version.

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets a custom timeout for communication with the server.

func WithoutSRV

func WithoutSRV() ClientOption

WithoutSRV disables SRV record lookups for the client.

type ConnState

type ConnState int64

ConnState represents the connection state of the Client.

const (
	Idle ConnState = iota
	Connected
	HandshakeComplete
)