diff --git a/README.md b/README.md index 9d45a0f..96de5d0 100644 --- a/README.md +++ b/README.md @@ -44,45 +44,45 @@ Confused on how this works, or you want to see more? Checkout the [examples](/ex ## Optional Fields -| Field | Type | Default | Description | -|:---------------------------|:--------|:----------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **address** | string | undefined | Override the IP address of the server skipping DNS resolution. When set, host will not be resolved, instead address will be connected to. However, some protocols still use host for other reasons e.g. as part of the query. | -| **port** | number | Game port | 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. | -| **maxRetries** | number | 1 | Number of retries to query server in case of failure. Note that this amount multiplies with the number of attempts. | -| **socketTimeout** | number | 2000 | Milliseconds to wait for a single packet. Beware that increasing this will cause many queries to take longer even if the server is online. | -| **attemptTimeout** | number | 10000 | Milliseconds allowed for an entire query attempt (including `socketTimeout`, beware that if this value is smaller (or even equal) to the socket one, the query will always fail). | -| **givenPortOnly** | boolean | false | Only attempt to query server on given port. It will ignore the game's default port. | -| **ipFamily** | number | 0 | IP family/version returned when looking up hostnames via DNS, can be 0 (IPv4 and IPv6), 4 (IPv4 only) or 6 (IPv6 only). | -| **debug** | boolean | false | Enables massive amounts of debug logging to stdout. | -| **requestRules** | boolean | false | Valve games only. Additional 'rules' may be fetched into the `raw` key. | -| **requestPlayers** | boolean | true | Valve games only. Disable this if you don't want to fetch players data. | -| **requestRulesRequired** | boolean | false | Valve games only. `requestRules` is always required to have a response or the query will timeout. | -| **requestPlayersRequired** | boolean | false | Valve games only. Querying players is always required to have a response or the query will timeout. Some [games](GAMES_LIST.md) may not provide a players response. | -| **stripColors** | boolean | true | Enables stripping colors for protocols: unreal2, savage2, quake3, nadeo, gamespy2, doom3, armagetron. | -| **portCache** | boolean | true | After you queried a server, the second time you query that exact server (identified by specified ip and port), first add an attempt to query with the last successful port. | -| **noBreadthOrder** | boolean | false | Enable the behaviour of retrying an attempt X times followed by the next attempt X times, otherwise try attempt A, then B, then A, then B until reaching the X retry count of each. | -| **checkOldIDs** | boolean | false | Also checks the old ids amongst the current ones. | +| Field | Type | Default | Description | +|:---------------------------|:--------|:------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **address** | string | `undefined` | Override the IP address of the server skipping DNS resolution. When set, host will not be resolved, instead address will be connected to. However, some protocols still use host for other reasons e.g. as part of the query. | +| **port** | number | Game port | 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. | +| **maxRetries** | number | `1` | Number of retries to query server in case of failure. Note that this amount multiplies with the number of attempts. | +| **socketTimeout** | number | `2000` | Milliseconds to wait for a single packet. Beware that increasing this will cause many queries to take longer even if the server is online. | +| **attemptTimeout** | number | `10000` | Milliseconds allowed for an entire query attempt (including `socketTimeout`, beware that if this value is smaller (or even equal) to the socket one, the query will always fail). | +| **givenPortOnly** | boolean | `false` | Only attempt to query server on given port. It will ignore the game's default port. | +| **ipFamily** | number | `0` | IP family/version returned when looking up hostnames via DNS, can be 0 (IPv4 and IPv6), 4 (IPv4 only) or 6 (IPv6 only). | +| **debug** | boolean | `false` | Enables massive amounts of debug logging to stdout. | +| **requestRules** | boolean | `false` | Valve games only. Additional 'rules' may be fetched into the `raw` key. | +| **requestPlayers** | boolean | `true` | Valve games only. Disable this if you don't want to fetch players data. | +| **requestRulesRequired** | boolean | `false` | Valve games only. `requestRules` is always required to have a response or the query will timeout. | +| **requestPlayersRequired** | boolean | `false` | Valve games only. Querying players is always required to have a response or the query will timeout. Some [games](GAMES_LIST.md) may not provide a players response. | +| **stripColors** | boolean | `true` | Enables stripping colors for protocols: unreal2, savage2, quake3, nadeo, gamespy2, doom3, armagetron. | +| **portCache** | boolean | `true` | After you queried a server, the second time you query that exact server (identified by specified ip and port), first add an attempt to query with the last successful port. | +| **noBreadthOrder** | boolean | `false` | Enable the behaviour of retrying an attempt X times followed by the next attempt X times, otherwise try attempt A, then B, then A, then B until reaching the X retry count of each. | +| **checkOldIDs** | boolean | `false` | Also checks the old ids amongst the current ones. | ## Query Response The returned state object will contain the following keys: -| Key | Type | Description | -|:-----------------|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **name** | string | Server name. | -| **map** | string | Server map. | -| **password** | boolean | If a password is required. | -| **numplayers** | number | Number of players connected. | -| **maxplayers** | number | Maximum number of connected players. | -| **players** | array of objects | Note that this could be of a different length compared to **numplayers**. | -| **players.name** | string | If the player's name is unknown, the string will be empty. | -| **players.raw** | object | Additional information about the player if available. | -| **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. | -| **queryPort** | number | Indicates on which port the query was done on, 0 if this is not applicable. | -| **version** | string | Game version that is running on the server. Empty if not present. | -| **raw** | object | Contains all information received from the server in a disorganized format. | +| Key | Type | Default | Description | +|:-----------------|:-----------------|-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **name** | string | An empty string | Server name. | +| **map** | string | An empty string | Server map. | +| **password** | boolean | `false` | If a password is required. | +| **numplayers** | number | `0` | Number of players connected. | +| **maxplayers** | number | `0` | Maximum number of connected players. | +| **players** | array of objects | `[]` | Note that this could be of a different length compared to **numplayers**. | +| **players.name** | string | An empty string | If the player's name is unknown, the string will be empty. | +| **players.raw** | object | `{}` | Additional information about the player if available. | +| **bots** | array of objects | `[]` | Same schema as `players`. | +| **connect** | string | `'${ip}:${port}'` | 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 entries, this may be a server ID or connection URL if the previous isn't applicable. | +| **ping** | number | `0` | 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. | +| **queryPort** | number | `0` | Indicates on which port the query was done on, if this is not applicable its the default value. | +| **version** | string | An empty string | Game version that is running on the server. | +| **raw** | object | `{}` | Contains all information received from the server in a disorganized format. | Note that `raw` (or **unstable**) objects contents MAY change on a per-protocol basis between GameDig patch releases (although not typical).