A multiplayer card battle engine and Hearthstone simulator
Branch: master
Clone or download
Latest commit 7091a70 Feb 19, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.elasticbeanstalk Do these configuration settings even get read? Why not tell me if the… Jun 26, 2018
cards Fix #974 Feb 13, 2019
client Update event model Feb 2, 2019
cluster GSVB exploits Fel Reaver Feb 14, 2019
ddnsroute53 Warn if the correct args aren't specified Jan 4, 2019
docs Update documentation and include tweaks to TycheBehaviour Feb 13, 2019
game Further bump to the performance of the bot Feb 14, 2019
gradle/wrapper Pre vertx- and hazelcast- version upgrades Nov 30, 2018
launcher Fix deployment scripts Jan 22, 2019
net delete spurious file Feb 19, 2019
spellsource Bump version Feb 8, 2019
swagger-templates/java At least add the Maven publishing info Jan 2, 2019
vertx-sync Begin streamlining the server for tracing Dec 7, 2018
www Invites bugfixes Feb 18, 2019
.dockerignore Prepare for self-hosted infrastructure Jan 4, 2019
.gitignore Updates to readme and release notes Nov 30, 2018
.java-version Use JDK 11 in .java-version Jan 20, 2019
.travis.yml Give more time to execute travis test Dec 9, 2018
Dockerfile Bump version Feb 8, 2019
Dockerrun.aws.json Run the server on docker in ELB Nov 14, 2017
LICENSE.md Production tasks underway. Dec 9, 2017
README.md Fix #849, fix #850 Jan 5, 2019
build.gradle Bump version Feb 8, 2019
client.gradle At least add the Maven publishing info Jan 2, 2019
deploy.sh Bump version Feb 8, 2019
docker-compose.yml Use networks Feb 20, 2019
gradlew Pre vertx- and hazelcast- version upgrades Nov 30, 2018
gradlew.bat Pre vertx- and hazelcast- version upgrades Nov 30, 2018
idea-codestyle-scheme.xml Include IntelliJ code style Jan 20, 2019
server.sh Bump version Feb 8, 2019
settings.gradle Use a new Quasar implementation that supports JDK8+ Sep 5, 2018
setup.cfg Bump version Feb 8, 2019
setup.py Bump version Feb 8, 2019
swagger-api.yaml Update event model Feb 2, 2019
test.sh Update tests and dependency installation Jan 20, 2019



Build Status Discord Documentation

In-Game Screenshot

This is a simulator and game server for community and official Hearthstone cards.

Play Now: Download the Hidden Switch Launcher for Mac OS X or Windows to get a copy of the game client. Play online against others! No other installation required.

Developers: See this example notebook for how to simulate games.

Please see the Issues tab to report bugs or request functionality.


  1. Description
  2. AI Research FAQ
  3. Quick Start Python
  4. Quick Start Multiplayer
  5. Quick Start Contributing Cards
  6. Using the Command Line Simulator
  7. Automated Deckbuilding FAQ
  8. Getting started with Development on Windows
  9. Troubleshooting
  10. Contributing Cards


The Spellsource-Server project adapts and updates metastone, an unmaintained Hearthstone simulator, to fully support hosted, networked gameplay. It features rudimentary matchmaking, collection management and support for game mechanics that persist between matches. It currently covers 100% of Hearthstone cards, with a handful of bugs, plus hundreds of community cards.

The project also contains adapters for Amazon Elastic MapReduce for processor-intensive AI training. Please reach out to the developers in an issue if you'd like to learn more or to use part of our AWS budget for AI experimentation.

See the complete reference here.

AI Research FAQ

Please visit this FAQ for an example of interactively playing a match in Python using Spellsource. This example can help you get started poking around Spellsource.

Quick Start Python

The spellsource package creates a bridge with the Java-based Spellsource-Server engine. It provides a direct 1-to-1 mapping with the Java API.

You can explore commands available in the package using this command:

$ spellsource --help

Usage: spellsource [OPTIONS] COMMAND [ARGS]...

  --help  Show this message and exit.

  change-password       Changes a Spellsource user's password.
  create-user           Creates an AWS user named USERNAME.
  format-cards          Formats JSON card files.
  hearthcards-stubs     Creates stubs from the Hearthcards.
  hs-replay-matchups    Prints a table of HSReplay matchups in TSV format.
  image-stubs           Converts images to card stubs.
  markdown-to-textmesh  Renders a Markdown file to TextMesh markup.
  replicate-database    Replicates mongo databases.
  simulate              Run a simulation using AIs of a given deck matchup.
  update-dbf            Updates Hearthstone IDs.
  update-decklists      Updates the deck lists from Tempostorm.

You can also use the spellsource package programmatically. This requires Python 3 and Java 8 or higher (only Java 11 tested). To get started:

  1. Install a Java JDK.

    • On Windows: Visit this link for the latest OpenJDK builds, which we test on. Choose a java-11 ... msi link, like this one.
    • On macOS: Install brew, then brew cask install java.
  2. pip3 install spellsource to install the latest version of the package. To build from Git, use pip3 install -e . to install the package from the root of this repository, and run ./gradlew net:shadowJar to build the engine.

  3. Start a game and play it with the specified bots:

    from spellsource.context import Context
    from spellsource.playrandombehaviour import PlayRandomBehaviour
    with Context() as ctx:
        game_context = ctx.game.GameContext.fromTwoRandomDecks()
        behaviour1 = PlayRandomBehaviour()
        behaviour2 = PlayRandomBehaviour()
        game_context.setBehaviour(0, behaviour1.wrap(ctx))
        game_context.setBehaviour(1, behaviour2.wrap(ctx))
        assert game_context.updateAndGetGameOver()

Visit GameStateValueBehaviour to see an implementation of a complex AI bot in Python. This is a direct port of the Java code. Unfortunately, on the Python platform, remoting (accessing the Java engine) in the particular way this bot does is slow. To implement more sophisticated bots, consider adding a method to GameContext that will extract the exact data, in a binary format, that you need in your Python implementation, to reduce the communication overhead between Java and Python.

Quick Start Multiplayer

  1. Download the Hidden Switch Launcher for Mac OS X or Windows.
  2. Download the Spellsource Client from within the launcher and start it.
  3. Enter Quick Play to play against a bot, or Matchmaking to play against a random opponent.

Quick Start Contributing Cards

If you'd like to contributed or edit cards, write new game mechanics or improve the server, follow these instructions to install and run the server:

  1. Install the Java JDK from Oracle's website
  2. Clone this repository.
  3. To run the server locally, execute the following on a command prompt:
    • Linux/Mac OS X: Run ./gradlew net:local.
    • Windows: See the Getting started with Development on Windows guide below.
  4. Download the Hidden Switch Launcher for Mac OS X or Windows.
  5. Download the Spellsource Client from within the launcher and start it.
  6. Your game client will automatically detect your local server and connect to it, as long as the server is running before you start the client.

Automated Deckbuilding FAQ

Visit the Cluster README for some theory on automated deckbuilding and useful scripts and extensions for performing it with Spellsource.

Getting started with Development on Windows

  1. Windows Defender significantly slows down or fails install processes. To temporarily turn off Windows Defender, hit the Windows key, type Windows Defender and open the Windows Defender Security Center. 1. Then, visit the Virus & threat protection page, then Virus & threat protection settings, and turn off all protection modes. 2. Go back to the home page by clicking the Home icon on the left. Visit Firewall & network protection, then turn off firewall for both Private and Public networks. 3. You will be reminded to re-enable real-time protection at the end of this document.
  2. Hit Start, type PowerShell, right click on the Windows PowerShell result and choose Run as Administrator.
  3. From the chocolatey docs, we'll run the following commands:
    Set-ExecutionPolicy AllSigned;
    Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'));
    choco feature enable -n allowGlobalConfirmation;
    This installs chocolatey, the Windows development package manager.
  4. We'll now install basic development packages. This includes the MongoDB, Java 8 SDK, git and ConEmu, a great Windows terminal emulator.
    choco install chocolatey-core.extension git.install git-credential-manager-for-windows jdk8 conemu
    Then, install IntelliJ Idea Community Edition to edit the Spellsource-Server Java project. Since sometimes choco packages fail to install, you might need to manually install MongoDB, JDK8, and git.
  5. Exit Windows PowerShell
  6. Start ConEmu. If you're starting it for the first time, observe you can specify a startup task. Choose {Shells::PowerShell (Admin)}.
  7. Navigate to your preferred directory for cloning the GitHub repository using cd path\to\directory. In this example, we'll use your user's Documents folder. Then, clone the repository. It is strongly recommended to clone in order to get the latest updates, instead of using Download as zip... from the GitHub.com interface.
    cd Documents
    git clone https://github.com/hiddenswitch/Spellsource-Server.git
  8. Enter the directory with the code files in it with the following command. Whenever you want to execute commands on files located inside the code, you'll have to cd (change directory) into it.
    cd Spellsource-Server
  9. Start by running the tests that don't require networking behavior to verify your installation worked. To do this, execute the following command:
    ./gradlew game:test
    A lot of packages should install. You should observe no errors.
  10. If the tests pass, you're now ready to start the server.
    1. In one tab in ConEmu, cd into your Spellsource-Server directory. You'll see an example of this below. Then, start MongoDB with the commands:
      cd Spellsource-Server
      md -Force .\net\.mongo\db
      & "C:\Program Files\MongoDB\Server\3.6\bin\mongod" --dbpath .\net\.mongo\db
    2. Then, in another tab, start the server. cd into your Spellsource-Server directory and run the command:
      ./gradlew net:localWindows
  11. When making changes to the files in the cards directory, you will need to restart the server. To restart it, you need to send the correct command to shut down the server. Unfortunately, batch files do not generally support this command correctly. To shut down correctly, you must configure the SIGINT command in ConEmu. Never end execution by closing the console tab or Window. Instead, use ConEmu, and configure a hotkey to send the Break key. In ConEmu, you can do this by clicking the Hamburger menu in the upper right corner, choosing settings, and then configuring a break command as documented on StackOverflow.
  12. Install the Hidden Switch Launcher, start it, Download the latest client in it and start the client. It will automatically connect to the local server.


My download got interrupted in the launcher and it won't restart.

On Windows, delete the %APPDATA%\Hidden Switch Launcher directory. (Copy and paste this into your Explorer address bar or Ctrl+R and type, explorer %APPDATA%\Hidden Switch Launcher).

I receive an error about Weaponized Piñata when I try to run tests while contributing cards on Windows.

This message can be safely ignored.

Contributing Cards

Visit our website for more about contributions, including guidelines.

Programming New Cards

Visit our website for more about programming cards, including an example.