enjine 0.1.0

data/lib/enjine/engine/faces.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Cards with more than one face (CR 712 double-faced, 716 adventurer, 721 omen, 723 preparation cards;
+    # see CardDefinition::Faces). The face that is up is the object's `card`: a face's id ("alfa/1") while
+    # that face is up, the card's own id while the front face is. So every characteristic, ability and
+    # copiable value (CR 707.8) comes from the face that's up with no special case.
+    #
+    #   memory["transformed_at"]  when the permanent last transformed (a timestamp), CR 701.27g
+    #   memory["prepared"]        the id of the prepare spell copy in exile while it's prepared (CR 723.3c)
+    #   memory["prepared_for"]    on that copy: the prepared permanent
+    #   memory["melded"]          on a melded permanent (its object is one card of the pair, back face up): the
+    #                             other card's id (CR 713.1a)
+    module Faces
+      ALTERNATIVE_SPELLS = %w[modal adventure omen].freeze
+
+      # ---- reading -----------------------------------------------------------------------------
+
+      # CR 701.27h: a double-faced permanent with its back face up.
+      def transformed?(obj)
+        defn = catalog.fetch(own_card(obj))
+        obj.zone == :battlefield && defn.double_faced? && defn.face_index.positive?
+      end
+
+      def prepared?(obj) = obj.zone == :battlefield && obj.memory.key?("prepared")
+
+      # The card an object is after moving to `to` (CR 400.7): its front face (CR 712.6a, 716.4, 721.4),
+      # except that a spell becoming a permanent keeps the face it had on the stack (CR 712.10) and a copy
+      # keeps the face it copies (CR 707.8, 716.3c, 723.3c).
+      def card_after_move(old, to)
+        own = own_card(old)
+        return own if old.memory["copy"] || (old.zone == :stack && to == :battlefield)
+
+        catalog.fetch(own).card.id
+      end
+
+      # ---- entering with a face up (CR 712.9, 712.11a-b) --------------------------------------------
+
+      # Whether the card can enter the battlefield with face `index` up: it's a double-faced card and that
+      # face is a permanent (CR 712.11a-b); otherwise it stays where it is.
+      def can_enter_face?(obj, index)
+        defn = catalog.fetch(own_card(obj)).card
+        faced = defn.double_faced? || (defn.layout == "meld" && obj.memory.key?("melded")) # CR 713.1b: only melded
+        faced && index < defn.faces.size && defn.face(index).permanent?
+      end
+
+      def enter_face!(fresh, index)
+        fresh.card = catalog.fetch(fresh.card).card.face(index).id if can_enter_face?(fresh, index)
+      end
+
+      # The definition of the face an entering object will have up (for its own entering replacements,
+      # CR 614.12), or nil when it enters as it is.
+      def entering_face(obj, enters)
+        index = enters && enters["face"]
+        index && can_enter_face?(obj, index) ? catalog.fetch(own_card(obj)).card.face(index) : nil
+      end
+
+      # ---- transforming (CR 701.27) ---------------------------------------------------------------
+
+      # Turns a double-faced permanent over (CR 701.27a). Nothing happens to a permanent that isn't a
+      # double-faced card or token (CR 701.27d; a copy of a double-faced card is, CR 707.8a) or whose other
+      # face is an instant or sorcery (CR 701.27e). It stays the same object (CR 701.27c, 712.15).
+      def transform!(obj)
+        own = catalog.fetch(own_card(obj))
+        return false unless obj.zone == :battlefield && own.double_faced?
+
+        into = own.other_face
+        return false if into.type?(:instant) || into.type?(:sorcery)
+
+        if obj.memory["own_card"] then obj.memory["own_card"] = into.id # still a copy of something else
+        else obj.card = into.id
+        end
+        obj.memory["transformed_at"] = next_timestamp!
+        emit Events::Transformed.new(object: obj.id, card: into.id)
+        true
+      end
+
+      # CR 701.27g: an activated or triggered ability of the permanent transforms it only if it hasn't
+      # transformed since the ability was put on the stack (the ability object's id is numbered then).
+      def transform_still_allowed?(obj, ctx)
+        ability = state.objects[ctx.object]
+        return true unless ability&.ability? && ability.source == obj.id
+
+        at = obj.memory["transformed_at"] or return true
+        at < ability.id.split("#").last.to_i
+      end
+
+      # ---- meld (CR 701.42, 713) -------------------------------------------------------------------
+
+      # CR 701.42b: two cards (not tokens or copies) of one meld pair: meld cards with the same back face name.
+      def meld_pair?(one, two)
+        a, b = [one, two].map { catalog.fetch(own_card(it)).card }
+        [one, two].none? { token?(it) || it.memory["copy"] } && a.id != b.id && [a, b].all? { it.layout == "meld" } &&
+          a.face(1).name == b.face(1).name
+      end
+
+      # CR 701.42a, 713.6: the exiled cards `first` and `second` of a meld pair enter the battlefield as one
+      # permanent with the back face up, under `controller`'s control; `first`'s object stands for both. Cards
+      # that can't be melded stay where they are (CR 701.42c).
+      def meld!(first, second, controller)
+        return unless [first, second].all? { it.zone == :exile } && meld_pair?(first, second)
+
+        state.exile.delete(second.id)
+        state.objects.delete(second.id)
+        move!(first.id, :battlefield, controller: controller, reason: "meld",
+                                      enters: { "face" => 1, "memory" => { "melded" => second.card } })
+      end
+
+      # CR 713.8, 713.8c: a melded permanent that leaves the battlefield puts its two cards into the new zone;
+      # the other card is a new object there too, and both are the result of what moved it.
+      def unmeld!(old, to, data)
+        other = create_object(old.memory["melded"], old.owner, to)
+        arrive!(other, old, data.merge("enters" => { "tapped" => false, "counters" => {} })) if to == :battlefield
+        state.zone_list(to, old.owner).unshift(other.id)
+        record_result!(other.id)
+        emit Events::ZoneChanged.new(card: other.card, old_id: nil, new_id: other.id, owner: name(old.owner),
+                                     from: "battlefield", to: to.to_s, reason: data["reason"])
+      end
+
+      # ---- casting another face (CR 712.8b, 716.3, 721.3) ----------------------------------------------
+
+      # The faces other than the front a card can be cast as: a modal card's nonland faces, an Adventure, an
+      # Omen. A preparation card's spell is cast only as a copy (CR 723.3).
+      def alternative_faces(obj)
+        defn = catalog.fetch(obj.card)
+        return [] if obj.memory["copy"] || defn.face_index.positive? || !ALTERNATIVE_SPELLS.include?(defn.layout)
+
+        (1...defn.faces.size).reject { defn.face(it).land? }
+      end
+
+      # Evaluates the block with face `index` up (CR 712.8c, 716.3a: only that face is evaluated). Nothing in
+      # the block changes state.
+      def with_face(obj, index)
+        card = obj.card
+        obj.card = catalog.fetch(obj.card).face(index).id
+        yield
+      ensure
+        obj.card = card
+      end
+
+      # Priority options for casting the cards in `index`'s hand as another face.
+      def face_cast_options(index, id)
+        obj = object(id)
+        alternative_faces(obj).filter_map do |face|
+          { type: "cast", object: id, face: face } if with_face(obj, face) { castable?(index, id) }
+        end
+      end
+
+      # CR 712.9: a modal double-faced card is played as a land with a land face up.
+      def face_land_options(id)
+        defn = catalog.fetch(object(id).card)
+        return [] unless defn.layout == "modal" && defn.face_index.zero?
+
+        (1...defn.faces.size).filter_map { { type: "play_land", object: id, face: it } if defn.face(it).land? }
+      end
+
+      # The spell goes on the stack with the chosen face up (CR 712.8b, 716.3b, 721.3b).
+      def turn_spell_face!(obj, face)
+        obj.card = catalog.fetch(obj.card).face(face).id if face
+      end
+
+      # CR 716.3d, 721.3d: a resolving Adventure is exiled (its controller may play the card while it stays
+      # exiled, not as an Adventure) and a resolving Omen is shuffled into its owner's library, instead of
+      # going to the graveyard. A copy isn't a card (it ceases to exist). True when handled.
+      def put_away_spell_face!(obj)
+        defn = catalog.fetch(obj.card)
+        return false if obj.memory["copy"] || defn.face_index.zero?
+
+        case defn.layout
+        when "adventure"
+          fresh = move!(obj.id, :exile, reason: "adventure")
+          grant_play_permission!(obj.controller, [fresh.id], duration: "while_exiled", play: "play") if fresh&.zone == :exile
+        when "omen"
+          move!(obj.id, :library, reason: "omen")
+          shuffle_library!(obj.owner)
+        else return false
+        end
+        true
+      end
+
+      # ---- prepared (CR 723.3) --------------------------------------------------------------------
+
+      # CR 723.3a, 723.3c: a permanent with a prepare spell (in its copiable values, CR 723.2b) becomes
+      # prepared: its controller creates a copy of the prepare spell in exile and may cast it while the
+      # permanent stays prepared. A permanent already prepared can't become prepared again.
+      def prepare!(obj)
+        defn = catalog.fetch(obj.card)
+        return false unless obj.zone == :battlefield && !obj.memory.key?("prepared") && defn.layout == "prepare"
+        return false if defn.face_index.positive?
+
+        spell = create_card_copy!([defn.face(1).id, {}], obj.controller, :exile)
+        spell.memory["prepared_for"] = obj.id
+        obj.memory["prepared"] = spell.id
+        grant_play_permission!(obj.controller, [spell.id], duration: "while_exiled", play: "cast")
+        emit Events::PreparedChanged.new(object: obj.id, prepared: true)
+        true
+      end
+
+      # CR 723.3b: it loses the designation; its copy in exile ceases to exist (Engine::Copies).
+      def unprepare!(obj)
+        return false unless obj.memory.delete("prepared")
+
+        emit Events::PreparedChanged.new(object: obj.id, prepared: false)
+        true
+      end
+
+      # CR 723.3c: the copy stays in exile while its permanent is on the battlefield and prepared with it.
+      def prepared_copy?(obj)
+        perm = obj.zone == :exile && state.objects[obj.memory["prepared_for"].to_s]
+        perm ? perm.zone == :battlefield && perm.memory["prepared"] == obj.id : false
+      end
+
+      # CR 723.3c: the permanent loses the designation as its copy becomes cast (`origin`: the copy's id).
+      def cast_prepared_copy!(origin)
+        perm = state.battlefield.map { object(it) }.find { it.memory["prepared"] == origin } or return
+        unprepare!(perm)
+      end
+    end
+    include Faces
+  end
+end

data/lib/enjine/engine/follow_ups.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # The rest of a replacement or prevention effect, done right after the event it modified (CR 615.5,
+    # 614.1a): "... and put that many +1/+1 counters on him", "... and you gain 2 life", "When you do, ..."
+    # (Mechanics::FollowUp). A replacement adds an entry to the event's data["follow_ups"].
+    module FollowUps
+      # `facts` overrides the entries' facts (the card exiled instead, known once the move is done). An entry
+      # with "link" links that card to its source ("exiled with [it]", CR 607.2a).
+      def run_follow_ups!(data, facts = {})
+        Array(data.delete("follow_ups")).each do |entry|
+          seen = entry["facts"].merge(facts).compact
+          link_exiled!(entry["source"], seen["object"]) if entry["link"] && seen["object"]
+          next unless entry["ref"]
+
+          effects = catalog.fetch(entry["card"]).ability(entry["ref"]).effects
+          memory = { "triggering" => seen, "source_card" => entry["card"] }
+          ctx = Mechanics::EffectContext.new(entry["controller"], entry["source"], entry["source"], [], [], [], memory)
+          effects.each { it.run(self, ctx, {}) } # effects that need no choice (CR 615.5)
+        end
+      end
+    end
+
+    include FollowUps
+  end
+end

data/lib/enjine/engine/mana_sources.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Mana the player could make (CR 106, 605): affordability of costs, mana abilities and their options,
+    # restricted mana (CR 106.6), mana costs of mana abilities paid from the pool (CR 605.3a), and adding
+    # mana to and emptying mana pools (CR 106.4).
+    module ManaSources
+      # Whether the cost could be paid with the mana pool plus untapped mana sources (CR 601.2g-h).
+      # Each colored symbol needs mana of that color, a hybrid symbol mana of either of its colors
+      # (CR 107.4e); generic is paid by anything left. `purpose` ({"spell" => id} or {"ability" => source})
+      # lets restricted mana count where it may be spent (CR 106.6).
+      def affordable?(index, cost, excluded_source, purpose = nil)
+        return true if cost.nil? || cost.mana_value.zero?
+
+        covers?(cost, mana_units(index, excluded_source, purpose))
+      end
+
+      # Whether `units` can pay `cost`, a monocolored hybrid {2/B} as {B} or as {2} (CR 107.4e, 601.2b).
+      def covers?(cost, units)
+        cost.equivalents.any? { units.size >= it.mana_value && match_colored(it.requirements, units) }
+      end
+
+      # Every unit of mana the player could make: pool mana (one fixed type each), restricted pool mana
+      # that may be spent on `purpose`, and one unit per untapped source, with the set of types it could
+      # produce (a Treasure: any color).
+      def mana_units(index, excluded_source, purpose = nil)
+        pool_units(index, player(index).mana_pool, purpose) + source_units(index, [excluded_source], purpose) +
+          convoke_units(index, purpose) + # CR 702.51a (Engine::AltCasting)
+          waterbend_units(index, purpose, [excluded_source]) # CR 701.67a (Engine::Waterbending)
+      end
+
+      def pool_units(index, pool, purpose, restricted = player(index).restricted_mana)
+        units = pool.flat_map { |type, n| Array.new([n, 0].max) { [type] } } +
+                restricted.select { spendable?(it, purpose) }.map { [it["mana"].to_sym] }
+        as_any_type(units, purpose)
+      end
+
+      # CR 609.4b: mana spent "as though it were mana of any type" can pay any symbol.
+      def as_any_type(units, purpose) = purpose&.[]("any_type") ? units.map { Mana::TYPES } : units
+
+      # Whether a restricted pool entry may be spent on `purpose` (CR 106.6).
+      def spendable?(entry, purpose)
+        entry["spend_only"].nil? || Mechanics::SpendOnly.from_data(entry["spend_only"]).allows?(self, purpose)
+      end
+
+      # One unit per untapped source not in `excluded`; a source that makes several mana ({C}{C})
+      # gives that many units. A source of restricted mana counts only where that mana may be spent; one
+      # whose ability costs mana isn't counted (it converts pool mana, CR 605.3a).
+      def source_units(index, excluded, purpose = nil)
+        by_source = Hash.new { |h, k| h[k] = [] }
+        all_mana_sources(index).each do |id, ref|
+          next if excluded.include?(id)
+
+          ability = chars(id).ability(ref)
+          next if ability.mana_cost || (ability.spend_only && !ability.spend_only.allows?(self, purpose))
+
+          by_source[id].concat(ability.outcomes(self, object(id)))
+        end
+        units = by_source.values.flat_map { |options| Array.new(options.map(&:size).max) { options.flatten.uniq } }
+        as_any_type(units, purpose)
+      end
+
+      # Bipartite matching (augmenting paths): can every colored or hybrid symbol (the list of types
+      # that can pay it) get its own unit?
+      def match_colored(symbols, units)
+        owner = Array.new(units.size)
+        symbols.each_index.all? { |s| augment(s, symbols, units, owner, Array.new(units.size, false)) }
+      end
+
+      def augment(symbol, symbols, units, owner, seen)
+        units.each_index.any? do |u|
+          next false if seen[u] || !units[u].intersect?(symbols[symbol])
+
+          seen[u] = true
+          next false unless owner[u].nil? || augment(owner[u], symbols, units, owner, seen)
+
+          owner[u] = symbol
+          true
+        end
+      end
+
+      # Every activatable mana ability [id, ability_index] the player controls. Memoized only
+      # while legal options are being computed (state can't change then); recomputed otherwise.
+      def all_mana_sources(index)
+        return scan_mana_sources(index) unless @options_memo
+
+        @options_memo[index] ||= scan_mana_sources(index)
+      end
+
+      def scan_mana_sources(index)
+        out = []
+        state.battlefield.each do |id|
+          obj = object(id)
+          next unless obj.controller == index && !mana_abilities_forbidden?(obj) # Engine::Rules
+
+          chars(obj).mana_abilities.each { |inst| out << [id, inst.ref] if inst.ability.activatable?(self, obj) }
+        end
+        out
+      end
+
+      # Activation options for mana abilities: one per source, or one per mana it could add when the
+      # mana is chosen as it's activated (`mana`: e.g. "{G}{G}", CR 605.3b).
+      def mana_activation_options(sources)
+        sources.flat_map do |id, ref|
+          ability = chars(id).ability(ref)
+          next [{ type: "activate_mana", object: id, ability: ref }] unless ability.choice?
+
+          ability.outcomes(self, object(id)).map { { type: "activate_mana", object: id, ability: ref, mana: Mana.symbols(it) } }
+        end
+      end
+
+      # CR 605.3: pay the ability's costs and add its mana immediately. Shared by priority and payment.
+      # `mana`: the mana chosen as it was activated (an option's "mana"). Restricted mana keeps its
+      # restriction in the pool (CR 106.6).
+      def activate_mana_ability!(index, id, ability_ref, mana = nil)
+        obj = object(id)
+        ability = chars(obj).ability(ability_ref) or raise ArgumentError, "#{id} has no ability #{ability_ref}"
+        chosen = mana && Mana.parse_produce(mana, [], "mana")
+        from = mana_provenance(id) # before a cost sacrifices it (a Treasure)
+        pay_from_pool!(index, ability.mana_cost, id) if ability.mana_cost
+        ability.costs.each { |cost| cost.pay!(self, obj) }
+        produced = chosen || ability.outcomes(self, obj).first # CR 605.3b: a fixed amount is counted as it resolves
+        add_mana!(index, produced, id, restriction: ability.spend_only&.data, from: from)
+      end
+
+      # Whether the mana in the pool (unrestricted) can pay `cost` (a mana ability's mana cost, CR 605.3a).
+      def pool_covers?(index, cost)
+        covers?(cost, player(index).mana_pool.flat_map { |type, n| Array.new(n) { [type] } })
+      end
+
+      # Pays a mana ability's mana cost from the pool: each colored or hybrid symbol with mana that keeps
+      # the rest payable, then generic mana with colorless first, then the most plentiful color.
+      def pay_from_pool!(index, cost, source)
+        pool = player(index).mana_pool
+        units = pool.flat_map { |type, n| Array.new(n) { type } }
+        reqs = cost.requirements
+        spent = reqs.each_with_index.map do |req, i|
+          type = req.find do |t|
+            at = units.index(t) or next false
+            match_colored(reqs.drop(i + 1), units.dup.tap { it.delete_at(at) }.map { [it] })
+          end
+          units.delete_at(units.index(type))
+          type
+        end
+        cost.generic.times do
+          type = units.include?(:C) ? :C : units.tally.max_by { |_, n| n }.first
+          spent << units.delete_at(units.index(type))
+        end
+        spent.each do |type|
+          pool[type] -= 1
+          emit Events::ManaPaid.new(player: name(index), mana: "{#{type}}", object: source)
+        end
+        trim_pool_sources!(player(index)) # mana spent on a mana ability: its source no longer matters
+      end
+
+      # ---- mana (CR 106) ----------------------------------------------------------
+
+      # CR 106.4: mana goes into the pool. Mana with a spending restriction (CR 106.6), or that isn't lost as
+      # steps end (`keep_until: "end_of_combat"`, CR 702.189a), is kept apart, one entry per mana. Mana made by
+      # an artifact remembers its source ("if mana from a Treasure was spent", `from`: #mana_provenance): an
+      # entry's "from", or for pool mana one PlayerState#pool_sources entry per mana.
+      def add_mana!(index, produce, source, restriction: nil, keep_until: nil, from: mana_provenance(source))
+        return if produce.empty?
+
+        pl = player(index)
+        if restriction || keep_until
+          entry = { "spend_only" => restriction && Snapshot.deep_copy(restriction), "until" => keep_until, "from" => from }.compact
+          produce.each { pl.restricted_mana << { "mana" => it.to_s }.merge(entry) }
+        else
+          produce.each { |type| pl.mana_pool[type] += 1 }
+          produce.each { (pl.pool_sources ||= []) << { "mana" => it.to_s, "from" => from } } if from
+        end
+        emit Events::ManaAdded.new(player: name(index), mana: Mana.symbols(produce), source: source)
+      end
+
+      # Pool mana of `type` that remembers no source (CR 106.6): the mana of that type beyond the remembered.
+      def unsourced_mana(player, type) = player.mana_pool[type.to_sym] - (player.pool_sources || []).count { it["mana"] == type.to_s }
+
+      # Keeps no more remembered sources of a type than there is mana of it in the pool.
+      def trim_pool_sources!(player)
+        return if player.pool_sources.nil? || player.pool_sources.empty?
+
+        kept = Hash.new(0)
+        player.pool_sources = player.pool_sources.select { (kept[it["mana"]] += 1) <= player.mana_pool[it["mana"].to_sym] }
+      end
+
+      # Where mana comes from, when a spell may ask ("mana from a Treasure", CR 106.6): an artifact source that
+      # isn't a land, as it is now (it may be sacrificed for the mana). Nil for other sources.
+      def mana_provenance(source)
+        obj = state.objects[source] or return nil
+        c = chars(obj)
+        return nil unless c.type?(:artifact) && !c.land?
+
+        { "name" => c.name, "types" => c.types.map(&:to_s), "subtypes" => c.subtypes.map(&:to_s),
+          "supertypes" => c.supertypes.map(&:to_s), "colors" => c.colors.map(&:to_s) }
+      end
+
+      # The characteristics a mana source had as it made the mana (#mana_provenance), to match a card spec.
+      def self.source_chars(from)
+        Enjine::Characteristics::FACE_DOWN.with(name: from["name"], types: from["types"].map(&:to_sym),
+                                                subtypes: from["subtypes"].map(&:to_sym), supertypes: from["supertypes"].map(&:to_sym),
+                                                colors: from["colors"].map(&:to_sym))
+      end
+
+      # Mana that stays as `step` ends: "until end of combat" mana through the combat steps (CR 702.189a).
+      def self.mana_kept?(entry, step) = entry["until"] == "end_of_combat" && COMBAT_STEPS.include?(step)
+      COMBAT_STEPS = %i[beginning_of_combat declare_attackers declare_blockers combat_damage].freeze
+
+      # Whether such mana may be in the pool during `step` (it empties as end of combat ends).
+      def self.mana_held?(entry, step) = mana_kept?(entry, step) || (entry["until"] == "end_of_combat" && step == :end_of_combat)
+
+      def empty_mana_pools!
+        state.players.each do |pl|
+          kept = pl.restricted_mana.select { ManaSources.mana_kept?(it, state.step) }
+          lost = pl.restricted_mana - kept
+          next if pl.mana_pool.values.all?(&:zero?) && lost.empty?
+
+          text = pl.mana_pool.flat_map { |type, n| ["{#{type}}"] * n }.join + lost.map { "{#{it["mana"]}}" }.join
+          pl.mana_pool.transform_values! { 0 }
+          pl.restricted_mana = kept
+          pl.pool_sources = []
+          emit Events::ManaEmptied.new(player: pl.name, mana: text)
+        end
+      end
+    end
+
+    include ManaSources
+  end
+end

data/lib/enjine/engine/phasing.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Phasing (CR 702.26) isn't a zone change (702.26d): a phased-out permanent keeps its id, counters,
+    # tapped status, attachments and controller. It is moved from `state.battlefield` to the pseudo-zone
+    # `state.phased_out` (zone `:phased_out`), so every rule that looks at the battlefield treats it as
+    # though it doesn't exist (702.26b) without knowing about phasing. `GameObject#phased_out` records
+    # who controlled it as it phased out (for 502.1) and whether it phased out indirectly, attached to
+    # another permanent (702.26g).
+    module Phasing
+      # Phases out the permanents `ids` at the same time. Auras and Equipment attached to them phase out
+      # indirectly with them; one that would phase out both ways phases out indirectly (CR 702.26g-h).
+      def phase_out!(ids)
+        ids = ids.select { state.battlefield.include?(it) }
+        indirect = ids.flat_map { attached_tree(it) }
+        (ids - indirect).each do |id|
+          obj = object(id)
+          phase_out_one!(obj, false)
+          attached_tree(id).each { phase_out_one!(object(it), true) }
+        end
+      end
+
+      # Every permanent attached to `id`, and every permanent attached to those (CR 702.26g).
+      def attached_tree(id)
+        attachments_of(id).flat_map { [it, *attached_tree(it)] }
+      end
+
+      def phase_out_one!(obj, indirectly)
+        return unless state.battlefield.delete(obj.id)
+
+        obj.zone = :phased_out
+        obj.phased_out = { "by" => obj.controller, "indirectly" => indirectly }
+        state.phased_out << obj.id
+        leave_combat!(obj.id) # CR 506.4: removed from combat
+        end_while_source_effects!(obj.id) # CR 702.26f: "for as long as" effects can no longer see it
+        emit Events::PhasedOut.new(object: obj.id, indirectly: indirectly)
+      end
+
+      # CR 502.1, 702.26a: simultaneously, the phased-in permanents with phasing that `index` controls phase
+      # out, and the permanents that phased out directly under `index`'s control phase in, with whatever
+      # phased out indirectly attached to them (CR 702.26g). The set phasing in is fixed first, so nothing
+      # phases out and back in at once. Nothing phases in while an effect says permanents can't phase in.
+      def phasing_step!(index)
+        coming = phasing_in_prevented? ? [] : state.phased_out.select { phases_in_for?(object(it), index) }
+        phase_out!(state.battlefield.select { object(it).controller == index && chars(it).keyword?(:phasing) })
+        coming.each { phase_in!(object(it)) }
+      end
+
+      def phases_in_for?(obj, index) = obj.phased_out["by"] == index && !obj.phased_out["indirectly"]
+
+      def phasing_in_prevented?
+        state.battlefield.any? { |id| chars(id).abilities.any? { it.ability.kind == :cant_phase_in } }
+      end
+
+      # CR 702.26c, 702.26i: it phases in attached to what it was attached to if that is still on the
+      # battlefield (phased in or not), else unattached; state-based actions deal with the rest.
+      def phase_in!(obj)
+        state.phased_out.delete(obj.id)
+        indirectly = obj.phased_out["indirectly"]
+        obj.zone = :battlefield
+        obj.phased_out = nil
+        state.battlefield << obj.id
+        to = obj.attached_to
+        obj.attached_to = nil if !indirectly && to && !state.battlefield.include?(to) && !state.phased_out.include?(to)
+        emit Events::PhasedIn.new(object: obj.id)
+        state.phased_out.select { object(it).attached_to == obj.id && object(it).phased_out["indirectly"] }
+             .each { phase_in!(object(it)) }
+      end
+    end
+
+    include Phasing
+  end
+end

data/lib/enjine/engine/pregame.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Starting the game (CR 103): choosing who plays first, mulligans (London mulligan,
+    # CR 103.5) and putting cards on the bottom.
+    module Pregame
+      def start!
+        state.decklists.each_with_index do |list, owner|
+          list.each { |card| state.players[owner].library << create_object(card, owner, :library).id }
+        end
+        emit Events::GameStarted.new(players: names, seed: state.seed)
+        winner = state.rng.rand(state.players.size)
+        emit Events::DieRolled.new(winner: name(winner))
+        ask!("kind" => "play_or_draw", "player" => winner)
+      end
+
+      # CR 103.1-103.4: starting player chosen, libraries shuffled, opening hands drawn.
+      def choose_starting_player!(chooser, play)
+        starting = play ? chooser : state.opponent(chooser)
+        state.starting_player = starting
+        emit Events::StartingPlayerChosen.new(chooser: name(chooser), choice: play ? "play" : "draw",
+                                              starting_player: name(starting))
+        turn_order.each do |i|
+          shuffle_library!(i)
+          HAND_SIZE.times { draw!(i) }
+        end
+        ask!("kind" => "mulligan", "player" => starting)
+      end
+
+      # Player indexes in turn order, starting with the starting player.
+      def turn_order
+        first = state.starting_player || 0
+        Array.new(state.players.size) { |i| (first + i) % state.players.size }
+      end
+
+      # CR 103.5 (London mulligan): players declare in turn order, then all mulligans happen at once.
+      def declare_mulligan!(index, choice)
+        player(index).mulligan_choice = choice
+        emit Events::MulliganDeclared.new(player: name(index), choice: choice)
+        undecided = turn_order.find { |i| !player(i).kept && player(i).mulligan_choice.nil? }
+        return ask!("kind" => "mulligan", "player" => undecided) if undecided
+
+        resolve_mulligan_round!
+      end
+
+      # CR 103.5: all declared mulligans happen at the same time. Taking a mulligan is:
+      # shuffle the hand away, draw a new hand, then put N cards (N = mulligans taken so
+      # far) on the bottom. Only then does the next round of declarations start.
+      def resolve_mulligan_round!
+        turn_order.each do |i|
+          pl = player(i)
+          if pl.mulligan_choice == "keep"
+            pl.kept = true
+            emit Events::HandKept.new(player: pl.name, mulligans: pl.mulligans)
+          elsif pl.mulligan_choice == "mulligan"
+            take_mulligan!(i)
+          end
+          pl.mulligan_choice = nil
+        end
+        next_bottom_or_declaration!
+      end
+
+      def take_mulligan!(index)
+        pl = player(index)
+        pl.mulligans += 1
+        pl.hand.dup.each { |id| move!(id, :library, reason: "mulligan") }
+        shuffle_library!(index)
+        HAND_SIZE.times { draw!(index) }
+        emit Events::MulliganTaken.new(player: pl.name, mulligans: pl.mulligans)
+      end
+
+      # Bottoms owed from this round's mulligans (in turn order), then the next round of
+      # declarations, then the first turn.
+      def next_bottom_or_declaration!
+        index = turn_order.find { |i| bottom_remaining(i).positive? }
+        return ask!("kind" => "bottom", "player" => index, "count" => bottom_remaining(index)) if index
+
+        next_player = turn_order.find { |i| !player(i).kept }
+        return ask!("kind" => "mulligan", "player" => next_player) if next_player
+
+        ask!(nil)
+        begin_turn!(state.starting_player)
+        advance!
+      end
+
+      def bottom_remaining(index)
+        pl = player(index)
+        [pl.hand.size - (HAND_SIZE - pl.mulligans), 0].max
+      end
+    end
+
+    include Pregame
+  end
+end