A modern, small, fast, performant, zero dependency TypeScript library made for pinging and getting status of Minecraft servers.
And in general, checking the status of Minecraft servers!
npm install minecraftstatuspinger
import mc from "minecraftstatuspinger"; let result = await mc.lookup({ host: "mc.hypixel.net" }) console.log(result);
import mc from "minecraftstatuspinger"; let result = await mc.lookup({ host: "mc.hypixel.net", port: 25565, ping: true, protocolVersion: 767, timeout: 10000, throwOnParseError: true, SRVLookup: true, JSONParse: true }) console.log(result);
.lookup(): ((options: ServerStatusOptions) => Promise<ServerStatus>)
host:
string
Either an IP, or a hostname of the server. (alias: hostname)
port?:
number default: 25565
Port of the server. SRV lookup is disabled when using ports other than 25565.
timeout?:
number default: 10000
How long until an error is thrown if the transaction still hasn't finished. Default is 10 seconds.
ping?:
boolean default: true
Whether to send a payload at the end to measure the server latency. If false, the
latency
field will be null.
protocolVersion?:
number default: 767
Protocol version to send to the server to simulate different Minecraft client versions. Here, you can see the Protocol Version Numbers. The current default protocol version is for 1.21.1 (767) and will be irregularly updated to newer versions.
throwOnParseError?:
boolean default: true
Whether to throw an error if the status packet fails to parse the status field. The
statusRaw
field is always included.
SRVLookup?:
boolean default: true
Whether to perform a SRV lookup on the provided hostname. Set to
true
in order to skip. Useful to disable when you're only looking up the basic DNS records and a server with a specific port.
JSONParse?:
boolean default: true
Whether to parse the JSON
status
field. Useful to disable when you only need the raw plaintext response. If false, thestatus
field will be null.
latency?:
number
The time it takes to receive back a response after sending a small payload to a server, in milliseconds. Will be null if the
ping
option is false.
status?:
DynamicObject
Parsed status response from the server. Will be null if the status fails to parse, or if disableJSONParse is true. Example of a valid Status Response.
statusRaw:
string
Plaintext status response in the form of JSON. Useful when
status
fails to parse.
.setDnsServers(): ((serverArray: string[]) => Promise<boolean>)
It wraps the
dns.setServers
function, useful for looking up SRV records through different DNS servers.
The first IP in the array will always be used first, others will be tried if the first one is unreachable.
Accepts an array of hostnames or IP addresses of DNS servers. It will either return true, or throw an error.
Usage:
// For example: mc.setDnsServers(["9.9.9.9", "1.1.1.1", "8.8.8.8"]) // (Quad9, Cloudflare, Google) // Cloudflare is usually the fastest for DNS queries.
If you never changed the DNS settings of your computer, the default DNS server will be your ISP's.
❗ I recommend changing your default DNS servers if you're doing thousands of lookups, such as for mass scanning.
View Changelog,
Latest version: v1.2.1
If you have some questions, you can message me through Discord - woodendoors7
This project is licensed under the GNU General Public License v3.0.
Add Package
deno add jsr:@minecraft/minecraftstatuspinger
Import symbol
import * as minecraftstatuspinger from "@minecraft/minecraftstatuspinger";
---- OR ----
Import directly with a jsr specifier
import * as minecraftstatuspinger from "jsr:@minecraft/minecraftstatuspinger";
Add Package
npx jsr add @minecraft/minecraftstatuspinger
Import symbol
import * as minecraftstatuspinger from "@minecraft/minecraftstatuspinger";
Add Package
yarn dlx jsr add @minecraft/minecraftstatuspinger
Import symbol
import * as minecraftstatuspinger from "@minecraft/minecraftstatuspinger";
Add Package
pnpm dlx jsr add @minecraft/minecraftstatuspinger
Import symbol
import * as minecraftstatuspinger from "@minecraft/minecraftstatuspinger";
Add Package
bunx jsr add @minecraft/minecraftstatuspinger
Import symbol
import * as minecraftstatuspinger from "@minecraft/minecraftstatuspinger";