enjine 0.1.0

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

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Cards an effect puts onto the battlefield under one player's control: each one's "as this enters"
+      # choice is made first, one card at a time, then they all enter at once (CR 614.12, 614.12a). The
+      # including effect has a `put` zone; other zones move one card at a time as before.
+      module EntersBattlefield
+        # Whether a choice is now pending (the effect returns :wait and asks again on resume).
+        def entering_choices?(engine, controller, locals, ids)
+          @put.to_s == "battlefield" && engine.ask_entering_choices!(locals, ids.map { [it, controller] }) == :wait
+        end
+
+        # Moves the cards to `@put`; onto the battlefield, under `controller`'s control and all at once.
+        def put_cards!(engine, locals, ids, controller, reason:, enters: nil)
+          return engine.enter_battlefield!(locals, ids.map { [it, controller, enters] }, reason: reason) if @put.to_s == "battlefield"
+
+          ids.each { engine.move!(it, @put.to_sym, reason: reason, enters: enters) }
+        end
+      end
+
+      # Where the cards a library effect didn't take go: the bottom of the library in a random order or in
+      # an order the player chooses (CR 401.4), or the graveyard.
+      module RestOfCards
+        REST = %w[bottom_random bottom_any graveyard].freeze
+
+        def parse_rest(params, errors, path)
+          rest = (Mechanics.fetch_param(params, :rest) || "bottom_random").to_s
+          errors << "#{path}.rest: must be one of #{REST.join(", ")}" unless REST.include?(rest)
+          rest
+        end
+
+        # Asks for the bottom order one card at a time ("the first chosen goes on the bottom first").
+        # Returns :wait while asking, else places the cards.
+        def place_rest(engine, locals, index, rest_ids)
+          if @rest == "graveyard"
+            engine.unrecorded { rest_ids.each { engine.move!(it, :graveyard, reason: "put") } }
+            return :done
+          end
+          if @rest == "bottom_any"
+            order = answers(locals).select { it["type"] == "bottom" }.map { it["object"] }
+            left = rest_ids - order
+            if left.size > 1
+              return ask(engine, locals, index, "Choose the next card to put on the bottom of your library",
+                         left.map { { "type" => "bottom", "object" => it } })
+            end
+            rest_ids = order + left
+          end
+          engine.put_on_bottom!(index, rest_ids, random: @rest == "bottom_random")
+          :done
+        end
+      end
+
+      # Look at (or reveal) the top N cards of your library, take the ones matching a card spec (all, a
+      # number, or up to a number), then put the rest away (CR 701.20a, 701.20e, 401.4).
+      class Dig < ChoiceEffect
+        include RestOfCards
+        include EntersBattlefield
+
+        PUT = %w[hand battlefield graveyard exile].freeze
+        REVEAL = %w[none chosen all].freeze
+
+        primitive :effect, :dig,
+                  description: "Look at the top `amount` cards of your library (`reveal: \"all\"`: reveal them). Take " \
+                               "`count` (default 1; \"all\": every matching card, no choice; \"any\": any number) " \
+                               "cards matching `for` and put them into `put` (`tapped` onto the battlefield); " \
+                               "`optional`: you may take fewer. `reveal: \"chosen\"` reveals the cards taken. The rest go " \
+                               "to `rest`: \"bottom_random\" (default), \"bottom_any\" (in an order you choose) or \"graveyard\". " \
+                               "`put: \"exile\"` takes `face_down: true` (only you may look at them) and `link: true` " \
+                               "(exiled with the source, CR 607.2a: hideaway).",
+                  rules: %w[701.20a 701.20e 401.4 400.7j 406.3 607.2a],
+                  params: { "amount" => "amount (how many cards)", "for" => "card spec (default any card)",
+                            "count" => "integer, \"all\" or \"any\"", "optional" => "boolean", "put" => PUT.join(" | "),
+                            "tapped" => "boolean", "reveal" => REVEAL.join(" | "), "rest" => RestOfCards::REST.join(" | "),
+                            "face_down" => "boolean (put exile)", "link" => "boolean (put exile)" },
+                  example: { "dig" => { "amount" => 6, "for" => { "types" => ["artifact"] }, "optional" => true,
+                                        "reveal" => "chosen", "put" => "hand" } }
+
+        attr_reader :spec, :count, :put
+
+        def self.keys = %w[amount for count optional put tapped reveal rest face_down link if]
+        def self.default_to = "you"
+
+        def setup(params, errors, path)
+          @spec = CardSpec.build(Mechanics.fetch_param(params, :for), errors, "#{path}.for")
+          @count = Mechanics.fetch_param(params, :count) || 1
+          unless %w[all any].include?(@count) || (@count.is_a?(Integer) && @count.positive?)
+            errors << "#{path}.count: must be a positive integer, \"all\" or \"any\""
+          end
+          @optional = Mechanics.flag_param(params, "optional", errors, path)
+          @put = (Mechanics.fetch_param(params, :put) || "hand").to_s
+          errors << "#{path}.put: must be one of #{PUT.join(", ")}" unless PUT.include?(@put)
+          @tapped = Mechanics.flag_param(params, "tapped", errors, path)
+          @reveal = (Mechanics.fetch_param(params, :reveal) || "none").to_s
+          errors << "#{path}.reveal: must be one of #{REVEAL.join(", ")}" unless REVEAL.include?(@reveal)
+          @rest = parse_rest(params, errors, path)
+          @face_down, @link = %i[face_down link].map { Mechanics.flag_param(params, it, errors, path) }
+          errors << "#{path}: face_down and link need put: \"exile\"" if (@face_down || @link) && @put != "exile"
+        end
+
+        def to_s
+          many = { "all" => "all", "any" => "any number of" }[count] || "#{"up to " if @optional}#{count}"
+          "#{@reveal == "all" ? "reveal" : "look at"} the top #{amount} cards, #{many} #{spec} → #{put}, rest → " \
+            "#{@rest.tr("_", " ")}"
+        end
+
+        def run(engine, ctx, locals)
+          return :done unless locals.key?("seen") || condition.nil? || condition.true?(engine, ctx)
+
+          index = ctx.controller
+          seen = (locals["seen"] ||= first_look(engine, ctx, index))
+          unless locals["taken"]
+            taken = answers(locals).select { it["type"] == "take" }.map { it["object"] }
+            choices = count == "all" ? [] : choices(engine, ctx, seen, taken, locals)
+            return ask(engine, locals, index, "Choose #{spec} to take", choices) unless choices.empty?
+
+            taken = seen.select { spec.match?(engine, engine.object(it), ctx) } if count == "all"
+            return :wait if entering_choices?(engine, ctx.controller, locals, taken)
+
+            take!(engine, ctx, index, taken, locals)
+            locals["taken"] = taken
+          end
+          place_rest(engine, locals, index, seen - locals["taken"])
+        end
+
+        private
+
+        def first_look(engine, ctx, index)
+          seen = engine.player(index).library.first(amount_for(engine, ctx))
+          @reveal == "all" ? engine.reveal!(index, seen) : engine.look_at!(index, index, seen)
+          seen
+        end
+
+        def choices(engine, ctx, seen, taken, locals)
+          return [] if answers(locals).any? { it["type"] == "done" } || (count != "any" && taken.size >= count)
+
+          ids = (seen - taken).select { spec.match?(engine, engine.object(it), ctx) }
+          options = ids.uniq { engine.object(it).card }.map { { "type" => "take", "object" => it } }
+          options << { "type" => "done" } if (@optional || count == "any") && !options.empty?
+          options
+        end
+
+        def take!(engine, ctx, index, taken, locals)
+          engine.reveal!(index, taken) if @reveal == "chosen"
+          return exile!(engine, ctx, index, taken) if @put == "exile"
+
+          put_cards!(engine, locals, taken, ctx.controller, reason: "put", enters: @tapped ? { "tapped" => true } : nil)
+        end
+
+        # CR 406.3, 607.2a: face down (only you may look), linked to the source.
+        def exile!(engine, ctx, index, taken)
+          taken.each do |id|
+            fresh = engine.move!(id, :exile, reason: "exile", face_down: @face_down ? [index] : nil)
+            engine.link_exiled!(ctx.source, fresh.id) if fresh && @link
+          end
+        end
+      end
+
+      # Reveal cards from the top of your library one at a time until N cards matching a spec are revealed;
+      # those go to a zone, the other revealed cards are put away (CR 701.20a, 401.4).
+      class RevealUntil < ChoiceEffect
+        include RestOfCards
+        include EntersBattlefield
+
+        PUT = %w[hand battlefield].freeze
+
+        primitive :effect, :reveal_until,
+                  description: "Reveal cards from the top of your library until `count` (an amount, default 1) cards " \
+                               "matching `for` are revealed (or the library runs out). Put those into `put` " \
+                               "(`tapped` onto the battlefield, under your control) and the rest to `rest` (default " \
+                               "the bottom in a random order).",
+                  rules: %w[701.20a 401.4 400.7j],
+                  params: { "for" => "card spec", "count" => "amount", "put" => PUT.join(" | "), "tapped" => "boolean",
+                            "rest" => RestOfCards::REST.join(" | ") },
+                  example: { "reveal_until" => { "for" => { "types" => ["land"] }, "count" => 2, "put" => "battlefield",
+                                                 "tapped" => true } }
+
+        def self.keys = %w[for count put tapped rest if]
+        def self.default_to = "you"
+
+        def setup(params, errors, path)
+          @spec = CardSpec.build(Mechanics.fetch_param(params, :for), errors, "#{path}.for")
+          @count = Amount.build(Mechanics.fetch_param(params, :count) || 1, errors, "#{path}.count", targets_count: @targets_count)
+          @put = (Mechanics.fetch_param(params, :put) || "hand").to_s
+          errors << "#{path}.put: must be one of #{PUT.join(", ")}" unless PUT.include?(@put)
+          @tapped = Mechanics.flag_param(params, "tapped", errors, path)
+          @rest = parse_rest(params, errors, path)
+        end
+
+        def to_s = "reveal until #{@count} #{@spec} → #{@put}#{" tapped" if @tapped}, rest → #{@rest.tr("_", " ")}"
+
+        def run(engine, ctx, locals)
+          return :done unless locals.key?("found") || condition.nil? || condition.true?(engine, ctx)
+
+          index = ctx.controller
+          unless locals.key?("found")
+            revealed, found = reveal(engine, ctx, index)
+            locals["found"] = found
+            locals["rest"] = revealed - found
+          end
+          unless locals["moved"]
+            return :wait if entering_choices?(engine, index, locals, locals["found"])
+
+            put_cards!(engine, locals, locals["found"], index, reason: "put", enters: @tapped ? { "tapped" => true } : nil)
+            locals["moved"] = true
+          end
+          place_rest(engine, locals, index, locals["rest"])
+        end
+
+        private
+
+        def reveal(engine, ctx, index)
+          wanted = @count.value(engine, ctx)
+          revealed = []
+          found = []
+          engine.player(index).library.each do |id|
+            break if found.size >= wanted
+
+            revealed << id
+            found << id if @spec.match?(engine, engine.object(id), ctx)
+          end
+          engine.reveal!(index, revealed)
+          [revealed, found]
+        end
+      end
+
+      # Exile the top N cards of a library (CR 406.1). What was exiled is the effect's result ({"result": n}),
+      # for later effects of the list (returning the permanent cards among them, permissions to play them);
+      # `link: true` exiles them with the source (CR 607.2a).
+      class ExileTop < Effect
+        primitive :effect, :exile_top,
+                  description: "Each referenced player (default: you) exiles the top `amount` cards of their library " \
+                               "(face up). Later effects name them with {\"result\": n}; `link: true` exiles them with " \
+                               "the source. `face_down: true` exiles them face down: only the `looker` players " \
+                               "(default: you) may look at them.",
+                  rules: %w[406.1 400.7j 607.2a 406.3 406.3a],
+                  params: { "amount" => "amount", "to" => "selector of players", "link" => "boolean",
+                            "face_down" => "boolean", "looker" => "selector of players who may look (default \"you\")" },
+                  example: { "exile_top" => { "amount" => 4 } }
+
+        def self.keys = %w[amount to link face_down looker if]
+        def self.default_to = "you"
+
+        def setup(params, errors, path)
+          @link = Mechanics.flag_param(params, "link", errors, path)
+          @face_down = Mechanics.flag_param(params, :face_down, errors, path)
+          raw = Mechanics.fetch_param(params, :looker)
+          errors << "#{path}.looker: needs face_down: true" if raw && !@face_down
+          @looker = Selector.build(raw || "you", errors, "#{path}.looker", targets_count: @targets_count,
+                                                                           results_count: @results_count)
+        end
+
+        def to_s = @face_down ? super.sub(" → ", " face down → ") : super
+
+        def apply(engine, ctx)
+          n = amount_for(engine, ctx)
+          lookers = @face_down ? @looker.resolve(engine, ctx).filter_map { Filters.player_index(engine, it) } : nil
+          players(engine, ctx).each do |index|
+            engine.player(index).library.first(n).each do |id|
+              fresh = engine.move!(id, :exile, reason: "exile", face_down: lookers)
+              engine.link_exiled!(ctx.source, fresh.id) if fresh && @link
+            end
+          end
+        end
+      end
+
+      # Explore (CR 701.44a): reveal the top card of your library; a land card goes to your hand,
+      # otherwise the exploring permanent gets a +1/+1 counter and you may put the card into your graveyard.
+      class Explore < ChoiceEffect
+        primitive :effect, :explore,
+                  description: "Each referenced permanent explores: its controller reveals the top card of their " \
+                               "library. A land card goes to their hand; otherwise the permanent gets a +1/+1 counter " \
+                               "(if it's still on the battlefield) and they may put the card into their graveyard.",
+                  rules: %w[701.44a 701.44b 701.44c],
+                  params: { "to" => "selector of permanents" },
+                  example: { "explore" => { "to" => "self" } }
+
+        def self.keys = %w[to if]
+
+        def run(engine, ctx, locals)
+          return :done unless locals.key?("queue") || condition.nil? || condition.true?(engine, ctx)
+
+          queue = (locals["queue"] ||= refs(engine, ctx).select { engine.state.objects.key?(it) })
+          while (id = queue.first)
+            return :wait if explore(engine, ctx, locals, id) == :wait
+
+            queue.shift
+            locals.delete("card")
+            locals.delete("answers")
+          end
+          :done
+        end
+
+        private
+
+        # CR 701.44c: a permanent that has left uses its last known controller (here: the effect's controller).
+        def explore(engine, ctx, locals, id)
+          obj = engine.object(id)
+          index = obj.zone == :battlefield ? obj.controller : ctx.controller
+          unless locals.key?("card")
+            locals["card"] = engine.player(index).library.first
+            return land_or_counter(engine, locals, id, index)
+          end
+          answer = answers(locals).first
+          card = locals["card"]
+          engine.move!(card, :graveyard, reason: "explore") if answer["type"] == "graveyard"
+          :done
+        end
+
+        def land_or_counter(engine, locals, id, index)
+          card = locals["card"]
+          engine.reveal!(index, [card]) if card
+          if card && engine.chars(card).land?
+            engine.move!(card, :hand, reason: "explore")
+            return :done
+          end
+          engine.add_counters!(engine.object(id), "+1/+1", 1, by_player: index) if engine.state.battlefield.include?(id)
+          return :done unless card
+
+          ask(engine, locals, index, "Explore: keep the revealed card on top or put it into your graveyard?",
+              [{ "type" => "top", "object" => card }, { "type" => "graveyard", "object" => card }])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Gain life (CR 119.3).
+      class GainLife < Effect
+        primitive :effect, :gain_life, description: "Each referenced player gains `amount` life (default: you).",
+                                       rules: %w[119.3], params: { "amount" => "integer", "to" => "selector" },
+                                       example: { "gain_life" => { "amount" => 3 } }
+        def self.default_to = "you"
+        def apply(engine, ctx) = players(engine, ctx).each { LoseLife.change!(engine, it, amount_for(engine, ctx)) }
+      end
+
+      # Lose life (CR 119.3).
+      class LoseLife < Effect
+        primitive :effect, :lose_life, description: "Each referenced player loses `amount` life. The life lost is " \
+                                                    "recorded for {\"this_way\": n}.",
+                                       rules: %w[119.3], params: { "amount" => "integer", "to" => "selector" },
+                                       example: { "lose_life" => { "amount" => 2, "to" => "each_opponent" } }
+        def apply(engine, ctx) = players(engine, ctx).each { LoseLife.change!(engine, it, -amount_for(engine, ctx)) }
+
+        # Changes a life total and records how much it changed (life lost "this way", CR 608.2c).
+        def self.change!(engine, index, delta)
+          before = engine.player(index).life
+          engine.change_life!(index, delta)
+          engine.record_amount!((engine.player(index).life - before).abs)
+        end
+      end
+
+      # "Your life total becomes 10" (CR 119.5): the player gains or loses the difference.
+      class SetLife < Effect
+        primitive :effect, :set_life,
+                  description: "Each referenced player's life total becomes `amount` (default: you): they gain or " \
+                               "lose the difference (so \"can't gain life\" and life-gain triggers apply).",
+                  rules: %w[119.5 119.7], params: { "amount" => "amount", "to" => "selector" },
+                  example: { "set_life" => { "amount" => 10 } }
+        def self.default_to = "you"
+
+        def apply(engine, ctx)
+          players(engine, ctx).each { LoseLife.change!(engine, it, amount_for(engine, ctx) - engine.player(it).life) }
+        end
+      end
+
+      # "Exchange life totals with target opponent" (CR 701.12a, 701.12c): the player `to` (default you) and
+      # the player `with` each gain or lose life to end at the other's previous total; if either can't (CR
+      # 119.7), nothing happens. The life the first player lost this way is recorded for {"this_way": n}.
+      class ExchangeLifeTotals < Effect
+        primitive :effect, :exchange_life_totals,
+                  description: "The player `to` references (default you) and the one `with` references exchange " \
+                               "life totals: each gains or loses the difference. If either can't gain life and " \
+                               "would, no exchange happens. The life the first player lost this way is recorded for " \
+                               "{\"this_way\": n}.",
+                  rules: %w[701.12a 701.12c 119.7],
+                  params: { "to" => "selector (a player, default you)", "with" => "selector (a player)" },
+                  example: { "exchange_life_totals" => { "with" => { "target" => 0 } } }
+
+        attr_reader :with
+
+        def self.keys = %w[to with if]
+        def self.default_to = "you"
+
+        def setup(params, errors, path)
+          @with = Exchange.with(params, errors, path, @targets_count, @results_count)
+        end
+
+        def apply(engine, ctx)
+          one, other = [to, with].map { |sel| sel.resolve(engine, ctx).filter_map { Filters.player_index(engine, it) }.first }
+          return engine.record_amount!(0) if one.nil? || other.nil? || one == other
+
+          lives = [one, other].to_h { [it, engine.player(it).life] }
+          gains = { one => lives[other] - lives[one], other => lives[one] - lives[other] }
+          return engine.record_amount!(0) if gains.any? { |index, delta| delta.positive? && engine.player_rule?(index, "cant_gain_life") }
+
+          gains.each { |index, delta| engine.change_life!(index, delta) }
+          engine.record_amount!([lives[one] - engine.player(one).life, 0].max)
+        end
+
+        def to_s = "exchange life totals: #{to} and #{with}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Looking at a player's hand (CR 701.20e): the controller sees those cards; others don't.
+      class LookAtHand < Effect
+        primitive :effect, :look_at_hand,
+                  description: "You look at each referenced player's hand (other players don't see the cards).",
+                  rules: %w[701.20e], params: { "to" => "selector of players" },
+                  example: { "look_at_hand" => { "to" => { "target" => 0 } } }
+        def self.keys = %w[to if]
+        def apply(engine, ctx) = players(engine, ctx).each { engine.look_at!(ctx.controller, it, engine.player(it).hand) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # "Draw N cards, then discard N cards; then something for the nonland cards discarded": the shared
+      # shape of connive (CR 701.50) and recruit (CR 701.70). The player draws, then chooses the discards one
+      # `effect_choice` at a time (fewer if their hand runs out); the reward counts the nonland cards among
+      # them by their card types as they were discarded.
+      class Loot < ChoiceEffect
+        def run(engine, ctx, locals)
+          return :done unless locals.key?("queue") || condition.nil? || condition.true?(engine, ctx)
+
+          queue = (locals["queue"] ||= loot_queue(engine, ctx))
+          while (entry = queue.first)
+            return :wait if loot(engine, locals, entry) == :wait
+
+            reward(engine, ctx, entry, locals["nonland"])
+            queue.shift
+            %w[drawn nonland applied answers asked].each { locals.delete(it) }
+          end
+          :done
+        end
+
+        private
+
+        def loot(engine, locals, entry)
+          index = entry["player"]
+          unless locals["drawn"]
+            entry["n"].times { engine.draw!(index) }
+            locals.merge!("drawn" => true, "nonland" => 0, "applied" => 0)
+          end
+          chosen = answers(locals)
+          chosen.drop(locals["applied"]).each do |answer|
+            locals["nonland"] += 1 unless engine.chars(answer["object"]).land?
+            engine.move!(answer["object"], :graveyard, reason: "discard")
+          end
+          locals["applied"] = chosen.size
+          hand = engine.player(index).hand
+          return :done if chosen.size >= entry["n"] || hand.empty?
+
+          ask(engine, locals, index, "Discard a card (#{entry["n"] - chosen.size} to go)",
+              hand.map { { "type" => "discard", "object" => it } })
+        end
+      end
+
+      # Connive / connive N (CR 701.50a, 701.50d): the permanent's controller draws N cards, then discards N
+      # cards, then puts a +1/+1 counter on it for each nonland card discarded. A permanent that has left the
+      # battlefield connives as it last existed: its last controller (here, the effect's controller) loots
+      # and no counters are put (CR 701.50b). Connive 0 does nothing (CR 701.50e).
+      class Connive < Loot
+        primitive :effect, :connive,
+                  description: "Each referenced permanent (default: this one) connives `amount` (default 1): its " \
+                               "controller draws that many cards, then discards that many, then it gets a +1/+1 " \
+                               "counter for each nonland card discarded.",
+                  rules: %w[701.50a 701.50b 701.50d 701.50e],
+                  params: { "amount" => "amount (default 1)", "to" => "selector of permanents (default self)" },
+                  example: { "connive" => { "to" => "self" } }
+
+        def self.default_to = "self"
+
+        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 to_s = "connive #{amount} → #{to}"
+
+        private
+
+        def loot_queue(engine, ctx)
+          n = amount_for(engine, ctx)
+          return [] unless n.positive?
+
+          refs(engine, ctx).filter_map do |id|
+            obj = engine.state.objects[id] or next
+            { "player" => obj.zone == :battlefield ? obj.controller : ctx.controller, "n" => n, "object" => id }
+          end
+        end
+
+        def reward(engine, _ctx, entry, nonland)
+          perm = engine.state.objects[entry["object"]]
+          engine.add_counters!(perm, "+1/+1", nonland, by_player: entry["player"]) if perm&.zone == :battlefield
+        end
+      end
+
+      # Recruit (CR 701.70a): "Draw a card, then discard a card. If you discarded a nonland card this way,
+      # create a 1/1 white Human Soldier creature token."
+      class Recruit < Loot
+        primitive :effect, :recruit,
+                  description: "Each referenced player (default: you) recruits: draws a card, then discards a card; " \
+                               "if a nonland card was discarded, they create a 1/1 white Human Soldier creature token.",
+                  rules: %w[701.70a],
+                  params: { "to" => "player selector (default you)" },
+                  example: { "recruit" => {} }
+
+        TOKEN = { "name" => "Human Soldier", "types" => ["creature"], "subtypes" => %w[human soldier], "colors" => ["W"],
+                  "power" => 1, "toughness" => 1 }.freeze
+
+        def self.keys = %w[to if]
+        def self.default_to = "you"
+        def self.token = @token ||= CardDefinition.token(TOKEN)
+
+        def created_tokens = [Recruit.token]
+        def to_s = "recruit → #{to}"
+
+        private
+
+        def loot_queue(engine, ctx) = players(engine, ctx).map { { "player" => it, "n" => 1 } }
+
+        def reward(engine, _ctx, entry, nonland)
+          engine.create_token!(Recruit.token, entry["player"]) if nonland.positive?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Effects
+      # Adding mana as the effect of a resolving spell or ability (CR 106.4): "Add {R}{R}{R}." or
+      # "Add two mana of any one color." The color is chosen as the effect resolves (CR 608.2d).
+      # Activated abilities without targets that add mana are mana abilities instead (CR 605.1a).
+      class AddMana < ChoiceEffect
+        COLORS = Mana::COLORS.map(&:to_s).freeze
+        CHOICES = %w[any_one any chosen].freeze
+
+        primitive :effect, :add_mana,
+                  description: "You add mana to your mana pool: the fixed mana in `produce`, or `amount` mana of a " \
+                               "color you choose as it resolves (`color: \"any_one\"`: all of one color; " \
+                               "`color: \"any\"`: each mana's color chosen separately, \"in any combination of " \
+                               "colors\"; `\"chosen\"`: of the color chosen for its source or by it, CR 607.2d). " \
+                               "`colors` limits the choice (\"add {R} or {G}\"). `spend_only` restricts " \
+                               "how the mana can be spent (CR 106.6). `until: \"end_of_combat\"`: you don't lose this " \
+                               "mana as steps end until end of combat (CR 702.189a).",
+                  rules: %w[106.1a 106.4 608.2d 605.1a 106.6 500.5 607.2d],
+                  params: { "produce" => "mana symbols, e.g. \"{R}{R}\"", "amount" => "amount (default 1; with produce: how many times)",
+                            "color" => CHOICES.join(" | "), "colors" => "list of colors to choose from (default all five)",
+                            "spend_only" => "{\"spells\": card spec, \"abilities\": card spec}",
+                            "until" => "\"end_of_combat\" (optional)" },
+                  example: { "add_mana" => { "amount" => 2, "color" => "any_one" } }
+
+        attr_reader :produce, :color
+
+        def self.keys = %w[produce amount color colors spend_only until 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)
+          raw = Mechanics.fetch_param(params, :produce)
+          @color = Mechanics.fetch_param(params, :color)
+          @produce = raw && Mana.parse_produce(raw, errors, "#{path}.produce")
+          errors << "#{path}: needs exactly one of produce, color" unless raw.nil? ^ @color.nil?
+          errors << "#{path}.color: must be one of #{CHOICES.join(", ")}" if @color && !CHOICES.include?(@color)
+          raw_spend = Mechanics.fetch_param(params, :spend_only)
+          @spend_only = raw_spend && SpendOnly.build(raw_spend, errors, "#{path}.spend_only")
+          @until = Mechanics.fetch_param(params, :until)
+          errors << "#{path}.until: must be \"end_of_combat\"" unless [nil, "end_of_combat"].include?(@until)
+          raw_colors = Mechanics.fetch_param(params, :colors)
+          @colors = raw_colors || COLORS
+          return if raw_colors.nil?
+          return if %w[any_one any].include?(@color) && @colors.is_a?(Array) && @colors.size >= 2 &&
+                    (@colors - COLORS).empty? && @colors.uniq == @colors
+
+          errors << "#{path}.colors: must list two or more colors (W U B R G), with color"
+        end
+
+        def run(engine, ctx, locals)
+          return :done unless condition.nil? || condition.true?(engine, ctx)
+
+          index = ctx.controller
+          return add(engine, index, @produce * amount_for(engine, ctx), ctx) unless @color # the fixed mana, `amount` times
+          return add(engine, index, Array(chosen_color(engine, ctx)) * amount_for(engine, ctx), ctx) if @color == "chosen"
+
+          n = (locals["n"] ||= amount_for(engine, ctx))
+          picks = answers(locals)
+          if picks.size < (@color == "any_one" ? [n, 1].min : n)
+            return ask(engine, locals, index, "Choose the color of #{@color == "any_one" ? "the" : "the next"} mana",
+                       @colors.map { { "type" => "color", "color" => it } })
+          end
+          colors = picks.map { it["color"].to_sym }
+          add(engine, index, @color == "any_one" ? colors * n : colors, ctx)
+        end
+
+        # CR 607.2d: the color chosen for the source, or by this spell or ability as it resolved ("choose a color").
+        def chosen_color(engine, ctx) = Filters.chosen_memory(engine, ctx.source, ctx)["chosen_color"]&.to_sym
+
+        def to_s
+          return "add #{produce.map { "{#{it}}" }.join}" if produce
+          return "add #{amount} mana of the chosen color" if @color == "chosen"
+
+          return "add #{amount} mana: #{@colors.map { "{#{it}}" }.join(" or ")}" unless @colors == COLORS
+
+          "add #{amount} mana of #{@color == "any_one" ? "any one color" : "any combination of colors"}"
+        end
+
+        private
+
+        def add(engine, index, produce, ctx)
+          engine.add_mana!(index, produce, ctx.source, restriction: @spend_only&.data, keep_until: @until) unless produce.nil?
+          :done
+        end
+      end
+    end
+  end
+end