Robot
/
node-gamedig
mirror of https://github.com/gamedig/node-gamedig.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README.md

This commit is contained in:
CosminPerRam 2023-09-11 01:50:30 +03:00 committed by GitHub
parent 96936b9b0c
commit d55aec285c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 58 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
README.md
View File

@ -1,16 +1,15 @@
node-GameDig - Game Server Query Library # node-GameDig - Game Server Query Library [![npmjs.com](https://img.shields.io/npm/v/gamedig?color=yellow)](https://www.npmjs.com/package/gamedig) [![npmjs.com](https://img.shields.io/npm/dt/gamedig?color=purple)](https://www.npmjs.com/package/gamedig)
---
node-GameDig is a game server query library, capable of querying for the status of
nearly any game or voice server. If a server makes its status publically available,
GameDig can fetch it for you.
GameDig is available as a node.js module, as well as a **node-GameDig** is a game server query Node.js module (as well as a [command line executable](#usage-from-command-line)),
[command line executable](#usage-from-command-line). capable of querying for the status of nearly any game or voice server.
If a server makes its status publically available, GameDig can fetch it for you.
Support is available on the [GameDig Discord](https://discord.gg/NVCMn3tnxH) (for questions), or [GitHub Issues](https://github.com/gamedig/node-gamedig/issues) (for bugs). Support is available on the [GameDig Discord](https://discord.gg/NVCMn3tnxH) (for questions), or [GitHub Issues](https://github.com/gamedig/node-gamedig/issues) (for bugs).
Usage from Node.js ## Games List
--- See the [GAMES_LIST.md](GAMES_LIST.md) file for the currently supported games, not yet supported games and notes about some of them.
## Usage from Node.js
```shell ```shell
npm install gamedig npm install gamedig
@ -28,7 +27,7 @@ Gamedig.query({
}); });
``` ```
### Query Options ## Query Options
**Typical** **Typical**
@ -40,6 +39,7 @@ this query port may work instead. (defaults to protocol default port)
**Advanced** **Advanced**
These fields are all optional.
* **maxAttempts**: number - Number of attempts to query server in case of failure. (default 1) * **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 * **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) will cause many queries to take longer even if the server is online. (default 2000)
@ -50,7 +50,7 @@ this query port may work instead. (defaults to protocol default port)
* **debug**: boolean - Enables massive amounts of debug logging to stdout. (default false) * **debug**: boolean - Enables massive amounts of debug logging to stdout. (default false)
* **requestRules**: boolean - Valve games only. Additional 'rules' may be fetched into the `raw` field. (default false) * **requestRules**: boolean - Valve games only. Additional 'rules' may be fetched into the `raw` field. (default false)
### Return Value ## Return Value
The returned state object will contain the following keys: The returned state object will contain the following keys:
@ -60,8 +60,7 @@ The returned state object will contain the following keys:
* **maxplayers**: number * **maxplayers**: number
* **players**: array of objects * **players**: array of objects
* **name**: string - If the player's name is unknown, the string will be empty. * **name**: string - If the player's name is unknown, the string will be empty.
* **raw**: object - Additional information about the player if available (unstable) * **raw**: object - Additional information about the player if available (**unstable**).
* The content of this field MAY change on a per-protocol basis between GameDig patch releases (although not typical).
* **bots**: array of objects - Same schema as `players` * **bots**: array of objects - Same schema as `players`
* **connect**: string * **connect**: string
* This will typically include the game's `ip:port` * This will typically include the game's `ip:port`
@ -72,16 +71,36 @@ The returned state object will contain the following keys:
* Note that this is not the RTT of an ICMP echo, as ICMP packets are often blocked by NATs and node * 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. 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. * 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**: freeform object (unstable) * **raw**: freeform object (**unstable**)
* Contains all information received from the server in a disorganized format. * Contains all information received from the server in a disorganized format.
* The content of this field MAY change on a per-protocol basis between GameDig patch releases (although not typical).
Games List Note that `raw` (or **unstable**) objects contents MAY change on a per-protocol basis between GameDig patch releases (although not typical).
---
See the [GAMES_LIST.md](GAMES_LIST.md) file for the currently supported games, not yet supported games and notes about some of them.
Common Issues ### 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.
## Common Issues
### Firewalls block incoming UDP ### Firewalls block incoming UDP
*(replit / docker / some VPS providers)* *(replit / docker / some VPS providers)*
@ -91,8 +110,7 @@ Most game query protocols require a UDP request and response. This means that in
Some examples include: Some examples include:
* Docker containers * Docker containers
* You may need to run the container in `--network host` mode so that gamedig can bind a UDP listen port. * 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 * 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.
instructions in the section down below.
* replit * replit
* Most online IDEs run in an isolated container, which will never receive UDP responses from outside networks. * Most online IDEs run in an isolated container, which will never receive UDP responses from outside networks.
* Various VPS / server providers * Various VPS / server providers
@ -101,7 +119,8 @@ Some examples include:
### Gamedig doesn't work in the browser ### 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. 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 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 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. 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 ### Specifying a listen UDP port override
@ -114,25 +133,3 @@ const gamedig = new Gamedig({
}); });
gamedig.query(...) gamedig.query(...)
``` ```
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:
```shell
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`, `--pretty`, `--socketTimeout 5000`, `--requestRules` etc.