deckgym-core is a high-performance Rust library designed for simulating Pokémon TCG Pocket games. It features a command-line interface (CLI) capable of running 10,000 simulations in approximately 3 seconds. This is the library that powers https://www.deckgym.com.

Its mission is to elevate the competitive TCG Pocket scene by helping players optimize their decks through large-scale simulations.

Join our Discord: https://discord.gg/ymxXHrzhak!

The CLI runs simulations between two decks in DeckGym Format. To create these files, build your decks in https://www.deckgym.com/builder, select Share > Copy as Text, and save the content as a text file.

We already provide several example decks in the repo you can use to get started. For example, to face off a VenusaurEx-ExeggutorEx deck with a Weezing-Arbok deck 1,000 times, run:

cargo run simulate example_decks/venusaur-exeggutor.txt example_decks/weezing-arbok.txt --num 1000 -v

The TUI provides an interactive way to view and replay games with a visual representation of the game state.

To use the TUI, you need to enable the tui feature:

cargo run --bin tui --features tui -- example_decks/venusaur-exeggutor.txt example_decks/weezing-arbok.txt --players e,e

• ↑/↓/Space: Navigate between game states (forward/backward)
• PageUp/PageDown: Scroll through battle log
• A/D: Scroll through your hand cards
• Shift+A/Shift+D: Scroll through opponent's hand cards
• Q/Esc: Quit

New to Open Source? See CONTRIBUTING.md.

The main contribution is to implement more cards, basically their attack and abilities logic. This makes the cards eligible for simulation and thus available for use in https://www.deckgym.com.

See the Claude SKILL.md describing how to implement cards. It's good documentation for humans and AIs alike.

Once you have Rust installed (see https://www.rust-lang.org/tools/install) you should be able to use the following commands from the root of the repo:

Running Automated Test Suite

cargo test

Running Benchmarks

cargo bench

Running Main Script

cargo run simulate example_decks/venusaur-exeggutor.txt example_decks/weezing-arbok.txt --num 1000 --players r,r
cargo run simulate example_decks/venusaur-exeggutor.txt example_decks/weezing-arbok.txt --num 1 --players r,r -vv
cargo run simulate example_decks/venusaur-exeggutor.txt example_decks/weezing-arbok.txt --num 1 --players r,r -vvvv
cargo run optimize example_decks/incomplete-chari.txt A2147,A2148 example_decks/ --num 10 --players e,e -v

Card Search Tool

The repository includes a search utility that's particularly useful for agentic AI applications, as reading the complete database.json file (which contains all card data) often exceeds context limits.

# Search for cards by name
cargo run --bin search "Charizard"

# Search for cards with specific attacks
cargo run --bin search "Venusaur" --attack "Giant Bloom"

Card Implementation Status Tool

Check which cards are fully implemented versus which are missing attack effects, abilities, or trainer logic. This tool helps contributors identify cards that need implementation work.

# Show all cards with their implementation status
cargo run --bin card_status

# Show only incomplete cards
cargo run --bin card_status -- --incomplete-only

# Get the first incomplete card (useful for automation)
cargo run --bin card_status -- --first-incomplete

The tool displays a summary showing total cards, completion percentage, and a breakdown of missing implementations by type (attacks, abilities, tools, trainer logic).

Setting Up Git Hooks (Optional)

The repository includes a pre-commit hook that ensures code quality by automatically fixing issues and running tests before each commit. To enable it:

git config core.hooksPath .githooks

The pre-commit hook runs:

1. cargo clippy --fix --allow-dirty --features tui -- -D warnings - Auto-fixes linting issues
2. cargo fmt - Auto-formats code
3. git add -u - Adds clippy and formatting fixes to the commit
4. cargo test --features tui - Runs the full test suite (fails commit if tests fail)

This helps maintain code quality and prevents broken commits, but it's optional and each developer can choose whether to enable it.

Generating database.rs

Ensure database.json is up-to-date with latest data. Mock the get_card_by_enum in database.rs with a _ => panic so that it compiles mid-way through the generation.

cargo run --bin card_enum_generator > tmp.rs && mv tmp.rs src/card_ids.rs && cargo fmt

Then temporarily edit database.rs for _ to match Bulbasaur (this is so that the next code can compile-run).

cargo run --bin card_enum_generator -- --database > tmp.rs && mv tmp.rs src/database.rs && cargo fmt

Profiling Main Script

cargo install flamegraph
sudo cargo flamegraph --root --dev -- simulate example_decks/venusaur-exeggutor.txt example_decks/weezing-arbok.txt --num 1000 && open flamegraph.svg