enjine 0.1.0

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # One-shot and continuous effects (CR 609-611). Each effect is built from data
+      # and applied at resolution with an EffectContext.
+      # Base effect: parses the common "to" selector, an "amount" (fixed or computed, see
+      # Mechanics::Amount) and an optional "if" condition checked on resolution (CR 608.2c).
+      class Effect < Primitive
+        attr_reader :to, :condition
+
+        def self.keys = %w[amount to if]
+        def self.default_to = nil
+        # Whether `amount` may be left out ("discard your hand").
+        def self.amount_optional?(_params) = false
+
+        # `results_count`: how many earlier effects of the enclosing list a {"result": n} selector may name.
+        def self.build(params, errors, path, targets_count: 0, results_count: 0, **)
+          Mechanics.check_keys(params, keys, errors, path)
+          raw_to = Mechanics.fetch_param(params, :to) || default_to
+          to = if raw_to.nil?
+                 errors << "#{path}.to: required"
+                 nil
+               else
+                 Selector.build(raw_to, errors, "#{path}.to", targets_count: targets_count, results_count: results_count)
+               end
+          new(to: to, params: params, errors: errors, path: path, targets_count: targets_count, results_count: results_count)
+        end
+
+        def initialize(to:, params:, errors:, path:, targets_count: 0, results_count: 0)
+          super()
+          @to = to
+          @targets_count = targets_count
+          @results_count = results_count
+          if self.class.keys.include?("amount")
+            raw = Mechanics.fetch_param(params, :amount)
+            @amount = if raw.nil?
+                        errors << "#{path}.amount: required" unless self.class.amount_optional?(params)
+                        Amount::Fixed.new(0)
+                      else
+                        Amount.build(raw, errors, "#{path}.amount", targets_count: targets_count,
+                                                                    results_count: results_count)
+                      end
+          end
+          raw_if = Mechanics.fetch_param(params, :if)
+          @condition = raw_if && Condition.build(raw_if, errors, "#{path}.if", targets_count: targets_count,
+                                                                               results_count: results_count)
+          setup(params, errors, path)
+          freeze
+        end
+
+        # The fixed amount (for display), or the amount computed for this resolution.
+        def amount = @amount.is_a?(Amount::Fixed) ? @amount.n : @amount
+        def amount_for(engine, ctx) = @amount.value(engine, ctx)
+
+        def setup(_params, _errors, _path) = nil
+
+        # Effects nested inside this one (a "may" or delayed trigger's list); see CardDefinition#all_effects.
+        def nested_effects = []
+
+        # CR 118.3: whether the effect can be done fully now (an optional effect offered as a cost).
+        def possible?(_engine, _ctx) = true
+
+        # Runs the effect during resolution. Effects that need a player's choice override this,
+        # keep their progress in `locals` (plain JSON data) and return :wait after asking.
+        def run(engine, ctx, _locals)
+          apply(engine, ctx) if condition.nil? || condition.true?(engine, ctx)
+          :done
+        end
+
+        def refs(engine, ctx) = to ? to.resolve(engine, ctx) : []
+
+        def to_s
+          words = self.class.primitive_name.tr("_", " ")
+          words += " #{amount}" if amount
+          "#{words} → #{to}"
+        end
+
+        def objects(engine, ctx)
+          refs(engine, ctx).select { engine.state.objects.key?(it) && engine.state.battlefield.include?(it) }
+        end
+
+        def players(engine, ctx) = refs(engine, ctx).filter_map { Filters.player_index(engine, it) }
+      end
+
+      # Moves each referenced permanent, or card in one of the class's other zones (a target card in a
+      # graveyard, a card chosen from a hand), to a zone. A card that has left the zone it was in
+      # (CR 400.7, 608.2b) isn't found any more, so it isn't moved.
+      class ZoneEffect < Effect
+        def self.keys = %w[to if]
+        def self.zone = raise(NotImplementedError)
+        def self.reason = name.split("::").last.downcase
+        def self.from_zones = %i[battlefield graveyard]
+
+        def apply(engine, ctx)
+          movable(engine, ctx).each { move(engine, ctx, it) }
+        end
+
+        # The referenced objects that are permanents or cards in the zones this effect moves cards from.
+        def movable(engine, ctx)
+          refs(engine, ctx).select do |id|
+            obj = engine.state.objects[id]
+            obj && !obj.ability? && self.class.from_zones.include?(obj.zone)
+          end
+        end
+
+        def move(engine, ctx, id)
+          Linked.remember!(engine, ctx, id)
+          engine.move!(id, self.class.zone, reason: self.class.reason)
+        end
+      end
+
+      # Base for effects that ask the controller (or a referenced player) questions while resolving.
+      # Progress lives in `locals` (plain data in the resolve frame), so they survive export/import.
+      class ChoiceEffect < Effect
+        def ask(engine, locals, player, prompt, choices)
+          locals["asked"] = true
+          engine.ask!("kind" => "effect_choice", "player" => player, "prompt" => prompt, "choices" => choices)
+          :wait
+        end
+
+        def answers(locals) = locals["answers"] ||= []
+      end
+
+      # Runs a nested effect list one effect at a time (`may`, `pay`, `choose_cards`); a waiting effect keeps its locals
+      # under "child", where Engine#effect_answer! delivers answers.
+      module NestedList
+        def run_list(engine, ctx, locals, list)
+          while locals["next"] < list.size
+            return :wait if list[locals["next"]].run(engine, ctx, locals["child"] ||= {}) == :wait
+
+            locals.delete("child")
+            locals["next"] += 1
+          end
+          :done
+        end
+
+        def parse_lists(params, errors, path, keys)
+          keys.to_h do |key|
+            [key, Abilities::StackAbility.parse_effects(params, errors, path, @targets_count, key: key.to_sym,
+                                                                                              results_count: @results_count)]
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/effects/become.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # "[It] becomes a Ferengi Scout with base power and toughness 3/4 and gains '...'" (CR 611.2a, 613):
+      # one resolved effect that, for its duration, adds card types, supertypes and subtypes "in addition to
+      # its other types" and sets creature types (layer 4, CR 205.1a-b), sets colors (layer 5), grants keywords
+      # and abilities (layer 6) and sets base power and toughness (layer 7b). "This land becomes a 3/3 red
+      # Elemental creature with haste until end of turn. It's still a land." is one `become`. The affected set
+      # is locked in as it resolves (CR 611.2c). `duration: "indefinite"` lasts as long as the permanent stays
+      # on the battlefield. Granted abilities are part of this card's data, referenced "<this effect's ref>:<j>"
+      # (CardDefinition#effect_granted); on the permanent they are "granted:<card>:<ref>:<j>".
+      class Become < Effect
+        DURATIONS = %w[end_of_turn indefinite while_source_on_battlefield while_you_control_source].freeze
+        GRANTABLE = %i[triggered mana activated play_from additional_land_plays hexproof_from protection_from].freeze
+        # Card types an effect can add (CR 205.1b); instants, sorceries and planeswalkers aren't permanents it makes.
+        ADDABLE_TYPES = %w[artifact creature enchantment land].freeze
+        CHANGES = %w[types supertypes subtypes creature_types colors loses_abilities keywords base_power_toughness
+                     abilities].freeze
+
+        primitive :effect, :become,
+                  description: "Each referenced permanent becomes what the parameters say, for `duration` " \
+                               "(end_of_turn, default; indefinite: as long as it stays on the battlefield; " \
+                               "while_source_on_battlefield: for as long as this effect's source remains on the " \
+                               "battlefield; while_you_control_source: for as long as you control it): it has " \
+                               "the card `types`, `supertypes` and `subtypes` in addition to its other types (layer 4, " \
+                               "\"becomes an artifact creature\"), its creature types are exactly `creature_types` " \
+                               "(layer 4), its colors are `colors` (layer 5), with `loses_abilities: true` it loses all " \
+                               "the abilities it had (layer 6; abilities granted later, keyword counters put on it " \
+                               "later and this effect's own `keywords` and `abilities` stay, CR 613.7), it has the " \
+                               "`keywords` and `abilities` " \
+                               "(layer 6: triggered, activated, mana, play_from or additional_land_plays abilities) and " \
+                               "its base " \
+                               "power and toughness are `base_power_toughness` (layer 7b). A permanent that becomes a " \
+                               "creature has its printed power and toughness (a Vehicle's), or 0/0.",
+                  rules: %w[611.2a 611.2b 611.2c 613.1d 613.1e 613.1f 613.4b 613.7b 205.1a 205.1b 301.7b 514.2],
+                  params: { "types" => "card types it also has: #{ADDABLE_TYPES.join(", ")}",
+                            "supertypes" => "supertypes it also has (\"legendary\")",
+                            "subtypes" => "subtypes it also has (\"in addition to its other types\")",
+                            "creature_types" => "list of creature types (replaces the others)",
+                            "colors" => "list of W, U, B, R, G (replaces its colors)",
+                            "loses_abilities" => "true: it loses all abilities (\"loses all abilities\")",
+                            "keywords" => "list of keywords it gains",
+                            "base_power_toughness" => "{\"power\": n, \"toughness\": n}",
+                            "abilities" => "list of abilities it gains", "duration" => DURATIONS.join(" | "),
+                            "to" => "selector" },
+                  example: { "become" => { "types" => ["creature"], "creature_types" => ["elemental"], "colors" => ["R"],
+                                           "base_power_toughness" => { "power" => 3, "toughness" => 3 },
+                                           "keywords" => ["haste"], "to" => "self" } }
+
+        attr_reader :ref, :creature_types, :base_power_toughness, :granted_abilities, :duration, :card_types,
+                    :supertypes, :subtypes, :colors, :keywords
+
+        def self.keys = CHANGES + %w[duration to if]
+
+        # A list of registered names (card types, supertypes, keywords) as symbols; [] when absent.
+        def self.names_param(params, key, category, errors, path, allowed: nil)
+          raw = Mechanics.fetch_param(params, key)
+          return [].freeze if raw.nil?
+
+          names = raw.is_a?(Array) ? raw.map { it.to_s.downcase.tr(" -", "__") } : []
+          ok = !names.empty? && names.all? { Enjine.registry.fetch(category, it) && (allowed.nil? || allowed.include?(it)) }
+          unless ok
+            choices = allowed || Enjine.registry.names(category)
+            errors << "#{path}.#{key}: must be a non-empty list of #{category}s (#{choices.join(", ")})"
+            return [].freeze
+          end
+          names.uniq.map(&:to_sym).freeze
+        end
+
+        def setup(params, errors, path)
+          @ref = "become:#{path}"
+          @card_types = Become.names_param(params, :types, :type, errors, path, allowed: ADDABLE_TYPES)
+          @supertypes = Become.names_param(params, :supertypes, :supertype, errors, path)
+          @subtypes = parse_types(Mechanics.fetch_param(params, :subtypes), errors, "#{path}.subtypes", "subtypes") || []
+          @creature_types = parse_types(Mechanics.fetch_param(params, :creature_types), errors, "#{path}.creature_types",
+                                        "creature types")
+          @colors = Become.parse_colors(Mechanics.fetch_param(params, :colors), errors, path)
+          @loses_abilities = Mechanics.fetch_param(params, :loses_abilities)
+          errors << "#{path}.loses_abilities: must be true (or absent)" unless [nil, true].include?(@loses_abilities)
+          @keywords = Become.names_param(params, :keywords, :keyword, errors, path)
+          @base_power_toughness = Become.parse_power_toughness(Mechanics.fetch_param(params, :base_power_toughness), errors, path)
+          @granted_abilities = parse_abilities(params, errors, path)
+          @duration = Mechanics.fetch_param(params, :duration) || "end_of_turn"
+          errors << "#{path}.duration: must be one of #{DURATIONS.join(", ")}" unless DURATIONS.include?(@duration)
+          return unless CHANGES.all? { Mechanics.fetch_param(params, it).nil? }
+
+          errors << "#{path}: needs at least one of #{CHANGES.join(", ")}"
+        end
+
+        def loses_abilities? = @loses_abilities == true
+
+        # The state.effects duration and the details it needs. "For as long as [source] remains on the
+        # battlefield" does nothing if the source has already left as this resolves (CR 611.2b).
+        def duration_details(engine, ctx)
+          case @duration
+          when "indefinite" then { "duration" => "permanent" }
+          when "end_of_turn" then { "duration" => "end_of_turn" }
+          else
+            holds = engine.source_duration_holds?(@duration, ctx.source, ctx.controller)
+            holds ? { "duration" => @duration, "source" => ctx.source } : nil
+          end
+        end
+
+        def apply(engine, ctx)
+          affected = objects(engine, ctx)
+          lasting = duration_details(engine, ctx) or return
+          add = ->(kind, details) { engine.add_continuous_effect!(kind, ctx, affected, details.merge(lasting)) }
+          # Removal first: this effect's own keywords and abilities come after it (CR 613.7b).
+          add.call("lose_abilities", {}) if loses_abilities?
+          unless card_types.empty? && supertypes.empty? && subtypes.empty?
+            add.call("add_types", "types" => card_types.map(&:to_s), "supertypes" => supertypes.map(&:to_s), "subtypes" => subtypes)
+          end
+          creatures = affected.select { engine.chars(it).creature? } # after the types above are added
+          engine.add_continuous_effect!("creature_types", ctx, creatures, { "types" => creature_types }.merge(lasting)) if creature_types
+          add.call("colors", "colors" => colors) if colors
+          add.call("grant", "keywords" => keywords.map(&:to_s)) unless keywords.empty?
+          engine.add_continuous_effect!("base_power_toughness", ctx, creatures, base_power_toughness.merge(lasting)) if base_power_toughness
+          return if granted_abilities.empty?
+
+          add.call("abilities", "card" => engine.object(ctx.object).card, "ref" => ref)
+        end
+
+        def nested_effects = granted_abilities.flat_map(&:try_effects)
+
+        def to_s
+          bits = []
+          bits << "loses all abilities" if loses_abilities?
+          bits << [*supertypes, *colors, *subtypes, *card_types].join(" ") unless (card_types + supertypes + subtypes).empty?
+          bits << creature_types.join(" ") if creature_types
+          bits << "base #{base_power_toughness.values.join("/")}" if base_power_toughness
+          bits << keywords.join(", ") unless keywords.empty?
+          bits << "\"#{granted_abilities.join("; ")}\"" unless granted_abilities.empty?
+          "becomes #{bits.join(", ")}#{" until end of turn" if duration == "end_of_turn"} → #{to}"
+        end
+
+        def self.parse_colors(raw, errors, path)
+          return nil if raw.nil?
+
+          ok = raw.is_a?(Array) && raw.all? { Mana::COLORS.include?(it.to_s.upcase.to_sym) }
+          errors << "#{path}.colors: must be a list of W, U, B, R, G ([] for colorless)" unless ok
+          ok ? raw.map { it.to_s.upcase }.uniq.freeze : nil
+        end
+
+        def self.parse_power_toughness(raw, errors, path)
+          return nil if raw.nil?
+
+          unless raw.is_a?(Hash)
+            errors << "#{path}.base_power_toughness: must be {\"power\": n, \"toughness\": n}"
+            return nil
+          end
+          sub = "#{path}.base_power_toughness"
+          Mechanics.check_keys(raw, %w[power toughness], errors, sub)
+          { "power" => Mechanics.integer_param(raw, :power, errors, sub, min: 0),
+            "toughness" => Mechanics.integer_param(raw, :toughness, errors, sub, min: 0) }.freeze
+        end
+
+        private
+
+        def parse_types(raw, errors, path, noun)
+          return nil if raw.nil?
+
+          ok = raw.is_a?(Array) && !raw.empty? && raw.all? { CardDefinition::SUBTYPE_FORMAT.match?(it.to_s) }
+          errors << "#{path}: must be a non-empty list of lowercase #{noun}" unless ok
+          ok ? raw.map(&:to_s).freeze : nil
+        end
+
+        def parse_abilities(params, errors, path)
+          Mechanics.list_param(params, :abilities, errors, path).each_with_index.filter_map do |entry, j|
+            ability = Mechanics.build_entry(:ability, entry, errors, "#{path}.abilities[#{j}]")
+            next ability if ability.nil? || (GRANTABLE.include?(ability.kind) && !(ability.kind == :play_from && ability.self?))
+
+            errors << "#{path}.abilities[#{j}]: only triggered, activated, mana, play_from (for other cards), " \
+                      "additional_land_plays, hexproof_from and protection_from abilities can be gained"
+            nil
+          end.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # "Behold a Dragon" as a resolving instruction (CR 701.4a), usually optional: "you may behold a Dragon.
+      # If you do, create a Treasure token" is {"may": {"effects": [{"behold": ...}], "then": [...]}}. You
+      # reveal a matching card from your hand or choose a matching permanent you control.
+      class Behold < ChoiceEffect
+        primitive :effect, :behold,
+                  description: "You behold an object matching the card spec `card`: reveal such a card from your " \
+                               "hand or choose such a permanent you control. Under `may`, \"yes\" is offered only " \
+                               "when there is one.",
+                  rules: %w[701.4a 701.4b 118.3],
+                  params: { "card" => "card spec (required), e.g. {\"subtypes\": [\"dragon\"]}" },
+                  example: { "may" => { "effects" => [{ "behold" => { "card" => { "subtypes" => ["dragon"] } } }],
+                                        "then" => [{ "create_token" => { "token" => "Treasure" } }] } }
+
+        def self.keys = %w[card if]
+        def self.default_to = "you"
+
+        def setup(params, errors, path)
+          raw = Mechanics.fetch_param(params, :card)
+          errors << "#{path}.card: required" if raw.nil?
+          @card = CardSpec.build(raw, errors, "#{path}.card")
+        end
+
+        def possible?(engine, ctx) = !Beholding.candidates(engine, ctx.controller, @card).empty?
+
+        def run(engine, ctx, locals)
+          return :done unless condition.nil? || condition.true?(engine, ctx)
+
+          options = Beholding.candidates(engine, ctx.controller, @card)
+          chosen = answers(locals).first
+          return :done if options.empty? && chosen.nil?
+
+          choices = options.map { { "type" => "behold", "object" => it } }
+          return ask(engine, locals, ctx.controller, "Behold a #{@card}", choices) unless chosen
+
+          Beholding.behold!(engine, ctx.controller, chosen["object"]) if engine.state.objects.key?(chosen["object"])
+          :done
+        end
+
+        def to_s = "behold a #{@card.to_s.delete_suffix(" card")}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/effects/blight.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # "Blight N" as a cost (CR 701.68a, 601.2h, 602.2b): put N -1/-1 counters on a creature you control,
+      # chosen while casting or activating; the counters are put on it as the spell or ability becomes cast.
+      # Without a creature it can't be paid (CR 701.68b, 118.3). The paid entry names the blighted creature
+      # (CR 701.68c).
+      class Blight < Choosing
+        primitive :cost, :blight,
+                  description: "Blight `amount`: put that many -1/-1 counters on a creature you control, chosen " \
+                               "while casting or activating and put on it as it becomes cast.",
+                  rules: %w[701.68a 701.68b 601.2h 602.2b 118.3],
+                  params: { "amount" => "integer >= 1" },
+                  example: { "blight" => { "amount" => 1 } }
+
+        attr_reader :amount
+
+        def self.keys = %w[amount]
+        def self.default_filter = "creature"
+
+        def initialize(filter, count, other, params, errors, path)
+          @amount = Mechanics.integer_param(params, :amount, errors, path, min: 1)
+          super
+        end
+
+        def pay_chosen!(engine, object, entries)
+          entries.each do |entry|
+            perm = engine.state.objects[entry["object"]]
+            engine.add_counters!(perm, "-1/-1", amount, by_player: object.controller) if perm&.zone == :battlefield
+          end
+        end
+
+        def to_s = "Blight #{amount}"
+      end
+    end
+
+    module Effects
+      # Blight N (CR 701.68a): each referenced player (default: you) puts N -1/-1 counters on a creature they
+      # control, of their choice. A player without creatures can't (CR 701.68b), so in a `may` yes is offered
+      # only when everyone can. The blighted creatures are the effect's results ("the blighted creature",
+      # CR 701.68c).
+      class Blight < ChoiceEffect
+        primitive :effect, :blight,
+                  description: "Each referenced player (default: you) blights `amount`: puts that many -1/-1 " \
+                               "counters on a creature they control, chosen as it resolves (one `effect_choice` " \
+                               "each, in turn order). The blighted creatures are its results.",
+                  rules: %w[701.68a 701.68b 701.68c],
+                  params: { "amount" => "amount", "to" => "player selector (default you)" },
+                  example: { "blight" => { "amount" => 2 } }
+
+        def self.default_to = "you"
+
+        def possible?(engine, ctx) = players(engine, ctx).all? { !creatures(engine, it).empty? }
+
+        def run(engine, ctx, locals)
+          return :done unless locals.key?("queue") || condition.nil? || condition.true?(engine, ctx)
+
+          queue = (locals["queue"] ||= players(engine, ctx))
+          locals["n"] ||= amount_for(engine, ctx)
+          chosen = answers(locals)
+          while chosen.size < queue.size
+            index = queue[chosen.size]
+            options = creatures(engine, index).map { { "type" => "blight", "object" => it } }
+            return ask(engine, locals, index, "Blight #{locals["n"]}: choose a creature you control", options) unless options.empty?
+
+            chosen << { "type" => "none" } # CR 701.68b: nothing to blight
+          end
+          apply_all(engine, locals, queue, chosen)
+        end
+
+        def to_s = "blight #{amount} → #{to}"
+
+        private
+
+        def creatures(engine, index)
+          engine.state.battlefield.select { engine.object(it).controller == index && engine.chars(it).creature? }
+        end
+
+        # The counters are put on once every player has chosen.
+        def apply_all(engine, locals, queue, chosen)
+          chosen.each_with_index do |answer, i|
+            next unless answer["type"] == "blight" && locals["n"].positive?
+
+            engine.add_counters!(engine.object(answer["object"]), "-1/-1", locals["n"], by_player: queue[i])
+            engine.record_result!(answer["object"])
+          end
+          :done
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/effects/choose_cards.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Choose cards from among a set (CR 700.2-style choices made on resolution): from what an earlier
+      # effect moved ({"result": n}), from a player's hand or graveyard, or from permanents. The chosen
+      # cards go to `put`; `then` follows if a card was chosen ("if you do"), `otherwise` if none was
+      # ("if you can't" / "if you don't").
+      class ChooseCards < ChoiceEffect
+        include NestedList
+
+        PUT = %w[hand graveyard exile battlefield library_top library_bottom].freeze
+        ZONES = %w[hand graveyard].freeze
+        REVEAL = %w[chosen all].freeze
+        LISTS = %w[then otherwise].freeze
+
+        primitive :effect, :choose_cards,
+                  description: "You choose `count` (default 1; \"any\": any number) cards matching `for` from `from`: a " \
+                               "selector (e.g. {\"result\": 0}, the cards an earlier effect milled) or a player's zone, " \
+                               "{\"hand\": selector} / {\"graveyard\": selector}. `optional`: you may choose fewer. Then " \
+                               "they are put into `put` (`tapped` onto the battlefield, under your control; exiled cards " \
+                               "`link`ed to the source). `look`: you look at the whole zone first; `reveal`: \"chosen\" " \
+                               "reveals what you chose, \"all\" the whole set. `then` runs if a card was chosen, " \
+                               "`otherwise` if none was (\"if you can't\"). `random: true`: the cards are picked at random " \
+                               "(the game's random number generator) instead of chosen.",
+                  rules: %w[701.20a 701.20e 400.7j 608.2c 607.2a 118.12 701.9b],
+                  params: { "from" => "selector or {\"hand\"|\"graveyard\": player selector}", "for" => "card spec",
+                            "count" => "integer or \"any\"", "optional" => "boolean", "put" => PUT.join(" | "),
+                            "tapped" => "boolean", "link" => "boolean", "look" => "boolean", "random" => "boolean",
+                            "reveal" => REVEAL.join(" | "), "then" => "list of effects", "otherwise" => "list of effects" },
+                  example: { "choose_cards" => { "from" => { "result" => 0 }, "for" => { "permanent" => true },
+                                                 "optional" => true, "put" => "hand" } }
+
+        attr_reader :spec, :count, :put
+
+        def self.keys = %w[from for count optional put tapped link look random reveal then otherwise if]
+        def self.default_to = "you"
+
+        def setup(params, errors, path)
+          @from_zone, @from = parse_from(Mechanics.fetch_param(params, :from), errors, path)
+          @spec = CardSpec.build(Mechanics.fetch_param(params, :for), errors, "#{path}.for")
+          @count = Mechanics.fetch_param(params, :count) || 1
+          unless @count == "any" || (@count.is_a?(Integer) && @count.positive?)
+            errors << "#{path}.count: must be a positive integer or \"any\""
+          end
+          @optional = Mechanics.flag_param(params, "optional", errors, path)
+          @put = Mechanics.fetch_param(params, :put).to_s
+          errors << "#{path}.put: must be one of #{PUT.join(", ")}" unless PUT.include?(@put)
+          @flags = %w[tapped link look random].to_h { [it, Mechanics.flag_param(params, it, errors, path)] }
+          errors << "#{path}.count: must be a number to pick at random" if @flags["random"] && @count == "any"
+          @reveal = Mechanics.fetch_param(params, :reveal)
+          errors << "#{path}.reveal: must be one of #{REVEAL.join(", ")}" unless @reveal.nil? || REVEAL.include?(@reveal)
+          @lists = parse_lists(params, errors, path, LISTS)
+        end
+
+        def parse_from(raw, errors, path)
+          zone = raw.is_a?(Hash) && raw.size == 1 && ZONES.include?(raw.keys.first.to_s) ? raw.keys.first.to_s : nil
+          inner = zone ? raw.values.first : raw
+          return [zone, nil] if inner.nil? && (errors << "#{path}.from: required")
+
+          [zone, Selector.build(inner, errors, "#{path}.from#{".#{zone}" if zone}", targets_count: @targets_count,
+                                                                                    results_count: @results_count)]
+        end
+
+        def nested_effects = @lists.values.flatten
+
+        def to_s
+          many = count == "any" ? "any number of" : "#{"up to " if @optional}#{count}"
+          "choose #{many} #{spec}#{" at random" if @flags["random"]} from #{"the #{@from_zone} of " if @from_zone}#{@from} " \
+            "→ #{put.tr("_", " ")}"
+        end
+
+        # CR 118.3: as the optional part of a "may", the full number of cards must be available.
+        def possible?(engine, ctx) = pool(engine, ctx).size >= (count == "any" ? 1 : count)
+
+        def run(engine, ctx, locals)
+          return :done unless locals["asked"] || locals.key?("chose") || condition.nil? || condition.true?(engine, ctx)
+
+          unless locals.key?("chose")
+            show!(engine, ctx, locals)
+            chosen = picked(engine, ctx, locals)
+            choices = @flags["random"] || stop?(locals, chosen) ? [] : choices(engine, ctx, chosen)
+            return ask(engine, locals, ctx.controller, "Choose #{spec}", choices) unless choices.empty?
+
+            return :wait if put == "battlefield" && engine.ask_entering_choices!(locals, chosen.map { [it, ctx.controller] }) == :wait
+
+            locals["chose"] = !perform!(engine, ctx, chosen, locals).empty?
+            locals["next"] = 0
+          end
+          run_list(engine, ctx, locals, @lists[locals["chose"] ? "then" : "otherwise"])
+        end
+
+        private
+
+        # The cards chosen so far, or picked at random once (as in CR 701.9b, through the game's RNG).
+        def picked(engine, ctx, locals)
+          return answers(locals).select { it["type"] == "choose" }.map { it["object"] } unless @flags["random"]
+
+          locals["picked"] ||= engine.state.rng.shuffle!(pool(engine, ctx)).first(count)
+        end
+
+        # The cards to choose from, in a stable order.
+        def pool(engine, ctx)
+          refs = set(engine, ctx)
+          refs.select { (obj = engine.state.objects[it]) && spec.match?(engine, obj, ctx) }
+        end
+
+        def set(engine, ctx)
+          refs = @from.resolve(engine, ctx)
+          return refs.select { engine.state.objects.key?(it) } unless @from_zone
+
+          refs.filter_map { Filters.player_index(engine, it) }.flat_map { engine.player(it).public_send(@from_zone) }
+        end
+
+        # Looking at or revealing the whole set happens once, before the choice (CR 701.20a, 701.20e).
+        def show!(engine, ctx, locals)
+          return if locals["shown"]
+
+          locals["shown"] = true
+          ids = set(engine, ctx)
+          if @reveal == "all"
+            ids.group_by { engine.object(it).owner }.each_value { engine.reveal!(engine.object(it.first).owner, it) }
+          elsif @flags["look"]
+            ids.group_by { engine.object(it).owner }.each { |owner, list| engine.look_at!(ctx.controller, owner, list) }
+          end
+        end
+
+        def stop?(locals, chosen)
+          answers(locals).any? { it["type"] == "done" } || (count != "any" && chosen.size >= count)
+        end
+
+        def choices(engine, ctx, chosen)
+          ids = pool(engine, ctx) - chosen
+          options = ids.map { { "type" => "choose", "object" => it } }
+          return options if options.empty?
+
+          options << { "type" => "done" } if @optional || count == "any"
+          options
+        end
+
+        def perform!(engine, ctx, chosen, locals)
+          engine.reveal!(ctx.controller, chosen) if @reveal == "chosen"
+          return enter!(engine, ctx, chosen, locals) if put == "battlefield"
+
+          chosen.filter_map { move(engine, ctx, it) }
+        end
+
+        # CR 614.12a: their "as this enters" choices were made first; they enter at the same time.
+        def enter!(engine, ctx, chosen, locals)
+          enters = @flags["tapped"] ? { "tapped" => true } : nil
+          engine.enter_battlefield!(locals, chosen.map { [it, ctx.controller, enters] }, reason: "put")
+        end
+
+        def move(engine, ctx, id)
+          case put
+          when "library_top", "library_bottom"
+            engine.move!(id, :library, reason: "put", position: put == "library_top" ? :top : :bottom)
+          else
+            fresh = engine.move!(id, put.to_sym, reason: put == "graveyard" ? "put" : put)
+            engine.link_exiled!(ctx.source, fresh.id) if fresh && @flags["link"]
+            fresh
+          end
+        end
+      end
+    end
+  end
+end