enjine 0.1.0

data/lib/enjine/fuzz.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Enjine
+  # Plays random games choosing uniformly among legal options and checks the
+  # engine's invariants after every decision. A crash, a stall, a broken invariant
+  # or an export/import mismatch raises Fuzz::Failure with the seed to reproduce it.
+  module Fuzz
+    # Raised when a fuzzed game breaks; carries the reproduction data. `kind`: :finding (the rules monitor
+    # disagreed), :stall (the decision cap was hit), :error (an exception, a broken invariant or roundtrip).
+    class Failure < Error
+      attr_reader :seed, :decisions, :kind
+
+      def initialize(message, seed:, decisions:, kind: :error)
+        @seed = seed
+        @decisions = decisions
+        @kind = kind
+        super("#{message} (seed #{seed}, after #{decisions} decisions)")
+      end
+    end
+
+    Result = Data.define(:games, :decisions, :turns, :outcomes, :casts, :seconds)
+
+    module_function
+
+    # A random legal deck of `size` cards drawn uniformly from `cards` (card data blocks), whatever their colors,
+    # plus `outside` cards its player owns outside the game (CR 400.11a; the copy limit counts both, 100.4a).
+    def random_deck(cards, rng:, size: Deck::MIN_SIZE, outside: 0)
+      definitions = cards.map { CardDefinition.from_h(it) }
+      counts = Hash.new(0)
+      extra = Hash.new(0)
+      draw(definitions, counts, rng, size) { counts[it] += 1 }
+      draw(definitions, counts, rng, outside) do |id|
+        counts[id] += 1
+        extra[id] += 1
+      end
+      doc = { "cards" => definitions.select { counts.key?(it.id) }.map(&:to_h),
+              "main" => counts.filter_map { |id, n| { "card" => id, "count" => n - extra[id] } if n > extra[id] } }
+      doc["outside"] = extra.map { |id, n| { "card" => id, "count" => n } } unless extra.empty?
+      doc
+    end
+
+    # Picks `number` random cards that still fit the four-copy rule, yielding each one's id.
+    def draw(definitions, counts, rng, number)
+      number.times do
+        defn = definitions[rng.rand(definitions.size)]
+        defn = definitions[rng.rand(definitions.size)] until defn.deck_limit.nil? || counts[defn.id] < defn.deck_limit
+        yield defn.id
+      end
+    end
+
+    # roundtrip_every: export+import and compare every N decisions (0 disables).
+    def run(setup, games:, seed: 0, max_decisions: 20_000, roundtrip_every: 0, invariants: true, monitor: true)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      totals = { decisions: 0, turns: 0, outcomes: Hash.new(0), casts: Hash.new(0) }
+      games.times do |i|
+        game_seed = seed + i
+        game = setup.new_game(seed: game_seed)
+        game.subscribe { |e| totals[:casts][e.card] += 1 if e.is_a?(Events::SpellCast) || e.is_a?(Events::AbilityActivated) }
+        watcher = monitor ? RulesMonitor.new(game) : nil
+        decisions = play(game, Agents::Random.new(seed: game_seed), game_seed, max_decisions, roundtrip_every,
+                         invariants, watcher)
+        totals[:decisions] += decisions
+        totals[:turns] += game.turn
+        totals[:outcomes][game.result["reason"]] += 1
+      end
+      Result.new(games: games, decisions: totals[:decisions], turns: totals[:turns],
+                 outcomes: totals[:outcomes].to_h,
+                 casts: totals[:casts].sort_by do |card, n|
+                   [-n, card]
+                 end.to_h, seconds: Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+    end
+
+    def play(game, agent, seed, max_decisions, roundtrip_every, invariants, watcher = nil)
+      count = 0
+      until game.over?
+        raise Failure.new("game exceeded #{max_decisions} decisions", seed: seed, decisions: count, kind: :stall) if count >= max_decisions
+
+        begin
+          entry = game.submit(agent.choose(game.pending_decision))
+        rescue Failure
+          raise
+        rescue StandardError => e
+          raise Failure.new("#{e.class}: #{e.message}", seed: seed, decisions: count)
+        end
+        count += 1
+        check!(game, seed, count) if invariants
+        watch!(watcher, entry, seed, count) if watcher
+        roundtrip!(game, seed, count) if roundtrip_every.positive? && (count % roundtrip_every).zero?
+      end
+      count
+    end
+
+    def watch!(watcher, entry, seed, count)
+      found = watcher.check!(entry)
+      return if found.empty?
+
+      first = found.first
+      raise Failure.new("rules finding CR #{first.rule}: #{first.message}", seed: seed, decisions: count, kind: :finding)
+    end
+
+    def check!(game, seed, count)
+      errors = Snapshot.validate(game.state.to_h, game.catalog)
+      raise Failure.new("invariant broken: #{errors.join("; ")}", seed: seed, decisions: count) unless errors.empty?
+    end
+
+    def roundtrip!(game, seed, count)
+      copy = Game.import(game.export, catalog: game.catalog)
+      same = copy.state.to_h == game.state.to_h && copy.pending_decision&.options == game.pending_decision&.options
+      raise Failure.new("export/import roundtrip changed the game", seed: seed, decisions: count) unless same
+    end
+  end
+end

data/lib/enjine/game.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Enjine
+  # The public face of one game.
+  #
+  #   decision = game.pending_decision   # => Decision(player:, kind:, options:)
+  #   game.submit(decision.options.first)
+  #
+  # An illegal submission raises and never changes the game; `apply` and `import` are all or nothing.
+  class Game
+    # The decision the engine is waiting for.
+    Decision = Data.define(:player, :kind, :options, :details) do
+      def to_h
+        { "player" => player, "kind" => kind, "options" => options.map { it.transform_keys(&:to_s) } }
+          .merge(details)
+      end
+    end
+
+    attr_reader :catalog, :history
+
+    def self.start(catalog:, names:, decklists:, seed:, outside: nil)
+      new(catalog, State.initial(names: names, decklists: decklists, seed: seed, outside: outside)).tap(&:start!)
+    end
+
+    # Resumes a game from #export output (a JSON String or the parsed Hash).
+    def self.import(snapshot, catalog:)
+      data = snapshot.is_a?(String) ? parse_json(snapshot) : Snapshot.deep_stringify(snapshot)
+      raise InvalidSnapshot, ["snapshot must contain \"state\""] unless data.is_a?(Hash) && data["state"]
+
+      state, history = load_parts(data, catalog)
+      game = new(catalog, state, history)
+      verify_pending!(game) # engine errors here are bugs and propagate unchanged
+      game
+    end
+
+    def self.load_parts(data, catalog)
+      [Snapshot.load(data["state"], catalog), Array(data["history"]).map { HistoryEntry.from_h(it) }]
+    rescue ArgumentError, KeyError, NoMethodError, TypeError => e
+      raise InvalidSnapshot, ["malformed snapshot: #{e.message}"]
+    end
+
+    def self.parse_json(text)
+      JSON.parse(text)
+    rescue JSON::ParserError => e
+      raise InvalidSnapshot, ["not valid JSON: #{e.message}"]
+    end
+
+    def self.verify_pending!(game)
+      return if game.over? || !game.pending_decision.options.empty?
+
+      raise InvalidSnapshot, ["pending #{game.state.pending["kind"]} decision has no legal options"]
+    end
+    private_class_method :parse_json, :verify_pending!, :load_parts
+
+    def initialize(catalog, state, history = [])
+      @version = 0
+      @catalog = catalog
+      @history = history
+      @subscribers = []
+      @buffer = []
+      @engine = Engine.new(catalog, state) { |event| @buffer << event }
+    end
+
+    # @api private
+    def start!
+      record(nil, nil) { @engine.start! }
+    end
+
+    def state = @engine.state
+    def names = @engine.names
+    def over? = state.over?
+    def result = state.result&.dup
+    def turn = state.turn
+    def step = state.step
+
+    def pending_decision
+      pending = state.pending
+      return nil unless pending
+
+      @pending_decision = nil if @pending_for != @version
+      @pending_for = @version
+      @pending_decision ||= Decision.new(
+        player: @engine.name(pending["player"]), kind: pending["kind"], options: @engine.options.freeze,
+        details: pending.except("kind", "player")
+      )
+    end
+
+    def legal_options = pending_decision&.options || []
+
+    # Submits one option for the pending decision. Returns the HistoryEntry it produced.
+    def submit(option)
+      decision = pending_decision
+      raise IllegalDecision, "the game is over" unless decision
+
+      chosen = normalize(option)
+      unless decision.options.include?(chosen)
+        raise IllegalDecision.new("#{chosen.inspect} is not a legal option for #{decision.kind}",
+                                  option: chosen, legal_options: decision.options)
+      end
+      record(decision.player, decision.kind, chosen) { @engine.submit!(chosen) }
+    end
+
+    # Fast-forwards through a list of options, all or nothing.
+    def apply(options)
+      transaction do
+        options.each_with_index do |option, index|
+          submit(option)
+        rescue IllegalDecision => e
+          raise IllegalDecision.new(e.message, option: e.option, legal_options: e.legal_options, index: index)
+        end
+      end
+      self
+    end
+
+    # CR 104.3a: a player may concede at any time.
+    def concede(player)
+      raise IllegalDecision, "the game is over" if over?
+
+      index = player_index(player)
+      record(names[index], "concede", { type: "concede" }) { @engine.concede!(index) }
+    end
+
+    # Starts this game over from its opening, with the same or a new seed.
+    def restart(seed: nil)
+      fresh = State.initial(names: names, decklists: state.decklists, seed: seed.nil? ? state.seed : seed,
+                            outside: state.outside_lists)
+      @engine.state = fresh
+      @history = []
+      @buffer.clear
+      start!
+      self
+    end
+
+    def view_for(viewer) = View.build(@engine, viewer_key(viewer))
+    def history_for(viewer) = @history.map { it.for_viewer(viewer_key(viewer)) }
+
+    # Ids of every decision submitted so far: with the seed this replays the game.
+    def decision_log = @history.reject { it.option.nil? || it.kind == "concede" }.map { it.option.transform_keys(&:to_s) }
+
+    def subscribe(&block)
+      @subscribers << block
+      self
+    end
+
+    def to_h = { "state" => state.to_h, "history" => @history.map(&:to_h) }
+
+    # An independent copy of this game (state and history) for search or lookahead.
+    # Subscribers are not copied.
+    def fork = Game.new(@catalog, state.fork, @history.dup)
+    def export = JSON.generate(to_h)
+
+    private
+
+    def record(player, kind, option = nil)
+      @version = @version.to_i + 1
+      @buffer.clear
+      before = [state.turn, state.step&.to_s]
+      yield
+      entry = HistoryEntry.new(seq: @history.size + 1, turn: before[0], step: before[1], player: player,
+                               kind: kind, option: option, events: @buffer.dup.freeze)
+      @history << entry
+      deliver(entry.events) unless @in_transaction
+      entry
+    end
+
+    def transaction
+      saved = state.fork
+      history_size = @history.size
+      @in_transaction = true
+      yield
+      @in_transaction = false
+      deliver(@history[history_size..].flat_map(&:events))
+    rescue StandardError
+      @in_transaction = false
+      @engine.state = saved
+      @version += 1
+      @history = @history.first(history_size)
+      raise
+    end
+
+    def deliver(events)
+      events.each { |event| @subscribers.each { it.call(event) } }
+    end
+
+    def normalize(option)
+      raise IllegalDecision, "an option must be a Hash, got #{option.class}" unless option.is_a?(Hash)
+
+      option.to_h { |k, v| [k.to_sym, v.is_a?(Symbol) ? v.to_s : v] }
+    end
+
+    def player_index(player)
+      names.index(player.respond_to?(:name) ? player.name : player) or
+        raise ArgumentError, "unknown player #{player.inspect}"
+    end
+
+    def viewer_key(viewer)
+      return :observer if viewer.to_s == "observer"
+
+      names[player_index(viewer)]
+    end
+  end
+end

data/lib/enjine/history.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Enjine
+  # One entry of a game's history: the decision a player made (nil for the game's
+  # opening) and every event it caused.
+  HistoryEntry = Data.define(:seq, :turn, :step, :player, :kind, :option, :events) do
+    def self.from_h(hash)
+      h = hash.transform_keys(&:to_s)
+      new(seq: h["seq"], turn: h["turn"], step: h["step"], player: h["player"], kind: h["kind"],
+          option: h["option"]&.transform_keys(&:to_sym), events: h["events"].map { Events.from_h(it) })
+    end
+
+    def to_h = for_viewer(:observer)
+
+    # What `viewer` (a player name or :observer) may know about this entry.
+    def for_viewer(viewer)
+      shown = if option.nil? || viewer == :observer || viewer == player || !Decisions::KINDS.key?(kind)
+                option # concessions (and other non-decision entries) are public
+              else
+                Decisions.fetch(kind).redact(option, false)
+              end
+      { "seq" => seq, "turn" => turn, "step" => step, "player" => player, "kind" => kind,
+        "option" => shown&.transform_keys(&:to_s), "events" => events.map { it.for_viewer(viewer) } }
+    end
+  end
+end

data/lib/enjine/mana.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Enjine
+  # Mana symbols, colors and mana costs (CR 106, 107.4, 202).
+  module Mana
+    COLORS = %i[W U B R G].freeze
+    # Every type of mana that can sit in a mana pool: five colors plus colorless (CR 106.1).
+    TYPES = (COLORS + [:C]).freeze
+    SYMBOL = /\{([^{}]*)\}/
+
+    def self.empty_pool
+      TYPES.to_h { |t| [t, 0] }
+    end
+
+    # A parsed mana cost such as "{2}{R}{R}" or "{X}{R}". `x_symbols` counts the {X} (CR 107.3);
+    # their value is announced while casting (CR 601.2b) and is 0 everywhere else (CR 107.3g).
+    # `hybrid` lists the hybrid symbols ({R/G}), each as the colors that can pay it (CR 107.4e).
+    Cost = Data.define(:generic, :colored, :x_symbols, :hybrid) do
+      def initialize(generic:, colored:, x_symbols: 0, hybrid: [].freeze) = super
+
+      def self.parse(text)
+        errors = []
+        cost = Mana.parse_cost(text, errors)
+        raise ArgumentError, errors.join(", ") unless errors.empty?
+
+        cost
+      end
+
+      # Mana value (CR 202.3); {X} counts as 0 off the stack (CR 202.3e). A hybrid symbol counts its
+      # largest component (CR 202.3f): 1 for {R/G}, 2 for {2/B}.
+      def mana_value = generic + colored.values.sum + hybrid.sum { Mana.mono_hybrid?(it) ? 2 : 1 }
+
+      # The cost with X replaced by `value` (CR 107.3a): each {X} adds that much generic mana.
+      def with_x(value) = with(generic: generic + (x_symbols * value), x_symbols: 0)
+
+      # The colors of the cost's colored and hybrid symbols, in WUBRG order (CR 202.2, 202.2d, 107.4e).
+      def colors = COLORS.select { |c| colored.key?(c) || hybrid.any? { it.include?(c) } }
+
+      # One entry per colored or two-color hybrid symbol: the mana types that can pay it (CR 601.2h). A
+      # monocolored hybrid symbol has no single requirement; see #equivalents.
+      def requirements = colored.flat_map { |color, n| Array.new(n) { [color] } } + hybrid.reject { Mana.mono_hybrid?(it) }
+
+      # The costs without monocolored hybrid symbols this cost can be paid as (CR 601.2b, 107.4e): each {2/B}
+      # as {B} or as {2}. Just itself when it has none.
+      def equivalents
+        mono, rest = hybrid.partition { Mana.mono_hybrid?(it) }
+        return [self] if mono.empty?
+
+        [true, false].repeated_permutation(mono.size).map do |as_color|
+          paid = mono.zip(as_color).filter_map { |symbol, color| symbol.last if color }
+          with(generic: generic + (2 * (mono.size - paid.size)), hybrid: rest,
+               colored: colored.merge(paid.tally) { |_, a, b| a + b })
+        end
+      end
+
+      def to_s
+        parts = ["{X}"] * x_symbols
+        parts << "{#{generic}}" if generic.positive? || (colored.empty? && hybrid.empty? && x_symbols.zero?)
+        hybrid.each { parts << "{#{it.join("/")}}" }
+        colored.each { |c, n| parts.concat(["{#{c}}"] * n) }
+        parts.join
+      end
+    end
+
+    HYBRID = %r{\A([WUBRG2])/([WUBRG])\z}
+
+    # A monocolored hybrid symbol such as {2/B} (CR 107.4e); its first component is the generic "2".
+    def self.mono_hybrid?(symbol) = symbol.first.to_s == "2"
+
+    # The sum of several costs (an ability's mana costs, a spell's mana cost plus a kicker cost).
+    def self.sum_costs(costs)
+      colored = Hash.new(0)
+      costs.each { |cost| cost.colored.each { |c, n| colored[c] += n } }
+      Cost.new(generic: costs.sum(&:generic), colored: colored.to_h.freeze, x_symbols: costs.sum(&:x_symbols),
+               hybrid: costs.flat_map(&:hybrid).freeze)
+    end
+
+    # Parses a mana cost string; pushes problems into errors and returns a Cost (or nil).
+    def self.parse_cost(text, errors, path = "mana_cost")
+      unless text.is_a?(String)
+        errors << "#{path}: must be a string like \"{1}{G}\""
+        return nil
+      end
+
+      rest = text.gsub(SYMBOL, "")
+      unless rest.empty?
+        errors << "#{path}: unexpected characters in #{text.inspect}"
+        return nil
+      end
+
+      generic = 0
+      x = 0
+      colored = {}
+      hybrid = []
+      text.scan(SYMBOL).flatten.each do |sym|
+        case sym
+        when /\A\d+\z/ then generic += sym.to_i
+        when "X" then x += 1
+        when "W", "U", "B", "R", "G", "C" then colored[sym.to_sym] = colored.fetch(sym.to_sym, 0) + 1
+        when HYBRID then hybrid << hybrid_symbol(sym, errors, path)
+        else errors << "#{path}: unsupported mana symbol {#{sym}}"
+        end
+      end
+      Cost.new(generic: generic, colored: colored.freeze, x_symbols: x, hybrid: hybrid.compact.freeze)
+    end
+
+    # A hybrid symbol (CR 107.4e), kept in its printed order: two-color such as {R/G} ([:R, :G]) or
+    # monocolored such as {2/B} ([:"2", :B]: one black mana or two mana of any type). Phyrexian symbols
+    # aren't supported (they are "unsupported mana symbol"s).
+    def self.hybrid_symbol(sym, errors, path)
+      pair = HYBRID.match(sym).captures.map(&:to_sym)
+      return pair.freeze if pair.uniq.size == 2
+
+      errors << "#{path}: {#{sym}} needs two different colors"
+      nil
+    end
+
+    # Pool types as mana symbols: [:G, :G] -> "{G}{G}".
+    def self.symbols(types) = types.map { "{#{it}}" }.join
+
+    # Parses produced mana such as "{G}" or "{C}{C}" into an Array of pool types.
+    def self.parse_produce(text, errors, path)
+      unless text.is_a?(String) && !text.empty?
+        errors << "#{path}: must be a string like \"{G}\""
+        return nil
+      end
+      unless text.gsub(SYMBOL, "").empty?
+        errors << "#{path}: unexpected characters in #{text.inspect}"
+        return nil
+      end
+
+      symbols = text.scan(SYMBOL).flatten
+      bad = symbols.reject { |s| TYPES.include?(s.to_sym) }
+      unless bad.empty?
+        errors << "#{path}: unsupported produced mana #{bad.map { "{#{it}}" }.join}"
+        return nil
+      end
+
+      symbols.map(&:to_sym).freeze
+    end
+  end
+end

data/lib/enjine/mechanics/abilities/additional_triggers.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Abilities
+      # "If [cause] causes a triggered ability of a permanent you control to trigger, that ability triggers
+      # an additional time" (CR 603.2d). A static ability; the engine asks it each time a triggered ability
+      # of a permanent triggers (Engine#additional_triggers). Delayed and reflexive triggered abilities are
+      # never affected.
+      class AdditionalTriggers < Primitive
+        CAUSES = %w[you_gain_life].freeze
+
+        primitive :ability, :additional_triggers,
+                  description: "While this permanent is on the battlefield, a triggered ability of a permanent its " \
+                               "controller controls that triggers because of `cause` triggers an additional time. " \
+                               "`cause`: you_gain_life (its controller gaining life).",
+                  rules: %w[603.2d 119.9],
+                  params: { "cause" => CAUSES.join(" | ") },
+                  example: { "additional_triggers" => { "cause" => "you_gain_life" } }
+
+        attr_reader :cause
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[cause], errors, path)
+          cause = Mechanics.fetch_param(params, :cause)
+          errors << "#{path}.cause: must be one of #{CAUSES.join(", ")}" unless CAUSES.include?(cause)
+          new(cause)
+        end
+
+        def initialize(cause)
+          super()
+          @cause = cause
+          freeze
+        end
+
+        def kind = :additional_triggers
+        def mana_ability? = false
+        def allowed_types = nil
+        def try_effects = []
+        def to_s = "triggered abilities of your permanents that trigger from you gaining life trigger an additional time"
+
+        # `holder`: the permanent with this ability; `source`: the triggering ability's source (a permanent).
+        def additional_trigger?(engine, event, holder, source)
+          return false unless source["controller"] == holder.controller
+
+          event.is_a?(Events::LifeChanged) && event.gain.positive? && engine.names.index(event.player) == holder.controller
+        end
+      end
+    end
+
+    module Effects
+      # "For as long as [this] remains tapped, if a triggered ability of that creature triggers, that ability
+      # triggers an additional time" (CR 603.2d, 611.2b): a resolved effect on the referenced permanents
+      # (locked in, CR 611.2c). It ends for good when its source untaps, leaves the battlefield or phases out
+      # (Engine#end_while_source_effects!); delayed and reflexive triggered abilities are never affected.
+      class AdditionalTriggersEffect < Effect
+        DURATIONS = %w[while_source_tapped].freeze
+
+        primitive :effect, :additional_triggers,
+                  description: "For `duration` (while_source_tapped: for as long as the source remains tapped), each " \
+                               "triggered ability of each referenced permanent triggers an additional time.",
+                  rules: %w[603.2d 611.2b 611.2c],
+                  params: { "to" => "selector", "duration" => DURATIONS.join(" | ") },
+                  example: { "additional_triggers" => { "to" => { "target" => 0 }, "duration" => "while_source_tapped" } }
+
+        def self.keys = %w[to duration if]
+
+        def setup(params, errors, path)
+          @duration = Mechanics.fetch_param(params, :duration)
+          errors << "#{path}.duration: must be one of #{DURATIONS.join(", ")}" unless DURATIONS.include?(@duration)
+        end
+
+        # CR 611.2b: if the source isn't tapped (or is gone) as this resolves, the duration never starts.
+        def apply(engine, ctx)
+          source = engine.state.objects[ctx.source]
+          return unless source && engine.state.battlefield.include?(source.id) && source.tapped
+
+          engine.add_continuous_effect!("additional_triggers", ctx, objects(engine, ctx),
+                                        "duration" => @duration, "source" => ctx.source)
+        end
+
+        def to_s = "its triggered abilities trigger an additional time while the source remains tapped → #{to}"
+      end
+    end
+  end
+end