Serialization Format

Serialization Format

The following is proposal for a serialization format of the current board state of a game in Heartstone. It makes no assumptions about the state of the game, (i.e. the game can be serialized or deserialized part of the way through a turn, or at the end or beginning of a turn).

The proposed format is a JSON based format. In most cases it relies on standard Hearthstone Terminology, but a standard for effect names and descriptions will have to be agreed upon.

Many of the objects described have tags associated with them. These tags are documented separately in Tag Format.

Game Object

At the root is the game object, which consists of an array of two Player objects and an integer which gives the index of the player whose turn it is now:

{
    "players": [Player, Player]
    "active_player": Integer
    "current_sequence_id": Integer
}

current_sequence_id is an integer to keep track of when minions are created. Each time a new minion is placed, current_sequence_id is incremented, and the minion's sequence_id is set to the new value. This allows for proper execution of deathrattles.

Player Object

The Player object houses all information about a Player:

{
    "hero": Hero,
    "deck": [DeckCard, DeckCard, ...],
    "hand": [card_name, card_name, ...],
    "graveyard": [card_name, card_name, ...],
    "secrets": [secret_name, secret_name, ...],
    "effects": [Effect, Effect],
    "auras": [Aura, Aura],
    "minions": [Minion, Minion, ...],
    "mana": Integer,
    "max_mana": Integer,
    "name": String
}

card_name and secret_name are just string representation of the card's name in English.

deck contains a list of DeckCard objects

graveyard should contain a list of cards which but have been played or discarded.

effects should contain a list of Effects active on this player. (See [Tag Format] for more details)

auras should contain a list of Auras currently affecting this player. (See [Tag Format] for more details)

mana and max_mana specify how much mana the player has this moment, and what their maxmimum mana are, respectively.

name is the name of this player.

Deck Card

{
    "name": String,
    "used": Boolean
}

name is the name of the card in English.

used signifies if the card has already been drawn or not

Hero Object

The Hero object refers to the avatar of the player in game:

{
     "character": "Mage" | "Paladin" | "Druid" | ... ,
     "weapon": Weapon,
     "health": Integer,
     "armor": Integer,
     "attack": Integer,
     "immune": Boolean,
     "frozen_for": Integer,
     "used_windfury": Boolean,
     "already_attacked": Boolean,
     "effects": [Effect, Effect, ...]
     "auras": [Aura, Aura, ...]
}

Most properties are fairly self explanatory. frozen_for is an integer that specifies how many of the player's turns this hero will be frozen for. If the hero is frozen on the owning player's turn, then it will be frozen for the remainder of that turn, and the next one, so frozen_for will be 2. If it is frozen on the opposing player's turn, then frozen_for will be 1. At the end of the owning player's turn, frozen_for will be decremented, until it is 0, and the hero is no longer frozen.

If a hero has windfury, then the first time the hero attacks in a turn, used_windfury will be set to True. The second time, already_attacked will be set to True. This gives a way to know if a can still attack.

effects should contain a list of Effects active on this hero. (See [Tag Format] for more details)

auras should contain a list of Auras currently affecting this hero. (See [Tag Format] for more details)

Weapon Object

The Weapon object simply gives the name of the weapon and its stats. Any effects or deathrattles (such as from Gladiator's Longbow or Death's Bite) can be inferred from the weapon's name

{
     "name": String,
     "attack": Integer,
     "durability": Integer
}

Minion Object

The Minion object represents a minion as placed on the board.

{
    "name": String,
    "sequence_id": Integer,
    "position": Integer,
    "damage": Integer,
    "max_health": Integer,
    "attack": Integer,
    "divine_shield": Boolean,
    "exhausted": Boolean,
    "already_attacked": Boolean,
    "windfury_used": Boolean,
    "frozen_for": Integer,
    "effects": [Effect, Effect, ...]
    "auras": [Aura, Aura, ...]
}

Most properties are fairly self explanatory, and frozen_for, windfury_used and already_attacked work similarly to how they work for Hero.

sequence_id is an integer that indicates when this minion was created, for the purpose of executing deathrattles. See the discussion in the Game object.

position is a zero based index of where the minion is on the board.

damage is used instead of Health because of the interplay between auras and health.

attack represents the base attack of the minion, without any buffs. These buffs are included in auras

effects is a list of Effects. (See [Tag Format] for more details)

auras is a list of auras. (See [Tag Format] for more details)