enjine 0.1.0

data/lib/enjine/mechanics/keywords/suspend.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative "../abilities/play_permissions"
+
+module Enjine
+  module Mechanics
+    module Keywords
+      # Suspend (CR 702.62a-b): a card that has suspend and is exiled with time counters is "suspended". At the
+      # beginning of its owner's upkeep they remove a time counter from it; when the last is removed, if it's
+      # exiled, they may play it without paying its mana cost, and a creature spell cast this way has haste
+      # while they control it. Both triggered abilities are the engine's (#watch!), put on the stack as this
+      # keyword's ability "keyword:suspend", so they work for a card that gained suspend ("exile it with four
+      # time counters; if it doesn't have suspend, it gains suspend", Effects::Suspend) as for a printed one.
+      class Suspend < Primitive
+        primitive :keyword, :suspend,
+                  description: "This card has suspend: while it's exiled with time counters, its owner removes one at " \
+                               "the beginning of each of their upkeeps; when the last is removed they may play it without " \
+                               "paying its mana cost (a creature spell gains haste). \"Suspend N—cost\" is the ability " \
+                               "`suspend`.",
+                  rules: %w[702.62a 702.62b], example: { "keywords" => ["suspend"] }
+
+        REF = "keyword:suspend"
+
+        # Never triggers by itself (zone :rules): the engine queues it (#watch!).
+        class Rules
+          def watches?(_event) = false
+          def leaves_battlefield? = false
+          def to_s = "Suspend"
+        end
+
+        def self.intrinsic_abilities
+          @intrinsic_abilities ||= [
+            Abilities::TriggeredAbility.new(trigger: Rules.new.freeze, targets: [].freeze, zone: :rules,
+                                            effects: [Effects::SuspendStep.new].freeze)
+          ].freeze
+        end
+
+        # The card has suspend: printed, from "Suspend N—cost", or gained in exile (memory "suspend").
+        def self.has?(engine, obj)
+          return true if obj.memory["suspend"]
+
+          chars = engine.chars(obj)
+          chars.keyword?(:suspend) || chars.abilities.any? { it.ability.is_a?(Abilities::Suspend) }
+        end
+
+        # CR 702.62b.
+        def self.suspended?(engine, obj) = obj.zone == :exile && obj.counters["time"].to_i.positive? && has?(engine, obj)
+
+        # Queues the upkeep trigger of each suspended card of the active player, and the "last counter removed"
+        # trigger of an exiled card with suspend.
+        def self.watch!(engine, event)
+          case event
+          when Events::StepBegan
+            return unless event.step == "upkeep"
+
+            engine.state.exile.each do |id|
+              obj = engine.object(id)
+              queue!(engine, obj, event, "upkeep") if obj.owner == engine.state.active && suspended?(engine, obj)
+            end
+          when Events::CountersChanged
+            return unless event.counter == "time" && event.to.zero? && event.from.positive?
+
+            obj = engine.state.objects[event.object]
+            queue!(engine, obj, event, "last") if obj&.zone == :exile && has?(engine, obj)
+          end
+        end
+
+        # CR 108.4a: the ability of a card in exile is controlled by its owner.
+        def self.queue!(engine, obj, event, step)
+          engine.queue_pending_trigger!({ "id" => obj.id, "card" => obj.card, "controller" => obj.owner, "ability" => REF },
+                                        event, { "suspend" => step })
+        end
+      end
+    end
+
+    module Abilities
+      # "Suspend N—[cost]" (CR 702.62a, 116.2f): if you could begin to cast this card from your hand, you may pay
+      # `cost` and exile it with N time counters (a special action, `{type: "special_action"}`). The card has
+      # suspend (Keywords::Suspend).
+      class Suspend < Primitive
+        primitive :ability, :suspend,
+                  description: "Suspend `amount`—`cost`: whenever you could begin to cast this card from your hand, you " \
+                               "may pay `cost` and exile it with `amount` time counters (special action " \
+                               "`{type: \"special_action\"}`); then it works as the keyword `suspend`.",
+                  rules: %w[702.62a 702.62c 116.2f],
+                  params: { "amount" => "integer >= 1 (time counters)", "cost" => "mana cost string" },
+                  example: { "suspend" => { "amount" => 3, "cost" => "{2}{W}" } }
+
+        attr_reader :amount, :special_cost
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[amount cost], errors, path)
+          amount = Mechanics.integer_param(params, :amount, errors, path, min: 1)
+          cost = Costs::ManaPayment.build(Mechanics.fetch_param(params, :cost).to_s, errors, "#{path}.cost").mana_cost
+          new(amount, cost)
+        end
+
+        def initialize(amount, cost)
+          super()
+          @amount = amount
+          @special_cost = cost
+          freeze
+        end
+
+        def kind = :suspend
+        def mana_ability? = false
+        def allowed_types = nil
+        def try_effects = []
+        def to_s = "Suspend #{amount}—#{special_cost}"
+
+        # CR 702.62a, 702.62c: when you could begin to cast it from your hand (timing; nothing forbids it).
+        def special_allowed?(engine, obj, index)
+          chars = engine.chars(obj)
+          obj.zone == :hand && (chars.type?(:instant) || chars.keyword?(:flash) || engine.sorcery_timing?(index)) &&
+            !engine.cast_forbidden?(index, obj)
+        end
+
+        def special!(engine, obj, _index) = Effects::Suspend.exile!(engine, obj.id, amount)
+      end
+    end
+
+    module Effects
+      # "Exile [it] with N time counters on it. If it doesn't have suspend, it gains suspend." (CR 702.62a-b)
+      class Suspend < Effect
+        primitive :effect, :suspend,
+                  description: "Exile each referenced card or spell with `amount` time counters on it; if it doesn't " \
+                               "have suspend, it gains suspend (keyword `suspend`) while it stays exiled.",
+                  rules: %w[702.62a 702.62b 406.1],
+                  params: { "amount" => "amount (time counters)", "to" => "selector (a spell, a card or a permanent)" },
+                  example: { "suspend" => { "to" => { "triggering" => "object" }, "amount" => 4 } }
+
+        def self.keys = %w[amount to if]
+
+        def self.exile!(engine, id, amount)
+          fresh = engine.move!(id, :exile, reason: "suspend")
+          return unless fresh&.zone == :exile
+
+          fresh.memory["suspend"] = true
+          engine.add_counters!(fresh, "time", amount, by_player: fresh.owner)
+        end
+
+        def apply(engine, ctx)
+          n = amount_for(engine, ctx)
+          refs(engine, ctx).each do |id|
+            obj = engine.state.objects[id]
+            Suspend.exile!(engine, id, n) if obj && !obj.ability? && obj.zone != :exile
+          end
+        end
+
+        def to_s = "exile with #{amount} time counters (suspend) → #{to}"
+      end
+
+      # The resolving suspend trigger (Keywords::Suspend): "upkeep" removes a time counter if the card is still
+      # suspended (CR 603.4); "last" lets its owner play it free if it's still exiled. A creature spell cast this
+      # way has haste while they control it (memory "haste_while_controlled_by").
+      class SuspendStep < CastFree
+        def self.keys = []
+
+        def initialize
+          errors = []
+          super(to: Selector.build("self", errors, "keyword:suspend", targets_count: 0), params: { "play" => true },
+                errors: errors, path: "keyword:suspend")
+        end
+
+        def run(engine, ctx, locals)
+          card = engine.state.objects[ctx.source]
+          return :done unless card&.zone == :exile || locals["asked"] || locals["casting"]
+
+          if Selector.memory(engine, ctx)["suspend"] == "upkeep"
+            engine.remove_counters!(card, "time", 1) if Keywords::Suspend.suspended?(engine, card)
+            return :done
+          end
+          super
+        end
+
+        def to_s = "remove a time counter; when the last is removed, you may play it without paying its mana cost"
+
+        private
+
+        def settle_cast!(engine, locals)
+          id = locals["casting"]
+          super
+          return if id.nil? || engine.state.objects.key?(id) || engine.state.stack.empty?
+
+          spell = engine.object(engine.state.stack.first)
+          spell.memory["haste_while_controlled_by"] = spell.controller if engine.chars(spell).creature?
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/teamwork.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "crew"
+require_relative "kicker"
+
+module Enjine
+  module Mechanics
+    module Costs
+      # The cost of teamwork N (CR 702.194a): "tap any number of creatures you control with total power N or
+      # more", chosen like crew's (one `choose_cost` decision per creature, `done` once the total is enough).
+      class Teamwork < Crew
+        def to_s = "Tap any number of untapped creatures you control with total power #{power} or greater"
+
+        # "Whenever this creature becomes tapped to pay a teamwork cost" (trigger becomes_tapped `for`).
+        def pay_chosen!(engine, object, entries)
+          entries.each { engine.emit Events::TappedForCost.new(object: it["object"], cost: "teamwork", spell: object.id) }
+        end
+      end
+    end
+
+    module Abilities
+      # Teamwork N (CR 702.194a): "As an additional cost to cast this spell, you may tap any number of creatures
+      # you control with total power N or more." It is announced like kicker (the `choose_kicker` decision) and
+      # paid like additional costs (CR 601.2b, 601.2f-h). "If this spell was cast using teamwork" is the condition
+      # `{"cast_with": "teamwork"}` (CR 702.194b); targets only for teamwork are `kicked_targets` (CR 702.194c).
+      class Teamwork < Kicker
+        primitive :ability, :teamwork,
+                  description: "Teamwork N: as you cast this spell you may also tap any number of untapped creatures " \
+                               "you control with total power N or more (the `choose_kicker` decision, then one " \
+                               "`choose_cost` per creature). `{\"cast_with\": \"teamwork\"}` holds if you did; " \
+                               "`kicked_targets` are its targets then.",
+                  rules: %w[702.194a 702.194b 702.194c 601.2b 601.2f 601.2h],
+                  params: { "power" => "integer >= 1 (the N of teamwork N)" },
+                  example: { "teamwork" => { "power" => 4 } }
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[power], errors, path)
+          new([Costs::Teamwork.new(Mechanics.integer_param(params, :power, errors, path, min: 1).to_i)].freeze)
+        end
+
+        def to_s = "Teamwork #{costs.first.power}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/ward.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../effects/pay"
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # Ward (CR 702.21a): "Whenever this permanent becomes the target of a spell or ability an opponent
+      # controls, counter that spell or ability unless that player pays [cost]." A triggered ability: it
+      # triggers as the target is chosen (CR 601.2c), goes on the stack once the spell is cast, and on
+      # resolution the targeting spell's controller may pay. Engine#choose_target! tells the trigger which
+      # spell or ability targeted it (its memory "targeted_by").
+      class Ward < TriggeredAbility
+        primitive :ability, :ward,
+                  description: "Ward: whenever this permanent becomes the target of a spell or ability an opponent " \
+                               "controls, counter that spell or ability unless its controller pays `cost`: a mana cost, " \
+                               "or a list of costs (\"Ward—Pay 2 life\", \"Ward—Discard a card or pay {2}\" with " \
+                               "`one_of`). With `waterbend`, they waterbend that cost: \"Ward—Waterbend {4}\".",
+                  rules: %w[702.21a 601.2c 603.2 701.6a 701.67a],
+                  params: { "cost" => "mana cost string, e.g. \"{2}\", or a list of costs, e.g. [{\"pay_life\": 2}]",
+                            "waterbend" => "mana cost string, instead of cost" },
+                  example: { "ward" => { "cost" => "{2}" } }
+
+        # The trigger: this permanent becomes the target of an opponent's spell or ability.
+        class BecomesTarget
+          def event_class = Events::TargetChosen
+          def watches?(event) = event.is_a?(Events::TargetChosen)
+          def leaves_battlefield? = false
+          def to_s = "When this becomes the target of a spell or ability an opponent controls"
+
+          def match?(engine, event, source)
+            return false unless event.target == source["id"]
+
+            engine.names.index(event.player) != source["controller"]
+          end
+        end
+
+        # Counters the spell or ability that targeted the permanent unless its controller pays.
+        class Counter < Effects::CounterUnlessPays
+          def refs(engine, ctx) = [engine.object(ctx.object).memory["targeted_by"]]
+          def to_s = "counter that spell or ability unless its controller pays #{what}"
+        end
+
+        TRIGGER = BecomesTarget.new.freeze
+
+        # `cost`: a mana cost string ("Ward {2}") or a list of costs ("Ward—Pay 2 life", CR 702.21a).
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[cost waterbend], errors, path)
+          raw = Mechanics.fetch_param(params, :cost)
+          bend = Mechanics.fetch_param(params, :waterbend)
+          errors << "#{path}.cost: required" if raw.nil? && bend.nil?
+          errors << "#{path}: needs exactly one of cost, waterbend" if params.key?("cost") && params.key?("waterbend")
+          effect = if raw.is_a?(Array) then Counter.new(to: nil, params: { "cost" => raw }, errors: errors, path: path)
+                   elsif bend then Counter.new(to: nil, params: { "waterbend" => bend }, errors: errors, path: path)
+                   else Counter.new(to: nil, params: { "mana" => raw || "{0}" }, errors: errors, path: "#{path}.cost")
+                   end
+          new(targets: [].freeze, effects: [effect].freeze, trigger: TRIGGER)
+        end
+
+        def to_s
+          costs = effects.first.costs
+          costs.size == 1 && costs.first.instance_of?(Costs::ManaPayment) ? "Ward #{costs.first}" : "Ward—#{costs.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/linked.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    # Linked abilities (CR 607.2a, 406.6): cards an ability of a source exiled are kept in the source's
+    # memory, so another ability of the same object can name "the cards exiled with it". A source that
+    # changes zones is a new object (CR 400.7) with no memory, so the link ends with it. Also the last
+    # known controller of objects a resolving effect moved (CR 608.2h), for {"controller_of": selector}.
+    module Linked
+      EXILED = "exiled_with"
+      UNTIL_LEAVES = "until_leaves"
+      LKI = "lki"
+
+      # Cards still in exile that an ability of `source` exiled (CR 607.2a). Once the source has left the
+      # battlefield, its triggered ability remembers them ("when this leaves, return the exiled card").
+      def self.exiled_with(engine, source, ctx = nil)
+        obj = engine.state.objects[source]
+        ids = obj ? obj.memory[EXILED] : ctx && engine.state.objects[ctx.object]&.memory&.dig("source_lki", EXILED)
+        Array(ids).select { engine.state.exile.include?(it) }
+      end
+
+      # Called by a resolving effect before it moves an object: who controlled it (CR 608.2h), kept on the
+      # resolving spell or ability. Only a permanent has a controller other than its owner.
+      def self.remember!(engine, ctx, id)
+        obj = engine.object(id)
+        (engine.object(ctx.object).memory[LKI] ||= {})[id] = obj.controller if obj.zone == :battlefield
+      end
+
+      # An amount whose {"count": selector} may name earlier effects' results ("up to that many").
+      def self.amount(raw, errors, path, targets_count, results_count)
+        return Amount.build(raw, errors, path, targets_count: targets_count) unless raw.is_a?(Hash) && raw.keys.map(&:to_s) == ["count"]
+
+        Amount.new("count", Selector.build(raw.values.first, errors, "#{path}.count", targets_count: targets_count,
+                                                                                      results_count: results_count))
+      end
+    end
+
+    class Condition
+      # Whether the referenced objects (e.g. the cards exiled with a source, CR 607.2a) have at least one
+      # card type in common. No objects share nothing.
+      class ShareCardType
+        def self.build(data, errors, path, targets_count)
+          Mechanics.check_keys(data, %w[share_card_type], errors, path)
+          raw = data["share_card_type"]
+          list = raw.is_a?(Array) ? raw : [raw]
+          new(list.each_with_index.map do |sel, i|
+            Selector.build(sel, errors, "#{path}.share_card_type#{"[#{i}]" if raw.is_a?(Array)}", targets_count: targets_count)
+          end)
+        end
+
+        def initialize(selectors)
+          @selectors = selectors
+          freeze
+        end
+
+        # A list of selectors is "they share a card type": each must still name an object (CR 701.12a).
+        def true?(engine, ctx)
+          groups = @selectors.map { |sel| sel&.resolve(engine, ctx).to_a.filter_map { engine.state.objects[it] } }
+          objects = groups.flatten
+          groups.none?(&:empty?) && !objects.map { engine.chars(it).types }.reduce(:&).empty?
+        end
+
+        def to_s = "#{@selectors.join(" and ")} share a card type"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/mana_spent.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    class Amount
+      # {"mana_spent": {"of": ..., "color": "W" | "colors": true}}: the mana spent to cast a spell (CR 601.2h),
+      # recorded by type as it was paid (an "any type" payment counts as the mana's real type, CR 609.4b):
+      #   no option        the total amount of mana spent ("X is the amount of mana spent to cast it")
+      #   "color": "W"     how much of one type was spent ("if {W}{W} was spent": at_least 2; "C" for colorless)
+      #   "colors": true   how many colors were spent (converge, CR 207.2c; colorless mana is no color, CR 105.1)
+      #   "from": spec     how much came from sources matching a card spec ("if mana from a Treasure was spent":
+      #                    {"subtypes": ["treasure"]}), as they were when they made it (Engine::ManaSources)
+      # `of` is whose: "self" (default) is this spell, or the permanent this card became as a resolving spell
+      # (CR 400.7d; its triggered abilities remember it once it has left); {"triggering": "object"} is the
+      # spell a "whenever you cast" trigger is about, as it was cast; {"target": n} is a target spell. Nothing
+      # was spent on an object that wasn't cast, and a copy of a spell had no mana spent on it (CR 707.10).
+      class ManaSpent
+        OF = "\"self\", {\"triggering\": \"object\"} or {\"target\": n}"
+
+        def self.build(data, errors, path, targets_count:, results_count: 0)
+          errors << "#{path}: must be an object" unless data.is_a?(Hash)
+          data = data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+          Mechanics.check_keys(data, %w[of color colors from], errors, path)
+          of = Selector.build(data.fetch("of", "self"), errors, "#{path}.of", targets_count: targets_count,
+                                                                              results_count: results_count)
+          errors << "#{path}.of: must be #{OF}" if of && !(%i[self target].include?(of.kind) || of.value == "object")
+          color = data["color"]
+          errors << "#{path}.color: must be one of #{Mana::TYPES.join(", ")}" unless color.nil? || Mana::TYPES.map(&:to_s).include?(color)
+          errors << "#{path}: color and colors can't be used together" if color && data["colors"]
+          errors << "#{path}.colors: must be true" unless [nil, true].include?(data["colors"])
+          errors << "#{path}: from can't be used with color or colors" if data.key?("from") && (color || data["colors"])
+          from = data.key?("from") ? CardSpec.build(data["from"], errors, "#{path}.from") : nil
+          new(of, color, data["colors"] == true, from)
+        end
+
+        def initialize(whose, color, colors, from = nil)
+          @of = whose
+          @color = color
+          @colors = colors
+          @from = from
+          freeze
+        end
+
+        def value(engine, ctx)
+          return from_count(engine, ctx) if @from
+
+          spent = ManaSpent.spent(engine, ctx, @of) || []
+          return (spent.uniq & Keywords::Sunburst::COLORS).size if @colors
+          return spent.count(@color) if @color
+
+          spent.size
+        end
+
+        def to_s
+          what = if @colors then "the number of colors of mana"
+                 elsif @color then "the amount of {#{@color}}"
+                 elsif @from then "the amount of mana from a #{@from.to_s.delete_suffix(" card")} source"
+                 else "the amount of mana"
+                 end
+          "#{what} spent to cast #{@of&.kind == :self ? "it" : @of}"
+        end
+
+        # How much of the mana spent came from sources matching `from` (their characteristics then, CR 106.6).
+        def from_count(engine, ctx)
+          sources = ManaSpent.spent(engine, ctx, @of, key: "mana_from") || []
+          sources.count { @from.chars_match?(engine, Engine::ManaSources.source_chars(it)) }
+        end
+
+        # The mana types spent on the object `whose` (the `of` selector) names, or nil when none was recorded.
+        # `key` "mana_from": instead, the remembered sources of the mana that came from artifacts.
+        def self.spent(engine, ctx, whose, key: "mana_spent")
+          case whose&.kind
+          when :target # a spell the resolving one countered: as it last existed (Engine::TurnHistory#remember_spell!)
+            ref = ctx.targets&.[](whose.value)
+            obj = engine.state.objects[ref]
+            obj ? recorded(obj, key) : engine.resolving_last_known(ref)&.[](key)
+          when :triggering then Selector.memory(engine, ctx).dig("triggering", key)
+          else own(engine, ctx, key)
+          end
+        end
+
+        # What `obj` recorded as it was cast: its mana spent (an attribute) or the mana's sources (memory).
+        def self.recorded(obj, key) = key == "mana_spent" ? obj.mana_spent : obj.memory[key]
+
+        # "This spell" while it resolves (or as it enters), else the source permanent, else what the resolving
+        # triggered ability remembers of a source that has left (CR 603.4, 608.2h).
+        def self.own(engine, ctx, key = "mana_spent")
+          holder = engine.state.objects[ctx.object]
+          return recorded(holder, key) if holder && !holder.ability?
+
+          source = engine.state.objects[ctx.source]
+          return recorded(source, key) if source && !source.ability? && %i[battlefield stack].include?(source.zone)
+
+          holder&.memory&.[]("source_#{key}")
+        end
+      end
+    end
+  end
+end