tribufu/rust-gamedig
1
0
Fork 0
mirror of https://github.com/tribufu/rust-gamedig synced 2026-05-06 07:17:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore: reformat markdown files

Browse source
This commit is contained in:
CosminPerRam 2024-04-14 23:08:11 +03:00
parent 29f1098daf
commit 3c9f109942
10 changed files with 357 additions and 142 deletions
Download patch file Download diff file Expand all files Collapse all files

64
CONTRIBUTING.md
View file

@ -1,10 +1,12 @@
# Contributing to rust-GameDig
This project is very open to new suggestions, additions and/or changes, these
can come in the form of *discussions* about the project's state, *proposing a
new feature*, *holding a few points on why we shall do X breaking change* or
*submitting a fix*.
## Communications
GitHub is the place we use to track bugs and discuss new features/changes,
although we have a [Discord](https://discord.gg/NVCMn3tnxH) server for the
community, all bugs, suggestions and changes will be reported on GitHub
@ -12,6 +14,7 @@ alongside with their backing points to ensure the transparency of the project's
development.
## Issues
Before opening an issue, check if there is an existing relevant issue first,
someone might just have had your issue already, or you might find something
related that could be of help.
@ -23,8 +26,11 @@ in your issue not being managed right away, if you don't understand something
so.
## Development
Note before contributing that everything done here is under the [MIT](https://opensource.org/license/mit/) license.
### Naming
Naming is an important matter, and it shouldn't be changed unless necessary.
Game **names** should be added as they appear on steam (or other storefront
@ -37,42 +43,45 @@ queries for the game), its name should be composed of the game name, a separatin
A game's **identification** is a lowercase alphanumeric string will and be forged
following these rules:
1. Names composed of a maximum of two words (unless #4 applies) will result in an
id where the words are concatenated (`Dead Cells` -> `deadcells`), acronyms in
the name count as a single word (`S.T.A.L.K.E.R.` -> `stalker`).
id where the words are concatenated (`Dead Cells` -> `deadcells`), acronyms in
the name count as a single word (`S.T.A.L.K.E.R.` -> `stalker`).
2. Names of more than two words shall be made into an acronym made of the
initial letters (`The Binding of Isaac` -> `tboi`), [hypenation composed words](https://prowritingaid.com/hyphenated-words)
don't count as a single word, but of how many parts they are made of
(`Dino D-Day`, 3 words, so `ddd`).
initial
letters (`The Binding of Isaac` -> `tboi`), [hypenation composed words](https://prowritingaid.com/hyphenated-words)
don't count as a single word, but of how many parts they are made of
(`Dino D-Day`, 3 words, so `ddd`).
3. If a game has the exact name as a previously existing id's game
(`Star Wars Battlefront 2`, the 2005 and 2017 one), append the release year to
the newer id (2005 would be `swb2` (suppose we already have this one supported)
and 2017 would be `swb22017`).
(`Star Wars Battlefront 2`, the 2005 and 2017 one), append the release year to
the newer id (2005 would be `swb2` (suppose we already have this one supported)
and 2017 would be `swb22017`).
4. If a new id (`Day of Dragons` -> `dod`) results in an id that already exists
(`Day of Defeat` -> `dod`), then the new name should ignore rule #2
(`Day of Dragons` -> `dayofdragons`).
(`Day of Defeat` -> `dod`), then the new name should ignore rule #2
(`Day of Dragons` -> `dayofdragons`).
5. Roman numbering will be converted to arabic numbering (`XIV` -> `14`).
6. Unless numbers (years included) are at the end of a name, they will be considered
words. If a number is not in the first position, its entire numeric digits will be
used instead of the acronym of that number's digits (`Left 4 Dead` -> `l4d`). If the
number is in the first position the longhand (words: 5 -> five) representation of the
number will be used to create an acronym (`7 Days to Die` -> `sdtd`). Other examples:
`Team Fortress 2` -> `teamfortress2`, `Unreal Tournament 2003` ->
`unrealtournament2003`.
words. If a number is not in the first position, its entire numeric digits will be
used instead of the acronym of that number's digits (`Left 4 Dead` -> `l4d`). If the
number is in the first position the longhand (words: 5 -> five) representation of the
number will be used to create an acronym (`7 Days to Die` -> `sdtd`). Other examples:
`Team Fortress 2` -> `teamfortress2`, `Unreal Tournament 2003` ->
`unrealtournament2003`.
7. If a game supports multiple protocols, multiple entries will be done for said game
where the edition/protocol name (first disposable in this order) will be appended to
the base game id's: `<game_id><protocol_id>` (where the protocol id will follow all
rules except #2) (Minecraft is mainly divided by 2 editions, Java and Bedrock
which will be `minecraftjava` and `minecraftbedrock` respectively, but it also has
legacy versions, which use another protocol, an example would be the one for `1.6`,
so the name would be `Legacy 1.6` which its id will be `legacy16`, resulting in the
entry of `minecraftlegacy16`). One more entry can be added by the base name of the
game, which queries in a group said supported protocols to make generic queries
easier and disposable.
where the edition/protocol name (first disposable in this order) will be appended to
the base game id's: `<game_id><protocol_id>` (where the protocol id will follow all
rules except #2) (Minecraft is mainly divided by 2 editions, Java and Bedrock
which will be `minecraftjava` and `minecraftbedrock` respectively, but it also has
legacy versions, which use another protocol, an example would be the one for `1.6`,
so the name would be `Legacy 1.6` which its id will be `legacy16`, resulting in the
entry of `minecraftlegacy16`). One more entry can be added by the base name of the
game, which queries in a group said supported protocols to make generic queries
easier and disposable.
8. If its actually about a mod that adds the ability for queries to be performed,
process only the mod name.
process only the mod name.
### Making commits
Where possible please format commits as complete atomic changes that don't rely on
any future commits. Also make sure that the commit message is as descriptive as
possible.
@ -82,6 +91,7 @@ run before you are able to make a commit (you can skip this at any time by addin
the `-n` flag to `git commit`).
To set this up you need the following programs installed
- [pre-commit](https://pre-commit.com/)
- [rustup](https://rustup.rs/)
- [act](https://github.com/nektos/act) (If you want to test changes to github actions workflows)
@ -94,6 +104,7 @@ $ pre-commit install
```
### Priorities
Game suggestions will be prioritized by maintainers based on whether the game
uses a protocol already implemented in the library (games that use already
implemented protocols will be added first), except in the case where a
@ -103,5 +114,6 @@ The same goes for protocols, if 2 were to be requested, the one implemented in
the most games will be prioritized.
### Releases
Currently, there is no release schedule.
Releases are made when the team decides one will be fitting to be done.

20
PROTOCOLS.md
View file

@ -1,15 +1,17 @@
A protocol is defined as proprietary if it is being used only for a single scope (or series, like Minecraft).
# Supported protocols:
| Name | For | Proprietary? | Documentation reference | Notes |
|----------------------------|-------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Valve Protocol | Games | No | [Server Queries](https://developer.valvesoftware.com/wiki/Server_queries) | In some cases, the players details query might contain some 0-length named players. Multi-packet decompression not tested. |
| Minecraft | Games | Yes | Java: [List Server Protocol](https://wiki.vg/Server_List_Ping) <br> Bedrock: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/minecraftbedrock.js) | |
| GameSpy | Games | No | One: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/gamespy1.js) Two: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/gamespy2.js) Three: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/gamespy3.js) | These protocols are not really standardized, gamedig tries to get the most common fields amongst its supported games, if there are parsing problems, use the `query_vars` function. |
| Quake | Games | No | One: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/quake1.js) Two: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/quake2.js) Three: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/quake3.js) | |
| Just Cause 2: Multiplayer | Games | Yes | [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/jc2mp.js) |
| Unreal 2 | Games | No | [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/unreal2.js) | Sometimes servers send strings that node-gamedig would treat as latin1 that are UTF-8 encoded, when this happens the remove color code breaks because latin1 decodes the colour sequences differently. Some games provide additional info at the end of the server info packet, this is not currently handled (see the node implementation). Some games use a bot player to denote the team names, this is not currently handled. |
| Savage 2 | Games | Yes | [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/savage2.js) | |
| Name | For | Proprietary? | Documentation reference | Notes |
|---------------------------|-------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Valve Protocol | Games | No | [Server Queries](https://developer.valvesoftware.com/wiki/Server_queries) | In some cases, the players details query might contain some 0-length named players. Multi-packet decompression not tested. |
| Minecraft | Games | Yes | Java: [List Server Protocol](https://wiki.vg/Server_List_Ping) <br> Bedrock: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/minecraftbedrock.js) | |
| GameSpy | Games | No | One: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/gamespy1.js) Two: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/gamespy2.js) Three: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/gamespy3.js) | These protocols are not really standardized, gamedig tries to get the most common fields amongst its supported games, if there are parsing problems, use the `query_vars` function. |
| Quake | Games | No | One: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/quake1.js) Two: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/quake2.js) Three: [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/quake3.js) | |
| Just Cause 2: Multiplayer | Games | Yes | [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/jc2mp.js) |
| Unreal 2 | Games | No | [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/unreal2.js) | Sometimes servers send strings that node-gamedig would treat as latin1 that are UTF-8 encoded, when this happens the remove color code breaks because latin1 decodes the colour sequences differently. Some games provide additional info at the end of the server info packet, this is not currently handled (see the node implementation). Some games use a bot player to denote the team names, this is not currently handled. |
| Savage 2 | Games | Yes | [Node-GameDig Source](https://github.com/gamedig/node-gamedig/blob/master/protocols/savage2.js) | |
## Planned to add support:
_

29
README.md
View file

@ -28,23 +28,28 @@
**Warning**: This project goes through frequent API breaking changes and hasn't been thoroughly tested.
## Community
Checkout the GameDig Community Discord Server [here](https://discord.gg/NVCMn3tnxH).
Note that it isn't be a replacement for GitHub issues, if you have found a problem
within the library or want to request a feature, it's better to do so here rather than
on Discord.
## Usage
Minimum Supported Rust Version is `1.65.0` and the code is cross-platform.
Pick a game/service/protocol (check the [GAMES](GAMES.md), [SERVICES](SERVICES.md) and [PROTOCOLS](PROTOCOLS.md) files to see the currently supported ones), provide the ip and the port (be aware that some game servers use a separate port for the info queries, the port can also be optional if the server is running the default ports) then query on it.
Pick a game/service/protocol (check the [GAMES](GAMES.md), [SERVICES](SERVICES.md) and [PROTOCOLS](PROTOCOLS.md) files
to see the currently supported ones), provide the ip and the port (be aware that some game servers use a separate port
for the info queries, the port can also be optional if the server is running the default ports) then query on it.
[Team Fortress 2](https://store.steampowered.com/app/440/Team_Fortress_2/) query example:
```rust
use gamedig::games::teamfortress2;
fn main() {
let response = teamfortress2::query(&"127.0.0.1".parse().unwrap(), None);
// None is the default port (which is 27015), could also be Some(27015)
// None is the default port (which is 27015), could also be Some(27015)
match response { // Result type, must check what it is...
Err(error) => println!("Couldn't query, error: {}", error),
@ -52,7 +57,9 @@ fn main() {
}
}
```
Response (note that some games have a different structure):
```json5
{
protocol: 17,
@ -72,10 +79,16 @@ Response (note that some games have a different structure):
steam_id: Some(69753253289735296),
tv_port: None,
tv_name: None,
keywords: Some("alltalk,nocrits"),
keywords: Some(
"alltalk,nocrits"
),
rules: [
"mp_autoteambalance": "1",
"mp_maxrounds": "5",
"mp_autoteambalance"
:
"1",
"mp_maxrounds"
:
"5",
//....
]
}
@ -84,14 +97,18 @@ Response (note that some games have a different structure):
Want to see more examples? Checkout the [examples](crates/lib/examples) folder.
## Command Line Interface
The library also has an official CLI: [GameDig-CLI](https://crates.io/crates/gamedig-cli).
## Documentation
The documentation is available at [docs.rs](https://docs.rs/gamedig/latest/gamedig/).
Curious about the history and what changed between versions?
Everything is in the changelogs file: [lib](crates/lib/CHANGELOG.md) and [cli](crates/lib/CHANGELOG.md).
## Contributing
If you want to see your favorite game/service being supported here, open an issue, and I'll prioritize it (or do a pull request if you want to implement it yourself)!
If you want to see your favorite game/service being supported here, open an issue, and I'll prioritize it (or do a pull
request if you want to implement it yourself)!
Before contributing please read [CONTRIBUTING](CONTRIBUTING.md).

3
RESPONSES.md
View file

@ -1,7 +1,8 @@
Every protocol has its own response type(s), below is a listing of the overlapping fields on these responses.
If a cell is blank it doesn't exist, otherwise it contains the type of that data in the current column's response type.
In the case that a field that performs the same function exists in the current column's response type that name is annotated in brackets.
In the case that a field that performs the same function exists in the current column's response type that name is
annotated in brackets.
# Response table

3
SERVICES.md
View file

@ -1,8 +1,9 @@
# Supported services:
| Name | Documentation reference |
|---------------------|-------------------------------------------------------------------------------------------------------|
| Valve Master Server | [Master Server Query Protocol](https://developer.valvesoftware.com/wiki/Master_Server_Query_Protocol) |
## Planned to add support:
TeamSpeak

3
VERSIONS.md
View file

@ -3,6 +3,7 @@
Current: `1.65.0`
Places to update:
- `Cargo.toml`
- `README.md`
- `.github/workflows/ci.yml`
@ -13,6 +14,7 @@ Places to update:
Current: `1.6.0`
Places to update:
- `.rustfmt.toml`
- The nightly rust version
@ -23,5 +25,6 @@ The toolchain version used to run rustfmt in CI
Current: `nightly-2023-07-09`
Places to update:
- `.github/workflows/ci.yml`
- `.pre-commit-config.yaml`

4
crates/cli/CHANGELOG.md
View file

@ -1,11 +1,13 @@
Who knows what the future holds...
# 0.X.Y - DD/MM/YYYY
Nothing... yet.
# 0.1.0 - 15/03/2024
### Changes:
- Added the CLI (by @cainthebest).
- Added DNS lookup support (by @Douile).
- Added JSON output option (by @Douile).

21
crates/cli/README.md
View file

@ -1,34 +1,46 @@
# rust-GameDig CLI
The official [rust-GameDig](https://crates.io/crates/gamedig) Command Line Interface.
[![CI](https://github.com/gamedig/rust-gamedig/actions/workflows/ci.yml/badge.svg)](https://github.com/gamedig/rust-gamedig/actions) [![Latest Version](https://img.shields.io/crates/v/gamedig-cli.svg?color=yellow)](https://crates.io/crates/gamedig-cli) [![Crates.io](https://img.shields.io/crates/d/gamedig-cli?color=purple)](https://crates.io/crates/gamedig-cli) [![License:MIT](https://img.shields.io/github/license/gamedig/rust-gamedig?color=blue)](https://github.com/gamedig/rust-gamedig/blob/main/LICENSE.md) [![node coverage](https://raw.githubusercontent.com/gamedig/rust-gamedig/main/.github/badges/node.svg)](https://github.com/gamedig/node-gamedig)
## Community
Checkout the GameDig Community Discord Server [here](https://discord.gg/NVCMn3tnxH).
Note that it isn't be a replacement for GitHub issues, if you have found a problem
within the library or want to request a feature, it's better to do so here rather than
on Discord.
## Usage
Just by running `gamedig-cli` prints the usage.
**Note**: Passing `--help` (or `-h`) shows the usage.
Here's also a quick rundown of a simple query with the `json-pretty` format:
Pick a game/service/protocol (check the [GAMES](https://github.com/gamedig/rust-gamedig/blob/main/GAMES.md), [SERVICES](https://github.com/gamedig/rust-gamedig/blob/main/SERVICES.md) and [PROTOCOLS](https://github.com/gamedig/rust-gamedig/blob/main/PROTOCOLS.md) files to see the currently supported ones), provide the ip and the port (be aware that some game servers use a separate port for the info queries, the port can also be optional if the server is running the default ports) then query on it.
Pick a game/service/protocol (check
the [GAMES](https://github.com/gamedig/rust-gamedig/blob/main/GAMES.md), [SERVICES](https://github.com/gamedig/rust-gamedig/blob/main/SERVICES.md)
and [PROTOCOLS](https://github.com/gamedig/rust-gamedig/blob/main/PROTOCOLS.md) files to see the currently supported
ones), provide the ip and the port (be aware that some game servers use a separate port for the info queries, the port
can also be optional if the server is running the default ports) then query on it.
[Team Fortress 2](https://store.steampowered.com/app/440/Team_Fortress_2/) query example:
```
gamedig-cli query -g teamfortress2 -i 127.0.0.1 -f json-pretty
```
What we are doing here:
* `-g` (or `--game`) specifies the game.
* `-i` (or `--ip`) target ip.
* `-f` (or `--format`) our preferred format.
Note: We haven't specified a port (via `-p` or `--port`), so the default one for the game will be used (`27015` in this case).
Note: We haven't specified a port (via `-p` or `--port`), so the default one for the game will be used (`27015` in this
case).
Response (note that some games have a different structure):
```json
{
"name": "A cool server.",
@ -45,8 +57,11 @@ Response (note that some games have a different structure):
```
## Documentation
The documentation is available at [docs.rs](https://docs.rs/gamedig/latest/gamedig-cli/).
Curious about the history and what changed between versions? Everything is in the [CHANGELOG](https://github.com/gamedig/rust-gamedig/blob/main/crates/cli/CHANGELOG.md) file.
Curious about the history and what changed between versions? Everything is in
the [CHANGELOG](https://github.com/gamedig/rust-gamedig/blob/main/crates/cli/CHANGELOG.md) file.
## Contributing
Please read [CONTRIBUTING](https://github.com/gamedig/rust-gamedig/blob/main/CONTRIBUTING.md).

237
crates/lib/CHANGELOG.md
View file

@ -1,16 +1,20 @@
Who knows what the future holds...
# 0.X.Y - DD/MM/YYYY
Games:
- [Mordhau](https://store.steampowered.com/app/629760/MORDHAU/) support.
- [Enshrouded](https://store.steampowered.com/app/1203620/Enshrouded/) support.
- [Myth of Empires](https://store.steampowered.com/app/1371580/Myth_of_Empires/) support.
- [Pirates, Vikings, and Knights II](https://store.steampowered.com/app/17570/Pirates_Vikings_and_Knights_II/) support.
# 0.5.0 - 15/03/2024
### Changes:
Games:
- [Valheim](https://store.steampowered.com/app/892970/Valheim/) support.
- [The Front](https://store.steampowered.com/app/2285150/The_Front/) support.
- [Conan Exiles](https://store.steampowered.com/app/440900/Conan_Exiles/) support.
@ -31,19 +35,26 @@ Games:
- [Double Action: Boogaloo](https://store.steampowered.com/app/317360/Double_Action_Boogaloo/) support.
Crate:
- Changed the serde feature to only enable serde derive for some types: serde and serde_json is now a dependecy by default.
- Changed the serde feature to only enable serde derive for some types: serde and serde_json is now a dependecy by
default.
Protocols:
- Added the unreal2 protocol and its associated games: Darkest Hour, Devastation, Killing Floor, Red Orchestra, Unreal Tournament 2003, Unreal Tournament 2004 (by @Douile).
- Added the unreal2 protocol and its associated games: Darkest Hour, Devastation, Killing Floor, Red Orchestra, Unreal
Tournament 2003, Unreal Tournament 2004 (by @Douile).
- Added HTTPClient to allow use of HTTP(S) (and JSON) APIs (by @CosminPerRam & @Douile).
Crate:
- Added a `packet_capture` feature to capture the raw packets sent and received by the socket (by @Douile).
- Added packet emulation and socket retrevial using the `packet_capture` feature (by @Douile).
- Added PCAP writing support to the `packet_capture` feature (by @Douile & @cainthebest).
- Refactored socket to use a custom implementation of socket for packet capture when using the `packet_capture` feature (by @Douile).
- Refactored socket to use a custom implementation of socket for packet capture when using the `packet_capture`
feature (by @Douile).
CLI:
- Added a CLI (by @cainthebest).
- Added DNS lookup support (by @Douile).
- Added JSON output option (by @Douile).
@ -58,123 +69,170 @@ CLI:
- Added source code information to the CLI (by @cainthebest).
### Breaking:
Game:
- Changed identifications of the following games as they weren't properly expecting the naming rules:
- - Left 4 Dead: `left4dead` -> `l4d`.
- - 7 Days to Die: `7d2d` in definitions and `sd2d` in game declaration -> `sdtd`.
- - Quake 3 Arena: `quake3arena` -> `q3a`.
- - Unreal tournament 2003: `ut2003` -> `unrealtournament2003`
- - Unreal tournament 2004: `ut2004` -> `unrealtournament2004`
- - Darkest Hour: Europe '44-'45: `darkesthour` -> `dhe4445`
-
- Left 4 Dead: `left4dead` -> `l4d`.
-
- 7 Days to Die: `7d2d` in definitions and `sd2d` in game declaration -> `sdtd`.
-
- Quake 3 Arena: `quake3arena` -> `q3a`.
-
- Unreal tournament 2003: `ut2003` -> `unrealtournament2003`
-
- Unreal tournament 2004: `ut2004` -> `unrealtournament2004`
-
- Darkest Hour: Europe '44-'45: `darkesthour` -> `dhe4445`
- Minecraft:
- - Legacy 1.5 and 1.3 were renamed to 1.4 and beta 1.8 respectively to show the lowest version they support, this change includes Structs, Enum and game id renames, also removed the "v" from the game definition name.
- - Moved the Minecraft protocol implementation in the games folder as its proprietary.
-
- Legacy 1.5 and 1.3 were renamed to 1.4 and beta 1.8 respectively to show the lowest version they support, this
change includes Structs, Enum and game id renames, also removed the "v" from the game definition name.
-
- Moved the Minecraft protocol implementation in the games folder as its proprietary.
Protocols:
- Valve: Removed `SteamApp` due to it not being really useful at all, replaced all instances with `Engine`.
Query:
- Added a connection timeout to TimeoutSettings (at the moment this only applies to TCP)
- Sockets are now expected to apply timeout settings in new()
- Sockets are now expected to apply timeout settings in new()
# 0.4.1 - 13/10/2023
### Changes:
Game:
- Added [Barotrauma](https://store.steampowered.com/app/602960/Barotrauma/) support.
Crate:
- Added `Send` and `Sync` on `Error::source` to fix some async issues.
Protocols:
- Minecraft Java: Add derives to `RequestSettings` and add `new_just_hostname` that creates new settings just by specifying
the hostname, `protocol_version` defaults to -1.
- Minecraft Java: Add derives to `RequestSettings` and add `new_just_hostname` that creates new settings just by
specifying
the hostname, `protocol_version` defaults to -1.
Games:
- Organised game modules into protocols (when protocol used by other games),
you can now access a game by its name or by its protocol name:
- `use gamedig::games::teamfortress2;`
- `use gamedig::games::valve::teamfortress2;`
- `use gamedig::games::teamfortress2;`
- `use gamedig::games::valve::teamfortress2;`
Generics:
- Added standard derives to `ProprietaryProtocol`, `CommonResponseJson`, `CommonPlayerJson`, `TimeoutSettings` and
`ExtraRequestSettings`.
`ExtraRequestSettings`.
### Breaking...
None, yaay!
# 0.4.0 - 07/10/2023
### Changes:
Games:
- [Creativerse](https://store.steampowered.com/app/280790/Creativerse/) support.
Protocols:
- Quake 2: Fixed a bug where the version tag wouldn't always be present.
- The Ship: Removed instances of using `unwrap` without handling the panics.
Crate:
- Updated [byteorder](https://crates.io/crates/byteorder) dependency from 1.4 to 1.5.
- Rich errors, capturing backtrace is done on `RUST_BACKTRACE=1`. (by @Douile)
- Applied some nursery Clippy lints.
- The `retries` field was added to `TimeoutSettings` that specifies the number of times to retry a failed request (request being individual send, receive sequence, some protocols can include multiple requests in a single query). (by @Douile)
- The `retries` field was added to `TimeoutSettings` that specifies the number of times to retry a failed request (
request being individual send, receive sequence, some protocols can include multiple requests in a single query). (by
@Douile)
- By default `retries` is set to `0`, meaning no retries will be attempted
Generics:
- Added `ExtraRequestSettings` containing all possible extra request settings. (by @Douile)
- Added `query_with_timeout_and_extra_settings()` to allow generic queries with extra settings. (by @Douile)
### Breaking...
Crate:
- The enum used for errors, `GDError` has been renamed to `GDErrorKind`.
- `GDError` is now a struct that holds its kind, the source and a backtrace.
- The `Socket::apply_timeout` method now borrows `TimeoutSettings` (`&Option<TimeoutSettings>`)
- To make this easier to work with a new method was added to `TimeoutSettings`: `TimeoutSettings::get_read_and_write_or_defaults` this takes a borrowed optional `TimeoutSettings` and returns the contained read and write durations or the default read and write durations.
- To make this easier to work with a new method was added
to `TimeoutSettings`: `TimeoutSettings::get_read_and_write_or_defaults` this takes a borrowed
optional `TimeoutSettings` and returns the contained read and write durations or the default read and write
durations.
Generics:
- Renamed `CommonResponseJson`'s `game` field (and the function) to `game_mode`.
- Changed `players_maximum` and `players_online` (and their functions) types from `u64` to `u32`.
- Changed `score` type (and the function) of player from `u32` to `i32`.
Games:
- Rename some game definitions and implementations to follow a stable ID naming system.
Protocols:
- Valve:
1. Renamed `protocol` to `protocol_version`.
2. Renamed `version` to `game_version`.
3. Renamed `game` to `game_mode`.
4. Fixed `player`'s `score` field being `u32` when it needed to be `i32`, as specified in the protocol.
5. Added the field `check_app_id` to `GatherSettings` which controls if the app id specified to the request and
reported by the server are the same, errors if not, enabled by default. (by @Douile)
reported by the server are the same, errors if not, enabled by default. (by @Douile)
6. Valve: Renamed SteamApp enum variants to match new definition names
- GameSpy (1, 2, 3):
1. Renamed `version` to `game_version`.
2. Changed `players_maximum` and `players_online` (and their functions) types from `usize` to `u32`.
- GameSpy 1:
1. Renamed the player's `frags` to `score` and type from `u32` to `i32`.
2. Made `Option` the following response fields `team`, `face`, `skin`, `mesh` and `secret` to fix missing fields issues. (by @Douile)
2. Made `Option` the following response fields `team`, `face`, `skin`, `mesh` and `secret` to fix missing fields
issues. (by @Douile)
- Quake (1, 2):
1. Renamed `game_type` to `game_mode`.
2. Changed `version` type from `String`to `Option<String>`.
- Minecraft Java
1. Renamed `version_protocol` to `protocol_version`.
2. Renamed `version_name` to `game_version`.
3. Renamed `players_sample` to `players`.
4. Added an optional parameter, `RequestSettings`, which contains fields that are used when creating the handshake
packet (this solves some servers not responding to the query). (by @Douile)
packet (this solves some servers not responding to the query). (by @Douile)
5. Legacy versions naming has been changed to represent up to what version they can query, `LegacyBV1_8` (Beta 1.8 to
1.3) -> `LegacyV1_3` and `LegacyV1_4` (1.4 to 1.5) -> `LegacyV1_5` (and their enums accordingly).
1.3) -> `LegacyV1_3` and `LegacyV1_4` (1.4 to 1.5) -> `LegacyV1_5` (and their enums accordingly).
- Minecraft Bedrock
1. Renamed `version_protocol` to `protocol_version`.
- Minecraft:
1. Added an optional parameter, `request_settings` parameter to `query`.
- The Ship:
1. Renamed `protocol` to `protocol_version`.
2. Renamed `max_players` to `players_maximum` and changed its type from `u64` to `u32`.
3. Renamed `bots` to `players_bots`. and changed its type from `u64` to `u32`.
@ -186,6 +244,7 @@ packet (this solves some servers not responding to the query). (by @Douile)
9. Changed `score` type of player from `u32` to `i32`.
- Frontlines: Fuel of War:
1. Renamed `game_mode` to `game`.
2. Renamed `version` to `game_version`.
3. Renamed `protocol` to `protocol_version`.
@ -193,44 +252,63 @@ packet (this solves some servers not responding to the query). (by @Douile)
5. Changed `players_maximum` and `players_minimum` types from `usize` to `u32`.
- Just Cause 2: Multiplayer:
1. Renamed `version` to `game_version`.
2. Changed `players_maximum` and `players_minimum` types from `usize` to `u32`.
# 0.3.0 - 18/07/2023
### Changes:
Protocols:
- GameSpy 2 support.
- Quake 2: Added Optional address field to Player.
Generic query:
- Added generic queries (by [@Douile](https://github.com/Douile)) which come with a common struct for the response fields.
- Added generic queries (by [@Douile](https://github.com/Douile)) which come with a common struct for the response
fields.
- The supported games list is available programmatically.
Games:
- [Halo: Combat Evolved](https://en.wikipedia.org/wiki/Halo:_Combat_Evolved) support.
- [Just Cause 2: Multiplayer](https://store.steampowered.com/app/259080/Just_Cause_2_Multiplayer_Mod/) support.
- [Warsow](https://warsow.net/) support.
Internal:
- Buffer reader rewrite, resulting in more data checks and better code quality (thanks [@cainthebest](https://github.com/cainthebest)).
- Buffer reader rewrite, resulting in more data checks and better code quality (
thanks [@cainthebest](https://github.com/cainthebest)).
- Better CI to never break accidentally MSRV again (thanks [@Douile](https://github.com/Douile)).
### Breaking...
Protocols:
- Quake 2: Renamed the players `frags` field to `score` to be more inline with the other protocols.
Crate:
- `no_games` and `no_services` have been changed to `games` and `services`, this better represents that they are present by default (by [@Douile](https://github.com/Douile)).
- `no_games` and `no_services` have been changed to `games` and `services`, this better represents that they are present
by default (by [@Douile](https://github.com/Douile)).
- Fixed crate's `rust-version`, it is now `1.60.0` (was `1.56.1`)
# 0.2.3 - 02/06/2023
### Changes:
Protocols:
- Valve:
1. Added standard and serde derives to `GatheringSettings`.
- Quake 1, 2 and 3 support.
Games:
- [Quake 2](https://store.steampowered.com/app/2320/Quake_II/) support.
- [Quake 1](https://store.steampowered.com/app/2310/Quake/) support.
- [Quake 3: Arena](https://store.steampowered.com/app/2200/Quake_III_Arena/) support.
@ -238,62 +316,88 @@ Games:
- [Soldier of Fortune 2](https://www.gog.com/en/game/soldier_of_fortune_ii_double_helix_gold_edition) support.
### Breaking:
- Every function that used `&str` for the address has been changed to `&IpAddr` (thanks [@Douile](https://github.com/Douile) for the re-re-write).
- Every function that used `&str` for the address has been changed to `&IpAddr` (
thanks [@Douile](https://github.com/Douile) for the re-re-write).
- Protocols now use `&SocketAddr` instead of `address: &str, port: u16`.
Services:
- Valve Master Query:
1. Removed Filter and SearchFilters lifetimes and changed `&'a str` to `String` and `&'a [&'a str]` to `Vec<String>`
# 0.2.2 - 01/05/2023
### Changes:
Crate:
- General optimizations thanks to [cargo clippy](https://github.com/rust-lang/rust-clippy) and [@cainthebest](https://github.com/cainthebest).
- Added feature `serde` which enables json serialization/deserialization for all types (by [@cainthebest](https://github.com/cainthebest)).
- General optimizations thanks to [cargo clippy](https://github.com/rust-lang/rust-clippy)
and [@cainthebest](https://github.com/cainthebest).
- Added feature `serde` which enables json serialization/deserialization for all types (
by [@cainthebest](https://github.com/cainthebest)).
- Documentation improvements.
Protocols:
- GameSpy 1: Add key `admin` as a possible variable for `admin_name`.
- GameSpy 3 support.
Games:
- [Serious Sam](https://www.gog.com/game/serious_sam_the_first_encounter) support.
- [Frontlines: Fuel of War](https://store.steampowered.com/app/9460/Frontlines_Fuel_of_War/) support.
- [Crysis Wars](https://steamcommunity.com/app/17340) support.
Services:
- [Valve Master Server Query](https://developer.valvesoftware.com/wiki/Master_Server_Query_Protocol) support.
- Added feature `no_services` which disables the supported services.
### Breaking:
Protocols:
- Valve: Request type enums have been renamed from all caps to starting-only uppercase, ex: `INFO` to `Info`
- GameSpy 1: `players_minimum` is now an `Option<u8>` instead of an `u8`
- GameSpy 1: Is now under `protocols::gamespy::one` instead of `protocols::gamespy`
# 0.2.1 - 03/03/2023
### Changes:
Crate:
- Added feature `no_games` which disables the supported games (useful when only the
protocols/services are needed, also saves storage space).
protocols/services are needed, also saves storage space).
Games:
- [V Rising](https://store.steampowered.com/app/1604030/V_Rising/) support.
- [Unreal Tournament](https://en.wikipedia.org/wiki/Unreal_Tournament) support.
- [Battlefield 1942](https://www.ea.com/games/battlefield/battlefield-1942) support.
Protocols:
- Valve:
1. Reversed (from `0.1.0`) "Players with no name are no more added to the `players_details` field.", also added a note in the [protocols](PROTOCOLS.md) file regarding this.
1. Reversed (from `0.1.0`) "Players with no name are no more added to the `players_details` field.", also added a note
in the [protocols](PROTOCOLS.md) file regarding this.
2. Fixed querying while multiple challenge responses might happen.
- GameSpy 1 support.
### Breaking:
None.
# 0.2.0 - 18/02/2023
### Changes:
Games:
- [Don't Starve Together](https://store.steampowered.com/app/322330/Dont_Starve_Together/) support.
- [Colony Survival](https://store.steampowered.com/app/366090/Colony_Survival/) support.
- [Onset](https://store.steampowered.com/app/1105810/Onset/) support.
@ -304,23 +408,31 @@ Games:
- [Operation: Harsh Doorstop](https://store.steampowered.com/app/736590/Operation_Harsh_Doorstop/) support.
Protocols:
- Valve:
1. `appid` is now a field in the `Response` struct.
### Breaking:
Protocols:
- Valve:
due to some games being able to host a server from within the game AND from a dedicated server,
if you were to query one of them, the query would fail for the other one, as the `SteamID` enum
for that game could specify only one id.
due to some games being able to host a server from within the game AND from a dedicated server,
if you were to query one of them, the query would fail for the other one, as the `SteamID` enum
for that game could specify only one id.
1. `SteamID` is now `SteamApp`, was an u32 enum, and now it's a simple enum.
2. `App` is now `Engine`, the `Source` enum's structure has been changed from `Option<u32>` to
`Option<u32, Option<u32>>`, where the first parameter is the game app id and the second is
the dedicated server app id (if there is one).
`Option<u32, Option<u32>>`, where the first parameter is the game app id and the second is
the dedicated server app id (if there is one).
# 0.1.0 - 17/01/2023
### Changes:
Games:
- [Risk of Rain 2](https://store.steampowered.com/app/632360/Risk_of_Rain_2/) support.
- [Battalion 1944](https://store.steampowered.com/app/489940/BATTALION_Legacy/) support.
- [Black Mesa](https://store.steampowered.com/app/362890/Black_Mesa/) support.
@ -328,36 +440,49 @@ Games:
- [Age of Chivalry](https://store.steampowered.com/app/17510/Age_of_Chivalry/) support.
Protocols:
- Valve: Players with no name are no more added to the `players_details` field.
- Valve: Split packets are now appending in the correct order.
Crate:
- `MSRV` is now `1.56.1` (was `1.58.1`)
### Breaking:
Protocols:
- Valve: The rules field is now a `HashMap<String, String>` instead of a `Vec<ServerRule>` (where the `ServerRule` structure had a name and a value fields).
- Valve: Structs that contained the `players`, `max_players` and `bots` fields have been renamed to `players_online`, `players_maximum` and `players_bots` respectively.
- Minecraft: Structs that contained the `online_players`, `max_players` and `sample_players` fields have been renamed to `players_online`, `players_maximum` and `players_sample` respectively.
- Valve: The rules field is now a `HashMap<String, String>` instead of a `Vec<ServerRule>` (where the `ServerRule`
structure had a name and a value fields).
- Valve: Structs that contained the `players`, `max_players` and `bots` fields have been renamed
to `players_online`, `players_maximum` and `players_bots` respectively.
- Minecraft: Structs that contained the `online_players`, `max_players` and `sample_players` fields have been renamed
to `players_online`, `players_maximum` and `players_sample` respectively.
- Minecraft: The Java query response struct named `Response` has been renamed to `JavaResponse`.
Errors:
- Besides the `BadGame` error, now no other errors returns details about what happened (as it was quite pointless).
Crate:
- `package.metadata.msrv` has been replaced with `package.rust-version`
# 0.0.7 - 03/01/2023
### Changes:
[Minecraft](https://www.minecraft.com) bedrock edition support.
Fix Minecraft legacy v1.6 max/online players count being reversed.
Added `query_legacy_specific` method to the Minecraft protocol.
### Breaking:
Removed `query_specific` from the mc protocol in favor of `query_java`, `query_legacy` and `query_legacy_specific`.
Some public functions that are meant to be used only internally were made private.
# 0.0.6 - 28/11/2022
[Minecraft](https://www.minecraft.com) support (bedrock not supported yet).
[7 Days To Die](https://store.steampowered.com/app/251570/7_Days_to_Die/) support.
[ARK: Survival Evolved](https://store.steampowered.com/app/346110/ARK_Survival_Evolved/) support.
@ -371,31 +496,40 @@ Some public functions that are meant to be used only internally were made privat
[Day of Infamy](https://store.steampowered.com/app/447820/Day_of_Infamy/) support.
[Half-Life Deathmatch: Source](https://store.steampowered.com/app/360/HalfLife_Deathmatch_Source/) support.
Successfully tested `Alien Swarm` and `Insurgency: Modern Infantry Combat`.
Restored rules response for `Counter-Strike: Global Offensive` (note: for a full player list response, the cvar `host_players_show` must be set to `2`).
Increased Valve Protocol `PACKET_SIZE` from 1400 to 6144 (because some games send larger packets than the specified protocol size).
Restored rules response for `Counter-Strike: Global Offensive` (note: for a full player list response, the
cvar `host_players_show` must be set to `2`).
Increased Valve Protocol `PACKET_SIZE` from 1400 to 6144 (because some games send larger packets than the specified
protocol size).
Removed DNS resolving as it was not needed.
Valve Protocol minor optimizations.
# 0.0.5 - 15/11/2022
Added `SocketBind` error, regarding failing to bind a socket.
Socket custom timeout capability (with an error if provided durations are zero).
Because of this, a parameter similar to GatherSettings has been added on the Valve Protocol Query.
Support for GoldSrc split packets and obsolete A2S_INFO response.
Changed the Valve Protocol app parameter to represent the engine responses.
It is now an enum of:
- `Source(Option<u32>)` - A Source response with optionally, the id (if the id is present and the response id is not the same, the query fails), if it isn't provided, find it.
- `Source(Option<u32>)` - A Source response with optionally, the id (if the id is present and the response id is not the
same, the query fails), if it isn't provided, find it.
- `GoldSrc(bool)` - A GoldSrc response with the option to enforce the obsolete A2S_INFO response.
Fixed Source multi-packet response crash due to when a certain app with a certain protocol doesn't have the Size field.
Fixed Source multi-packet response crash due to when a certain app with a certain protocol doesn't have the Size
field.
Reduced Valve Protocol `PACKET_SIZE` to be as specified from 2048 to 1400.
[Counter-Strike: Condition Zero](https://store.steampowered.com/app/80/CounterStrike_Condition_Zero/) implementation.
[Day of Defeat](https://store.steampowered.com/app/30/Day_of_Defeat/) implementation.
Games besides CSGO and TS now have the same response structure.
# 0.0.4 - 23/10/2022
Queries now support DNS resolve.
Changed uses a bit, example: from `use gamedig::valve::ValveProtocol::query` to `use gamedig::protocols::valve::query`.
Changed uses a bit, example: from `use gamedig::valve::ValveProtocol::query`
to `use gamedig::protocols::valve::query`.
Changed Valve Protocol Query parameters to (ip, port, app, gather_settings), changes include:
- the app is now optional, being None means to anonymously query the server.
- gather_settings is now also an optional, being None means all query settings.
@ -405,12 +539,15 @@ Better bad game error.
[Alien Swarm: Reactive Drop](https://store.steampowered.com/app/563560/Alien_Swarm_Reactive_Drop/) implementation.
[Insurgency](https://store.steampowered.com/app/222880/Insurgency/) implementation.
[Insurgency: Sandstorm](https://store.steampowered.com/app/581320/Insurgency_Sandstorm/) implementation.
[Insurgency: Modern Infantry Combat](https://store.steampowered.com/app/17700/INSURGENCY_Modern_Infantry_Combat/) implementation (not tested).
[Insurgency: Modern Infantry Combat](https://store.steampowered.com/app/17700/INSURGENCY_Modern_Infantry_Combat/)
implementation (not tested).
# 0.0.3 - 22/10/2022
Valve protocol now properly supports multi-packet responses (compressed ones not tested).
CSGO, TF2 and TS now have independent Responses, if you want a generic one, query the protocol.
[Counter Strike: Source](https://store.steampowered.com/app/240/CounterStrike_Source/) implementation (if protocol is 7, queries with multi-packet responses will crash).
[Counter Strike: Source](https://store.steampowered.com/app/240/CounterStrike_Source/) implementation (if protocol is 7,
queries with multi-packet responses will crash).
[Day of Defeat: Source](https://store.steampowered.com/app/300/Day_of_Defeat_Source/) implementation.
[Garry's Mod](https://store.steampowered.com/app/4000/Garrys_Mod/) implementation.
[Half-Life 2 Deathmatch](https://store.steampowered.com/app/320/HalfLife_2_Deathmatch/) implementation.
@ -418,16 +555,20 @@ CSGO, TF2 and TS now have independent Responses, if you want a generic one, quer
[Left 4 Dead 2](https://store.steampowered.com/app/550/Left_4_Dead_2/) implementation.
# 0.0.2 - 20/10/2022
Further implementation of the Valve protocol (PLAYERS and RULES queries).
[Counter Strike: Global Offensive](https://store.steampowered.com/app/730/CounterStrike_Global_Offensive/) implementation.
[Counter Strike: Global Offensive](https://store.steampowered.com/app/730/CounterStrike_Global_Offensive/)
implementation.
[The Ship](https://developer.valvesoftware.com/wiki/The_Ship) implementation.
The library now has error handling.
# 0.0.1 - 16/10/2022
The first usable version of the crate, yay!
It brings:
Initial implementation of the [Valve server query protocol](https://developer.valvesoftware.com/wiki/Server_queries).
Initial [Team Fortress 2](https://en.wikipedia.org/wiki/Team_Fortress_2) support.
# 0.0.0 - 15/10/2022
The first *markdown*, the crate is unusable as it doesn't contain anything helpful.

37
crates/lib/README.md
View file

@ -28,23 +28,30 @@
**Warning**: This project goes through frequent API breaking changes and hasn't been thoroughly tested.
## Community
Checkout the GameDig Community Discord Server [here](https://discord.gg/NVCMn3tnxH).
Note that it isn't be a replacement for GitHub issues, if you have found a problem
within the library or want to request a feature, it's better to do so here rather than
on Discord.
## Usage
Minimum Supported Rust Version is `1.65.0` and the code is cross-platform.
Pick a game/service/protocol (check the [GAMES](https://github.com/gamedig/rust-gamedig/blob/main/GAMES.md), [SERVICES](https://github.com/gamedig/rust-gamedig/blob/main/SERVICES.md) and [PROTOCOLS](https://github.com/gamedig/rust-gamedig/blob/main/PROTOCOLS.md) files to see the currently supported ones), provide the ip and the port (be aware that some game servers use a separate port for the info queries, the port can also be optional if the server is running the default ports) then query on it.
Pick a game/service/protocol (check
the [GAMES](https://github.com/gamedig/rust-gamedig/blob/main/GAMES.md), [SERVICES](https://github.com/gamedig/rust-gamedig/blob/main/SERVICES.md)
and [PROTOCOLS](https://github.com/gamedig/rust-gamedig/blob/main/PROTOCOLS.md) files to see the currently supported
ones), provide the ip and the port (be aware that some game servers use a separate port for the info queries, the port
can also be optional if the server is running the default ports) then query on it.
[Team Fortress 2](https://store.steampowered.com/app/440/Team_Fortress_2/) query example:
```rust
use gamedig::games::teamfortress2;
fn main() {
let response = teamfortress2::query(&"127.0.0.1".parse().unwrap(), None);
// None is the default port (which is 27015), could also be Some(27015)
// None is the default port (which is 27015), could also be Some(27015)
match response { // Result type, must check what it is...
Err(error) => println!("Couldn't query, error: {}", error),
@ -52,7 +59,9 @@ fn main() {
}
}
```
Response (note that some games have a different structure):
```json5
{
protocol: 17,
@ -72,22 +81,34 @@ Response (note that some games have a different structure):
steam_id: Some(69753253289735296),
tv_port: None,
tv_name: None,
keywords: Some("alltalk,nocrits"),
keywords: Some(
"alltalk,nocrits"
),
rules: [
"mp_autoteambalance": "1",
"mp_maxrounds": "5",
"mp_autoteambalance"
:
"1",
"mp_maxrounds"
:
"5",
//....
]
}
```
Want to see more examples? Checkout the [examples](https://github.com/gamedig/rust-gamedig/tree/main/crates/lib/examples) folder.
Want to see more examples? Checkout
the [examples](https://github.com/gamedig/rust-gamedig/tree/main/crates/lib/examples) folder.
## Documentation
The documentation is available at [docs.rs](https://docs.rs/gamedig/latest/gamedig/).
Curious about the history and what changed between versions? Everything is in the [CHANGELOG](https://github.com/gamedig/rust-gamedig/blob/main/crates/lib/CHANGELOG.md) file.
Curious about the history and what changed between versions? Everything is in
the [CHANGELOG](https://github.com/gamedig/rust-gamedig/blob/main/crates/lib/CHANGELOG.md) file.
## Contributing
If you want to see your favorite game/service being supported here, open an issue, and I'll prioritize it (or do a pull request if you want to implement it yourself)!
If you want to see your favorite game/service being supported here, open an issue, and I'll prioritize it (or do a pull
request if you want to implement it yourself)!
Before contributing please read [CONTRIBUTING](https://github.com/gamedig/rust-gamedig/blob/main/CONTRIBUTING.md).