Game Objects Module

exception hearthbreaker.game_objects.GameException(message)[source]

Bases: builtins.Exception

An Exception relating to the operation of the game

__init__(message)[source]
class hearthbreaker.game_objects.Bindable[source]

Bases: builtins.object

A class which inherits from Bindable has an event structure added to it.

This event structure follows the observer pattern. It consists of two parts: binding and triggering. A function handler is bound to an event using the bind() or bind_once() methods. When the event is triggered using the trigger() method, then any function handlers which have been bound to that event are called.

Arguments can be passed to a bound function when binding or when triggering, or both. Arguments from triggering are passed first, followed by arguments from binding.

Functions can be bound such that they are called each time an event is triggered, or so that they are only called the next time a function is triggered. The former case is handled by bind() and the latter by bind_once()

Examples:

Simple Binding:

class EventTarget(Bindable):
    def __init__(self):
        super().__init__()

def handler(fangs, scales):
    print("fangs: {:d}, scales: {:d}".format(fangs, scales))

target = EventTarget()
target.bind("attack", handler, 1001)
target.trigger("attack", 2)             # outputs "fangs: 2, scales: 1001"
target.trigger("attack", 6)             # outputs "fangs: 6, scales: 1001"

Binding Once:

class EventTarget(Bindable):
    def __init__(self):
        super().__init__()

def handler(joke):
     print("{:s}! HAHAHA".format(joke))

target = EventTarget()
target.bind_once("joke_told", handler)

# outputs "Well, I'd better replace it then! HAHAHA"
target.trigger("joke_told", "Well, I'd better replace it then")

# outputs nothing
target.trigger("joke_told", "What a senseless waste of human life")

Any class which subclasses this class must be sure to call __init__()

__init__()[source]

Set up a new Bindable. Must be called by any subclasses.

bind(event, function)[source]

Bind a function to an event. Each time the event is triggered, the function will be called.

Parameters:
  • event (string) – The event to bind a function to
  • function (function) – The function to bind. The parameters are not checked until it is called, so ensure its signature matches the parameters called from trigger()
See:

Bindable
bind_once(event, function)[source]

Bind a function to an event. This function will only be called the next time the event is triggered, and then ignored.

Parameters:
  • event (string) – The event to bind a function to
  • function (function) – The function to bind. The parameters are not checked until it is called, so ensure its signature matches the parameters called from trigger()
See:

Bindable
trigger(event, *args)[source]

Trigger an event. Any functions which have been bound to that event will be called.

The parameters passed to this function as args will be passed along to the bound functions.

Parameters:
  • event (string) – The name of the event to trigger
  • args (list) – The arguments to pass to the bound function
See:

Bindable
unbind(event, function)[source]

Unbind a function from an event. When this event is triggered, the function is no longer called.

function must be the same function reference as was passed in to bind() or bind_once()

Parameters:
  • event (string) – The event to unbind the function from
  • function (function) – The function to unbind.
class hearthbreaker.game_objects.Card(name, mana, character_class, rarity, target_func=None, filter_func=<function _is_spell_targetable at 0x0000000004491488>, overload=0, ref_name=None)[source]

Bases: hearthbreaker.game_objects.Bindable

Represents a card in Heathstone. Every card is implemented as a subclass, either directly or through MinionCard, SecretCard or WeaponCard. If it is a direct subclass of this class then it is a standard spell, whereas if it is a subclass of one of MinionCard, SecretCard or WeaponCard., then it is a minion, secret or weapon respectively.

In order to play a card, it should be passed to Game.play_card(). Simply calling use() will cause its effect, but not update the game state.

__init__(name, mana, character_class, rarity, target_func=None, filter_func=<function _is_spell_targetable at 0x0000000004491488>, overload=0, ref_name=None)[source]

Creates a new Card.

target_func and filter_func have very specific behavior. In use, the target function is called with
the filter function as a parameter to generate the list of possible targets for the card, then ask the agent to choose the appropriate target. The selected target will be available as the target attribute of Card. As such, it is critical to call use() in any overriding implementations.
Parameters:
  • name (string) – The name of the card in English
  • mana (int) – The base amount of mana this card costs
  • character_class (int) – A constant from hearthbreaker.constants.CHARACTER_CLASS denoting which character this card belongs to or hearthbreaker.constants.CHARACTER_CLASS.ALL if neutral
  • rarity (int) – A constant from hearthbreaker.constants.CARD_RARITY denoting the rarity of the card.
  • target_func (function) –

    A function which takes a game, and returns a list of targets. If None, then the card is assumed not to require a target. If target_func returns an empty list, then the card cannot be played. If it returns None, then the card is played, but with no target (i.e. a battlecry which has no valid target will not stop the minion from being played).

    See hearthbreaker.targeting for more details.

  • filter_func (function) – A boolean function which can be used to filter the list of targets. An example for hearthbreaker.cards.spells.priest.ShadowMadness might be a function which returns true if the target’s attack is less than 3.
  • overload (int) – The amount of overload on the card
can_use(player, game)[source]

Verifies if the card can be used with the game state as it is.

Checks that the player has enough mana to play the card, and that the card has a valid target if it requires one.

Returns:True if the card can be played, false otherwise.
Return type:bool
is_spell()[source]

Verifies if this is a spell card (or a secret card)

Returns:True if the card is a spell card, false otherwise
Return type:bool
mana_cost(player)[source]

Calculates the mana cost for this card.

This cost is the base cost for the card, modified by any tags from the card itself, or from other cards (such as hearthbreaker.cards.minions.neutral.VentureCoMercenary)

Parameters:player (hearthbreaker.game_objects.Player) – The player who is trying to use the card.
Returns:representing the actual mana cost of this card.
Return type:int
use(player, game)[source]

Use the card.

This method will cause the card’s effect, but will not update the game state or trigger any events. To play a card correctly, use Game.play_card().

Implementations of new cards should override this method, but be sure to call super().use(player, game)

Parameters:
class hearthbreaker.game_objects.Character(attack_power, health, enrage=None)[source]

Bases: hearthbreaker.game_objects.Bindable

A Character in Hearthstone is something that can attack, i.e. a Hero or Minion.

This common superclass handles all of the status tags and calculations involved in attacking or being attacked.
__init__(attack_power, health, enrage=None)[source]

Create a new Character with the given attack power and health

Parameters:
  • attack_power (int) – the amount of attack this character has at creation
  • health (int) – the maximum health of this character
  • List[Action] – (optional) A list of hearthbreaker.tags.base.ReversibleActions that describe what will happen when this character is enraged
activate_delayed()[source]

Activate any events that were delayed.

See:delayed_trigger()
add_aura(aura)[source]
add_effect(effect)[source]

Applies the the given effect to the Character. The effect will be unapplied in the case of silence, and will be applied to any copies that are made.

Parameters:effect (MinionEffect) – The effect to apply to this :class:`Character
attack()[source]

Causes this Character to attack.

The Character will assemble a list of possible targets and then ask the agent associated with this Character to select which target from the list it would like to attack.

This method will not succeed if the Character can’t attack, either because it is not active, or it is frozen, or some other factor. All of the damage and death triggers will be processed at the end of this method, so that the order or evaluation doesn’t affect the calculations. For example, if Amani Berserker is damaged in the attack, its attack power shouldn’t go up before the damage to its attacker is calculated.

The attack will not take place if the Character dies or is otherwise removed as a result of attacking (e.g. various secrets)

calculate_attack()[source]

Calculates the amount of attack this Character has, including the base attack, any temporary attack bonuses for this turn

calculate_max_health()[source]

Calculates the maximum amount of health this Character has, including the base health, and any aura tags

can_attack()[source]

Checks if this Character can attack. Evaluates whether or not is has already attacked, if its frozen and if it has an attack value

Rtype boolean:
change_attack(amount)[source]

Change the amount of attack this Character has. The amount can be either positive or negative. This method will automatically undo its effect when silenced, and re-apply its effect when copied

Parameters:amount (int) – The amount to change the attack by
change_temp_attack(amount)[source]

Change the amount of attack this Character has on this turn only. The amount can be either positive or negative. This method will automatically undo its effect when silenced, and re-apply its effect when copied

Parameters:amount (int) – The amount to change the temporary attack by
choose_target(targets)[source]

Consults the associated player to select a target from a list of targets

Parameters:targets (list[Character]) – the targets to choose a target from
damage(amount, attacker)[source]

Deal damage to this Character. This method uses the attacker parameter to determine the nature of the damage taken. If the attacker is a Character, then it is assumed to be a physical attack. If attacker is a SpellCard, then it assumes a spell attack. If None, then something else (hero ability or battlecry). This method will also trigger the various events associated with taking damage or dying.

If the character has a divine shield, it will be removed, and the character will take no damage. If the character’s health is below the max_health, then the character is considered enraged.

Parameters:
  • amount (int) – The amount of damage done (should be positive)
  • attacker (Object) – The Character`or :class:`SpellCard that did the damage or ``None`.
decrease_health(amount)[source]

Decrease the amount of total health this Character has. This is a permanent effect (unless the Character is silenced). This effect will decrease the player’s maximum health, but will only decrease the player’s health if it is above the new value for maximum health

Parameters:amount (int) – the amount to decrease health by
delayed_trigger(event, *args)[source]

Set up a delayed trigger for an event. Any events triggered with this method will not be called until activate_delayed() is called.

The purpose of this method is to allow for simultaneous events. For example, if a minion is attacked then any damage events should be triggered after the attack, and at the same time as each other.

Parameters:
  • event (string) – The event to set up a delayed trigger for
  • args (list) – The arguments to pass to the handler when it is called.
See:

Bindable
die(by)[source]

Kills this Character. The death event will not be processed until activate_delayed() is called.

Parameters:by – The object that killed this character. Could be a Character, a spell card or None
freeze()[source]

Causes this Character to be frozen. If this character is frozen on its opponent’s turn, it will not be able to attack on the next turn. If frozen on its owner’s turn, it will not be able to attack this turn or its owner’s next turn.

heal(amount, source)[source]

Heals the Character. The health cannot exceed the character’s max health. If the amount being healed is less than 0, then the character is damaged instead.

If the character’s health is brought back to its maximum, then it is no longer enraged.

Parameters:
  • amount (int) – The amount this character is being healed by. Can be negative
  • source – The source of this healing. Could be a Minion, a spell card or None
increase_health(amount)[source]

Increase the amount of total health this Character has. This is a permanent effect (unless the Character is silenced). This effect will increase both the player’s current health and maximum health

Parameters:amount (int) – the amount to increase health by
remove_aura(aura)[source]
set_attack_to(new_attack)[source]

Sets the amount of total attack this Character has. :param new_attack: An integer specifying what this character’s new attack should be

set_health_to(new_health)[source]

Sets the amount of total health this Character has. This will adjust its actual health if necessary :param new_health: An integer specifying what this character’s new health should be

silence()[source]

Silence this Character. This will trigger the silence event, and undo any status tags that have affected this character (immune, attack & health increases, frozen, windfury)

spell_targetable()[source]

Checks if a Character can be targeted by a spell. Minions with stealth or whose text say they can’t be targeted by spells cannot be targeted, but any other character can.

active = None

Whether or not this character can attack this turn

attack_delta = None

An integer describing how much the attack of this character has been adjusted

auras = None

A list of auras that affect this character

base_attack = None

The amount of attack this character has

born = None

An integer describing when this character was created. The lower, the earlier it was created

dead = None

Whether or not this character has died

delayed = None

The list of delayed events

effects = None

A list of tags that have been applied to this character

enraged = None

If this character is enraged

frozen = None

If this character is currently frozen

frozen_this_turn = None

If the character was frozen this turn (and so won’t be unfrozen before the next turn)

health_delta = None

An integer describing how much the health of this character has been adjusted

immune = None

Whether or not this character is immune to damage (but not other tags)

player = None

The Player that owns this character

removed = None

If this character has been removed from the board

stealth = None

Non zero if this character has stealth

used_windfury = None

If this character has used their first windfury attack

windfury = None

If this character has windfury

class hearthbreaker.game_objects.Deck(cards, character_class)[source]

Bases: builtins.object

__init__(cards, character_class)[source]
can_draw()[source]
copy()[source]
draw(game)[source]
put_back(card)[source]
class hearthbreaker.game_objects.Game(decks, agents)[source]

Bases: hearthbreaker.game_objects.Bindable

__init__(decks, agents)[source]
check_delayed()[source]
copy()[source]
game_over()[source]
play_card(card)[source]
play_single_turn()[source]
pre_game()[source]
random_amount(minimum, maximum)[source]
random_choice(choice)[source]
random_draw(cards, requirement)[source]
remove_minion(minion, player)[source]
start()[source]
class hearthbreaker.game_objects.Hero(character_class, player)[source]

Bases: hearthbreaker.game_objects.Character

__init__(character_class, player)[source]
attack()[source]
calculate_attack()[source]
copy(new_owner, new_game)[source]
damage(amount, attacker)[source]
die(by)[source]
find_power_target()[source]
increase_armor(amount)[source]
class hearthbreaker.game_objects.Minion(attack, health, battlecry=None, deathrattle=None, taunt=False, charge=False, spell_damage=0, divine_shield=False, stealth=False, windfury=False, spell_targetable=True, effects=None, auras=None, enrage=None)[source]

Bases: hearthbreaker.game_objects.Character

__init__(attack, health, battlecry=None, deathrattle=None, taunt=False, charge=False, spell_damage=0, divine_shield=False, stealth=False, windfury=False, spell_targetable=True, effects=None, auras=None, enrage=None)[source]
add_to_board(index)[source]
attack()[source]
bounce()[source]
calculate_attack()[source]

Calculates the amount of attack this Minion has, including the base attack, any temporary attack bonuses for this turn and any aura tags

calculate_max_health()[source]

Calculates the maximum amount of health this Character has, including the base health, and any aura tags

can_attack()[source]
can_be_attacked()[source]
copy(new_owner, new_game=None)[source]
damage(amount, attacker)[source]
die(by)[source]
heal(amount, source)[source]
remove_from_board()[source]
replace(new_minion)[source]

Replaces this minion with another one

Parameters:new_minion (hearthbreaker.game_objects.Minion) – The minion to replace this minion with
silence()[source]
spell_targetable()[source]
class hearthbreaker.game_objects.MinionCard(name, mana, character_class, rarity, minion_type=0, targeting_func=None, filter_func=<function MinionCard.<lambda> at 0x000000000447FB70>, ref_name=None, battlecry=None, choices=None, overload=0)[source]

Bases: hearthbreaker.game_objects.Card

Describes a Card for summoning a minion. This is distinct from the Minion that represents the minion after it has been played. This class represents the card aspects (mana cost, character class and rarity) as well as being responsible for creating the minion that will be added to the table.

See:Card
See:create_minion()
__init__(name, mana, character_class, rarity, minion_type=0, targeting_func=None, filter_func=<function MinionCard.<lambda> at 0x000000000447FB70>, ref_name=None, battlecry=None, choices=None, overload=0)[source]

All parameters are passed directly to the superclass's __init__ method.

Parameters:
  • name (string) – The name of this card in English
  • mana (int) – The base mana cost of this card
  • character_class (int) – The character class that this card belongs to. Should be a member of hearthbreaker.constants.CHARACTER_CLASS
  • rarity (int) – How rare the card is. Should be a member of hearthbreaker.constants.CARD_RARITY
  • minion_type (int) – The type that the summoned minion will have. Should be a member of hearthbreaker.constants.MINION_TYPE
  • targeting_func (function) – The function used to select a list of targets for this minion’s battlecry, if it has one. If it does not, then None. This function should be taken from hearthbreaker.targeting, and should return None if there are no feasible targets.
  • filter_func (function) – Used to filter targets returned from the targeting function for appropriateness. Typically used for ensuring that stealthed minions aren’t targeted
  • ref_name (string) – The name used for reference for this card. If None (the default), the reference name will be the same as its name. Otherwise, this name must be unique across all cards.
  • battlecry (hearthbreaker.tags.base.Battlecry) – Describes the battlecry this minion will use when it enters the field, or None for no battlecry
  • choices ([hearthbreaker.tags.base.Choice]) – Gives a list of :class:`Choice <hearthbreaker.tags.base.Choice>`s for the user to pick between
can_use(player, game)[source]

Checks if this minion can be played. The card must be able to play AND the board must not be full.

Parameters:
create_minion(player)[source]

Creates the minion associated with this card. This method is responsible for creating the Minion object and adding any necessary tags. This method must be overridden by a subclass’s implementation. For more details, see Contributing.

This method is only responsible for creating the minion and attaching events. It is not responsible for setting the minion’s player or game attributes, or correctly setting its index. That is handled within play() and summon()

Parameters:player (hearthbreaker.game_objects.Player) – The player who the newly created minion will belong to.
Return type:hearthbreaker.game_objects.Minion
is_spell()[source]

Checks if this card is a spell card. Always returns false

Return type:boolean
summon(player, game, index)[source]

Summons the minion associated with this card onto the board. This is to be used when a spell created a minion, instead of being played from the hand.

If the player already has 7 minions on the board, this method does nothing.

This method operates in the following order:

  1. Minion is placed on the board
  2. minion_placed event
  3. minion_summoned_event
  4. after_minion_added event

The ordering is important so that efects trigger in the correct order.

See:

use()
Parameters:
use(player, game)[source]

Adds this minion to the board for the given player, if the card is able to be played. The agent for the given player will be consulted about the location on the board of the played minion, about the target for the battlecry if necessary, and to choose an option for cards with choose.

This method operates in the following order:

  1. Battlecry target chosen (if needed)
  2. Board placement chosen
  3. Minion is placed on the board
  4. minion_placed event
  5. Battlecry activated (if needed)
  6. minion_played event
  7. minion_summoned_event
  8. after_minion_added event

The precise ordering of events is necessary so that various tags (Sword of Justice, Knife Juggler, etc) trigger in the correct order, and to distinguish from summon(), which is called when a minion is played as a side effect of of card (e.g. Feral Spirit)

Parameters:
class hearthbreaker.game_objects.Player(name, deck, agent, game)[source]

Bases: hearthbreaker.game_objects.Bindable

__init__(name, deck, agent, game)[source]
add_aura(aura)[source]
add_effect(effect)[source]
can_draw()[source]
choose_target(targets)[source]
copy(new_game)[source]
discard()[source]
draw()[source]
effective_heal_power(base_heal)[source]
effective_spell_damage(base_damage)[source]
put_back(card)[source]
remove_aura(aura)[source]
class hearthbreaker.game_objects.SecretCard(name, mana, character_class, rarity)[source]

Bases: hearthbreaker.game_objects.Card

__init__(name, mana, character_class, rarity)[source]
activate(player)[source]
can_use(player, game)[source]
deactivate(player)[source]
reveal()[source]
use(player, game)[source]
class hearthbreaker.game_objects.Weapon(attack_power, durability, battlecry=None, deathrattle=None)[source]

Bases: hearthbreaker.game_objects.Bindable

Represents a Hearthstone weapon. All weapons have attack power and durability. The logic for handling the attacks is handled by Hero, but it can be modified through the use of events.

__init__(attack_power, durability, battlecry=None, deathrattle=None)[source]

Creates a new weapon with the given attack power and durability. A battlecry and deathrattle can also optionally be set. :param int attack_power: The amount of attack this weapon gives the hero :param int durability: The number of times this weapon can be used to attack before being discarded :param function battlecry: Called when this weapon is equipped :param function deathrattle: Called when the weapon is destroyed

copy(new_owner)[source]
destroy()[source]
equip(player)[source]
battlecry = None

Called when this weapon is equipped

card = None

The WeaponCard that created this weapon

deathrattle = None

Called when the weapon is destroyed

player = None

The Player associated with this weapon

class hearthbreaker.game_objects.WeaponCard(name, mana, character_class, rarity, target_func=None, filter_func=<function WeaponCard.<lambda> at 0x000000000449A378>, overload=0)[source]

Bases: hearthbreaker.game_objects.Card

Represents a Card for creating a Weapon

__init__(name, mana, character_class, rarity, target_func=None, filter_func=<function WeaponCard.<lambda> at 0x000000000449A378>, overload=0)[source]

Create a new WeaponCard

Parameters:
  • name (string) – The name of the weapon in English
  • mana (int) – The base amount of mana this card costs
  • character_class (int) – A constant from hearthbreaker.constants.CHARACTER_CLASS denoting which character this card belongs to or hearthbreaker.constants.CHARACTER_CLASS.ALL if neutral
  • rarity (int) – A constant from hearthbreaker.constants.CARD_RARITY denoting the rarity of the card.
  • target_func (function) – A function which takes a game, and returns a list of targets. If None, then the weapon is assumed not to require a target for its battlecry. If target_func returns None, then the card is played, but with no target (i.e. a battlecry which has no valid target will not stop the weapon from being played). See hearthbreaker.targeting for more details.
  • filter_func (function) – A boolean function which can be used to filter the list of targets. An example for hearthbreaker.cards.spells.priest.ShadowMadness might be a function which returns true if the target’s attack is less than 3. Currently no weapons require anything but the default
  • overload (int) – The amount of overload on the card
create_weapon(player)[source]

Create a new weapon. Any new weapon cards which are created must override this method.

is_spell()[source]
use(player, game)[source]

Create a new weapon and attach it to the player’s hero

Parameters:
  • player (Player) – The player who will use this weapon
  • game (Game) – The game this weapon will be used in
hearthbreaker.game_objects.card_lookup(card_name)[source]

Given a the name of a card as a string, return an object corresponding to that card

Parameters:card_name (str) – A string representing the name of the card in English
Returns:An instance of a subclass of Card corresponding to the given card name or None if no Card by that name exists.
Return type:hearthbreaker.game_objects.Card
hearthbreaker.game_objects.get_cards()[source]