|0.2.4||May 20, 2022|
|0.2.3||Mar 18, 2022|
|0.1.0||Oct 27, 2021|
#218 in Games
psbattletools is a command-line tool written in Rust for manipulating Pokémon Showdown battle logs.
psbattletools currently requires nightly Rust, since it uses Rust's built-in benchmarker. If you don't have nightly Rust, install
rustup, then run
rustup install nightly.
psbattletools itself is as simple as running
cargo install psbattletools.
Searching for battles
s subcommand allows you to search for battles; this is significantly faster than Showdown's built-in
/battlesearch functionality (TODO: add benchmark).
You must specify a username to search for, and a list of directories to search in (these will be searched recursively, ignoring non-JSON files). You may also specify any of the following options:
-f: search only for battles that ended by forfeit
-w: search only for battles that the specified username won
psbattletools search --wins-only Annika logs/2020-06/gen8randombattle logs/2020-05/gen8randombattle would search for [Gen 8] Random Battle battles won by Annika in May and June of 2020.
Calculating winrates and statistics
winrates) subcommand calculates the winrates (in percentage, raw games, and standard deviations) for each Pokémon used in a given format. Currently, usage stats are handled by other, closed-source scripts, but if there is demand for it I'm happy to consider implementing more complex statistics.
By default, this command prints a human-readable winrates format to standard output, but there are also options to produce CSVs (for easy consumption by scripts and programs), and/or write output to a file.
You must provide a list of directories to analyze, but
psbattletools statistics also accepts the following optional arguments:
--csv [path]: writes CSV output to the given file
--pretty [path]: writes human-readable (prettytable) output to the given file
--elo [ELO]: ignores battles where either player is below the given ELO rating at the start of the battle
--exclude [text]: ignores directories and JSON files whose names include the given text
psbattletools stats --pretty gen8randombattle-1500.txt --minimum-elo 1500 logs/2021-08/gen8randombattle would write winrates for [Gen 8] Random Battle games in August 2021 with 1500 ELO or higher as human-readable tables to the file
anonymize subcommand removes personally-identifying data from battle logs, while assigning each player a unique ID (so it's still possible to identify when two anonymous players are the same).
You must provide a list of directories containing JSON files to anonymize; all of the JSON battle logs in these directories will be anonymized, and directory structure will not be preserved in the output. This subcommand accepts only one argument, which must be specified:
--output [directory] (or
-o [directory]), which specifies the directory in which anonymized battle logs will be written.
For example, to write anonymized [Gen 8] Random Battle logs from June-August 2021 to the directory
anonymized/, you'd use the command
psbattletools anonymize -o anonymized logs/2021-06/gen8randombattle logs/2021-07/gen8randombattle logs/2021-08/gen8randombattle.
I welcome contributions to
psbattletools. There's currently no formal contribution guide, but pull requests are always welcome. If possible, make sure your code is
rustfmted and has unit test(s) to detect regressions and/or test added functionality.
Unit and integration tests can be run with
cargo test, and benchmarks can be run with
cargo bench. The following features may be enabled during benchmarks (with
cargo bench --features ...) to run additional benchmarks:
bench_old_battlesearchruns the same benchmark as is used for the integration benchmark of
psbattletools searchon my old
battlesearchprogram; this allows for direct performance comparisons. Don't enable this feature unless you have
bench_old_winratesruns the same benchmark as is used for the integration benchmark of
psbattletools statisticson my old
randbats-winratesprogram; this allows for direct performance comparisons. Don't enable this feature unless you have
bench_old_anonbattleruns the same benchmark as is used for the integration benchmark of
psbattletools anonymizeon my old
anonbattleprogram; this allows for direct performance comparisons. Don't enable this feature unless you have