enjine 0.1.0

data/lib/enjine/engine/attachments.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Auras and Equipment on the battlefield (CR 301.5, 303.4, 701.3): attaching, and the
+    # state-based actions that clean up illegal attachments (CR 704.5m, 704.5n, 704.5p).
+    # An attachment remembers the id it is attached to; when that object leaves the
+    # battlefield it becomes a new object (CR 400.7), so the stale id is cleaned up here.
+    module Attachments
+      def aura?(obj) = chars(obj).subtypes.include?(:aura)
+      def equipment?(obj) = chars(obj).subtypes.include?(:equipment)
+
+      # The objects attached to `id`, in battlefield order.
+      def attachments_of(id) = state.battlefield.select { object(it).attached_to == id }
+
+      # CR 700.9: equipped, or enchanted by an Aura its controller controls, makes a permanent modified.
+      def modifying_attachment?(obj)
+        attachments_of(obj.id).any? do
+          attachment = object(it)
+          equipment?(attachment) || (aura?(attachment) && attachment.controller == obj.controller)
+        end
+      end
+
+      # Whether `attachment` could legally be attached to the permanent `target_id` (CR 701.3a): not to a
+      # permanent with protection from it (CR 702.16c-d).
+      def can_attach?(attachment, target_id)
+        return false if target_id == attachment.id || !state.battlefield.include?(target_id) # CR 301.5c, 303.4d
+        return false if protected_from?(object(target_id), attachment)
+
+        if aura?(attachment)
+          enchantable?(attachment, target_id)
+        elsif equipment?(attachment)
+          !chars(attachment).creature? && chars(target_id).creature? # CR 301.5, 301.5c
+        else
+          false
+        end
+      end
+
+      # CR 702.5a, 702.5c, 303.4d: what the Aura's enchant abilities allow (an Aura creature can't enchant).
+      def enchantable?(aura, target_id)
+        return false if chars(aura).creature?
+
+        enchants = chars(aura).abilities.map(&:ability).select { it.kind == :enchant }
+        !enchants.empty? && enchants.all? { it.filter.match_for?(self, target_id, aura.controller, aura.id) }
+      end
+
+      # CR 701.3b-c: an illegal attachment doesn't move; reattaching to the same object does nothing.
+      def attach!(attachment, target_id)
+        return false if attachment.attached_to == target_id || !can_attach?(attachment, target_id)
+
+        attachment.attached_to = target_id
+        attachment.memory["attached_at"] = next_timestamp! # CR 613.7e: a new timestamp (AbilityLayers#timestamp_of)
+        emit Events::Attached.new(object: attachment.id, to: target_id)
+        true
+      end
+
+      # CR 701.3d: unattach (the permanent stays on the battlefield).
+      def unattach!(attachment)
+        from = attachment.attached_to or return
+        attachment.attached_to = nil
+        emit Events::Unattached.new(object: attachment.id, from: from)
+      end
+
+      # CR 704.5m: an Aura attached to an illegal object, or to nothing, goes to the graveyard.
+      def illegal_aura?(obj)
+        return false unless aura?(obj)
+
+        to = obj.attached_to
+        to.nil? || !can_attach?(obj, to)
+      end
+
+      # CR 704.5n (Equipment attached to an illegal permanent) and 704.5p (anything that's neither
+      # an Aura nor an Equipment, e.g. a permanent that stopped being one): it becomes unattached.
+      # Returns true when anything was unattached.
+      def unattach_illegal_attachments!
+        loose = state.battlefield.select do |id|
+          obj = object(id)
+          obj.attached_to && !aura?(obj) && !can_attach?(obj, obj.attached_to)
+        end
+        loose.each { unattach!(object(it)) }
+        !loose.empty?
+      end
+    end
+    include Attachments
+  end
+end

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

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Alternative costs given by keyword abilities (CR 118.9, Abilities::AlternativeCost): flashback, harmonize,
+    # mayhem, warp, evoke, web-slinging and sneak, plus convoke (CR 702.51), which changes how the total cost
+    # is paid. Each keyword is a cast *method* of Engine::Permissions:
+    #   {"via" => "alt:<ref>", "play" => "cast" | "play", "keyword" => "flashback", "instant" => true (sneak),
+    #    "alt" => {"cost" => "{2}{R}", "ref" => ref, "exile" => true, "returns" => "tapped" | "unblocked",
+    #              "harmonize" => true}}
+    # and a warped card in exile has the method {"via" => "warped", "play" => "cast"} (CR 702.185a).
+    #
+    # How a spell was cast is remembered on the spell (memory "cast_from": the zone, "cast_with": the keyword)
+    # and on the permanent it becomes (CR 400.7d), and each player's turn log keeps the keywords of the
+    # spells they cast this turn ("cast_with"), for "if a spell was warped this turn" (CR 702.185c).
+    module AltCasting
+      HARMONIZE_TEXT = "Tap up to one untapped creature you control (harmonize)"
+      RETURN_TEXT = { "tapped" => "Return a tapped creature you control to its owner's hand",
+                      "unblocked" => "Return an unblocked attacking creature you control to its owner's hand" }.freeze
+
+      # ---- methods ------------------------------------------------------------------------------
+
+      # The cards in a hand with an alternative cost (only those can be cast from it with a method).
+      def alt_cost_hand(player) = player.hand.select { |id| chars(id).abilities.any? { it.ability.kind == :alternative_cost } }
+
+      # The alternative-cost methods of `obj` (a card `index` owns) that function now. A face-down card its owner
+      # may look at is seen face up (a foretold card, CR 702.143a, 406.3a).
+      def alt_methods(index, obj)
+        return [] unless obj.owner == index && obj.kind == "card" && may_look?(obj, index)
+
+        own = face_up(obj.id) { chars(obj).abilities }.filter_map do |inst|
+          ability = inst.ability
+          ability.method_for(inst.ref) if ability.kind == :alternative_cost && ability.functions?(self, obj, index)
+        end
+        own + warped_methods(index, obj)
+      end
+
+      # CR 702.185a: "Its owner may cast this card after the current turn has ended for as long as it remains
+      # exiled." The exiled card remembers the turn it was warped in.
+      def warped_methods(_index, obj)
+        turn = obj.zone == :exile && obj.memory["warped"]
+        turn && state.turn > turn ? [{ "via" => "warped", "play" => "cast" }] : []
+      end
+
+      # CR 702.187b: mayhem needs the card to have been discarded this turn (TurnHistory stamps it).
+      def discarded_this_turn?(obj) = !turned_memory(obj, "discarded").nil?
+
+      # The non-mana parts of the alternative cost being paid (a list of costs, CR 601.2h).
+      def alt_cost_parts(obj, method)
+        ref = method&.dig("alt", "ref") or return []
+        chars(obj).ability(ref).choosing_costs
+      end
+
+      def alt_parts_payable?(obj, method) = alt_cost_parts(obj, method).all? { it.payable?(self, obj) }
+
+      # ---- returning a creature (beam me up, web-slinging, sneak) -------------------------------------
+
+      # Whether an alternative cost returns a creature to its owner's hand (Engine::Permissions#beam_choices).
+      def returns_creature?(alt) = !alt.nil? && (alt.key?("beam") || alt.key?("returns"))
+
+      # The creatures `index` could return for the alternative cost `alt`: any (beam me up, CR 702.196a), a
+      # tapped one (web-slinging, CR 702.188a) or an unblocked attacking one (sneak, CR 702.190a).
+      def return_candidates(index, alt)
+        case alt["returns"]
+        when "tapped" then state.battlefield.select { (o = object(it)).controller == index && o.tapped && chars(o).creature? }
+        when "unblocked"
+          attackers.filter_map { |id, a| id if !a["blocked"] && object(id).controller == index && chars(id).creature? }
+        else beam_candidates(index, alt["not"])
+        end
+      end
+
+      # ---- harmonize (CR 702.180a-b) --------------------------------------------------------------
+
+      def harmonize_candidates(index)
+        state.battlefield.select { (o = object(it)).controller == index && !o.tapped && chars(o).creature? }
+      end
+
+      # The largest reduction harmonize could give `index` now (for whether the card is castable).
+      def best_harmonize_power(index, method)
+        return 0 unless method.dig("alt", "harmonize")
+
+        harmonize_candidates(index).map { [chars(it).power.to_i, 0].max }.max || 0
+      end
+
+      # CR 702.180a: the total cost is reduced by generic mana equal to the tapped creature's power.
+      def harmonize_reduced(cost, power)
+        return cost if cost.nil? || !power.positive?
+
+        cost.with(generic: [cost.generic - power, 0].max)
+      end
+
+      # Costs#frame_total_cost: the cast in progress's reduction.
+      def frame_harmonize_power(ctx) = ctx.dig("harmonize", "power").to_i
+
+      # CR 702.180b: the creature is chosen as the harmonize cost is chosen, before the total cost is locked.
+      def harmonize_pending?(ctx) = ctx["kind"] == "spell" && ctx.dig("method", "alt", "harmonize") && !ctx.key?("harmonize")
+
+      def ask_harmonize!(ctx)
+        ask!("kind" => "choose_cost", "player" => ctx["player"], "cost" => HARMONIZE_TEXT)
+        :wait
+      end
+
+      # Options: each untapped creature, or none (`{type: "cost"}`).
+      def harmonize_options(ctx) = harmonize_candidates(ctx["player"]).map { { object: it } } + [{}]
+
+      # The creature is tapped now (cancelling untaps it); its power is the reduction.
+      def choose_harmonize!(ctx, id)
+        ctx["harmonize"] = { "creature" => id, "power" => id ? [chars(id).power.to_i, 0].max : 0 }
+        if id
+          tap!(object(id))
+          ctx["tapped"] << id
+        end
+        ask!(nil)
+      end
+
+      # The zone a spell is (being) cast from (CR 601.2a): remembered once cast, the cast frame's origin
+      # while it's being cast, or the zone a card is in before it's cast (when its cost is estimated).
+      def cast_origin(spell)
+        return spell.zone.to_s unless spell.zone == :stack
+
+        spell.memory["cast_from"] || state.frames.rfind { it["object"] == spell.id }&.dig("origin", "zone") || "hand"
+      end
+
+      # ---- as the spell becomes cast --------------------------------------------------------------
+
+      # Where the spell was cast from and with which keyword (CR 601.2a, 400.7d); a warp spell's delayed
+      # trigger (CR 702.185a); the creatures that convoked it (CR 702.51c).
+      def record_cast_how!(obj, ctx)
+        obj.memory["cast_from"] = ctx.dig("origin", "zone") || "hand"
+        obj.memory["convoked"] = ctx["convoked"].dup if ctx["convoked"]
+        return unless ctx.dig("method", "alt") # mayhem without a cost: no keyword cost was paid
+
+        keyword = ctx.dig("method", "keyword") or return
+        obj.memory["cast_with"] = keyword
+        (turn_log(ctx["player"])["cast_with"] ||= []) << keyword
+        warp_delayed!(obj, ctx) if keyword == "warp"
+      end
+
+      def warp_delayed!(obj, ctx)
+        ability = chars(obj).ability(ctx.dig("method", "alt", "ref"))
+        create_delayed_trigger!("controller" => ctx["player"], "source" => obj.id, "card" => obj.card,
+                                "ability" => ability.delayed.ref, "watched" => [obj.id])
+      end
+
+      # The creature returned for beam me up, web-slinging or sneak goes to its owner's hand as the spell
+      # becomes cast (CR 601.2h); a sneak spell remembers what it was attacking (CR 702.190b).
+      def returned_creature!(obj, ctx)
+        creature = ctx["beam_creature"]
+        alt = ctx.dig("method", "alt")
+        obj.memory["sneak_attack"] = attackers.dig(creature, "target") if alt["returns"] == "unblocked"
+        move!(creature, :hand, reason: alt.key?("beam") ? "beam_me_up" : ctx.dig("method", "keyword"))
+      end
+
+      # The permanent a spell becomes remembers how it was cast; a warp spell's permanent is watched by the
+      # delayed trigger; a sneak spell's enters tapped and attacking (CR 702.190b, 506.3a). Cards its costs
+      # exiled stay linked to it ("behold a Goblin and exile it", CR 607.2a).
+      def alt_enters!(spell, enters)
+        how = spell.memory.slice("cast_from", "cast_with", "mana_from", Mechanics::Linked::EXILED, "haste_while_controlled_by")
+        how["warp_spell"] = spell.id if spell.memory["cast_with"] == "warp"
+        (enters["memory"] ||= {}).merge!(how) unless how.empty?
+        target = spell.memory["sneak_attack"] or return
+        enters["tapped"] = true
+        enters["attacking"] = target if target.start_with?("player:") || state.battlefield.include?(target)
+      end
+
+      # ---- convoke (CR 702.51) and improvise (CR 702.126) ------------------------------------------
+
+      # Who helps pay: convoke taps creatures (for {1} or one mana of their color), improvise artifacts
+      # (for {1} only). Neither is an additional or alternative cost (CR 702.51b, 702.126b).
+      HELPERS = { "convoke" => :creature, "improvise" => :artifact }.freeze
+
+      def convoke?(spell) = helper_keywords(spell).include?("convoke")
+      def helper_keywords(spell) = spell.nil? ? [] : HELPERS.keys.select { chars(spell).keyword?(it.to_sym) } | granted_helpers(spell)
+
+      # "Noncreature spells you cast have improvise" (Abilities::SpellsHave, CR 611.3a).
+      def granted_helpers(spell)
+        board_abilities(:spells_have).flat_map { |perm, ability| ability.keywords_for(self, spell, perm.controller) }
+      end
+
+      # Mana units (Engine::ManaSources) the permanents `index` could convoke or improvise with add for
+      # `purpose`: one per untapped helper that isn't counted as a mana source, paying {1} or (convoke) one
+      # of its colors; an improvise-only unit has no type, so it pays only generic mana.
+      def convoke_units(index, purpose, excluded = [])
+        spell = purpose&.[]("spell")
+        spell = state.objects[spell] unless spell.is_a?(GameObject)
+        kinds = helper_keywords(spell)
+        return [] if kinds.empty?
+
+        sources = all_mana_sources(index).map(&:first)
+        kinds.flat_map { convoke_candidates(index, it) }.uniq.reject { excluded.include?(it) || sources.include?(it) }.map do |id|
+          kinds.include?("convoke") && chars(id).creature? ? chars(id).colors : []
+        end
+      end
+
+      def convoke_candidates(index, kind = "convoke")
+        state.battlefield.select { (o = object(it)).controller == index && !o.tapped && chars(o).type?(HELPERS[kind]) }
+      end
+
+      # pay_cost options: `{type: "convoke" | "improvise", object: id}` for each helper that can pay part of what is left.
+      def convoke_options
+        frame = payment
+        return [] unless frame["type"] == "cast" && frame["kind"] == "spell"
+
+        helper_keywords(object(frame["object"])).flat_map do |kind|
+          convoke_candidates(frame["player"], kind).filter_map do |id|
+            { type: kind, object: id } if convoke_slot(frame, id, kind)
+          end
+        end
+      end
+
+      # The part of the remaining cost the permanent pays: for convoke a colored or hybrid symbol of one of its
+      # colors, else generic (or half of a {2/B} paid as {2}, CR 107.4e, 601.2b); for improvise only generic (one
+      # that keeps the rest payable once the payment is irreversible).
+      def convoke_slot(frame, id, kind = "convoke")
+        rem = frame["remaining"]
+        colors = kind == "convoke" ? chars(id).colors : []
+        slots = colors.flat_map { pay_slots(rem, it.to_s) }.select { %i[color hybrid].include?(it.first) }.uniq
+        slots << [:generic] if rem["generic"].positive?
+        slots += pay_slots(rem, "C").select { it.first == :two_generic }
+        return slots.first unless frame["irreversible"]
+
+        pl = player(frame["player"])
+        slots.find do |slot|
+          payable_with?(frame, remaining_cost(after_paying(rem, slot)), pl.mana_pool.dup, payment_reserved(frame) + [id],
+                        restricted: pl.restricted_mana)
+        end
+      end
+
+      # CR 702.51a, 702.126a: tapping the permanent pays that mana; cancelling untaps it.
+      def convoke!(id, kind = "convoke")
+        frame = payment
+        frame["remaining"] = after_paying(frame["remaining"], convoke_slot(frame, id, kind))
+        tap!(object(id))
+        frame["tapped"] << id
+        (frame["convoked"] ||= []) << id if kind == "convoke" # CR 702.51c
+        ask!(nil)
+      end
+
+      # ---- history ------------------------------------------------------------------------------------
+
+      # CR 702.187b: a card discarded this turn is stamped in the graveyard (TurnHistory#object_memory!).
+      def discard_recorded!(event)
+        return unless event.reason == "discard" && event.to == "graveyard" && state.objects.key?(event.new_id)
+
+        object_memory!(event.new_id, "discarded")
+      end
+
+      # Whether any player cast a spell with `keyword`'s cost this turn (CR 702.185c: "a spell was warped").
+      def cast_with_this_turn?(keyword) = state.players.each_index.any? { Array(turn_log(it)["cast_with"]).include?(keyword) }
+    end
+
+    include AltCasting
+  end
+end

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

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Choices made while casting or activating, besides targets and mana (CR 601.2b-d, 601.2h, 602.2b):
+    # kicker and other additional costs, how many modes, dividing an amount among targets, costs that
+    # need a choice (tap or sacrifice a permanent, remove counters), and "activate only once each turn".
+    module CastChoices
+      # ---- additional costs of spells (CR 601.2b, 601.2f, 702.33) ----------------------------
+
+      def spell_cost_abilities(obj, kind) = chars(obj).abilities.map(&:ability).select { it.kind == kind }
+
+      # CR 601.2f / 118.3: the spell's mandatory non-mana additional costs can be paid.
+      def additional_costs_payable?(obj) = spell_cost_abilities(obj, :additional_cost).all? { it.payable?(self, obj) }
+
+      # The costs being paid, in order: an ability's own costs; a spell's additional costs (and kicker's).
+      def casting_costs(ctx)
+        case ctx["kind"]
+        when "ability" then frame_costs(ctx) # with the chosen option of each one_of (Engine::CostOptions)
+        when "spell" then frame_costs(ctx).reject(&:mana?) + alt_cost_parts(object(ctx["object"]), ctx["method"]) # Engine::AltCasting
+        else []
+        end
+      end
+
+      # CR 601.2b / 702.33a: true while waiting for the kicker announcement.
+      def ask_kicker!(ctx)
+        return false unless ctx["kind"] == "spell" && ctx["kicked"].nil?
+
+        kicker = spell_cost_abilities(object(ctx["object"]), :kicker).first
+        return ctx["kicked"] = false unless kicker
+
+        ask!("kind" => "choose_kicker", "player" => ctx["player"], "cost" => kicker.costs.join(", "))
+        true
+      end
+
+      # "Kick" when the kicked total could be paid (CR 118.3, 601.2f) and the kicked spell has targets;
+      # "don't kick" when the spell has targets without it (CR 702.33g).
+      def kicker_options
+        ctx = casting
+        obj = object(ctx["object"])
+        spell = spell_ability_of(obj)
+        kick = kicked_castable?(ctx["player"], obj)
+        plain = ability_targetable?(spell, ctx["player"], obj.id)
+        (kick ? [{ type: "kick" }] : []) + (plain ? [{ type: "no_kick" }] : [])
+      end
+
+      # Whether the spell could be cast kicked: kicker payable, the kicked total affordable and its
+      # kicked targets (or normal ones) available.
+      def kicked_castable?(index, obj)
+        return false if spell_cost_abilities(obj, :kicker).empty?
+
+        spell = spell_ability_of(obj)
+        targetable = if spell.nil? || spell.modal?
+                       ability_targetable?(spell, index,
+                                           obj.id)
+                     else
+                       targets_available?(spell.targets_for([], kicked: true),
+                                          index, obj.id)
+                     end
+        targetable && cost_variant_affordable?(index, spell_cost_list(obj, true), obj, chars(obj).mana_cost, nil, { "spell" => obj.id }) do
+          total_cost(index, it, spell: obj)
+        end
+      end
+
+      # The spell remembers it at once, so a "choose both if ..." mode count sees it (CR 601.2b, 702.194b);
+      # `kicked_with` names the optional cost paid (kicker, teamwork, an optional additional cost); only kicker
+      # makes the spell kicked (CR 702.33d).
+      def announce_kicker!(kicked)
+        ctx = casting
+        ctx["kicked"] = kicked
+        if kicked
+          obj = object(ctx["object"])
+          optional = spell_cost_abilities(obj, :kicker).first
+          obj.memory["kicked_with"] = optional.keyword
+          obj.memory["kicked"] = true if optional.kicks?
+        end
+        ask!(nil)
+      end
+
+      # ---- modes (CR 700.2) ---------------------------------------------------------------------
+
+      # [min, max], determined once as modes are first chosen.
+      def mode_range(ctx, ability)
+        ctx["choose"] ||= ability.choice_range(self, Mechanics::EffectContext.new(ctx["player"], ctx["source"] || ctx["object"],
+                                                                                  ctx["object"], nil))
+      end
+
+      def modes_pending?(ctx, ability)
+        min, max = mode_range(ctx, ability)
+        chosen = ctx["modes"].size
+        chosen < min || (chosen < max && !ctx["modes_done"] && !choosable_modes(ctx, ability).empty?)
+      end
+
+      # CR 601.2b / 700.2: modes still choosable (distinct, with legal targets, and for "choose one that
+      # hasn't been chosen" not chosen before for this object).
+      def choosable_modes(ctx, ability)
+        modes = available_modes(ability, ctx["player"], ctx["object"], ctx["source"]) - ctx["modes"]
+        (modes - used_modes(ability, ctx["source"], ctx["ability"])).select { mode_affordable?(ctx, ability.modes[it]) }
+      end
+
+      # A spell's mode with a cost (tiered, CR 702.183a) is offered only if the spell could still be paid for
+      # with it (CR 601.2f, 118.3).
+      def mode_affordable?(ctx, mode)
+        base = mode.cost && base_cost(ctx) or return true
+
+        obj = object(ctx["object"])
+        total = total_cost(ctx["player"], Mana.sum_costs([base, mode.cost]), spell: obj)
+        affordable?(ctx["player"], total, nil, { "spell" => obj.id })
+      end
+
+      # Modes chosen before for this source's "choose one that hasn't been chosen" ability `ref`.
+      def used_modes(ability, source, ref)
+        return [] unless ability.extras.unchosen
+
+        state.objects[source]&.memory&.dig("chosen_modes", ref) || []
+      end
+
+      def mode_options
+        ctx = casting
+        ability = casting_ability
+        options = choosable_modes(ctx, ability).map { { type: "mode", mode: it } }
+        ctx["modes"].size >= mode_range(ctx, ability).first ? options + [{ type: "done" }] : options
+      end
+
+      def choose_mode!(index)
+        casting["modes"] << index
+        ask!(nil)
+      end
+
+      def modes_done!
+        casting["modes_done"] = true
+        ask!(nil)
+      end
+
+      # ---- dividing among targets (CR 601.2d) ------------------------------------------------------
+
+      # Each chosen target gets one; the rest is assigned one at a time when there's a choice.
+      def ask_distribution!(ctx, ability)
+        amount = divided_amount(ctx, ability) or return false
+        chosen = ctx["targets"].flatten.compact
+        ctx["division"] ||= chosen.to_h { [it, 1] }
+        left = amount - ctx["division"].values.sum
+        return false unless left.positive? && chosen.any?
+
+        if chosen.size == 1
+          ctx["division"][chosen.first] += left
+          return false
+        end
+
+        ask!("kind" => "distribute", "player" => ctx["player"], "left" => left)
+        true
+      end
+
+      # The amount divided (CR 601.2d), an amount such as "X damage, where X is the number of lands you
+      # control": computed once, as the spell or ability is put on the stack, and kept in the frame.
+      def divided_amount(ctx, ability)
+        divide = ability&.extras&.divide or return nil
+        ctx["divide"] ||= [divide.value(self, Mechanics::EffectContext.new(ctx["player"], ctx["source"] || ctx["object"],
+                                                                           ctx["object"], nil, [])), 0].max
+      end
+
+      def distribute_options = casting["division"].keys.map { { type: "assign", target: it } }
+
+      def distribute!(ref)
+        casting["division"][ref] += 1
+        ask!(nil)
+      end
+
+      # ---- costs that need a choice (CR 601.2h, 602.2b) -----------------------------------------
+
+      # The index (in casting_costs) of the next cost that still needs a choice.
+      def next_cost_choice(ctx, _ability = nil)
+        made = (ctx["paid"] || []).group_by { it["cost"] }
+        casting_costs(ctx).each_with_index.find do |cost, i|
+          cost.respond_to?(:choices_needed) && !cost_chosen?(ctx, cost, i, made.fetch(i, []))
+        end&.last
+      end
+
+      # A cost with a fixed number of choices is chosen once it has them; one of "any number" (crew, CR
+      # 702.122a) says itself, given whether the player said they're done.
+      def cost_chosen?(ctx, cost, index, entries)
+        return entries.size >= ctx["x"].to_i if cost.respond_to?(:x?) && cost.x? # "exile X cards" (CR 601.2b)
+        return entries.size >= cost.choices_needed unless cost.respond_to?(:chosen?)
+
+        cost.chosen?(self, cost_payer(ctx), entries, ctx.fetch("costs_done", []).include?(index))
+      end
+
+      # Whether the player may stop choosing for the current cost ("any number", once enough is chosen).
+      def cost_choice_finishable?
+        ctx = casting
+        return false if harmonize_pending?(ctx) || beam_choice_pending?(ctx)
+
+        index = next_cost_choice(ctx)
+        cost = casting_costs(ctx)[index]
+        cost.respond_to?(:finishable?) && cost.finishable?(cost_entries(ctx, index))
+      end
+
+      def finish_cost_choice!
+        ctx = casting
+        (ctx["costs_done"] ||= []) << next_cost_choice(ctx)
+        ask!(nil)
+      end
+
+      def ask_cost_choice!(ctx, cost)
+        ask!("kind" => "choose_cost", "player" => ctx["player"], "cost" => cost.to_s)
+        :wait
+      end
+
+      # The object a cost is paid for: the ability's source, or the spell itself.
+      def cost_payer(ctx) = object(ctx["kind"] == "ability" ? ctx["source"] : ctx["object"])
+
+      def cost_entries(ctx, index) = (ctx["paid"] || []).select { it["cost"] == index }
+
+      def cost_choice_candidates
+        ctx = casting
+        return harmonize_options(ctx) if harmonize_pending?(ctx) # Engine::AltCasting
+        return beam_choices(ctx).map { { object: it } } if beam_choice_pending?(ctx) # Engine::Permissions
+
+        index = next_cost_choice(ctx)
+        casting_costs(ctx)[index].choice_options(self, cost_payer(ctx), cost_entries(ctx, index))
+      end
+
+      # Records (and for tapping, pays) the chosen part of the cost (costs may be paid in any order,
+      # CR 601.2h). Cancelling the cast untaps what was tapped (ctx "tapped").
+      def choose_cost!(option)
+        ctx = casting
+        return choose_harmonize!(ctx, option[:object]) if harmonize_pending?(ctx) # Engine::AltCasting
+        return choose_beam_creature!(option[:object]) if beam_choice_pending?(ctx) # Engine::Permissions
+
+        index = next_cost_choice(ctx)
+        entry = casting_costs(ctx)[index].choose!(self, option).merge("cost" => index)
+        ctx["tapped"] << entry["object"] if entry["tapped"]
+        (ctx["paid"] ||= []) << entry
+        ask!(nil)
+      end
+
+      # As the spell or ability becomes cast: sacrifices and counter removals chosen earlier happen now.
+      def pay_chosen_costs!(ctx)
+        payer = state.objects[ctx["kind"] == "ability" ? ctx["source"] : ctx["object"]]
+        casting_costs(ctx).each_with_index do |cost, i|
+          cost.pay_chosen!(self, payer, cost_entries(ctx, i)) if cost.respond_to?(:pay_chosen!)
+        end
+        object(ctx["object"]).paid = Snapshot.deep_copy(ctx["paid"]) if ctx["paid"] # with what was sacrificed
+      end
+
+      # ---- once each turn (CR 602.5b) ----------------------------------------------------------
+
+      def activations_this_turn(obj, ref)
+        entry = obj.memory.dig("activations", ref)
+        entry && entry["turn"] == state.turn ? entry["count"] : 0
+      end
+
+      def activation_allowed?(index, obj, ref, ability)
+        return true unless ability.respond_to?(:restriction_met?)
+        return false if ability.per_turn && activations_this_turn(obj, ref) >= ability.per_turn
+        return false if ability.once? && obj.memory.fetch("exhausted", []).include?(ref) # CR 602.5b, 702.177a, 702.193a
+
+        ability.restriction_met?(self, index, obj.id)
+      end
+
+      # Kept on the source object, so the limit applies even if its controller changes (CR 602.5b). An exhaust or
+      # power-up ability is remembered for as long as the object exists (CR 702.177a, 702.193a; a new object can
+      # again, CR 400.7).
+      def record_activation!(ctx)
+        source = state.objects[ctx["source"]] or return
+        ability = chars(source).ability(ctx["ability"])
+        (source.memory["exhausted"] ||= []) << ctx["ability"] if ability.respond_to?(:once?) && ability.once?
+        return unless ability.respond_to?(:per_turn) && ability.per_turn
+
+        (source.memory["activations"] ||= {})[ctx["ability"]] =
+          { "turn" => state.turn, "count" => activations_this_turn(source, ctx["ability"]) + 1 }
+      end
+
+      # What was announced while casting stays with the spell or ability (CR 702.33d, 601.2d).
+      def record_announcements!(obj, ctx)
+        obj.memory["kicked"] = true if ctx["kicked"] && spell_cost_abilities(obj, :kicker).first&.kicks? # CR 702.33d
+        obj.memory["division"] = ctx["division"].dup if ctx["division"]
+        record_chosen_modes!(ctx, casting_ability)
+      end
+
+      # "Choose one that hasn't been chosen": the source remembers the modes chosen for it.
+      def record_chosen_modes!(ctx, ability)
+        return unless ability&.modal? && ability.extras.unchosen
+
+        source = state.objects[ctx["source"]] or return
+        ((source.memory["chosen_modes"] ||= {})[ctx["ability"]] ||= []).concat(ctx["modes"])
+      end
+    end
+
+    include CastChoices
+  end
+end