node-GameDig, one query interface for over 320 games

What the library does and the scale of the catalogue

node-GameDig is a game server query library, and the README describes it as capable of querying for the status of nearly any game or voice server. The governing principle is stated in one sentence: if a server makes its status publicly available, GameDig can fetch it for you.

The scale is the headline number. The README says it can query over 320 games plus a few services, and the GAMES_LIST.md file in the repository holds the currently supported titles, the ones not yet supported and notes about some of them. That file is the reference to read before you commit, because a library that claims breadth is only useful if the specific title you care about is actually in it.

The protocol is not always the game's own. The type field takes a game type ID from the games list, or you can use a protocol-prefixed form to select a specific protocol directly, with the protocols listed in protocols/index.js. So the same underlying query implementation can be pointed at different titles, and the prefix form is the escape hatch when a title is supported but the automatic mapping picks the wrong protocol.

The library is MIT licensed and published on npm as gamedig. The current version in the package metadata is 5.3.3, and the package is an ES module with a CommonJS build shipped alongside it. The engines field requires Node 16.20.0 or newer, and the README carries badges for Deno 1.39.2 and Bun 1.1.21, which is a much wider compatibility claim than the Node requirement alone suggests.

One warning in the README is worth reading early, because it is a breaking change that catches people out. The README asks whether you are updating from v4 to v5, notes that many game ids have changed, and points at an id migration document and the changelog. If you have an existing integration, the type strings you pass may no longer mean what they meant.

Support is offered on Discord for questions and on GitHub issues for bugs.

Using it from Node and from the command line

Installation is with the package manager of your choice, and the README gives npm install gamedig, followed by a tip for trying the latest features by installing from the repository directly with npm i git+https://github.com/gamedig/node-gamedig.

The Node usage is a single call returning a promise:

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}`);
});

The import comment matters, because the package is an ES module with type set to module and an exports map that points import at lib/index.js and require at dist/index.cjs. So the same package works from both module systems, but the build step has to have run to produce the CommonJS file, which is what the prepare script does by running the build before publishing.

The catch branch is the interesting part. A server that does not answer is a normal outcome for a status checker rather than an exceptional one, and the README's example treats it as a message rather than a crash. That is the right shape for anything that polls a list of servers on a schedule.

The required fields are minimal. The type is the game type ID from the games list, or a protocol-prefixed name, and the host is the hostname or IP of the server. The README notes that some games require additional values, which is the practical caveat: the required fields are the common case, not the whole story.

The command line interface is registered in the bin field as gamedig, pointing at bin/gamedig.js, and the README describes the library as also being a command line executable. The examples directory has an import.mjs and a require.cjs, one for each module system, which is a small confirmation that the dual build is tested in both.

The options and why the timeout settings matter

The optional fields are where the real control lives, and a few of them deserve attention because they change the behaviour of a query in ways that are not obvious from the names.

The address field overrides the IP address of the server and skips DNS resolution, so host is not resolved and address is connected to instead. The README notes that some protocols still use host for other reasons, for example as part of the query itself, so this is an override rather than a replacement.

The port field is the connection port or the query port for the server, and the README explains that some games use a separate query port, so if the game port does not behave as expected, passing the query port may work instead.

The two timeout settings are the ones that bite. socketTimeout is the milliseconds to wait for a single packet, with a default of 2000, and the README warns that increasing it causes many queries to take longer even if the server is online. attemptTimeout is the milliseconds allowed for an entire query attempt, defaulting to 10000, and it includes the socket timeout. The warning is specific and worth memorising: if the attempt timeout is smaller than, or even equal to, the socket timeout, the query will always fail. That is a configuration trap where a query can never succeed no matter what is wrong with the server.

maxRetries defaults to 1 and is the number of retries in case of failure, and the README notes that this multiplies with the number of attempts, so it is not an absolute count of attempts but a multiplier.

givenPortOnly makes the query attempt only the given port, ignoring default ports, port offsets and cached ports. ipFamily controls the IP family used when resolving hostnames through DNS, with 0 for both IPv4 and IPv6, 4 for IPv4 only and 6 for IPv6 only, which matters on a dual-stack host where you want a predictable answer.

There are then the Valve-specific options, since the Source engine family needs its own configuration. requestRules and requestPlayers fetch additional data into a raw key, and the required variants of both exist because the README explains that a response is always needed or the query will time out. requestPlayers defaults to true, and the README notes that some games may not provide a players response at all, which is the kind of detail that explains a timeout that looks like a server problem.

Finally, stripColors, defaulting to true, enables stripping of colour codes for a specific list of protocols including unreal2, savage2, quake3, nadeo, gamespy2, doom3 and armagetron, and debug turns on verbose logging to stdout.

The implementation and the protocol layer

The dependency list is short and each entry tells you what kind of protocol the library speaks.

There are two HTTP clients, got for HTTP requests, and gbxremote for the Nadeo remote protocol. There is a telnet-client, which is what several older protocols require since they answer a telnet-style negotiation before the query. There is fast-xml-parser for XML responses, iconv-lite for decoding the non-UTF-8 text that older servers emit, and long and varint for 64-bit values and variable length integer encoding.

seek-bzip is there for the compressed payloads that some games send, and minimist is the argument parser behind the command line interface. The dependency list is pinned to exact versions rather than ranges, which is the practice of a library whose behaviour depends on the wire format of a hundred different games.

The build is esbuild, driven by a small script in tools/esbuild.js, and the package layout separates the source from the build. The lib/ directory holds the source, the protocols/ directory holds the protocol implementations and is shipped in the package, the bin/ directory holds the command line entry point, and the tools/ directory holds the build script. The files list in the package metadata confirms what actually gets published: the CommonJS bundle, the bin script, the lib and protocols directories, the licence and the two documentation files.

The linting is eslint with a configuration in.eslintrc.json, and the scripts offer both a check and a fix mode. There is a.nvmrc pinning the Node version, a CONTRIBUTING.md, a CHANGELOG.md, and the MIGRATE_IDS.md file that documents the identifier change between versions.

The one structural thing to be aware of is that the protocol implementations are data as much as code. The type strings map to directories or modules under protocols/, and adding support for a new title usually means adding a protocol implementation rather than adding a case to a switch. That is why a repository of this size can cover so many games, and it is also why the GAMES_LIST.md file carries notes about titles that are only partially supported.

Editorial conclusion

Adopt node-GameDig if you are building a game server list, a status page or a Discord bot and you would rather not implement the protocol for each title yourself. Skip it if you query exactly one game and its protocol is simple, since a direct query might be less code. Verify first by running the CLI against a known public server, then by checking the fields you need are populated in the response rather than undefined, since protocol coverage varies by title.

Frequently asked questions

Official sources

1. gamedig/node-gamedig on GitHub
2. Issues
3. License: MIT
4. Project website
5. README