enjine 0.1.0

data/lib/enjine/engine/turn_history.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # What happened this turn and this game, for effects and conditions that look back ("if a
+    # creature died this turn", life a player lost this turn, how many times an ability resolved this
+    # turn).
+    #
+    # Everything is recorded in one place, from the events the engine already emits, before
+    # triggered abilities look at the event (so an intervening "if" sees it). A cast that is
+    # cancelled never emits SpellCast, so it never counts (CR 601.2i: a spell becomes cast only
+    # once casting is complete).
+    #
+    # Per player (PlayerState#turn_log, reset as each turn begins and kept as #last_turn_log for the turn after;
+    # #game_log for the whole game):
+    #   "spells"   card ids of spells the player cast       "life_gained" / "life_lost"  totals
+    #   "spells_from"  the zone each of those spells was cast from (CR 601.2a), in the same order
+    #   "lands_played" [card id, zone it was played from] of the lands the player played (CR 305.1)
+    #   "entered"  [card id, types, subtypes] of permanents that entered under their control
+    #   "died"     [card id, types] of their permanents put into a graveyard from the battlefield
+    #   "left"     [card id, types, subtypes] of their permanents that left the battlefield (CR 400.7)
+    #   "sacrificed" [card id, types, subtypes] of the permanents they sacrificed (CR 701.21a)
+    #   "attackers" [card id, types, subtypes] of the creatures they attacked with (CR 508.1)
+    #   "exiled"   [card id, types] of their cards put into exile, from anywhere (as it last existed)
+    #   "returned" permanents returned to their hand from the battlefield
+    #   "drawn" / "discarded"  how many cards they drew (CR 121.2) / discarded (CR 701.9a)
+    #   "dilemmas" dilemmas they faced (CR 700.17)
+    #   "noncombat_damage"  noncombat damage dealt to them (CR 120.2b)
+    #   "coin_flips"  coins they flipped (CR 705)
+    # The game log also counts the turns each player has begun ("turns").
+    # Per object (GameObject#memory, stamped with the turn): "attacked" and "resolved" counts.
+    module TurnHistory
+      def record_history!(event)
+        case event
+        when Events::TurnBegan
+          turn_logs_rolled!
+          bump!(game_log(names.index(event.active)), "turns", 1) # "your third turn of the game"
+        when Events::SpellCast then cast_recorded!(event)
+        when Events::LifeChanged then life_recorded!(event)
+        when Events::ZoneChanged
+          zone_change_recorded!(event)
+          discard_recorded!(event) # mayhem (Engine::AltCasting)
+        when Events::DilemmaFaced then bump!(log_of(event.player), "dilemmas", 1)
+        when Events::AttackerDeclared then attack_recorded!(event)
+        when Events::AttacksDeclared # the attacking creatures' total power, per combat (Triggers::PlayerAttacks)
+          (log_of(event.player)["attack_powers"] ||= []) << event.attackers.sum { power(object(it)) }
+        when Events::Resolved then resolution_recorded!(event)
+        when Events::DamageDealt then damage_recorded!(event)
+        when Events::CoinFlipped then bump!(log_of(event.player), "coin_flips", 1) # CR 705.3 (Abilities::FirstFlipsWin)
+        end
+      end
+
+      # This turn's log of the player at `index`.
+      def turn_log(index) = player(index).turn_log ||= {}
+
+      # The previous turn's log of the player at `index` ("last turn", CR 500.1: whoever's turn it was).
+      def last_turn_log(index) = player(index).last_turn_log ||= {}
+
+      # This game's log of the player at `index`.
+      def game_log(index) = player(index).game_log ||= {}
+
+      # How many times this turn the ability `ref` of `source` has finished resolving (CR 608.2).
+      def times_resolved(source, ref)
+        memory = turned_memory(state.objects[source], "resolved")
+        memory ? memory.fetch(ref, 0) : 0
+      end
+
+      # Whether the permanent attacked this turn (CR 508.1).
+      def attacked_this_turn?(id) = attacks_this_turn(id).positive?
+
+      # How many times the permanent was declared as an attacker this turn ("for the first time each turn").
+      def attacks_this_turn(id) = turned_memory(state.objects[id], "attacked")&.fetch("count", 0).to_i
+
+      # An attack undone before the declaration was legal (CR 508.1c) never happened.
+      def attack_withdrawn!(id)
+        obj = state.objects[id]
+        bump!(object_memory!(id, "attacked"), "count", -1)
+        log = turn_log(obj.controller)["attackers"]
+        log&.delete_at(log.rindex { it.first == obj.card } || log.size)
+      end
+
+      # Whether the permanent entered the battlefield this turn (memory "entered", stamped as it enters).
+      def entered_this_turn?(obj) = obj.memory["entered"] == state.turn
+
+      # CR 608.2h: a permanent leaving the battlefield is remembered as it last existed by the abilities it
+      # is the source of (on the stack, being activated or waiting to be put on the stack: "source_lki" in
+      # their memory) and by the spell or ability resolving now ("its controller" of a destroyed target).
+      def remember_last_known!(id, lki)
+        info = last_known_memory(lki)
+        state.stack.each do |sid|
+          obj = object(sid)
+          obj.memory["source_lki"] = info.dup if obj.ability? && obj.source == id
+        end
+        state.pending_triggers.each { (it["memory"] ||= {})["source_lki"] = info.dup if it["source"] == id }
+        resolving = state.frames.rfind { it["type"] == "resolve" && it["ctx"] }
+        (resolving["ctx"]["lki"] ||= {})[id] = info if resolving
+      end
+
+      # A spell leaving the stack while a spell or ability resolves ("counter target spell. If the amount of mana
+      # spent to cast that spell was less than its mana value, ..."): the resolving one remembers it as it last
+      # existed on the stack (CR 608.2h): its controller, mana spent (CR 601.2h) and mana value, X included (CR 202.3e).
+      def remember_spell!(obj)
+        resolving = state.frames.rfind { it["type"] == "resolve" && it["ctx"] } or return
+        (resolving["ctx"]["lki"] ||= {})[obj.id] = { "controller" => obj.controller, "card" => obj.card,
+                                                     "mana_spent" => obj.mana_spent&.dup, "mana_from" => obj.memory["mana_from"],
+                                                     "mana_value" => Mechanics::Amount.mana_value(self, obj) }
+      end
+
+      # The part of last known information an ability keeps in its memory ("source_lki"): plain data.
+      def last_known_memory(lki)
+        info = { "controller" => lki["controller"], "power" => lki["power"], "toughness" => lki["toughness"],
+                 "counters" => lki["counters"].dup, "card" => lki["card"], "keywords" => lki["keywords"].dup }
+        info["except"] = lki["except"] if lki["except"] # what a copy of it copies (CR 707.2, Engine::Copies)
+        info.merge(lki.slice(Mechanics::Linked::EXILED).transform_values(&:dup)) # CR 607.2a (Linked.exiled_with)
+      end
+
+      # What the resolving spell or ability remembers about an object that left the battlefield during it.
+      def resolving_last_known(id) = state.frames.rfind { it["type"] == "resolve" && it["ctx"] }&.dig("ctx", "lki", id)
+
+      # CR 702.171b: a permanent becomes saddled until the end of the turn; leaving the battlefield ends it (the
+      # card is a new object, CR 400.7), and it isn't copiable (it lives on the object, not its characteristics).
+      def saddle!(id) = object_memory!(id, "saddled")
+      def saddled?(obj) = obj.zone == :battlefield && !turned_memory(obj, "saddled").nil?
+
+      private
+
+      def log_of(player_name) = turn_log(names.index(player_name))
+
+      def turn_logs_rolled!
+        state.players.each do |pl|
+          pl.last_turn_log = pl.turn_log || {}
+          pl.turn_log = {}
+        end
+      end
+
+      def bump!(log, key, amount) = log[key] = log.fetch(key, 0) + amount
+
+      def cast_recorded!(event)
+        index = names.index(event.player)
+        (turn_log(index)["spells"] ||= []) << event.card
+        (turn_log(index)["spells_from"] ||= []) << ((spell = state.objects[event.object]) ? cast_origin(spell) : "hand")
+        bump!(game_log(index), "spells", 1)
+      end
+
+      def life_recorded!(event)
+        log = log_of(event.player)
+        bump!(log, "life_gained", event.gain) if event.gain.positive? # CR 119.9
+        bump!(log, "life_lost", event.loss) if event.loss.positive?
+      end
+
+      # CR 700.4: "dies" is battlefield to graveyard; the types are those it last had (CR 603.10a).
+      # Who it counts for: a permanent's controller as it last existed, or a card's owner.
+      def zone_change_recorded!(event)
+        entered_recorded!(event) if event.to == "battlefield"
+        land_play_recorded!(event) if event.reason == "play_land"
+        lki = event.from == "battlefield" ? last_known(event.old_id) : nil
+        departed_recorded!(event, lki) if lki
+        log = lki ? turn_log(lki["controller"]) : log_of(event.owner)
+        case event.reason
+        when "draw" then bump!(log_of(event.owner), "drawn", 1)
+        when "discard" then bump!(log_of(event.owner), "discarded", 1)
+        end
+        (log["exiled"] ||= []) << [event.card, (lki ? lki["types"] : printed_types(event.card)).map(&:to_s)] if event.to == "exile"
+      end
+
+      def entered_recorded!(event)
+        obj = state.objects[event.new_id] or return
+        (turn_log(obj.controller)["entered"] ||= []) << history_entry(event.card, chars(obj))
+      end
+
+      # CR 305.1: the player who plays a land controls it as it enters.
+      def land_play_recorded!(event)
+        index = state.objects[event.new_id]&.controller || names.index(event.owner)
+        (turn_log(index)["lands_played"] ||= []) << [event.card, event.from]
+      end
+
+      def departed_recorded!(event, lki)
+        log = turn_log(lki["controller"])
+        left = [event.card, lki["types"].map(&:to_s), lki.fetch("subtypes", []).map(&:to_s)]
+        (log["left"] ||= []) << left
+        (log["died"] ||= []) << left.first(2) if event.to == "graveyard"
+        (log["sacrificed"] ||= []) << left if event.reason == "sacrifice"
+        bump!(log_of(event.owner), "returned", 1) if event.to == "hand"
+      end
+
+      # CR 508.1: "you attacked this turn" / "attacked with a Spacecraft"; the attacker remembers it attacked.
+      def attack_recorded!(event)
+        obj = state.objects[event.object] or return
+        bump!(object_memory!(event.object, "attacked"), "count", 1)
+        (turn_log(obj.controller)["attackers"] ||= []) << history_entry(obj.card, chars(obj))
+      end
+
+      def history_entry(card, current) = [card, current.types.map(&:to_s), current.subtypes.map(&:to_s)]
+      def printed_types(card) = catalog.fetch(card).types
+
+      def damage_recorded!(event)
+        index = Mechanics::Filters.player_index(self, event.target)
+        bump!(turn_log(index), "noncombat_damage", event.amount) if index && !event.combat
+      end
+
+      def resolution_recorded!(event)
+        obj = state.objects[event.object]
+        return unless obj&.ability? && state.objects.key?(obj.source)
+
+        memory = object_memory!(obj.source, "resolved")
+        memory[obj.ability] = memory.fetch(obj.ability, 0) + 1
+      end
+
+      # A memory entry of the object that holds only this turn's data.
+      def object_memory!(id, key)
+        memory = state.objects.fetch(id).memory
+        entry = memory[key]
+        entry = memory[key] = { "turn" => state.turn } unless entry.is_a?(Hash) && entry["turn"] == state.turn
+        entry
+      end
+
+      def turned_memory(obj, key)
+        entry = obj&.memory&.[](key)
+        entry if entry.is_a?(Hash) && entry["turn"] == state.turn
+      end
+
+      # What a triggered ability remembers of its source: whether it was cast (CR 400.7d) and kicked (CR 702.33d),
+      # how it was cast, the mana spent to cast it (CR 601.2h) and, for a source that just left the battlefield
+      # ("when this leaves, put its counters on ..."), how it last existed (CR 603.10a, 608.2h).
+      def trigger_memory(source)
+        obj = state.objects[source["id"]]
+        source_memory = obj&.memory || {}
+        memory = source_memory["cast"] ? { "source_cast" => true } : {}
+        memory["kicked"] = true if source_memory["kicked"] # CR 702.33d: a kicked permanent's "if it was kicked"
+        memory.merge!(source_memory.slice("cast_from", "cast_with", "kicked_with")) # "if its evoke cost was paid" (Engine::AltCasting)
+        memory["source_mana_spent"] = obj.mana_spent.dup if obj&.mana_spent
+        memory["source_mana_from"] = Snapshot.deep_copy(source_memory["mana_from"]) if source_memory["mana_from"]
+        lki = last_known(source["id"])
+        memory["source_lki"] = last_known_memory(lki) if lki
+        memory
+      end
+    end
+    include TurnHistory
+  end
+end

data/lib/enjine/engine/turn_structure.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Turn structure (CR 500): moving from step to step, the untap step's turn-based actions and the
+    # land-play allowance (CR 502, 305.2).
+    #
+    # Untap step (CR 502.1, 502.3): first, the permanents the active player controlled when they phased
+    # out phase in (unless an effect says permanents can't phase in); then the active player chooses
+    # which of their "may choose not to untap" permanents stay tapped (an `untap_choice` frame, one
+    # decision per such tapped permanent); then the rest of their permanents untap.
+    module TurnStructure
+      # ---- lands (CR 305.2) ---------------------------------------------------------------
+
+      # How many lands `index` can play this turn: one, plus one for each "you may play an additional
+      # land" ability of a permanent they control (CR 305.2). Lands put onto the battlefield by effects
+      # aren't played, so they don't count against it (CR 305.2a).
+      def land_plays_allowed(index)
+        1 + state.battlefield.sum do |id|
+          obj = object(id)
+          obj.controller == index ? chars(obj).abilities.count { it.ability.kind == :additional_land_plays } : 0
+        end
+      end
+
+      # CR 305.2a-b: whether `index` may play another land this turn.
+      def land_play_available?(index) = player(index).lands_played < land_plays_allowed(index)
+
+      # ---- the untap step (CR 502) --------------------------------------------------------
+
+      def begin_untap_step!
+        index = state.active
+        phasing_step!(index) # CR 502.1
+        candidates = untap_choice_candidates(index)
+        return finish_untap_step!(index, []) if candidates.empty?
+
+        state.frames << { "type" => "untap_choice", "player" => index, "pending" => candidates, "keep" => [] }
+        ask!(nil)
+      end
+
+      # CR 502.3: tapped permanents of `index` whose "you may choose not to untap" applies, and that
+      # would otherwise untap.
+      def untap_choice_candidates(index)
+        state.battlefield.select do |id|
+          obj = object(id)
+          current = chars(obj)
+          obj.tapped && obj.controller == index && !current.keyword?(:doesnt_untap) && !obj.memory["exerted"] &&
+            current.abilities.any? { it.ability.kind == :may_not_untap }
+        end
+      end
+
+      # The untap_choice frame: one decision per candidate, then everything else untaps.
+      def step_untap_choice!(frame)
+        frame["pending"] &= state.battlefield
+        if (id = frame["pending"].first)
+          ask!("kind" => "untap_choice", "player" => frame["player"], "object" => id)
+          return :wait
+        end
+        finish_untap_step!(frame["player"], frame["keep"])
+        :done
+      end
+
+      # Records the answer to an untap_choice decision.
+      def choose_untap!(id, untap)
+        frame = state.frames.rfind { it["type"] == "untap_choice" }
+        frame["pending"].delete(id)
+        frame["keep"] << id unless untap
+        ask!(nil)
+      end
+
+      def finish_untap_step!(index, keep)
+        untap_all!(index, keep: keep)
+        turn_based_actions_done!
+      end
+
+      # ---- turn structure (CR 500) --------------------------------------------
+
+      def begin_turn!(index)
+        end_effects_until_turn_of!(index) # "until your next turn" (CR 611.2a)
+        state.turn += 1
+        state.active = index
+        state.players.each { it.lands_played = 0 }
+        state.extra_phases = State.no_extra_phases
+        emit Events::TurnBegan.new(turn: state.turn, active: name(index))
+        enter_step!(:untap)
+      end
+
+      def enter_step!(step_name)
+        state.extra_phases["combats"] += 1 if step_name == :beginning_of_combat
+        state.step = step_name
+        state.step_state = "begin"
+        state.passes = 0
+        state.priority = nil
+      end
+
+      # Runs the game forward until a decision is pending or the game is over.
+      def advance!
+        until state.pending || state.over?
+          if (frame = state.frames.last)
+            step_frame!(frame)
+            next
+          end
+          break if state.step.nil?
+
+          case state.step_state
+          when "begin"
+            state.step_state = "active"
+            emit Events::StepBegan.new(turn: state.turn, step: state.step.to_s, phase: step.phase.to_s)
+            step.begin(self)
+          when "done" then next_step!
+          else raise Error, "engine stalled in #{state.step} (#{state.step_state}) with no pending decision"
+          end
+        end
+      end
+
+      # Steps the innermost in-progress process (see Enjine::Frames).
+      def step_frame!(frame)
+        result = Frames.fetch(frame["type"]).step(self, frame)
+        state.frames.delete_at(state.frames.rindex { it.equal?(frame) }) if result == :done && state.frames.include?(frame)
+      end
+
+      # Called once a step's turn-based actions (and any decisions they needed) are complete.
+      def turn_based_actions_done!
+        step.finish(self)
+        if !step.priority? && state.step == :cleanup && !state.pending_triggers.empty?
+          state.repeat_cleanup = true # CR 514.3a: priority now, then another cleanup step
+          state.step_state = "active"
+          give_priority!(state.active)
+        elsif step.priority?
+          give_priority!(state.active)
+        else
+          ask!(nil)
+          state.step_state = "done"
+        end
+      end
+
+      # CR 500.4: mana empties between steps. CR 500.1: proceed to the next step / turn.
+      def next_step!
+        empty_mana_pools!
+        end_combat! if state.step == :end_of_combat # CR 511.3
+        return enter_step!(:combat_damage) if second_combat_damage_step? # CR 510.4
+
+        if state.step == :cleanup && state.repeat_cleanup
+          state.repeat_cleanup = false
+          return enter_step!(:cleanup)
+        end
+        index = Steps.index(state.step) + 1
+        index += 1 while index < Steps::ORDER.size && Steps::ORDER[index].skip?(self)
+        if index >= Steps::ORDER.size
+          begin_turn!(take_next_turn!) # an extra turn comes first (CR 500.7)
+        else
+          following = Steps::ORDER[index]
+          enter_step!(following.phase == step.phase ? following.name : phase_after!(step.phase, following.name))
+        end
+      end
+
+      # ---- additional phases (CR 500.8) ---------------------------------------------------
+
+      # The first step of each kind of phase an effect can add (an added main phase is a postcombat one).
+      ADDED_PHASES = { "combat" => :beginning_of_combat, "main" => :postcombat_main }.freeze
+
+      # "After this phase, there is an additional combat phase [followed by an additional main phase]": the
+      # phases are added directly after the current phase (CR 500.8).
+      # `attackers` (filter data): "only [these] creatures can attack during that combat phase" (CR 508.1c), the
+      # first added combat phase; the queue then holds {"phase": "combat", "attackers": filter} for it.
+      def add_phases!(phases, attackers: nil)
+        if attackers && (at = phases.index("combat"))
+          phases[at] = { "phase" => "combat", "attackers" => attackers }
+        end
+        state.extra_phases["pending"] << { "after" => step.phase.to_s, "phases" => phases }
+      end
+
+      # The attack restriction of the current added combat phase (CR 508.1c), as a filter; nil when none.
+      def combat_attack_filter
+        raw = state.extra_phases["attackers"] or return nil
+        (@attack_filters ||= {})[raw] ||= Mechanics.build_entry(:filter, raw, [], "attackers")
+      end
+
+      # As `phase` ends: the first step of the next added phase, else of the phase the turn goes on with
+      # (`natural`). Phases added after the same phase come most recently created first (CR 500.8).
+      def phase_after!(phase, natural)
+        extra = state.extra_phases
+        due = extra["pending"].select { it["after"] == phase.to_s }
+        extra["pending"] -= due
+        due.each { extra["queue"].unshift(*it["phases"]) }
+        extra.delete("attackers") # a restriction lasts for its combat phase only
+        if extra["queue"].empty?
+          resume = extra.delete("resume")
+          return resume ? resume.to_sym : natural
+        end
+        extra["resume"] ||= natural.to_s
+        added = extra["queue"].shift
+        return ADDED_PHASES.fetch(added) unless added.is_a?(Hash)
+
+        extra["attackers"] = added["attackers"]
+        ADDED_PHASES.fetch(added["phase"])
+      end
+
+      # ---- ending the turn (CR 725) -------------------------------------------------------
+
+      # CR 725.1: triggered abilities waiting to be put on the stack cease to exist (725.1a); every object on
+      # the stack is exiled, the resolving one included (725.1b); state-based actions are checked (725.1c);
+      # combat ends and the game skips to the cleanup step (725.1d), where abilities that triggered meanwhile
+      # go on the stack and another cleanup step follows (725.1f, 514.3a). The resolving spell or ability does
+      # nothing more (Engine::Resolution sees "turn_ended" on its frame).
+      def end_the_turn!
+        state.pending_triggers.clear
+        state.frames.each { it["turn_ended"] = true if it["type"] == "resolve" }
+        state.stack.dup.each do |id|
+          object(id).ability? ? remove_stack_object!(id) : move!(id, :exile, reason: "end_the_turn")
+        end
+        check_state_based_actions!
+        end_combat!
+        state.extra_phases = State.no_extra_phases.merge("combats" => state.extra_phases["combats"])
+        empty_mana_pools! # CR 500.4: the step ends
+        enter_step!(:cleanup)
+      end
+
+      # "If it's the first combat phase of the turn".
+      def first_combat_phase? = state.extra_phases["combats"] == 1
+    end
+
+    include TurnStructure
+  end
+end