enjine 0.1.0

data/lib/enjine/engine/damage.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Damage, life and counters (CR 120, 119, 122), and fighting (CR 701.14).
+    module Damage
+      # CR 120.3: results of damage depend on what receives it. `combat`: combat damage (CR 510.2).
+      # Returns the damage dealt. With `lifelink: false` the caller applies lifelink itself
+      # (simultaneous combat damage: one life gain event per source, CR 120.3f, 119.9).
+      def deal_damage!(source, ref, amount, combat: false, lifelink: true)
+        return 0 unless amount.positive?
+
+        data = propose("damage", { "source" => source, "target" => ref, "amount" => amount, "combat" => combat }).data
+        dealt = deal_proposed_damage!(source, data, combat, lifelink)
+        run_follow_ups!(data) # the rest of a prevention effect (CR 615.5)
+        dealt
+      end
+
+      # The damage event after replacement and prevention effects (CR 614, 615).
+      def deal_proposed_damage!(source, data, combat, lifelink)
+        amount = data["amount"]
+        return 0 unless amount.positive? # prevented (CR 615)
+
+        ref = data["target"] # redirected (CR 614.9)
+
+        has = %i[deathtouch lifelink wither].to_h { [it, damage_source_keyword?(source, it)] }
+        index = Mechanics::Filters.player_index(self, ref)
+        if index
+          emit Events::DamageDealt.new(source: source, target: ref, amount: amount, combat: combat)
+          change_life!(index, -amount) # CR 120.3a
+        else
+          return 0 unless state.battlefield.include?(ref)
+
+          obj = object(ref)
+          defn = chars(obj)
+          emit Events::DamageDealt.new(source: source, target: ref, amount: amount, combat: combat)
+          if defn.creature?
+            mark_creature_damage!(obj, source, has[:wither], amount)
+            obj.deathtouched = true if has[:deathtouch] # CR 702.2b
+          end
+          remove_counters!(obj, "loyalty", amount) if defn.planeswalker? # CR 120.3c
+        end
+        lifelink!(source, amount) if lifelink && has[:lifelink]
+        amount
+      end
+
+      # CR 120.3d-e: damage to a creature is marked on it; from a source with wither it's -1/-1 counters
+      # put by the source's controller instead (CR 702.80a).
+      def mark_creature_damage!(obj, source, wither, amount)
+        return obj.damage += amount unless wither
+
+        add_counters!(obj, "-1/-1", amount, by_player: damage_source_controller(source))
+      end
+
+      # CR 120.6, 120.4a: damage that would be lethal to the creature `id` from `source`, counting damage already
+      # marked on it (1 if the source has deathtouch, CR 702.2c); a planeswalker's is its loyalty (CR 120.10).
+      # Nil for a player or an object that is neither.
+      def lethal_damage(source, id)
+        obj = state.objects[id]
+        return nil unless obj && state.battlefield.include?(id)
+        return loyalty(obj) if !chars(obj).creature? && chars(obj).planeswalker?
+        return nil unless chars(obj).creature?
+
+        lethal = [toughness(obj) - obj.damage, 0].max
+        damage_source_keyword?(source, :deathtouch) ? [lethal, 1].min : lethal
+      end
+
+      # CR 120.4a, 120.10: the excess damage of `amount` dealt to `id`, given its lethal damage before.
+      def excess_damage(lethal, amount) = lethal ? [amount - lethal, 0].max : 0
+
+      # Damage dealt at the same time (combat damage, CR 510.2) is one event for prevention effects
+      # that apply once per event (a shield counter, CR 122.1c). Nil outside such a batch.
+      attr_reader :damage_batch
+
+      def simultaneous_damage
+        @damage_batch = []
+        yield
+      ensure
+        @damage_batch = nil
+      end
+
+      # Whether a damage source has `keyword` (deathtouch, lifelink, wither): a card (a permanent or a spell) as it
+      # is now; a source no longer in the zone it's expected to be in, as it last existed (CR 702.2e, 702.15c,
+      # 702.80b).
+      def damage_source_keyword?(source, keyword)
+        obj = state.objects[source]
+        return obj.kind == "card" && chars(obj).keyword?(keyword) if obj
+
+        lki = last_known(source) || resolving_last_known(source) || resolving_source_lki(source)
+        Array(lki&.[]("keywords")).include?(keyword.to_s)
+      end
+
+      # The controller of a damage source, or as it last existed (CR 702.15b, 702.80a).
+      def damage_source_controller(source)
+        state.objects[source]&.controller ||
+          (last_known(source) || resolving_last_known(source) || resolving_source_lki(source))&.[]("controller")
+      end
+
+      # What the resolving ability remembers of its source, if `source` is that source (CR 608.2h).
+      def resolving_source_lki(source)
+        frame = state.frames.rfind { it["type"] == "resolve" }
+        ability = frame && state.objects[frame["object"]]
+        ability.memory&.[]("source_lki") if ability && !source.nil? && ability.source == source
+      end
+
+      # CR 702.15b: damage dealt by a source with lifelink makes its controller gain that much life.
+      def lifelink!(source, amount)
+        controller = damage_source_controller(source) or return
+        change_life!(controller, amount)
+      end
+
+      def change_life!(index, delta)
+        return if delta.zero?
+        return if delta.positive? && player_rule?(index, "cant_gain_life") # CR 119.7: not even replaced
+
+        delta = propose("life", { "player" => index, "delta" => delta }).data["delta"]
+        return if delta.zero?
+
+        pl = player(index)
+        before = pl.life
+        pl.life += delta
+        emit Events::LifeChanged.new(player: pl.name, from: before, to: pl.life)
+      end
+
+      # `by_player`: the player putting the counters (CR 122.6a; default the permanent's controller).
+      def add_counters!(object, kind, amount, by_player: nil)
+        return unless amount.positive?
+
+        data = { "object" => object.id, "counter" => kind, "amount" => amount, "player" => by_player || object.controller }
+        amount = propose("counters", data).data["amount"]
+        return unless amount.positive?
+
+        before = object.counters.fetch(kind, 0)
+        object.counters[kind] = before + amount
+        # CR 613.7c: keyword counters of this kind get the new counter's timestamp (Engine::Characteristics#ability_layers).
+        # The next timestamp isn't taken: an effect created later gets this number too and sorts after it.
+        (object.memory["counter_timestamps"] ||= {})[kind] = state.next_id if Mechanics::Counters.keyword?(kind)
+        emit Events::CountersChanged.new(object: object.id, counter: kind, from: before, to: before + amount)
+      end
+
+      # Counters on a player (CR 122.1): poison (ten or more lose the game, CR 122.1f, 704.5c), experience, rad, ...
+      def player_counters(index)
+        pl = player(index)
+        (pl.counters || {}).merge(pl.poison.positive? ? { "poison" => pl.poison } : {})
+      end
+
+      def add_player_counters!(index, kind, amount)
+        return unless amount.positive?
+
+        pl = player(index)
+        before = player_counters(index).fetch(kind, 0)
+        kind == "poison" ? pl.poison += amount : (pl.counters ||= {})[kind] = before + amount
+        emit Events::PlayerCountersChanged.new(player: pl.name, counter: kind, from: before, to: before + amount)
+      end
+
+      def remove_counters!(object, kind, amount)
+        before = object.counters.fetch(kind, 0)
+        after = [before - amount, 0].max
+        return if after == before
+
+        object.counters[kind] = after
+        emit Events::CountersChanged.new(object: object.id, counter: kind, from: before, to: after)
+      end
+
+      # ---- damage and counters --------------------------------------------------------------
+
+      # All damage marked on a permanent is removed ("healed", CR 120.6, 514.2).
+      def remove_damage!(obj)
+        obj.damage = 0
+        obj.deathtouched = false
+      end
+
+      def remove_all_counters!(obj, kind = nil)
+        (kind ? [kind] : obj.counters.keys).each { remove_counters!(obj, it, obj.counters.fetch(it, 0)) }
+      end
+
+      # CR 701.14a-d: each creature deals damage equal to its power to the other, at the same time; not
+      # combat damage. Neither deals damage unless both are still creatures on the battlefield (701.14b).
+      # A creature fighting itself deals twice its power to itself (701.14c). Returns the excess damage `one` dealt
+      # to `other` (CR 120.4a: "if excess damage is dealt to [it] this way"), 0 if they didn't fight.
+      def fight!(one, other)
+        return 0 unless [one, other].all? { state.battlefield.include?(it) && chars(it).creature? }
+
+        lethal = lethal_damage(one, other)
+        return excess_damage(lethal, deal_damage!(one, one, 2 * power(object(one)))) if one == other
+
+        powers = [power(object(one)), power(object(other))]
+        dealt = deal_damage!(one, other, powers[0])
+        deal_damage!(other, one, powers[1])
+        excess_damage(lethal, dealt)
+      end
+    end
+
+    include Damage
+  end
+end

data/lib/enjine/engine/designations.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Player designations that last for the rest of the game (PlayerState#designations), such as an enduring
+    # story (CR 702.195b). They have no rules meaning of their own; conditions read them
+    # (`{"designation": "enduring_story"}`, Mechanics::Condition::Designation).
+    module Designations
+      NAMES = %w[enduring_story].freeze
+
+      def designation?(index, designation) = player(index).designations.to_a.include?(designation)
+
+      def gain_designation!(index, designation)
+        return if designation?(index, designation)
+
+        (player(index).designations ||= []) << designation
+        emit Events::DesignationGained.new(player: name(index), designation: designation)
+      end
+
+      # Storied (CR 702.195a): "Any time you control three or more permanents that are artifacts, Sagas, and/or
+      # legendary and you don't have an enduring story, you have an enduring story for the rest of the game."
+      # Checked whenever state-based actions are, so before triggered abilities are put on the stack
+      # (CR 702.195c). Returns true when a player got one.
+      def tell_enduring_stories!
+        return false unless storied_card?
+
+        told = state.players.each_index.select do |i|
+          mine = state.battlefield.filter_map { (obj = object(it)).controller == i ? chars(obj) : nil }
+          !designation?(i, "enduring_story") && mine.any? { it.keyword?(:storied) } && mine.count { story_piece?(it) } >= 3
+        end
+        told.each { gain_designation!(it, "enduring_story") }
+        !told.empty?
+      end
+
+      private
+
+      def story_piece?(chars) = chars.type?(:artifact) || chars.legendary? || chars.subtypes.include?(:saga)
+
+      def storied_card?
+        @storied_card = !catalog.find { it.keyword?(:storied) }.nil? unless defined?(@storied_card)
+        @storied_card
+      end
+    end
+    include Designations
+  end
+end

data/lib/enjine/engine/emblems.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Emblems (CR 114): objects in the command zone with abilities and no other characteristics. An emblem
+    # is a GameObject of kind "emblem" whose `card` is the card whose effect created it and whose `ability`
+    # is that effect's reference; its abilities are part of that card's data (Effects::CreateEmblem), so it
+    # needs no card of its own. It never leaves the command zone. Its abilities function there (CR 114.4):
+    # triggered abilities (Engine::Triggers#trigger_sources), static abilities (#static_sources) and
+    # player rules (#player_rule_statics).
+    module Emblems
+      # CR 114.1, 114.2: `index` gets an emblem; returns it.
+      def create_emblem!(index, card, ref)
+        obj = create_object(card, index, :command)
+        obj.kind = "emblem"
+        obj.ability = ref
+        state.command << obj.id
+        emit Events::EmblemCreated.new(player: name(index), object: obj.id, card: card)
+        obj
+      end
+
+      # CR 114.3: an emblem has no characteristics other than its abilities. They are referenced as granted
+      # abilities ("granted:<card>:<ref>:<j>"), so a triggered one resolves from the creating card's data.
+      def emblem_characteristics(obj)
+        abilities = catalog.fetch(obj.card).effect_granted(obj.ability).map do |inst|
+          AbilityInstance.new(ref: "granted:#{obj.card}:#{inst.ref}", ability: inst.ability)
+        end
+        Enjine::Characteristics::FACE_DOWN.with(name: "Emblem", abilities: abilities.freeze)
+      end
+
+      # The emblems in the command zone, as objects.
+      def emblems = (state.command || []).map { object(it) }
+    end
+
+    include Emblems
+  end
+end

data/lib/enjine/engine/entering.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # "As this enters" choices (CR 614.12), the status a permanent enters with (Engine#plan_move), and
+    # permanents a resolving effect puts onto the battlefield.
+    module Entering
+      # Counters from the caller ("with a +1/+1 counter", CR 701.72b) add to the ones replacements gave it.
+      def merge_enters!(status, extra)
+        extra.each do |key, value|
+          status[key] = key == "counters" ? status.fetch(key, {}).merge(value) { |_, a, b| a + b } : value
+        end
+      end
+
+      # The "as this enters" choices the controller must make before `id` enters (CR 614.12), in printed order
+      # (Multiversal Passage: a basic land type, then pay 2 life or enter tapped). `id` may also be an object (a
+      # stand-in), name a land played from outside the game, or a token an effect is about to create (see
+      # #token_key).
+      def entering_choices(id)
+        id = outside_object(nil, outside_card(id)) if outside_key?(id)
+        abilities = if id.is_a?(GameObject) || state.objects.key?(id) then chars(id).abilities
+                    else token_to_create(id).printed_characteristics.abilities
+                    end
+        abilities.map(&:ability).select { it.kind == :entering_choice }
+      end
+
+      def entering_choice(id) = entering_choices(id).first
+
+      # The answers given so far, one per choice in order (a single answer from an older snapshot counts as one).
+      def self.answers(given) = given.is_a?(Hash) ? [given] : Array(given)
+
+      # Whether `id` still has an "as this enters" choice to make, given the answers so far.
+      def entering_choice_pending?(id, given) = entering_choices(id).size > Entering.answers(given).size
+
+      # Records the answer to an enter_choice decision on the frame that asked, or, for a permanent an
+      # effect puts onto the battlefield, in that effect's locals (#ask_entering_choices!).
+      def enter_choice!(option)
+        answer = option.transform_keys(&:to_s)
+        # A choice of any number of permanents (devour): each pick asks again; "done" ends it (CR 614.12).
+        return ask!(state.pending.merge("chosen" => state.pending.fetch("chosen", []) + [answer["object"]])) if answer["type"] == "devour"
+
+        answer["objects"] = state.pending["chosen"] if state.pending.key?("chosen")
+        if state.pending["effect"]
+          answers = (answering_locals["entering"] ||= {})
+          id = state.pending["object"]
+          answers[id] = Entering.answers(answers[id]) + [answer.merge("player" => state.pending["player"])]
+        else
+          frame = state.frames.last
+          frame["enter"] = Entering.answers(frame["enter"]) + [answer]
+        end
+        ask!(nil)
+      end
+
+      def ask_enter_choice!(id, controller)
+        ask!("kind" => "enter_choice", "player" => controller, "object" => id)
+        :wait
+      end
+
+      def enters_from_answer(id, frame) = entering_statuses(id, Entering.answers(frame["enter"]))
+
+      # What a permanent enters with given its "as this enters" answers, combined (memories merged, counters
+      # added, tapped if any says so), or nil.
+      def entering_statuses(id, answers)
+        choices = entering_choices(id)
+        answers.each_with_index.reduce(nil) do |status, (answer, i)|
+          extra = choices[i] && entering_status(choices[i], answer)
+          next status || extra unless status && extra
+
+          status.merge(extra) do |key, mine, theirs|
+            next mine || theirs if key == "tapped"
+            next mine.merge(theirs) { |_, a, b| a + b } if key == "counters"
+
+            mine.is_a?(Hash) ? mine.merge(theirs) : theirs
+          end
+        end
+      end
+
+      # What a permanent enters with given one "as this enters" answer (a memory, tapped, a copy, CR 707.5).
+      def entering_status(choice, answer)
+        answer = answer.except("player").transform_keys(&:to_sym)
+        choice.respond_to?(:enters_with) ? choice.enters_with(self, answer) : choice.enters_for(answer)
+      end
+
+      # What the "as this enters" answers cost, paid as the permanent enters: life (CR 119.4), the card
+      # beheld (CR 701.4a), the permanents it devours (CR 702.82a).
+      def pay_entering_costs!(controller, frame)
+        choices = entering_choices(frame["object"])
+        Entering.answers(frame["enter"]).each_with_index do |answer, i|
+          choices[i].pay!(self, controller, answer) if choices[i].respond_to?(:pay!)
+        end
+      end
+
+      # ---- permanents an effect puts onto the battlefield (CR 614.12, 614.12a) ----------------
+
+      # Before any of them enters, the player who will control each permanent makes its "as this enters"
+      # choice, one permanent at a time. `entries`: [[object id or token key, controller], ...]. Answers
+      # stay in the effect's locals (Engine#enter_choice!), so the effect resumes after each. :wait while asking.
+      def ask_entering_choices!(locals, entries)
+        answers = locals["entering"] ||= {}
+        id, controller = entries.find { |ref, _| entering_choice_pending?(ref, answers[ref]) }
+        return nil unless id
+
+        token = state.objects.key?(id) ? {} : { "card" => token_to_create(id).id }
+        ask!({ "kind" => "enter_choice", "player" => controller, "object" => id, "effect" => true }.merge(token))
+        :wait
+      end
+
+      # Puts cards onto the battlefield at the same time: replacement effects for all of them are determined
+      # before any enters (CR 614.12), with the choices asked by #ask_entering_choices!. `entries`:
+      # [[id, controller, enters]]. Returns the new permanents.
+      def enter_battlefield!(locals, entries, reason:)
+        plans = entries.map do |id, controller, enters|
+          plan_move(id, :battlefield, reason: reason, controller: controller,
+                                      enters: with_entering_answer(locals, id, controller, enters))
+        end
+        plans.compact.map { execute_zone_change!(it) }
+      end
+
+      # The entering status `enters` plus what the "as this enters" answer for `id` adds (a memory, tapped);
+      # a life payment chosen is paid now, as it enters (CR 119.4).
+      def with_entering_answer(locals, id, controller, enters)
+        answers = locals.fetch("entering", {})[id] or return enters
+        pay_entering_costs!(controller, "enter" => answers, "object" => id)
+        extra = entering_statuses(id, Entering.answers(answers)) or return enters
+        (enters || {}).merge(extra) do |key, mine, theirs|
+          next mine || theirs if key == "tapped" # "enters tapped" from the effect stays
+
+          mine.is_a?(Hash) ? mine.merge(theirs) : theirs
+        end
+      end
+
+      # The options of a pending enter_choice: the first choice not answered yet. Several permanents entering at
+      # once can't be given choices whose combined life payments are more than the player has (CR 614.12b).
+      def entering_options(pending)
+        given = pending["effect"] ? answering_locals.fetch("entering", {})[pending["object"]] : state.frames.last["enter"]
+        choice = entering_choices(pending["object"])[Entering.answers(given).size]
+        return choice.pick_options(self, pending["player"], pending.fetch("chosen", [])) if choice.respond_to?(:pick_options)
+
+        options = choice.options(self, pending["player"])
+        return options unless pending["effect"]
+
+        spent = answering_locals.fetch("entering", {}).values.flat_map { Entering.answers(it) }.sum do
+          it["player"] == pending["player"] && it["type"] == "pay_life" ? it["life"] : 0
+        end
+        options.reject { it[:type] == "pay_life" && it[:life] > player(pending["player"]).life - spent }
+      end
+
+      # A token an effect is about to create, named before it exists ("new_token:<card>:<n>") so its "as
+      # this enters" choice can be asked first (CR 614.12, 111.1).
+      def token_key(definition, index) = "new_token:#{definition.id}:#{index}"
+      def token_to_create(key) = catalog.fetch(key.to_s.split(":")[1].to_s)
+    end
+
+    include Entering
+  end
+end

data/lib/enjine/engine/face_down.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # The id prefix of a card exiled face down, so its id doesn't name it (CR 406.3).
+    FACE_DOWN_ID = "face_down"
+
+    # Cards exiled face down (CR 406.3, 406.3a-b). Such a card has no characteristics (Engine#chars) and
+    # only the players in its memory "may_look" see which card it is (View, Events::ZoneChanged). The effect
+    # that exiled it may let a player play it; the card is turned face up just before it's played, so
+    # whether it can be played is judged face up, and only for a player who may look at it.
+    module FaceDown
+      def face_down?(obj) = obj.zone == :exile && obj.memory["face_down"] == true
+
+      # Whether `index` may look at the face-down card (always true for a face-up card).
+      def may_look?(obj, index) = !face_down?(obj) || obj.memory.fetch("may_look", []).include?(index)
+
+      # Evaluates the block with the face-down card `id` seen face up (CR 406.3a: "turned face up just
+      # before the player announces that they are playing the card"). Nothing in the block changes state.
+      def face_up(id)
+        previous = @face_up
+        @face_up = id
+        yield
+      ensure
+        @face_up = previous
+      end
+    end
+    include FaceDown
+  end
+end