If you're new to MineQuery, you can skip this part. If you have used it before, you might want to give it a read if you're planning to switch from v1, or want to know about breaking changes in v2.x.x version and how to adapt your codebase.
See MIGRATING.md for help with migrating from MineQuery.
MineQuery supports pinging of all versions of Minecraft.
| Beta 1.8 to 1.3 | 1.4 to 1.5 | 1.6 | 1.7+ |
|---|---|---|---|
| ✅ Supported | ✅ Supported | ✅ Supported | ✅ Supported |
MineQuery v2.1.0+ fully supports Query protocol.
MineQuery v2.5.0+ fully supports SRV records.
For simple pinging with default parameters, use package-global Ping* functions
(where * is your respective Minecraft server version.)
If you're unsure about version, it is known that Notchian servers respond to all previous version pings (e.g. 1.7+ server will respond to 1.6 ping, and so on.)
Here's a quick example how to:
import "github.com/dreamscached/minequery/v2"
res, err := minequery.Ping17("localhost", 25565)
if err != nil { panic(err) }
fmt.Println(res)import "github.com/dreamscached/minequery/v2"
res, err := minequery.QueryBasic("localhost", 25565)
// ... or ...
res, err := minequery.QueryFull("localhost", 25565)
if err != nil { panic(err) }
fmt.Println(res)For full info on response object structure, see documentation.
For more advanced usage, such as setting custom timeout or enabling more strict
response validation, you can use Pinger struct with PingerOption passed to it:
import "github.com/dreamscached/minequery/v2"
pinger := minequery.NewPinger(
minequery.WithTimeout(5 * time.Second),
minequery.WithUseStrict(true),
minequery.WithProtocolVersion16(minequery.Ping16ProtocolVersion162),
minequery.WithProtocolVersion17(minequery.Ping17ProtocolVersion172),
)Then, use Ping* functions on it the same way as described in Basic usage section:
import "github.com/dreamscached/minequery/v2"
// Ping Beta 1.8+
pinger.PingBeta18("localhost", 25565)
// Ping 1.4+
pinger.Ping14("localhost", 25565)
// Ping 1.6+
pinger.Ping16("localhost", 25565)
// Ping 1.7+
pinger.Ping17("localhost", 25565)Or Query*:
import "github.com/dreamscached/minequery/v2"
// Query basic stats
res, err := pinger.QueryBasic("localhost", 25565)
// Query full stats
res, err := pinger.QueryFull("localhost", 25565)By default, Pinger has 15-second timeout before connection aborts. If you need
to customize this duration, you can use WithTimeout option.
By default, Pinger does not validate response data it receives and silently
omits erroneous values it processes (incorrect favicon or bad player UUID).
If you need it to return an error in case of invalid response, you can use
WithUseStrict option.
By default, Pinger stores query sessions in cache for 30 seconds and flushes expired
entries every 5 minutes. If you want to override these defaults, use WithQueryCacheExpiry
option.
By default, Pinger stores query sessions in cache, reusing sessions and security tokens
and saving bandwidth. If you don't want to use session cache, use WithQueryCacheDisabled
option.
By default, Pinger stores query sessions using patrickmn/go-cache library
(and WithQueryCacheExpiry/WithQueryCacheDisabled only affect this implementation of
cache for Go). If you wish to use other cache implementation, you can use any that
implements Cache interface.
By default, Pinger sends protocol version 74 in 1.6 ping packets. If you need
to customize protocol version sent, use WithProtocolVersion16. MineQuery provides
a convenient set of constants you can use — see Ping16ProtocolVersion* constants.
By default, Pinger sends protocol version -1 in 1.7 ping packets. If you need
to customize protocol version sent, use WithProtocolVersion17. MineQuery provides
a convenient set of constants you can use — see Ping17ProtocolVersion* constants.
By default, Pinger uses standard Go json.Unmarshal function to unmarshal JSON which can
be slow compared to alternatives. If you need to use another unmarshaller library, you can
use this option to provide an Unmarshaller implementation that will be used instead.
By default, Pinger uses standard Go png.Decode function to decode PNG from binary stream.
If you need to use another decoding library, you can use this option to provide
png.Decode-compatible function that will be used instead.
By default, Pinger uses standard Go base64.StdEncoding encoding to decode Base64 string
returned in 1.7+ responses. If you need to use another encoding, you can use this option to
provide a compatible implementation that will be used instead.