A C++23 Hearthstone simulator with C++, Python, console, and tooling interfaces
RosettaStone models Hearthstone's normal play mode and Battlegrounds. The core simulator is shared by the C++ API, the pyRosetta Python extension, and the console and utility programs.
- Provides a reusable C++23 Hearthstone simulator library.
- Models cards, entities, zones, tasks, triggers, auras, and game flow.
- Keeps normal play and Battlegrounds in separate simulator trees.
- Exposes the simulator to Python through pybind11.
- Includes console and utility executables, card data, and C++ and Python tests.
For deeper design details, see ARCHITECTURE.md. For coding-agent rules, see AGENTS.md.
- A C++23 compiler
- CMake 3.31.6 or later
- vcpkg with
VCPKG_ROOTset - Python 3.12 or later for the Python API and tests
- Git
git clone https://github.com/utilForever/RosettaStone.git --recursive
cd RosettaStonecmake -S . -B build \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake --build build --config ReleasemacOS, Linux, and WSL:
./build/bin/UnitTestsWindows release builds:
.\build\bin\Release\UnitTests.exepython -m pip install -r requirements.txt
python -m pip install .
python -m pytest Tests/PythonTests/| Area | Paths | Purpose |
|---|---|---|
| Core C++ API | Includes/Rosetta/ |
Public simulator headers and models |
| Core implementation | Sources/Rosetta/ |
Game flow, loaders, tasks, cards, auras, and triggers |
| Battlegrounds | Includes/Rosetta/Battlegrounds/, Sources/Rosetta/Battlegrounds/ |
Battlegrounds-specific simulation |
| Python API | Extensions/RosettaPython/ |
pybind11 bindings for pyRosetta |
| Applications | Extensions/RosettaConsole/, Extensions/RosettaTool/ |
Console and utility executables |
| Tests | Tests/UnitTests/, Tests/PythonTests/ |
C++ doctest and Python pytest coverage |
| Data | Resources/, Datas/ |
Card metadata and fixtures |
| Documentation | Documents/ |
Build, API, card, task, and contribution guides |
The full architecture guide explains game flow, the runtime model, card loading, effect timing, module boundaries, and Python API synchronization.
Implementation progress is generated from the Implemented column in the card lists. Run python Scripts/card_stats.py after updating a list.
| Set | Implemented | Total | Progress |
|---|---|---|---|
| Core | 247 | 250 | 98.8% |
| Forged in the Barrens | 139 | 170 | 81.8% |
| United in Stormwind | 60 | 170 | 35.3% |
| Fractured in Alterac Valley | 61 | 170 | 35.9% |
| Voyage to the Sunken City | 22 | 170 | 12.9% |
| Murder at Castle Nathria | 17 | 170 | 10% |
| March of the Lich King | 0 | 1 | 0% |
| Total | 546 | 1101 | 49.6% |
| Set | Implemented | Total | Progress |
|---|---|---|---|
| Legacy | 167 | 167 | 100% |
| Expert1 | 245 | 245 | 100% |
| Demon Hunter Initiate | 20 | 20 | 100% |
| Curse of Naxxramas | 30 | 30 | 100% |
| Goblins vs Gnomes | 8 | 123 | 6.5% |
| Blackrock Mountain | 31 | 31 | 100% |
| The Grand Tournament | 11 | 132 | 8.3% |
| The League of Explorers | 45 | 45 | 100% |
| Whispers of the Old Gods | 8 | 134 | 6% |
| One Night in Karazhan | 45 | 45 | 100% |
| Mean Streets of Gadgetzan | 3 | 132 | 2.3% |
| Journey to Un'Goro | 10 | 135 | 7.4% |
| Knights of the Frozen Throne | 6 | 135 | 4.4% |
| Kobolds & Catacombs | 7 | 135 | 5.2% |
| The Witchwood | 8 | 135 | 5.9% |
| The Boomsday Project | 4 | 136 | 2.9% |
| Rastakhan's Rumble | 7 | 135 | 5.2% |
| Rise of Shadows | 136 | 136 | 100% |
| Saviors of Uldum | 134 | 135 | 99.3% |
| Descent of Dragons | 140 | 140 | 100% |
| Galakrond's Awakening | 21 | 35 | 60% |
| Ashes of Outland | 82 | 135 | 60.7% |
| Scholomance Academy | 78 | 135 | 57.8% |
| Madness at the Darkmoon Faire | 79 | 170 | 46.5% |
| Total | 1325 | 2801 | 47.3% |
| Set | Implemented | Total | Progress |
|---|---|---|---|
| Vanilla | 382 | 382 | 100% |
| Total | 382 | 382 | 100% |
See the ability list and task list for mechanic and task support.
Use CMake targets as the source of truth and run the narrowest checks that cover a change. The CI workflows build on Ubuntu, macOS, and Windows, run the C++ unit tests, install pyRosetta, and run the Python tests.
When changing public C++ behavior, keep Extensions/RosettaPython/ and Tests/PythonTests/ in sync. Treat Includes/Rosetta/RosettaStone.hpp as generated output.
See AGENTS.md for the repository workflow and Documents/Contributing.md for contribution guidelines.
RosettaStone is licensed under the GNU Affero General Public License v3.0.
RosettaStone is based on part of SabberStone's code.
Copyright © 2017-2021 SabberStone Team, darkfriend77, and rnilva
Copyright © 2017-2026 Chris Ohk
Hearthstone is an interactive game of Blizzard Entertainment, Inc. and all rights are reserved. Hearthstone is a registered trademark of Blizzard Entertainment, Inc. in the U.S. and/or other countries. This project is not affiliated with Blizzard Entertainment.
