enjine 0.1.0

data/lib/enjine/mechanics/abilities/entering_choices.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # Shared behaviour of "as this enters, choose ..." abilities (CR 614.12, 614.12a): the controller
+      # chooses before the permanent enters (an enter_choice decision) and the permanent remembers the
+      # choice in its memory, where linked abilities read it (CR 607.2).
+      class EnteringChoice < Primitive
+        def kind = :entering_choice
+        def mana_ability? = false
+        def allowed_types = nil
+        def try_effects = []
+      end
+
+      # "As this enters, choose a number between 0 and 10."
+      class ChooseNumber < EnteringChoice
+        primitive :ability, :choose_number,
+                  description: "As this permanent enters, its controller chooses a number from `min` to `max`; abilities " \
+                               "of it that say \"the chosen number\" use it.",
+                  rules: %w[614.12 614.12a 607.2],
+                  params: { "min" => "integer (default 0)", "max" => "integer" },
+                  example: { "choose_number" => { "min" => 0, "max" => 10 } }
+
+        attr_reader :min, :max
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[min max], errors, path)
+          min = Mechanics.integer_param(params, :min, errors, path, default: 0, min: 0)
+          max = Mechanics.integer_param(params, :max, errors, path, min: 0)
+          errors << "#{path}.max: must be at least min" if max < min
+          new(min, max)
+        end
+
+        def initialize(min, max)
+          super()
+          @min = min
+          @max = max
+          freeze
+        end
+
+        def to_s = "as this enters, choose a number from #{min} to #{max}"
+        def options(_engine, _controller) = (min..max).map { { type: "number", number: it } }
+        def enters_for(answer) = { "memory" => { "chosen_number" => answer[:number] } }
+      end
+
+      # "As this enters, choose a nonland card name." The names offered are those of the cards in the game's
+      # decklists (CR 201.4: a player chooses a card name; names of cards outside the game can't matter).
+      class ChooseCardName < EnteringChoice
+        primitive :ability, :choose_card_name,
+                  description: "As this permanent enters, its controller chooses a card name among the cards in the " \
+                               "game (`not`: card types the named card mustn't have, e.g. [\"land\"]); abilities of it " \
+                               "that say \"the chosen name\" use it.",
+                  rules: %w[614.12 614.12a 201.4 201.4a 607.2],
+                  params: { "not" => "list of card types" },
+                  example: { "choose_card_name" => { "not" => ["land"] } }
+
+        attr_reader :excluded
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[not], errors, path)
+          excluded = Mechanics.fetch_param(params, :not) || []
+          types = Filters::Restricted::TYPES
+          unless excluded.is_a?(Array) && (excluded - types).empty?
+            errors << "#{path}.not: must be a list of card types (#{types.join(", ")})"
+            excluded = []
+          end
+          new(excluded.map(&:to_sym))
+        end
+
+        def initialize(excluded)
+          super()
+          @excluded = excluded.freeze
+          freeze
+        end
+
+        def to_s = "as this enters, choose a #{excluded.map { "non#{it}" }.join(" ")} card name".squeeze(" ")
+
+        def options(engine, _controller)
+          names = engine.state.decklists.flatten.uniq.filter_map do |card|
+            defn = engine.catalog.fetch(card)
+            defn.name unless defn.types.intersect?(excluded)
+          end
+          names.uniq.sort.map { { type: "name", name: it } }
+        end
+
+        def enters_for(answer) = { "memory" => { "chosen_name" => answer[:name] } }
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/abilities/entering_copy.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "entering_choices"
+require_relative "../copy_except"
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # "You may have this creature enter as a copy of any artifact or creature on the battlefield" (CR 707.5,
+      # 614.1c, 614.12): as it would enter, its controller chooses a permanent matching `of` (or none); it
+      # enters as a copy of it, with the `except` modifications, and with `with_counters: true` also with
+      # the same number and kinds of counters the copied permanent has.
+      class EnterAsCopy < EnteringChoice
+        primitive :ability, :enter_as_copy,
+                  description: "As this permanent enters, its controller may choose a permanent on the battlefield " \
+                               "matching `of`; it enters as a copy of that permanent (its copiable values, with the " \
+                               "`except` modifications) and its enter abilities trigger. `with_counters: true`: it " \
+                               "also enters with the counters the copied permanent has. Choosing none: it enters as " \
+                               "itself.",
+                  rules: %w[707.5 707.9b 614.1c 614.12],
+                  params: { "of" => "filter (the permanents it may copy)", "except" => Mechanics::CopyExcept::PARAM,
+                            "with_counters" => "boolean" },
+                  example: { "enter_as_copy" => { "of" => { "permanent" => { "any_of" => %w[artifact creature] } },
+                                                  "except" => { "legendary" => false }, "with_counters" => true } }
+
+        attr_reader :filter, :except, :with_counters
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[of except with_counters], errors, path)
+          raw = Mechanics.fetch_param(params, :of)
+          filter = raw.nil? ? (errors << "#{path}.of: required") && nil : Mechanics.build_entry(:filter, raw, errors, "#{path}.of")
+          except = Mechanics::CopyExcept.build(Mechanics.fetch_param(params, :except), errors, "#{path}.except")
+          new(filter, except, Mechanics.flag_param(params, :with_counters, errors, path))
+        end
+
+        def initialize(filter, except, with_counters)
+          super()
+          @filter = filter
+          @except = except
+          @with_counters = with_counters
+          freeze
+        end
+
+        def to_s
+          what = filter.is_a?(Class) ? filter.primitive_name : filter
+          "you may have it enter as a copy of a #{what}#{Mechanics::CopyExcept.to_s(except)}#{" with its counters" if with_counters}"
+        end
+
+        def options(engine, controller)
+          candidates = filter ? filter.candidates_for(engine, controller, nil) : []
+          candidates.select { engine.state.battlefield.include?(it) }.map { { type: "copy", object: it } } +
+            [{ type: "dont_copy" }]
+        end
+
+        # What it enters with (Engine#enters_from_answer): the copy, and the copied permanent's counters.
+        def enters_with(engine, answer)
+          obj = answer[:type] == "copy" && engine.state.objects[answer[:object]]
+          return nil unless obj && obj.zone == :battlefield
+
+          card, except = engine.copiable_values(obj)
+          enters = { "copy" => { "card" => card, "except" => Engine::Copies.merge_except(except, @except) } }
+          with_counters && !obj.counters.empty? ? enters.merge("counters" => obj.counters.dup) : enters
+        end
+
+        def enters_for(_answer) = nil
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/abilities/enters_tapped.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # "This permanent enters tapped." A replacement effect on its own entering (CR 614.1c, 614.12).
+      class EntersTapped < Primitive
+        primitive :ability, :enters_tapped,
+                  description: "This permanent enters the battlefield tapped (a self-replacement effect).",
+                  rules: %w[614.1c 614.12],
+                  example: "enters_tapped"
+
+        INSTANCE = new.freeze
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, [], errors, path)
+          INSTANCE
+        end
+
+        def kind = :enters_tapped
+        def mana_ability? = false
+        def allowed_types = nil
+        def to_s = "enters tapped"
+        def try_effects = []
+
+        # Called by the replacement pass for the entering object.
+        def modify_entering(enters) = enters["tapped"] = true
+      end
+
+      # "As this enters, you may pay N life. If you don't, it enters tapped." (CR 614.12, 119.4).
+      # The controller chooses before it enters.
+      class EntersTappedUnlessPayLife < Primitive
+        primitive :ability, :enters_tapped_unless_pay_life,
+                  description: "As this permanent enters, its controller may pay `life` life; if they don't, it enters " \
+                               "tapped. You can't pay more life than you have.",
+                  rules: %w[614.12 119.4],
+                  params: { "life" => "integer" },
+                  example: { "enters_tapped_unless_pay_life" => { "life" => 2 } }
+
+        attr_reader :life
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[life], errors, path)
+          new(Mechanics.integer_param(params, :life, errors, path, min: 1))
+        end
+
+        def initialize(life)
+          super()
+          @life = life
+          freeze
+        end
+
+        def kind = :entering_choice
+        def mana_ability? = false
+        def allowed_types = nil
+        def try_effects = []
+        def to_s = "as this enters, pay #{life} life or it enters tapped"
+
+        # Options for the controller (CR 119.4: paying life needs at least that much).
+        def options(engine, controller)
+          pay = engine.player(controller).life >= life ? [{ type: "pay_life", life: life }] : []
+          pay + [{ type: "enter_tapped" }]
+        end
+
+        def enters_for(answer) = { "tapped" => answer[:type] != "pay_life" }
+
+        # Paid as it enters (CR 119.4).
+        def pay!(engine, controller, answer)
+          engine.change_life!(controller, -answer["life"]) if answer["type"] == "pay_life"
+        end
+      end
+
+      # "As this land enters, you may behold a Jace. If you don't, this land enters tapped." (CR 614.12,
+      # 701.4a). The controller chooses what to behold (or not) before it enters; a card is revealed as it enters.
+      class EntersTappedUnlessBehold < Primitive
+        primitive :ability, :enters_tapped_unless_behold,
+                  description: "As this permanent enters, its controller may behold an object matching the card spec " \
+                               "`card` (reveal such a card from their hand or choose such a permanent they control); " \
+                               "if they don't, it enters tapped.",
+                  rules: %w[614.12 701.4a],
+                  params: { "card" => "card spec (required), e.g. {\"subtypes\": [\"jace\"]}" },
+                  example: { "enters_tapped_unless_behold" => { "card" => { "subtypes" => ["jace"] } } }
+
+        attr_reader :card
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[card], errors, path)
+          raw = Mechanics.fetch_param(params, :card)
+          errors << "#{path}.card: required" if raw.nil?
+          new(CardSpec.build(raw, errors, "#{path}.card"))
+        end
+
+        def initialize(card)
+          super()
+          @card = card
+          freeze
+        end
+
+        def kind = :entering_choice
+        def mana_ability? = false
+        def allowed_types = nil
+        def try_effects = []
+        def to_s = "as this enters, you may behold a #{card.to_s.delete_suffix(" card")}; if you don't, it enters tapped"
+
+        def options(engine, controller)
+          Beholding.candidates(engine, controller, card).map { { type: "behold", object: it } } + [{ type: "enter_tapped" }]
+        end
+
+        def enters_for(answer) = { "tapped" => answer[:type] != "behold" }
+
+        # The card is revealed as it enters (CR 701.4a).
+        def pay!(engine, controller, answer)
+          id = answer["object"]
+          Beholding.behold!(engine, controller, id) if answer["type"] == "behold" && engine.state.objects.key?(id)
+        end
+      end
+
+      # "This land enters tapped unless you control two or more other lands." A self-replacement effect that
+      # checks its condition as the permanent would enter (CR 614.1c, 614.12): it isn't on the battlefield
+      # yet, so "you control" counts only the others.
+      class EntersTappedUnless < Primitive
+        primitive :ability, :enters_tapped_unless,
+                  description: "This permanent enters tapped unless `condition` is true as it would enter (checked for " \
+                               "its controller; the permanent itself isn't on the battlefield yet).",
+                  rules: %w[614.1c 614.12],
+                  params: { "condition" => "a condition, e.g. {\"controls\": {\"each\": \"land\", \"controller\": \"you\"}, " \
+                                           "\"at_least\": 2}" },
+                  example: { "enters_tapped_unless" => { "condition" => { "controls" => { "each" => "land", "controller" => "you" },
+                                                                          "at_least" => 2 } } }
+
+        attr_reader :condition
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[condition], errors, path)
+          raw = Mechanics.fetch_param(params, :condition)
+          condition = raw.nil? ? ((errors << "#{path}.condition: required") && nil) : Condition.build(raw, errors, "#{path}.condition")
+          new(condition)
+        end
+
+        def initialize(condition)
+          super()
+          @condition = condition
+          freeze
+        end
+
+        def kind = :enters_tapped
+        def mana_ability? = false
+        def allowed_types = nil
+        def try_effects = []
+        def to_s = "enters tapped unless #{condition}"
+
+        # Called by the replacement pass for the entering object (Replacements.entering!).
+        def modify_entering_for(engine, controller, object_id, enters)
+          enters["tapped"] = true unless condition&.true?(engine, EffectContext.new(controller, object_id, nil, []))
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/abilities/enters_with_counters.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # Entering with counters: a permanent's own counters as it enters, or extra counters a permanent
+      # on the battlefield gives to matching permanents as they enter. Replacement effects that modify
+      # how a permanent enters (CR 614.1c, 614.12); counters given as it enters count as counters put
+      # on it (CR 122.6).
+      class EntersWithCounters < Primitive
+        primitive :ability, :enters_with_counters,
+                  description: "Without `affects`: this permanent enters with the `counters` on it; a count may be an " \
+                               "amount computed as it enters (e.g. the mana spent to cast it, CR 601.2h). With `affects` " \
+                               "({\"each\": filter, \"controller\": you|opponent|any, \"other\": true}, relative to " \
+                               "this permanent's controller): while this permanent is on the battlefield, each " \
+                               "matching permanent enters with the `counters` in addition to any others.",
+                  rules: %w[614.1c 614.12 122.6 122.6a],
+                  params: { "counters" => "{counter name: n} (n >= 1; without `affects`, n may be an amount)",
+                            "affects" => "optional {\"each\": filter, \"controller\": ..., \"other\": bool}" },
+                  example: { "enters_with_counters" => { "counters" => { "+1/+1" => 1 },
+                                                         "affects" => { "each" => "creature", "controller" => "you",
+                                                                        "other" => true } } }
+
+        attr_reader :counters, :filter, :controller, :amounts
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[counters affects], errors, path)
+          affects = Mechanics.fetch_param(params, :affects)
+          counters = read_counters(Mechanics.fetch_param(params, :counters), errors, "#{path}.counters", amounts: affects.nil?)
+          counters, amounts = counters.partition { |_, n| n.is_a?(Integer) }.map(&:to_h)
+          return new(counters, nil, nil, amounts) if affects.nil?
+
+          unless affects.is_a?(Hash) && affects["each"]
+            errors << "#{path}.affects: must be {\"each\": filter, ...}"
+            return new(counters, nil, nil)
+          end
+          Mechanics.check_keys(affects, %w[each controller other], errors, "#{path}.affects")
+          filter = Mechanics.build_entry(:filter, affects["each"], errors, "#{path}.affects.each")
+          live = filter ? filter.live_keys : []
+          errors << "#{path}.affects.each: #{live.join(", ")} can't be used for an entering permanent" unless live.empty?
+          controller = affects.fetch("controller", "any")
+          errors << "#{path}.affects.controller: must be one of you, opponent, any" unless %w[you opponent any].include?(controller)
+          new(counters, filter, controller)
+        end
+
+        # `amounts`: a count may be an amount (Amount), computed as the permanent enters.
+        def self.read_counters(raw, errors, path, amounts: false)
+          unless raw.is_a?(Hash) && !raw.empty?
+            errors << "#{path}: must be a non-empty object {counter name: n}"
+            return {}
+          end
+          raw.to_h do |name, n|
+            name = Counters.normalize(name)
+            Counters.parse(name, errors, "#{path}.#{name}")
+            next [name, Amount.build(n, errors, "#{path}.#{name}", targets_count: 0)] if amounts && !n.is_a?(Integer)
+
+            errors << "#{path}.#{name}: must be an integer >= 1" unless n.is_a?(Integer) && n >= 1
+            [name, n]
+          end
+        end
+
+        def initialize(counters, filter, controller, amounts = {})
+          super()
+          @counters = counters.freeze
+          @amounts = amounts.freeze
+          @filter = filter
+          @controller = controller
+          freeze
+        end
+
+        def kind = :enters_with_counters
+        def mana_ability? = false
+        def allowed_types = nil
+        def try_effects = []
+
+        def to_s
+          list = (counters.map { |name, n| "#{n} #{name} counter#{"s" if n > 1}" } +
+                  amounts.map { |name, n| "#{name} counters equal to #{n}" }).join(" and ")
+          return "enters with #{list}" unless filter
+
+          whose = { "you" => " you control", "opponent" => " your opponents control" }[controller]
+          label = filter.is_a?(Class) ? filter.primitive_name.tr("_", " ") : filter.to_s
+          "#{label}s#{whose} enter with an additional #{list}"
+        end
+
+        # The entering permanent's own replacement effect (called by Replacements for it alone).
+        def modify_entering(enters) = filter ? nil : add!(enters)
+
+        # Counts computed as it enters, from the entering object (a resolving spell: what was spent on it).
+        def modify_entering_for(engine, controller, object_id, enters)
+          ctx = EffectContext.new(controller, object_id, object_id, [])
+          amounts.each do |name, amount|
+            n = amount.value(engine, ctx)
+            enters["counters"][name] = enters["counters"].fetch(name, 0) + n if n.positive?
+          end
+        end
+
+        # A permanent on the battlefield modifying another one as it enters.
+        def affects_entering?(source, entering_controller, facts)
+          return false unless filter
+          return false unless controller == "any" || (controller == "you") == (entering_controller == source.controller)
+
+          filter.matches_facts?(facts)
+        end
+
+        def modify_other_entering(enters) = add!(enters)
+
+        private
+
+        def add!(enters)
+          counters.each { |name, n| enters["counters"][name] = enters["counters"].fetch(name, 0) + n }
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/abilities/mana_ability.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "../keywords/alternative_costs"
+
+module Enjine
+  module Mechanics
+    # "Spend this mana only to cast [quality] spells or activate abilities of [quality] sources" (CR 106.6):
+    # a restriction on mana, kept with that mana in the pool. Data:
+    #   {"spells": card spec, "abilities": card spec}   at least one; "card" matches every spell or source
+    # The spec is matched against the spell being cast or the source of the ability being activated. Mana
+    # paid for a cost while a spell or ability resolves (CR 118.12) is neither, so restricted mana can't pay it.
+    # `from` / `not_from` a zone limit the spells to those cast from (not from) it ("spend this mana only to cast
+    # a spell from anywhere other than your hand": {"not_from": "hand"}; CR 601.2a); alone, they mean spells.
+    class SpendOnly
+      KEYS = (%w[spells abilities] + CastFrom::KEYS).freeze
+
+      attr_reader :data
+
+      def self.build(data, errors, path)
+        unless data.is_a?(Hash) && !data.empty? && (data.keys.map(&:to_s) - KEYS).empty?
+          errors << "#{path}: must be {\"spells\": card spec, \"abilities\": card spec, \"from\" | \"not_from\": zone} " \
+                    "(at least one)"
+          return nil
+        end
+        data = data.transform_keys(&:to_s)
+        zones = CastFrom.build(data, errors, path)
+        specs = data.slice("spells", "abilities").to_h { |key, spec| [key, CardSpec.build(spec, errors, "#{path}.#{key}")] }
+        specs["spells"] ||= CardSpec.build("card", errors, path) if data.keys.intersect?(CastFrom::KEYS)
+        new(data, specs, zones)
+      end
+
+      # The restriction kept on pool mana (plain data, CR 106.6), rebuilt once per distinct data.
+      def self.from_data(data)
+        (@cache ||= {})[data] ||= build(data, [], "spend_only")
+      end
+
+      def initialize(data, specs, zones = CastFrom.new(nil, nil))
+        @data = Snapshot.deep_copy(data).freeze
+        @specs = specs.freeze
+        @zones = zones
+        freeze
+      end
+
+      # `purpose`: {"spell" => id} for a spell being cast, {"ability" => source id} for an ability being
+      # activated, nil for anything else.
+      def allows?(engine, purpose)
+        return false if purpose.nil?
+
+        spell = purpose.key?("spell")
+        spec = spell ? @specs["spells"] : @specs["abilities"]
+        ref = purpose["spell"] || purpose["ability"]
+        obj = ref.is_a?(GameObject) ? ref : engine.state.objects[ref] # a card outside the game is its stand-in
+        !spec.nil? && !obj.nil? && spec.match?(engine, obj) && (!spell || @zones.match?(engine.cast_origin(obj)))
+      end
+
+      def to_s
+        parts = []
+        parts << "cast #{"#{@specs["spells"]} " unless @specs["spells"].any?}spells#{@zones}" if @specs["spells"]
+        parts << "activate abilities of #{@specs["abilities"]}s" if @specs["abilities"]
+        "spend this mana only to #{parts.join(" or ")}"
+      end
+    end
+
+    module Abilities
+      # Activated mana ability (CR 605). Resolves immediately, never uses the stack. It adds the fixed
+      # mana in `produce` (`amount` times), or `amount` mana of colors chosen as it is activated
+      # (CR 605.3b, 106.1a): all of one color (`color: "any_one"`) or each separately (`"any"`).
+      class ManaAbility < Primitive
+        COLORS = Mana::COLORS.map(&:to_s).freeze
+        CHOICES = %w[any_one any chosen].freeze
+
+        primitive :ability, :mana,
+                  description: "An activated mana ability: pay the cost, add the mana to your mana pool " \
+                               "immediately. It does not use the stack and can be activated whenever you " \
+                               "have priority. `produce`: the fixed mana (`amount` times). Or `color`: " \
+                               "`amount` mana (default 1) of one color you choose as you activate it " \
+                               "(`\"any_one\"`) or in any combination of colors (`\"any\"`); `colors` limits " \
+                               "the choice. `\"chosen\"`: of the color chosen as this entered (choose_color). " \
+                               "`spend_only` restricts how the mana can be spent. `only_if`: \"Activate only if ...\".",
+                  rules: %w[605.1a 605.3a 605.3b 106.1a 106.4 106.6 607.2d 602.5b],
+                  params: { "cost" => "list of costs (e.g. [\"tap\"])",
+                            "produce" => "mana symbols added, e.g. \"{G}\" or \"{C}{C}\"",
+                            "amount" => "amount (default 1; with produce: how many times)",
+                            "color" => CHOICES.join(" | "), "colors" => "list of colors to choose from (default all five)",
+                            "spend_only" => "{\"spells\": card spec, \"abilities\": card spec, \"from\" | \"not_from\": zone}",
+                            "only_if" => "condition: it can be activated only while it holds (CR 602.5b)" },
+                  example: { "mana" => { "cost" => ["tap"], "produce" => "{C}" } }
+
+        attr_reader :costs, :produce, :color, :colors, :amount, :spend_only
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[cost produce amount color colors spend_only only_if], errors, path)
+          costs = build_costs(Mechanics.fetch_param(params, :cost), errors, path)
+          raw = Mechanics.fetch_param(params, :produce)
+          color = Mechanics.fetch_param(params, :color)
+          errors << "#{path}: needs exactly one of produce, color" unless raw.nil? ^ color.nil?
+          produce = raw && Mana.parse_produce(raw, errors, "#{path}.produce")
+          errors << "#{path}.color: must be one of #{CHOICES.join(", ")}" if color && !CHOICES.include?(color)
+          raw_amount = Mechanics.fetch_param(params, :amount)
+          amount = raw_amount.nil? ? nil : Amount.build(raw_amount, errors, "#{path}.amount", targets_count: 0)
+          raw_spend = Mechanics.fetch_param(params, :spend_only)
+          spend_only = raw_spend.nil? ? nil : SpendOnly.build(raw_spend, errors, "#{path}.spend_only")
+          raw_if = Mechanics.fetch_param(params, :only_if)
+          only_if = raw_if && Condition.build(raw_if, errors, "#{path}.only_if")
+          new(costs.compact.freeze, produce, color: color, colors: build_colors(params, color, errors, path),
+                                             amount: amount, spend_only: spend_only, only_if: only_if)
+        end
+
+        # CR 605.3a: a mana ability is paid for and resolves at once, so none of its costs can wait for a
+        # choice, an announced X or a {2/B} paid one way or the other.
+        def self.build_costs(raw, errors, path)
+          unless raw.is_a?(Array) && !raw.empty?
+            errors << "#{path}.cost: must be a non-empty list"
+            return []
+          end
+
+          raw.each_with_index.map do |c, i|
+            cost = Mechanics.build_entry(:cost, c, errors, "#{path}.cost[#{i}]")
+            errors << "#{path}.cost[#{i}]: a mana ability's cost can't need a choice, X or {2/B}" if choosing_cost?(cost)
+            cost
+          end
+        end
+
+        def self.choosing_cost?(cost)
+          cost.respond_to?(:choices_needed) || (cost.respond_to?(:x?) && cost.x?) ||
+            (cost.respond_to?(:mana_cost) && cost.mana_cost.hybrid.any? { Mana.mono_hybrid?(it) })
+        end
+
+        def self.build_colors(params, color, errors, path)
+          raw = Mechanics.fetch_param(params, :colors)
+          return COLORS if raw.nil?
+          if color && color != "chosen" && raw.is_a?(Array) && raw.size >= 2 && (raw - COLORS).empty? && raw.uniq == raw
+            return raw.map(&:to_s).freeze
+          end
+
+          errors << "#{path}.colors: must list two or more colors (W U B R G), with color"
+          COLORS
+        end
+
+        def initialize(costs, produce, color: nil, colors: COLORS, amount: nil, spend_only: nil, only_if: nil)
+          super()
+          @costs = costs
+          @produce = produce
+          @color = color
+          @colors = colors
+          @amount = amount
+          @spend_only = spend_only
+          @only_if = only_if
+          list = costs.select(&:mana?).map(&:mana_cost)
+          @mana_cost = list.empty? ? nil : Mana.sum_costs(list)
+          freeze
+        end
+
+        def mana_ability? = true
+        def try_effects = []
+        def kind = :mana
+        def allowed_types = nil
+
+        # A mana cost ("{1}, {T}: Add …") is paid from the mana already in the pool (CR 605.3a, 601.2g-h).
+        # "Activate only if ..." (CR 602.5b) is checked for its controller.
+        def activatable?(engine, object)
+          return false if @only_if && !@only_if.true?(engine, EffectContext.new(object.controller, object.id, nil, nil))
+
+          costs.all? { |c| c.payable?(engine, object) } && (mana_cost.nil? || engine.pool_covers?(object.controller, mana_cost))
+        end
+
+        # The sum of its mana costs, or nil.
+        attr_reader :mana_cost
+
+        # Whether the mana is chosen as it's activated (so each activation option names it).
+        def choice? = !color.nil? && color != "chosen"
+
+        # CR 607.2d: "one mana of the chosen color", chosen as the source entered (choose_color); none, no mana.
+        def chosen_color(object) = object.memory["chosen_color"]&.to_sym
+
+        # How much mana (or how many times `produce`) one activation adds now.
+        def count(engine, object)
+          return 1 if amount.nil?
+
+          [amount.value(engine, EffectContext.new(object.controller, object.id, nil, [])), 0].max
+        end
+
+        # Every mana an activation could add now, each as a list of pool types (CR 605.3b). One entry
+        # without a choice; with `any_one` one per color; with `any` one per combination of colors.
+        def outcomes(engine, object)
+          n = count(engine, object)
+          return [Array(chosen_color(object)) * n] if color == "chosen"
+          return [(produce || []) * n] unless choice?
+          return [[]] if n.zero?
+
+          picks = colors.map(&:to_sym)
+          return picks.map { [it] * n } if color == "any_one"
+
+          picks.repeated_combination(n).map(&:freeze)
+        end
+
+        def to_s
+          what = if produce then "Add #{produce.map { "{#{it}}" }.join}#{" #{amount} times" if amount}"
+                 elsif color == "chosen" then "Add #{amount || 1} mana of the chosen color"
+                 else "Add #{amount || 1} mana of #{color == "any_one" ? "any one color" : "any combination of colors"}" \
+                   "#{" (#{colors.join("/")})" unless colors == COLORS}"
+                 end
+          "#{costs.join(", ")}: #{what}.#{" #{spend_only.to_s.capitalize}." if spend_only}" \
+            "#{" Activate only if #{@only_if}." if @only_if}"
+        end
+      end
+    end
+  end
+end