User talk:Patashu/Advanced rulebook rewrite 2

This is a sandbox page to discuss how the Advanced rulebook can be made cleaner, clearer and more technically accurate/consistent. Feel free to add drafts, suggestions, discussions, etc here and make new sections.

Terminology
The Terminology of the Advanced Rulebook as it is right now is... not ideal. It was evolved from the previous iteration of the Advanced rulebook, as opposed to being written from scratch. As we learned more about how to model Hearthstone, they started to blend together.

Here is a good technical introduction to the basic concepts, illustrating how awkward they are to define cleanly: http://pastebin.com/LAi8cxuL

JimboHS and Meerkov have some other thoughts:

[13:22]  it might be worthwhile to actually think about removing terminology [13:22]  like you can describe everything in terms of trees, or everything in terms of queues, without mixing terms [13:22]  because oftentimes it's not clear what the exact translation from one to another is [13:29]  I would love to cut out some of the description text. Can we replace it with links to the youtube videos to shrink the page a bit? [13:29]  I think 1 described example per rule is probably enough, and they can watch videos for more examples [13:31]  at least for the simple rules [13:31]  Meerkov, JimboHS: http://pastebin.com/LAi8cxuL [13:34]  mm yeah [13:34]  one challenge is that each of the key terms (sequence, phase, queue, etc.) can only be really understood in reference to something else [13:34]  yes, that is the big problem [13:34]  it would be nice to build definitions from the ground up, but i'm not sure which piece of the knot to pull on first [13:35]  like, i'm very tempted to use tree terminology because: [13:35]  ordering is implicit once you define a search order [13:35]  'phases' can be worked in by showing multiple trees that get played in order [13:35]  and it lends itself to visual presentation [13:36]  but if you try to define everything in the language of trees, you will end up either importing a lot of CS terms (child node, ancestor, etc.) [13:36] <JimboHS> or you will be more verbose than now

Definitions and links

 * From a wider wiki perspective, the current version is lacking clean definitions for terms, and easy places to link. Ideally we would integrate the rulebook a lot more into pages, through linking terms like "X Phase" to the appropriate section of the rulebook. In this way, readers can learn about advanced subjects naturally as they read card pages, rather than having to specifically seek out the rulebook and swallow it whole.


 * At present the only place with actual definitions is usually the Glossary, which itself is a bit sparse and not that well-linked to the rest of the rulebook. It's also not that useful for phases and the like, which often only make sense in the context of their encompassing sequence. Making terms have their own sections is another solution, or adding a definition at the top of the section rather than having it be just a list of related info. Otherwise simply making sure the rundown of terms (their definitions/place in the sequence of events) is clearly shown at the start of the related section could improve this.


 * An alternative might be to have a small page for each of these terms, which briefly defines it and links to a section of the rulebook for exhaustive info. I'm not sure if that would be desirable or practical, though, particularly as the information gets updated and revised.


 * Regardless, some kind of solution could be helpful in integrating the rulebook into the rest of the wiki, thus gaining greater traffic to the page and increasing reader learning. -- Taohinton (talk) 00:55, 1 November 2015 (UTC)

Glossary Rewrite
Work in progress...

Part 1: Building blocks of Hearthstone
Power.log: Allows you to record a textual version of everything that happens inside of a Hearthstone game, and lets you see the model of Entities, Tags, Triggers and so on. To turn this on, see https://github.com/jleclanche/fireplace/wiki/How-to-enable-logging

Entity: Something that exists inside of a game of Hearthstone, including Players, Heroes, Hero Powers, Cards, Weapons, attached Enchantments, Minions and the Game Entity itself. (For example, when you play a Minion from your hand, the Entity moves its ZONE from HAND to PLAY - no creation or destruction of Entities occurs, the Card and Minion are the same Entity.) Entities have many Tags that describe their identity and state (see Tag).

Tag: Describes one aspect of the state/identity of an Entity. Has a name (such as ZONE) and a value (which can be an integer, boolean (0 or 1) or string).

Tag numerical limits: 32-bit signed integers are used to represent the numerical values of Tags. These range from [-2^31, 2^31 - 1] while the value of a Tag is being recalculated. However, if a Tag would be assigned a negative value, it is assigned 0 instead. Examples:
 * If you have a Lorewalker Cho with 2^30 HEALTH and cast Divine Spirit on it, its HEALTH becomes 0 (because 2^31 assigned to a 32-bit signed integer overflows to a negative number, which is capped to 0).
 * If you play Shrinkmeister on a Wisp, it becomes a 0/1. If you end your turn, it becomes a 1/1. If instead you target it with Abusive Sargeant, it becomes a 1/1 also.
 * If you have a Wisp in your hand and a Pint-Sized Summoner and Mana Wraith in play, regardless of order of play, it costs 0 Mana to play.

Turn: The first player's first turn is turn 1. Increments by 1 whenever the current player changes. The last turn of the game is 89 (see Ending the game).

Round: A set of two turns - player 1's turn, then player 2's turn.

Common Tags:
 * ENTITY_ID/EntityID: A unique number assigned to each Entity, starting from 1 and increasing.
 * PLAYER_ID/PlayerID: Either 1 or 2. Uniquely identifies the two players of the game.
 * CardID: Uniquely identifies the kind of Entity this is (there's one for every Collectible Card, Uncollectible Card, Enchantment, Hero Power, Hero, etc that exists in Hearthstone).
 * CONTROLLER: Has the same number as the PlayerID of the player controlling this Entity.
 * ZONE: What Zone this Entity is currently in (HAND, DECK, PLAY, etc).
 * HEALTH, DAMAGE, ATTACK, etc: Self-explanatory.
 * TO_BE_DESTROYED: A tag set to 1 when a Character is hit by a Destroy effect. Set to 0 when the Character dies or enters play.

Starting the game: When a game begins, Entities are generated in this order:
 * The GameEntity is generated with ENTITY_ID 1. (This tracks things like what turn it is, what part of the turn we're in, etc)
 * The Player Entities are generated for PLAYER_ID 1 and 2 respectively. One of them at random is decided to go first (FIRST_PLAYER = 1).
 * For PLAYER_ID 1 then 2, we generate the Hero Entity, Hero Power Entity then the 30 cards of their deck in random order. Randomly, 3 (if going first) or 4 (if going second) cards will already be in their hand.
 * The Coin is generated as ENTITY_ID 68 and placed in the hand of the player going second.
 * Both players mulligan. (They pick any combination of the cards in their hand, set them aside, draw that many cards from their deck, place the mulliganned cards in their deck and shuffle their deck.)
 * Turn 1 (the first player's first turn) begins.

Ending the game: The game ends if any of the following happen:
 * The Game End Step declares a win/loss/draw (see Game End Step).
 * If Turn 90 (Turn 45 for the player going second) would begin, instead the game ends in an unconditional draw.
 * If either player concedes or disconnects, the game ends in a win for the other player.

Game End Step: A Step that runs at the end of every Sequence, but also in the Combat Sequence between the Combat Preparation Phase and Combat Phase, and two times in the End Turn Sequence (just before the Start of Turn Phase, and just before the Draw Phase). During the Death Creation Step, if a Hero is killed, PLAYSTATE is set to LOSING on the respective Player Entity. At the next Game End Step, if one or both Player Entities are LOSING, the game ends in a win/loss/draw.
 * (The technical reason why the Game End State runs at these extra times is because it runs whenever the GameEntity's STEP tag changing values. (TODO: But when you just play a card the STEP doesn't change from MAIN_ACTION, so there must be an extra time that it checks, something like NUM_OPTIONS_PLAYED_THIS_TURN incrementing?) In particular, normally during your turn it is MAIN_ACTION, but just after the Combat Preparation Phase runs but before the subsequent Death Creation Step STEP becomes MAIN_COMBAT until the Combat Phase resolves (TODO: So why can the game end between the Combat Preparation Phase and the Combat Phase, if the Game End Step runs BEFORE the Death Creation Step? Shouldn't it have to run AFTER?), and the act of ending your turn proceeds through a number of STEPs (see http://hearthstone.gamepedia.com/User:Xinhuan/Advanced_rulebook_%28rewrite%29#Turn_sequence ) and thus each has an associated Game End Step.)

Part 2: Making a Change
Coming soon!

Event:
 * 1) A change in the game's state. Has a source (Entity that caused the Event to be Created) and a target (what Entity the Event happened to). For example, if a Mistress of Pain attacks a Shieldbearer, a Damage Event is Created with source Mistress of Pain, target Shieldbearer.
 * 2) The named Event of a named Phase that is part of a Sequence (see also: Sequence).

Trigger: Card text that runs by Queueing on an Event. Triggers run arbitrary code and can Create further Events. Examples of Triggers are Deathrattles, Secrets, Battlecrys, Spell Text, Secrets any kind of Triggered effect (Lightning bolt, Inspire, Poison, etc). Specific examples:
 * 1) Explosive Sheep's Deathrattle is a Trigger on the minion's own Death Event that runs the card text 'Deal 2 damage to all minions'.
 * 2) Ironforge Rifleman's Battlecry is a Trigger in the minion's Battlecry Phase that runs the card text 'Deal 1 damage.'. (The target was specified in the act of playing Ironforged Rifleman.)
 * 3) Frothing Berserker has a Trigger on Damage Events on any minion that runs the card text 'gain +1 Attack.'

Resolve:
 * Resolving an Event means 'to Queue and Resolve all related Triggers'.
 * Resolving a Trigger means 'to run the associated card text, Resolving all Events the moment they're Created'
 * Resolving an Event Queue means 'to close the Queue to new entries, then to resolve the Events in the order they were added to the Queue'
 * Resolving a Trigger Queue means 'to close the Queue to new entries, then to resolve the Triggers in the order they were added to the Queue'. (TODO: kind of redundant, need to make it clearer when we talk about Delayed Event Queues)
 * Resolving a Phase means to resolve its associated Event (Events, in the case of a Death Phase). Then, the Steps will Resolve one by one, which might lead to a Death Phase being the next thing that gets resolved, instead of the next Named Phase of the Sequence (TODO: this is badly written)
 * Resolving a Sequence means to resolve its Phases. Finally, the Game End Step runs.

Depth-First Rule:

Queue:

Order of Play:

Priority:

Player Action:

Sequence:

Phase:

Mortally Wounded:

Pending Destroy/TO_BE_DESTROYED:

Delayed Event/Delayed Event Queue:

Death Event:

Damage Event:

Heal Event:

Summon Event:

Pre-X Trigger:

Presummon Event/Presummon Trigger:

Predamage Event/Predamage Trigger:

Predeath Event/Predeath Trigger: This was only ever used during Banana Brawl!. The moment each of your minions died and the Death Event was created, a Banana was generated and added to your hand. This meant you got all bananas before any Death Event triggers Resolved.

Aura:

Enchantment:

Aura Update (Health/Attack):

Summon Resolution Step:

Death Creation Step:

Aura Update (Other):

Queuing Condition:

Triggering Condition:

(compare hobgoblin and warsong commander here)

also need to talk about triggering zones...


 * DRs: hand, play and graveyard
 * triggers: play only or hand only, depending on the kind of trigger (flesheating ghoul vs bolvar fordragon for example)
 * secrets: play only
 * battlecries/spells: anywhere to anywhere

(auras also have zones they work in and zones they broadcast to!)

Targeting Condition:

Patashu: btw, the official wording for what you call targeting condition is "play requirement"

Holding a Dragon Rule:

Humble Safeguard: (exception: Battlecry Phase, Garrison Commander, Coldarra Drake)

Present Rule:

Livelihood Rule:

Part 3: Miscellaneous
Dominant Player Bug:

Split Trigger Queue:

Double Safeguard:

Combat Preparation Phase/Double Greedy Queue:

Force Play Event: (note two kinds)

Force Play Bug:

Steal Event:

Bounce Event:

Transform Event:

Special Summon Resolution Step: (note Poultryizer)

Example of casting a two-effect spell
[13:41] <JimboHS> if i had a card that said 'deal 3 damage, summon a random minion' [13:41] <JimboHS> and i kill something [13:41] <JimboHS> does the death always happen before the summon?

http://pastebin.com/zyjvqf16

EDIT: Since it's not clear, a Queue becomes immutable when you finish filling it, just as you start to resolve the first Trigger/Event in it. (And the Greedy Queue of the Combat Preparation Phase does not become immutable.)

Redundancy
Right now, the following sections share a lot of text with each other:

2.1 Sequences, Phases, Queues, Resolution

2.2 Death Phases and consequences of Death

4.5 Auras

5 Glossary

It would be nice if this wasn't the case.

Missing sections
Important Events, Tags and Concepts that currently lack mention in the Advanced rulebook are:


 * 'If you're holding a dragon' Deathrattles and Battlecries vs other kinds of conditional Deathrattles and Battlecries ( Discussed here https://www.reddit.com/r/hearthstone/comments/3luhow/the_hearthstone_quiz_6_are_you_smarter_than_a/cv9fw28 )
 * Should be strictly confined to the Esoteric rulebook, but trigger re-entrancy oddities: http://hearthstone.gamepedia.com/User_talk:Patashu#Trigger_Re-entrancy_Exploration
 * The difference between Death Events and being in the Graveyard: https://www.youtube.com/watch?v=k-Y-KD9W75Q&list=PLx2kRadCTuYYrck0V0soHYjBvas9dGDYI&index=95 https://www.youtube.com/watch?v=En5vFbyTNXw&list=PLx2kRadCTuYYrck0V0soHYjBvas9dGDYI&index=53
 * An explicit handling of the delayed Event Queue system (as described in Summon Resolution Step explanations)
 * the 'humble safeguard' and 'double safeguard' http://hearthstone.gamepedia.com/User_talk:Patashu#The_.27humble_safeguard.27
 * Blessing of Wisdom/Power Word: Glory vs Nightmare/Corruption/Conceal: Why they're different
 * Spell Damage +1 - does it immediately enter (Frigid Snobold, Mirror Entity, Snipe), does it immediately leave (yes - Earth Shock on Wrath of Air totem), and what happens if you Silence or Earth Shock a 1 Health minion, buffed to 2 by Stormwind Champion, and damaged to 1/2 current Health? (test also Velen's Chosen and Jungle Moonkin)
 * A giant list of everything's trigger and queuing conditions. Surprisingly I hadn't used these terms once until the Combat section overhaul - that needs to be fixed ASAP!
 * Talk explicitly about 32 bit signed arithmetic and how the final result of a tag, if negative, is set to 0 instead (but intermediate values can be temporarily negative).

Standardization of bracket usage
I suggest


 * <>: Events created (and immediately resolved) simultaneously (steal, bounce, pre-summon, after-summon) AKA Immediate Events being created/resolved
 * : Events created simultaneously, not resolved yet (damage, heal, death, summon) AKA Delayed Event Queue being populated
 * []: Events resolved simultaneously, created previously (damage, heal, death, summon) AKA Delayed Event Queue being resolved
 * {}: Triggers queued and resolved simultaneously AKA Trigger Queue being populated/resolved
 * ||: order of processing of Enchantments/Auras on a given Entity AKA Enchantment List being updated during Aura Update (Enchantment)

Renaming Combat terminology
jleclanche wants it renamed, and tbh I want it too.

[13:01] if you want to go with the hearthstone names [13:01] it's "Proposed attack" and "Attack" and "after attack" [13:02] I'm fine with Proposed attack, or pre-attack

so it'd be like


 * Combat Preparation Phase: Greedy Proposed Attack Queue resolves repeatedly until no new triggers can be added, then the Attack Queue resolves.
 * Game End Step
 * Combat Phase: Attacker deals damage, then defender deals damage, then all damage is resolved. The attacker's weapon loses durability (unless overriden by Gorehowl's effect). (Additionally, Bear Trap triggers here even if no damage is taken.)
 * Game End Step

EDIT: Got a cool idea for how we can change our model of the Combat Preparation Phase. The best part is, if it's true, then there's no such thing as a 'Greedy Queue' at all!


 * 1) When the Combat Preparation Phase begins, a 'Proposed Attack Event' is created and resolved. All triggers (Mogor, Forgetful, Noble Sac, Misdirection, Explosive, Snake, Freezing, etc) queue and resolve. (Triggers that require the target to be minion or hero only check when queuing, not resolving.)
 * 2) If the target changes, another 'Proposed Attack Event' is created, and will be resolved afterwards. (Only triggers that have not triggered yet can queue.) This process repeats if the attack is changed yet another time.
 * 3) Finally, an 'Attack Event' is created and resolved (Blessing of Wisdom, PW:G, Ice Barrier, Cutpurse, Gorehowl). Now the Phase is resolved.

How we can test this model:


 * Have a minion attack an enemy minion. Two Mogors redirect it - to face then back to the minion. (PattuX notes we can use a Noble Sac instead of the second Mogor. Either attacker is dominant player and owner of Mogor, or defender owns Mogor and plays Mogor before Noble Sacrifice. ) Does an enemy Misdirection/Explosive Trap trigger? (If yes, then a 'Proposed Attack Event' is made the moment the attack is redirected. If no, then a 'Proposed Attack Event' is made only when the previous one resolves and the target has changed.)
 * Tested by PattuX in Patch 4.1, the answer is NO: https://www.youtube.com/watch?v=d91L4Wka6b4 What happens: First 'Proposed Attack Event' is for targeting minion, so both Ogre Brute and Noble Sacrifice Queue and resolve. Second 'Proposed Attack Event' is also for targeting minion, so the Explosive Trap never triggers. So cool~ (EDIT: Just to clarify, it could be the case that a new Event is made immediately, but by the time it starts to resolve, the most up-to-date defender is used to decide what Queues. Equivalent model.)
 * If a Mogor/Forgetful minion could have triggered but failed the 50% chance (no fwoosh also), it can't queue on later 'Proposed Attack Events'. (It sounds obvious, but need to make it clear.) https://www.youtube.com/watch?v=PFo6ZfbNnZI&t=0m25s
 * If a Mogor/Forgetful minion starts targeting a minion and in the first 'Proposed Attack Event' redirects to face then gets bounced by Freezing Trap, will Explosive/Misdirection trigger? What about Ice Barrier? (Or face to minion then bounced by Freezing Trap - will Snake Trap trigger?)
 * Re-test Gorehowl bug: https://github.com/HearthSim/hs-bugs/issues/55 Figure out which event it queues on, how it interacts with Misdirection, etc
 * Tested! Looks like Gorehowl is an 'Attack Event' trigger that queues if the final target is a minion, and adds 'Bloodrage' enchantment to Gorehowl, which sets CANT_BE_DAMAGED (literally Immune) on Gorehowl to 1. After combat damage occurs, Immune prevents the durability loss. Bloodrage then triggers to end, and additionally triggers to reduce attack by 1 if the enemy target was a minion. So if you attack an enemy minion and the attack is canceled, Bloodrage and thus CANT_BE_DAMAGED linger around until the attack after, allowing you to attack face once without losing durability OR attack.) https://youtu.be/wJ35sbzkRXg

EDIT: A few misc things I need cleared up to be able to finalize the section, as well:


 * 1) Are Noble Sacrifice and Snake Trap's 'board must not be full' conditions a queuing or trigger condition? (test by having a board 1 short from full, and play them in both orders) (TESTED: trigger condition)
 * 2) Is Misdirection's 'must be another target to redirect to' condition a queuing or trigger condition? (test by having an empty board and playing Noble Sacrifice, Misdirection) (TESTED: queuing condition)
 * 3) Is Power Word: Glory a Proposed Attack Event trigger or an Attack Event trigger? (test by doing ABA with Blessing of Wisdom) (TESTED: Attack Event trigger)
 * 4) Does Noble Sacrifice have a 'attacker must not be mortally wounded' trigger condition like Misdirection and Freezing Trap? (test by having a 1-2 Health attacker and playing Explosive Trap, Noble Sacrifice) (TESTED: It doesn't. Noble Sacrifice also triggers if the attacker is returned, e.g. https://www.youtube.com/watch?v=KnnCIg_62KI&list=PLx2kRadCTuYYrck0V0soHYjBvas9dGDYI&index=98 )

EDIT: 7 mooore tests:


 * 1) minion -> hero: misdirection onto friendly minion, board full of mogors
 * 2) minion -> hero: misdirection onto friendly minion then noble sac onto enemy minion, board full of mogors
 * 3) minion -> hero: board full of mogors, attacker mortally wounded by explosive trap
 * 4) board otherwise empty, ogre brute attacks enemy hero, is redirected by noble sacrifice first, can he redirect back onto enemy hero? (presumably on the second proposed attack event if not the first, so...)
 * 5) friendly minion at 1-2 health and board otherwise empty, hero attacks into explosive trap, misdirection
 * 6) friendly minion at 1-2 health and board otherwise empty, hero attacks into explosive trap, noble sacrifice, misdirection
 * 7) friendly minion at 1-2 health and board otherwise empty, hero attacks into explosive trap, misdirection, snake trap

Combat
Already dropped into the Advanced rulebook. Yay!

Card encyclopedia
(This is probably a bad idea.)

(Properties of cards that are totally covered by rules in the Advanced rulebook won't always be covered again.)

Basic set

 * Ancestral Healing: Heals for the minion's Health, not its current damage.
 * Arcane Missiles: N-step spell - Each Damage event is resolved before the next target is chosen. Because of Rule 5, ignores mortally wounded Characters.
 * Backstab: Has a targeting condition of 'undamaged minion'.
 * Drain Life: Two-step spell - Damage is resolved before Healing begins.
 * Hammer of Wrath: Two-step spell - Damage is resolved before drawing a card.
 * Houndmaster: Has a targeting condition of 'minion is a Beast'.
 * Innervate: Because of Rule M1, cannot increase your current Mana above 10.
 * Multi-Shot: Has a play requirement of '2 or more enemy minions exist'. The order of the minions is random, but the damage events are not resolved until all are created.
 * Northshire Cleric: Trigger on Healing Event, condition 'target is a minion'.
 * Raid Leader: A Health/Attack Aura, therefore, because of Rule 4d, has priority later than all Health/Attack Enchantments.
 * Shadow Word: Pain: Has a targeting condition of 'minion has 3 or less Attack'.
 * Timber Wolf: A Health/Attack Aura, therefore, because of Rule 4d, has priority later than all Health/Attack Enchantments.
 * Tracking: The two unpicked choices are sent to the Setaside Zone. Due to a bug, does not count as drawing for the purposes of Chromaggus etc (see Rule DC4).
 * Warsong Commander: A Health/Attack Aura, therefore, because of Rule 4d, has priority later than all Health/Attack Enchantments. Seems to update correctly after Tundra Rhino regardless of play order/timing. (Note: Aura Update (Health/Attack) is actually Aura Update (Enchantment), and Tundra Rhino creates Enchantments granting Charge and therefore updates in this step as well. Warsong Commander seems to always update after Tundra Rhino regardless of play order.)

Classic set

 * Acidic Swamp Ooze: Due to Instant Weapon Destruction, the weapon's Deathrattle (if any) is resolved inside of the Battlecry Phase, rather than in a subsequent Death Phase.
 * Cleave: Has a play requirement of '2 or more enemy minions exist'. The order of the minions is random, but the damage events are not resolved until all are created.
 * Corruption: Has a targeting condition of 'target is an enemy minion'. Attaches an Enchantment that triggers in the Start of Turn Phase with effect 'Destroy this minion'. Note that the attached Enchantment initially has CONTROLLER equal to the caster (and thus triggers in the caster's Start of Turn Phase), but if the minion is stolen, the attached Enchantment will have CONTROLLER equal to the new controller (and thus triggers in the new controller's Start of Turn Phase).
 * Divine Spirit: When it resolves, calculates and attaches an Enchantment with effect 'Increase Health by current Health'. Has a rounding bug above about 2^24.
 * Dread Infernal: (TODO: Test if Dread Infernal + Brann Bronzebeard overkills mortally wounded Characters.)
 * Fan of Knives: Two-step spell - Damage is resolved before drawing a card.
 * Flametongue Totem: A Health/Attack Aura, therefore, because of Rule 4d, has priority later than all Health/Attack Enchantments.
 * Grimscale Oracle: A Health/Attack Aura, therefore, because of Rule 4d, has priority later than all Health/Attack Enchantments.
 * Gurubashi Berserker: Trigger on Damage Event, condition 'target is this minion'.