Async node.js implementation of the UDP Minecraft Server Query Protocol and TCP Minecraft Server List Ping Protocol

Overview

πŸ”Ž Mc Server Status

Async node.js implementation of the UDP Minecraft Server Query Protocol and TCP Minecraft Server List Ping Protocol.

Also available as a npm package! npm i mc-server-info

After using implementations that either were bloated with functionality not suitable for my use-case, required some boilerplate like class instantiation and manual socket closing or were just way too abstracted for the small task they provide, I decided to prep up my own - plain - implementation of the UDP Server Query Protocol, as lined out by Dinnerbone in his Original Blog Post, as well as the Server List Ping Protocol in a purely functional manner (only up to v1.1.0). I just want to call a single function and that's it - so I did it.

Requirements

The target minecraft server has to run the JAVA edition of minecraft on any version more recent than 1.7.

In order to use Server Query Protocol (queryBasicStat() and queryFullStat()) the server.properties file (or if a proxy like Bungeecord or Waterfall is used in their specific config file) the option enable-query has to be set to true and the query.port has to bet set to any valid port (can be the same as the game port but has to be specified) and the server must be running Java Edition.

In order to use Server List Ping Protocol (serverStatus()) the server must be online, running Java Edition and may not be behind an obfuscation proxy like TCPShield. It does not have to have enable-query enabled, however the retrievable data is limited in comparison to the Server Query Protocol.

How to use

No fancy instantiations or anything necessary, simply require the wanted function(s) from mc-server-query and/or mc-server-status and call the function you need, then you'll receive a Map of the server data (or an error).

const { queryFullStat } = require('./mc-server-query');

(async function () {
    try {
        let info = await queryFullStat({ host: "localhost", port: 56789, timeout: 6000 });
        console.log(info);
    } catch (err) {
        console.log('FullStat Query threw an error:\n\n' + err);
    }
})();
{ console.log(map); }) .catch((err) => console.log(err)); ">
const { queryBasicStat } = require('./mc-server-query');

queryBasicStat({ host: "localhost", port: 56789, timeout: 6000 })
    .then((map)=>{
        console.log(map);
    })
    .catch((err) => console.log(err)); 
{ console.log(map); }) .catch((err) => console.log(err)); ">
const { serverStatus } = require('./mc-server-status');

serverStatus({ host: "localhost", port: 56789, timeout: 6000 })
    .then((map)=>{
        console.log(map);
    })
    .catch((err) => console.log(err)); 

Arguments

All functions take an Object parameter consisting of the following attributes:

host: (string) Domain or IP-Address of the target server 
port: (integer) [optional] Query Port of the target server (default 25565)
timeout: (integer) [optional] Time in ms until the request should time out (default: 4000)

All query functions return a Map of the query data.

Output

Full stat:

{
  motd: 'This is a MOTD',
  type: 'SMP',
  gameid: 'MINECRAFT',
  version: '1.x.x',
  plugins: 'Plugin1; Plugin2; Plugin3',
  servertype: 'world',
  playercount: '3',
  maxplayers: '100',
  port: '25565',
  players: [ 'EpicPlayer', '0ti', 'otto6' ]
}

Basic Stat:

{
  motd: 'This is a MOTD',
  type: 'SMP',
  servertype: 'world',
  playersonline: '3',
  maxplayers: '100'
}

Server status data may be limited depending on server software used, but is reliably mapped to the FullStat data map format and uses some internal functions in order to try and get as much readable data as possible. It has an additional field containing the base64 string representation of the favicon of the server, if exists:

{
  motd: 'This is a MOTD',
  type: 'SMP',
  gameid: 'MINECRAFT',
  version: '1.x.x',
  plugins: 'undefined',
  servertype: 'world',
  playercount: '3',
  maxplayers: '100',
  port: '25565',
  players: [ 'EpicPlayer', '0ti', 'otto6' ],
  favicon: *string, base64 encoded*
}

Intended Use

Initially I wrote this small ibrary as a simple way to use the Server Query Protocol, however after learning how little servers even have query enabled in their config, I felt the need to add a fallback option. Therefore the intended use is to try and query server data using the Server Query Protocol and if the server does not allow query, use the Server List Ping Protocol function serverStatus() to force a server status response and acquire server data.

Limitations

Some servers run behind a proxy aimed at protecting from DDOS, such as TCPShield. Many large playercount servers use such system. In that case neither protocols will result in retrievable data and the only way to get data from those servers is to get your request host whitelisted by those servers.

Dependencies

This library is using dgram for UDP Messaging, net for TCP Messaging and buffer to craft the necessary packets. These are standard libraries included in the nodejs runtime and therefore this library does not require any external dependencies.

You might also like...

A fully-featured Node.js REST client built for ease-of-use and resilience

A fully-featured Node.js REST client built for ease-of-use and resilience

flashheart A fully-featured Node.js REST client built for ease-of-use and resilience flashheart is built on http-transport to provide everything you n

Jun 21, 2022

Very very very powerful, extensible http client for both node.js and browser.

ES-Fetch-API δΈ­ζ–‡ | English Very very very powerful, extensible http client for both node.js and browser. Why should you use ES-Fetch API? Still using a

Dec 12, 2022

Highly sophisticated proxy used for evading internet censorship or accessing websites in a controlled sandbox using the power of service-workers and more! Easy deployment version (Node.js)

Highly sophisticated proxy used for evading internet censorship or accessing websites in a controlled sandbox using the power of service-workers and more! Easy deployment version (Node.js)

Ultraviolet-Node The deployable version of Ultraviolet, a highly sophisticated proxy used for evading internet censorship or accessing websites in a c

Jan 2, 2023

Highly sophisticated proxy used for evading internet censorship or accessing websites in a controlled sandbox using the power of service-workers and more! Easy deployment version (Node.js)

Highly sophisticated proxy used for evading internet censorship or accessing websites in a controlled sandbox using the power of service-workers and more! Easy deployment version (Node.js)

Ultraviolet-Node The deployable version of Ultraviolet, a highly sophisticated proxy used for evading internet censorship or accessing websites in a c

Apr 15, 2022

:dash: Simple yet powerful file-based mock server with recording abilities

:dash: Simple yet powerful file-based mock server with recording abilities

πŸ’¨ smoke Simple yet powerful file-based mock server with recording abilities Just drop a bunch of (JSON) files in a folder and you're ready to go! Bas

Dec 13, 2022

An HTTP Web Server for Chrome (chrome.sockets API)

An HTTP Web Server for Chrome (chrome.sockets API)

Dec 31, 2022

A server side agnostic way to stream JavaScript.

JS in JSN A server side agnostic way to stream JavaScript, ideal for: inline hydration network free ad-hoc dependencies bootstrap on demand libraries

Nov 21, 2022

A TurboRepo local cache server which uploads artifact cache to GH artifacts.

TurboRepo Github Artifacts action This action allows you use Github artifacts as TurboRepo remote cache server. How it works? It's starts a local Turb

Dec 18, 2022

A full-featured http proxy for node.js

A full-featured http proxy for node.js

node-http-proxy node-http-proxy is an HTTP programmable proxying library that supports websockets. It is suitable for implementing components such as

Jan 3, 2023
Owner
Daniel
πŸ”ŽπŸ“‘πŸ’Ύ πŸ”“ Software Engineer for Business Process Digitalization and Full-Time Hobbyist Developer
Daniel
GraphQL query utility for serverside apps

Write GraphQL queries as objects instead of strings This is a better implementation of the GraphQL query API via NodeJS, created as a wrapper of Got.

Lucas Santos 391 Dec 6, 2022
A collaborative Whiteboard powered by the [matrix] protocol and infrastucture.

TheBoard A collaborative Whiteboard powered by the [Matrix] protocol and infrastructure. Table of Content: Introduction DISCLAIMER How this project ca

Timo 391 Dec 23, 2022
HTTP server mocking and expectations library for Node.js

Nock HTTP server mocking and expectations library for Node.js Nock can be used to test modules that perform HTTP requests in isolation. For instance,

Nock 11.9k Jan 3, 2023
SPDY server on Node.js

SPDY Server for node.js With this module you can create HTTP2 / SPDY servers in node.js with natural http module interface and fallback to regular htt

SPDY & HTTP2 in JavaScript 2.8k Jan 4, 2023
Node.js web server framework for Http/1.1 or Http/2

Node.js web server framework for Http/1.1 or Http/2 Description: This is http framework, you can use it to create Http/1.1 or Http/2 service。 Now let'

Jeremy Yu 10 Mar 24, 2022
Run Node.js on Android by rewrite Node.js in Java

node-android Run Node.js on Android by rewrite Node.js in Java with the compatible API. third-party: libuvpp, libuv-java JNI code by Oracle. Build Clo

AppNet.Link 614 Nov 15, 2022
Promise based HTTP client for the browser and node.js

axios Promise based HTTP client for the browser and node.js New axios docs website: click here Table of Contents Features Browser Support Installing E

axios 98k Dec 31, 2022
Ajax for Node.js and browsers (JS HTTP client)

superagent Small progressive client-side HTTP request library, and Node.js module with the same API, supporting many high-level HTTP client features T

Sloth 16.2k Jan 1, 2023
🌐 Human-friendly and powerful HTTP request library for Node.js

Sindre's open source work is supported by the community. Special thanks to: Human-friendly and powerful HTTP request library for Node.js Moving from R

Sindre Sorhus 12.5k Jan 9, 2023
Full-featured, middleware-oriented, programmatic HTTP and WebSocket proxy for node.js

rocky A multipurpose, full-featured, middleware-oriented and hackable HTTP/S and WebSocket proxy with powerful built-in features such as versatile rou

Tom 370 Nov 24, 2022