minecraft

Core package for dialing and listening to Minecraft Bedrock Edition connections

The minecraft package provides high-level abstractions for connecting to and hosting Minecraft Bedrock Edition servers. It handles authentication, encryption, and the login sequence automatically.

Core Functions

Dial

func Dial(network, address string) (*Conn, error)

Dials a Minecraft connection to the specified address. The network is typically “raknet”.

network · string

The network protocol to use (typically “raknet”)

address · string

The server address to connect to (e.g., “localhost:19132”)

*Conn

A connection that can be used to send and receive packets

error

Error if the connection fails

DialTimeout

func DialTimeout(network, address string, timeout time.Duration) (*Conn, error)

Dials a connection with a specified timeout period.

DialContext

func DialContext(ctx context.Context, network, address string) (*Conn, error)

Dials a connection with context support for cancellation.

Listen

func Listen(network, address string) (*Listener, error)

Creates a listener for incoming Minecraft connections.

network · string

The network protocol to use (typically “raknet”)

address · string

The address to listen on (e.g., “:19132”)

*Listener

A listener that accepts incoming connections

Dialer

The Dialer type allows customizing connection behavior.

type Dialer struct {
    ErrorLog               *slog.Logger
    HTTPClient             *http.Client
    ClientData             login.ClientData
    IdentityData           login.IdentityData
    TokenSource            oauth2.TokenSource
    XBLToken               *auth.XBLToken
    PacketFunc             func(header packet.Header, payload []byte, src, dst net.Addr)
    DownloadResourcePack   func(id uuid.UUID, version string, current, total int) bool
    DisconnectOnUnknownPackets bool
    DisconnectOnInvalidPackets bool
    Protocol               Protocol
    FlushRate              time.Duration
    EnableClientCache      bool
    KeepXBLIdentityData    bool
    EnableLegacyAuth       bool
}

Methods

Dial

func (d Dialer) Dial(network, address string) (*Conn, error)

Dials using the custom dialer configuration.

DialTimeout

func (d Dialer) DialTimeout(network, address string, timeout time.Duration) (*Conn, error)

DialContext

func (d Dialer) DialContext(ctx context.Context, network, address string) (*Conn, error)

ListenConfig

The ListenConfig type allows customizing listener behavior.

type ListenConfig struct {
    ErrorLog                   *slog.Logger
    HTTPClient                 *http.Client
    AuthenticationDisabled     bool
    MaximumPlayers             int
    AllowUnknownPackets        bool
    AllowInvalidPackets        bool
    StatusProvider             ServerStatusProvider
    AcceptedProtocols          []Protocol
    Compression                packet.Compression
    CompressionSelector        func(proto Protocol) packet.Compression
    CompressionThreshold       int
    FlushRate                  time.Duration
    ResourcePacks              []*resource.Pack
    TexturePacksRequired       bool
    FetchResourcePacks         func(identityData login.IdentityData, clientData login.ClientData, current []*resource.Pack) []*resource.Pack
    PacketFunc                 func(header packet.Header, payload []byte, src, dst net.Addr)
    MaxDecompressedLen         int
}

Methods

Listen

func (cfg ListenConfig) Listen(network string, address string) (*Listener, error)

Creates a listener with the custom configuration.

Listener

Represents a server that accepts incoming Minecraft connections.

Methods

Accept

func (listener *Listener) Accept() (net.Conn, error)

Accepts a fully connected client. Cast the returned net.Conn to *minecraft.Conn to use packet methods.

Disconnect

func (listener *Listener) Disconnect(conn *Conn, message string) error

Disconnects a client with an optional message.

AddResourcePack

func (listener *Listener) AddResourcePack(pack *resource.Pack)

Adds a resource pack to the listener.

RemoveResourcePack

func (listener *Listener) RemoveResourcePack(uuid string)

Removes a resource pack by UUID.

Addr

func (listener *Listener) Addr() net.Addr

Returns the listener’s address.

Close

func (listener *Listener) Close() error

Closes the listener.

PlayerCount

func (listener *Listener) PlayerCount() int

Returns the number of active connections.

Conn

Represents a Minecraft connection (client or server side).

Methods

ReadPacket

func (conn *Conn) ReadPacket() (pk packet.Packet, err error)

Reads the next packet from the connection.

WritePacket

func (conn *Conn) WritePacket(pk packet.Packet) error

Writes a packet to the connection (buffered until flush).

Flush

func (conn *Conn) Flush() error

Flushes buffered packets to the network.

StartGame

func (conn *Conn) StartGame(data GameData) error

Starts the game for a client (server-side only).

DoSpawn

func (conn *Conn) DoSpawn() error

Completes the spawn sequence (client-side only).

IdentityData

func (conn *Conn) IdentityData() login.IdentityData

Returns the client’s identity data (UUID, XUID, username).

ClientData

func (conn *Conn) ClientData() login.ClientData

Returns the client data (skin, locale, device info).

Authenticated

func (conn *Conn) Authenticated() bool

Returns true if the connection was authenticated via XBOX Live.

GameData

func (conn *Conn) GameData() GameData

Returns game-specific initialization data.

Proto

func (conn *Conn) Proto() Protocol

Returns the protocol version being used.

ResourcePacks

func (conn *Conn) ResourcePacks() []*resource.Pack

Returns all resource packs associated with the connection.

ClientCacheEnabled

func (conn *Conn) ClientCacheEnabled() bool

Returns whether client blob cache is enabled.

ChunkRadius

func (conn *Conn) ChunkRadius() int

Returns the negotiated chunk radius.

Latency

func (conn *Conn) Latency() time.Duration

Returns the rolling average latency (half RTT).

Context

func (conn *Conn) Context() context.Context

Returns the connection’s context (canceled when closed).

Close

func (conn *Conn) Close() error

Closes the connection after flushing pending packets.

Example Usage

Client Example

conn, err := minecraft.Dial("raknet", "localhost:19132")
if err != nil {
    panic(err)
}
defer conn.Close()

if err := conn.DoSpawn(); err != nil {
    panic(err)
}

for {
    pk, err := conn.ReadPacket()
    if err != nil {
        break
    }
    // Handle packet
}

Server Example

listener, err := minecraft.Listen("raknet", ":19132")
if err != nil {
    panic(err)
}
defer listener.Close()

for {
    c, err := listener.Accept()
    if err != nil {
        break
    }
    conn := c.(*minecraft.Conn)
    go handleConn(conn)
}