enjine 0.1.0

data/lib/enjine/mechanics/keywords/convoke.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Keywords
+      # CR 702.51a-d: convoke. While paying the spell's total cost, each untapped creature you control may be
+      # tapped to pay {1} or one mana of one of its colors (a `pay_cost` option `{type: "convoke", object: id}`).
+      class Convoke < Primitive
+        primitive :keyword, :convoke,
+                  description: "Convoke: while paying this spell's total cost you may tap untapped creatures you " \
+                               "control, each paying for {1} or one mana of one of its colors (pay_cost option " \
+                               "`{type: \"convoke\", object: id}`). It isn't an alternative or additional cost.",
+                  rules: %w[702.51a 702.51b 702.51c 702.51d],
+                  example: { "keywords" => ["convoke"] }
+      end
+
+      # CR 702.126a-c: improvise. For each generic mana in the spell's total cost, an untapped artifact you control
+      # may be tapped instead of paying it (a `pay_cost` option `{type: "improvise", object: id}`).
+      class Improvise < Primitive
+        primitive :keyword, :improvise,
+                  description: "Improvise: while paying this spell's total cost you may tap untapped artifacts you " \
+                               "control, each paying for {1} of its generic part (pay_cost option `{type: " \
+                               "\"improvise\", object: id}`). It isn't an alternative or additional cost.",
+                  rules: %w[702.126a 702.126b 702.126c],
+                  example: { "keywords" => ["improvise"] }
+      end
+    end
+
+    module Abilities
+      # "Noncreature spells you cast have improvise." (CR 702.126a, 611.3a): while this permanent is on the
+      # battlefield, spells its controller casts matching the card spec `spells` have the listed helper keywords
+      # (convoke, improvise) as their costs are paid (Engine::AltCasting#helper_keywords).
+      class SpellsHave < Primitive
+        KEYWORDS = %w[convoke improvise].freeze
+
+        primitive :ability, :spells_have,
+                  description: "Spells you cast matching the card spec `spells` (default: every spell) have `keywords` " \
+                               "(convoke and/or improvise) while this permanent is on the battlefield.",
+                  rules: %w[702.126a 702.51a 611.3a 604.1],
+                  params: { "spells" => "card spec, e.g. {\"not_types\": [\"creature\"]}",
+                            "keywords" => "list of convoke, improvise" },
+                  example: { "spells_have" => { "spells" => { "not_types" => ["creature"] }, "keywords" => ["improvise"] } }
+
+        attr_reader :spells, :keywords
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[spells keywords], errors, path)
+          keywords = Mechanics.fetch_param(params, :keywords)
+          unless keywords.is_a?(Array) && !keywords.empty? && (keywords - KEYWORDS).empty?
+            errors << "#{path}.keywords: must be a non-empty list of #{KEYWORDS.join(", ")}"
+          end
+          raw = Mechanics.fetch_param(params, :spells)
+          new(raw && CardSpec.build(raw, errors, "#{path}.spells"), Array(keywords).freeze)
+        end
+
+        def initialize(spells, keywords)
+          super()
+          @spells = spells
+          @keywords = keywords
+          freeze
+        end
+
+        def kind = :spells_have
+        def mana_ability? = false
+        def allowed_types = nil
+        def try_effects = []
+
+        # The keywords `spell` gets from this ability of a permanent controlled by `controller`.
+        def keywords_for(engine, spell, controller)
+          spell.controller == controller && (spells.nil? || spells.match?(engine, spell)) ? keywords : []
+        end
+
+        def to_s = "#{spells&.to_s&.sub(/ card\z/, "")} spells you cast have #{keywords.join(", ")}".strip.capitalize
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/crew.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Costs
+      # The cost of crew N (CR 702.122a): "Tap any number of other untapped creatures you control with total
+      # power N or greater." Each creature is a `choose_cost` decision and is tapped as it is chosen (cancelling
+      # untaps it); once their total power is N or more the player may stop (`done`) or tap more. Summoning
+      # sickness doesn't matter (CR 302.6). As the ability is activated each one crews the Vehicle (CR 702.122b).
+      class Crew < Primitive
+        attr_reader :power
+
+        def initialize(power)
+          super()
+          @power = power
+          freeze
+        end
+
+        def mana? = false
+        def pay!(_engine, _object) = nil
+        def choices_needed = power
+        def to_s = "Tap any number of other untapped creatures you control with total power #{power} or greater"
+
+        # The power a creature crews with: its power, unless it "crews Vehicles as though its power were 2 greater"
+        # or "using its toughness" (Abilities::TappingPower).
+        def crew_power(engine, creature) = Abilities::TappingPower.of(engine, creature, action)
+        def action = :crew
+
+        def candidates(engine, object)
+          engine.state.battlefield.select do |id|
+            other = engine.object(id)
+            id != object.id && other.controller == object.controller && !other.tapped && engine.chars(other).creature?
+          end
+        end
+
+        def payable?(engine, object) = candidates(engine, object).sum { crew_power(engine, engine.object(it)) } >= power
+        def choice_options(engine, object, _chosen) = candidates(engine, object).map { { object: it } }
+
+        def choose!(engine, option)
+          creature = engine.object(option[:object])
+          engine.tap!(creature)
+          { "object" => creature.id, "power" => crew_power(engine, creature), "tapped" => true }
+        end
+
+        def finishable?(entries) = entries.sum { it["power"] } >= power
+
+        # Chosen once the total power is enough and the player is done (or nothing is left to tap).
+        def chosen?(engine, object, entries, done)
+          finishable?(entries) && (done || candidates(engine, object).empty?)
+        end
+
+        # CR 702.122b: each creature tapped to pay the cost crews the Vehicle.
+        def pay_chosen!(engine, object, entries)
+          entries.each { engine.emit Events::CrewedVehicle.new(object: it["object"], vehicle: object.id) }
+        end
+      end
+    end
+
+    module Effects
+      # The effect of a crew ability (CR 702.122a, 702.122e): this permanent becomes an artifact creature until
+      # end of turn, and it "becomes crewed" by the creatures tapped to pay the cost.
+      class Crewed < Effect
+        def self.keys = %w[to]
+
+        def apply(engine, ctx)
+          vehicle = objects(engine, ctx).first or return
+          engine.add_continuous_effect!("add_types", ctx, [vehicle], "types" => %w[artifact creature], "supertypes" => [],
+                                                                     "subtypes" => [])
+          crew = (engine.object(ctx.object).paid || []).map { it["object"] }
+          engine.emit Events::BecameCrewed.new(object: vehicle, crew: crew)
+        end
+
+        def to_s = "this becomes an artifact creature until end of turn"
+      end
+    end
+
+    module Abilities
+      # Crew N (CR 702.122a): an activated ability of a Vehicle. Written {"crew": {"power": N}}.
+      class Crew < ActivatedAbility
+        primitive :ability, :crew,
+                  description: "Crew N: tap any number of other untapped creatures you control with total power N or " \
+                               "more (chosen one at a time; `done` once the total is enough): this permanent becomes " \
+                               "an artifact creature until end of turn. A Vehicle has its printed power and toughness " \
+                               "only while it's a creature.",
+                  rules: %w[702.122a 702.122b 702.122e 301.7 301.7a 301.7b 208.3 302.6],
+                  params: { "power" => "integer >= 1 (the N of crew N)" },
+                  example: { "crew" => { "power" => 3 } }
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[power], errors, path)
+          n = Mechanics.integer_param(params, :power, errors, path, min: 1)
+          new(sorcery: false, targets: [].freeze, costs: [Costs::Crew.new(n)].freeze,
+              effects: [Effects::Crewed.new(to: Selector.new(:self), params: {}, errors: [], path: path)].freeze)
+        end
+
+        def power = costs.first.power
+        def to_s = "Crew #{power}"
+      end
+    end
+
+    module Triggers
+      # "Whenever this Vehicle becomes crewed" (CR 702.122e): whenever its crew ability resolves.
+      class BecomesCrewed < Trigger
+        primitive :trigger, :becomes_crewed,
+                  description: "A crew ability of the subject resolves (it becomes crewed).",
+                  rules: %w[702.122e 603.2],
+                  params: { "subject" => "\"self\" (default) or {\"each\": filter, ...}" },
+                  example: { "becomes_crewed" => {} }
+
+        def event_class = Events::BecameCrewed
+
+        def match?(engine, event, source)
+          obj = engine.state.objects[event.object] or return false
+          @subject.match?(engine, event.object, obj.controller, obj.card, source, types: engine.chars(obj).types)
+        end
+
+        def occurrences(engine, event, source)
+          return [] unless match?(engine, event, source)
+
+          obj = engine.object(event.object)
+          [{ "object" => obj.id, "player" => obj.controller, "card" => obj.card, "amount" => event.crew.size }]
+        end
+
+        def to_s = "Whenever #{@subject} becomes crewed"
+      end
+
+      # "Whenever this creature crews a Vehicle" (CR 702.122b): it was tapped to pay a crew cost. The event's
+      # object for the effects ("that Vehicle") is the Vehicle.
+      class CrewsVehicle < Trigger
+        primitive :trigger, :crews_vehicle,
+                  description: "The subject (a creature) crews a Vehicle: it's tapped to pay that Vehicle's crew cost. " \
+                               "{\"triggering\": \"object\"} is the Vehicle.",
+                  rules: %w[702.122b 603.2],
+                  params: { "subject" => "\"self\" (default) or {\"each\": filter, ...}" },
+                  example: { "crews_vehicle" => { "subject" => "self" } }
+
+        def event_class = Events::CrewedVehicle
+
+        def match?(engine, event, source)
+          obj = engine.state.objects[event.object] or return false
+          @subject.match?(engine, event.object, obj.controller, obj.card, source, types: engine.chars(obj).types)
+        end
+
+        def occurrences(engine, event, source)
+          return [] unless match?(engine, event, source)
+
+          vehicle = engine.state.objects[event.vehicle]
+          [{ "object" => event.vehicle, "player" => engine.object(event.object).controller, "card" => vehicle&.card }.compact]
+        end
+
+        def to_s = "Whenever #{@subject} crews a Vehicle"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/cycling.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # Cycling and typecycling (CR 702.29): activated abilities that function only while the card
+      # is in its owner's hand.
+      #   {"cycling": {"cost": "{2}"}}                                   [cost], discard this card: draw a card
+      #   {"cycling": {"cost": "{2}", "for": {"subtypes": ["swamp"]}}}  ...: search for a Swamp card (typecycling)
+      #   {"cycling": {"cost": "{2}", "for": {"supertypes": ["basic"], "types": ["land"]}}}   basic landcycling
+      class Cycling < ActivatedAbility
+        primitive :ability, :cycling,
+                  description: "Cycling: pay `cost` and discard this card from your hand to draw a card. With `for` " \
+                               "it is typecycling: instead search your library for a card matching `for`, reveal " \
+                               "it, put it into your hand, then shuffle.",
+                  rules: %w[702.29a 702.29b 702.29e 702.29f 113.6m 602.2a],
+                  params: { "cost" => "mana cost string, e.g. \"{2}\"",
+                            "for" => "optional card spec for typecycling (see search_library)" },
+                  example: { "cycling" => { "cost" => "{2}", "for" => { "supertypes" => ["basic"], "types" => ["land"] } } }
+
+        attr_reader :spec
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[cost for], errors, path)
+          raw = Mechanics.fetch_param(params, :cost)
+          mana = raw.nil? ? ((errors << "#{path}.cost: required") && "{0}") : raw
+          costs = [Costs::ManaPayment.build(mana, errors, "#{path}.cost"), Costs::DiscardSelf::INSTANCE].freeze
+          spec_data = Mechanics.fetch_param(params, :for)
+          spec = spec_data.nil? ? nil : CardSpec.build(spec_data, errors, "#{path}.for")
+          new(targets: [].freeze, effects: [effect_for(spec_data)].compact.freeze, costs: costs, sorcery: false, spec: spec)
+        end
+
+        # The ability's effect as card data, built like any other effect (errors in `for` are reported above).
+        def self.effect_for(spec_data)
+          data = if spec_data.nil?
+                   { "draw" => { "amount" => 1 } }
+                 else
+                   { "search_library" => { "for" => spec_data, "reveal" => true } }
+                 end
+          Mechanics.build_entry(:effect, data, [], "cycling")
+        end
+
+        def initialize(spec:, **)
+          @spec = spec
+          super(**)
+        end
+
+        # CR 702.29f: typecycling abilities are cycling abilities.
+        def cycling? = true
+
+        def to_s
+          name = spec ? "#{spec.to_s.delete_suffix(" card").capitalize}cycling" : "Cycling"
+          "#{name} #{costs.first}"
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/decayed.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "prowess"
+
+module Enjine
+  module Mechanics
+    module Keywords
+      # Decayed (CR 702.147a): "This creature can't block" (Engine::Combat#eligible_blockers) and "When this
+      # creature attacks, sacrifice it at end of combat." A decayed counter gives it too (CR 122.1b).
+      class Decayed < Primitive
+        primitive :keyword, :decayed,
+                  description: "This creature can't block. When it attacks, sacrifice it at end of combat.",
+                  rules: %w[702.147a 122.1b], example: { "keywords" => ["decayed"] }
+
+        ABILITY = { "triggered" => { "when" => { "attacks" => {} },
+                                     "effects" => [{ "delayed_trigger" => {
+                                       "when" => { "step_begins" => { "step" => "end_of_combat", "whose" => "each" } },
+                                       "watch" => "self", "effects" => [{ "sacrifice" => { "to" => "watched" } }]
+                                     } }] } }.freeze
+
+        def self.intrinsic_abilities = @intrinsic_abilities ||= [Keywords.ability_from_data(ABILITY, "decayed")].freeze
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/devour.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../abilities/entering_choices"
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # Devour N / devour [quality] N (CR 702.82a, 702.82c): "As this object enters, you may sacrifice any number
+      # of creatures ([quality] permanents). This permanent enters with N +1/+1 counters on it for each one
+      # sacrificed this way." An "as this enters" choice of any number of permanents, picked one at a time
+      # (enter_choice `{type: "devour", object: id}`, then `{type: "done"}`); they're sacrificed as it enters,
+      # and it remembers how many it devoured (memory "devoured", CR 702.82b).
+      class Devour < EnteringChoice
+        primitive :ability, :devour,
+                  description: "Devour `amount`: as this permanent enters, you may sacrifice any number of permanents " \
+                               "matching `each` (default \"creature\"; \"land\" for devour land) that you control, one " \
+                               "at a time; it enters with `amount` +1/+1 counters for each.",
+                  rules: %w[702.82a 702.82b 702.82c 614.12 701.21a],
+                  params: { "amount" => "integer >= 1", "each" => "permanent filter (default \"creature\")" },
+                  example: { "devour" => { "amount" => 3, "each" => "land" } }
+
+        attr_reader :amount
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[amount each], errors, path)
+          amount = Mechanics.integer_param(params, :amount, errors, path, min: 1)
+          raw = Mechanics.fetch_param(params, :each) || "creature"
+          new(amount, Selector.build({ "each" => raw, "controller" => "you" }, errors, "#{path}.each", targets_count: 0))
+        end
+
+        def initialize(amount, selector)
+          super()
+          @amount = amount
+          @selector = selector
+          freeze
+        end
+
+        def to_s = "Devour #{amount} (#{@selector})"
+
+        # The permanents still to pick from, then "done" (CR 702.82a: any number, so none is fine).
+        def pick_options(engine, controller, chosen)
+          ctx = EffectContext.new(controller, nil, nil, [], [])
+          (@selector.resolve(engine, ctx) - chosen).map { { type: "devour", object: it } } + [{ type: "done" }]
+        end
+
+        def enters_for(answer)
+          count = Array(answer[:objects]).size
+          { "counters" => count.positive? ? { "+1/+1" => amount * count } : {}, "memory" => { "devoured" => count } }
+        end
+
+        # As it enters: the chosen permanents still there are sacrificed (CR 701.21a).
+        def pay!(engine, controller, answer)
+          Array(answer["objects"]).each do |id|
+            obj = engine.state.objects[id]
+            engine.move!(id, :graveyard, reason: "sacrifice") if obj&.zone == :battlefield && obj.controller == controller
+          end
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/evergreen.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Keywords
+      # Evergreen keyword abilities. A keyword is a flag on the object's characteristics;
+      # the rules code asks chars(obj).keyword?(:name) at the point the rule applies.
+      class Evergreen < Primitive
+        def self.define(name, description, rules)
+          klass = Class.new(self)
+          Keywords.const_set(name.to_s.split("_").map(&:capitalize).join, klass)
+          klass.primitive :keyword, name, description: description, rules: rules, example: { "keywords" => [name.to_s.tr("_", " ")] }
+        end
+      end
+
+      {
+        flying: ["Can't be blocked except by creatures with flying or reach.", %w[702.9b]],
+        reach: ["Can block creatures with flying.", %w[702.17b]],
+        vigilance: ["Attacking doesn't cause this creature to tap.", %w[702.20b]],
+        menace: ["Can't be blocked except by two or more creatures.", %w[702.111b]],
+        defender: ["Can't attack.", %w[702.3b]],
+        trample: ["Excess combat damage beyond lethal damage to its blockers can be assigned to the player or " \
+                  "planeswalker it's attacking.", %w[702.19b 702.19e]],
+        first_strike: ["Deals combat damage in a first combat damage step, before creatures without first strike.",
+                       %w[702.7b 510.4]],
+        double_strike: ["Deals combat damage in both the first-strike and the regular combat damage step.",
+                        %w[702.4b 510.4]],
+        deathtouch: ["Any damage it deals to a creature is enough to destroy it; 1 damage counts as lethal when " \
+                     "assigning combat damage.", %w[702.2b 702.2c 704.5h]],
+        lifelink: ["Damage dealt by this source also causes its controller to gain that much life.", %w[702.15b]],
+        indestructible: ["Can't be destroyed: lethal damage, deathtouch and \"destroy\" effects don't put it into " \
+                         "the graveyard.", %w[702.12b]],
+        hexproof: ["Can't be the target of spells or abilities your opponents control.", %w[702.11b]],
+        wither: ["Damage this source deals to creatures is dealt as that many -1/-1 counters instead of marked " \
+                 "damage, put by its controller.", %w[702.80a 702.80c 702.80d 120.3d]]
+      }.each { |name, (description, rules)| Evergreen.define(name, description, rules) }
+
+      # Flash (CR 702.8): may be cast any time its controller could cast an instant.
+      class Flash < Primitive
+        primitive :keyword, :flash,
+                  description: "You may cast this spell any time you could cast an instant.",
+                  rules: %w[702.8a], example: { "keywords" => ["flash"] }
+      end
+
+      # Haste (CR 702.10): can attack and {T} the turn it comes under your control.
+      class Haste < Primitive
+        primitive :keyword, :haste,
+                  description: "This creature can attack and use {T} abilities even if it hasn't been under your " \
+                               "control continuously since your most recent turn began.",
+                  rules: %w[702.10a 302.6], example: { "keywords" => ["haste"] }
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/extort.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Keywords
+      # Extort (CR 702.101a): "Whenever you cast a spell, you may pay {W/B}. If you do, each opponent loses 1 life
+      # and you gain life equal to the total life lost this way." Each instance triggers separately (CR 702.101b).
+      # The life lost inside the payment is recorded on the payment (effect 0), so the gain reads it.
+      class Extort < Primitive
+        primitive :keyword, :extort,
+                  description: "Whenever you cast a spell, you may pay {W/B}. If you do, each opponent loses 1 life " \
+                               "and you gain life equal to the total life lost this way.",
+                  rules: %w[702.101a 702.101b 118.12], example: { "keywords" => ["extort"] }
+
+        ABILITY = { "triggered" => {
+          "when" => { "cast" => { "controller" => "you" } },
+          "effects" => [{ "pay" => { "mana" => "{W/B}",
+                                     "then" => [{ "lose_life" => { "amount" => 1, "to" => "each_opponent" } }] } },
+                        { "gain_life" => { "amount" => { "this_way" => 0 } } }]
+        } }.freeze
+
+        def self.intrinsic_abilities = @intrinsic_abilities ||= [Keywords.ability_from_data(ABILITY, "extort")].freeze
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/flags.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "evergreen"
+
+module Enjine
+  module Mechanics
+    module Keywords
+      # Rules modifications that work like a keyword: a flag on the object's characteristics that the
+      # rules code checks, printed, handed out by a static ability (often a conditional one) or gained until end of
+      # turn.
+      {
+        attacks_despite_defender: ["Defender doesn't stop this creature from attacking.", %w[702.3b 508.1c]],
+        doesnt_untap: ["This permanent doesn't untap during its controller's untap step.", %w[502.3]],
+        assigns_damage_by_toughness: ["If this creature's toughness is greater than its power, it assigns combat damage " \
+                                      "equal to its toughness rather than its power.", %w[510.1a]],
+        keeps_damage: ["Damage isn't removed from this permanent during cleanup steps (remove_damage still removes it).",
+                       %w[514.2 120.6]],
+        abilities_cant_be_activated: ["Its activated abilities, mana abilities included, can't be activated (\"Activated " \
+                                      "abilities of artifacts can't be activated\" is a static handing it out).",
+                                      %w[602.5 605.3a 101.2]]
+      }.each { |name, (description, rules)| Evergreen.define(name, description, rules) }
+
+      # Combat restrictions and requirements (CR 508.1c-d, 509.1b). They aren't keyword abilities
+      # in the CR (702), but they work exactly like one: a flag on the object's current
+      # characteristics that combat code checks. So a card prints them (`"keywords": ["cant_block"]`),
+      # a static ability hands them out ("Creatures your opponents control can't block") and the
+      # `grant` effect gives them until end of turn ("Target creature can't be blocked this turn").
+      {
+        cant_attack: ["Restriction: this creature can't attack.", %w[508.1c]],
+        cant_block: ["Restriction: this creature can't block.", %w[509.1b]],
+        cant_be_blocked: ["Restriction: this creature can't be blocked.", %w[509.1b]],
+        cant_attack_alone: ["Restriction: this creature can't attack unless another creature attacks too. It is " \
+                            "offered as an attacker only while another creature attacks or could still be declared, " \
+                            "and declaring attackers can't finish while it attacks alone.", %w[506.5 508.1c]],
+        attacks_each_combat: ["Requirement: this creature attacks each combat if able. Declaring attackers can't " \
+                              "finish while it could still attack.", %w[508.1d]],
+        must_be_blocked: ["Requirement: this attacking creature must be blocked if able. Declaring blockers can't " \
+                          "finish while it is unblocked and a creature that could block it blocks nothing.", %w[509.1c]]
+      }.each { |name, (description, rules)| Evergreen.define(name, description, rules) }
+
+      # "This spell can't be countered." (CR 101.2: a "can't" wins over an effect that would counter it.)
+      Evergreen.define(:cant_be_countered, "This spell can't be countered: counter effects leave it on the stack.",
+                       %w[701.6a 101.2])
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/foretell.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "alternative_costs"
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # Foretell (CR 702.143a-b): any time its owner has priority during their turn, they may pay {2} and exile
+      # the card from their hand face down (a special action, `{type: "special_action", object: id, ability:
+      # ref}`, CR 116.2h). They may look at it while it remains exiled, and cast it after that turn has ended by
+      # paying its foretell cost rather than its mana cost (cast option `via: "alt:<ref>"`, an alternative cost).
+      class Foretell < AlternativeCost
+        primitive :ability, :foretell,
+                  description: "Foretell: during your turn, you may pay {2} and exile this card from your hand face down " \
+                               "(special action `{type: \"special_action\"}`). After that turn you may cast it from " \
+                               "exile by paying `cost` rather than its mana cost (cast option `via: \"alt:<ref>\"`). " \
+                               "`{\"cast_with\": \"foretell\"}` reads it.",
+                  rules: %w[702.143a 702.143b 702.143c 116.2h 406.3 118.9 601.2b 601.2f 601.2h],
+                  params: { "cost" => "mana cost string, or a list of costs" },
+                  example: { "foretell" => { "cost" => "{2}{R}" } }
+
+        FORETELL_COST = Mana::Cost.parse("{2}")
+
+        def zone = :exile
+
+        # CR 702.143a: a card foretold on an earlier turn (the exiled card remembers the turn).
+        def functions?(engine, obj, _index)
+          turn = obj.zone == :exile && obj.memory["foretold"]
+          turn ? engine.state.turn > turn : false
+        end
+
+        # ---- the special action (Actions::SpecialAction) ----
+
+        def special_cost = FORETELL_COST
+        def special_allowed?(engine, obj, index) = obj.zone == :hand && engine.state.active == index
+
+        # Exiled face down; its owner may look at it (CR 702.143a, 406.3).
+        def special!(engine, obj, index)
+          fresh = engine.move!(obj.id, :exile, reason: "foretell", face_down: [index])
+          fresh.memory["foretold"] = engine.state.turn if fresh
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/gift.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "kicker"
+
+module Enjine
+  module Mechanics
+    module Costs
+      # The gift cost (CR 702.174a): "you may choose an opponent" — one `choose_cost` decision among the
+      # opponents. As the spell becomes cast it remembers the chosen player ("gift"), who the gift goes to.
+      class GiftOpponent
+        def mana? = false
+        def choices_needed = 1
+        def payable?(engine, object) = !opponents(engine, object).empty?
+        def opponents(engine, object) = engine.state.players.each_index.reject { it == object.controller }
+        def choice_options(engine, object, _chosen) = opponents(engine, object).map { { object: Filters.player_ref(engine, it) } }
+        def choose!(_engine, option) = { "object" => option[:object] }
+        def pay_chosen!(_engine, object, entries) = object.memory["gift"] = entries.first&.fetch("object")
+        def to_s = "Choose an opponent"
+      end
+    end
+
+    module Abilities
+      # Gift (CR 702.174a-b, k): "As an additional cost to cast this spell, you may choose an opponent." It is
+      # announced like kicker (the `choose_kicker` decision), then the opponent is chosen (`choose_cost`). The
+      # gift itself is ordinary card data: the effect, first in the spell's effects (CR 702.174j) or in an
+      # "enters" trigger of a permanent, with `"if": {"cast_with": "gift"}` ("if the gift was promised") and the
+      # selector "gift_recipient" for the chosen player. Targets only for a promised gift are `kicked_targets`
+      # (CR 702.174m).
+      class Gift < SpellCost
+        primitive :ability, :gift,
+                  description: "Gift: as you cast this spell you may promise a gift to an opponent you choose (the " \
+                               "`choose_kicker` decision, then `choose_cost` for the opponent). `{\"cast_with\": " \
+                               "\"gift\"}` holds if you did, and the selector \"gift_recipient\" is that player; write " \
+                               "the gift as the spell's first effect (or an enters trigger) under that condition.",
+                  rules: %w[702.174a 702.174b 702.174j 702.174k 702.174m 601.2b],
+                  example: "gift"
+
+        COST = Costs::GiftOpponent.new.freeze
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, [], errors, path)
+          new([COST].freeze)
+        end
+
+        def kind = :kicker
+        def to_s = "Gift"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/keywords/hideaway.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "mobilize_and_firebending"
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # Hideaway N (CR 702.75a): "When this permanent enters, look at the top N cards of your library. Exile one
+      # of them face down and put the rest on the bottom of your library in a random order." Only its controller
+      # may look at the exiled card. It's linked to the permanent (CR 607.2a): another of its abilities names it
+      # with the selector "exiled_with", e.g. `cast_free` with `play: true` ("you may play the exiled card
+      # without paying its mana cost").
+      class Hideaway < NumberedTrigger
+        primitive :ability, :hideaway,
+                  description: "Hideaway `amount`: when this permanent enters, look at the top N cards of your library, " \
+                               "exile one face down (linked: \"exiled_with\") and put the rest on the bottom in a random order.",
+                  rules: %w[702.75a 406.3 607.2a],
+                  params: { "amount" => "amount" },
+                  example: { "hideaway" => { "amount" => 4 } }
+
+        def self.expansion(amount)
+          { "when" => { "enters" => {} },
+            "effects" => [{ "dig" => { "amount" => amount, "put" => "exile", "face_down" => true, "link" => true } }] }
+        end
+      end
+    end
+  end
+end