This guide was updated to comply with changes made for the 2020 Hearthstone AI competition.

On this page, you will learn how to set up your first agent. During the tutorial, we will quickly summarize the components of the framework and show you how a simple Random Agent is implemented.

Step 1: Important Framework Components

Class Description
Program.cs The Program class includes the Main function, which is called when the SabberStoneCoreAi is started. The example file includes functions for running single Turns, complete games, and whole tournaments. Feel free to change this according to your needs, since you will just need to submit files that correspond to your agent.
POGameHandler.cs The Partial Observation folder contains classes that will be used to ensure that at all times the agents will not be able to see the cards of its opponent. Please note, that any attempt in violating this constraint will lead to the disqualification of the agent.

POGameHandler controls the flow of the game. At the beginning of each match the agent’s InitializeGame method will be called. Similarly, the FinalizeGame method is called at the end of each game. During the game, the POGameHandler creates a game-state in which the opponent’s cards will be replaced with a useless card that does nothing. Given this POGame (a partial observable instance of the game-state object) the agent needs to return a single action. After the action was applied, the agent receives an updated POGame instance which allows the agent to react on random results of a card.
POGame.cs POGame provides access to all visible components of the game. hand, board, and deck cards, as well as current information on the game state such as turn-number or mana can be accessed.

The POGame also provides possible moves to the player. An integrated forward model can be used to see the result of the move.

In case you want to simulate your opponent’s turn it is highly advised to replace the dummy-cards on the opponent’s hand and deck with more meaningful cards.
GameStats.cs The GameStats object stores the number of simulated games, winning statistics and average times per turn.
AbstractAgent.cs The AbstractAgent is the base-class for your own Agents. Your agent should inherit this class and implement the following methods.

  • InitializeAgent: load files once at the start of the simulation
  • InitializeGame: initialize data at the start of a game
  • GetMove: return a non-empty list of moves based on the provided POGame
  • FinalizeGame: store the result and update the agent after a game
  • FinalizeGame: store the final model at the end of the simulation

In case your agent is participating in the Deck-Building track, we require you to define your preferred Hero and Deck at the top of this file.

Please adhere to the namespace conventions mentioned in the submission guidelines.
RandomAgent.cs The RandomAgent discussed in Step 3

Step 2: Setting up the files for your own Agent

  • Open the src/AIAgent folder in the SabberStoneCoreAi project
  • You can use and rename the MyAgent.cs file
  • Please choose a submission_tag to define your namespace. All the files you are going to submit should be using the same namespace or any of its subspaces.

Step 3: Implementing a simple Random Agent

  • Now, let’s add some code to GetMove. Using the poGame object we can get all possible moves by calling the function Options() on the current player controller.
  • We add a private Random object to our agent and initialize it in the InitializeAgent function.
  • Back in the GetMove function we choose a random option and return it.
  • The final result should look like this:

Step 4: Further Example Agents

  • Make sure to study our example agents in „\core-extensions\SabberStoneBasicAI\src\AIAgents\Examples\“ to get accustomed to the framework.
  • Feel free to download and adapt agents of previous competition years from this webpage. They will require minimal adjustments due to changes in the namespaces of the underlying framework, but this process is fairly easy.
  • Some of the agents were part of a research paper. This website features a collection of Hearthstone related research papers in the additional resources sub-page.

Additional Hints

  • We can simulate the result of our chosen Option by calling „poGame.Simulate(option);“. Keep in mind that some PlayerTasks yield non-deterministic results. For this reason, handle the result of this function with care.