minecraftstatuspinger

A modern, small, fast, performant, zero dependency TypeScript library made for pinging and getting status of Minecraft servers.

---

What can this be used for?

• Getting server Latency (ping)
• Getting server MOTD
• Downloading server Thumbnail (favicon)
• Viewing Server Version
• Fetching Player Count and Playerlist

And in general, checking the status of Minecraft servers!

Getting started

Requirements

• NodeJS, Deno or Bun (used to run JavaScript code)
• NPM/JSR (used to install JavaScript packages)

Installation

npm install minecraftstatuspinger

Basic Example

import mc from "minecraftstatuspinger";

let result = await mc.lookup({ host: "mc.hypixel.net" });
console.log(result);

Advanced Example

import mc from "minecraftstatuspinger";
//OR
const mc = require("minecraftstatuspinger");

let result = await mc.lookup({
    host: "mc.hypixel.net",  // A hostname, or an IP of your server. 
    port: 25565,             // Port of the server.
    ping: true,              // Whether to get the latency of the server, or skip that part.
    protocolVersion: 769,    // Minecraft version - 769 is 1.21.4
    timeout: 10000,          // Time in milliseconds to wait for a response before throwing an error.
    throwOnParseError: true, // Whether to throw an error if parsing of the status response fails.
    SRVLookup: true,         // Whether to do a SRV lookup before doing a normal lookup.
    JSONParse: true          // Whether to skip parsing the JSON response entirely.
});

console.log(result);

Docs

• .lookup(): ((options: ServerStatusOptions) => Promise<ServerStatus>)

  • options: ServerStatusOptions
    • host: string

      An IP address or 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

      The time (in milliseconds) to wait for a response before throwing an error if the transaction isn’t completed. (Default: 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: 769

      The protocol version sent to the server to simulate different Minecraft client versions. Refer to the Protocol Version Numbers for details. It is recommended to set this explicitly, as it will be updated periodically through minor version bumps. The default is 769 (Minecraft 1.21.4).

    • throwOnParseError?: boolean default: true

      If true, an error will be thrown when the the status field fails to parse. The raw status response is always provided in the statusRaw field.

    • SRVLookup?: boolean default: true

      Whether to perform a SRV lookup on the provided hostname. Set to false to skip the lookup, which is useful when you're only looking for basic DNS records. It is automatically disabled when you define a port different from 25565.

    • JSONParse?: boolean default: true

      Whether to parse the JSON status field. Useful to disable when you only need the raw plaintext response. If false, the status field will be null.

  • ServerStatus
    • 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. This field will be null if parsing fails or if JSONParse is false. 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>)

  Wraps the dns.setServers function, useful for quicker lookups 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, otherwise, it uses the default DNS servers of your computer.
  
  ❗ Changing the default DNS servers is recommended, if you're doing tons of lookups at once.

  Usage:

    // For example:
    mc.setDnsServers(["9.9.9.9", "1.1.1.1", "8.8.8.8"])
    // (Quad9, Cloudflare, Google)
    // Note: Cloudflare is typically the fastest for DNS queries.

---

Changelog

View Changelog, Latest version: v1.2.2

Contact

If you have some questions, you can message me through Discord - woodendoors7

Acknowledgements

TINY Readme

To-do

• [x] Do SRV lookups
• [ ] Parse MOTDs
• [ ] Support versions less than 1.7.
• [ ] Support Bedrock

(I plan to add these over summer!)

License

This project is licensed under the GNU General Public License v3.0.