All protocols are implemented in pure Go, without any external dependency besides stdlib. All protocols should be supported on any platform/architecture as long as Go can compile them.
All protocols have been implemented using minecraft.wiki. All of them are 100% compliant with the standard described there.
This project also contains an helper in communication with tcp/udp, called pkg/networking. While it is published as a package, it is primarly used in this library and its API should not be considered stable.
-
Ping (Server List Ping)
All protocols implementations support SRV record resolving.
Rcon implementation supports fragmented response packets.
Ping protocol changed in 1.7 in a non-backwards compatible way. Both modern and legacy SLP protocols are supported.
go install -ldflags="-w -s" github.com/xrjr/mcutils/cmd/mcutils@latestShow usage
$ mcutils [--json] ping <hostname> <port>
Example : mcutils ping localhost 25565
$ mcutils [--json] ping-legacy <hostname> <port>
Example : mcutils ping localhost 25565
$ mcutils [--json] ping-legacy-1.6.4 <hostname> <port>
Same as ping-legacy, but uses 1.6+ SLP protocol
Example : mcutils ping localhost 25565
$ mcutils [--json] query-basic <hostname> <port>
Example : mcutils query-basic localhost 25565
$ mcutils [--json] query-full <hostname> <port>
Example : mcutils query-full localhost 25565
$ mcutils [--json] rcon <hostname> <port> <password> <command>
Example : mcutils rcon localhost 25575 mypassword "say hello"
$ mcutils [--json] ping-bedrock <hostname> <port>
Example : mcutils ping-bedrock localhost 19132Ping
// Ping returns the server list ping infos (JSON-like object), and latency of a minecraft server.
properties, latency, err := ping.Ping("localhost", 25565)// Ping returns the legacy server list ping infos, and latency of a minecraft server.
properties, latency, err := ping.PingLegacy("localhost", 25565)// Ping returns the legacy server list ping infos (using 1.6+ SLP protocol), and latency of a minecraft server.
properties, latency, err := ping.PingLegacy1_6_4("localhost", 25565)Query
// QueryBasic returns the basic stat of a minecraft server.
basicStat, err := query.QueryBasic("localhost", 25565)
// QueryBasic returns the full stat of a minecraft server.
fullStat, err := query.QueryFull("localhost", 25565)Rcon
// Rcon executes a command on a minecraft server, and returns the response of that command.
response, err := rcon.Rcon("localhost", 25575, "password", "command")Bedrock ping
// Ping returns the server infos, and latency of a minecraft bedrock server.
response, err := bedrock.Ping("localhost", 19132)Ping
pingclient := ping.NewClient("localhost", 25565)
// Connect opens the connection, and can raise an error for example if the server is unreachable
err := pingclient.Connect()
// Handshake is the base request of ping, the one that displays number of players, MOTD, etc...
// If all went well, hs contains a field Properties which contains a golang-usable JSON Object
hs, err := pingclient.Handshake()
// Ping is a request that basically do nothing and is just used for measuring the latency
// pong contains the latency in ms
pong, err := pingclient.Ping()
// Disconnect closes the connection
err = pingclient.Disconnect()legacypingclient := ping.NewClientLegacy("localhost", 25565)
// Connect opens the connection, and can raise an error for example if the server is unreachable
err := legacypingclient.Connect()
// Ping requests for informations and latency of a server, using legacy SLP.
infos, latency, err := legacypingclient.Ping()
// Same as Ping, but uses 1.6+ SLP protocol. Only one call to Ping or Ping1_6_4 should be done per opened connection.
infos, latency, err := legacypingclient.Ping1_6_4()
// Disconnect closes the connection
err = legacypingclient.Disconnect()Query
queryclient := query.NewClient("localhost", 25565)
// Connect opens the connection, and can raise an error for example if the server is unreachable
err := queryclient.Connect()
// Handshake request is used to get the challenge token, needed for questing basic and full stat
challengeToken, err := queryclient.Handshake()
// BasicStat returns several informations about the server like number of players, maximum number of players, etc... in a fully predictable way
bs, err := queryclient.BasicStat(challengeToken)
// FullStat returns several informations (more than BasicStat) in a Key/Value format, plus the list of connected players
fs, err := queryclient.FullStat(challengeToken)
// Disconnect closes the connection
queryclient.Disconnect()Rcon
rconclient := rcon.NewClient("localhost", 25575)
// Connect opens the connection, and can raise an error for example if the server is unreachable
err := rconclient.Connect()
// Authenticate request is used to authenticate the connection.
// If the authentication succeeds, ok will be true, and if it fails, ok will be false.
// err will be nil unless there is a communication problem with the server
ok, err := rconclient.Authenticate("password")
// Command will execute the given command on the server, and the output text will be returned in res
res, err := rconclient.Command("playerlist")
// Disconnect closes the connection
rconclient.Disconnect()Bedrock Ping
pingclient := ping.NewClient("localhost", 25565)
// Connect opens the connection, and can raise an error for example if the server is unreachable
err := pingclient.Connect()
// UnconnectedPing is a request that retrieve server informations and latency
pong, latency, err := pingclient.UnconnectedPing()
// Disconnect closes the connection
err = pingclient.Disconnect()Customize client parameters
Each protocol client is created with reasonable defaults, but you may need to adapt them to your very own requirements. For example, you may want to customize timeouts or skip the SRV lookup. Explore exported fields of clients to see more.
client.SkipSRVLookup = true
client.DialTimeout = 10 * time.Second
client.ReadTimeout = 500 * time.MilisecondNote on SRV resolving
All clients are created with a default option that performs SRV resolving, besides bedrock one. This is because there is no such SRV records mechanism on bedrock servers.
As we've seen in the client customization part, you can disbale SRV resolving for clients that perform it by default, and you can even enable it for bedrock one. In this last case, it would be using the same service and protocol as the java edition, but please note that it is not standard.
For clients that rely on UDP streams (currently query and bedrock), you can also change the protocol for the SRV lookup (default is _minecraft._tcp, you can make it _minecraft._udp). See ForceUDPProtocolForSRVLookup option. Please note that, again, this is not standard at all.
SRV resolution is automatically skipped at client creation if the provided hostname either is localhost or a textual IP. While this is how most minecraft client work for optimization purposes, you can still re-enable it right after client creation.