node-gamedig/README.md

141 lines
7.1 KiB
Markdown
Raw Normal View History

# node-GameDig - Game Server Query Library
[![npmjs.com](https://img.shields.io/npm/dt/gamedig?color=purple)](https://www.npmjs.com/package/gamedig) ![deno compatibility](https://shield.deno.dev/deno/>=1.39.2) ![Static Badge](https://img.shields.io/badge/node-%3E%3D16.20.0-green?logo=node.js&logoColor=green)
2014-10-29 08:02:03 +01:00
2023-09-11 00:50:30 +02:00
**node-GameDig** is a game server query Node.js module (as well as a [command line executable](#usage-from-command-line)),
capable of querying for the status of nearly any game or voice server.
2023-09-11 00:50:30 +02:00
If a server makes its status publically available, GameDig can fetch it for you.
2014-10-29 08:02:03 +01:00
Support is available on the [Discord server](https://discord.gg/NVCMn3tnxH) (for questions), or [GitHub Issues](https://github.com/gamedig/node-gamedig/issues) (for bugs).
2023-05-29 17:42:27 +02:00
2023-09-11 00:50:30 +02:00
## Games List
2023-10-15 22:37:35 +02:00
**node-GameDig** can query over 310 games (+ a few services)!
See the [GAMES_LIST.md](GAMES_LIST.md) file for the currently supported titles, not yet supported ones and notes about some of them.
2023-09-11 00:50:30 +02:00
## Usage from Node.js
Install using your favorite package manager: `npm install gamedig`, then use!
```js
import GameDig from 'gamedig';
2014-10-29 08:02:03 +01:00
GameDig.query({
2019-01-13 05:22:26 +01:00
type: 'minecraft',
host: 'mc.example.com'
2017-03-14 09:40:02 +01:00
}).then((state) => {
2019-01-13 05:22:26 +01:00
console.log(state);
2017-03-14 09:40:02 +01:00
}).catch((error) => {
2019-01-13 05:22:26 +01:00
console.log("Server is offline");
2017-03-14 09:40:02 +01:00
});
```
2023-10-30 22:35:39 +01:00
Confused on how this works, or you want to see more? Checkout the [examples](/examples) folder!
2017-03-14 09:40:02 +01:00
2023-09-11 00:50:30 +02:00
## Query Options
2018-01-31 11:03:13 +01:00
**Typical**
2014-10-29 08:02:03 +01:00
2019-01-13 05:22:26 +01:00
* **type**: string - One of the game IDs listed in the game list below
* **host**: string - Hostname or IP of the game server
* **port**: number (optional) - Connection port or query port for the game server. Some
games utilize a separate "query" port. If specifying the game port does not seem to work as expected, passing in
this query port may work instead. (defaults to protocol default port)
2018-01-31 11:03:13 +01:00
**Advanced**
2023-09-11 00:50:30 +02:00
These fields are all optional.
2019-01-13 05:22:26 +01:00
* **maxAttempts**: number - Number of attempts to query server in case of failure. (default 1)
* **socketTimeout**: number - Milliseconds to wait for a single packet. Beware that increasing this
will cause many queries to take longer even if the server is online. (default 2000)
2019-01-13 05:22:26 +01:00
* **attemptTimeout**: number - Milliseconds allowed for an entire query attempt. This timeout is not commonly hit,
2018-01-31 11:03:13 +01:00
as the socketTimeout typically fires first. (default 10000)
* **givenPortOnly**: boolean - Only attempt to query server on given port. (default false)
2022-12-13 11:02:05 +01:00
* **ipFamily**: number - IP family/version returned when looking up hostnames via DNS, can be 0 (IPv4 and IPv6), 4 (IPv4 only) or 6 (IPv6 only). (default 0)
2019-01-13 05:22:26 +01:00
* **debug**: boolean - Enables massive amounts of debug logging to stdout. (default false)
2021-07-22 01:10:48 +02:00
* **requestRules**: boolean - Valve games only. Additional 'rules' may be fetched into the `raw` field. (default false)
2014-10-29 08:02:03 +01:00
2023-09-11 00:50:30 +02:00
## Return Value
2014-10-29 08:02:03 +01:00
2017-03-14 09:40:02 +01:00
The returned state object will contain the following keys:
2014-10-29 08:02:03 +01:00
2019-01-13 05:22:26 +01:00
* **name**: string - Server name
* **map**: string - Current server game map
* **password**: boolean - If a password is required
* **numplayers**: number
2019-01-13 05:22:26 +01:00
* **maxplayers**: number
* **players**: array of objects - note that this could be of a different length compared to **numplayers**
2021-02-25 09:15:53 +01:00
* **name**: string - If the player's name is unknown, the string will be empty.
* **raw**: object - Additional information about the player if available.
2019-01-14 05:21:29 +01:00
* **bots**: array of objects - Same schema as `players`
* **connect**: string
* This will typically include the game's `ip:port`
* The port will reflect the server's game port, even if your request specified the game's query port in the request.
* For some games, this may be a server ID or connection url if an IP:Port is not appropriate for end-users.
* **ping**: number
* Round trip time to the server (in milliseconds).
* Note that this is not the RTT of an ICMP echo, as ICMP packets are often blocked by NATs and node
has poor support for raw sockets.
* This value is derived from the RTT of one of the query packets, which is usually quite accurate, but may add a bit due to server lag.
* **raw**: object
2019-01-14 05:21:29 +01:00
* Contains all information received from the server in a disorganized format.
2014-10-29 08:02:03 +01:00
2023-09-11 00:50:30 +02:00
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:
```shell
npm install gamedig -g
```
After installing gamedig globally, you can call gamedig via the command line:
```shell
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 informations, 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, eg. `5000`).
* ... and the rest in the same format.
2014-10-29 08:02:03 +01:00
## Deno
The minimum supported deno version is `1.39.2` and the `--allow-net` permission is required.
2023-09-11 00:50:30 +02:00
## 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 reponse 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.
2023-09-11 00:50:30 +02:00
* 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
2021-05-18 14:26:13 +02:00
* Most online IDEs run in an isolated container, which will never receive UDP responses from outside networks.
* Various VPS / server providers
2021-05-18 14:26:13 +02:00
* 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
2023-09-11 00:50:30 +02:00
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
2023-09-11 00:50:30 +02:00
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
2023-09-11 00:50:30 +02:00
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(...)
```