enjine 0.1.0

data/lib/enjine/mechanics/triggers/ability_triggers.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Triggers
+      # "Whenever a creature you control attacking causes a triggered ability of that creature to trigger" (CR 603.2):
+      # another ability triggering is the event. `cause: "attacks"`: the other ability triggered on its own source
+      # attacking (CR 508.1). "Copy that ability" is copy_spell of {"triggering": "ability"}: the triggered ability
+      # once it's on the stack (CR 707.10); the controller orders the two abilities (CR 603.3b).
+      class AbilityTriggers < Trigger
+        CAUSES = %w[attacks].freeze
+
+        primitive :trigger, :ability_triggers,
+                  description: "A triggered ability of the subject triggers. `cause: \"attacks\"` (required): its trigger " \
+                               "event was the subject attacking. {\"triggering\": \"ability\"} is that triggered ability " \
+                               "while it's on the stack.",
+                  rules: %w[603.2 603.3b 508.1 707.10],
+                  params: { "subject" => "\"self\" (default) or {\"each\": filter, \"controller\": ..., \"other\": true}",
+                            "cause" => CAUSES.join(" | ") },
+                  example: { "ability_triggers" => { "subject" => { "each" => "creature", "controller" => "you" },
+                                                     "cause" => "attacks" } }
+
+        def self.keys = %w[subject cause]
+        def event_class = Events::AbilityTriggered
+
+        def setup(params, errors, path)
+          @cause = params["cause"]
+          errors << "#{path}.cause: must be one of #{CAUSES.join(", ")}" unless CAUSES.include?(@cause)
+        end
+
+        def match?(engine, event, source)
+          pending = engine.state.pending_triggers.find { it["id"] == event.trigger } or return false
+          cause = pending["event"] || {}
+          return false unless cause["type"] == "attacker_declared" && cause["object"] == event.source # CR 508.1
+
+          obj = engine.state.objects[event.source] or return false
+          @subject.match?(engine, event.source, obj.controller, obj.card, source, types: engine.chars(obj).types)
+        end
+
+        def occurrences(engine, event, source)
+          return [] unless match?(engine, event, source)
+
+          [{ "object" => event.source, "player" => engine.object(event.source).controller, "card" => event.card,
+             "ability" => event.trigger }]
+        end
+
+        def to_s = "Whenever #{@subject} attacking causes a triggered ability of it to trigger"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/triggers/any_of.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Triggers
+      # "Whenever ~ enters or attacks": one ability with several trigger events. It triggers once
+      # per event that matches any of them (CR 603.2c).
+      class AnyOf < Trigger
+        primitive :trigger, :any_of,
+                  description: "Triggers when any of the listed trigger conditions is met.",
+                  rules: %w[603.2 603.2c],
+                  params: { "(list)" => "two or more trigger conditions" },
+                  example: { "any_of" => [{ "enters" => {} }, { "attacks" => {} }] }
+
+        attr_reader :parts
+
+        def self.scalar_params? = true
+
+        def self.build(params, errors, path, **)
+          unless params.is_a?(Array) && params.size >= 2
+            errors << "#{path}: must be a list of at least two trigger conditions"
+            params = []
+          end
+          parts = params.each_with_index.filter_map { |entry, i| Mechanics.build_entry(:trigger, entry, errors, "#{path}[#{i}]") }
+          new(parts)
+        end
+
+        def initialize(parts) # rubocop:disable Lint/MissingSuper -- no subject or params of its own
+          @parts = parts.freeze
+          freeze
+        end
+
+        def watches?(event) = parts.any? { it.watches?(event) }
+        def leaves_battlefield? = parts.any?(&:leaves_battlefield?)
+        def match?(engine, event, source) = parts.any? { it.watches?(event) && it.match?(engine, event, source) }
+
+        def to_s
+          parts.map(&:to_s).each_with_index.map { |text, i| i.zero? ? text : text.sub(/\A(When|Whenever) /, "") }.join(" or ")
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/triggers/base.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Triggers
+      # Trigger conditions for triggered abilities (CR 603). A trigger watches one kind of
+      # event and decides whether it matches for a given source permanent:
+      #   match?(engine, event, source) -> true/false
+      # `source` is a Hash with "id", "card", "controller" (for a permanent that just left
+      # the battlefield it describes the object as it last existed, CR 603.10a).
+      # What an event tells a triggered ability about itself (CR 603.2): the object and player it is
+      # about and a number ("that many"). Effects name them with {"triggering": "object" | "player"}
+      # and the amount {"triggering": "amount"}; "card" is the object's card, for conditions.
+      def self.event_facts(engine, event)
+        facts = {}
+        case event
+        when Events::ZoneChanged then facts.merge!("object" => event.new_id, "player" => engine.names.index(event.owner))
+        when Events::SpellCast, Events::DilemmaFaced, Events::Tapped, Events::AttackerDeclared, Events::BecameBlocked,
+             Events::BlockerDeclared
+          facts["object"] = event.object
+        when Events::AbilityActivated then facts.merge!("object" => event.source, "ability" => event.object)
+        when Events::TriggerPutOnStack then facts["ability"] = event.object
+        when Events::DamageDealt
+          facts.merge!("object" => event.source, "amount" => event.amount, "player" => Filters.player_index(engine, event.target))
+        when Events::LifeChanged then facts["amount"] = [event.gain, event.loss].max
+        when Events::CountersChanged then facts.merge!("object" => event.object, "amount" => event.to - event.from)
+        when Events::StepBegan then facts["player"] = engine.state.active # "that player": whose step it is
+        end
+        cast_facts(engine, event, facts) if event.is_a?(Events::SpellCast)
+        facts["player"] ||= engine.names.index(event.player) if event.respond_to?(:player)
+        facts["card"] = event.respond_to?(:card) ? event.card : engine.state.objects[facts["object"]]&.card
+        facts.compact
+      end
+
+      # CR 601.2h: the mana spent to cast "that spell" and the sources of what artifacts made, as it was cast;
+      # storm's "that many" (CR 702.40a).
+      def self.cast_facts(engine, event, facts)
+        spell = engine.state.objects[event.object]
+        facts["mana_spent"] = spell&.mana_spent&.dup
+        facts["mana_from"] = Snapshot.deep_copy(spell&.memory&.[]("mana_from"))
+        facts["amount"] = Triggers.spells_before(engine)
+      end
+
+      def self.filter_words(filter)
+        return nil if filter.nil?
+
+        filter.is_a?(Class) ? filter.primitive_name.tr("_", " ") : filter.to_s
+      end
+
+      # One entry (the event facts) per occurrence of the trigger event in `event` (CR 603.2c). Works for
+      # any trigger condition, including ones that only answer match? (a Saga's chapter trigger).
+      def self.occurrences(trigger, engine, event, source)
+        return trigger.occurrences(engine, event, source) if trigger.respond_to?(:occurrences)
+
+        trigger.match?(engine, event, source) ? [event_facts(engine, event)] : []
+      end
+
+      # Who a trigger is about: "self" (default), "attached" (the creature the source equips or
+      # enchants, CR 301.5f / 303.4m), "watched" (the objects a delayed triggered ability was created
+      # to watch, CR 603.7c: "when that creature dies this turn") or {"each": filter, "controller": ...,
+      # "other": true}.
+      class Subject
+        def self.build(data, errors, path)
+          data = "self" if data.nil?
+          return new(data.to_sym) if %w[self attached watched].include?(data)
+
+          unless data.is_a?(Hash) && data["each"]
+            errors << "#{path}: must be \"self\", \"attached\", \"watched\" or " \
+                      "{\"each\": filter, \"controller\": you|opponent|any, \"other\": bool}"
+            return nil
+          end
+          Mechanics.check_keys(data, %w[each controller other], errors, path)
+          filter = Mechanics.build_entry(:filter, data["each"], errors, "#{path}.each")
+          controller = data.fetch("controller", "any")
+          errors << "#{path}.controller: must be one of you, opponent, any" unless %w[you opponent any].include?(controller)
+          new(:each, filter, controller, other: data["other"] == true)
+        end
+
+        def initialize(kind, filter = nil, controller = nil, other: false)
+          @kind = kind
+          @filter = filter
+          @controller = controller
+          @other = other
+          freeze
+        end
+
+        # Does the object `object_id` (controlled by `object_controller`, of card `card`) count?
+        # `types`: its card types at the time (current or last known, CR 603.10a); printed if omitted.
+        def match?(engine, object_id, object_controller, card, source, types: nil)
+          return object_id == source["id"] if @kind == :self
+          return object_id == engine.state.objects[source["id"]]&.attached_to if @kind == :attached
+          return Array(source["watched"]).include?(object_id) if @kind == :watched
+          return false if @other && object_id == source["id"]
+          return false unless controller_ok?(object_controller, source["controller"])
+
+          obj = engine.state.objects[object_id]
+          return @filter.match_for?(engine, object_id, source["controller"], source["id"]) if obj&.zone == :battlefield
+
+          # Left the battlefield: as it last existed (CR 603.10a), from its card, last known types and counters.
+          defn = engine.catalog.fetch(card)
+          chars = types ? defn.printed_characteristics.with(types: types) : defn.printed_characteristics
+          lki = engine.last_known(object_id) || {}
+          token = lki.fetch("token") { defn.token? } # a token copy of a card (CR 111.1)
+          @filter.matches_facts?(Filters::Facts.new(chars: chars, counters: lki.fetch("counters", nil) || {}, token: token,
+                                                    chosen: engine.state.objects[source["id"]]&.memory))
+        end
+
+        def controller_ok?(object_controller, you)
+          @controller == "any" || (@controller == "you") == (object_controller == you)
+        end
+
+        def to_s
+          return "this" if @kind == :self
+          return "the attached creature" if @kind == :attached
+          return "that object" if @kind == :watched
+
+          "#{"another " if @other}#{@filter.primitive_name.tr("_",
+                                                              " ")}#{{ "you" => " you control",
+                                                                       "opponent" => " an opponent controls" }[@controller]}"
+        end
+      end
+
+      # Base class for trigger conditions.
+      class Trigger < Primitive
+        def self.keys = %w[subject]
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, keys, errors, path)
+          new(params.transform_keys(&:to_s), errors, path)
+        end
+
+        def initialize(params, errors, path)
+          super()
+          @subject = Subject.build(params["subject"], errors, "#{path}.subject") if self.class.keys.include?("subject")
+          setup(params, errors, path)
+          freeze
+        end
+
+        def setup(_params, _errors, _path) = nil
+        def leaves_battlefield? = false
+
+        # Whether this trigger looks at `event` at all (one event class by default).
+        def watches?(event) = event.is_a?(event_class)
+
+        # "One or more ...": all occurrences in one event batch trigger it once (CR 603.2c).
+        def batched? = false
+
+        # "When you cast this spell": the trigger functions while its card is a spell on the stack.
+        def own_spell? = false
+
+        # The event facts of each occurrence this trigger matches (CR 603.2c); see Triggers.event_facts.
+        def occurrences(engine, event, source) = match?(engine, event, source) ? [Triggers.event_facts(engine, event)] : []
+      end
+
+      # Matching the source's "as this enters" choice (CR 614.12, 607.2): `"name": "chosen"` is "with the
+      # chosen name" (CR 201.4) and `"mana_value": "chosen"` is "with mana value equal to the chosen number".
+      module ChosenMatch
+        def setup_chosen(params, errors, path)
+          @chosen = %w[name mana_value].select { params.key?(it) }
+          @chosen.each { errors << "#{path}.#{it}: must be \"chosen\"" unless params[it] == "chosen" }
+        end
+
+        # `card`: the card the spell or source is; `x_value`: the X announced for a spell on the stack (CR 202.3e).
+        def chosen_ok?(engine, source, card, x_value = 0)
+          memory = engine.state.objects[source["id"]]&.memory || {}
+          defn = engine.catalog.fetch(card)
+          @chosen.all? do |key|
+            if key == "name" then !memory["chosen_name"].nil? && defn.name == memory["chosen_name"]
+            else
+              cost = defn.mana_cost
+              !memory["chosen_number"].nil? && (cost ? cost.mana_value + (cost.x_symbols * x_value.to_i) : 0) == memory["chosen_number"]
+            end
+          end
+        end
+
+        def chosen_words = @chosen.map { it == "name" ? " with the chosen name" : " with mana value equal to the chosen number" }.join
+      end
+
+      PLAYERS = %w[you opponent any].freeze
+
+      # Base for triggers about a player ("whenever you gain life", "whenever you attack"):
+      # `controller` is you (default) | opponent | any, relative to the source's controller.
+      class PlayerTrigger < Trigger
+        def self.keys = %w[controller]
+
+        def setup(params, errors, path)
+          @controller = params.fetch("controller", "you")
+          errors << "#{path}.controller: must be one of #{PLAYERS.join(", ")}" unless PLAYERS.include?(@controller)
+        end
+
+        def player_ok?(engine, player_name, source)
+          return true if @controller == "any"
+
+          (@controller == "you") == (engine.names.index(player_name) == source["controller"])
+        end
+
+        def who = { "you" => "you", "opponent" => "an opponent", "any" => "a player" }.fetch(@controller)
+      end
+
+      # A `batched` flag: "one or more ..." triggers once per event batch (CR 603.2c), and its "that many"
+      # ({"triggering": "amount"}) is how many occurrences the batch had (Engine::Triggering#queue_trigger).
+      module Batched
+        def setup_batched(params, errors, path)
+          @batched = params.fetch("batched", false)
+          errors << "#{path}.batched: must be true or false" unless [true, false].include?(@batched)
+        end
+
+        def batched? = @batched
+      end
+
+      # Matching a card (not a permanent) by its printed characteristics.
+      module CardMatch
+        def setup_card(params, errors, path)
+          @card = params["card"] && Mechanics.build_entry(:filter, params["card"], errors, "#{path}.card")
+        end
+
+        def card_ok?(engine, card)
+          return true unless @card
+
+          defn = engine.catalog.fetch(card)
+          @card.matches_facts?(Filters::Facts.new(chars: defn.printed_characteristics, counters: {}, token: defn.token?))
+        end
+
+        def card_words = @card ? Triggers.filter_words(@card) : "card"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/triggers/casting.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Triggers
+      # "Whenever you cast a spell" (optionally only matching spells); "when you cast this spell" (`self`).
+      # It triggers once the spell becomes cast (CR 601.2i), so a cast that is cancelled never triggers it.
+      class Cast < Trigger
+        include ChosenMatch
+
+        primitive :trigger, :cast,
+                  description: "A player casts a spell. `controller`: you (default) | opponent | any; `spell`: creature | " \
+                               "noncreature | instant_or_sorcery, or any spell filter, e.g. {\"spell\": {\"subtypes\": " \
+                               "[\"saga\"]}} or {\"one_of\": [...]} for \"creature or Spacecraft spell\"; `name` / " \
+                               "`mana_value`: \"chosen\" (the source's as-it-entered choice); `self: true`: \"when you cast " \
+                               "this spell\" (it functions on the stack). `targets`: only a spell that targets something " \
+                               "matching this filter (\"self\": this permanent), e.g. {\"creature\": {\"controller\": " \
+                               "\"you\"}}. `from` / `not_from`: only a spell cast from (not from) that zone: hand | " \
+                               "graveyard | exile | library | outside. `single_target: true`: only a spell with exactly " \
+                               "one target.",
+                  rules: %w[603.2 601.2i 113.6 202.3e 201.4 607.2 115.1 601.2a 601.2c],
+                  params: { "controller" => "you | opponent | any", "spell" => "creature | noncreature | instant_or_sorcery | filter",
+                            "name" => "\"chosen\"", "mana_value" => "\"chosen\"", "self" => "true",
+                            "targets" => "\"self\" or a target filter", "from" => "zone", "not_from" => "zone",
+                            "single_target" => "true" },
+                  example: { "cast" => { "controller" => "you", "spell" => "noncreature" } }
+
+        SPELLS = %w[creature noncreature instant_or_sorcery].freeze
+
+        def self.keys = %w[controller spell name mana_value self targets from not_from single_target]
+        def event_class = Events::SpellCast
+        def own_spell? = @self
+
+        def setup(params, errors, path)
+          @controller = params.fetch("controller", "you")
+          @self = params["self"] == true
+          raw = params["spell"]
+          errors << "#{path}.controller: must be one of you, opponent, any" unless %w[you opponent any].include?(@controller)
+          errors << "#{path}.self: must be true" unless params["self"].nil? || @self
+          if raw.is_a?(String) && SPELLS.include?(raw) then @spell = raw
+          elsif !raw.nil? && !raw.is_a?(String) then @filter = Mechanics.build_entry(:filter, raw, errors, "#{path}.spell")
+          elsif raw then errors << "#{path}.spell: must be one of #{SPELLS.join(", ")} or a spell filter"
+          end
+          setup_chosen(params, errors, path)
+          setup_targets(params, errors, path)
+          @single = params["single_target"] == true
+          errors << "#{path}.single_target: must be true" unless params["single_target"].nil? || @single
+          @zones = CastFrom.build(params, errors, path)
+        end
+
+        def match?(engine, event, source)
+          return event.object == source["id"] if @self
+
+          caster = engine.names.index(event.player)
+          return false unless @controller == "any" || (@controller == "you") == (caster == source["controller"])
+          return false unless spell_ok?(engine, event, caster, source) && targets_ok?(engine, event, source)
+          return false unless @zones.match?((spell = engine.state.objects[event.object]) && engine.cast_origin(spell))
+
+          chosen_ok?(engine, source, event.card, engine.state.objects[event.object]&.x)
+        end
+
+        # "Those creatures" ({"triggering": "targets"}): the spell's targets that matched `targets` (all of them
+        # without it), as they were chosen (CR 601.2c).
+        def occurrences(engine, event, source)
+          return [] unless match?(engine, event, source)
+
+          [Triggers.event_facts(engine, event).merge("targets" => matched_targets(engine, event, source))]
+        end
+
+        # "A spell that targets this creature / a creature you control" (CR 115.1, 601.2c): one of the
+        # targets chosen as it was cast matches, relative to the trigger's source.
+        def setup_targets(params, errors, path)
+          raw = params["targets"]
+          @targets = raw == "self" ? :self : raw && Mechanics.build_entry(:filter, raw, errors, "#{path}.targets")
+        end
+
+        def targets_ok?(engine, event, source)
+          return false if @single && Array(event.targets).flatten.compact.uniq.size != 1 # "with a single target"
+
+          !@targets || matched_targets(engine, event, source).any?
+        end
+
+        def matched_targets(engine, event, source)
+          Array(event.targets).flatten.compact.uniq.select do |ref|
+            next true unless @targets
+
+            @targets == :self ? ref == source["id"] : @targets.match_for?(engine, ref, source["controller"], source["id"])
+          end
+        end
+
+        def spell_ok?(engine, event, caster, source)
+          return @filter.match_for?(engine, event.object, caster, source["id"]) if @filter # "of the chosen color"
+
+          types = engine.catalog.fetch(event.card).types
+          case @spell
+          when "creature" then types.include?(:creature)
+          when "noncreature" then !types.include?(:creature)
+          when "instant_or_sorcery" then types.intersect?(%i[instant sorcery])
+          else true
+          end
+        end
+
+        def to_s
+          return "When you cast this spell" if @self
+
+          kind = Triggers.filter_words(@filter) || @spell || "spell"
+          "Whenever #{{ "you" => "you cast", "opponent" => "an opponent casts" }.fetch(@controller, "a player casts")} a #{kind}" \
+            "#{@zones}#{target_words}#{chosen_words}"
+        end
+
+        def target_words
+          return "" unless @targets || @single
+
+          return " with a single target" if @single && !@targets
+
+          " that targets #{@targets == :self ? "this" : Triggers.filter_words(@targets)}"
+        end
+      end
+
+      # "Whenever a creature you control becomes the target of a spell or ability an opponent controls"
+      # (CR 115.1, 603.2): checked once the spell is cast, the ability activated or the triggered ability
+      # put on the stack with its targets, so a cancelled cast never triggers it. Each matching object
+      # that became a target is one occurrence.
+      class BecomesTarget < Trigger
+        BY = %w[opponent you any].freeze
+        EVENTS = %i[SpellCast AbilityActivated TriggerPutOnStack].freeze
+
+        primitive :trigger, :becomes_target,
+                  description: "The subject becomes the target of a spell or ability (controlled by `by`: opponent | you | " \
+                               "any (default), relative to the source's controller). One trigger per matching object " \
+                               "targeted.",
+                  rules: %w[115.1 601.2c 603.2 603.2c],
+                  params: { "subject" => "\"self\" (default) or {\"each\": filter, ...}", "by" => BY.join(" | ") },
+                  example: { "becomes_target" => { "subject" => { "each" => "creature", "controller" => "you" },
+                                                   "by" => "opponent" } }
+
+        def self.keys = %w[subject by]
+        def watches?(event) = EVENTS.any? { event.is_a?(Events.const_get(it)) }
+
+        def setup(params, errors, path)
+          @by = params.fetch("by", "any")
+          errors << "#{path}.by: must be one of #{BY.join(", ")}" unless BY.include?(@by)
+        end
+
+        def occurrences(engine, event, source)
+          player = engine.names.index(event.player)
+          return [] unless @by == "any" || (@by == "you") == (player == source["controller"])
+
+          Array(event.targets).uniq.filter_map do |ref|
+            obj = engine.state.objects[ref]
+            next unless obj && obj.zone == :battlefield
+            next unless @subject.match?(engine, ref, obj.controller, obj.card, source, types: engine.chars(obj).types)
+
+            { "object" => ref, "player" => player, "card" => obj.card }
+          end
+        end
+
+        def match?(engine, event, source) = !occurrences(engine, event, source).empty?
+
+        def to_s
+          "Whenever #{@subject} becomes the target of a spell or ability#{{ "you" => " you control",
+                                                                            "opponent" => " an opponent controls" }[@by]}"
+        end
+      end
+
+      # "Whenever a player activates an ability of a source with ..." (CR 602.2, 605.1): non-mana activated
+      # and loyalty abilities only (mana abilities aren't activated through the stack and aren't watched).
+      class ActivatesAbility < PlayerTrigger
+        include ChosenMatch
+
+        primitive :trigger, :activates_ability,
+                  description: "A player (`controller`: you (default) | opponent | any) activates an ability that isn't a " \
+                               "mana ability. `source`: optional filter on the source's card; `name: \"chosen\"`: only a " \
+                               "source with the name chosen as this permanent entered. `exhaust: true`: only an exhaust " \
+                               "ability (\"whenever you activate an exhaust ability\", CR 702.177). `boast: true`: only a " \
+                               "boast ability (\"whenever a creature you control boasts\", CR 702.142b).",
+                  rules: %w[602.2 605.1a 603.2 201.4 702.177a 702.142b],
+                  params: { "controller" => PLAYERS.join(" | "), "source" => "card filter", "name" => "\"chosen\"",
+                            "exhaust" => "true: only exhaust abilities", "boast" => "true: only boast abilities" },
+                  example: { "activates_ability" => { "controller" => "opponent" } }
+
+        def self.keys = %w[controller source name exhaust boast]
+        KINDS = { "exhaust" => :exhaust?, "boast" => :boast? }.freeze
+        def event_class = Events::AbilityActivated
+
+        def setup(params, errors, path)
+          super
+          @source = params["source"] && Mechanics.build_entry(:filter, params["source"], errors, "#{path}.source")
+          setup_chosen(params, errors, path)
+          @kinds = KINDS.select { |key, _| params[key] == true }.values
+          KINDS.each_key { errors << "#{path}.#{it}: must be true or false" unless [nil, true, false].include?(params[it]) }
+        end
+
+        def match?(engine, event, source)
+          return false unless player_ok?(engine, event.player, source) && chosen_ok?(engine, source, event.card)
+          return false unless @kinds.all? { kind?(engine, event, it) }
+          return true unless @source
+
+          defn = engine.catalog.fetch(event.card)
+          @source.matches_facts?(Filters::Facts.new(chars: defn.printed_characteristics, counters: {}, token: defn.token?))
+        end
+
+        def to_s
+          what = "#{@kinds.map { "#{it.to_s.delete("?")} " }.join}ability"
+          "Whenever #{who} activate#{"s" unless @controller == "you"} #{what.start_with?("b") ? "a" : "an"} #{what}#{chosen_words}"
+        end
+
+        private
+
+        # The activated ability on the stack is an exhaust ability (CR 702.177a) / a boast ability (CR 702.142b).
+        def kind?(engine, event, flag)
+          obj = engine.state.objects[event.object]
+          ability = obj && engine.stack_ability(obj)
+          ability.respond_to?(flag) && ability.public_send(flag)
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/triggers/combat.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Triggers
+      # "Whenever ~ attacks" / "Whenever ~ attacks for the first time each turn".
+      class Attacks < Trigger
+        primitive :trigger, :attacks,
+                  description: "The subject is declared as an attacker. `first_time_this_turn: true`: only the first " \
+                               "time that creature attacks this turn (later combats of the turn don't trigger it).",
+                  rules: %w[508.3a 603.2],
+                  params: { "subject" => "\"self\" (default) or {\"each\": filter, ...}", "first_time_this_turn" => "boolean" },
+                  example: { "attacks" => { "subject" => "self", "first_time_this_turn" => true } }
+
+        def self.keys = %w[subject first_time_this_turn]
+        def event_class = Events::AttackerDeclared
+
+        def setup(params, errors, path)
+          @first_time = params["first_time_this_turn"] == true
+          errors << "#{path}.first_time_this_turn: must be true or false" unless [nil, true, false].include?(params["first_time_this_turn"])
+        end
+
+        def match?(engine, event, source)
+          obj = engine.state.objects[event.object] or return false
+          return false if @first_time && engine.attacks_this_turn(event.object) != 1
+
+          @subject.match?(engine, event.object, obj.controller, obj.card, source, types: engine.chars(obj).types)
+        end
+
+        def to_s = "Whenever #{@subject} attacks#{" for the first time each turn" if @first_time}"
+      end
+
+      # "Whenever you attack" (CR 508.3d): once per combat, if one or more creatures attack.
+      # "Whenever you attack with creatures with total power 12 or greater for the first time each turn".
+      class PlayerAttacks < PlayerTrigger
+        primitive :trigger, :player_attacks,
+                  description: "A player declares one or more attackers (once per combat, not per creature). " \
+                               "`controller`: you (default) | opponent | any. `attacking_power` ({\"at_least\": n}): " \
+                               "only when the attacking creatures' total power is at least n as they're declared; " \
+                               "with `first_time_this_turn: true`, only the first combat this turn in which it was.",
+                  rules: %w[508.3d 508.1 603.2],
+                  params: { "controller" => PLAYERS.join(" | "), "attacking_power" => "{\"at_least\": n}",
+                            "first_time_this_turn" => "boolean" },
+                  example: { "player_attacks" => { "controller" => "you", "attacking_power" => { "at_least" => 12 },
+                                                   "first_time_this_turn" => true } }
+
+        def self.keys = %w[controller attacking_power first_time_this_turn]
+        def event_class = Events::AttacksDeclared
+
+        def setup(params, errors, path)
+          super
+          power = params["attacking_power"]
+          @at_least = power.is_a?(Hash) && power.keys == ["at_least"] && power["at_least"].is_a?(Integer) ? power["at_least"] : nil
+          errors << "#{path}.attacking_power: must be {\"at_least\": n}" if power && @at_least.nil?
+          @first_time = params["first_time_this_turn"] == true
+          errors << "#{path}.first_time_this_turn: must be true or false" unless [nil, true, false].include?(params["first_time_this_turn"])
+        end
+
+        # The attackers' total power was recorded as they were declared (Engine::TurnHistory, "attack_powers").
+        def match?(engine, event, source)
+          return false unless player_ok?(engine, event.player, source)
+
+          powers = engine.turn_log(engine.names.index(event.player)).fetch("attack_powers", [])
+          wanted = ->(power) { power >= (@at_least || 0) }
+          return false unless wanted.call(powers.last.to_i)
+
+          !@first_time || powers[0...-1].none?(&wanted)
+        end
+
+        def to_s
+          power = " with total power #{@at_least} or greater" if @at_least
+          "Whenever #{who} attack#{"s" unless @controller == "you"}#{power}#{" for the first time each turn" if @first_time}"
+        end
+      end
+
+      # "Whenever ~ blocks" / "Whenever this creature blocks a creature with flying" (CR 509.3a-b, 509.3f).
+      class Blocks < Trigger
+        primitive :trigger, :blocks,
+                  description: "The subject is declared as a blocker. With `blocking`, only when the attacking creature " \
+                               "it blocks matches that filter (\"blocks a creature with flying\"). {\"triggering\": " \
+                               "\"object\"} is the blocking creature.",
+                  rules: %w[509.3a 509.3b 509.3f 603.2],
+                  params: { "subject" => "\"self\" (default) or {\"each\": filter, ...}", "blocking" => "filter" },
+                  example: { "blocks" => { "blocking" => { "creature" => { "keywords" => ["flying"] } } } }
+
+        def self.keys = %w[subject blocking]
+        def event_class = Events::BlockerDeclared
+
+        def setup(params, errors, path)
+          @blocking = params["blocking"] && Mechanics.build_entry(:filter, params["blocking"], errors, "#{path}.blocking")
+        end
+
+        def match?(engine, event, source)
+          obj = engine.state.objects[event.object] or return false
+          return false if @blocking && !@blocking.match_for?(engine, event.attacker, source["controller"], source["id"])
+
+          @subject.match?(engine, event.object, obj.controller, obj.card, source, types: engine.chars(obj).types)
+        end
+
+        def to_s = "Whenever #{@subject} blocks#{" a #{Triggers.filter_words(@blocking)}" if @blocking}"
+      end
+
+      # "Whenever ~ becomes blocked" (CR 509.3c): once per combat, however many creatures block it.
+      class BecomesBlocked < Trigger
+        primitive :trigger, :becomes_blocked,
+                  description: "The subject becomes blocked: once per combat when blockers are declared, even if " \
+                               "several creatures block it.",
+                  rules: %w[509.3c 509.1h 603.2e],
+                  params: { "subject" => "\"self\" (default) or {\"each\": filter, ...}" },
+                  example: { "becomes_blocked" => { "subject" => "self" } }
+
+        def event_class = Events::BecameBlocked
+
+        def match?(engine, event, source)
+          obj = engine.state.objects[event.object] or return false
+          @subject.match?(engine, event.object, obj.controller, obj.card, source, types: engine.chars(obj).types)
+        end
+
+        def to_s = "Whenever #{@subject} becomes blocked"
+      end
+    end
+  end
+end