enjine 0.1.0

data/lib/enjine/mechanics/selector.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    # The context an effect runs in.
+    # `results` lists, per earlier effect of the same effect list, the objects that effect
+    # moved or created (CR 400.7j: "the card exiled this way"); see Selector {"result": n}.
+    # `amounts`: per earlier effect, how much it changed (life an earlier effect took); see Amount {"this_way": n}.
+    # `memory`: stands in for the resolving ability's memory while a trigger condition is checked (CR 603.4).
+    EffectContext = Struct.new(:controller, :source, :object, :targets, :results, :amounts, :memory)
+
+    # Data form of "who/what does this effect apply to":
+    #   {"target": 0}                               the first chosen target
+    #   "self"                                      the source permanent, or the source card while it's still in
+    #                                               the graveyard, hand or exile ("return this card from your
+    #                                               graveyard", CR 113.6m; it's a new object once it moves, CR 400.7)
+    #   "you"                                       the controller
+    #   "each_opponent"                             every opponent
+    #   "attached"                                  what the source is attached to ("enchanted creature", CR 303.4m)
+    #   {"each": "creature", "controller": "you"}  every matching object (you | opponent | any)
+    #   {"result": 0}                               what effect 0 of this list moved or created (CR 400.7j)
+    #   {"controller_of": selector}                 the controller of each referenced object ("its controller");
+    #                                               one that has left the battlefield as it last existed (CR 608.2h)
+    #   {"triggering": "object" | "player"}        what the trigger event was about ("that creature",
+    #                                               "that player", CR 603.2); see Triggers.event_facts
+    #   {"triggering": "targets"}                   the targets of the spell a cast trigger saw that matched its
+    #                                               `targets` filter ("those creatures", CR 601.2c)
+    #   {"triggering": "ability"}                   the activated or triggered ability on the stack the trigger
+    #                                               event was about ("copy that ability", CR 707.10)
+    #   "watched"                                   what a delayed triggered ability watches (CR 603.7c)
+    #   "exiled_with"                               cards in exile exiled with the source (linked abilities, CR 607.2a)
+    #   "gift_recipient"                            the opponent chosen for the spell's gift (CR 702.174a)
+    #   "granter"                                   the permanent whose static ability granted this ability ("Return
+    #                                               Trusty Boomerang to its owner's hand", CR 607.1a), while it's still
+    #                                               on the battlefield; the source itself for an ability it has printed
+    class Selector
+      CONTROLLERS = %w[you opponent any].freeze
+      TRIGGERING = %w[object player targets ability].freeze
+      # Where "self" finds its source (CR 113.6m); a source that changed zones is a new object (CR 400.7).
+      SELF_ZONES = %i[battlefield graveyard exile hand].freeze
+
+      attr_reader :kind, :value, :controller
+
+      def self.build(data, errors, path, targets_count:, results_count: 0)
+        case data
+        when "self", "you", "each_opponent", "attached", "watched", "exiled_with", "gift_recipient", "granter" then new(data.to_sym)
+        when Hash
+          data = data.transform_keys(&:to_s)
+          return build_result(data, errors, path, results_count) if data.key?("result")
+          return build_controller_of(data, errors, path, targets_count, results_count) if data.key?("controller_of")
+          return build_triggering(data, errors, path) if data.key?("triggering")
+
+          build_hash(data, errors, path, targets_count)
+        else
+          errors << "#{path}: must be {\"target\": n}, \"self\", \"you\", \"each_opponent\", \"attached\" or {\"each\": filter}"
+          nil
+        end
+      end
+
+      # {"result": n}: n must name an earlier effect of the same list (a nested list sees its parent's).
+      def self.build_result(data, errors, path, results_count)
+        Mechanics.check_keys(data, %w[result], errors, path)
+        index = data["result"]
+        unless index.is_a?(Integer) && index >= 0 && index < results_count
+          errors << "#{path}.result: must refer to one of the #{results_count} earlier effects"
+        end
+        new(:result, index)
+      end
+
+      def self.build_controller_of(data, errors, path, targets_count, results_count)
+        Mechanics.check_keys(data, %w[controller_of], errors, path)
+        inner = build(data["controller_of"], errors, "#{path}.controller_of", targets_count: targets_count,
+                                                                              results_count: results_count)
+        new(:controller_of, inner)
+      end
+
+      def self.build_triggering(data, errors, path)
+        Mechanics.check_keys(data, %w[triggering], errors, path)
+        errors << "#{path}.triggering: must be one of #{TRIGGERING.join(", ")}" unless TRIGGERING.include?(data["triggering"])
+        new(:triggering, data["triggering"])
+      end
+
+      def self.build_hash(data, errors, path, targets_count)
+        if data.key?("target")
+          index = data["target"]
+          unless index.is_a?(Integer) && index >= 0 && index < targets_count
+            errors << "#{path}.target: must refer to one of the #{targets_count} declared targets"
+          end
+          Mechanics.check_keys(data, %w[target], errors, path)
+          new(:target, index)
+        elsif data.key?("each")
+          Mechanics.check_keys(data, %w[each controller], errors, path)
+          filter = Mechanics.build_entry(:filter, data["each"], errors, "#{path}.each")
+          controller = data.fetch("controller", "any")
+          errors << "#{path}.controller: must be one of #{CONTROLLERS.join(", ")}" unless CONTROLLERS.include?(controller)
+          new(:each, filter, controller)
+        else
+          errors << "#{path}: needs \"target\" or \"each\""
+          nil
+        end
+      end
+
+      def initialize(kind, value = nil, controller = nil)
+        @kind = kind
+        @value = value
+        @controller = controller
+        freeze
+      end
+
+      def to_s
+        case kind
+        when :target then "target ##{value + 1}"
+        when :result then "the object(s) from effect ##{value + 1}"
+        when :controller_of then "the controller of #{value}"
+        when :self then "itself"
+        when :attached then "the attached permanent"
+        when :triggering then "the triggering #{value}"
+        when :watched then "the watched object(s)"
+        when :you then "you"
+        when :each_opponent then "each opponent"
+        when :exiled_with then "the cards exiled with it"
+        when :gift_recipient then "the chosen opponent"
+        when :granter then "the permanent granting it"
+        when :each then "each #{value.primitive_name.tr("_",
+                                                        " ")}#{{ "you" => " you control",
+                                                                 "opponent" => " an opponent controls" }[controller]}"
+        end
+      end
+
+      # Resolves to a list of references (object ids / "player:<name>") at resolution time.
+      def resolve(engine, ctx)
+        case kind
+        when :target then Array(ctx.targets[value]).compact # a counted target's slot holds a list (CR 601.2c)
+        when :result then Array(ctx.results&.[](value))
+        when :self then SELF_ZONES.include?(engine.state.objects[ctx.source]&.zone) ? [ctx.source] : []
+        when :attached then attached(engine, ctx)
+        when :triggering then triggering(engine, ctx)
+        when :watched, :gift_recipient then remembered(engine, ctx)
+        when :you then [Filters.player_ref(engine, ctx.controller)]
+        when :each_opponent
+          engine.state.players.each_index.reject { it == ctx.controller }.map { Filters.player_ref(engine, it) }
+        when :each then each(engine, ctx)
+        when :controller_of then controllers(engine, ctx)
+        when :exiled_with then Linked.exiled_with(engine, ctx.source, ctx)
+        when :granter then granter(engine, ctx)
+        end
+      end
+
+      # What the resolving triggered ability remembers (the event facts, watched objects).
+      def self.memory(engine, ctx) = ctx.memory || engine.state.objects[ctx.object]&.memory || {}
+
+      # What a delayed trigger watches; the opponent chosen for a gift, kept by the spell or the permanent it
+      # became (CR 702.174b).
+      def remembered(engine, ctx)
+        return Array(Selector.memory(engine, ctx)["watched"]) if kind == :watched
+
+        Array(Selector.memory(engine, ctx)["gift"] || engine.state.objects[ctx.source]&.memory&.[]("gift"))
+      end
+
+      private
+
+      def controllers(engine, ctx)
+        Array(value&.resolve(engine, ctx)).filter_map do |ref|
+          obj = engine.state.objects[ref]
+          controller = if obj && %i[battlefield
+                                    stack].include?(obj.zone)
+                         obj.controller
+                       else
+                         engine.resolving_last_known(ref)&.fetch("controller") ||
+                           engine.state.objects[ctx.object]&.memory&.dig(Linked::LKI, ref) || obj&.controller
+                       end
+          controller && Filters.player_ref(engine, controller)
+        end.uniq
+      end
+
+      def granter(engine, ctx)
+        id = engine.state.objects[ctx.object]&.memory&.[]("granter") || ctx.source
+        engine.state.battlefield.include?(id) ? [id] : []
+      end
+
+      def triggering(engine, ctx)
+        found = Selector.memory(engine, ctx).fetch("triggering", {})[value]
+        return [] if found.nil?
+
+        case value
+        when "player" then [Filters.player_ref(engine, found)]
+        when "ability" then [engine.stack_object_for(found)].compact
+        else Array(found)
+        end
+      end
+
+      # CR 301.5f / 303.4m: "equipped/enchanted creature" is whatever the source is attached to now.
+      def attached(engine, ctx)
+        to = engine.state.objects[ctx.source]&.attached_to
+        to && engine.state.battlefield.include?(to) ? [to] : []
+      end
+
+      def each(engine, ctx)
+        value.candidates_for(engine, ctx.controller, ctx.source, ctx: ctx).select do |ref|
+          index = Filters.player_index(engine, ref)
+          owner = index || engine.object(ref).controller
+          controller == "any" || (controller == "you") == (owner == ctx.controller)
+        end
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/subtypes/auras_and_equipment.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Subtypes
+      # Auras and Equipment (CR 301.5, 303.4, 701.3, 702.5, 702.6). A permanent is attached to
+      # another through GameObject#attached_to; "equipped/enchanted creature" abilities refer to
+      # whatever the source is attached to (CR 301.5f, 303.4m). The engine side (legality,
+      # attach!/unattach!, state-based actions 704.5m/n/p) is in Engine::Attachments.
+      # Shared rules of the subtypes that make a permanent attachable.
+      class AttachmentSubtype < Primitive
+        def self.validate_definition(_defn, _errors) = nil
+      end
+
+      # Aura (CR 303.4): an enchantment that enters attached to what its spell targeted.
+      class Aura < AttachmentSubtype
+        primitive :subtype, :aura,
+                  description: "An enchantment that is cast targeting what its `enchant` ability allows and enters " \
+                               "the battlefield attached to that target. If it's attached to something it can't " \
+                               "enchant, or to nothing, it's put into its owner's graveyard (a state-based action).",
+                  rules: %w[303.4 303.4a 303.4c 303.4d 608.3c 704.5m],
+                  example: { "types" => ["enchantment"], "subtypes" => ["aura"], "abilities" => [{ "enchant" => "creature" }] }
+
+        def self.applies_to = [:enchantment]
+
+        # CR 303.4a: an Aura spell requires a target, defined by its enchant ability.
+        def self.validate_definition(defn, errors)
+          count = defn.abilities.count { it.kind == :enchant }
+          errors << "abilities: an Aura needs exactly one enchant ability (CR 303.4a, 702.5a)" unless count == 1
+        end
+      end
+
+      # Equipment (CR 301.5): an artifact that can be attached to a creature, usually by equip.
+      class Equipment < AttachmentSubtype
+        primitive :subtype, :equipment,
+                  description: "An artifact that can be attached to a creature (it enters unattached). If the " \
+                               "creature it equips stops being a creature or leaves, it becomes unattached and " \
+                               "stays on the battlefield (a state-based action).",
+                  rules: %w[301.5 301.5b 301.5c 704.5n],
+                  example: { "types" => ["artifact"], "subtypes" => ["equipment"],
+                             "abilities" => [{ "equip" => { "cost" => [{ "mana" => "{2}" }] } }] }
+
+        def self.applies_to = [:artifact]
+      end
+    end
+
+    module Abilities
+      # Enchant [object] (CR 702.5): what an Aura spell can target and what the Aura can enchant.
+      class Enchant < Primitive
+        primitive :ability, :enchant,
+                  description: "The Aura's enchant ability: a target filter for what its spell targets and what the " \
+                               "Aura may be attached to, e.g. \"creature\" or {\"permanent\": {\"any_of\": " \
+                               "[\"artifact\", \"creature\"]}}. Only Auras have it.",
+                  rules: %w[702.5a 115.1b 303.4a],
+                  params: { "(value)" => "a target filter for a permanent" },
+                  example: { "enchant" => "creature" }
+
+        PLAYER_FILTERS = %w[player opponent any_target].freeze
+
+        attr_reader :filter
+
+        def self.scalar_params? = true
+
+        def self.build(params, errors, path, **)
+          filter = Mechanics.build_entry(:filter, params, errors, path)
+          message = "must be a filter for permanents (Auras that enchant players are not supported yet)"
+          errors << "#{path}: #{message}" unless permanents?(filter)
+          new(filter)
+        end
+
+        # Whether the filter matches only permanents ("Enchant creature or Vehicle" is a one_of of two).
+        def self.permanents?(filter)
+          return filter.filters.all? { permanents?(it) } if filter.respond_to?(:filters)
+
+          base = filter.respond_to?(:base) ? filter.base : filter
+          base.nil? || (base.zone == :battlefield && !PLAYER_FILTERS.include?(base.primitive_name))
+        end
+
+        def initialize(filter)
+          super()
+          @filter = filter
+          freeze
+        end
+
+        def kind = :enchant
+        def mana_ability? = false
+        def allowed_types = [:enchantment]
+        def try_effects = []
+
+        def validate_definition(defn, errors, path)
+          errors << "#{path}: only Auras have enchant (CR 702.5a)" unless defn.subtypes.include?(:aura)
+        end
+
+        def to_s = "Enchant #{filter.is_a?(Class) ? filter.primitive_name.tr("_", " ") : filter}"
+      end
+
+      # The spell ability an Aura spell has implicitly (CR 115.1b, 303.4a): one target chosen
+      # by its enchant ability, no effects. Resolving attaches the Aura to it (CR 608.3c).
+      class AuraSpell < StackAbility
+        def self.for(enchant) = new(targets: [enchant.filter].freeze, effects: [].freeze)
+
+        def kind = :aura_spell
+      end
+
+      # Equip [cost] (CR 702.6a): "[Cost]: Attach this permanent to target creature you control.
+      # Activate only as a sorcery."
+      class Equip < ActivatedAbility
+        primitive :ability, :equip,
+                  description: "Equip: pay `cost` to attach this Equipment to target creature you control (not " \
+                               "itself). Sorcery speed. Only Equipment have it.",
+                  rules: %w[702.6a 301.5b 301.5c 701.3a],
+                  params: { "cost" => "list of costs, e.g. [{\"mana\": \"{2}\"}]" },
+                  example: { "equip" => { "cost" => [{ "mana" => "{2}" }] } }
+
+        TARGET = { "creature" => { "controller" => "you", "other" => true } }.freeze
+        EFFECT = { "attach" => { "to" => { "target" => 0 } } }.freeze
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[cost], errors, path)
+          costs = parse_costs(params, errors, path)
+          errors << "#{path}.cost: must be a non-empty list" if costs.empty? && errors.none? { it.start_with?("#{path}.cost") }
+          targets = [Mechanics.build_entry(:filter, TARGET, errors, path)].freeze
+          effects = [Mechanics.build_entry(:effect, EFFECT, errors, path, targets_count: 1)].freeze
+          new(targets: targets, effects: effects, costs: costs, sorcery: true)
+        end
+
+        def allowed_types = [:artifact]
+
+        def validate_definition(defn, errors, path)
+          errors << "#{path}: only Equipment have equip (CR 702.6a)" unless defn.subtypes.include?(:equipment)
+        end
+
+        def to_s = "Equip #{costs.join(", ")}"
+      end
+    end
+
+    module Effects
+      # Attach the source Aura or Equipment to a permanent (CR 701.3).
+      class Attach < Effect
+        primitive :effect, :attach,
+                  description: "Attach this Aura or Equipment (the ability's source), or the `attachment` (e.g. a token " \
+                               "an earlier effect created, {\"result\": n}), to the referenced permanent. Nothing " \
+                               "happens if it can't legally be attached to it, if it's already attached to it, or if " \
+                               "the attachment has left the battlefield.",
+                  rules: %w[701.3a 701.3b 701.3c 301.5c],
+                  params: { "to" => "selector naming one permanent: {\"target\": n}, \"self\" or {\"result\": n}",
+                            "attachment" => "selector (default: the source)" },
+                  example: { "attach" => { "to" => { "target" => 0 } } }
+
+        SINGLE = %i[target self result].freeze
+
+        def self.keys = %w[to attachment if]
+
+        def setup(params, errors, path)
+          if to && !SINGLE.include?(to.kind)
+            errors << "#{path}.to: must be {\"target\": n}, \"self\" or {\"result\": n} (an attachment equips one object, CR 301.5c)"
+          end
+          raw = Mechanics.fetch_param(params, :attachment)
+          @attachment = raw && Selector.build(raw, errors, "#{path}.attachment", targets_count: @targets_count,
+                                                                                 results_count: @results_count)
+        end
+
+        def apply(engine, ctx)
+          target = objects(engine, ctx).first or return
+          ids = @attachment ? @attachment.resolve(engine, ctx) : [ctx.source]
+          ids.each do |id|
+            source = engine.state.objects[id]
+            engine.attach!(source, target) if source && engine.state.battlefield.include?(id)
+          end
+        end
+
+        def to_s = "attach to #{to}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/subtypes/basic_land_types.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Subtypes
+      # Shared behavior of the five basic land types (CR 305.6): each grants an
+      # intrinsic "{T}: Add <color>." ability.
+      class BasicLandType < Primitive
+        class << self
+          attr_reader :color
+
+          def define(name, color)
+            klass = Class.new(self)
+            klass.instance_variable_set(:@color, color)
+            Subtypes.const_set(name.capitalize, klass)
+            klass.primitive :subtype, name,
+                            description: "Basic land type. A land with this subtype has \"{T}: Add {#{color}}.\"",
+                            rules: %w[305.6 205.3i],
+                            example: { "types" => ["land"], "subtypes" => [name.to_s] }
+            klass
+          end
+
+          def applies_to = [:land]
+
+          def intrinsic_abilities
+            @intrinsic_abilities ||= [Abilities::ManaAbility.new([Costs::Tap::INSTANCE].freeze, [color].freeze)].freeze
+          end
+        end
+      end
+
+      { plains: :W, island: :U, swamp: :B, mountain: :R, forest: :G }.each do |name, color|
+        BasicLandType.define(name, color)
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/subtypes/class_levels.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../triggers/base"
+require_relative "../keywords/station"
+
+module Enjine
+  module Mechanics
+    module Effects
+      # The effect of a class level bar's activated ability (CR 717.2a): "This Class's level becomes N."
+      class GainClassLevel < Effect
+        def self.keys = %w[to]
+
+        attr_reader :level
+
+        def setup(params, _errors, _path) = @level = params["level"]
+        def apply(engine, ctx) = objects(engine, ctx).each { engine.set_class_level!(engine.object(it), level) }
+        def to_s = "this Class's level becomes #{level}"
+      end
+    end
+
+    module Abilities
+      # A class level bar "[Cost]: Level N — [Abilities]" (CR 717.2a): "[Cost]: This Class's level becomes N.
+      # Activate only if this Class is level N-1 and only as a sorcery" and "As long as this Class is level N or
+      # greater, it has [abilities]." Abilities printed in its text box section are its `abilities` and
+      # `keywords`; those above the first level bar are ordinary abilities (CR 717.3).
+      class ClassLevel < ActivatedAbility
+        primitive :ability, :class_level,
+                  description: "A class level bar: `cost` (a mana cost string or a list of costs): this permanent's " \
+                               "level becomes `level`; activate only if its level is `level` - 1, as a sorcery. While " \
+                               "its level is `level` or greater it has `keywords` and `abilities`. A permanent " \
+                               "without a level is level 1.",
+                  rules: %w[717.2a 717.2b 717.2d 717.3 602.5d],
+                  params: { "level" => "integer >= 2", "cost" => "mana cost string or list of costs",
+                            "keywords" => "list of keywords", "abilities" => "list of abilities" },
+                  example: { "class_level" => { "level" => 2, "cost" => "{1}{R}",
+                                                "abilities" => [{ "triggered" => {
+                                                  "when" => { "discards" => {} },
+                                                  "effects" => [{ "deal_damage" => { "amount" => 2, "to" => "each_opponent" } }]
+                                                } }] } }
+
+        attr_reader :level, :keywords, :nested_abilities
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[level cost keywords abilities], errors, path)
+          level = Mechanics.integer_param(params, :level, errors, path, min: 2).to_i
+          raw = Mechanics.fetch_param(params, :cost)
+          costs = raw.is_a?(String) ? [Costs::ManaPayment.build(raw, errors, "#{path}.cost")] : parse_costs(params, errors, path)
+          errors << "#{path}.cost: required" if raw.nil?
+          keywords = StationSymbol.build_keywords(params, errors, path)
+          nested = StationSymbol.build_abilities(params, errors, path)
+          nested.each_with_index do |ability, i|
+            errors << "#{path}.abilities[#{i}]: class level bars can't be nested" if ability.is_a?(ClassLevel)
+          end
+          effect = Effects::GainClassLevel.new(to: Selector.new(:self), params: { "level" => level }, errors: errors, path: path)
+          new(sorcery: true, targets: [].freeze, costs: costs.compact.freeze, effects: [effect].freeze,
+              level: level, keywords: keywords.freeze, nested_abilities: nested.freeze)
+        end
+
+        def initialize(level:, keywords:, nested_abilities:, **)
+          @level = level
+          @keywords = keywords
+          @nested_abilities = nested_abilities
+          super(**)
+        end
+
+        # No power/toughness box (Engine::Characteristics#station_symbol_layers reads it).
+        def power = nil
+
+        # CR 717.2a: only if this Class is level N-1.
+        def restriction_met?(engine, index, source)
+          engine.class_level(engine.object(source)) == level - 1 && super
+        end
+
+        def to_s
+          bits = keywords.map(&:to_s) + nested_abilities.map(&:to_s)
+          "#{costs.join(", ")}: Level #{level}#{" — #{bits.join("; ")}" unless bits.empty?}"
+        end
+      end
+    end
+
+    module Triggers
+      # "When this Class becomes level N" (CR 717.2a): its level bar for N resolved.
+      class BecomesLevel < Trigger
+        primitive :trigger, :becomes_level,
+                  description: "This permanent's level becomes `level` (a class level bar's ability resolves).",
+                  rules: %w[717.2a 603.2],
+                  params: { "level" => "integer >= 2" },
+                  example: { "becomes_level" => { "level" => 3 } }
+
+        def self.keys = %w[level]
+        def event_class = Events::ClassLevelChanged
+
+        def setup(params, errors, path)
+          @level = Mechanics.integer_param(params, :level, errors, path, min: 2)
+        end
+
+        def match?(_engine, event, source) = event.object == source["id"] && event.level == @level
+        def to_s = "When this becomes level #{@level}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/subtypes/saga.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Subtypes
+      # The Saga enchantment type (CR 715).
+      class Saga < Primitive
+        primitive :subtype, :saga,
+                  description: "Enchantment type. A Saga enters with a lore counter; as its controller's precombat " \
+                               "main phase begins, they put another lore counter on it. Each lore counter added can " \
+                               "trigger its chapter abilities. Once its lore counters reach its final chapter number " \
+                               "and no chapter ability of it is waiting to resolve, its controller sacrifices it.",
+                  rules: %w[715.3a 715.3c 505.4 715.4 704.5s],
+                  example: { "types" => ["enchantment"], "subtypes" => ["saga"],
+                             "abilities" => [{ "chapter" => { "chapter" => 1, "effects" => [{ "draw" => { "amount" => 1 } }] } }] }
+
+        def self.applies_to = [:enchantment]
+
+        # CR 715.3a: "This Saga enters with a lore counter on it" (a replacement effect, CR 614.1c).
+        def self.entering(_definition, enters)
+          enters["counters"]["lore"] = enters["counters"].fetch("lore", 0) + 1
+        end
+      end
+    end
+
+    module Triggers
+      # The trigger condition of a chapter ability (CR 715.2b): one or more lore counters are put on
+      # this Saga and their number goes from less than N to at least N. Entering with lore counters
+      # counts as having them put on it (CR 122.6).
+      class ChapterTrigger
+        attr_reader :chapter
+
+        def initialize(chapter)
+          @chapter = chapter
+          freeze
+        end
+
+        def watches?(event) = event.is_a?(Events::CountersChanged) || event.is_a?(Events::ZoneChanged)
+        def leaves_battlefield? = false
+
+        def match?(engine, event, source)
+          if event.is_a?(Events::CountersChanged)
+            event.object == source["id"] && event.counter == "lore" && event.from < chapter && event.to >= chapter
+          else
+            entered = event.to == "battlefield" && event.new_id == source["id"]
+            entered && engine.state.objects[event.new_id].counters.fetch("lore", 0) >= chapter
+          end
+        end
+
+        def to_s = "Chapter #{chapter}"
+      end
+    end
+
+    module Abilities
+      # A chapter ability "{rN} — [effect]" (CR 715.2): a triggered ability of a Saga. Write
+      # "{rN1}, {rN2} — [effect]" as one chapter ability per number (CR 715.2c).
+      class ChapterAbility < StackAbility
+        primitive :ability, :chapter,
+                  description: "A Saga's chapter ability: triggers when lore counters put on it bring their number " \
+                               "from below `chapter` to at least `chapter`. Its targets are chosen as it's put on the " \
+                               "stack. A Saga's final chapter number is its greatest `chapter`.",
+                  rules: %w[715.2 715.2b 715.2c 715.2d 122.6],
+                  params: { "chapter" => "integer >= 1 (the chapter symbol's number)", "targets" => "list of target filters",
+                            "effects" => "list of effects", "modes" => "optional modes, as for a spell" },
+                  example: { "chapter" => { "chapter" => 2, "effects" => [{ "gain_life" => { "amount" => 3 } }] } }
+
+        attr_reader :chapter, :trigger
+
+        def self.build(params, errors, path, **)
+          Mechanics.check_keys(params, %w[chapter] + BODY_KEYS, errors, path)
+          chapter = Mechanics.integer_param(params, :chapter, errors, path, min: 1)
+          new(**parse_body(params, errors, path), chapter: chapter)
+        end
+
+        def initialize(chapter:, **)
+          @chapter = chapter
+          @trigger = Triggers::ChapterTrigger.new(chapter)
+          super(**)
+        end
+
+        def kind = :triggered
+        def allowed_types = [:enchantment]
+        def condition = nil
+        def condition_met?(*, **) = true
+        def to_s = "Chapter #{chapter} — #{effects_text}"
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/supertypes/basic.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Supertypes
+      # Basic (CR 205.4c). Exempt from the four-copy deck limit.
+      class Basic < Primitive
+        primitive :supertype, :basic,
+                  description: "Basic cards are exempt from the four-copies deck construction limit.",
+                  rules: %w[205.4c 100.2a],
+                  example: { "supertypes" => ["basic"] }
+
+        def self.deck_limit_exempt? = true
+      end
+    end
+  end
+end

data/lib/enjine/mechanics/supertypes/legendary.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Mechanics
+    module Supertypes
+      # Legendary (CR 205.4d). Subject to the legend rule (CR 704.5j).
+      class Legendary < Primitive
+        primitive :supertype, :legendary,
+                  description: "If a player controls two or more legendary permanents with the same name, they choose " \
+                               "one and put the rest into their owners' graveyards (the legend rule).",
+                  rules: %w[205.4d 704.5j],
+                  example: { "supertypes" => ["legendary"] }
+
+        def self.deck_limit_exempt? = false
+      end
+    end
+  end
+end