enjine 0.1.0

data/lib/enjine/mechanics/copy_except.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    # The exceptions of a copy effect (CR 707.9a-b), e.g. {"legendary": false} ("except it isn't
+    # legendary") or {"keywords": ["menace"]} ("except it has menace"). They become part of the copy's
+    # copiable values, so a copy of the copy has them too (CR 707.2). See Engine::Copies.
+    module CopyExcept
+      KEYS = %w[legendary keywords types subtypes supertypes name power toughness colors].freeze
+      LISTS = { "keywords" => :keyword, "types" => :type, "supertypes" => :supertype }.freeze
+      PARAM = "{\"legendary\": false, \"keywords\": [...], \"types\": [...], \"subtypes\": [...], " \
+              "\"supertypes\": [...], \"name\": ..., \"power\": n, \"toughness\": n, \"colors\": [...]}"
+
+      module_function
+
+      def build(raw, errors, path)
+        return {}.freeze if raw.nil?
+        return (errors << "#{path}: must be an object #{PARAM}") && {}.freeze unless raw.is_a?(Hash)
+
+        raw = raw.transform_keys(&:to_s)
+        Mechanics.check_keys(raw, KEYS, errors, path)
+        out = {}
+        errors << "#{path}.legendary: must be false (\"it isn't legendary\")" if raw.key?("legendary") && raw["legendary"] != false
+        out["legendary"] = false if raw.key?("legendary")
+        LISTS.each { |key, category| out[key] = names(raw[key], category, errors, "#{path}.#{key}") if raw.key?(key) }
+        out["subtypes"] = subtypes(raw["subtypes"], errors, "#{path}.subtypes") if raw.key?("subtypes")
+        values(raw, out, errors, path)
+        out["colors"] = colors(raw["colors"], errors, "#{path}.colors") if raw.key?("colors")
+        out.freeze
+      end
+
+      # "name", "power", "toughness": values the copy has instead of the copied ones.
+      def values(raw, out, errors, path)
+        out["name"] = raw["name"] if raw.key?("name")
+        errors << "#{path}.name: must be a non-empty string" if raw.key?("name") && !(raw["name"].is_a?(String) && !raw["name"].empty?)
+        %w[power toughness].each do |key|
+          next unless raw.key?(key)
+
+          errors << "#{path}.#{key}: must be an integer" unless raw[key].is_a?(Integer)
+          out[key] = raw[key]
+        end
+      end
+
+      def names(list, category, errors, path)
+        ok = list.is_a?(Array) && !list.empty? && list.all? { Enjine.registry.fetch(category, it.to_s.downcase.tr(" -", "__")) }
+        errors << "#{path}: must be a non-empty list of #{category}s (#{Enjine.registry.names(category).join(", ")})" unless ok
+        ok ? list.map { it.to_s.downcase.tr(" -", "__") }.freeze : [].freeze
+      end
+
+      def subtypes(list, errors, path)
+        ok = list.is_a?(Array) && !list.empty? && list.all? { CardDefinition::SUBTYPE_FORMAT.match?(it.to_s) }
+        errors << "#{path}: must be a non-empty list of lowercase subtypes" unless ok
+        ok ? list.map(&:to_s).freeze : [].freeze
+      end
+
+      def colors(list, errors, path)
+        ok = list.is_a?(Array) && list.all? { Mana::COLORS.include?(it.to_s.upcase.to_sym) }
+        errors << "#{path}: must be a list of W, U, B, R, G ([] for colorless)" unless ok
+        ok ? list.map { it.to_s.upcase }.freeze : [].freeze
+      end
+
+      def to_s(except)
+        return "" if except.empty?
+
+        bits = []
+        bits << "not legendary" if except["legendary"] == false
+        %w[name power toughness].each { bits << "#{it} #{except[it]}" if except.key?(it) }
+        %w[keywords types subtypes supertypes colors].each { bits << "#{it} #{except[it].join("/")}" if except[it] }
+        " (except #{bits.join(", ")})"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # Costs that need choices while casting or activating (CR 601.2h, 602.2b): which permanents to tap
+      # or sacrifice, which counters to remove. Each choice is a `choose_cost` decision recorded in the
+      # cast frame's "paid" list ({"cost": index, "object": id, ...}); the spell or ability keeps that list
+      # (GameObject#paid) so effects can ask about "the sacrificed creature". Tapping happens at once
+      # (cancelling untaps); sacrificing and removing counters happen as the spell or ability becomes cast.
+      class Choosing < Primitive
+        attr_reader :count, :filter
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, keys, errors, path)
+          raw = Mechanics.fetch_param(params, :filter) || default_filter
+          filter = Mechanics.build_entry(:filter, raw, errors, "#{path}.filter")
+          count = Mechanics.integer_param(params, :count, errors, path, default: 1, min: 1)
+          new(filter, count, Mechanics.flag_param(params, :other, errors, path), params, errors, path)
+        end
+
+        def self.keys = %w[filter count other]
+        def self.default_filter = "permanent"
+
+        def initialize(filter, count, other, _params, _errors, _path)
+          super()
+          @filter = filter
+          @count = count
+          @other = other
+          freeze
+        end
+
+        def mana? = false
+        def choices_needed = count
+
+        # Permanents the controller of `object` controls that match (not `object` itself for "another").
+        def matching(engine, object)
+          engine.state.battlefield.select do |id|
+            perm = engine.object(id)
+            perm.controller == object.controller && !(@other && id == object.id) &&
+              @filter.match_for?(engine, id, object.controller, object.id)
+          end
+        end
+
+        # The options still open, given the choices already made for this cost (`chosen`: paid entries).
+        def choice_options(engine, object, chosen)
+          taken = chosen.map { it["object"] }
+          candidates(engine, object).reject { taken.include?(it) }.map { { object: it } }
+        end
+
+        def candidates(engine, object) = matching(engine, object)
+        def payable?(engine, object) = candidates(engine, object).size >= count
+
+        # Called when a choice is made: the paid entry to record (and any immediate payment).
+        def choose!(_engine, option) = { "object" => option[:object] }
+
+        # Called as the spell or ability becomes cast, with this cost's paid entries.
+        def pay_chosen!(_engine, _object, _entries) = nil
+
+        # Costs without choices of their own are paid by ActivatedAbility's finishing step.
+        def pay!(_engine, _object) = nil
+
+        def what = @filter.is_a?(Class) ? @filter.primitive_name.tr("_", " ") : @filter.to_s
+
+        def amount_words
+          if count == 1
+            @other ? "another" : "a"
+          else
+            count.to_s
+          end
+        end
+      end
+
+      # `count` cards from one of your zones (`zone`) matching the card spec `card`, never the card the spell
+      # or ability belongs to: "discard a card", "exile two cards from your graveyard" (CR 601.2h, 602.2b).
+      class CardsCost < Choosing
+        def self.keys = %w[count card]
+        def self.zone = raise(NotImplementedError)
+
+        # `count` "X": as many as the X announced for the spell or ability (CR 601.2b, 107.3a).
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, keys, errors, path)
+          count = if Mechanics.fetch_param(params, :count) == "X" then "X"
+                  else Mechanics.integer_param(params, :count, errors, path, default: 1, min: 1)
+                  end
+          raw = Mechanics.fetch_param(params, :card)
+          spec = raw && CardSpec.build(raw, errors, "#{path}.card")
+          new(spec, count, false, params, errors, path)
+        end
+
+        def candidates(engine, object)
+          engine.player(object.controller).public_send(self.class.zone).select do |id|
+            id != object.id && (filter.nil? || filter.match?(engine, engine.object(id)))
+          end
+        end
+
+        # "Exile X cards": the engine asks for as many as X (Engine::CastChoices#cost_chosen?); X can be at
+        # most the number of matching cards (Engine::Costs#x_limit).
+        def x? = count == "X"
+        def choices_needed = x? ? 0 : super
+        def payable?(engine, object) = x? || super
+        def x_limit(engine, object) = candidates(engine, object).size
+
+        # As it becomes cast, the chosen cards still where they were chosen are paid (exiled by default).
+        def pay_chosen!(engine, _object, entries)
+          entries.map { it["object"] }.select { engine.state.objects[it]&.zone == self.class.zone }.each { pay_card!(engine, it) }
+        end
+
+        def pay_card!(engine, id) = engine.move!(id, :exile, reason: "cost")
+
+        def cards_text = "#{count == 1 ? "a" : count} #{filter || "card"}#{"s" unless count == 1}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/behold.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    # Behold (CR 701.4a): "behold a [quality]" means reveal a [quality] card from your hand or choose a
+    # [quality] permanent you control. Whether a [quality] was beheld looks at the object as it was beheld
+    # (CR 701.4b).
+    module Beholding
+      # The cards in `index`'s hand and the permanents they control matching the card spec.
+      def self.candidates(engine, index, spec)
+        perms = engine.state.battlefield.select { engine.object(it).controller == index }
+        (perms + engine.player(index).hand).select { spec.match?(engine, engine.object(it)) }
+      end
+
+      # Reveals a card from the hand (CR 701.4a); the entry remembers what was beheld (CR 701.4b).
+      def self.behold!(engine, index, id)
+        obj = engine.object(id)
+        engine.reveal!(index, [id]) if obj.zone == :hand
+        facts = engine.chars(obj)
+        { "object" => id, "zone" => obj.zone.to_s, "types" => facts.types.map(&:to_s),
+          "subtypes" => facts.subtypes.map(&:to_s) }
+      end
+    end
+
+    module Costs
+      # "Behold a Goblin" / "Behold three Elementals" / "Behold a Kithkin and exile it" as a cost (CR 701.4a,
+      # 601.2h). Each choice is a card in your hand or a permanent you control matching `card`; with `exile`
+      # they are exiled as the spell or ability becomes cast, linked to it ("the exiled card", CR 607.2a). A
+      # spell's linked cards stay linked to the permanent it becomes.
+      class Behold < Choosing
+        primitive :cost, :behold,
+                  description: "Behold `count` (default 1) objects matching the card spec `card`: each a card " \
+                               "revealed from your hand or a permanent you control, chosen while casting or " \
+                               "activating. `exile: true` also exiles them as it becomes cast; they are then " \
+                               "\"exiled with\" it (selector `exiled_with`).",
+                  rules: %w[701.4a 701.4b 601.2h 602.2b 118.3 607.2a],
+                  params: { "card" => "card spec (required), e.g. {\"subtypes\": [\"goblin\"]}",
+                            "count" => "integer (default 1)", "exile" => "true: exile what was beheld" },
+                  example: { "behold" => { "card" => { "subtypes" => ["goblin"] }, "exile" => true } }
+
+        def self.keys = %w[card count exile]
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, keys, errors, path)
+          count = Mechanics.integer_param(params, :count, errors, path, default: 1, min: 1)
+          raw = Mechanics.fetch_param(params, :card)
+          errors << "#{path}.card: required" if raw.nil?
+          new(CardSpec.build(raw, errors, "#{path}.card"), count, false, params, errors, path)
+        end
+
+        def initialize(filter, count, other, params, errors, path)
+          @exile = Mechanics.flag_param(params, :exile, errors, path)
+          super
+        end
+
+        # Not the card being cast (it is on the stack once casting begins).
+        def candidates(engine, object) = Beholding.candidates(engine, object.controller, filter) - [object.id]
+        def choose!(engine, option) = Beholding.behold!(engine, engine.object(option[:object]).controller, option[:object])
+
+        def pay_chosen!(engine, object, entries)
+          return unless @exile
+
+          entries.each do |entry|
+            card = engine.state.objects[entry["object"]]
+            next unless card&.zone.to_s == entry["zone"]
+
+            fresh = engine.move!(card.id, :exile, reason: "cost")
+            engine.link_exiled!(object.id, fresh.id) if fresh
+          end
+        end
+
+        def to_s = "Behold #{count == 1 ? "a" : count} #{filter.to_s.delete_suffix(" card")}#{" and exile it" if @exile}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/discard.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # "Discard this card" as a cost (CR 701.9a, 602.2b). It moves the card out of its owner's
+      # hand, so an ability with this cost functions only from the hand (CR 113.6m).
+      class DiscardSelf < Primitive
+        primitive :cost, :discard_self,
+                  description: "Discard the card the ability belongs to (it goes from your hand to your graveyard). " \
+                               "An ability with this cost is activated from your hand.",
+                  rules: %w[701.9a 602.2b 113.6m 118.3],
+                  example: "discard_self"
+
+        INSTANCE = new.freeze
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, [], errors, path)
+          INSTANCE
+        end
+
+        def mana? = false
+        def zone = :hand
+        def payable?(engine, object) = engine.player(object.owner).hand.include?(object.id)
+        def pay!(engine, object) = engine.move!(object.id, :graveyard, reason: "discard")
+        def to_s = "Discard this card"
+      end
+
+      # "Discard a card" / "Discard two cards" / "Discard a creature card" / "Discard a card at random" as a
+      # cost (CR 701.9a-b, 601.2h): cards from your hand other than this one, chosen while casting or activating
+      # and discarded as the spell or ability becomes cast. Random discards are paid last (CR 601.2h).
+      class Discard < CardsCost
+        primitive :cost, :discard,
+                  description: "Discard `count` cards (default 1) from your hand, never this card, matching the card " \
+                               "spec `card` if given: chosen while casting or activating and discarded as the spell " \
+                               "or ability becomes cast. `random: true` discards them at random instead.",
+                  rules: %w[701.9a 701.9b 601.2h 602.2b 118.3],
+                  params: { "count" => "integer (default 1), or \"X\": the X announced",
+                            "card" => "card spec, e.g. {\"types\": [\"land\"]}",
+                            "random" => "true: at random (CR 701.9b)" },
+                  example: { "discard" => { "count" => 1 } }
+
+        def self.keys = %w[count card random]
+        def self.zone = :hand
+
+        def initialize(filter, count, other, params, errors, path)
+          @random = Mechanics.flag_param(params, :random, errors, path)
+          super
+        end
+
+        def choices_needed = @random ? 0 : count
+
+        def pay_chosen!(engine, object, entries)
+          return super unless @random
+
+          left = candidates(engine, object)
+          [count, left.size].min.times { pay_card!(engine, left.delete_at(engine.state.rng.rand(left.size))) }
+        end
+
+        def pay_card!(engine, id) = engine.move!(id, :graveyard, reason: "discard")
+        def to_s = "Discard #{cards_text}#{" at random" if @random}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/exert.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # "Exert [this permanent]" as a cost (CR 701.43a): it won't untap during your next untap step. It can be
+      # exerted tapped or untapped, and again before that untap step (one untap step is skipped, CR 701.43b);
+      # only a permanent can be (CR 701.43c).
+      class Exert < Primitive
+        primitive :cost, :exert,
+                  description: "Exert this permanent: it doesn't untap during your next untap step.",
+                  rules: %w[701.43a 701.43b 701.43c],
+                  example: "exert"
+
+        INSTANCE = new.freeze
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, [], errors, path)
+          INSTANCE
+        end
+
+        def payable?(_engine, object) = object.zone == :battlefield
+        def pay!(engine, object) = engine.exert!(object)
+        def mana? = false
+        def to_s = "Exert this"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/exile_cards.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # "Exile a card from your hand" / "Exile two cards from your hand" as a cost (CR 406.1, 601.2h,
+      # 602.2b). The cards are chosen while casting or activating and exiled as it becomes cast; never the
+      # card the ability belongs to.
+      class ExileFromHand < CardsCost
+        primitive :cost, :exile_from_hand,
+                  description: "Exile `count` cards from your hand (default 1), chosen while casting or activating, " \
+                               "exiled as the spell or ability becomes cast. `card` (a card spec) restricts which.",
+                  rules: %w[406.1 601.2h 602.2b 118.3],
+                  params: { "count" => "integer (default 1), or \"X\": the X announced",
+                            "card" => "card spec, e.g. {\"types\": [\"creature\"]}" },
+                  example: { "exile_from_hand" => { "count" => 1 } }
+
+        def self.zone = :hand
+        def to_s = "Exile #{cards_text} from your hand"
+      end
+
+      # "Exile a creature card from your graveyard" / "Exile two cards from your graveyard" as a cost (CR 406.1,
+      # 601.2h): cards other than the one the ability belongs to, chosen while casting or activating.
+      class ExileFromGraveyard < CardsCost
+        primitive :cost, :exile_from_graveyard,
+                  description: "Exile `count` cards from your graveyard (default 1), never this card, chosen while " \
+                               "casting or activating and exiled as the spell or ability becomes cast. `card` (a card " \
+                               "spec) restricts which.",
+                  rules: %w[406.1 601.2h 602.2b 118.3],
+                  params: { "count" => "integer (default 1), or \"X\": the X announced",
+                            "card" => "card spec, e.g. {\"types\": [\"creature\"]}" },
+                  example: { "exile_from_graveyard" => { "count" => 2 } }
+
+        def self.zone = :graveyard
+        def to_s = "Exile #{cards_text} from your graveyard"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/from_graveyard.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # "Exile this card from your graveyard" / "Put this card from your graveyard on the bottom of your
+      # library" as a cost: the ability functions only from the graveyard (CR 113.6m).
+      class FromGraveyard < Primitive
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, [], errors, path)
+          new
+        end
+
+        def mana? = false
+        def zone = :graveyard
+        def uses_source? = true
+        def payable?(engine, object) = engine.player(object.owner).graveyard.include?(object.id)
+      end
+
+      # Exile this card from your graveyard (CR 406, 113.6m).
+      class ExileSelfFromGraveyard < FromGraveyard
+        primitive :cost, :exile_self_from_graveyard,
+                  description: "Exile this card from your graveyard. An ability with this cost is activated from " \
+                               "your graveyard.",
+                  rules: %w[406.1 113.6m 602.2b 118.3],
+                  example: "exile_self_from_graveyard"
+
+        def pay!(engine, object) = engine.move!(object.id, :exile, reason: "cost")
+        def to_s = "Exile this card from your graveyard"
+      end
+
+      # Put this card from your graveyard on the bottom of your library (CR 401, 113.6m).
+      class BottomSelfFromGraveyard < FromGraveyard
+        primitive :cost, :bottom_self_from_graveyard,
+                  description: "Put this card from your graveyard on the bottom of your library. An ability with " \
+                               "this cost is activated from your graveyard.",
+                  rules: %w[401.1 113.6m 602.2b 118.3],
+                  example: "bottom_self_from_graveyard"
+
+        def pay!(engine, object) = engine.move!(object.id, :library, position: :bottom, reason: "cost")
+        def to_s = "Put this card from your graveyard on the bottom of your library"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/get_counters.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # "Get five poison counters" as a cost (CR 118.1, 122.1): the payer gets that many counters of a kind
+      # (a player with ten or more poison counters loses the game, CR 704.5c). It can always be paid.
+      class GetCounters < Primitive
+        primitive :cost, :get_counters,
+                  description: "You get `amount` counters of the kind `counter` (e.g. poison). It can always be paid.",
+                  rules: %w[118.1 122.1 704.5c],
+                  params: { "counter" => "player counter kind, e.g. \"poison\"", "amount" => "integer >= 1" },
+                  example: { "get_counters" => { "counter" => "poison", "amount" => 5 } }
+
+        attr_reader :counter, :amount
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[counter amount], errors, path)
+          counter = Mechanics.fetch_param(params, :counter)
+          errors << "#{path}.counter: must be a counter kind, e.g. \"poison\"" unless counter.is_a?(String) && !counter.empty?
+          new(counter.to_s, Mechanics.integer_param(params, :amount, errors, path, min: 1))
+        end
+
+        def initialize(counter, amount)
+          super()
+          @counter = counter
+          @amount = amount
+          freeze
+        end
+
+        def mana? = false
+        def spell_cost? = true
+        def payable?(_engine, _object) = true
+        def pay!(engine, object) = engine.add_player_counters!(object.controller, counter, amount)
+        def to_s = "Get #{amount} #{counter} counter#{"s" unless amount == 1}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/mana.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # A mana cost for an activated ability, e.g. {"mana": "{1}{R}"} (CR 602.2b, 601.2f).
+      class ManaPayment < Primitive
+        primitive :cost, :mana,
+                  description: "Pay mana as part of an activation. Paid during the activation by spending mana from " \
+                               "your pool, tapping sources one at a time.",
+                  rules: %w[601.2g 601.2h 602.2b],
+                  params: { "(value)" => "mana cost string, e.g. \"{1}{R}\"" },
+                  example: { "mana" => "{1}{R}" }
+
+        attr_reader :mana_cost
+
+        def self.scalar_params? = true
+
+        # Accepts {"mana": "{1}{R}"}; the params object here is the cost string itself.
+        def self.build(params, errors, path, **)
+          new(Mana.parse_cost(params, errors, path) || Mana::Cost.new(generic: 0, colored: {}))
+        end
+
+        def initialize(mana_cost)
+          super()
+          @mana_cost = mana_cost
+          freeze
+        end
+
+        def mana? = true
+        def payable?(_engine, _object) = true
+        def pay!(_engine, _object) = nil
+        def to_s = mana_cost.to_s
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/one_of.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # A choice between costs: "behold a Goblin or pay {2}", "sacrifice an artifact or discard a nonland card"
+      # (CR 118.3, 601.2b). Which one will be paid is announced while casting or activating, before X and the
+      # total cost (CR 601.2b, 601.2f, 602.2b): the `choose_cost_option` decision. From then on the chosen cost
+      # stands in its place. While resolving (`pay`, ward) the payer chooses as they pay (CR 118.12).
+      class OneOf < Primitive
+        primitive :cost, :one_of,
+                  description: "Pay one of the listed costs (two or more), chosen as the spell or ability is cast or " \
+                               "activated (the `choose_cost_option` decision) or, for `pay` and ward, as it is paid. " \
+                               "A cost that can't be paid can't be chosen.",
+                  rules: %w[118.3 601.2b 601.2f 602.2b 118.12],
+                  params: { "(list)" => "two or more costs" },
+                  example: { "one_of" => [{ "behold" => { "card" => { "subtypes" => ["goblin"] } } }, { "mana" => "{2}" }] }
+
+        attr_reader :options
+
+        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 costs"
+            return new([])
+          end
+          options = params.each_with_index.filter_map { |c, i| Mechanics.build_entry(:cost, c, errors, "#{path}[#{i}]") }
+          errors << "#{path}: a one_of can't contain another one_of" if options.any?(OneOf)
+          new(options)
+        end
+
+        def initialize(options)
+          super()
+          @options = options.freeze
+          freeze
+        end
+
+        def mana? = false
+
+        # Some option could be paid (a mana option is checked against the total cost by the engine).
+        def payable?(engine, object) = options.any? { it.mana? || it.payable?(engine, object) }
+        # Each option as text: "Behold a Goblin", "Pay {2}".
+        def option_texts = options.map { it.mana? ? "Pay #{it}" : it.to_s }
+        def to_s = option_texts.each_with_index.map { |text, i| i.zero? ? text : text.sub(/\A\w/, &:downcase) }.join(" or ")
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/costs/pay_life.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # "Pay 2 life" / "Pay X life" as a cost (CR 119.4, 118.3b): {"pay_life": 2} or {"pay_life": "X"}. A
+      # player can pay life only if their life total is at least that much; 0 life can always be paid
+      # (CR 119.4b). X is announced with the spell or ability (CR 601.2b, 107.3a), at most the life total.
+      class PayLife < Primitive
+        primitive :cost, :pay_life,
+                  description: "Pay that much life (you lose it). Only possible while your life total is at least " \
+                               "that much. `\"X\"` pays the X announced for the spell or ability (at most your life " \
+                               "total); it may be a spell's additional cost.",
+                  rules: %w[119.4 119.4b 118.3b 601.2b 107.3a],
+                  params: { "(value)" => "integer >= 1, or \"X\"" },
+                  example: { "pay_life" => 2 }
+
+        attr_reader :amount
+
+        def self.scalar_params? = true
+
+        def self.build(params, errors, path, **)
+          errors << "#{path}: must be an integer >= 1 or \"X\"" unless params == "X" || (params.is_a?(Integer) && params >= 1)
+          new(params)
+        end
+
+        def initialize(amount)
+          super()
+          @amount = amount
+          freeze
+        end
+
+        def mana? = false
+        def spell_cost? = true
+        def x? = @amount == "X"
+        def x_limit(engine, object) = [engine.player(object.controller).life, 0].max
+
+        # X is bounded by the life total as it's announced (Engine::Costs#x_limit).
+        def payable?(engine, object) = x? || engine.player(object.controller).life >= @amount.to_i
+
+        def pay!(engine, object)
+          life = x? ? engine.casting&.fetch("x", 0).to_i : @amount.to_i
+          engine.change_life!(object.controller, -life) if life.positive?
+        end
+
+        def to_s = "Pay #{@amount} life"
+      end
+    end
+  end
+end