gamedig v5.1.4

node-GameDig - Game Server Query Library

node-GameDig is a game server query Node.js module (as well as a command line executable), capable of querying for the status of nearly any game or voice server.

If a server makes its status publicly available, GameDig can fetch it for you.

Support is available on the Discord for questions, or GitHub for bugs.

Are you updating from v4 to v5? Many game ids have changed.
Make sure to check if your game's ID is in the id migration document and don't forget to check the changelog file.

Games List

node-GameDig can query over 320 games + a few services!
See the GAMES_LIST.md file for the currently supported titles, not yet supported titles and notes about some of them.

Usage from Node.js

Install using your favorite package manager: npm install gamedig, then use!
Tip: Do you want to try and use the latest features? Install GameDig from this repository via npm i git+https://github.com/gamedig/node-gamedig!

import { GameDig } from 'gamedig';
// Or if you're using CommonJS:
// const { GameDig } = require('gamedig'); 

GameDig.query({
    type: 'minecraft',
    host: 'mc.hypixel.net'
}).then((state) => {
    console.log(state);
}).catch((error) => {
    console.log(`Server is offline, error: ${error}`);
});

Confused on how this works, or you want to see more? Checkout the examples folder!

Required Fields

Optional Fields

Query Response

The returned state object will contain the following keys:

Note that raw (or unstable) objects contents MAY change on a per-protocol basis between GameDig patch releases (although not typical).

Usage from Command Line

Want to integrate server queries from a batch script or other programming language? You'll still need npm to install gamedig:

npm install gamedig -g

After installing gamedig globally, you can call gamedig via the command line:

gamedig --type minecraft mc.example.com:11234
# Alternatively, if you don't want to install gamedig globally, you can run it with npx:
npx gamedig --type minecraft mc.example.com:11234

The output of the command will be in JSON format.
Additional advanced parameters can be passed in as well:

• --debug: Print debugging information, useful when stating an issue.
• --pretty: Outputs the JSON format nicely.
• --requestRules: Request Valve games rules.
• --givenPortOnly: Run the query with the specified port only (if any).
• --socketTimeout N: Specifies socket timeout (where N is a number, e.g. 5000).
• ... and the rest in the same format.

Using with other runtimes

While we still expect to be some minor issues with these, the library works, if any problems arises please open an issue, and we'll look into it.

• Deno: Minimum supported deno version is 1.39.2 and the --allow-net permission is required.
• Bun: Minimum supported version is 1.1.21.

Common Issues

Firewalls block incoming UDP

(replit / docker / some VPS providers)

Most game query protocols require a UDP request and response. This means that in some environments, gamedig may not be able to receive the response required due to environmental restrictions.

Some examples include:

• Docker containers
  • You may need to run the container in --network host mode so that gamedig can bind a UDP listen port.
  • Alternatively, you can forward a single UDP port to your container, and force gamedig to listen on that port using the instructions in the section down below.
• replit
  • Most online IDEs run in an isolated container, which will never receive UDP responses from outside networks.
• Various VPS / server providers
  • Even if your server provider doesn't explicitly block incoming UDP packets, some server hosts block other server hosts from connecting to them for DDOS-mitigation and anti-botting purposes.

Gamedig doesn't work in the browser

Gamedig cannot operate within a browser. This means you cannot package it as part of your webpack / browserify / rollup / parcel package.
Even if you were able to get it packaged into a bundle, unfortunately no browsers support the UDP protocols required to query server status from most game servers.
As an alternative, we'd recommend using gamedig on your server-side, then expose your own API to your webapp's frontend displaying the status information. If your application is thin (with no constant server component), you may wish to investigate a server-less lambda provider.

Specifying a listen UDP port override

In some very rare scenarios, you may need to bind / listen on a fixed local UDP port. The is usually not needed except behind some extremely strict firewalls, or within a docker container (where you only wish to forward a single UDP port).
To use a fixed listen udp port, construct a new Gamedig object like this:

const gamedig = new GameDig({
    listenUdpPort: 13337
});
gamedig.query(...)