-
Notifications
You must be signed in to change notification settings - Fork 122
Tag Format
This tag format is loosely based around the effect system for Focus and the tag system of Fireplace.
There are currently two types of tags: Auras and Effects. Auras have a continuous effect, which is removed at a given event, or when the corresponding minion is removed. Effects happen repeatedly at a given event until their associated minion is removed.
Auras are tags that provide a continuous change to the affected objects. As such, the change must be reversible, so it can be undone when the aura is removed.
Auras take the following form:
{
"action": Reversible Action,
"selector": Selector,
"until": Player Event (Optional)
}action is any kind of Reversible Action. This action is performed on every object selected by selector
selector is any Selector. Typically the selector should match the action. So, if the action is Draw then the selector should be a Player Selector. If the action is Increase Health then the selector should be a Minion Selector.
until is an optional Player Event that dictates when the aura should be removed. This should be included for any aura that is attached to a player (such as a card mana change aura) but should not be included for any aura that is attached to a minion.
An effect is a tag which performs an action each time an event occurs.
{
"when": Event,
"action": Action,
"selector": Selectorwhen is an Event that dictates when the effect occurs.
action is any kind of Action that specifies what will happen when the effect is triggered.
selector is a Selector that indicates which objects the action should happen to. Like for auras, the selector should match the action.
An action is some kind of change that happens to an object. There are two types of actions: Permanent Actions and Reversible Actions, although they are not represented differently in the serialization format.
All actions have a name that dictates what the action is. Some actions also have properties which inform how the action is performed. For example, Heal has the amount property that dictates how many health points to heal the target.
Permanent actions change the state of the game in some way that cannot be undone (for example, killing a character or drawing a card.
Summon will cause a new minion to be added to the board, so long as there are fewer than 7 minions already on the board.
{
"name": "summon",
"card": String
}card is a string that gives the name of the card to summon.
Draw causes the player to draw a new card from the deck. This will cause the card to be destroyed if the player already has 10 cards in hand, and will cause the player to take fatigue damage if their deck is empty.
{
"name": "draw"
}Kills a character
{
"name": "kill"
}Heals a character. A character cannot be healed past its maximum health.
{
"name": "heal",
"amount": Positive Integer
}amount is how much the character should be healed by. Should always be positive.
Freeze causes a character to give up one turn of movement.
{
"name": "freeze"
}Gives an aura to its target. For example, Young Priestess gives a +1 health aura to a random friendly minion at the end of its player's turn.
{
"name": "give",
"aura": Aura
}aura is an Aura that will affect the targeted character. The action for a Young Priestess, as above would look like
{
"name": "give",
"aura": {
"action": {
"name": "change_health",
"amount": 1
},
"selector": {
"name": "self"
}
}
}At the end of a turn, the randomly targeted minion would have that aura applied.
Take is the opposite of give. It will remove its associated aura from its target. In HearthBreaker, this is only used to remove stealth from minions when Conceal expires, but may have other uses. It will remove at most one aura whose serialization exactly matches aura's.
{
"name": "take",
"aura": aura
}aura is an aura that will be removed, if present, from the given target.
Reversible actions are those which can be undone. These are essentially status changes. For example, giving a minion stealth can be undone, as can changing the mana cost of a card or set of cards.
Mana change is an action which will change the mana cost for some cards. The amount to change the mana by, what the minimum mana resulting from this change can be, and the type of cards affected are all properties that can be changed.
{
"name": "mana_change",
"amount": Integer,
"minimum": Integer,
"card_selector": Card Selector,
}amount is an integer specifying the change in mana. A positive number will cause the mana cost to go up, a negative number will cause it to go down, although it will not go lower than minimum
minimum is the lowest that the mana cost for a card affected by this change can go. Is almost always 0.
card_selector is a Card Selector that dictates which cards are affected by this change.
Change attack modifies the character's attack value.
{
"name": "change_attack",
"amount": Integer
}amount is an integer, positive or negative, that specifies how much to change the attack by. If positive, the attack will increase, if negative, it will decrease.
Changes the character's health. This affects the character's maximum health and sometimes its actual health as well.
An increase in health will change both its max health and actual health by the same amount. However, when the change is undone, only the max health will be decreased, unless the max health is now below actual health, in which case the actual health will be changed to whatever the new max health is.
A decrease in health will change only the max health, unless the max health is below actual health, in which case the actual health will be changed to whatever the new max health is. When the change is undone, only the max health is increased, unless the max health and the actual health were equal, in which case both are.
{
"name": "change_health",
"amount": Integer
}amount is an integer, positive or negative, that specifies how much to change the health by. If positive, the health will increase, if negative, it will decrease.
Indicates that this card has been stolen from the opposing player. Currently this effect is only used for Shadow Madness. When removed it should revert back to the other player.
{
"name": "stolen"
}Multiplies the spell damage by a specified amount.
{
"name": "spell_damage_multiplier",
"amount": Integer
}amount is an integer specifying how much to multiply the spell damage by.
Multiplies the power of healing cards and hero abilities by the specified amount
{
"name": "heal_power_multiplier",
"amount": Integer
}amount is an integer specifying how much to multiply the healing power by.
Events are generated on various changes in the board state. They are used with effects to perform an action in response to certain circumstances.
All events have two properties: name and condition. Some events may have additional properties
{
"name": String,
}name is a string describing the event. Names are listed below.
There are two types of events: player events which trigger for any part of a player's board, and character events which trigger only for a particular character.
{
"name": String,
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Player events are events which can happen to any character. They are not localized to a single character.
player is the name of the player whose deck, minions or hero is generating the event. Possible values are "friendly", "enemy", "both", "player_one", "player_two". "friendly", "enemy" and "both" are in relation to the owner of the tag.
condition specifies a Condition that must be true in order for the event to fire. For example, a character event can have a condition attached that only fires when a minion with a battlecry is the cause. Conditions should be chosen to match with the type of event. Conditions on cards should be used with card playing conditions, conditions on minions for minion playing conditions, and so on. The condition is associated with the source of the event, rather than the target (e.g. on the card that caused the spell, rather than the minion being damaged by it). Restrictions on event targets can be expressed through the selector associated with the tag.
{
"name": "card_played",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered when the player plays any card from their hand. This event triggers before the card's effect.
{
"name": "card_used",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered after the player plays any card from their hand. This event triggers after the card's effect.
{
"name": "spell_cast",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered when the player uses a spell or secret card.
{
"name": "turn_ended",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered when the player's turn ends.
{
"name": "turn_started",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two"
"condition": Condition
}Triggered when the player's turn starts.
{
"name": "minion_died",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered when any minion that matches the condition dies.
{
"name": "minion_placed",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered when any minion that matches the condition is first placed on the board. This happens before the battlecry, and regardless of whether the minion was played from the hand or summoned.
{
"name": "minion_summoned",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered when any minion that matches the condition is summoned. This happens after the battlecry, and regardless of whether or not the minion was played from the hand or summoned via a deathrattle or spell.
{
"name": "after_added",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered after any minion that matches the condition is added to the board. This event is triggered immediately after Minion Summoned, and under the same conditions. It primarily exists for the knife juggler, who must always throw knives after all other events have taken place.
{
"name": "character_healed",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered when any character that matches the condition is healed. This only triggers when the character's health is actually restored, not just when a healing card or power is used on a character with full health.
{
"name": "character_damaged",
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition
}Triggered when any character that matches the condition is damaged. Will not trigger in the event that only armor was affected.
Character events are tied only to a single character, and so only fire when that character makes a move or change.
{
"name": "did_damage"
}Triggered whenever the character does damage to another character. This will be triggered regardless of armor on the target.
{
"name": "attack"
}Triggered whenever the character attacks another character.
{
"name": "weapon_destroyed"
}Triggered whenever the hero's weapon is destroyed.
A composite event is made up of more than one event. It's expressed as an "either" event as follows:
{
"name": "either",
"event1": Event,
"event2": Event
}Either will fire if either one of its subevents fires. Its main usage is for situations where something happens either when a card is played, or at the end of the player's turn, but it could be used in any way.
Selectors are used to specify which objects an aura or effect should affect. There are four types of selectors: card selectors, character selectors, player selectors and weapon selectors. Each selector can be refined by player and given a condition. A selector can be seen as finding a list of objects of a particular type, and then refining that list based on a condition. For example, to cause an aura to affect all friendly beasts on the board, one would use a minion selector with a minion is type condition and set player to "friendly".
All selectors have at least the following properties.
{
"name": String,
"player": "friendly" | "enemy" | "both" | "player_one" | "player_two",
"condition": Condition (optional)
}name is a string which identifies the type of the selector. It may have other properties depending on this value.
player is a string which specifies which player's objects should be searched.
condition is an optional condition that any selected objects must satisfy. If it isn't present, then the selector will get a list of all its associated objects.