| Name | shroudstone JSON |
| Version |
0.2.7
JSON |
| download |
| home_page | None |
| Summary | Python utilities for working with Stormgate replays |
| upload_time | 2024-10-20 12:14:23 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4,>=3.8 |
| license | None |
| keywords |
stormgate
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# shroudstone
[](https://pypi.org/project/shroudstone/)
Shroudstone is principally a tool to automatically rename replays of your
Stormgate ladder games.
Say goodbye to
CL44420-2024.02.03-08.28.SGReplay
and say hello to
2024-02-03 08.28 L 03m03s Pox IvI Veni Vidi Vici - Broken Crown.SGReplay
Shroudstone also acts as a general Python/CLI toolkit for working with
Stormgate replays - right now it's probably not useful for much else, but
hopefully it will grow over time :)
## Caveats
Shroudstone works by decoding the contents of replay files, which contain
little more than the raw actions of each player. This means some of the
information that is used is technically a guess, and might not be 100%
accurate:
- 1v1 match results are determined by who leaves the game first. In most ladder
games this is the loser "gging out"; but if you e.g. win by destroying all
your opponent's buildings and then leave the game before your opponent,
Shroudstone will incorrectly mark your game as a loss.
- Likewise, game durations are determined by the time at which the first player
leaves the game - this can also be incorrect in the case of a win by
elimination or in non-1v1 games.
Previously, Shroudstone used data obtained from the Stormgate World API to fill
these gaps (in the case of 1v1 ladder games). Unfortunately, Frost Giant are no
longer providing access to this data to the community, so this will no
longer be possible going forward. See [Stormgate World's
post](https://stormgateworld.com/api-restrictions/) on the matter for more
information. Thanks to the Stormgate World team (and contributors) for their
great work, it was cool even if short-lived.
## Installation & Usage
### On Windows: .exe download
Simply [download the latest standalone
executable](https://github.com/acarapetis/shroudstone/releases/latest/download/shroudstone.exe)
and double-click it to launch the user interface. (The first time you do,
you'll probably get a Windows Defender SmartScreen popup - you did just
download some random program from the internet, after all! If you trust me,
click "More Info" and then "Run Anyway".)
Assuming you have a normal Stormgate install with a single account, everything
should be autodetected and you'll be faced with the main user interface:
Just click "Rename My Replays Now" to run the renaming process on your existing replays.
If you enable the checkbox "Automatically rename new replays" and leave
Shroudstone open in the background while you play, then the process will run
every 30 seconds, renaming new replays as they are created.
### On Windows: Using pip
1. Install Python 3.11 using
[the Microsoft Store](https://apps.microsoft.com/detail/9nrwmjp3717k) or the
[official installer](https://www.python.org/downloads/). If using the
official installer, make sure to check the "add python.exe to PATH" option.
2. Open Command Prompt and type `pip install shroudstone` to install shroudstone.
3. You can now invoke `python -m shroudstone gui` from the command line to
launch the user interface, or `python -m shroudstone --help` for usage
instructions for the command-line interface.
If you're already a WSL user, you should also be able to `pip install
shroudstone` inside your WSL session and have at least the CLI work.
### On Linux: using pip
If you're running Stormgate on Linux+Steam+Proton, this should also work for
you!
1. Ensure python 3.8+ and pip are installed using your system package manager.
(e.g. on Ubuntu, run `sudo apt install python3-pip`.)
2. Run `pip install shroudstone` in a terminal.
3. Launch the GUI with `shroudstone gui`, or check out `shroudstone --help` if
you want to use the CLI.
### Updating
Regardless of your operating system, if you installed using `pip install
shroudstone` originally, you can update to the newest version with a simple
`pip install --upgrade shroudstone`.
If you downloaded the .exe, just download a new one to replace it!
## Notes
- Stormgate names your replays using your local time. After renaming, the times
will be in the UTC timezone, as on the Stormgate World leaderboard.
- Your settings are saved in %LOCALAPPDATA%/shroudstone/config.json on Windows
or ~/.local/share/shroudstone/config.json on Linux/WSL. Note that if you're
using Python from the Microsoft Store, this %LOCALAPPDATA% might not be
what you expect - use `python -m shroudstone config-path` to find out exactly
where it is.
- If using the CLI, your replay directory path and replay format
strings can be configured by passing command-line options to `python -m
shroudstone rename-replays`; but you probably want to use the config file
instead so you don't have to provide them every time. Use `python -m
shroudstone edit-config` to edit the configuration file.
## Customizing replay names
You can customize the filenames of your renamed replays by editing the format
string in your configuration, either through the GUI or in your config file.
The default format string for 1v1 matches is
{time:%Y-%m-%d %H.%M} {result:.1} {duration} {us} {f1:.1}v{f2:.1} {them} - {map_name}.SGReplay
which results in e.g.
2024-02-03 08.28 L 03m03s Pox IvI Veni Vidi Vici - Broken Crown.SGReplay
Note the usage of `:.1` to take just the first letter of the race and result strings.
Format strings for 1v1 matches can use the following values:
* `us` (str): Your nickname (as it appeared in the replay)
* `them` (str): Opponent nickname (as it appeared in the replay)
* `f1` (str): Faction/Race you played (Vanguard or Infernals or Maloc or Blockade)
* `f2` (str): Faction/Race opponent played
* `time` (datetime): Creation time of match
* `duration` (str): Game duration (e.g. "15m10s")
* `result` (str): Your game result (Win, Loss, Undecided)
* `map_name` (str): Name of the map on which the game was played (extracted from replay file)
* `build_number` (int): Build number of Stormgate version on which the game was played (extracted from replay file)
For other matches (e.g. co-op), the default format string is
{time:%Y-%m-%d %H.%M} {duration} {players_with_factions} - {map_name}.SGReplay
which results in e.g.
2024-02-03 01:23 20m10s Pox M, Alice B, Bob M - WreckHavoc.SGReplay
Format strings for generic matches can use the following values:
* `players` (str): Comma-separated list of player nicknames
* `players_with_factions` (str): Comma-separated list of player nicknames, each
followed by the initial letter of their faction (e.g. M for Maloc)
* `time` (datetime): Creation time of match
* `duration` (str): Game duration (e.g. "15m10s")
* `map_name` (str): Name of the map on which the game was played (extracted from replay file)
* `build_number` (int): Build number of Stormgate version on which the game was played (extracted from replay file)
## Contributing
Contributions are welcome - feel free to open a PR, or message Pox on the
Stormgate Discord if you want to discuss with me first.
### Developing
Assuming you have python 3.8+ and pip installed on your system, all you need to
do to start working on shroudstone is to clone the repository and install the
python package in *development mode*. [See
here](https://setuptools.pypa.io/en/latest/userguide/development_mode.html) for
more information, or follow this recipe to get started using a virtual
environment:
Create a working directory:
```
mkdir shroudstone-workspace
cd shroudstone-workspace
```
Download the code and setup a python virtual environment:
```
python -m venv .venv
git clone https://github.com/acarapetis/shroudstone.git
```
Finally, install and run the code:
```
.venv/bin/pip3 install -e shroudstone/
.venv/bin/shroudstone
```
To run the tests, just install and invoke pytest:
```
.venv/bin/pip3 install pytest
.venv/bin/python -m pytest
````
Note that the tests require python 3.9 or higher.
Raw data
{
"_id": null,
"home_page": null,
"name": "shroudstone",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "Stormgate",
"author": null,
"author_email": "Anthony Carapetis <anthony.carapetis@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/71/91/8b0211bee69d1618a811f0412477590c0886ee51531ca06e249bef0961b8/shroudstone-0.2.7.tar.gz",
"platform": null,
"description": "# shroudstone\n\n[](https://pypi.org/project/shroudstone/)\n\nShroudstone is principally a tool to automatically rename replays of your\nStormgate ladder games.\n\nSay goodbye to \n\n CL44420-2024.02.03-08.28.SGReplay\n\nand say hello to\n\n 2024-02-03 08.28 L 03m03s Pox IvI Veni Vidi Vici - Broken Crown.SGReplay\n\nShroudstone also acts as a general Python/CLI toolkit for working with\nStormgate replays - right now it's probably not useful for much else, but\nhopefully it will grow over time :)\n\n## Caveats\n\nShroudstone works by decoding the contents of replay files, which contain\nlittle more than the raw actions of each player. This means some of the\ninformation that is used is technically a guess, and might not be 100%\naccurate:\n\n- 1v1 match results are determined by who leaves the game first. In most ladder\n games this is the loser \"gging out\"; but if you e.g. win by destroying all\n your opponent's buildings and then leave the game before your opponent,\n Shroudstone will incorrectly mark your game as a loss.\n- Likewise, game durations are determined by the time at which the first player\n leaves the game - this can also be incorrect in the case of a win by\n elimination or in non-1v1 games.\n\nPreviously, Shroudstone used data obtained from the Stormgate World API to fill\nthese gaps (in the case of 1v1 ladder games). Unfortunately, Frost Giant are no\nlonger providing access to this data to the community, so this will no\nlonger be possible going forward. See [Stormgate World's\npost](https://stormgateworld.com/api-restrictions/) on the matter for more\ninformation. Thanks to the Stormgate World team (and contributors) for their\ngreat work, it was cool even if short-lived.\n\n## Installation & Usage\n\n### On Windows: .exe download\n\nSimply [download the latest standalone\nexecutable](https://github.com/acarapetis/shroudstone/releases/latest/download/shroudstone.exe)\nand double-click it to launch the user interface. (The first time you do,\nyou'll probably get a Windows Defender SmartScreen popup - you did just\ndownload some random program from the internet, after all! If you trust me,\nclick \"More Info\" and then \"Run Anyway\".)\n\nAssuming you have a normal Stormgate install with a single account, everything\nshould be autodetected and you'll be faced with the main user interface:\n\n\n\nJust click \"Rename My Replays Now\" to run the renaming process on your existing replays.\n\nIf you enable the checkbox \"Automatically rename new replays\" and leave\nShroudstone open in the background while you play, then the process will run\nevery 30 seconds, renaming new replays as they are created.\n\n### On Windows: Using pip\n\n1. Install Python 3.11 using\n [the Microsoft Store](https://apps.microsoft.com/detail/9nrwmjp3717k) or the\n [official installer](https://www.python.org/downloads/). If using the\n official installer, make sure to check the \"add python.exe to PATH\" option.\n2. Open Command Prompt and type `pip install shroudstone` to install shroudstone.\n3. You can now invoke `python -m shroudstone gui` from the command line to\n launch the user interface, or `python -m shroudstone --help` for usage\n instructions for the command-line interface.\n\nIf you're already a WSL user, you should also be able to `pip install\nshroudstone` inside your WSL session and have at least the CLI work.\n\n### On Linux: using pip\n\nIf you're running Stormgate on Linux+Steam+Proton, this should also work for\nyou!\n\n1. Ensure python 3.8+ and pip are installed using your system package manager.\n (e.g. on Ubuntu, run `sudo apt install python3-pip`.)\n2. Run `pip install shroudstone` in a terminal.\n3. Launch the GUI with `shroudstone gui`, or check out `shroudstone --help` if\n you want to use the CLI.\n\n### Updating\n\nRegardless of your operating system, if you installed using `pip install\nshroudstone` originally, you can update to the newest version with a simple\n`pip install --upgrade shroudstone`.\n\n\nIf you downloaded the .exe, just download a new one to replace it!\n\n\n## Notes\n- Stormgate names your replays using your local time. After renaming, the times\n will be in the UTC timezone, as on the Stormgate World leaderboard.\n- Your settings are saved in %LOCALAPPDATA%/shroudstone/config.json on Windows\n or ~/.local/share/shroudstone/config.json on Linux/WSL. Note that if you're\n using Python from the Microsoft Store, this %LOCALAPPDATA% might not be\n what you expect - use `python -m shroudstone config-path` to find out exactly\n where it is.\n- If using the CLI, your replay directory path and replay format\n strings can be configured by passing command-line options to `python -m\n shroudstone rename-replays`; but you probably want to use the config file\n instead so you don't have to provide them every time. Use `python -m\n shroudstone edit-config` to edit the configuration file.\n\n\n## Customizing replay names\n\nYou can customize the filenames of your renamed replays by editing the format\nstring in your configuration, either through the GUI or in your config file.\n\nThe default format string for 1v1 matches is\n\n {time:%Y-%m-%d %H.%M} {result:.1} {duration} {us} {f1:.1}v{f2:.1} {them} - {map_name}.SGReplay\n\nwhich results in e.g.\n\n 2024-02-03 08.28 L 03m03s Pox IvI Veni Vidi Vici - Broken Crown.SGReplay\n\nNote the usage of `:.1` to take just the first letter of the race and result strings.\n\nFormat strings for 1v1 matches can use the following values:\n\n* `us` (str): Your nickname (as it appeared in the replay)\n* `them` (str): Opponent nickname (as it appeared in the replay)\n* `f1` (str): Faction/Race you played (Vanguard or Infernals or Maloc or Blockade)\n* `f2` (str): Faction/Race opponent played\n* `time` (datetime): Creation time of match\n* `duration` (str): Game duration (e.g. \"15m10s\")\n* `result` (str): Your game result (Win, Loss, Undecided)\n* `map_name` (str): Name of the map on which the game was played (extracted from replay file)\n* `build_number` (int): Build number of Stormgate version on which the game was played (extracted from replay file)\n\nFor other matches (e.g. co-op), the default format string is\n\n {time:%Y-%m-%d %H.%M} {duration} {players_with_factions} - {map_name}.SGReplay\n\nwhich results in e.g.\n\n 2024-02-03 01:23 20m10s Pox M, Alice B, Bob M - WreckHavoc.SGReplay\n\nFormat strings for generic matches can use the following values:\n\n* `players` (str): Comma-separated list of player nicknames\n* `players_with_factions` (str): Comma-separated list of player nicknames, each\n followed by the initial letter of their faction (e.g. M for Maloc)\n* `time` (datetime): Creation time of match\n* `duration` (str): Game duration (e.g. \"15m10s\")\n* `map_name` (str): Name of the map on which the game was played (extracted from replay file)\n* `build_number` (int): Build number of Stormgate version on which the game was played (extracted from replay file)\n\n\n## Contributing\n\nContributions are welcome - feel free to open a PR, or message Pox on the\nStormgate Discord if you want to discuss with me first.\n\n### Developing\n\nAssuming you have python 3.8+ and pip installed on your system, all you need to\ndo to start working on shroudstone is to clone the repository and install the\npython package in *development mode*. [See\nhere](https://setuptools.pypa.io/en/latest/userguide/development_mode.html) for\nmore information, or follow this recipe to get started using a virtual\nenvironment:\n\nCreate a working directory:\n```\nmkdir shroudstone-workspace\ncd shroudstone-workspace\n```\nDownload the code and setup a python virtual environment:\n```\npython -m venv .venv\ngit clone https://github.com/acarapetis/shroudstone.git\n```\nFinally, install and run the code:\n```\n.venv/bin/pip3 install -e shroudstone/\n.venv/bin/shroudstone\n```\nTo run the tests, just install and invoke pytest:\n```\n.venv/bin/pip3 install pytest\n.venv/bin/python -m pytest\n````\nNote that the tests require python 3.9 or higher.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python utilities for working with Stormgate replays",
"version": "0.2.7",
"project_urls": {
"Source": "https://github.com/acarapetis/shroudstone"
},
"split_keywords": [
"stormgate"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f03cffbe458ff9a5b2581150628f6d169150138013e37dd22eb756a1882c22fc",
"md5": "20cfee0886718d8b9059b88a31db360f",
"sha256": "94bfb98be7746227d80f58c2710f68efa60e135f48d6bf3038270581b35fc6f2"
},
"downloads": -1,
"filename": "shroudstone-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "20cfee0886718d8b9059b88a31db360f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 50137,
"upload_time": "2024-10-20T12:14:22",
"upload_time_iso_8601": "2024-10-20T12:14:22.333596Z",
"url": "https://files.pythonhosted.org/packages/f0/3c/ffbe458ff9a5b2581150628f6d169150138013e37dd22eb756a1882c22fc/shroudstone-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "71918b0211bee69d1618a811f0412477590c0886ee51531ca06e249bef0961b8",
"md5": "24443f6a230423b04e056ea7cf70a20c",
"sha256": "cd88cb1a0b65fd1ce07394d633b1fb3036806db03f0b11d8a3ed123c5069ea3b"
},
"downloads": -1,
"filename": "shroudstone-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "24443f6a230423b04e056ea7cf70a20c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 1419601,
"upload_time": "2024-10-20T12:14:23",
"upload_time_iso_8601": "2024-10-20T12:14:23.517397Z",
"url": "https://files.pythonhosted.org/packages/71/91/8b0211bee69d1618a811f0412477590c0886ee51531ca06e249bef0961b8/shroudstone-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 12:14:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "acarapetis",
"github_project": "shroudstone",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shroudstone"
}
