enjine 0.1.0

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Put permanents or cards on top or bottom of their owners' libraries (CR 401.4); with
+      # `position: "owner_choice"` each owner chooses top or bottom.
+      class PutInLibrary < ChoiceEffect
+        POSITIONS = %w[top bottom owner_choice].freeze
+
+        primitive :effect, :put_in_library,
+                  description: "Put each referenced permanent, or card in a graveyard or exile, into its owner's " \
+                               "library: on the `top` or `bottom`, or (`owner_choice`) where its owner chooses.",
+                  rules: %w[401.4 400.7 608.2b],
+                  params: { "to" => "selector", "position" => POSITIONS.join(" | ") },
+                  example: { "put_in_library" => { "to" => { "target" => 0 }, "position" => "bottom" } }
+
+        FROM = %i[battlefield graveyard exile].freeze
+
+        attr_reader :position
+
+        def self.keys = %w[to position if]
+
+        def setup(params, errors, path)
+          @position = Mechanics.fetch_param(params, :position).to_s
+          errors << "#{path}.position: must be one of #{POSITIONS.join(", ")}" unless POSITIONS.include?(@position)
+        end
+
+        def to_s = "put into its owner's library (#{position.tr("_", " ")}) → #{to}"
+
+        def run(engine, ctx, locals)
+          return :done unless locals["asked"] || locals.key?("refs") || condition.nil? || condition.true?(engine, ctx)
+
+          refs = (locals["refs"] ||= movable(engine, ctx))
+          done = (locals["done"] ||= 0)
+          while (id = refs[done])
+            where = position
+            if where == "owner_choice"
+              answer = answers(locals)[done] or return ask_owner(engine, locals, id)
+              where = answer["type"]
+            end
+            Linked.remember!(engine, ctx, id)
+            engine.move!(id, :library, reason: "put", position: where.to_sym)
+            locals["done"] = done += 1
+          end
+          :done
+        end
+
+        private
+
+        def movable(engine, ctx)
+          refs(engine, ctx).select { FROM.include?(engine.state.objects[it]&.zone) }
+        end
+
+        def ask_owner(engine, locals, id)
+          obj = engine.object(id)
+          ask(engine, locals, obj.owner, "Put #{engine.chars(obj).name} on the top or the bottom of your library?",
+              [{ "type" => "top", "object" => id }, { "type" => "bottom", "object" => id }])
+        end
+      end
+
+      # Shuffling cards into their owners' libraries (CR 701.24c): each owner shuffles their library even
+      # if none of the cards is still where it was.
+      class ShuffleIntoLibrary < Effect
+        primitive :effect, :shuffle_into_library,
+                  description: "Put each referenced card (in a graveyard or exile) or permanent into its owner's " \
+                               "library; each of those owners shuffles their library.",
+                  rules: %w[701.24a 701.24c],
+                  params: { "to" => "selector" },
+                  example: { "shuffle_into_library" => { "to" => { "target" => 0 } } }
+
+        def self.keys = %w[to if]
+
+        def apply(engine, ctx)
+          owners = []
+          refs(engine, ctx).each do |id|
+            obj = engine.state.objects[id]
+            next unless obj && PutInLibrary::FROM.include?(obj.zone) # abilities are on the stack, players aren't objects
+
+            owners << obj.owner
+            engine.move!(id, :library, reason: "shuffle")
+          end
+          owners.uniq.sort.each { engine.shuffle_library!(it) }
+        end
+      end
+
+      # Shuffle a library (CR 701.24a).
+      class ShuffleLibrary < Effect
+        primitive :effect, :shuffle_library, description: "Each referenced player shuffles their library (default: you).",
+                                             rules: %w[701.24a], params: { "to" => "selector" },
+                                             example: { "shuffle_library" => {} }
+        def self.keys = %w[to if]
+        def self.default_to = "you"
+        def apply(engine, ctx) = players(engine, ctx).each { engine.shuffle_library!(it) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "sacrifice"
+
+module Enjine
+  module Mechanics
+    module Effects
+      # "Return a land you control to its owner's hand": like sacrifice_choice, each referenced player
+      # chooses permanents they control matching `filter` (a choice, not a target), in turn order starting
+      # with the active player (CR 101.4); then all of them are put into their owners' hands at once.
+      class ReturnChoice < SacrificeChoice
+        primitive :effect, :return_choice,
+                  description: "Each referenced player (default: you) returns `count` (default 1; \"any\": any number) " \
+                               "permanents they control matching `filter` to their owners' hands, chosen by them in " \
+                               "turn order starting with the active player (not targeted); all move at once.",
+                  rules: %w[101.4 400.7 608.2c],
+                  params: { "filter" => "a filter, e.g. \"land\"", "count" => "integer or \"any\"",
+                            "to" => "selector of players" },
+                  example: { "return_choice" => { "filter" => "land" } }
+
+        def finish!(engine, id) = engine.move!(id, :hand, reason: "return")
+        def choosable?(_engine, obj, index) = obj.zone == :battlefield && obj.controller == index
+        def verb = "return"
+
+        def to_s = "#{to} returns #{count == "any" ? "any number of" : count} #{words} of their choice to its owner's hand"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Puts cards from exile or a graveyard onto the battlefield ("return that card to the
+      # battlefield under its owner's control"). Usually aimed at {"result": n}: a flicker is
+      # `exile` followed by `return_to_battlefield` of the exile's result.
+      class ReturnToBattlefield < Effect
+        UNDER = %w[owner you].freeze
+        ZONES = %i[exile graveyard].freeze
+
+        primitive :effect, :return_to_battlefield,
+                  description: "Put each referenced card that is in exile or a graveyard onto the battlefield under its " \
+                               "owner's control (`under: \"you\"`: under the controller's), tapped if `tapped: true`. " \
+                               "A card that is no longer in the zone it was expected in, or isn't a permanent card, " \
+                               "stays where it is. `transformed: true`: it enters with its back face up; a card that " \
+                               "isn't double-faced, or whose back face isn't a permanent, stays where it is.",
+                  rules: %w[400.7 400.4a 110.2 111.8 603.7c 614.1c 122.6 712.11a 712.11b],
+                  params: { "to" => "selector (usually {\"result\": n})", "tapped" => "boolean", "transformed" => "boolean",
+                            "under" => UNDER.join(" | "),
+                            "counters" => "{counter name: n}: it enters with these counters (\"with a +1/+1 counter on it\")" },
+                  example: { "return_to_battlefield" => { "to" => { "result" => 0 } } }
+
+        attr_reader :tapped, :under, :counters, :transformed
+
+        def self.keys = %w[to tapped under counters transformed if]
+
+        def setup(params, errors, path)
+          @tapped = Mechanics.fetch_param(params, :tapped) == true
+          @transformed = Mechanics.fetch_param(params, :transformed) == true
+          @under = Mechanics.fetch_param(params, :under) || "owner"
+          errors << "#{path}.under: must be one of #{UNDER.join(", ")}" unless UNDER.include?(@under)
+          @counters = parse_counters(Mechanics.fetch_param(params, :counters) || {}, errors, "#{path}.counters")
+        end
+
+        def parse_counters(raw, errors, path)
+          return (errors << "#{path}: must be an object of counter name => count") && {} unless raw.is_a?(Hash)
+
+          raw.to_h do |name, n|
+            kind = Counters.parse(name.to_s, errors, "#{path}.#{name}")
+            errors << "#{path}.#{name}: must be a positive integer" unless n.is_a?(Integer) && n.positive?
+            [kind, n]
+          end.freeze
+        end
+
+        def to_s
+          extra = counters.map { |kind, n| " with #{n} #{kind} counter(s)" }.join
+          status = "#{" tapped" if tapped}#{" transformed" if transformed}"
+          "return to the battlefield#{status}#{" under your control" if under == "you"}#{extra} → #{to}"
+        end
+
+        # CR 614.12a: each card's "as this enters" choice is made first (asked in turn), then they all
+        # enter at the same time. The cards are fixed as the effect starts.
+        def run(engine, ctx, locals)
+          return :done unless locals.key?("cards") || condition.nil? || condition.true?(engine, ctx)
+
+          entries = (locals["cards"] ||= cards(engine, ctx).map { [it, under == "you" ? ctx.controller : engine.object(it).owner] })
+          entries = entries.select { engine.state.objects.key?(it[0]) }
+          return :wait if engine.ask_entering_choices!(locals, entries) == :wait
+
+          enters = { "tapped" => tapped || nil, "counters" => counters.empty? ? nil : counters.dup,
+                     "face" => transformed ? 1 : nil }.compact
+          engine.enter_battlefield!(locals, entries.map { [*it, enters.empty? ? nil : enters] }, reason: "return")
+          :done
+        end
+
+        # CR 400.4a: an instant or sorcery card can't enter the battlefield. CR 111.8: a token that
+        # has left the battlefield can't come back (it ceases to exist at the next SBA check).
+        def cards(engine, ctx)
+          refs(engine, ctx).select do |id|
+            obj = engine.state.objects[id]
+            obj && ZONES.include?(obj.zone) && !engine.token?(obj) &&
+              !(engine.chars(obj).types - %i[instant sorcery]).empty? && (!transformed || engine.can_enter_face?(obj, 1))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Return to its owner's hand (CR 400.6).
+      class ReturnToHand < ZoneEffect
+        primitive :effect, :return_to_hand,
+                  description: "Return each referenced permanent, spell (\"return target spell to its owner's hand\"), or " \
+                               "card in a graveyard or exile (\"target creature " \
+                               "card from your graveyard\"), to its owner's hand.",
+                  rules: %w[400.6 404.1 608.2b], params: { "to" => "selector" },
+                  example: { "return_to_hand" => { "to" => { "target" => 0 } } }
+        def self.zone = :hand
+        def self.reason = "bounce"
+        def self.from_zones = %i[battlefield graveyard exile stack]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Rolling dice (CR 706): you roll `amount` dice with `sides` sides each (CR 706.1a), each result from 1 to
+      # `sides` at random (the game's random number generator). The total of the results is the effect's amount
+      # for later effects ({"this_way": n}), so a results table is a list of effects with `if` comparing it
+      # (CR 706.3a).
+      class RollDice < Effect
+        primitive :effect, :roll_dice,
+                  description: "You roll `amount` dice (default 1) with `sides` sides (default 6). The total of the " \
+                               "results is this effect's amount: {\"this_way\": n} in later effects and conditions " \
+                               "(a results table is effects with an `if` on it).",
+                  rules: %w[706.1 706.1a 706.2 706.3a 608.2c],
+                  params: { "sides" => "integer >= 2 (default 6)", "amount" => "amount (default 1)" },
+                  example: { "roll_dice" => { "sides" => 20 } }
+
+        def self.keys = %w[sides amount if]
+        def self.default_to = "you"
+
+        def initialize(to:, params:, errors:, path:, targets_count: 0, results_count: 0)
+          params = params.transform_keys(&:to_s)
+          params["amount"] = 1 unless params.key?("amount")
+          super
+        end
+
+        def setup(params, errors, path)
+          @sides = Mechanics.fetch_param(params, :sides) || 6
+          errors << "#{path}.sides: must be an integer >= 2" unless @sides.is_a?(Integer) && @sides >= 2
+        end
+
+        def to_s = "roll #{amount == 1 ? "a" : amount} d#{@sides}"
+
+        def apply(engine, ctx)
+          amount_for(engine, ctx).times do
+            result = engine.state.rng.rand(@sides) + 1 # CR 706.2: the natural result
+            engine.emit Events::RolledDie.new(player: engine.name(ctx.controller), sides: @sides, result: result)
+            engine.record_amount!(result)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Sacrifice permanents (CR 701.21): "sacrifice it at the beginning of the next end step".
+      class Sacrifice < Effect
+        primitive :effect, :sacrifice,
+                  description: "The controller sacrifices each referenced permanent they control (it goes to its " \
+                               "owner's graveyard; it isn't destroyed, so indestructible doesn't stop it).",
+                  rules: %w[701.21a],
+                  params: { "to" => "selector" },
+                  example: { "sacrifice" => { "to" => { "result" => 0 } } }
+
+        def self.keys = %w[to if]
+
+        def apply(engine, ctx) = mine(engine, ctx).each { engine.move!(it, :graveyard, reason: "sacrifice") }
+
+        # CR 701.21a: a player can't sacrifice a permanent they don't control.
+        def mine(engine, ctx) = objects(engine, ctx).select { engine.can_sacrifice?(engine.object(it), ctx.controller) }
+        def possible?(engine, ctx) = !mine(engine, ctx).empty?
+      end
+
+      # Edicts and sacrifices of the player's choice: each referenced player chooses a number of permanents
+      # they control matching `filter`, in APNAP order (CR 101.4); then all of them are sacrificed at the
+      # same time (CR 701.21a).
+      class SacrificeChoice < ChoiceEffect
+        primitive :effect, :sacrifice_choice,
+                  description: "Each referenced player (default: you) sacrifices `count` (default 1; \"any\": any number) " \
+                               "permanents they control matching `filter`, chosen by them in turn order starting with " \
+                               "the active player; all are sacrificed at once. The `filter`'s `controller` and `other` " \
+                               "restrictions are relative to the effect's controller and source.",
+                  rules: %w[701.21a 101.4 118.3],
+                  params: { "filter" => "a filter, e.g. {\"creature\": {\"token\": false}}", "count" => "integer or \"any\"",
+                            "to" => "selector of players" },
+                  example: { "sacrifice_choice" => { "filter" => "creature", "to" => "each_opponent" } }
+
+        attr_reader :filter, :count
+
+        def self.keys = %w[filter count to if]
+        def self.default_to = "you"
+
+        def setup(params, errors, path)
+          raw = Mechanics.fetch_param(params, :filter)
+          errors << "#{path}.filter: required" if raw.nil?
+          @filter = raw && Mechanics.build_entry(:filter, raw, errors, "#{path}.filter")
+          @count = Mechanics.fetch_param(params, :count) || 1
+          return if @count == "any" || (@count.is_a?(Integer) && @count.positive?)
+
+          errors << "#{path}.count: must be a positive integer or \"any\""
+        end
+
+        def to_s = "#{to} sacrifices #{count == "any" ? "any number of" : count} #{words} of their choice"
+        def words = filter.is_a?(Class) ? filter.primitive_name.tr("_", " ") : filter.to_s
+
+        # CR 118.3: as the optional part of a "may", there must be enough permanents to sacrifice.
+        def possible?(engine, ctx)
+          players(engine, ctx).all? { candidates(engine, ctx, it, []).size >= (count == "any" ? 0 : count) }
+        end
+
+        def run(engine, ctx, locals)
+          return :done unless locals["asked"] || locals.key?("queue") || condition.nil? || condition.true?(engine, ctx)
+
+          queue = (locals["queue"] ||= apnap(engine, players(engine, ctx)))
+          picks = (locals["picks"] ||= [])
+          take_answers(locals, picks)
+          while (index = queue.first)
+            mine = picks.select { it[0] == index }.map { it[1] }
+            ask_for = remaining(engine, ctx, locals, index, mine)
+            return ask_for if ask_for == :wait
+
+            queue.shift
+          end
+          picks.each { finish!(engine, it[1]) }
+          :done
+        end
+
+        # Hooks for Effects::ReturnChoice: what happens to the chosen permanents, who may choose one.
+        def finish!(engine, id) = engine.move!(id, :graveyard, reason: "sacrifice")
+        def choosable?(engine, obj, index) = engine.can_sacrifice?(obj, index)
+        def verb = "sacrifice"
+
+        private
+
+        def apnap(engine, indexes) = engine.turn_order_from_active.select { indexes.include?(it) }
+
+        # Permanents `index` controls that match the filter, not yet chosen.
+        def candidates(engine, ctx, index, chosen)
+          filter.candidates_for(engine, ctx.controller, ctx.source)
+                .select { engine.state.objects.key?(it) && choosable?(engine, engine.object(it), index) } - chosen
+        end
+
+        # Asks `index` for their next permanent, or picks automatically when there is no real choice.
+        def remaining(engine, ctx, locals, index, mine)
+          left = candidates(engine, ctx, index, mine)
+          return :next if left.empty? || locals["stopped"] == index || (count != "any" && mine.size >= count)
+
+          if count != "any" && left.size <= count - mine.size
+            left.each { locals["picks"] << [index, it] }
+            return :next
+          end
+          choices = left.map { { "type" => verb, "object" => it } }
+          choices << { "type" => "done" } if count == "any"
+          locals["chooser"] = index
+          ask(engine, locals, index, "#{verb.capitalize} #{words}", choices)
+        end
+
+        def take_answers(locals, picks)
+          (locals["taken"] ||= 0).upto(answers(locals).size - 1) do |i|
+            answer = answers(locals)[i]
+            answer["type"] == "done" ? locals["stopped"] = locals["chooser"] : picks << [locals["chooser"], answer["object"]]
+          end
+          locals["taken"] = answers(locals).size
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Scry N / surveil N (CR 701.22, 701.25): look at the top N, put each on the top or away
+      # (bottom / graveyard), then order the ones kept on top.
+      class LookAtTop < ChoiceEffect
+        def self.default_to = "you"
+        def self.away = raise(NotImplementedError)
+
+        def run(engine, ctx, locals)
+          index = ctx.controller
+          locals["amount"] ||= amount_for(engine, ctx)
+          seen = (locals["seen"] ||= engine.player(index).library.first(locals["amount"]))
+          decided = answers(locals).reject { it["type"] == "order" }
+          if decided.size < seen.size
+            card = seen[decided.size]
+            return ask(engine, locals, index, "#{self.class.primitive_name}: keep on top or #{self.class.away}?",
+                       [{ "type" => "top", "object" => card }, { "type" => self.class.away, "object" => card }])
+          end
+          tops = decided.select { it["type"] == "top" }.map { it["object"] }
+          order = answers(locals).select { it["type"] == "order" }.map { it["object"] }
+          if tops.size - order.size > 1
+            return ask(engine, locals, index, "Choose the next card to put on top (the first chosen ends up on top)",
+                       (tops - order).map { { "type" => "order", "object" => it } })
+          end
+          place(engine, index, order + (tops - order), decided.reject { it["type"] == "top" }.map { it["object"] })
+          performed!(engine, index, locals["amount"])
+          :done
+        end
+
+        # CR 701.22b, 701.25c-d: scry or surveil N > 0 is an event once it's complete, even if the library
+        # had fewer cards; "whenever you scry" triggers on it.
+        def performed!(engine, index, amount)
+          return unless amount.positive?
+
+          engine.emit Events::KeywordAction.new(player: engine.name(index), action: self.class.primitive_name.to_s,
+                                                amount: amount)
+        end
+      end
+
+      # Scry N (CR 701.22).
+      class Scry < LookAtTop
+        primitive :effect, :scry, description: "Look at the top `amount` cards of your library; put any number on the " \
+                                               "bottom and the rest on top in any order.",
+                                  rules: %w[701.22a], params: { "amount" => "integer" }, example: { "scry" => { "amount" => 2 } }
+        def self.away = "bottom"
+
+        def place(engine, index, tops, bottoms)
+          library = engine.player(index).library
+          library.replace(tops + (library - tops - bottoms) + bottoms)
+          engine.emit Events::LibraryReordered.new(player: engine.name(index), top: tops.size, bottom: bottoms.size)
+        end
+      end
+
+      # Surveil N (CR 701.25).
+      class Surveil < LookAtTop
+        primitive :effect, :surveil, description: "Look at the top `amount` cards of your library; put any number into " \
+                                                  "your graveyard and the rest on top in any order.",
+                                     rules: %w[701.25a], params: { "amount" => "integer" },
+                                     example: { "surveil" => { "amount" => 2 } }
+        def self.away = "graveyard"
+
+        def place(engine, index, tops, gone)
+          library = engine.player(index).library
+          library.replace(tops + (library - tops))
+          gone.each { engine.move!(it, :graveyard, reason: "surveil") }
+          engine.emit Events::LibraryReordered.new(player: engine.name(index), top: tops.size, bottom: 0)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "library"
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Search your library (CR 701.23), optionally reveal what was found (CR 701.20a), put it
+      # into your hand or onto the battlefield, then shuffle (CR 701.24).
+      #
+      # The searcher picks one card at a time. Copies of the same card in a library are
+      # interchangeable, so each distinct card is offered once. Only the searcher sees the
+      # choices; other players see the reveal (when the effect reveals), the zone change
+      # as their zone rules allow, and the shuffle.
+      class SearchLibrary < ChoiceEffect
+        include EntersBattlefield # effects/library.rb
+
+        primitive :effect, :search_library,
+                  description: "Search your library for up to `count` cards matching `for`, then put them into your " \
+                               "hand (or onto the battlefield, tapped if `tapped`, with `counters`) and shuffle. With a " \
+                               "stated quality you may find fewer (or none); a search for just \"a card\" must find one " \
+                               "if it can. `reveal` shows the found cards to every player. `searcher` names another " \
+                               "player who searches their own library (e.g. {\"controller_of\": {\"target\": 0}}); " \
+                               "`may: true` lets the searcher decline (then nothing is shuffled). `different_names: true`: " \
+                               "the cards found must all have different names (\"basic land cards with different names\").",
+                  rules: %w[701.23a 701.23b 701.23d 701.23e 701.20a 701.24a 701.24b 118.12 110.2a],
+                  params: { "for" => "card spec: \"card\" (default), {\"types\"|\"subtypes\"|\"supertypes\": [...], " \
+                                     "\"name\": \"...\"} or {\"any_of\": [spec, ...]}",
+                            "count" => "integer (default 1), \"any\" (any number), \"x\" or an amount (\"up to that many\")",
+                            "put" => "\"hand\" (default) or \"battlefield\"",
+                            "tapped" => "true: the cards enter tapped (with put: battlefield)",
+                            "counters" => "{counter name: n}: the cards enter with these counters (with put: battlefield)",
+                            "reveal" => "true: reveal the found cards",
+                            "searcher" => "selector of the searching player (default \"you\")",
+                            "may" => "true: the searcher may choose not to search",
+                            "different_names" => "true: each card found has a different name" },
+                  example: { "search_library" => { "for" => { "supertypes" => ["basic"], "types" => ["land"] },
+                                                   "reveal" => true } }
+
+        ZONES = %w[hand battlefield].freeze
+
+        attr_reader :spec, :count, :put, :tapped, :reveal
+
+        def self.keys = %w[for count put tapped counters reveal searcher may different_names if]
+        def self.default_to = "you"
+
+        def setup(params, errors, path)
+          @spec = CardSpec.build(Mechanics.fetch_param(params, :for), errors, "#{path}.for")
+          @count = parse_count(Mechanics.fetch_param(params, :count) || 1, errors, path)
+          @put = (Mechanics.fetch_param(params, :put) || "hand").to_s
+          errors << "#{path}.put: must be one of #{ZONES.join(", ")}" unless ZONES.include?(@put)
+          @tapped = Mechanics.flag_param(params, :tapped, errors, path)
+          @reveal = Mechanics.flag_param(params, :reveal, errors, path)
+          @may = Mechanics.flag_param(params, :may, errors, path)
+          @different_names = Mechanics.flag_param(params, :different_names, errors, path)
+          errors << "#{path}.tapped: only cards put onto the battlefield can enter tapped" if @tapped && @put != "battlefield"
+          @counters = parse_counters(Mechanics.fetch_param(params, :counters), errors, path)
+          raw = Mechanics.fetch_param(params, :searcher) || "you"
+          @searcher = Selector.build(raw, errors, "#{path}.searcher", targets_count: @targets_count, results_count: @results_count)
+        end
+
+        def parse_count(raw, errors, path)
+          return raw if raw == "any" || (raw.is_a?(Integer) && raw.positive?)
+          return Linked.amount(raw, errors, "#{path}.count", @targets_count, @results_count) if raw.is_a?(Hash) || raw == "x"
+
+          errors << "#{path}.count: must be a positive integer, \"any\" or an amount"
+          1
+        end
+
+        def parse_counters(raw, errors, path)
+          return {} if raw.nil?
+
+          unless raw.is_a?(Hash) && raw.all? { |name, n| Counters.valid?(Counters.normalize(name.to_s)) && n.is_a?(Integer) && n.positive? }
+            errors << "#{path}.counters: must be {counter name: positive integer}"
+            return {}
+          end
+          errors << "#{path}.counters: only cards put onto the battlefield enter with counters" if @put != "battlefield"
+          raw.to_h { |name, n| [Counters.normalize(name.to_s), n] }
+        end
+
+        def to_s
+          many = if count == "any" then "any number of"
+                 elsif count.is_a?(Integer) then "up to #{count}"
+                 else "up to #{count} (computed)"
+                 end
+          "search your library for #{many} #{spec}#{", reveal" if reveal} → #{put}#{" tapped" if tapped}, shuffle"
+        end
+
+        def run(engine, ctx, locals)
+          return :done unless locals["asked"] || condition.nil? || condition.true?(engine, ctx)
+
+          index = (locals["searcher"] ||= [searcher(engine, ctx)]).first
+          return :done if index.nil?
+
+          if @may && !locals["search"]
+            answer = answers(locals).first or return ask(engine, locals, index, "Search your library?",
+                                                         [{ "type" => "search" }, { "type" => "decline" }])
+            return :done if answer["type"] == "decline"
+
+            locals["search"] = true
+          end
+          found = answers(locals).select { it["type"] == "find" }.map { it["object"] }
+          unless stop?(engine, ctx, locals, found)
+            choices = candidates(engine, index, found)
+            return ask(engine, locals, index, "Search your library (#{spec}): find a card", choices) unless choices.empty?
+          end
+          return :wait if entering_choices?(engine, index, locals, found)
+
+          finish!(engine, index, found, locals)
+          :done
+        end
+
+        private
+
+        def searcher(engine, ctx) = @searcher.resolve(engine, ctx).filter_map { Filters.player_index(engine, it) }.first
+
+        def limit(engine, ctx, locals)
+          return count unless count.respond_to?(:value)
+
+          locals["limit"] ||= count.value(engine, ctx)
+        end
+
+        def stop?(engine, ctx, locals, found)
+          wanted = limit(engine, ctx, locals)
+          answers(locals).any? { it["type"] == "done" } || (wanted != "any" && found.size >= wanted)
+        end
+
+        # One option per distinct matching card (CR 701.23a); "done" stops looking unless the
+        # search is for just a quantity of cards (CR 701.23b, 701.23d).
+        def candidates(engine, index, found)
+          names = @different_names ? found.map { engine.chars(it).name } : []
+          ids = (engine.player(index).library - found).sort.select do
+            spec.match?(engine, engine.object(it)) && !names.include?(engine.chars(it).name)
+          end
+          choices = ids.uniq { engine.object(it).card }.map { { "type" => "find", "object" => it } }
+          return choices if choices.empty? || (spec.any? && count != "any")
+
+          choices << { "type" => "done" }
+        end
+
+        def finish!(engine, index, found, locals)
+          if reveal && put == "hand"
+            found.each do |id|
+              engine.emit Events::CardRevealed.new(player: engine.name(index), object: id, card: engine.object(id).card)
+            end
+          end
+          enters = {}
+          enters["tapped"] = true if tapped
+          enters["counters"] = @counters.dup unless @counters.empty?
+          put_cards!(engine, locals, found, index, reason: "search", enters: enters.empty? ? nil : enters)
+          engine.shuffle_library!(index) # CR 701.24b: the found cards have left; the rest is shuffled
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Tap permanents (CR 701.26).
+      class TapEffect < Effect
+        primitive :effect, :tap, description: "Tap each referenced permanent.", rules: %w[701.26a],
+                                 params: { "to" => "selector" }, example: { "tap" => { "to" => { "target" => 0 } } }
+        def self.keys = %w[to if]
+        def apply(engine, ctx) = objects(engine, ctx).each { engine.tap!(engine.object(it)) unless engine.object(it).tapped }
+      end
+
+      # Untap permanents (CR 701.26).
+      class UntapEffect < Effect
+        primitive :effect, :untap, description: "Untap each referenced permanent.", rules: %w[701.26b],
+                                   params: { "to" => "selector" }, example: { "untap" => { "to" => "self" } }
+        def self.keys = %w[to if]
+        def apply(engine, ctx) = objects(engine, ctx).each { engine.untap!(engine.object(it)) }
+      end
+    end
+  end
+end