Hearthstone Simulation 101: Game State

So you want to write a Hearthstone simulator, eh? Let's start with the basics first.

Entities and Zones

A Hearthstone game is a state machine. Once the players enter a game, they are allowed a bunch of different options (and sometimes sub-options!), optionally on a target - including the option of ending the turn. Choosing an option causes a bunch of reactions based on the board state, and the turn may change. This continues until at least one player loses.

So what does the game state looks like? Everything is an entity and every entity is in a zone. These are the major zones (there are a couple more):

• PLAY
• DECK
• HAND
• GRAVEYARD
• SETASIDE

These are somewhat straightforward. Keeping in mind, the PLAY zone contains every entity currently in play. Let's take a look at the game's hierarchy:

• The Game entity itself. This is the root entity. It enters PLAY when the game begins.
• The Player entities. Very theoretically, there can be any amount of players... but let's stick to 2. It makes things simpler. They also enter PLAY when the game begins.
  • Each player, during a running game, has a Hero entity summoned (in PLAY) at the beginning of the game. When the Hero in play dies, their owner loses the game.
    • Each Hero also has a Hero Power slot, where their hero power will be summoned when they arrive in PLAY. The Hero Power, too, will be in PLAY.
    • Each player also has card lists representing the player's hand and deck. Cards in those lists, unsurprisingly and respectively, are in the HAND and DECK zones.
    • When a Minion is played, it enters the PLAY zone. This puts it into another card list: the player's field. The "board" is the sum of all players' fields.
    • When a Weapon is played, it also enters the PLAY zone. This puts it into the player's Weapon slot.
    • When a spell is played, it enters the PLAY zone... but leaves it immediately and goes to the GRAVEYARD, after doing its thing.
      • One exception: Secrets. When a Secret spell is played, it enters the SECRET Zone... we didn't talk about that one. It'll stay there until it triggers, and then will go to the GRAVEYARD.

It's pretty straightforward from there: Whenever a card in play is destroyed, be it a hero, hero power, minion, weapon ... it goes to the GRAVEYARD. Incidentally, when a card is milled (from the DECK) or discarded (from the HAND), it also goes to the GRAVEYARD - although Fireplace choses to separate those into a DISCARD zone, which Hearthstone does not do.

Wait - there's one more card type we did not talk about: Enchantment. Enchantments are "buffs". They can be attached to any other entity (even a Player!), and most often will change its stats or give it additional triggers.

So what's SETASIDE? It's more or less everything else. It's where fresh cards are created before they move into a proper zone. It's where Tracking does its thing, or where minions go when they are morphed (transformed). It's where cards which have been put aside, but not been properly destroyed, will hang around for the rest of the game.

Game Tags

We established that entities have a state. In order for that state to be understood by the Hearthstone client, it has to be serialized somehow. This is where GameTags are useful! Every entity has a bunch of GameTags to it, each of which can be serialized to an integer (except the strings - but those are not needed for simulation). They all default to 0.

Internally, these may be properties which are part of the entity's class. Or sometimes, they may be lazily calculated - such as the ZONE_POSITION.

It's also worth mentioning that, when transmitting this data to the players, some cards are considered "unrevealed" for certain players (cards still in the deck, or in the opponent's hand) and will not broadcast information about them. This should be irrelevant for simulation, unless you intend to create a framework in which to play real games.

Finally, when using Game Tags, it is possible (and very much recommended...) to reuse the game files for static data - this includes card names and a bunch of base values such as attack, health, taunt/divine shield/windfury-type attributes, etc. See CardDefs.xml for further information.

---

That's it! You're now able to describe any game state, in full. You can't do much with it yet, so in the next lesson, we'll learn about Actions and Powers.