Home

Fireplace

Fireplace is a simulator for Hearthstone. Fireplace can create Game objects and keep track of their state and offers an API to play cards, interact with the board and game state, etc. Fireplace uses the game files as a basis for most cards and also offers an API to manually define cards and override values defined in the game files. For more information about card definitions, see the wiki page.

Entities

All game objects are a subclass of Entity. Entities track their public properties in a tags dictionary containing key-value pairs for GameTag keys and bool, int, str or Entity values. The Fireplace API lets the user get, set, and remove the more common tags through public properties on the Entity objects themselves.

Entities can also bind themselves to events and broadcast events themselves. More on this later.

The game is laid out in a set of Entity objects: Game, Player, and Card objects. Lists of cards, such as the player's deck and hand, are kept in a CardList object.

Game

The Game object keeps track of the game's status and players. Game.start() will begin a game by determining the first and second Player and starting the mulligan phase. Once mulligan is over, the TURN_BEGIN event is fired and the turn takes place until Game.endTurn() is called, firing TURN_END.

Player

A Game will generally have two Player objects which will keep track of their Zones (Deck, Hand, Play, Graveyard, ...). A player can play a card from their hand with Player.play(). They can directly summon a Card with Player.summon(). They can be given a fresh card with Player.give(). They can affect the board in various other ways and keep track of their live entities in the deck, hand, field, secrets and ## Entities All game objects are a subclass of Entity. Entities track their public properties in a tags dictionary containing key-value pairs for GameTag keys and bool, int, str or Entity values.

Entities can also bind themselves to events and broadcast events themselves. More on this later.

The game is laid out in a set of Entity objects: Game, Player, and Card objects. Lists of cards, such as the player's deck and hand, are kept in a CardList object.

Game

The Game object keeps track of the game's status and players. Game.start() will begin a game by determining the first and second Player and starting the mulligan phase. Once mulligan is over, the TURN_BEGIN event is fired and the turn takes place until Game.endTurn() is called, firing TURN_END.

Player

A Game will generally have two Player objects which will keep track of their Zones (Deck, Hand, Play, Graveyard, ...). A player can play a card from their hand with Player.play(). They can directly summon a Card with Player.summon(). They can be given a fresh card with Player.give(). They can affect the board in various other ways and keep track of their live entities in the deck, hand, field, secrets and hero attributes.

Card

The Card class encompasses all types of cards in Hearthstone and even some internal ones. A Card has a Zone which can be any of PLAY, DECK, HAND, GRAVEYARD, REMOVEDFROMGAME, SETASIDE or SECRET. When created, a Card object is immediately transformed into a Minion, Spell, Weapon, Hero, HeroPower or Enchantment instance depending on its CardType. Additionally, Spell cards with the SECRET tag will be transformed into a Secret instance.

Note from the author: I am not sure why Blizzard decided to have a separate Zone for secrets without giving them their own card type, unlike weapons which don't have a special Zone (They reuse the PLAY Zone) but have their own CardType. While making them behave like spells is cheap and useful, that is IMO of little internal value. I'd love to see them get their own CardType... and a cool card frame!

A Card has buffs and slots. A card's buffs is a CardList of Enchantment cards attached to said card, and will receive the Card's events as if they were their own. That means an Enchantment can easily attach an event listener to a card, such as Blessing of Wisdom and the SELF_ATTACK event.

A Card's slots are additional places (such as buffs), some properties will look in order to determine the value of a GameTag. This is limited to tags that are known to have such an effect in Hearthstone for the sake of simplicity. For example, to determine a Minion's ATK (attack) value, we don't just look at its GameTag.ATK but also at all its buffs. A 3-attack minion with a -2-attack and a +5-attack buff will be a 6-attack minion.

Slots encompass more than buffs however. For Hero cards, they also encompass the Weapon. So a 0-attack Hero with a 4-attack Weapon will be a 4-attack Hero. If the Weapon has WINDFURY, the Hero will also inherit it.

Finally, on Minion cards, slots are used to determine the Enrage buffs. Enrage is implemented as a virtual card which is part of the Minion that owns it. When the Minion has a DAMAGE value and an ENRAGED tag, the slots will then also look in the Minion's Enrage for extra tags or even auras (cf. Spiteful Smith).

Auras

Auras are a special type of Enchantment which is applied to several characters at once. An Aura generally has a source, and will be removed if the source is removed or silenced. If an aura's source is a Minion and has the ADJACENT_BUFF tag, the aura will only be applied to the minions adjacent to that minion. For that purpose, the aura source creates an Aura virtual card in the Game entity. The Aura Card will receive events and on UPDATE will create and apply an Enchantment of itself to all entities for which it is a valid target.

Events

Documentation on events can be found here.