enjine 0.1.0

data/lib/enjine/engine/casting/casting.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Casting spells (CR 601) and activating abilities (CR 602), one atomic decision
+    # at a time: announce -> choose targets -> pay mana (tapping sources manually)
+    # -> cast. Until every cost is paid the whole process can be cancelled and is
+    # rewound (CR 734, "Handling Illegal Actions"). The in-progress context lives in
+    # casting so a game can be exported mid-cast.
+    module Casting
+      # ---- what can be started ---------------------------------------------------
+
+      def castable?(index, id)
+        obj = object(id)
+        defn = definition(obj)
+        return false unless defn.castable?
+        return false unless defn.instant_speed? || sorcery_timing?(index)
+        return false if cast_forbidden?(index, obj) # CR 101.2 (Engine::Rules)
+        return false unless additional_costs_payable?(obj) # CR 601.2f: e.g. "sacrifice a creature"
+
+        if ability_targetable?(defn.spell_ability, index, id) && # CR 601.2b: some way of paying its costs (Engine::CostOptions)
+           cost_variant_affordable?(index, spell_cost_list(obj, false), obj, defn.mana_cost, nil, { "spell" => id }) do
+             total_cost(index, it, spell: obj)
+           end
+          return true
+        end
+
+        kicked_castable?(index, obj) # CR 702.33g: only the kicked spell has legal targets
+      end
+
+      def activatable?(index, id, ability_ref)
+        obj = object(id)
+        ability = chars(obj).ability(ability_ref)
+        return false unless ability && %i[activated loyalty].include?(ability.kind)
+        return false unless obj.zone == ability.zone # CR 113.6: e.g. cycling only from the hand (702.29a)
+        return false if ability.sorcery_speed? && !sorcery_timing?(index)
+        return false if activation_forbidden?(index, obj) # CR 602.5, 101.2 (Engine::Rules)
+        return false unless activation_allowed?(index, obj, ability_ref, ability) # CR 602.5b
+
+        if (ability.kind == :loyalty) && (obj.loyalty_turn == state.turn || (loyalty(obj) + ability.loyalty_cost).negative?)
+          # CR 606.3: once per turn. CR 118.3: a cost can't remove more counters than there are.
+          return false
+        end
+
+        # CR 118.3, 601.2b: some way of paying its costs (Engine::CostOptions); waterbend: CR 701.67a
+        ability_targetable?(ability, index, nil, id, ref: ability_ref) &&
+          cost_variant_affordable?(index, ability.costs, obj, nil, needs_tap?(ability) ? id : nil, { "ability" => id }) do
+            total_cost(index, it, ability: ability, source: id)
+          end
+      end
+
+      # Whether the ability can get legal targets: for modal abilities, enough modes must (CR 700.2),
+      # not counting modes already chosen for the source of a "choose one that hasn't been chosen".
+      def ability_targetable?(ability, index, exclude, source = nil, ref: nil)
+        return true if ability.nil?
+        return targets_available?(ability.targets, index, exclude, source) unless ability.modal?
+
+        (available_modes(ability, index, exclude, source) - used_modes(ability, source, ref)).size >= ability.choose
+      end
+
+      def available_modes(ability, index, exclude, source = nil)
+        ability.modes.each_index.select { targets_available?(ability.modes[it].targets, index, exclude, source) }
+      end
+
+      # "Up to one target" needs no candidate (CR 601.2c).
+      def targets_available?(specs, index, exclude, source = nil)
+        specs.all? do |spec|
+          need = target_minimum(spec, index, source) # Engine::TargetCounts
+          need.zero? || spec.candidates_for(self, index, source).count do
+            it != exclude && targetable?(it, index, source, targeter: source || exclude) # a spell's card is `exclude`
+          end >= need
+        end
+      end
+
+      def optional_target?(spec) = spec.respond_to?(:optional?) && spec.optional?
+
+      # CR 702.11b: hexproof permanents can't be targeted by their controller's opponents. `source`: the
+      # permanent whose ability targets (nil for a spell); `targeter`: the spell, or the ability's source (protection,
+      # CR 702.16b); see Engine::Rules#targeting_forbidden?.
+      def targetable?(ref, index, source = nil, targeter: source)
+        return false if targeting_forbidden?(ref, index, source, targeter: targeter) # CR 702.11c, 115.4
+
+        obj = state.objects[ref]
+        return true unless obj && obj.zone == :battlefield && obj.controller != index
+
+        !chars(obj).keyword?(:hexproof)
+      end
+
+      # The ability an ability object on the stack represents. It keeps existing even if its
+      # source has left the battlefield (CR 113.7a), so it's looked up on the source's card.
+      def stack_ability(obj) = definition(obj).ability(obj.ability)
+
+      def needs_tap?(ability) = ability.costs.any?(Mechanics::Costs::Tap)
+
+      # The spell ability of a spell (printed, CR 113.3a).
+      def spell_ability_of(obj) = definition(obj).spell_ability
+
+      # ---- starting ----------------------------------------------------------------
+
+      # CR 601.2a: the card moves from where it is to the stack. `via` names how a card outside the
+      # hand is cast (see Engine::Permissions); "free" casts it without paying its mana cost during
+      # the resolution of a spell or ability (CR 608.2g, 118.9), after which nobody gets priority.
+      # `face`: cast another face of the card (a modal card's back, an Adventure, an Omen; Engine::Faces).
+      # `riders`: how an effect casting it while resolving changes the cast ("exile_instead", "any_mana_type").
+      def begin_cast!(index, card_id, via: nil, face: nil, riders: {})
+        return begin_outside_cast!(index, card_id, via) if outside_key?(card_id) # CR 400.11b
+
+        card = object(card_id)
+        method = via && play_method(index, card_id, via).merge(riders)
+        origin = { "id" => card_id, "zone" => card.zone.to_s,
+                   "index" => state.zone_list(card.zone, card.owner).index(card_id) }
+        origin["memory"] = card.memory.slice("face_down", "may_look") if face_down?(card) # turned face up (CR 406.3a)
+        origin["memory"] = card.memory.slice("prepared_for") if card.memory["prepared_for"] # a prepare spell (CR 723.3c)
+        obj = move!(card_id, :stack, controller: index, reason: "cast")
+        turn_spell_face!(obj, face) # CR 712.8b, 716.3b, 721.3b
+        extra = method ? { "method" => method } : {}
+        extra["no_priority"] = true if %w[free resolving].include?(via) # cast while resolving (CR 608.2g)
+        start_casting!(index, obj.id, "spell", origin: origin, extra: extra)
+      end
+
+      # CR 602.2a: the ability is created on the stack.
+      def begin_activation!(index, source_id, ability_ref)
+        source = object(source_id)
+        # CR 602.2a: activating from a hidden zone reveals the card.
+        emit Events::CardRevealed.new(player: name(index), object: source_id, card: source.card) if source.zone == :hand
+        card, ref, granter = AbilityLayers.granted_parts(ability_ref) # a granted ability lives in the granting card's data
+        obj = create_object(card || source.card, index, :stack)
+        obj.kind = "ability"
+        obj.source = source_id
+        obj.ability = ref || ability_ref
+        obj.memory["granter"] = granter if granter # CR 607.1a: "Return Trusty Boomerang" (Selector "granter")
+        state.stack.unshift(obj.id)
+        start_casting!(index, obj.id, "ability", source: source_id, ability: ability_ref)
+      end
+
+      # `x` stays nil until announced (CR 601.2b); `remaining` stays nil until the total cost is
+      # determined and locked in after targets are chosen (CR 601.2f).
+      def start_casting!(index, object_id, kind, origin: nil, source: nil, ability: nil, extra: {})
+        state.frames << { "type" => "cast", "player" => index, "object" => object_id, "kind" => kind,
+                          "origin" => origin, "source" => source, "ability" => ability, "targets" => [], "modes" => [],
+                          "x" => nil, "remaining" => nil,
+                          "pool" => player(index).mana_pool.transform_keys(&:to_s), "tapped" => [],
+                          "restricted" => Snapshot.deep_copy(player(index).restricted_mana),
+                          "pool_sources" => Snapshot.deep_copy(player(index).pool_sources),
+                          "triggers_before" => state.pending_triggers.map { it["id"] } }.merge(extra)
+        ask!(nil) # advance! now steps the cast frame
+      end
+
+      # The cast/activation in progress (the top frame while a cast decision is pending).
+      def casting
+        frame = state.frames.last
+        frame if frame && frame["type"] == "cast"
+      end
+
+      def casting_ability
+        ctx = casting
+        obj = object(ctx["object"])
+        ctx["kind"] == "spell" ? definition(obj).spell_ability : stack_ability(obj)
+      end
+
+      # ---- the in-progress steps --------------------------------------------------
+
+      # Steps the cast frame: modes and X (601.2b), targets (601.2c), total cost (601.2f), payment.
+      def continue_casting!
+        ctx = casting
+        ability = casting_ability
+        return :wait if ask_kicker!(ctx)
+
+        if ability&.modal? && modes_pending?(ctx, ability)
+          min, max = mode_range(ctx, ability)
+          ask!({ "kind" => "choose_mode", "player" => ctx["player"], "choose" => max, "chosen" => ctx["modes"].size }
+                 .merge(min == max ? {} : { "min" => min }))
+          return :wait
+        end
+        return :wait if ask_cost_option!(ctx) # CR 601.2b: which of two costs (Engine::CostOptions)
+        return :wait if ask_x!(ctx)
+
+        specs = casting_targets
+        return :wait if ask_targets!(ctx, specs) # Engine::TargetCounts
+        return :wait if ask_distribution!(ctx, ability)
+
+        return ask_harmonize!(ctx) if harmonize_pending?(ctx) # CR 702.180b (Engine::AltCasting)
+
+        lock_total_cost!(ctx) unless ctx["remaining"]
+        if beam_choice_pending?(ctx) then ask_beam_choice!(ctx) # CR 702.196a (Engine::Permissions)
+        elsif (cost = next_cost_choice(ctx)) then ask_cost_choice!(ctx, casting_costs(ctx)[cost])
+        elsif remaining_left?(ctx["remaining"])
+          ask!("kind" => "pay_cost", "player" => ctx["player"], "remaining" => remaining_text)
+          :wait
+        else
+          finish_casting!
+          :done
+        end
+      end
+
+      def casting_targets = casting_ability&.targets_for(casting["modes"], kicked: casting["kicked"]) || []
+
+      # CR 601.2c: targets, in order; a spell or ability can't target itself (CR 115.5), and the same
+      # object can't be chosen twice for one instance of the word "target" (`distinct_from`).
+      def target_candidates
+        ctx = casting
+        spec = casting_targets[target_slot(ctx)] # Engine::TargetCounts: a counted slot's list may be open
+        taken = spec.respond_to?(:distinct_from) ? spec.distinct_from.flat_map { Array(ctx["targets"][it]) } : []
+        taken += open_target_group(ctx)
+        candidates = spec.candidates_for(self, ctx["player"], ctx["source"]).reject do
+          it == ctx["object"] || taken.include?(it) || !targetable?(it, ctx["player"], ctx["source"],
+                                                                    targeter: ctx["source"] || ctx["object"])
+        end
+        sharing_type(candidates, spec, ctx)
+      end
+
+      # "Target permanents that share a card type" (`shares_type_with`, CR 205.2a): only candidates sharing one
+      # with the earlier target.
+      def sharing_type(candidates, spec, ctx)
+        index = spec.respond_to?(:shares_type_with) && spec.shares_type_with
+        other = index && state.objects[Array(ctx["targets"][index]).first] or return candidates
+
+        candidates.select { state.objects.key?(it) && chars(it).types.intersect?(chars(other).types) }
+      end
+
+      # The target options; an "up to one" target may be left unchosen (`done`).
+      def target_options
+        options = target_candidates.map { { type: "target", target: it } }
+        optional_target?(casting_targets[casting["targets"].size]) && !casting["counting"] ? options + [{ type: "done" }] : options
+      end
+
+      # `ref` nil: no target chosen for an optional ("up to one") target. Abilities that trigger when
+      # something becomes a target (ward, CR 702.21a) learn which spell or ability targeted it.
+      def choose_target!(ref)
+        ctx = casting
+        add_chosen_target!(ctx, ref)
+        if ref
+          queued = state.pending_triggers.size
+          emit Events::TargetChosen.new(player: name(ctx["player"]), object: ctx["object"], target: ref)
+          state.pending_triggers.drop(queued).each { it["memory"] = it["memory"].merge("targeted_by" => ctx["object"]) }
+        end
+        ask!(nil)
+      end
+
+      # CR 601.2h-i / 602.2b: remaining costs are paid, the spell becomes cast.
+      def finish_casting!
+        ctx = casting
+        index = ctx["player"]
+        obj = object(ctx["object"])
+        obj.targets = ctx["targets"].dup
+        obj.modes = ctx["modes"].dup unless ctx["modes"].empty?
+        obj.mana_spent = ctx["spent"].dup if ctx["spent"]
+        obj.memory["mana_from"] = Snapshot.deep_copy(ctx["spent_from"]) if ctx["spent_from"] # the sources (ManaSources)
+        record_announcements!(obj, ctx) # kicked (CR 702.33d), division (CR 601.2d), modes chosen before
+        record_cast_choices!(obj, ctx) # cost choices; facing a dilemma (CR 700.17)
+        waterbent!(ctx) # CR 701.67c (Engine::Waterbending)
+        if ctx["kind"] == "trigger"
+          emit Events::TriggerPutOnStack.new(player: name(index), object: obj.id, source: ctx["source"], card: obj.card,
+                                             ability: ctx["ability"], targets: obj.targets.flatten)
+          return # placing continues in the put_triggers frame; no priority yet
+        elsif ctx["kind"] == "ability"
+          pay_ability_costs!(ctx, obj)
+          record_activation!(ctx) # CR 602.5b
+          emit Events::AbilityActivated.new(player: name(index), object: obj.id, card: obj.card, source: ctx["source"],
+                                            ability: ctx["ability"], targets: obj.targets.flatten)
+        else
+          finish_spell_cast!(ctx, obj)
+        end
+        return if ctx["no_priority"] # CR 608.2g: no priority; the resolving spell or ability continues
+
+        action_taken!(index) # CR 117.3c (the frame is popped by advance!)
+      end
+
+      # A spell becomes cast (CR 601.2i) once its other costs are paid.
+      def finish_spell_cast!(ctx, obj)
+        casting_costs(ctx).each { it.pay!(self, obj) unless it.respond_to?(:choices_needed) } # pay life (CR 119.4)
+        pay_chosen_costs!(ctx) # e.g. the creature sacrificed for an additional cost (CR 601.2h)
+        finish_cast_method!(obj, ctx) # Engine::Permissions
+        cast_prepared_copy!(ctx.dig("origin", "id")) # CR 723.3c (Engine::Faces)
+        emit Events::SpellCast.new(player: name(ctx["player"]), object: obj.id, card: obj.card,
+                                   targets: obj.targets.flatten, during_resolution: ctx["no_priority"] == true)
+      end
+
+      # The non-mana costs (CR 602.2b): its own ({T}, sacrifice it, exile it from the graveyard), then
+      # the chosen ones (sacrifice another creature, remove counters). A source sacrificed as a cost is
+      # remembered as it last existed (its counters, CR 608.2h).
+      def pay_ability_costs!(ctx, obj)
+        source = object(ctx["source"])
+        ability = chars(source).ability(ctx["ability"])
+        obj.memory["source_counters"] = source.counters.dup if ability.costs.any?(Mechanics::Costs::SacrificeSelf)
+        frame_costs(ctx).reject(&:mana?).each { it.pay!(self, source) } # the chosen option of a one_of (CR 601.2b)
+        pay_chosen_costs!(ctx)
+        return unless ability.kind == :loyalty
+
+        source.loyalty_turn = state.turn
+        cost = ability.loyalty_cost
+        cost.negative? ? remove_counters!(source, "loyalty", -cost) : add_counters!(source, "loyalty", cost)
+      end
+
+      # Rewinds an unfinished cast or activation (CR 734.1). Offered only while nothing irreversible
+      # has been paid (see Engine::Payment#cancellable?): tapping is undone, mana abilities' mana
+      # leaves the pool, and abilities that triggered meanwhile are dropped.
+      def cancel_casting!
+        ctx = casting
+        index = ctx["player"]
+        rewind_payment!(ctx)
+        obj = object(ctx["object"])
+        state.stack.delete(obj.id)
+        state.objects.delete(obj.id)
+        restore_to_origin!(obj, ctx["origin"]) if ctx["kind"] == "spell"
+        emit Events::CastCancelled.new(player: name(index), object: obj.id, card: obj.card)
+        state.frames.pop
+        return ask!(nil) if ctx["no_priority"] # cast during resolution: the resolution goes on (CR 608.2g)
+
+        give_priority!(index)
+      end
+
+      # (Costs that need a choice, e.g. tapping another creature: see Engine::CastChoices.)
+
+      # As a spell or ability becomes cast, activated or put on the stack: it keeps the cost choices
+      # (CR 702.184a uses the tapped creature's power), and chosen modes mean its controller faced a
+      # dilemma (CR 700.17). Recording it here, not as modes are chosen, keeps a cancelled cast from counting.
+      def record_cast_choices!(obj, ctx)
+        obj.paid = ctx["paid"].map(&:dup) if ctx["paid"]
+        emit Events::DilemmaFaced.new(player: name(ctx["player"]), object: obj.id, modes: obj.modes.dup) if obj.modes
+      end
+    end
+
+    include Casting
+  end
+end

data/lib/enjine/engine/casting/cost_options.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Choosing between costs (Costs::OneOf, CR 601.2b): which of the listed costs will be paid is announced
+    # while casting or activating, before X and the total cost (CR 601.2f, 602.2b). The cast frame keeps the
+    # option chosen for each one_of, in order ("cost_options"); from then on the chosen cost stands in its place.
+    # Before the cast begins, every combination is tried (`cost_variants`).
+    module CostOptions
+      ONE_OF = Mechanics::Costs::OneOf
+
+      # Every way to pay `costs`: each one_of replaced by one of its options.
+      def cost_variants(costs)
+        costs.reduce([[]]) do |variants, cost|
+          cost.is_a?(ONE_OF) ? variants.product(cost.options).map { |v, o| v + [o] } : variants.map { it + [cost] }
+        end
+      end
+
+      # `costs` with the n-th one_of replaced by its option chosen[n]; one_ofs not announced yet are left out.
+      def with_cost_options(costs, chosen)
+        n = -1
+        costs.filter_map do |cost|
+          next cost unless cost.is_a?(ONE_OF)
+
+          option = chosen[n += 1]
+          option && cost.options[option]
+        end
+      end
+
+      # The mana parts of a cost list, as one mana cost.
+      def costs_mana(costs) = Mana.sum_costs(costs.select(&:mana?).map(&:mana_cost))
+
+      # Whether some way of paying `costs` (on top of the mana cost `base`) is open to `index`: its other parts
+      # payable for `payer` (CR 118.3) and the total cost affordable (CR 601.2f). The block turns the mana to pay
+      # into the total cost.
+      def cost_variant_affordable?(index, costs, payer, base, excluded, purpose)
+        variants = costs.any?(ONE_OF) ? cost_variants(costs) : [costs]
+        variants.any? do |variant|
+          variant.all? { it.mana? || it.payable?(self, payer) } &&
+            affordable?(index, yield(variant_mana(base, variant)), excluded, { **purpose, **waterbend_purpose(variant) })
+        end
+      end
+
+      # The mana cost `base` plus the mana parts of a cost list.
+      def variant_mana(base, costs)
+        return base if base && costs.none?(&:mana?)
+
+        Mana.sum_costs([base, costs_mana(costs)].compact)
+      end
+
+      # The cost list of a cast frame, before the announced options are applied: an ability's costs, a spell's
+      # additional costs (and kicker's when kicked).
+      def frame_cost_list(ctx)
+        case ctx["kind"]
+        when "ability" then stack_ability(object(ctx["object"])).costs
+        when "spell" then spell_cost_list(object(ctx["object"]), ctx["kicked"])
+        else []
+        end
+      end
+
+      def frame_costs(ctx) = with_cost_options(frame_cost_list(ctx), ctx["cost_options"] || [])
+
+      # CR 601.2b: true while waiting for the choice of the next one_of.
+      def ask_cost_option!(ctx)
+        one_of = pending_one_of(ctx) or return false
+        ask!("kind" => "choose_cost_option", "player" => ctx["player"], "costs" => one_of.option_texts)
+        true
+      end
+
+      def pending_one_of(ctx) = frame_cost_list(ctx).grep(ONE_OF)[ctx.fetch("cost_options", []).size]
+
+      # `{type: "cost_option", option: i}` for each option that could be paid: its own part payable (CR 118.3)
+      # and the total cost with it affordable (CR 601.2f).
+      def cost_option_options
+        ctx = casting
+        chosen = ctx.fetch("cost_options", [])
+        pending_one_of(ctx).options.each_with_index.filter_map do |cost, i|
+          { type: "cost_option", option: i } if cost_option_payable?(ctx.merge("cost_options" => chosen + [i]), cost)
+        end
+      end
+
+      def cost_option_payable?(trial, cost)
+        return false unless cost.mana? || cost.payable?(self, cost_payer(trial))
+
+        bend = waterbend_generic(frame_costs(trial))
+        purpose = payment_purpose(bend.positive? ? trial.merge("waterbend" => bend) : trial)
+        affordable?(trial["player"], frame_total_cost(trial, x_value: 0, targets: nil), payment_excluded_source(trial), purpose)
+      end
+
+      def choose_cost_option!(option)
+        ctx = casting
+        (ctx["cost_options"] ||= []) << option
+        ask!(nil)
+      end
+    end
+
+    include CostOptions
+  end
+end

data/lib/enjine/engine/casting/costs.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # The total cost of a spell or ability (CR 601.2f, 602.2b): the mana cost with X announced
+    # (CR 107.3a, 601.2b), plus cost increases, minus cost reductions. It is determined after
+    # targets are chosen and then locked in for payment.
+    module Costs
+      # The mana cost with X announced (CR 107.3a), plus cost increases, minus cost reductions.
+      # Changes affect only the generic part (CR 118.7a) and can't take it below {0}. `targets`
+      # nil means "not chosen yet": conditions about targets then count as met, so the result
+      # is a lower bound on what casting can cost (an upper bound on affordability).
+      def total_cost(index, cost, spell: nil, ability: nil, source: nil, x_value: 0, targets: nil)
+        return nil if cost.nil?
+
+        cost = Mechanics::Keywords::PowerUp.reduced(self, cost.with_x(x_value), ability, source) # CR 702.193a
+        change = cost_change(index, spell, ability, source, targets)
+        change.zero? ? cost : cost.with(generic: [cost.generic + change, 0].max)
+      end
+
+      # Net generic change: + increases - reductions, from the spell's own abilities ("this spell
+      # costs {1} less"), the activated ability's own reduction, and static abilities of
+      # permanents ("spells you cast cost {1} less").
+      def cost_change(index, spell, ability, source, targets)
+        if spell
+          ctx = Mechanics::EffectContext.new(index, spell.id, spell.id, targets)
+          own = chars(spell).abilities.sum do |inst|
+            inst.ability.kind == :cost_reduction ? -inst.ability.reduction(self, ctx) : 0
+          end
+          own + cost_modifiers.sum { |perm, modifier| modifier.change_for(self, perm, spell, index) }
+        elsif ability.respond_to?(:cost_reduction) && ability.cost_reduction
+          -ability.cost_reduction.reduction(self, Mechanics::EffectContext.new(index, source, nil, targets))
+        else
+          0
+        end
+      end
+
+      # [[permanent, CostModifier], ...] on the battlefield.
+      def cost_modifiers
+        state.battlefield.flat_map do |id|
+          obj = object(id)
+          chars(obj).abilities.filter_map { [obj, it.ability] if it.ability.kind == :cost_modifier }
+        end
+      end
+
+      # The mana cost being paid, before X and cost changes (nil for a triggered ability).
+      def base_cost(ctx)
+        obj = object(ctx["object"])
+        case ctx["kind"]
+        when "spell" # plus additional costs, kicker and chosen tiered modes (CR 601.2f, 702.183a); alternative
+          # costs (CR 118.9, Permissions)
+          cost = ctx["method"] ? alternative_base_cost(ctx) : chars(obj).mana_cost
+          modes = spell_ability_of(obj)&.mode_costs(ctx["modes"] || []) || []
+          cost && Mana.sum_costs([cost, costs_mana(frame_costs(ctx)), *modes]) # Engine::CostOptions
+        when "ability" then costs_mana(frame_costs(ctx))
+        end
+      end
+
+      def frame_total_cost(ctx, x_value: ctx["x"].to_i, targets: ctx["targets"])
+        obj = object(ctx["object"])
+        spell = ctx["kind"] == "spell" ? obj : nil
+        ability = ctx["kind"] == "ability" ? stack_ability(obj) : nil
+        total = total_cost(ctx["player"], base_cost(ctx), spell: spell, ability: ability, source: ctx["source"],
+                                                          x_value: x_value, targets: targets)
+        harmonize_reduced(total, frame_harmonize_power(ctx)) # CR 702.180a (Engine::AltCasting)
+      end
+
+      # CR 601.2f: the total cost is determined once and locked in.
+      def lock_total_cost!(ctx)
+        ctx["remaining"] = remaining_hash(frame_total_cost(ctx))
+        lock_waterbend!(ctx) # CR 701.67b (Engine::Waterbending)
+      end
+
+      # CR 601.2b: X is announced (once) before targets are chosen. True while waiting for it. Without {X} in
+      # the mana cost or a cost such as "pay X life" or "exile X cards", X is 0.
+      def ask_x!(ctx)
+        return false unless ctx["x"].nil?
+        return (ctx["x"] = 0) && false unless base_cost(ctx)&.x_symbols.to_i.positive? || x_costs(ctx).any?
+
+        ask!("kind" => "choose_x", "player" => ctx["player"], "max" => x_limit(ctx))
+        true
+      end
+
+      # The costs paid while casting that define X: "pay X life" (Costs::PayLife), "exile X cards from your
+      # graveyard" (Costs::CardsCost).
+      def x_costs(ctx) = casting_costs(ctx).select { it.respond_to?(:x?) && it.x? }
+
+      # A {T} ability's own source can't pay for it.
+      def payment_excluded_source(ctx)
+        ctx["type"] == "cast" && ctx["kind"] == "ability" && needs_tap?(casting_ability) ? ctx["source"] : nil
+      end
+
+      # The largest X the player could pay for: the mana available beyond the rest of the cost, and for
+      # "pay X life" no more than their life total (CR 119.4), for "exile X cards" no more than there are (CR 118.3).
+      def x_limit(ctx)
+        limits = x_costs(ctx).map { it.x_limit(self, cost_payer(ctx)) }
+        symbols = base_cost(ctx)&.x_symbols.to_i
+        return limits.min if symbols.zero?
+
+        cost = frame_total_cost(ctx, x_value: 0, targets: nil)
+        spare = mana_units(ctx["player"], payment_excluded_source(ctx), payment_purpose(ctx)).size - cost.mana_value
+        (limits << ([spare, 0].max / symbols)).min
+      end
+
+      # CR 601.2b / 107.3a: the value of X is announced; the spell or ability keeps it on the stack.
+      def announce_x!(value)
+        ctx = casting
+        ctx["x"] = value
+        object(ctx["object"]).x = value
+        emit Events::XAnnounced.new(player: name(ctx["player"]), object: ctx["object"], value: value)
+        ask!(nil)
+      end
+    end
+
+    include Costs
+  end
+end