1: The Fireplace Card API

In the engine, Cards are Entities. They have tags (attributes), and various properties which can cause the game state to change.

Static data

Hearthstone entities — that is, every Game, Player and Card object — are publicly defined by their tags. The static tags are defined in the CardXML data.

Card scripting

Card scripts are defined in the fireplace.cards module, using parentless classes named according to their Card ID. The module is split into the various original sets; however, each set is imported and imports all the cards, so every card is available at the fireplace.cards level. For example, Lightwarden is defined in fireplace/cards/classic/priest.py, but should be accessed from fireplace.cards.EX1_001.

During the first fireplace.cards import, the processed CardXML file is parsed and the static data is merged with the script data. For the full reference of what is merged in, see CardXML enhancements.

The card scripting API includes:

• Action triggers
• Event listeners
• Attribute scripts

We will go over each one of those APIs in details below.

Action triggers

Action triggers are a sequence of actions which are triggered directly by the engine. They implement the Battlecry, Combo, Deathrattle and Inspire keywords. The "main" action sequence of spells works the same as a Battlecry.

They are defined as the following attributes of the card script class, respectively:

• action: The main action trigger (Battlecry or spell action). Triggers when the card is played from the hand.
• combo: Same as action, but triggers when at least one more card was played this turn, and the COMBO tag is set on the card.
• deathrattle: The main death action. Triggers when the card dies, if it has the DEATHRATTLE tag. Can be used in Enchantment cards to attach a deathrattle to a buff (Note: the DEATHRATTLE tag still needs to be set on the buff for it to work).
• inspire: A new keyword in The Grand Tournament. Will trigger after the controller's Hero Power has been used.

These can be either an iterable of Actions, or a callable. Callable action sequences are not declarative nor introspectable and should only be used if the trigger cannot be implemented any other way.

Event listeners

Event listeners will listen for actions triggering and immediately queue further actions. They are defined in the events attribute, which is an iterable of EventListener.

An EventListener is an Action with arguments matching the desired trigger, with one or more resulting Actions attached. The objects are created by calling on(), after() or once() on an Action object.

In-hand events

The in_hand attribute works exactly like the events attribute, but holds Event Listeners which will trigger while the card is in hand.

For a full reference of Events and Event Listeners, see Events.

Attack target selection

A card's attack targets can be determined with the attack_targets script. It should always be a selector. The selector will be evaluated against the Game's characters, therefore it is impossible to have non-character entities in the result. Taunts will be taken into account natively.

Example:

attack_targets = ENEMY_MINIONS

Atttribute scripts

Attribute scripts can be used to dynamically change the value of some tags. It is used to implement effects such as the various Giants, Southsea Deckhand, Dragon's Breath as well as the buffs from Equality, Millhouse Manastorm and many more.

Attribute scripts are defined as callable functions that take the form func(self, i). self is the card object, and i is the current value of the attribute at the level of the call. For example, doubling the atk of a card:

atk = lambda self, i: i * 2

The following attribute scripts are supported:

• atk
• charge
• cost
• max_health

Note: When an attribute script that modifies max_health is set on a character, that character will immediately reset all its DAMAGE.

---

Next article: The Fireplace DSL