mirror of
https://github.com/gamedig/node-gamedig.git
synced 2024-09-28 13:21:30 +02:00
Update README.md
This commit is contained in:
parent
96936b9b0c
commit
d55aec285c
87
README.md
87
README.md
@ -1,16 +1,15 @@
|
||||
node-GameDig - Game Server Query Library
|
||||
---
|
||||
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.
|
||||
# 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)
|
||||
|
||||
GameDig is available as a node.js module, as well as a
|
||||
[command line executable](#usage-from-command-line).
|
||||
**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.
|
||||
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).
|
||||
|
||||
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
|
||||
npm install gamedig
|
||||
@ -28,7 +27,7 @@ Gamedig.query({
|
||||
});
|
||||
```
|
||||
|
||||
### Query Options
|
||||
## Query Options
|
||||
|
||||
**Typical**
|
||||
|
||||
@ -40,6 +39,7 @@ this query port may work instead. (defaults to protocol default port)
|
||||
|
||||
**Advanced**
|
||||
|
||||
These fields are all optional.
|
||||
* **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)
|
||||
@ -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)
|
||||
* **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:
|
||||
|
||||
@ -60,8 +60,7 @@ The returned state object will contain the following keys:
|
||||
* **maxplayers**: number
|
||||
* **players**: array of objects
|
||||
* **name**: string - If the player's name is unknown, the string will be empty.
|
||||
* **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).
|
||||
* **raw**: object - Additional information about the player if available (**unstable**).
|
||||
* **bots**: array of objects - Same schema as `players`
|
||||
* **connect**: string
|
||||
* 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
|
||||
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**: freeform object (unstable)
|
||||
* **raw**: freeform object (**unstable**)
|
||||
* 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
|
||||
---
|
||||
See the [GAMES_LIST.md](GAMES_LIST.md) file for the currently supported games, not yet supported games and notes about some of them.
|
||||
Note that `raw` (or **unstable**) objects contents MAY change on a per-protocol basis between GameDig patch releases (although not typical).
|
||||
|
||||
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
|
||||
*(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:
|
||||
* 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.
|
||||
* 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
|
||||
@ -101,7 +119,8 @@ Some examples include:
|
||||
### 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
|
||||
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
|
||||
@ -114,25 +133,3 @@ const gamedig = new Gamedig({
|
||||
});
|
||||
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.
|
||||
|
Loading…
Reference in New Issue
Block a user