enjine 0.1.0

data/lib/enjine/engine/priority.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Priority (CR 117): who may act, passing, and when the top of the stack resolves or the step ends.
+    module Priority
+      # CR 117.5: state-based actions are checked whenever a player would receive priority.
+      def give_priority!(index)
+        check_state_based_actions!
+        return if state.over?
+        return if legend_rule_first!(index)
+        return if put_triggers_first!(index)
+
+        state.priority = index
+        ask!("kind" => "priority", "player" => index)
+      end
+
+      # Any action other than passing resets the "pass in succession" count (CR 117.4).
+      def action_taken!(index)
+        state.passes = 0
+        give_priority!(index)
+      end
+
+      def pass_priority!(index)
+        emit Events::PriorityPassed.new(player: name(index))
+        state.passes += 1
+        if state.passes >= state.players.size && !state.stack.empty?
+          ask!(nil)
+          begin_resolution! # CR 117.4, 608
+        elsif state.passes >= state.players.size
+          # CR 117.4 / 500.2: all players passed with an empty stack -> the step ends.
+          ask!(nil)
+          state.step_state = "done"
+        else
+          give_priority!(state.opponent(index))
+        end
+      end
+
+      def sorcery_timing?(index)
+        state.active == index && Steps::MAIN_PHASE_STEPS.include?(state.step) && state.stack.empty? &&
+          state.pending&.fetch("kind") == "priority"
+      end
+    end
+
+    include Priority
+  end
+end

data/lib/enjine/engine/resolution.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Resolving the top object of the stack (CR 608), as a resumable "resolve" frame:
+    # the frame remembers which effect is next ("pc") and each effect's scratch data
+    # ("locals"), so an effect may stop to ask a player and continue after the answer.
+    module Resolution
+      def begin_resolution!
+        state.frames << { "type" => "resolve", "object" => state.stack.first, "pc" => nil, "ctx" => nil,
+                          "locals" => {} }
+      end
+
+      # Records a player's answer for the effect that is asking (see Effects::ChoiceEffect). An effect
+      # running a nested effect (a "may") keeps that effect's locals under "child": the innermost asks.
+      def effect_answer!(option)
+        (answering_locals["answers"] ||= []) << option.transform_keys(&:to_s)
+        ask!(nil)
+      end
+
+      # The locals of the effect that is asking: the innermost one of the resolving effect list.
+      def answering_locals
+        frame = state.frames.rfind { it["type"] == "resolve" }
+        locals = frame["locals"][frame["pc"].to_s]
+        locals = locals["child"] while locals["child"]
+        locals
+      end
+
+      def resolving_ability(obj)
+        obj.ability? ? stack_ability(obj) : definition(obj).spell_ability
+      end
+
+      def step_resolution!(frame)
+        obj = object(frame["object"])
+        ability = resolving_ability(obj)
+        start_resolution!(frame, obj, ability) if frame["pc"].nil?
+        return finish_fizzle!(frame, obj) if frame["fizzled"]
+
+        plan = ability ? ability.effect_plan(obj.modes || []) : []
+        while frame["pc"] < plan.size
+          effect, offset, count, index = plan[frame["pc"]]
+          ctx = effect_context(frame["ctx"], offset, count, index ? frame["pc"] - index : 0)
+          locals = (frame["locals"][frame["pc"].to_s] ||= {})
+          return :wait if recording_results(frame) { simultaneously { effect.run(self, ctx, locals) } } == :wait
+          return :done if frame["turn_ended"] # CR 725.1b: exiled mid-resolution (Engine::TurnStructure#end_the_turn!)
+
+          frame["pc"] += 1
+        end
+        if !obj.ability? && definition(obj).permanent? && entering_choice_pending?(obj.id, frame["enter"])
+          return ask_enter_choice!(obj.id, obj.controller) # CR 614.12: decided before it enters
+        end
+
+        emit Events::Resolved.new(object: obj.id, card: obj.card, kind: obj.kind)
+        finish_resolution!(obj, frame)
+        after_resolution!
+      end
+
+      # CR 608.2b: targets are checked once, as resolution begins.
+      def start_resolution!(frame, obj, ability)
+        specs = ability&.targets_for(obj.modes || [], kicked: obj.memory.key?("kicked_with")) || []
+        targets = legal_targets(obj, specs)
+        frame["pc"] = 0
+        # An "up to one" target left unchosen doesn't count: only chosen targets can all be illegal.
+        frame["fizzled"] = (!specs.empty? && obj.targets.to_a.flatten.any? && targets.flatten.none?) ||
+                           !intervening_if_holds?(obj, ability)
+        frame["ctx"] = { "controller" => obj.controller, "source" => obj.ability? ? obj.source : obj.id,
+                         "object" => obj.id, "targets" => targets, "results" => {} }
+        frame["ctx"]["linked"] = obj.memory["results"] if obj.memory.key?("results") # a delayed trigger's (CR 603.7c)
+        frame["ctx"]["linked_amounts"] = obj.memory["amounts"] if obj.memory.key?("amounts") # a reflexive trigger's
+      end
+
+      # CR 400.7j / 608.2c: objects an effect moves or creates, so later effects can refer to them
+      # ("the card exiled this way"). Kept per effect in the frame, so a waiting effect accumulates.
+      def recording_results(frame)
+        @recorded = []
+        @recorded_amount = 0
+        yield
+      ensure
+        (frame["ctx"]["results"] ||= {})[frame["pc"].to_s] = (frame["ctx"]["results"][frame["pc"].to_s] || []) + @recorded
+        record_amounts!(frame) if @recorded_amount.positive?
+        @recorded = @recorded_amount = nil
+      end
+
+      # How much an effect changed, e.g. life it made a player lose (CR 608.2c), per effect (see {"this_way": n}).
+      def record_amounts!(frame)
+        amounts = (frame["ctx"]["amounts"] ||= {})
+        amounts[frame["pc"].to_s] = amounts.fetch(frame["pc"].to_s, 0) + @recorded_amount
+      end
+
+      def record_amount!(amount) = @recorded_amount &&= @recorded_amount + amount
+
+      # Called by zone changes and token creation while an effect runs.
+      def record_result!(id) = @recorded&.push(id)
+
+      # The context for one effect; a modal ability's effects see only their mode's targets.
+      # CR 603.4: a triggered ability whose intervening "if" is false on resolution does nothing.
+      def intervening_if_holds?(obj, ability)
+        return true unless obj.ability? && ability.respond_to?(:condition_met?)
+
+        ability.condition_met?(self, obj.controller, obj.source, obj.id)
+      end
+
+      # `base` is the plan position of the first effect of this effect's list: result n is at base + n.
+      # A delayed trigger's effects see the results of the list that created it instead.
+      def effect_context(data, offset = 0, count = nil, base = 0)
+        targets = count ? data["targets"][offset, count] || [] : data["targets"]
+        own = data["results"] || {}
+        results = data["linked"] || Array.new([own.size - base, 0].max) { own[(base + it).to_s] || [] }
+        amounts = data["linked_amounts"] || Array.new(results.size) { data.fetch("amounts", {})[(base + it).to_s] || 0 }
+        Mechanics::EffectContext.new(data["controller"], data["source"], data["object"], targets, results, amounts)
+      end
+
+      def finish_fizzle!(_frame, obj)
+        emit Events::Fizzled.new(object: obj.id, card: obj.card)
+        obj.ability? ? remove_stack_object!(obj.id) : move!(obj.id, :graveyard, reason: "fizzled")
+        after_resolution!
+      end
+
+      def after_resolution!
+        state.passes = 0
+        give_priority!(state.active) # CR 117.3b
+        :done
+      end
+
+      # Targets that are still legal; illegal ones become nil and are ignored (CR 608.2b).
+      def legal_targets(obj, specs)
+        legal = lambda { |ref, spec|
+          spec&.match_for?(self, ref, obj.controller,
+                           obj.source) && targetable?(ref, obj.controller, obj.source, targeter: obj.source || obj.id)
+        }
+        (obj.targets || []).each_with_index.map do |ref, i|
+          ref.is_a?(Array) ? ref.select { legal.call(it, specs[i]) } : (ref if legal.call(ref, specs[i])) # a counted slot's list
+        end
+      end
+
+      def finish_resolution!(obj, frame = {})
+        return remove_stack_object!(obj.id) if obj.ability?
+        return unless state.stack.include?(obj.id) # it may have left the stack during resolution
+
+        if definition(obj).permanent?
+          enters = with_sunburst(obj, enters_from_answer(obj.id, frame) || {}).merge("cast" => true)
+          enters = enters.merge("attached_to" => frame.dig("ctx", "targets", 0)) if aura?(obj) # CR 608.3c
+          pay_entering_costs!(obj.controller, frame)
+          move!(obj.id, :battlefield, controller: obj.controller, reason: "resolve", enters: enters) # CR 608.3
+        elsif !put_away_spell_face!(obj) && !Mechanics::Keywords::Paradigm.resolved!(self, obj) # Engine::Faces; CR 702.192a
+          move!(obj.id, :graveyard, reason: "resolve") # CR 608.2n
+        end
+      end
+
+      # CR 702.44a-b: a spell with sunburst enters with a counter for each color of mana spent on it.
+      def with_sunburst(obj, enters)
+        counters = Mechanics::Keywords::Sunburst.entering_counters(self, obj)
+        return enters if counters.empty?
+
+        enters ||= {}
+        enters.merge("counters" => enters.fetch("counters", {}).merge(counters) { |_, a, b| a + b })
+      end
+
+      # Abilities on the stack aren't cards; they simply cease to exist.
+      def remove_stack_object!(id)
+        state.stack.delete(id)
+        state.objects.delete(id)
+      end
+    end
+
+    include Resolution
+  end
+end

data/lib/enjine/engine/rules.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Player-level rules effects and the rules they change: "you have hexproof", "no maximum hand
+    # size", "can't attack", "prevent all damage that would be dealt to you", "you don't lose the
+    # game for having 0 or less life", "you can't sacrifice ..." (static abilities of permanents and
+    # resolved effects with a duration), winning and losing by an effect (CR 104.2b, 104.3e), extra
+    # turns (CR 500.7), control changes (CR 613.1b), assimilate (CR 701.72), "for as long as" effects
+    # (CR 611.2b) and targeting restrictions (CR 115.4).
+    module Rules
+      # ---- player rules -------------------------------------------------------------------
+
+      # Whether `rule` applies to the player: a `player_rule` effect naming them (state.effects) or a
+      # `player_rule` static ability of a permanent on the battlefield whose condition holds. `object`: the
+      # permanent or card a filtered rule ("can't sacrifice Treasure tokens", "creature spells can't be
+      # countered") is asked about.
+      def player_rule?(index, rule, object = nil)
+        ref = Mechanics::Filters.player_ref(self, index)
+        return true if state.effects.any? { it["kind"] == "player_rule" && it["rule"] == rule && it["affected"].include?(ref) }
+
+        player_rule_statics.any? do |source, ability|
+          ability.rule == rule && ability.applies_to?(index, source.controller) &&
+            (object.nil? || ability.matches?(self, object, source)) && ability.active?(self, source)
+        end
+      end
+
+      # A rule of the whole game ("Damage can't be prevented"), whichever player it was given to.
+      def game_rule?(rule) = state.players.each_index.any? { player_rule?(it, rule) }
+
+      # CR 101.2: "can't cast" beats any permission to cast. `obj`: the card (or stand-in) to be cast. The card's own
+      # "you can't cast this spell unless ..." too (CR 601.3).
+      def cast_forbidden?(index, obj)
+        player_rule?(index, "cant_cast", obj) || (obj.zone != :hand && player_rule?(index, "cant_cast_except_from_hand")) ||
+          chars(obj).abilities.any? { it.ability.kind == :cast_restriction && !it.ability.allows?(self, index, obj) }
+      end
+
+      # CR 602.5, 101.2: abilities of a permanent matching a `cant_activate` filter can't be activated, nor any of a
+      # permanent whose activated abilities can't be activated (#mana_abilities_forbidden?).
+      def activation_forbidden?(index, obj)
+        obj.zone == :battlefield && (mana_abilities_forbidden?(obj) || player_rule?(index, "cant_activate", obj))
+      end
+
+      # CR 602.5, 605.3a: "its activated abilities can't be activated" covers its mana abilities too.
+      def mana_abilities_forbidden?(obj) = chars(obj).keyword?(:abilities_cant_be_activated)
+
+      # CR 615.12: damage that can't be prevented.
+      def unpreventable?(combat) = game_rule?("damage_cant_be_prevented") || (combat && game_rule?("combat_damage_cant_be_prevented"))
+
+      def player_rule_statics = board_abilities(:player_rule)
+
+      # [[source, ability]] of abilities of `kind` on the battlefield and of emblems (CR 114.4), cached with the
+      # layer pass (they change only on the events that change characteristics).
+      def board_abilities(kind)
+        unless @board_abilities && @board_abilities_epoch == @epoch && @board_abilities_state.equal?(state)
+          @board_abilities_epoch = @epoch
+          @board_abilities_state = state
+          @board_abilities = {}
+        end
+        @board_abilities[kind] ||= (state.battlefield + (state.command || [])).flat_map do |id|
+          source = object(id)
+          chars(source).abilities.filter_map { [source, it.ability] if it.ability.kind == kind }
+        end
+      end
+
+      # CR 402.2 / 514.1: seven, or nil when the player has no maximum hand size.
+      def max_hand_size(index) = player_rule?(index, "no_max_hand_size") ? nil : HAND_SIZE
+
+      # CR 701.21a: only a permanent you control can be sacrificed, and "can't" effects forbid more
+      # (CR 614.17b: a cost that includes sacrificing it can't be paid).
+      def can_sacrifice?(obj, index)
+        obj.zone == :battlefield && obj.controller == index && !player_rule?(index, "cant_sacrifice", obj)
+      end
+
+      # CR 704.5a, unless an effect says the player doesn't lose for having 0 or less life.
+      def loses_for_life?(index) = player(index).life <= 0 && !player_rule?(index, "cant_lose_for_life")
+
+      # CR 615.1: a prevention effect protecting a player from all damage (Replacements#preventing!).
+      def damage_prevented?(ref)
+        index = Mechanics::Filters.player_index(self, ref)
+        !index.nil? && player_rule?(index, "prevent_all_damage")
+      end
+
+      # "Until your next turn" effects end as that player's next turn begins (CR 611.2a, 500.1).
+      def end_effects_until_turn_of!(index)
+        ending = state.effects.count { it["duration"] == "until_your_next_turn" && it["controller"] == index }
+        return if ending.zero?
+
+        state.effects.reject! { it["duration"] == "until_your_next_turn" && it["controller"] == index }
+        emit Events::EffectsEnded.new(count: ending)
+      end
+
+      # ---- targeting restrictions (CR 115.4, 702.11c) --------------------------------------
+
+      # Whether choosing `ref` as a target is forbidden for player `index`: a player with hexproof can't
+      # be targeted by opponents (CR 702.11c), and a permanent may say it can't be the target of
+      # abilities from some sources its controller's opponents control. `source`: the permanent whose
+      # ability is targeting (nil for a spell). `targeter`: the spell, or the ability's source, whose qualities
+      # protection and hexproof from a quality look at (CR 702.16b, 702.11d).
+      def targeting_forbidden?(ref, index, source = nil, targeter: source)
+        player = Mechanics::Filters.player_index(self, ref)
+        # CR 702.11c, 702.16k: a player with hexproof or protection from each of their opponents
+        return player != index && (player_rule?(player, "hexproof") || player_rule?(player, "protection_from_opponents")) if player
+
+        obj = state.objects[ref]
+        return false unless obj && obj.zone == :battlefield
+
+        quality = targeter && state.objects[targeter]
+        return true if protected_from?(obj, quality)
+        return false if obj.controller == index
+
+        src = source && state.objects[source]
+        protected_from?(obj, quality, :hexproof_from) ||
+          (!src.nil? && chars(obj).abilities.any? { it.ability.kind == :cant_be_targeted_by && it.ability.forbids?(self, src) })
+      end
+
+      # ---- protection and hexproof from a quality (CR 702.11d, 702.16) ----------------------
+
+      # Whether the permanent has protection (or, with `kind` :hexproof_from, hexproof) from `other`: a spell,
+      # the source of an ability or of damage, an Aura, an Equipment or a blocking creature.
+      def protected_from?(obj, other, kind = :protection_from)
+        return false if other.nil?
+
+        chars(obj).abilities.any? { it.ability.kind == kind && it.ability.from?(self, other, obj) }
+      end
+
+      # ---- winning and losing by an effect (CR 104.2b, 104.3e) ------------------------------
+
+      # CR 104.2b: in a two-player game, a player winning means every opponent loses. CR 104.3f: a
+      # player who would win and lose at once loses (handled: a loss already recorded stays).
+      def win_game!(index)
+        state.players.each_index { lose!(it, "opponent_won") unless it == index || player(it).lost }
+        end_game_if_decided!
+      end
+
+      def lose_game!(index)
+        lose!(index, "effect")
+        end_game_if_decided!
+      end
+
+      # ---- extra and skipped turns (CR 500.7, 614.10) ----------------------------------------
+
+      # CR 500.7: the turn is added directly after this one; the most recently created is taken first.
+      def add_extra_turn!(index)
+        state.extra_turns["queue"] << index
+        emit Events::ExtraTurnAdded.new(player: name(index))
+      end
+
+      # CR 614.10a: the player skips their next `count` turns (each skip waits for a turn that isn't skipped).
+      def skip_turns!(index, count)
+        return unless count.positive?
+
+        (state.extra_turns["skip"] ||= []).concat([index] * count)
+      end
+
+      # The player whose turn comes next: an extra turn if one was added, else the next in turn order. A
+      # skipped turn doesn't happen (CR 614.10): the turn after it comes next.
+      def take_next_turn!
+        last = state.active
+        loop do
+          extra = state.extra_turns["queue"].pop
+          index = extra || state.opponent(last)
+          skip = state.extra_turns.fetch("skip", []).index(index)
+          unless skip
+            state.extra_turns["begun"] |= [index] if extra
+            return index
+          end
+          state.extra_turns["skip"].delete_at(skip)
+          state.extra_turns.delete("skip") if state.extra_turns["skip"].empty?
+          emit Events::TurnSkipped.new(player: name(index))
+          last = index
+        end
+      end
+
+      def began_extra_turn?(index) = state.extra_turns["begun"].include?(index)
+
+      # ---- control changes (CR 613.1b, 108.4) -----------------------------------------------
+
+      # A control change with indefinite duration (CR 613.1b): it becomes a new controller's
+      # permanent, newly under their control (CR 302.6), and leaves combat (CR 506.4). The newest
+      # control change is remembered, so an older "until end of turn" one doesn't undo it as it ends.
+      def gain_control!(obj, controller, timestamp = next_timestamp!)
+        obj.memory["control_timestamp"] = timestamp
+        return if obj.controller == controller
+
+        leave_combat!(obj.id)
+        obj.controller = controller
+        obj.controlled_since = state.turn
+        emit Events::ControlChanged.new(object: obj.id, controller: name(controller))
+        end_while_source_effects!(obj.id, %w[while_you_control_source]) # CR 611.2b: "for as long as you control"
+      end
+
+      # Control of `obj` for a while: until end of turn, an effect that ends in the cleanup step (CR 514.2), handing
+      # it back unless a newer control change has happened since.
+      # `duration`: "end_of_turn", or "for as long as" its source remains tapped / on the battlefield (CR 611.2b,
+      # `source` set; Engine::Rules#end_while_source_effects! hands it back).
+      def gain_control_for!(obj, controller, ctx, duration: "end_of_turn", source: nil)
+        return if obj.controller == controller
+
+        timestamp = next_timestamp!
+        previous = obj.controller
+        gain_control!(obj, controller, timestamp)
+        state.effects << { "kind" => "control", "timestamp" => timestamp, "controller" => ctx.controller,
+                           "affected" => [obj.id], "duration" => duration, "previous" => previous,
+                           "source" => source }.compact
+        emit Events::EffectStarted.new(kind: "control", affected: [obj.id], details: { "controller" => controller })
+      end
+
+      # CR 514.2: as "until end of turn" control effects end, control returns to the previous controller.
+      def revert_temporary_control! = revert_control!(state.effects.select { it["duration"] == "end_of_turn" })
+
+      # As temporary control effects end, control returns to the previous controller. Several of them on one
+      # permanent all end together: it goes back to whoever had it before the first.
+      def revert_control!(ending)
+        ending.select { it["kind"] == "control" }.group_by { it["affected"].first }.each do |id, list|
+          obj = state.objects[id]
+          next unless obj && obj.zone == :battlefield && obj.memory["control_timestamp"] == list.last["timestamp"]
+
+          gain_control!(obj, list.first["previous"])
+        end
+      end
+
+      # ---- assimilate (CR 701.72) -------------------------------------------------------------
+
+      # CR 701.72a: a permanent: gain control of it, put a +1/+1 counter on it, it becomes a Borg artifact creature.
+      # CR 701.72b: a permanent card elsewhere: put it onto the battlefield under your control with a +1/+1
+      # counter; it's a Borg artifact creature. Returns the assimilated permanent's id (or nil).
+      # `enters`: what an "as this enters" choice adds for a card put onto the battlefield (CR 614.12a).
+      def assimilate!(ref, controller, ctx, enters: nil)
+        obj = state.objects[ref] or return nil
+        if obj.zone == :battlefield
+          gain_control!(obj, controller)
+          add_counters!(obj, "+1/+1", 1)
+        else
+          return nil unless obj.kind == "card" && catalog.fetch(obj.card).permanent? && %i[graveyard exile hand library].include?(obj.zone)
+
+          status = (enters || {}).merge("counters" => (enters || {}).fetch("counters", {}).merge("+1/+1" => 1) { |_, a, b| a + b })
+          obj = move!(ref, :battlefield, controller: controller, reason: "assimilate", enters: status) or return nil
+        end
+        # The type change lasts while it stays on the battlefield; ones about objects that left are dropped.
+        state.effects.reject! { it["kind"] == "assimilate" && !state.battlefield.include?(it["affected"].first) }
+        state.effects << { "kind" => "assimilate", "timestamp" => next_timestamp!, "controller" => ctx.controller,
+                           "affected" => [obj.id], "duration" => "permanent" }
+        emit Events::EffectStarted.new(kind: "assimilate", affected: [obj.id], details: {})
+        obj.id
+      end
+
+      # ---- "for as long as [source] remains tapped" (CR 611.2b) ------------------------------
+
+      # Whether a `while_source_tapped` effect still applies: its source is on the battlefield and tapped.
+      def while_source_holds?(effect)
+        source = effect["source"]
+        state.battlefield.include?(source) && object(source).tapped
+      end
+
+      # "For as long as [source] remains tapped / on the battlefield", "for as long as you control [source]" (CR 611.2b).
+      WHILE_SOURCE = %w[while_source_tapped while_source_on_battlefield while_you_control_source].freeze
+
+      # Whether a "for as long as" duration about `source` holds now for an effect controlled by `controller`; one
+      # that has already ended never starts (CR 611.2b). Other durations always hold.
+      def source_duration_holds?(duration, source, controller)
+        return true unless WHILE_SOURCE.include?(duration)
+        return false unless state.battlefield.include?(source)
+
+        case duration
+        when "while_source_tapped" then object(source).tapped
+        when "while_you_control_source" then object(source).controller == controller
+        else true
+        end
+      end
+
+      # CR 611.2b: once the duration ends (the source untaps, leaves or phases out, CR 702.26f), the effect
+      # is over for good, even if the source becomes tapped again. Untapping ends only `while_source_tapped`.
+      def end_while_source_effects!(id, durations = WHILE_SOURCE)
+        ending = ->(effect) { durations.include?(effect["duration"]) && effect["source"] == id }
+        count = state.effects.count(&ending)
+        return if count.zero?
+
+        revert_control!(state.effects.select(&ending)) # "for as long as" control (CR 611.2b)
+        state.effects.reject!(&ending)
+        emit Events::EffectsEnded.new(count: count)
+      end
+    end
+
+    include Rules
+  end
+end

data/lib/enjine/engine/sagas.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Sagas (CR 715, 704.5s): lore counters, chapter abilities and sacrificing a finished Saga.
+    module Sagas
+      # Chapter numbers of a permanent's chapter abilities (CR 715.2).
+      def chapter_numbers(id) = chars(id).abilities.filter_map { it.ability.chapter if it.ability.respond_to?(:chapter) }
+
+      # CR 715.3c / 505.4: as the precombat main phase begins, the active player puts a lore counter on
+      # each Saga they control with one or more chapter abilities (a turn-based action).
+      def add_lore_counters!(index)
+        sagas = state.battlefield.select do |id|
+          object(id).controller == index && chars(id).subtypes.include?(:saga) && !chapter_numbers(id).empty?
+        end
+        sagas.each { add_counters!(object(it), "lore", 1) }
+      end
+
+      # CR 715.4 / 704.5s: a Saga whose lore counters reach its final chapter number (CR 715.2d) is
+      # sacrificed, unless it's the source of a chapter ability that has triggered but not left the stack.
+      def saga_complete?(obj)
+        c = chars(obj)
+        return false unless c.subtypes.include?(:saga)
+
+        chapters = chapter_numbers(obj.id)
+        !chapters.empty? && obj.counters.fetch("lore", 0) >= chapters.max && !chapter_pending?(obj)
+      end
+
+      def chapter_pending?(obj)
+        chapter = ->(card, ref) { catalog.fetch(card).ability(ref).respond_to?(:chapter) }
+        state.pending_triggers.any? { it["source"] == obj.id && chapter.call(it["card"], it["ability"]) } ||
+          state.stack.any? do |id|
+            stacked = object(id)
+            stacked.ability? && stacked.source == obj.id && chapter.call(stacked.card, stacked.ability)
+          end
+      end
+    end
+
+    include Sagas
+  end
+end

data/lib/enjine/engine/speed.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Enjine
+  class Engine
+    # Speed (CR 702.179) and max speed (CR 702.178). A player has no speed (PlayerState#speed nil) until
+    # start your engines! gives them 1 (CR 702.179a-b, a state-based action); it then rises to at most 4.
+    module Speed
+      MAX_SPEED = 4
+      SPEED_ABILITY = "keyword:start_your_engines"
+
+      # CR 702.179f: a player without speed has speed 0 for effects that refer to it.
+      def speed(index) = player(index).speed.to_i
+
+      # CR 702.179e: max speed is speed 4.
+      def max_speed?(index) = speed(index) >= MAX_SPEED
+
+      # CR 702.179c: a player without speed who is told to increase it gets that value. Never above 4.
+      def increase_speed!(index, amount)
+        set_speed!(index, [speed(index) + amount, MAX_SPEED].min)
+      end
+
+      def set_speed!(index, value)
+        pl = player(index)
+        from = pl.speed
+        return if from == value
+
+        pl.speed = value
+        emit Events::SpeedChanged.new(player: name(index), from: from, to: value)
+      end
+
+      # CR 704.5aa / 702.179a: a player who controls a permanent with start your engines! and has no speed gets
+      # speed 1. Returns true when a player's speed was set (state-based actions are checked again).
+      def start_engines!
+        return false unless speed_card
+
+        started = state.players.each_index.select do |i|
+          player(i).speed.nil? && state.battlefield.any? do |id|
+            obj = object(id)
+            obj.controller == i && chars(obj).keyword?(:start_your_engines)
+          end
+        end
+        started.each { set_speed!(it, 1) }
+        !started.empty?
+      end
+
+      # CR 702.179d: "Whenever one or more opponents lose life during your turn, if your speed is less than 4,
+      # your speed increases by 1. This ability triggers only once each turn." It has no source; it is put on the
+      # stack as the start your engines! keyword ability of a card in the game (its text, not its source).
+      def watch_speed!(event)
+        return unless event.is_a?(Events::LifeChanged) && event.loss.positive? && speed_card
+
+        index = state.active
+        return if index.nil? || names.index(event.player) == index
+        return unless (1...MAX_SPEED).cover?(speed(index)) # has speed (CR 702.179d); the intervening "if" (CR 603.4)
+
+        log = turn_log(index)
+        return if log["speed_triggered"]
+
+        log["speed_triggered"] = true
+        queue_pending_trigger!({ "id" => nil, "card" => speed_card_of(index), "controller" => index,
+                                 "ability" => SPEED_ABILITY }, event, {})
+      end
+
+      # The card whose start your engines! keyword ability stands for the speed trigger: one the player controls
+      # if any (for display only: the ability has no source), else any card in the game with the keyword.
+      def speed_card_of(index)
+        mine = state.battlefield.find do |id|
+          obj = object(id)
+          obj.controller == index && catalog.fetch(obj.card).keyword?(:start_your_engines)
+        end
+        mine ? object(mine).card : speed_card
+      end
+
+      # A card in this game with start your engines! (whose keyword ability holds the speed trigger), or nil.
+      def speed_card
+        @speed_card = catalog.find { it.keyword?(:start_your_engines) }&.id unless defined?(@speed_card)
+        @speed_card
+      end
+
+      # Max speed abilities that apply to `obj`: those of its card while `index` (its controller, or its owner
+      # off the battlefield, CR 702.178b) has max speed.
+      def active_max_speed(obj, index)
+        return EMPTY_ABILITIES unless max_speed?(index)
+
+        catalog.fetch(obj.card).ability_instances.select { it.ability.kind == :max_speed }
+      end
+      EMPTY_ABILITIES = [].freeze
+
+      # A card outside the battlefield has what its max speed abilities grant while its owner has max speed
+      # (CR 702.178b): e.g. "Max speed — {3}, Exile this card from your graveyard: Draw a card."
+      def with_max_speed(obj, base)
+        return base if obj.ability?
+
+        symbols = active_max_speed(obj, obj.owner)
+        return base if symbols.empty?
+
+        defn = catalog.fetch(obj.card)
+        base.with(abilities: (base.abilities + symbols.flat_map { defn.nested_instances(it.ref) }).freeze,
+                  keywords: (base.keywords | symbols.flat_map { it.ability.keywords }).freeze)
+      end
+    end
+    include Speed
+  end
+end