Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status

HearthSim is a generic Hearthstone game simulator and AI, designed to run large numbers of simulated AI vs AI games in order to test and understand the values of various game mechanics and cards.

The code has two main components: the game mechanics and the AI.

Game Mechanics

The game mechanics include the implementation of individual cards as well as the turn based draw card, use card, and attack mechanisms.

The state of the game is represented in with the BoardState class. The BoardState is the combined states of: hero state, friendly minions, enemy hero state, enemy minions, the cards in the hero's hand, and how many cards have been drawn from the deck. All actions in the game are represented as changes to the given BoardState.

Each card and minion is modeled as a derivative of the Card class. The job of each card is to manipulate the BoardState upon its use, either from the hero's hand or from the board as a minion.

Finally, there is the BoardStateFactory class, whose job is to recursively generate all possible BoardStates resulting from taking all possibles actions from a single starting BoardState.

AI Model

Detailed AI model descrition can be found here.

Addendum I: Divine Shield modeling
Addendum II: Random effects modeling

The essence of the AI model is the score function, which is a function of BoardState. For each BoardState generated by the BoardStateFactory, the AI determines the score and picks the chain of BoardStates resulting in the highest score as its play. The difference in AI really just comes down to the difference in the scoring function it uses.

Running Simulations

Pre-compiled GUI

Pre-compiled versions can be downloaded from HearthSim downloads page.

HearthSim GUI

Command line

There is an example simulation setup in the example directory. You can run the project easily by executing:

./gradlew runSim

and configure the simulation parameter file within

The GUI can be run via

./gradlew runGui

Some Results

You can find some simulation results HearthSim board or on my blog.

Effect of The Coin
Effect of direct damage spells
Effect of taunts
Effect of divine shield
Effect of additional card draw

Some Benchmarks

Simulations have been run on Digital Ocean machines for some performance benchmarks. Currently the simulations have been run once, with no variation in decks/ai/etc. Eventually we would like to keep track of performance with each release, and perform more varied testing with different BoardStateFactories etc. Decks were always deck0.hsdeck and deck1.hsdeck from example1.

Machine 1

DigitalOcean 1 CPU, 512MB Ram

  • CPU op-mode(s): 32-bit, 64-bit
  • CPU(s): 1
  • Thread(s) per core: 1
  • Vendor ID: GenuineIntel
  • CPU MHz: 2399.998
  • L1d cache: 32K
  • L1i cache: 32K
  • L2 cache: 256K
  • L3 cache: 15360K
Test 1
  • num_simulations: 1000
  • num_threads: 4
  • average time per game: 4.14 seconds
Test 2
  • num_simulations: 1000
  • num_threads: 1
  • average time per game: 5.73 seconds
Machine 2

DigitalOcean 4 CPU, 8GB Ram

  • Architecture: x86_64
  • CPU op-mode(s): 32-bit, 64-bit
  • CPU(s): 4
  • Thread(s) per core: 1
  • Vendor ID: GenuineIntel
  • CPU MHz: 2399.998
  • L1d cache: 32K
  • L1i cache: 32K
  • L2 cache: 256K
  • L3 cache: 15360K
Test 1
  • num_simulations: 100
  • num_threads: 4
  • average time per game: 1.58 seconds
Test 2
  • num_simulations: 10
  • num_threads: 1
  • average time per game: 5.58 seconds


To contribute, follow the usual procedure: fork, make changes, and submit a pull request.


YourKit supports the HearthSim project with its full-featured Java Profiler.

YourKit, LLC is the creator of YourKit Java Profiler and YourKit .NET Profiler, innovative and intelligent tools for profiling Java and .NET applications.



Generic Hearthstone game simulator







No releases published


No packages published